Apothecary Shelf

showcase/apothecary-shelf/

A procedural apothecary shelf — housed shelves, gallery rails, a drawer bank and an arched crest, stocked with fifteen lathed bottles, flasks and glazed jars, each corked or lidded and labelled — carried through UVs, bake, LOD, convex collider, and Unity glTF, asserting recomputed budgets rather than an API contract.

Rendered headless by the showcase piece itself. Select it to enlarge.

witnesses Recomputed: 10456 tris, six materials with a face floor each, UVs in 0..1 with zero AABB overlap, outer AABB 0.876×0.274×1.076 m, zmin 0, hygiene 0 including zero coplanar cross-shell pairs, both sides grounded, seven cross members housed 8 mm into each side and 14 mm clear of its far face, fifteen vessels seated 1.0–1.8 mm into their shelves, every cork and lid biting 5 mm, every label 0.3 mm into its body and 0.8 mm proud, no vessel touching another or the carcass, and at least 24 mm of headroom between every vessel and the member above it. --tall-flask exits 20 at −5.5 mm while every seat and the envelope still pass; --short-shelves exits 17 on the dado bite.

category Village

tags mesh export showcase

blender --background --python showcase/apothecary-shelf/apothecary_shelf.py --

An apothecary shelf: a stained carcass with three shelves housed in its sides, a gallery rail along each shelf, lapped back boards, a bank of three drawers with brass knobs and an arched crest, stocked with fifteen vessels in five forms (bottle, flask, jar, albarello, vial). Every vessel is corked or lidded and carries a paper label. A showcase piece, not an example — it witnesses no API contract. It asserts that generated geometry meets declared asset budgets, recomputed from the finished mesh.

What it composes#

Shipped contentUsed for
skills/mesh-editing-and-bmeshchamfered boards, arched crest, lathed vessels, closures and knobs, labels on the bodies' rings, all in one bmesh
skills/custom-propertiesface attributes (PlankTone, GrainDir, Tint) read by the shaders
skills/procedural-materials-and-shadersgrained stain, tinted glass, glaze, cork, inked paper, aged brass
skills/bake-high-to-lowCycles tangent-space normal bake, high onto low
skills/engine-export-presetsUnity glTF (export_yup=True)
skills/depsgraph-and-evaluated-dataevaluated triangle counts for the LOD ratios
snippets/decimate_to_budget.pyLOD1 / LOD2 COLLAPSE chain
snippets/convex_hull_collider.pyone hull over the carcass and knobs
snippets/lod_chain.pyLOD naming and ratio pattern
examples/mesh-hygiene-audithygiene combinatorics (copied, not imported)

The budget that matters#

A stocked shelf fails invisibly when a vessel does not fit between its shelf and the one above. A flask a few centimetres too tall runs its neck up into the next shelf, and nothing else notices:

The piece reads each vessel's top (body or closure, whichever is higher) and the underside of the lowest horizontal member above it off the finished mesh, and asserts a headroom floor of 20 mm. The tightest vessel clears by 24.05 mm.

--tall-flask is the falsifier built for exactly this. It stretches the flask on the middle shelf by 1.20. It then runs 5.5 mm into the shelf above and exits 20, while every seat, every joint and the envelope still pass.

Budgets#

Declared in the script as named constants, recomputed from the generated mesh. Measured values are from Blender 5.2.1; every one is byte-identical on 4.5.11 and 5.1.2 (only the glTF file size differs, by up to 8 bytes, which is exporter metadata and not a budget).

BudgetBandMeasured
Base triangles9800–1110010456
LOD1 ratio0.32–0.620.5000
LOD2 ratio0.10–0.350.2200
Material slotsexactly 6, distinct6
Wood / glass / glaze faces≥ 450 / 1800 / 1300525 / 2080 / 1520
Cork / paper / brass faces≥ 850 / 380 / 300960 / 420 / 336
UV boundsinside 0..1(0.0009, 0.0010)–(0.9991, 0.9990)
UV AABB overlap≤ 1e-50.000000
Outer AABB0.876 × 0.274 × 1.076 m ± 0.0200.8760 × 0.2740 × 1.0760
Collider triangles≤ 200138
Normal bake{'FINISHED'} with image data{'FINISHED'}, has_data=True
glTF exportfile written, non-empty~449 kB
Hygieneall zeroloose 0/0, non-manifold 0, zero-area 0, doubles 0, n-gons 0, coplanar cross-shell pairs 0
Grounded AABB\zmin\≤ 1e-40.00000
Named sides2 sides, each zmin ≤ 1e-42 at 0.00000
Dado7 cross members, each ≥ 5 mm into both sides and ≥ 6 mm clear of the far face8.00 mm in, 14.00 mm clear
Closure biteevery cork and lid 2–10 mm into its body5.00 mm
Knob bite3 knobs, each 2–10 mm into its drawer front4.00 mm
Vessel seat15 vessels, each 0.5–3.0 mm into its shelf1.00–1.80 mm
Drawer seat3 drawer fronts, each 1–4 mm into the base2.00 mm
Label seatinner face 0.1–0.8 mm inside the body, outer face ≥ 0.4 mm proud0.30 mm in, 0.80 mm proud
Headroomevery vessel ≥ 20 mm under the member above24.05 mm
Vessel overlaps0, vessel against vessel and against the carcass0
Form spreadwidest / narrowest body ≥ 2.0; tallest / shortest ≥ 1.53.146 / 2.202
Edge treatmentright-angle wood edges0

Real-world size: 0.88 m wide, 1.08 m to the top of the crest and 0.27 m deep. It is a wall shelf for a shop counter or a study, and each compartment is 260 mm clear.

Construction#

Sizes vary by a closed-form ±5 % per vessel. Each shelf shares its clear width out evenly. Vessels step front and back alternately inside the depth left between the rail and the back boards.

Findings the budgets forced#

Conventions walked#

Every convention in showcase/README.md, and whether it applies here.

ConventionAppliesHow
Deterministic, budgets declared, assertions recomputeyesno RNG; every value above is read off the mesh
Falsifier fails the budget it targetsyestable below, proven on all three binaries
Hygiene incl. cross-shell coplanaryesexit 15; seats, lap steps and cork flares chosen to keep it at 0
Named supportsyesthe two sides (--float-side)
Joint-fit budgetsyesdado bite and far-face clearance per cross member (--short-shelves)
A member is tenoned into its seatyessides into the top, crest into the top, back boards into base and top
A platform bears on somethingyesevery shelf housed in both sides and biting the back boards
Carried parts bite their bearersyesvessels in shelves (--float-jars), drawer fronts in the base (--lift-drawers)
A joint bites; touching is not joiningyesclosures (--pop-corks) and knobs (--pull-knobs) as banded bites
Bands on a curved host are built on the host's arcyeslabels on the body's own rings and angles (--float-labels)
Scattered parts do not interpenetrateyesexit 21 (--crowd-jars)
Scatter varies in sizeyesform spread, exit 22 (--uniform-vessels)
Edge treatment: no right anglesyesexit 23 (--sharp-rail), wood only; lathed feet are chamfered by construction
Aim an edge falsifier at one memberyesone rail left square: 12 edges, −32 triangles
Chamfer n-gon caps, then triangulateyescrest caps
Sort bmesh operator inputsyesbevel edges sorted by index
A plank wall is boardsyesfour lapped back boards
Identical boards read as CGyesper-board PlankTone and GrainDir
Shading is part of the modelyesvessels, closures and knobs smooth (blown, turned); every edge over 35° hard, so boards read flat with crisp chamfers
One substance, one slotyeswood, glass, glaze, cork, paper, brass; glass and glaze colour per vessel from Tint
Iron is not chromen/abrass knobs: metallic 0.9, roughness 0.42, darkened by noise
Bake texels per UV cellmeasured, not a budget512 px over a 32-cell grid, about 15 px per cell
The bake cage is narrower than the nearest neighbouryesCAGE_EXTRUSION 0.01 m
Level on the stage; stage 60 myesturned about Z only; 60 m floor and wall
Keep a falsifier's envelope stillyesevery falsifier leaves the AABB unchanged except --pull-knobs (+6 mm in Y, inside BBOX_TOL)
Mirror symmetry, plumb, rope, masonry, roofs, rings, scatter on terrain, vessels with liquidnothe piece has none of these

Falsifiers#

Each breaks one pipeline stage so a named budget fails. All fourteen were run on 4.5.11, 5.1.2 and 5.2.1 and exited the same declared code on all three.

FlagTarget budgetBreaksExit
--skip-decimateLOD1 ratiodrops the DECIMATE modifiers, LOD1 ratio goes to 1.00009
--stray-vertmesh hygieneadds one loose vertex inside the carcass15
--lift-zgrounded zminlifts the whole mesh 50 mm16
--float-sidenamed sideslifts the left side 5 mm; the right side still grounds the AABB16
--short-shelvesdado bitestops the three shelves 4 mm short of the sides; −4.0 mm17
--pop-corksclosure bitelifts every cork and lid 10 mm; −5.0 mm17
--pull-knobsknob bitepulls every knob 8 mm out of its front; −4.0 mm17
--float-jarsvessel seatlifts every vessel 6 mm off its shelf; −5.0 to −4.2 mm18
--lift-drawersdrawer seatlifts the drawer fronts 3 mm; −1.0 mm18
--float-labelslabel seatbuilds every label 1.1 mm off its body; −1.1 mm18
--tall-flaskheadroomstretches the middle-shelf flask 1.20 into the shelf above; −5.5 mm20
--crowd-jarsvessel overlapsdraws the bottom shelf's jars to 0.55 of their spacing; 3 overlaps21
--uniform-vesselsform spreadone radius and height for every vessel; 1.000 / 1.00022
--sharp-railedge treatmentleaves the top rail unchamfered; 12 right-angle edges23

Exit codes#

File-local and sequential. 9 is a valid check code. 1 is the FATAL wrapper — a crash, never a named check. 19 (plumb and real-world size) is reserved across pieces and unused here.

CodeMeaning
0Success
1Uncaught exception (FATAL wrapper)
2argparse / usage
3Mesh did not build, or has no UV layer
4Base triangle count outside band
5Material slots, or a material's face floor
6UVs outside 0..1
7UV AABB overlap above tolerance
8Outer AABB off declared size
9LOD1 or LOD2 ratio outside band (--skip-decimate)
10Framing gate (examples/gallery_framing.py, render path only)
11Collider triangles above ceiling
12Normal bake failed or produced no image data
13glTF export missing or empty
14--output produced no file
15Mesh hygiene (--stray-vert)
16Grounded zmin, or a side floating (--lift-z, --float-side)
17Dado, closure or knob bite (--short-shelves, --pop-corks, --pull-knobs)
18Vessel, drawer or label seat (--float-jars, --lift-drawers, --float-labels)
20Headroom under the member above (--tall-flask)
21Vessels overlap each other or the carcass (--crowd-jars)
22Form spread below floor (--uniform-vessels)
23Right-angle wood edges (--sharp-rail)
24Gallery asset-quality violation (render path; the floors' 11 is remapped here)

Run it#

# Budget check, no render. ~4.5 s on 5.1 and 5.2.
blender --background --python apothecary_shelf.py --

# Falsifier: the middle-shelf flask runs into the shelf above. Must exit 20.
blender --background --python apothecary_shelf.py -- --tall-flask

# Falsifier: the shelves stop short of their dados. Must exit 17.
blender --background --python apothecary_shelf.py -- --short-shelves

# Render the gallery still (EEVEE; --engine cycles on a GPU-less host).
blender --background --python apothecary_shelf.py -- --output apothecary_shelf.webp

Smoke runs the check-only path. It does not pass --output or any falsifier.

Cross-version measurements#

Value4.5.115.1.25.2.1
Base triangles104561045610456
LOD1 / LOD2 tris5228 / 2300samesame
Face counts (wood / glass / glaze / cork / paper / brass)525 / 2080 / 1520 / 960 / 420 / 336samesame
Outer AABB0.8760 × 0.2740 × 1.0760samesame
Collider tris138138138
Headroom / form spread24.05 mm / 3.146, 2.202samesame
glTF bytes448604448600448596

Source

showcase/apothecary-shelf/apothecary_shelf.py View the script on GitHub →
A stained wooden shelf with an arched crest, gallery rails and three brass-knobbed drawers, stocked with labelled glass bottles and flasks and cream and blue glazed jars.