Crate Stack

showcase/crate-stack/

A stack of three procedural shipping crates built by one generator called three times with a per-instance seed, carried through UVs, bake, LOD, 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: 6060 tris, two materials with 1344 iron and 2418 timber faces, UVs in 0..1 with zero AABB overlap, outer AABB 0.658×0.524×0.704 m, zmin 0, hygiene 0 including zero coplanar disjoint pairs, three ground runners at z=0, both crate-to-crate seats overlapping, each crate's own footprint 0.588×0.428 m measured in its own frame, yaw spread 0.026 rad and plank spread 2.05 mm across instances, LOD ratios in band, convex collider 204 tris, non-empty glTF. --float-stack exits 18 on the seat; --same-seed exits 20 on per-instance variation.

category Village

tags mesh export showcase

blender --background --python showcase/crate-stack/crate_stack.py --

A stack of three shipping crates. 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#

One build_crate generator, invoked three times with a per-instance seed, then the shipped pipeline:

Shipped contentUsed for
skills/mesh-editing-and-bmeshbox, bevel and UV construction in one bmesh
skills/procedural-materials-and-shadersattribute-driven timber (per-plank tone, grain along each board) and rusted iron
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.pyconvex collider
snippets/lod_chain.pyLOD naming and ratio pattern
examples/mesh-hygiene-audithygiene combinatorics (copied, not imported)

Reuse with variation#

The point of the piece. Each crate comes out of the same generator; what differs is the seed. That seed drives the yaw, the plank widths, and the board heights, so the three read as three of the same design rather than one model pasted three times.

True instancing — three objects sharing one mesh datablock — and per-instance geometry variation are mutually exclusive. This piece takes the variation, and the shipped asset is the flattened single mesh an engine would receive. The generator is reused; the geometry is not.

Two independent random streams keep that honest. The design stream (yaw, plank widths) is what --same-seed collapses. The placement stream (lateral offsets) stays per-instance either way, so a falsified stack has the same footprint as a good one and fails on the variation budget rather than on the bounding box.

Budgets#

Declared in the script as named constants, recomputed from the generated mesh. Measured values below are from Blender 5.2.1; see the table at the end for the 4.5.11 / 5.1.2 figures.

BudgetBandMeasured
Base triangles5200–70006060
LOD1 ratio0.32–0.620.5000
LOD2 ratio0.10–0.350.2198
Material slotsexactly 2, distinct2
Iron faces≥ 9001344
Timber faces≥ 18002418
UV boundsinside 0..1(0.0006, 0.0007)–(0.9994, 0.9993)
UV AABB overlap≤ 1e-50.000000
Outer AABB0.658 × 0.524 × 0.704 m ± 0.0200.6583 × 0.5235 × 0.7040
Crate body footprint0.588 × 0.428 m ± 0.015, in the crate's own frame0.5882 × 0.4282 (all three)
Collider triangles≤ 260204
Normal bake{'FINISHED'} with image data{'FINISHED'}, has_data=True
glTF exportfile written, non-empty~490 kB
Hygieneall zeroloose 0/0, non-manifold 0, zero-area 0, doubles 0, n-gons 0, coplanar disjoint pairs 0
Grounded AABB\zmin\≤ 1e-40.00000
Ground runners3 named supports, each zmin ≤ 1e-33 at 0.00000
Crate-to-crate seatboth seats, surface gap ≤ 0.0015 m0.00000 (overlapping)
Yaw bandeach \yaw\in 0.040–0.192 rad0.0681, 0.0943, 0.1093
Per-instance variationyaw spread ≥ 0.020 rad, plank spread ≥ 0.0008 m0.0262 rad, 0.00205 m
Nail seat48 nails; bite 0.3–1.0 mm into the strap, head ≥ 1.0 mm proud48; bite 0.60 mm, proud 1.80 mm
Edge treatmentmanifold edges within 5° of a right angle: 0timber 0, iron 0

Real-world size: each crate is 0.58 × 0.42 m at the timber and 0.588 × 0.428 m over the corner iron and its nail heads, 0.244 m tall including runners and lid. Three stacked come to 0.70 m — knee height, wider than tall.

Why the footprint is measured in the crate's own frame#

The stack AABB is the union of three yawed boxes, so a crate could drift to any size underneath it and the outer budget would not notice. Each crate's footprint is therefore measured after un-rotating by the yaw that crate was measured to have, not the yaw it was built with. All three land on 0.5882 × 0.4282 m exactly, which is what makes the un-rotation trustworthy.

Why parts are classified by principal axes#

Every part is an axis-aligned box in its crate's frame and then rotated about Z. A world-AABB shape filter measures the rotated bounding box, not the part: a 0.554 m board yawed 0.09 rad reports 0.061 m of depth instead of its 0.013 m thickness, and every filter keyed to thickness silently matches nothing. xy_principal recovers each box's own axes, and hands back the yaw as a by-product — which is where the variation budget's yaw numbers come from.

Why stack levels come from the runners#

Binning parts against the declared stack pitch put a lid — which sits 8 mm below the next crate's base — on the wrong level the moment a falsifier shifted a crate, and the seat budget then compared a crate against itself. The bands are clustered from the runner heights the mesh actually has, so they follow the geometry including when a falsifier moves it.

Why the corner iron is one shell#

Each strap used to be two overlapping boxes, one per leg of the L. Both boxes had a vertical edge on the strap's outer corner, and once the iron was chamfered each box laid a chamfer strip on that same line: a coplanar cross-shell pair at all twelve corners, which the z-fight budget caught. The strap is now a single L-section extrusion — each cap two convex quads meeting on the inner-corner diagonal, so no n-gon — with one outer corner. The iron bevel passes material=METAL_IDX; left to its default, bevel gave the chamfer faces slot 0 and the plates rendered and classified as timber.

Why nails are told from plates by the strap's size#

Nail and plate shells are both iron; the nail audit separates them by world-AABB extent. The threshold is IRON_WRAP * 0.5, derived from the strap. A fixed 10 mm threshold dropped 8 of 48 nails as soon as the heads grew to 10 mm, because a yawed head's world AABB is wider than the head.

Timber surface#

paint_planks writes two face attributes: PlankTone, a seeded tone per shell, and GrainDir, the shell's own long axis recovered from its vertices. The wood shader samples noise in object space with the component along GrainDir compressed, so the grain streaks run along each board whatever the crate's yaw, and scales the colour by the plank's tone. Neither attribute is a budget: a tone cannot be seen by an assertion, which is why the inspection sheet looked at it.

Determinism#

Fixed seed 41; no unseeded randomness. Identical geometry across runs on one binary and across 4.5.11, 5.1.2 and 5.2.1 — every measured value above is byte-identical on the three. LOD2 used to differ — DECIMATE COLLAPSE produced 878 triangles on 5.2 and 934 on 4.5 and 5.1 on the earlier mesh — and on the current mesh lands on 1332 on all three. The LOD gate stays a ratio band (0.10–0.35) rather than an exact count, because that agreement is a property of this mesh, not of the modifier.

Falsifiers#

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

FlagBreaksExit
--skip-decimatedrops the DECIMATE modifiers, LOD1 ratio goes to 1.00009
--stray-vertadds one loose vertex inside the silhouette, so hygiene catches it rather than the bounding box15
--lift-zlifts the whole mesh 50 mm off the floor16
--short-skidsfloats one of the three ground runners 12 mm; the other two still ground the AABB, so only the named-support budget sees it16
--float-stacklifts the top crate 9 mm clear of the lid below, opening a 34 mm seat gap18
--same-seedgives all three crates the same design seed; yaw spread and plank spread both go to 020
--float-nailslifts every nail head 1.5 mm along its plate normal; bite goes to −0.90 mm, nail seat budget18
--sharp-ironskips the iron chamfer pass; 216 right-angle iron edges, edge-treatment budget21

Exit codes#

File-local and sequential. 9 is a valid check code; there is no rule against it. 1 is the FATAL wrapper — a crash, never a named check.

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 named ground runner floating (--lift-z, --short-skids)
18Crate-to-crate seat gap (--float-stack), or a nail head off its strap seat band (--float-nails)
19Crate body footprint off declared size
20Per-instance variation collapsed (--same-seed)
21A manifold edge within 5° of a right angle: a chamfer pass skipped (--sharp-iron)
22Gallery asset-quality violation (render path; the floors' 11 is remapped here)

17 is unused here: this piece has no diagonal member. 15–19 are reserved across showcase pieces for the hygiene family, so the numbering skips rather than reuses.

Run it#

# Budget check, no render. ~1.4-1.7 s on 4.5 / 5.1 / 5.2.
blender --background --python crate_stack.py --

# Falsifier: the three crates become copies. Must exit 20.
blender --background --python crate_stack.py -- --same-seed

# Falsifier: the top crate floats off the lid below. Must exit 18.
blender --background --python crate_stack.py -- --float-stack

# Render the gallery still (EEVEE; --engine cycles on a GPU-less host).
blender --background --python crate_stack.py -- --output stack.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 triangles606060606060
LOD1 tris / ratio3030 / 0.50003030 / 0.50003030 / 0.5000
LOD2 tris / ratio1332 / 0.21981332 / 0.21981332 / 0.2198
Outer AABB0.6583 × 0.5235 × 0.7040samesame
Collider tris204204204
Yaws (rad)0.0943, −0.1093, 0.0681samesame
Seat gap0.000000.000000.00000
Nails / bite / proud48 / 0.60 mm / 1.80 mmsamesame
Right-angle edges000
Check wall-clock~1.59 s~1.41 s~1.65 s

Source

showcase/crate-stack/crate_stack.py View the script on GitHub →
Three grained wooden shipping crates stacked, each turned slightly differently, with nailed iron corner straps.