Skip to content

Commit 68d79c7

Browse files
TMHSDigitalclaude
andcommitted
feat: add crate-stack showcase piece
Three shipping crates stacked, built by one generator called three times with a per-instance seed. The subject is reuse with variation: the seed drives yaw and plank widths so the crates read as three of the same design rather than one model pasted three times, and the README says plainly that true instancing and per-instance geometry variation are mutually exclusive. Budgets recomputed from the finished mesh, measured before they were written: 4380 tris, 2 materials with 216 iron and 2436 timber faces, UVs in 0..1 with zero overlap, outer AABB 0.658x0.524x0.704 m, each crate's own footprint 0.585x0.425 m in its own frame, three ground runners at z=0, both crate-to-crate seats overlapping, LOD ratios in band, 202-tri collider, non-empty glTF, and hygiene zero across loose/non-manifold/zero-area/ doubles/n-gons/coplanar-disjoint. Six falsifiers, each breaking one named budget, all proven on 4.5.11, 5.1.2 and 5.2.1 with identical exit codes: --skip-decimate 9, --stray-vert 15, --lift-z 16, --short-skids 16, --float-stack 18, --same-seed 20. Three findings the budgets forced, all documented in the README: - Shape filters had to move to principal axes. Every part is axis-aligned in its crate's frame then rotated about Z, so a world-AABB filter measures the rotated box: a 0.554 m board yawed 0.09 rad reports 0.061 m of depth instead of 0.013 m, and every thickness-keyed filter matched nothing. - Stack levels had to be clustered from the runners the mesh actually has. Binning against the declared pitch put a lid on the wrong level as soon as a falsifier shifted a crate, and the seat budget then compared a crate against itself. - find_doubles caught two real joints, not false positives: the corner straps sat flush with the post corner, and the lid rested exactly on the rail top. Both now bite into their host. Falsifiers were also retuned so each fails on its own budget rather than on an earlier check: the stray vertex sits inside the silhouette, --short-skids floats one of three runners so the AABB still grounds, and --same-seed collapses only the design stream while placement stays per-instance so the footprint is unchanged. LOD2 is the one value that differs across versions (878 tris on 5.2, 934 on 4.5 and 5.1) — DECIMATE COLLAPSE, which is why the gate is a ratio band. Adds ~1.0 s to smoke on 4.5/5.1 and ~1.2 s on 5.2. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
1 parent 0718120 commit 68d79c7

11 files changed

Lines changed: 3380 additions & 8 deletions

File tree

‎.cursor-plugin/plugin.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@
163163
"showcase/tavern-stool",
164164
"showcase/iron-cauldron",
165165
"showcase/wooden-ladder",
166-
"showcase/hay-bale"
166+
"showcase/hay-bale",
167+
"showcase/crate-stack"
167168
]
168169
}

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ rules/<rule-name>.mdc - Anti-pattern rules, 9 total
2222
templates/<template-name>/ - Starter projects, 3 total
2323
snippets/<snippet-name>.py - Standalone code patterns, 27 total
2424
examples/<name>/ - Runnable smoke-gated examples, 59 total (+ gallery.json)
25-
showcase/<name>/ - Budget-conformance props, 26 pieces (sibling of examples/; see showcase/README.md)
25+
showcase/<name>/ - Budget-conformance props, 27 pieces (sibling of examples/; see showcase/README.md)
2626
scripts/build_gallery.py - Regenerates docs/gallery/ from examples/gallery.json + showcase/gallery.json
2727
scripts/site/ - Vendored landing-page build (Jinja2)
2828
docs/gallery/ - Committed generated gallery pages + hero renders

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
</p>
1919

2020
<p align="center">
21-
<strong>16 skills</strong> &nbsp;&bull;&nbsp; <strong>9 rules</strong> &nbsp;&bull;&nbsp; <strong>3 templates</strong> &nbsp;&bull;&nbsp; <strong>27 snippets</strong> &nbsp;&bull;&nbsp; <strong>59 examples</strong> &nbsp;&bull;&nbsp; <strong>26 showcase pieces</strong>
21+
<strong>16 skills</strong> &nbsp;&bull;&nbsp; <strong>9 rules</strong> &nbsp;&bull;&nbsp; <strong>3 templates</strong> &nbsp;&bull;&nbsp; <strong>27 snippets</strong> &nbsp;&bull;&nbsp; <strong>59 examples</strong> &nbsp;&bull;&nbsp; <strong>27 showcase pieces</strong>
2222
</p>
2323

2424
<p align="center">
@@ -37,7 +37,7 @@
3737

3838
## Overview
3939

40-
This repository ships **16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, and 26 showcase pieces** for Blender Python development targeting Blender 5.2 LTS (current stable) with Blender 4.5 LTS fallback support. Blender 5.1 is prior stable.
40+
This repository ships **16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, and 27 showcase pieces** for Blender Python development targeting Blender 5.2 LTS (current stable) with Blender 4.5 LTS fallback support. Blender 5.1 is prior stable.
4141

4242
The content is consumed by AI coding agents reading these files directly from a checkout — **there is no MCP server in this repository, and none is required**. Cursor applies `rules/*.mdc` automatically wherever their scope globs match and takes skills by name in chat; Claude Code reads `skills/` and `rules/` from the project workspace, or from this repo kept as a referenced checkout. Any agent that can read files in a workspace can use it the same way. There is no build step for the content — edit the Markdown and Python files directly.
4343

@@ -106,7 +106,7 @@ per-script exit-code model, are in
106106
Budget-conformance props. Not examples. Conventions: [`showcase/README.md`](showcase/README.md).
107107

108108
<details>
109-
<summary><strong>26 showcase pieces</strong> — click to expand the preview grid</summary>
109+
<summary><strong>27 showcase pieces</strong> — click to expand the preview grid</summary>
110110

111111
<p align="center">
112112
<a href="showcase/shipping-crate/"><img src="showcase/shipping-crate/preview.webp" width="24%" alt="Shipping crate: a wooden slat crate with iron corner brackets on a dark studio floor, warm wedge on the back wall" /></a>
@@ -135,6 +135,7 @@ Budget-conformance props. Not examples. Conventions: [`showcase/README.md`](show
135135
<a href="showcase/iron-cauldron/"><img src="showcase/iron-cauldron/preview.webp" width="24%" alt="Iron cauldron: a bulged iron pot hanging from a timber tripod on a dark studio floor" /></a>
136136
<a href="showcase/wooden-ladder/"><img src="showcase/wooden-ladder/preview.webp" width="24%" alt="Wooden ladder: a raked timber ladder with six rungs and iron shoes on a dark studio floor" /></a>
137137
<a href="showcase/hay-bale/"><img src="showcase/hay-bale/preview.webp" width="24%" alt="Hay bale: a bound straw bale with two sisal twine belts on a dark studio floor" /></a>
138+
<a href="showcase/crate-stack/"><img src="showcase/crate-stack/preview.webp" width="24%" alt="Crate stack: three slatted shipping crates stacked and yawed, each with iron corner straps and runners, on a dark studio floor" /></a>
138139
</p>
139140

140141
[`shipping-crate`](showcase/shipping-crate/) — procedural crate through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets. Falsifier `--skip-decimate` exits 9.
24.9 KB
Loading

‎docs/gallery/crate-stack/index.html‎

Lines changed: 1756 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/gallery/index.html‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,7 @@ <h1>Examples and Showcase</h1>
272272
autocomplete="off" spellcheck="false" aria-label="Search examples and showcase pieces" />
273273
<button class="q-clear" id="qClear" type="button" aria-label="Clear search" hidden>&times;</button>
274274
</div>
275-
<span class="count" id="count" role="status" aria-live="polite">51 examples, 26 showcase pieces</span>
275+
<span class="count" id="count" role="status" aria-live="polite">51 examples, 27 showcase pieces</span>
276276
<div class="density" role="group" aria-label="Card density">
277277
<button class="density-btn" data-density="compact" type="button" aria-pressed="false">Compact</button>
278278
<button class="density-btn" data-density="detailed" type="button" aria-pressed="false">Detailed</button>
@@ -1171,6 +1171,17 @@ <h2><a href="hay-bale/">hay-bale</a></h2>
11711171
<a class="card-link" href="hay-bale/">View showcase piece <span aria-hidden="true">&rarr;</span></a>
11721172
</div>
11731173
</article>
1174+
<article class="card" data-tags="mesh export showcase">
1175+
<a class="card-media" href="crate-stack/" aria-label="crate-stack showcase piece detail page">
1176+
<img src="assets/crate-stack-hero.webp" alt="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…" loading="lazy" decoding="async" />
1177+
</a>
1178+
<div class="card-body">
1179+
<h2><a href="crate-stack/">crate-stack</a></h2>
1180+
<p class="teaches">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.</p>
1181+
<p class="witnesses"><span class="tag">witnesses</span> Recomputed: 4380 tris, two materials with 216 iron and 2436 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&#x27;s own footprint 0.585×0.425 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 202 tris, non-empty glTF. --float-stack exits 18 on the seat; --same-seed exits 20 on per-instance variation.</p>
1182+
<a class="card-link" href="crate-stack/">View showcase piece <span aria-hidden="true">&rarr;</span></a>
1183+
</div>
1184+
</article>
11741185
</div>
11751186
<p class="noresults" id="noResults" hidden>Nothing matches the current filters.
11761187
<button class="chip" id="resetFilters" type="button">Clear search and tags</button></p>
@@ -1200,7 +1211,7 @@ <h2><a href="hay-bale/">hay-bale</a></h2>
12001211
var tagsToggle = document.getElementById('tagsToggle');
12011212
var toTop = document.getElementById('toTop');
12021213
var total = cards.length;
1203-
var COUNT_LABEL = '51 examples, 26 showcase pieces';
1214+
var COUNT_LABEL = '51 examples, 27 showcase pieces';
12041215
var LS_KEY = 'bdt-gallery-density';
12051216
var reduced = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
12061217

‎showcase/crate-stack/README.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# crate-stack
2+
3+
![Three shipping crates stacked, each yawed and offset differently](preview.webp)
4+
5+
A stack of three shipping crates. **A showcase piece, not an example** — it
6+
witnesses no API contract. It asserts that generated geometry meets declared
7+
asset budgets, recomputed from the finished mesh.
8+
9+
## What it composes
10+
11+
One `build_crate` generator, invoked three times with a per-instance seed,
12+
then the shipped pipeline:
13+
14+
| Shipped content | Used for |
15+
| --- | --- |
16+
| `skills/mesh-editing-and-bmesh` | box, bevel and UV construction in one `bmesh` |
17+
| `skills/procedural-materials-and-shaders` | two Principled materials with noise-driven wear |
18+
| `skills/bake-high-to-low` | Cycles tangent-space normal bake, high onto low |
19+
| `skills/engine-export-presets` | Unity glTF (`export_yup=True`) |
20+
| `skills/depsgraph-and-evaluated-data` | evaluated triangle counts for the LOD ratios |
21+
| `snippets/decimate_to_budget.py` | LOD1 / LOD2 COLLAPSE chain |
22+
| `snippets/convex_hull_collider.py` | convex collider |
23+
| `snippets/lod_chain.py` | LOD naming and ratio pattern |
24+
| `examples/mesh-hygiene-audit` | hygiene combinatorics (copied, not imported) |
25+
26+
## Reuse with variation
27+
28+
The point of the piece. Each crate comes out of the same generator; what
29+
differs is the seed. That seed drives the yaw, the plank widths, and the
30+
board heights, so the three read as three of the same design rather than one
31+
model pasted three times.
32+
33+
True instancing — three objects sharing one mesh datablock — and
34+
per-instance geometry variation are mutually exclusive. This piece takes the
35+
variation, and the shipped asset is the flattened single mesh an engine would
36+
receive. The generator is reused; the geometry is not.
37+
38+
Two independent random streams keep that honest. The **design** stream
39+
(yaw, plank widths) is what `--same-seed` collapses. The **placement** stream
40+
(lateral offsets) stays per-instance either way, so a falsified stack has the
41+
same footprint as a good one and fails on the variation budget rather than on
42+
the bounding box.
43+
44+
## Budgets
45+
46+
Declared in the script as named constants, recomputed from the generated
47+
mesh. Measured values below are from Blender 5.2.1; see the table at the end
48+
for the 4.5.11 / 5.1.2 figures.
49+
50+
| Budget | Band | Measured |
51+
| --- | --- | --- |
52+
| Base triangles | 3200–7200 | 4380 |
53+
| LOD1 ratio | 0.32–0.62 | 0.5000 |
54+
| LOD2 ratio | 0.10–0.35 | 0.2005 (5.2) / 0.2199 (4.5, 5.1) |
55+
| Material slots | exactly 2, distinct | 2 |
56+
| Iron faces | ≥ 120 | 216 |
57+
| Timber faces | ≥ 600 | 2436 |
58+
| UV bounds | inside 0..1 | (0.0008, 0.0008)–(0.9992, 0.9992) |
59+
| UV AABB overlap | ≤ 1e-5 | 0.000000 |
60+
| Outer AABB | 0.658 × 0.524 × 0.704 m ± 0.020 | 0.6582 × 0.5235 × 0.7040 |
61+
| Crate body footprint | 0.585 × 0.425 m ± 0.015, in the crate's own frame | 0.5846 × 0.4246 (all three) |
62+
| Collider triangles | ≤ 260 | 202 |
63+
| Normal bake | `{'FINISHED'}` with image data | `{'FINISHED'}`, `has_data=True` |
64+
| glTF export | file written, non-empty | ~340 kB |
65+
| Hygiene | all zero | loose 0/0, non-manifold 0, zero-area 0, doubles 0, n-gons 0, coplanar disjoint pairs 0 |
66+
| Grounded AABB | \|zmin\| ≤ 1e-4 | 0.00000 |
67+
| Ground runners | 3 named supports, each zmin ≤ 1e-3 | 3 at 0.00000 |
68+
| Crate-to-crate seat | both seats, surface gap ≤ 0.0015 m | 0.00000 (overlapping) |
69+
| Yaw band | each \|yaw\| in 0.040–0.192 rad | 0.0681, 0.0943, 0.1093 |
70+
| Per-instance variation | yaw spread ≥ 0.020 rad, plank spread ≥ 0.0008 m | 0.0262 rad, 0.00205 m |
71+
72+
Real-world size: each crate is 0.58 × 0.42 m at the timber and 0.585 × 0.425 m
73+
over the corner iron, 0.244 m tall including runners and lid. Three stacked
74+
come to 0.70 m — knee height, wider than tall.
75+
76+
### Why the footprint is measured in the crate's own frame
77+
78+
The stack AABB is the union of three yawed boxes, so a crate could drift to
79+
any size underneath it and the outer budget would not notice. Each crate's
80+
footprint is therefore measured after un-rotating by the yaw that crate was
81+
*measured* to have, not the yaw it was built with. All three land on
82+
0.5846 × 0.4246 m exactly, which is what makes the un-rotation trustworthy.
83+
84+
### Why parts are classified by principal axes
85+
86+
Every part is an axis-aligned box in its crate's frame and then rotated about
87+
Z. A world-AABB shape filter measures the rotated bounding box, not the part:
88+
a 0.554 m board yawed 0.09 rad reports 0.061 m of depth instead of its
89+
0.013 m thickness, and every filter keyed to thickness silently matches
90+
nothing. `xy_principal` recovers each box's own axes, and hands back the yaw
91+
as a by-product — which is where the variation budget's yaw numbers come from.
92+
93+
### Why stack levels come from the runners
94+
95+
Binning parts against the declared stack pitch put a lid — which sits 8 mm
96+
below the next crate's base — on the wrong level the moment a falsifier
97+
shifted a crate, and the seat budget then compared a crate against itself.
98+
The bands are clustered from the runner heights the mesh actually has, so
99+
they follow the geometry including when a falsifier moves it.
100+
101+
## Determinism
102+
103+
Fixed seed 41; no unseeded randomness. Identical geometry across runs on one
104+
binary and across 4.5.11, 5.1.2 and 5.2.1 — every measured value above is
105+
byte-identical on the three **except** LOD2, where `DECIMATE COLLAPSE`
106+
produces 878 triangles on 5.2 and 934 on 4.5 and 5.1. That is why the LOD
107+
gate is a ratio band (0.10–0.35, measured 0.2005 and 0.2199) and not an exact
108+
count.
109+
110+
## Falsifiers
111+
112+
Each breaks one pipeline stage so a **named** budget fails. All six were run
113+
on 4.5.11, 5.1.2 and 5.2.1 and produced the same exit code on all three.
114+
115+
| Flag | Breaks | Exit |
116+
| --- | --- | --- |
117+
| `--skip-decimate` | drops the DECIMATE modifiers, LOD1 ratio goes to 1.0000 | 9 |
118+
| `--stray-vert` | adds one loose vertex *inside* the silhouette, so hygiene catches it rather than the bounding box | 15 |
119+
| `--lift-z` | lifts the whole mesh 50 mm off the floor | 16 |
120+
| `--short-skids` | floats **one** of the three ground runners 12 mm; the other two still ground the AABB, so only the named-support budget sees it | 16 |
121+
| `--float-stack` | lifts the top crate 9 mm clear of the lid below, opening a 34 mm seat gap | 18 |
122+
| `--same-seed` | gives all three crates the same design seed; yaw spread and plank spread both go to 0 | 20 |
123+
124+
## Exit codes
125+
126+
File-local and sequential. `9` is a valid check code; there is no rule
127+
against it. `1` is the FATAL wrapper — a crash, never a named check.
128+
129+
| Code | Meaning |
130+
| --- | --- |
131+
| 0 | Success |
132+
| 1 | Uncaught exception (FATAL wrapper) |
133+
| 2 | argparse / usage |
134+
| 3 | Mesh did not build, or has no UV layer |
135+
| 4 | Base triangle count outside band |
136+
| 5 | Material slots, or a material's face floor |
137+
| 6 | UVs outside 0..1 |
138+
| 7 | UV AABB overlap above tolerance |
139+
| 8 | Outer AABB off declared size |
140+
| 9 | LOD1 or LOD2 ratio outside band (`--skip-decimate`) |
141+
| 10 | Framing gate (`examples/gallery_framing.py`, render path only) |
142+
| 11 | Collider triangles above ceiling |
143+
| 12 | Normal bake failed or produced no image data |
144+
| 13 | glTF export missing or empty |
145+
| 14 | `--output` produced no file |
146+
| 15 | Mesh hygiene (`--stray-vert`) |
147+
| 16 | Grounded zmin, or a named ground runner floating (`--lift-z`, `--short-skids`) |
148+
| 18 | Crate-to-crate seat gap (`--float-stack`) |
149+
| 19 | Crate body footprint off declared size |
150+
| 20 | Per-instance variation collapsed (`--same-seed`) |
151+
152+
`17` is unused here: this piece has no diagonal member. `15`–`19` are
153+
reserved across showcase pieces for the hygiene family, so the numbering
154+
skips rather than reuses.
155+
156+
## Run it
157+
158+
```bash
159+
# Budget check, no render. ~1.0 s on 4.5/5.1, ~1.2 s on 5.2.
160+
blender --background --python crate_stack.py --
161+
162+
# Falsifier: the three crates become copies. Must exit 20.
163+
blender --background --python crate_stack.py -- --same-seed
164+
165+
# Falsifier: the top crate floats off the lid below. Must exit 18.
166+
blender --background --python crate_stack.py -- --float-stack
167+
168+
# Render the gallery still (EEVEE; --engine cycles on a GPU-less host).
169+
blender --background --python crate_stack.py -- --output stack.webp
170+
```
171+
172+
Smoke runs the check-only path. It does not pass `--output` or any falsifier.
173+
174+
## Cross-version measurements
175+
176+
| Value | 4.5.11 | 5.1.2 | 5.2.1 |
177+
| --- | --- | --- | --- |
178+
| Base triangles | 4380 | 4380 | 4380 |
179+
| LOD1 tris / ratio | 2190 / 0.5000 | 2190 / 0.5000 | 2190 / 0.5000 |
180+
| LOD2 tris / ratio | 934 / 0.2199 | 934 / 0.2199 | 878 / 0.2005 |
181+
| Outer AABB | 0.6582 × 0.5235 × 0.7040 | same | same |
182+
| Collider tris | 202 | 202 | 202 |
183+
| Yaws (rad) | 0.0943, −0.1093, 0.0681 | same | same |
184+
| Seat gap | 0.00000 | 0.00000 | 0.00000 |
185+
| Check wall-clock | ~0.99 s | ~1.01 s | ~1.20 s |

0 commit comments

Comments
 (0)