diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index aad3f755..c1992361 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -170,6 +170,7 @@ "showcase/grain-sacks", "showcase/brazier", "showcase/apothecary-shelf", - "showcase/wooden-yoke" + "showcase/wooden-yoke", + "showcase/butter-churn" ] } diff --git a/CLAUDE.md b/CLAUDE.md index eae428f2..bf3ae90e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,7 +22,7 @@ rules/.mdc - Anti-pattern rules, 9 total templates// - Starter projects, 3 total snippets/.py - Standalone code patterns, 27 total examples// - Runnable smoke-gated examples, 59 total (+ gallery.json) -showcase// - Budget-conformance props, 33 pieces (sibling of examples/; see showcase/README.md) +showcase// - Budget-conformance props, 34 pieces (sibling of examples/; see showcase/README.md) scripts/build_gallery.py - Regenerates docs/gallery/ from examples/gallery.json + showcase/gallery.json scripts/site/ - Vendored landing-page build (Jinja2) docs/gallery/ - Committed generated gallery pages + hero renders diff --git a/README.md b/README.md index 96789be0..d6c08cfa 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@

- 16 skills  •  9 rules  •  3 templates  •  27 snippets  •  59 examples  •  33 showcase pieces + 16 skills  •  9 rules  •  3 templates  •  27 snippets  •  59 examples  •  34 showcase pieces

@@ -37,7 +37,7 @@ ## Overview -This repository ships **16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, and 33 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. +This repository ships **16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, and 34 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. 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. @@ -106,7 +106,7 @@ per-script exit-code model, are in Budget-conformance props. Not examples. Conventions: [`showcase/README.md`](showcase/README.md).

-33 showcase pieces — click to expand the preview grid +34 showcase pieces — click to expand the preview grid

Shipping crate: a wooden slat crate with iron corner brackets on a dark studio floor, warm wedge on the back wall @@ -142,6 +142,7 @@ Budget-conformance props. Not examples. Conventions: [`showcase/README.md`](show Brazier: an iron fire bowl with a rolled rim on three S-curved forged legs, holding ash and a heap of glowing charcoal, on a dark studio floor Apothecary shelf: a stained wooden shelf unit with an arched crest, gallery rails and three drawers, stocked with labelled glass bottles, flasks and glazed jars, on a dark studio floor Wooden yoke: a carved oak ox yoke with upturned ends standing on two bent hickory oxbows pinned above the beam, with an iron ring hung under its centre, on a dark studio floor + Butter churn: a tall staved oak churn narrowing toward the top, bound by three iron hoops, with a two-board lid and a maple dasher handle rising through it, on a dark studio floor

[`shipping-crate`](showcase/shipping-crate/) — procedural crate through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets. Falsifier `--skip-decimate` exits 9. @@ -206,6 +207,8 @@ Budget-conformance props. Not examples. Conventions: [`showcase/README.md`](show [`wooden-yoke`](showcase/wooden-yoke/) — procedural double ox yoke on two bent hickory bows with a hung ring, whose neck openings are measured between the bow legs and up to the saddles, through the same pipeline. Falsifiers `--pinch-bows` exits 19, `--edge-on-ring` exits 17. +[`butter-churn`](showcase/butter-churn/) — procedural staved plunge churn whose dasher stroke is recomputed from the inner wall read off the staves and the plunger's reach, through the same pipeline. Falsifiers `--wide-dasher` exits 20, `--tight-hole` exits 18. +
## Examples diff --git a/ROADMAP.md b/ROADMAP.md index bf37329a..a84d8d5f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -138,9 +138,9 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo - ~~Brazier (iron bowl on legs, coals, ash) as a game-prop showcase piece~~ **SHIPPED** as `showcase/brazier/` — spun bowl with a rolled rim, three one-sweep forged legs, ash bed biting the wall, 36 cleaved coals packed without interpenetration; tip angle from a density-weighted mass centre and the support polygon, `--tuck-legs` exits 19 on it while the feet still ground - ~~Apothecary shelf (shelf unit, bottles and jars of varied form) as a game-prop showcase piece~~ **SHIPPED** as `showcase/apothecary-shelf/` — housed shelves, gallery rails, lapped back boards, a drawer bank and an arched crest, stocked with fifteen lathed vessels in five forms, each corked or lidded and labelled on its own rings; per-vessel headroom under the member above is read off the mesh, `--tall-flask` exits 20 on it while every seat and the envelope still pass - ~~Wooden yoke (oxbow, iron rings) as a game-prop showcase piece~~ **SHIPPED** as `showcase/wooden-yoke/` — lofted oak beam with neck saddles and upturned ends, two bent-hickory bows through it and pinned above it, a staple and a threaded hung ring; each neck opening measured between the bow legs and up to the saddle, `--pinch-bows` exits 19 on it while the bows still ground and the envelope is unchanged -- Ox cart tongue or plough beam that hitches to the yoke's ring as a game-prop showcase piece — a hitch is a ring-on-hook contact the yoke's hung ring only tests against a fixed bar -- Butter churn (staved tub, lid, dasher) as a game-prop showcase piece +- ~~Butter churn (staved tub, lid, dasher) as a game-prop showcase piece~~ **SHIPPED** as `showcase/butter-churn/` — sixteen tapered staves with canted ends, three hoops seated vertex-for-vertex on them, a three-board bottom in a croze, a two-board lid and a cross dasher; the plunge stroke is recomputed from the inner wall and the plunger's reach, `--wide-dasher` exits 20 on it while the plunger still clears the staves at rest - Bookshelf with leaning books (upright and toppled volumes of varied size, one leaning on its neighbour) as a game-prop showcase piece — the lean needs a contact budget the apothecary shelf's upright vessels never exercised: each leaning book rests on its neighbour's spine edge and on the shelf, not in either +- Ox cart tongue or plough beam that hitches to the yoke's ring as a game-prop showcase piece — a hitch is a ring-on-hook contact the yoke's hung ring only tests against a fixed bar - ~~Small modular kit showcase on recognizable geometry (`modular-kit-snap` contract)~~ **SHIPPED** as `showcase/fence-kit/` — tiling post-and-rail section (AABB X is the tile width; does not re-witness the snap contract); `--skip-decimate` exits 9 on the LOD1 ratio band - ~~Custom ID-property delete witness~~ **SHIPPED** as `examples/cross-version-property-delete/` — IDs built via `bpy.data.objects.new` (not `active_object`); `property_unset` is TypeError and leaves the key; `del` removes it on 4.5 LTS and 5.x diff --git a/docs/gallery/asset-sheets/butter-churn.webp b/docs/gallery/asset-sheets/butter-churn.webp new file mode 100644 index 00000000..d167e037 Binary files /dev/null and b/docs/gallery/asset-sheets/butter-churn.webp differ diff --git a/docs/gallery/assets/butter-churn-hero.webp b/docs/gallery/assets/butter-churn-hero.webp new file mode 100644 index 00000000..33b8dcb2 Binary files /dev/null and b/docs/gallery/assets/butter-churn-hero.webp differ diff --git a/docs/gallery/butter-churn/index.html b/docs/gallery/butter-churn/index.html new file mode 100644 index 00000000..8896ee6f --- /dev/null +++ b/docs/gallery/butter-churn/index.html @@ -0,0 +1,1644 @@ + + + + + + butter-churn — Showcase — Blender Developer Tools + + + + + + + + + + + + + + + + + + + + + + + +
+ Examples and Showcase +
+ GitHub +
+
+
+

butter-churn

+

A procedural plunge butter churn — sixteen tapered oak staves, three iron hoops, a three-board bottom, a two-board lid and a maple cross dasher — carried through UVs, bake, LOD, compound collider, and Unity glTF, asserting recomputed budgets rather than an API contract.

+
+
+ +

Rendered headless by the showcase piece itself — click to zoom.

+
witnesses Recomputed: 5684 tris, three materials with 2240 oak, 160 maple and 576 iron faces, UVs in 0..1 with zero AABB overlap, outer AABB 0.340×0.340×1.050 m, zmin 0, hygiene 0 including zero coplanar cross-shell pairs, all sixteen staves on the floor, three bottom boards with 1.2 mm seams, the handle 14 mm into the slats, three hoops 2.5 mm into the staves and 4.9 mm proud, the lid 1.4–2.0 mm onto the stave tops, 5 mm of clearance round the handle, and a 514 mm plunge stroke for a 101 mm reach. --wide-dasher exits 20 at 140 mm while the plunger still clears the staves at rest; --tight-hole exits 18.
+
+ 
blender --background --python showcase/butter-churn/butter_churn.py --
+ +
+
+

A plunge butter churn: a tall body of sixteen oak staves that narrows toward the top, three forged iron hoops, a bottom of three boards set in a croze, a lid of two boards with a hole for the handle, and a maple cross dasher whose handle runs up through the lid. 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-bmeshlofted staves, banded hoops, clipped board polygons, lathed handle, all in one bmesh
skills/custom-propertiesface attributes (PlankTone, GrainDir) read by the wood shaders
skills/procedural-materials-and-shadersoak with grain along each stave, pale maple, rusted rough 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.pyone hull for the body and lid, one for the handle above it
snippets/lod_chain.pyLOD naming and ratio pattern
examples/mesh-hygiene-audithygiene combinatorics (copied, not imported)
+

The budget that matters

+

A churn is for plunging. The body narrows toward the top, so a plunger that clears the staves at the bottom can jam partway up the stroke, and nothing else notices:

+
  • the plunger still sits inside the body without touching it;
  • the handle still clears the lid's hole;
  • the bounding box does not move.
+

The piece reads the inner wall off the staves ring by ring and the plunger's reach off the dasher's slats, about the handle's axis. It finds the height at which the wall comes within WALL_CLEAR (10 mm) of the plunger, stops at the lid if that comes first, and asserts the travel from the plunger's rest height as a stroke floor of 400 mm. Measured: 513.8 mm, for a 100.6 mm reach.

+

--wide-dasher is the falsifier built for exactly this. It widens the slats to 125 mm. The plunger still clears the staves at rest, but it can travel only 140.4 mm before it would meet the wall, and the run exits

+
  1. Every other budget passes and the AABB is unchanged.
+

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 8 bytes, which is exporter metadata and not a budget).

+
BudgetBandMeasured
Base triangles5000–65005684
LOD1 ratio0.32–0.620.5000
LOD2 ratio0.10–0.350.2199
Material slotsexactly 3, distinct3
Oak / maple / iron faces≥ 2000 / 140 / 5002240 / 160 / 576
UV boundsinside 0..1(0.0013, 0.0013)–(0.9987, 0.9987)
UV AABB overlap≤ 1e-50.000000
Outer AABB0.340 × 0.340 × 1.050 m ± 0.0200.3401 × 0.3401 × 1.0500
Collider triangles≤ 200178 (two hulls)
Normal bake{'FINISHED'} with image data{'FINISHED'}, has_data=True
glTF exportfile written, non-empty~240 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 staves16 staves, each zmin ≤ 1e-416 at 0.00000
Bottom boards3 boards, seams 0.6–2.5 mm3, 1.20 mm
Handle bitehandle's foot 8–20 mm into the slats14.0 mm
Hoop seat3 hoops, inner face 1.0–4.5 mm into the staves, outer face ≥ 3 mm proud2.50 mm in, 4.90 mm proud
Lid seat2 boards, each 1–4 mm onto the stave tops1.40–2.00 mm
Handle clearancelid hole over handle radius, 2–10 mm5.00 mm
Plunge stroke≥ 400 mm513.8 mm
+

Real-world size: 0.34 m across the foot, 0.75 m to the rim and 1.05 m to the top of the handle. It is a farmhouse plunge churn.

+

Construction

+
  • Staves. Sixteen staves are lofted on a straight taper (R_BOT 170 mm to R_TOP 120 mm), with a gap of STAVE_GAP between neighbours.
  • Each stave's section has four vertices across its width at fractions 0, ¼, ¾ and 1, outer face over inner face, and quads close both ends.
  • Ring heights are a uniform run plus both edges of every hoop and of the croze, so a hoop's edge and the bottom's faces meet stave vertices.
  • Each stave's foot and top are cut sloping inward (END_CANT, doubled on alternate staves), so the churn stands on its outer edges.
  • Every real edge is chamfered at 1.5 mm; the few-degree edges across a stave's width are left alone.
  • Hoops. Each hoop is a banded iron section: flat inner face, chamfered outer edges. It is sampled at every stave's two interior vertex angles, so every hoop vertex lies radially over a stave vertex at the same height. The inner face is HOOP_BITE inside the stave's outer face, read from the same taper; the outer face is HOOP_PROUD outside it.
  • Bottom. A 48-gon disk sized to the inner wall plus CROZE, cut across X into three boards with a named seam (Sutherland–Hodgman clip). Caps are chamfered as n-gons and then triangulated.
  • Lid. Two half-annulus boards with the seam across the hole. The hole is HOLE_CLEAR wider than the handle. The lid rests LID_SEAT on the stave tops and overhangs by LID_OVER.
  • Dasher. Two crossed maple slats, the second a step higher. The handle's foot is driven HANDLE_BITE into them. The handle is a 12-segment lathe with rings at both faces of the lid, so its clearance is measured where it passes, and it ends in a swelled grip.
+

Findings the budgets forced

+
  • Neighbouring ends in one plane. The first build had 240 coplanar cross-shell pairs:
  • adjacent stave feet and tops;
  • the two lid boards;
  • the bottom boards' faces and a rim chord the seams split.
+

The fixes:

+
  • stave ends are canted inward, doubled on alternate staves (at one cant, neighbours 5.6° apart in bearing still matched as one plane);
  • one lid board stands 0.6 mm proud;
  • the middle bottom board steps up and in by 0.6 mm.
+

The count is 0.

+
  • A falsifier stolen by the collider. --float-hoops exited 11 on the collider ceiling (242 against 240) instead of 18. The hoops stand 5 mm proud and add nothing a character could hit, so they were taken out of the body hull rather than the ceiling raised. The collider is now 178 triangles, and the falsifier exits 18.
+

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; canted stave ends and stepped boards keep it at 0
Named supportsyesall sixteen staves (--short-stave)
Seat conformance, sampled per segmentyesevery hoop vertex against the stave vertex under it (--float-hoops)
Bands on a curved host are built on the host's arcyeshoop vertices at the staves' own angles
A band wraps its host, never sunk into ityesinner face bites, outer face asserted proud
A head or bottom is boards, not a slabyesthree bottom boards with a banded seam (--one-piece-bottom); the lid is two boards
A vessel holds its contentsn/athe churn shows no contents
A joint bites; touching is not joiningyeshandle into the slats (--short-handle)
Carried parts bite their bearersyeslid on the stave tops (--float-lid)
What passes through a part must clear its mountyeshandle through the lid's hole (--tight-hole)
Identical boards read as CGyesper-stave and per-board PlankTone, grain along each piece's longest extent
Hoops are forged iron, not brightyesnear-black and rust, roughness 0.55–0.85, metallic 0.65
Shading is part of the modelyesstaves smooth across their width with every edge over 35° hard, so they read as coopered boards; handle smooth (turned)
One substance, one slotyesoak, maple, iron
Chamfer n-gon caps, then triangulateyesbottom and lid boards
Sort bmesh operator inputsyesbevel edges sorted by index
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
Rope, masonry, roofs, rings, scatter, mirrored assembliesnothe piece has none of these
+

Falsifiers

+

Each breaks one pipeline stage so a named budget fails. All ten 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 body15
--lift-zgrounded zminlifts the whole mesh 50 mm16
--short-stavenamed stavesstops one stave's foot 6 mm above the floor; the rest ground the AABB16
--one-piece-bottombottom boardsone disk instead of three boards17
--short-handlehandle bitestarts the handle 5 mm above the slats; −5.0 mm17
--float-hoopshoop seatbuilds every hoop 4 mm off the staves; −3.5 mm18
--float-lidlid seatlifts the lid 5 mm; −3.6 to −3.0 mm18
--tight-holehandle clearancecuts the hole 2 mm inside the handle; −2.0 mm18
--wide-dasherplunge strokewidens the slats to 125 mm; 140.4 mm20
+

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 stave floating (--lift-z, --short-stave)
17Bottom boards or handle bite (--one-piece-bottom, --short-handle)
18Hoop seat, lid seat or handle clearance (--float-hoops, --float-lid, --tight-hole)
20Plunge stroke below floor (--wide-dasher)
+

Run it

+
# Budget check, no render. ~1.8 s on 4.5 and 5.2.
+blender --background --python butter_churn.py --
+
+# Falsifier: the plunger jams partway up the narrowing body. Must exit 20.
+blender --background --python butter_churn.py -- --wide-dasher
+
+# Falsifier: the lid's hole is narrower than the handle. Must exit 18.
+blender --background --python butter_churn.py -- --tight-hole
+
+# Render the gallery still (EEVEE; --engine cycles on a GPU-less host).
+blender --background --python butter_churn.py -- --output butter_churn.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 triangles568456845684
LOD1 / LOD2 tris2842 / 1250samesame
Face counts (oak / maple / iron)2240 / 160 / 576samesame
Outer AABB0.3401 × 0.3401 × 1.0500samesame
Collider tris178178178
Plunge stroke / reach513.8 mm / 100.6 mmsamesame
glTF bytes239804239804239796
+
+
+

Source

+
+ showcase/butter-churn/butter_churn.py + View on GitHub → +
+ 
"""Game-ready butter churn — a showcase piece, not an example.
+
+Asserts budget conformance of a procedural plunge churn: a tall staved
+body that narrows toward the top, three iron hoops, a bottom of three
+boards set in a croze, a lid of two boards with a hole for the handle,
+and a cross dasher whose handle runs up through the lid. Carried through
+UVs, three materials (oak, maple, iron), a high-to-low normal bake, an
+LOD chain, a compound convex collider, and a Unity glTF export.
+
+The budget that matters here is the one a churn fails invisibly: the
+dasher has to plunge. The body narrows toward the top, so a plunger that
+clears the staves at rest can jam a hand's width up the stroke. It still
+sits inside the body without touching it, the handle still clears the lid
+and the bounding box does not move; only the stroke knows. The piece
+reads the inner wall off the staves and the plunger's reach off the
+dasher, and asserts how far the plunger can travel before it would meet
+the wall or the lid.
+
+Budgets are declared below and recomputed from the generated result.
+They are not API-contract witnesses. Each falsifier violates one named
+budget: ``--skip-decimate`` the LOD-ratio band, ``--stray-vert`` mesh
+hygiene, ``--lift-z`` grounded zmin, ``--short-stave`` the named staves,
+``--one-piece-bottom`` the bottom boards, ``--short-handle`` the handle
+bite, ``--float-hoops`` the hoop seat, ``--float-lid`` the lid seat,
+``--tight-hole`` the handle clearance, ``--wide-dasher`` the stroke.
+
+No randomness: every stave's tone is a closed-form term of its index.
+DECIMATE COLLAPSE triangle counts are not byte-identical across Blender
+versions — the LOD gate is a ratio band.
+
+    blender --background --python butter_churn.py --
+    blender --background --python butter_churn.py -- --wide-dasher
+    blender --background --python butter_churn.py -- --output butter_churn.png
+"""
+import argparse
+import math
+import os
+import sys
+import tempfile
+import traceback
+
+import bmesh
+import bpy
+from mathutils import Matrix, Vector
+from mathutils.kdtree import KDTree
+
+_REPO = os.path.abspath(
+    os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir, os.pardir)
+)
+sys.path.insert(0, os.path.join(_REPO, "examples"))
+sys.dont_write_bytecode = True
+import gallery_framing  # noqa: E402
+
+# The body: sixteen staves on a straight taper, wider at the foot.
+HEIGHT = 0.750
+R_BOT = 0.170
+R_TOP = 0.120
+N_STAVES = 16
+STAVE_T = 0.018
+STAVE_GAP = 0.0008
+STAVE_FRACS = (0.0, 0.25, 0.75, 1.0)
+BODY_RINGS = 6
+CHAMFER = 0.0015
+SHORT_STAVE = 0.006
+# Each stave's foot and top are cut sloping inward, so the churn stands on
+# its outer edges. Alternate staves take a double cant: at one cant, two
+# neighbours' end faces are only 5.6 degrees apart in bearing and still
+# match as one plane.
+END_CANT = 0.0015
+
+# Hoops: banded iron sampled at each stave's interior vertices, so every
+# hoop vertex sits radially over a stave vertex at the same height.
+HOOP_ZS = (0.060, 0.360, 0.655)
+HOOP_H = 0.024
+HOOP_BITE = 0.0025
+HOOP_PROUD = 0.005
+HOOP_CH = 0.0015
+FLOAT_HOOP = 0.004
+
+# Bottom: three boards in a croze cut into the staves' inner face.
+BOTTOM_Z = 0.012
+BOTTOM_T = 0.022
+CROZE = 0.0035
+N_BOARDS = 3
+BOARD_SEAM = 0.0012
+DISK_SEG = 48
+BOARD_STEP = 0.0006
+
+# Lid: two boards resting on the stave tops, a hole for the handle.
+LID_T = 0.022
+LID_SEAT = 0.002
+LID_OVER = 0.008
+LID_SEAM = 0.0012
+HOLE_CLEAR = 0.005
+TIGHT_HOLE = -0.002
+FLOAT_LID = 0.005
+LID_ARC = 24
+LID_STEP = 0.0006
+
+# Dasher: a round maple handle through the lid, two crossed slats below.
+HANDLE_R = 0.016
+HANDLE_TOP = 1.050
+HANDLE_BITE = 0.014
+SHORT_HANDLE = -0.005
+PLUNGER_Z = BOTTOM_Z + BOTTOM_T + 0.050
+SLAT_REACH = 0.100
+WIDE_REACH = 0.125
+SLAT_W = 0.024
+SLAT_T = 0.020
+SLAT_STEP = 0.004
+WALL_CLEAR = 0.010
+
+BBOX_TOL = 0.020
+OUTER_SIZE = (0.340, 0.340, 1.050)
+
+BASE_TRIS_MIN = 5000
+BASE_TRIS_MAX = 6500
+LOD1_RATIO_MIN = 0.32
+LOD1_RATIO_MAX = 0.62
+LOD2_RATIO_MIN = 0.10
+LOD2_RATIO_MAX = 0.35
+LOD1_TARGET = 0.50
+LOD2_TARGET = 0.22
+MATERIAL_COUNT = 3
+FACE_FLOORS = {0: 2000, 1: 140, 2: 500}
+UV_EPS = 1e-4
+UV_OVERLAP_MAX = 1e-5
+COLLIDER_TRIS_MAX = 200
+BAKE_RES = 512
+CAGE_EXTRUSION = 0.01
+ZMIN_EPS = 1e-4
+DOUBLES_EPS = 1e-5
+AREA_EPS = 1e-10
+COPLANAR_NORMAL_EPS = 1e-4
+COPLANAR_PLANE_EPS = 1e-4
+COPLANAR_CENTRE_MAX = 0.05
+LIFT_Z = 0.05
+STAVE_Z_MAX = 1e-4
+BOARD_SEAM_MIN = 0.0006
+BOARD_SEAM_MAX = 0.0025
+HANDLE_BITE_MIN = 0.008
+HANDLE_BITE_MAX = 0.020
+HOOP_BITE_MIN = 0.0010
+HOOP_BITE_MAX = 0.0045
+HOOP_PROUD_MIN = 0.0030
+LID_SEAT_MIN = 0.0010
+LID_SEAT_MAX = 0.0040
+HOLE_CLEAR_MIN = 0.002
+HOLE_CLEAR_MAX = 0.010
+STROKE_MIN = 0.400
+
+OAK_IDX = 0
+MAPLE_IDX = 1
+IRON_IDX = 2
+
+
+def eevee_engine_id():
+    """EEVEE id: 'BLENDER_EEVEE' on 5.0+, 'BLENDER_EEVEE_NEXT' on 4.2-4.5."""
+    return "BLENDER_EEVEE" if bpy.app.version >= (5, 0, 0) else "BLENDER_EEVEE_NEXT"
+
+
+def fail(msg, code):
+    print(f"FAIL[{code}]: {msg}", file=sys.stderr)
+    return code
+
+
+def triangle_count(mesh):
+    mesh.calc_loop_triangles()
+    return len(mesh.loop_triangles)
+
+
+def evaluated_triangle_count(obj):
+    deps = bpy.context.evaluated_depsgraph_get()
+    ev = obj.evaluated_get(deps)
+    mesh = ev.to_mesh()
+    try:
+        mesh.calc_loop_triangles()
+        return len(mesh.loop_triangles)
+    finally:
+        ev.to_mesh_clear()
+
+
+def r_out(z):
+    return R_BOT + (R_TOP - R_BOT) * z / HEIGHT
+
+
+def r_in(z):
+    return r_out(z) - STAVE_T
+
+
+def stave_angles(k):
+    """Angles of stave ``k``'s vertices across its width, gap split either side."""
+    span = 2.0 * math.pi / N_STAVES
+    gap = STAVE_GAP / R_TOP
+    a0 = k * span + gap * 0.5
+    width = span - gap
+    return [a0 + width * f for f in STAVE_FRACS]
+
+
+def ring_zs():
+    """Stave ring heights: a uniform run plus both edges of every hoop and the croze."""
+    zs = {round(HEIGHT * k / BODY_RINGS, 6) for k in range(BODY_RINGS + 1)}
+    for z in HOOP_ZS:
+        zs |= {round(z, 6), round(z + HOOP_H, 6)}
+    zs |= {round(BOTTOM_Z, 6), round(BOTTOM_Z + BOTTOM_T, 6)}
+    return sorted(zs)
+
+
+# --- construction -----------------------------------------------------------
+
+
+def new_island(ctx):
+    ctx["next"] += 1
+    return ctx["next"]
+
+
+def stamp(ctx, face, island, uvmap):
+    face[ctx["isl"]] = island
+    for loop in face.loops:
+        loop[ctx["uv"]].uv = uvmap[loop.vert]
+
+
+def loft(bm, rings, mat_idx, ctx, closed=True):
+    """Quads between consecutive rings of equal length; one strip island."""
+    island = new_island(ctx)
+    n = len(rings[0])
+    arc = [0.0]
+    for a, b in zip(rings, rings[1:]):
+        ca = sum((v.co for v in a), Vector()) / n
+        cb = sum((v.co for v in b), Vector()) / n
+        arc.append(arc[-1] + (cb - ca).length)
+    faces = []
+    for k in range(len(rings) - 1):
+        a, b = rings[k], rings[k + 1]
+        for i in range(n if closed else n - 1):
+            j = (i + 1) % n
+            f = bm.faces.new((a[i], a[j], b[j], b[i]))
+            f.material_index = mat_idx
+            stamp(ctx, f, island, {a[i]: (arc[k], i / n), a[j]: (arc[k], (i + 1) / n),
+                                   b[j]: (arc[k + 1], (i + 1) / n), b[i]: (arc[k + 1], i / n)})
+            faces.append(f)
+    return faces
+
+
+def add_stave(bm, k, ctx, z0, verts_out):
+    """One stave: an annular sector on the taper, capped by quads at both ends."""
+    angs = stave_angles(k)
+    rings = []
+    for z in ring_zs():
+        # ``z0`` lifts only the foot ring, so a short stave stops above the
+        # floor while its hoop and croze rings stay where the others are.
+        zz = z if z > 0.0 else z0
+        c = END_CANT * (1 + k % 2)
+        cant = c if z <= 0.0 else (-c if z >= HEIGHT else 0.0)
+        outer = [Vector((r_out(z) * math.cos(a), r_out(z) * math.sin(a), zz)) for a in angs]
+        inner = [Vector((r_in(z) * math.cos(a), r_in(z) * math.sin(a), zz + cant))
+                 for a in reversed(angs)]
+        rings.append([bm.verts.new(p) for p in outer + inner])
+    loft(bm, rings, OAK_IDX, ctx)
+    m = len(angs)
+    for ring, flip in ((rings[0], True), (rings[-1], False)):
+        for i in range(m - 1):
+            o0, o1 = ring[i], ring[i + 1]
+            i1, i0 = ring[2 * m - 2 - i], ring[2 * m - 1 - i]
+            vs = (o0, o1, i1, i0)
+            f = bm.faces.new(tuple(reversed(vs)) if flip else vs)
+            f.material_index = OAK_IDX
+            f[ctx["isl"]] = 0
+    for r in rings:
+        verts_out.extend(r)
+
+
+def add_hoop(bm, z, ctx, float_hoop=False):
+    """A banded hoop sampled at every stave's interior vertex angles.
+
+    Its inner face sits HOOP_BITE inside the stave's outer face at each
+    edge height, read from the same taper, so the band follows the staves.
+    """
+    angs = [a for k in range(N_STAVES) for a in stave_angles(k)[1:-1]]
+    off_in = FLOAT_HOOP if float_hoop else -HOOP_BITE
+    sec = [(off_in, 0.0), (HOOP_PROUD - HOOP_CH, 0.0), (HOOP_PROUD, HOOP_CH),
+           (HOOP_PROUD, HOOP_H - HOOP_CH), (HOOP_PROUD - HOOP_CH, HOOP_H), (off_in, HOOP_H)]
+    cols = []
+    for a in angs:
+        c, s = math.cos(a), math.sin(a)
+        cols.append([bm.verts.new(((r_out(z + dz) + dr) * c, (r_out(z + dz) + dr) * s, z + dz))
+                     for dr, dz in sec])
+    island = new_island(ctx)
+    n, m = len(cols), len(sec)
+    for i in range(n):
+        a, b = cols[i], cols[(i + 1) % n]
+        for j in range(m):
+            jj = (j + 1) % m
+            f = bm.faces.new((a[j], a[jj], b[jj], b[j]))
+            f.material_index = IRON_IDX
+            stamp(ctx, f, island, {a[j]: (i / n, j / m), a[jj]: (i / n, (j + 1) / m),
+                                   b[jj]: ((i + 1) / n, (j + 1) / m), b[j]: ((i + 1) / n, j / m)})
+
+
+def clip_x(poly, x0, x1):
+    """Clip a convex (x, y) polygon to x0 <= x <= x1 (Sutherland-Hodgman)."""
+    def cut(pts, keep, xc):
+        out = []
+        for i, p in enumerate(pts):
+            q = pts[(i + 1) % len(pts)]
+            pin, qin = keep(p[0]), keep(q[0])
+            if pin:
+                out.append(p)
+            if pin != qin:
+                t = (xc - p[0]) / (q[0] - p[0])
+                out.append((xc, p[1] + (q[1] - p[1]) * t))
+        return out
+    pts = cut(poly, lambda x: x >= x0, x0)
+    return cut(pts, lambda x: x <= x1, x1)
+
+
+def extrude_polygon(bm, poly, z0, z1, mat_idx, verts_out):
+    """A board from an (x, y) outline: two n-gon caps and quad sides."""
+    lo = [bm.verts.new((x, y, z0)) for x, y in poly]
+    hi = [bm.verts.new((x, y, z1)) for x, y in poly]
+    faces = [bm.faces.new(lo), bm.faces.new(list(reversed(hi)))]
+    n = len(poly)
+    for i in range(n):
+        j = (i + 1) % n
+        faces.append(bm.faces.new((lo[j], lo[i], hi[i], hi[j])))
+    for f in faces:
+        f.material_index = mat_idx
+    verts_out.extend(lo + hi)
+
+
+def add_bottom(bm, one_piece, verts_out):
+    zm = BOTTOM_Z + BOTTOM_T * 0.5
+    rr = r_in(zm) + CROZE
+    disk = [(rr * math.cos(2 * math.pi * i / DISK_SEG), rr * math.sin(2 * math.pi * i / DISK_SEG))
+            for i in range(DISK_SEG)]
+    if one_piece:
+        extrude_polygon(bm, disk, BOTTOM_Z, BOTTOM_Z + BOTTOM_T, OAK_IDX, verts_out)
+        return
+    w = (2.0 * rr - BOARD_SEAM * (N_BOARDS - 1)) / N_BOARDS
+    for k in range(N_BOARDS):
+        x0 = -rr + k * (w + BOARD_SEAM)
+        # Alternate boards step up and in by BOARD_STEP: level with their
+        # neighbours, their faces and the rim chord a seam splits would each
+        # be one plane shared by two boards.
+        step = BOARD_STEP if k % 2 else 0.0
+        src = [(x * (rr - step) / rr, y * (rr - step) / rr) for x, y in disk]
+        poly = clip_x(src, x0 - (1.0 if k == 0 else 0.0), x0 + w + (1.0 if k == N_BOARDS - 1 else 0.0))
+        extrude_polygon(bm, poly, BOTTOM_Z + step, BOTTOM_Z + BOTTOM_T + step, OAK_IDX, verts_out)
+
+
+def add_lid(bm, hole_r, lift, verts_out):
+    """Two half-annulus boards, seam across the hole, resting on the stave tops."""
+    ro = r_out(HEIGHT) + LID_OVER
+    z0 = HEIGHT - LID_SEAT + lift
+    s = LID_SEAM * 0.5
+    t_o = math.acos(s / ro)
+    t_i = math.acos(s / hole_r)
+    for side in (1.0, -1.0):
+        outer = [(ro * math.cos(-t_o + 2 * t_o * k / LID_ARC), ro * math.sin(-t_o + 2 * t_o * k / LID_ARC))
+                 for k in range(LID_ARC + 1)]
+        inner = [(hole_r * math.cos(t_i - 2 * t_i * k / 8), hole_r * math.sin(t_i - 2 * t_i * k / 8))
+                 for k in range(9)]
+        poly = [(side * x, y) for x, y in outer + inner]
+        if side < 0:
+            poly.reverse()
+        # One board a step proud of the other, so the two do not share a face plane.
+        step = LID_STEP if side < 0 else 0.0
+        extrude_polygon(bm, poly, z0 + step, z0 + step + LID_T, OAK_IDX, verts_out)
+
+
+def lathe_z(bm, profile, n, mat_idx, ctx, base):
+    """Revolve an (r, z) profile about the vertical axis through ``base``."""
+    rings, poles = [], []
+    for p in profile:
+        if p.x <= 0.0:
+            poles.append(bm.verts.new(base + Vector((0.0, 0.0, p.y))))
+        else:
+            rings.append([bm.verts.new(base + Vector((p.x * math.cos(2 * math.pi * k / n),
+                                                       p.x * math.sin(2 * math.pi * k / n), p.y)))
+                          for k in range(n)])
+    loft(bm, rings, mat_idx, ctx)
+    island = new_island(ctx)
+    for pole, ring, flip in ((poles[0], rings[0], True), (poles[1], rings[-1], False)):
+        for i in range(n):
+            j = (i + 1) % n
+            vs = (pole, ring[j], ring[i]) if flip else (pole, ring[i], ring[j])
+            f = bm.faces.new(vs)
+            f.material_index = mat_idx
+            stamp(ctx, f, island, {pole: (0.5 if flip else 1.5, (i + 0.5) / n),
+                                   ring[i]: (0.0 if flip else 1.0, i / n),
+                                   ring[j]: (0.0 if flip else 1.0, (i + 1) / n)})
+
+
+def handle_profile(z_start, lid_z0):
+    """(r, z) from the handle's foot, with rings at both faces of the lid."""
+    r = HANDLE_R
+    top = HANDLE_TOP - z_start
+    rings = [(r * 0.85, 0.0), (r, 0.004), (r, lid_z0 - z_start), (r, lid_z0 + LID_T - z_start),
+             (r, top - 0.060), (r * 1.25, top - 0.035), (r * 1.35, top - 0.018), (r * 1.05, top)]
+    return [Vector((0.0, 0.0))] + [Vector(p) for p in rings] + [Vector((0.0, top))]
+
+
+def build_churn_mesh(
+    name,
+    stray_vert=False,
+    short_stave=False,
+    one_piece_bottom=False,
+    short_handle=False,
+    float_hoops=False,
+    float_lid=False,
+    tight_hole=False,
+    wide_dasher=False,
+):
+    bm = bmesh.new()
+    try:
+        ctx = {"uv": bm.loops.layers.uv.new("UVMap"),
+               "isl": bm.faces.layers.int.new("UVIsland"), "next": 0}
+        wood = []
+        for k in range(N_STAVES):
+            add_stave(bm, k, ctx, SHORT_STAVE if (short_stave and k == 0) else 0.0, wood)
+        add_bottom(bm, one_piece_bottom, wood)
+        hole_r = HANDLE_R + (TIGHT_HOLE if tight_hole else HOLE_CLEAR)
+        lid_lift = FLOAT_LID if float_lid else 0.0
+        add_lid(bm, hole_r, lid_lift, wood)
+        # Dasher: two crossed slats, the second a step higher so no two of
+        # their faces share a plane, and the handle's foot biting both.
+        reach = WIDE_REACH if wide_dasher else SLAT_REACH
+        maple = []
+        extrude_polygon(bm, [(-reach, -SLAT_W / 2), (reach, -SLAT_W / 2), (reach, SLAT_W / 2), (-reach, SLAT_W / 2)],
+                PLUNGER_Z, PLUNGER_Z + SLAT_T, MAPLE_IDX, maple)
+        extrude_polygon(bm, [(-SLAT_W / 2, -reach), (SLAT_W / 2, -reach), (SLAT_W / 2, reach), (-SLAT_W / 2, reach)],
+                PLUNGER_Z + SLAT_STEP, PLUNGER_Z + SLAT_STEP + SLAT_T, MAPLE_IDX, maple)
+        # Real edges only (a stave's width and a disk's rim meet at a few
+        # degrees), sorted by index, each pass pinned to its own material.
+        for verts, mat_idx in ((wood, OAK_IDX), (maple, MAPLE_IDX)):
+            bm.edges.index_update()
+            edges = sorted({e for v in verts if v.is_valid for e in v.link_edges
+                            if e.calc_face_angle(0.0) > math.radians(20.0)},
+                           key=lambda e: e.index)
+            bmesh.ops.bevel(bm, geom=edges, offset=CHAMFER, segments=1, profile=0.5,
+                            affect="EDGES", clamp_overlap=True, material=mat_idx)
+        bmesh.ops.triangulate(bm, faces=[f for f in bm.faces if len(f.verts) > 4])
+        for z in HOOP_ZS:
+            add_hoop(bm, z, ctx, float_hoop=float_hoops)
+        z_start = PLUNGER_Z + SLAT_STEP + SLAT_T - (SHORT_HANDLE if short_handle else HANDLE_BITE)
+        lathe_z(bm, handle_profile(z_start, HEIGHT - LID_SEAT + lid_lift), 12, MAPLE_IDX, ctx,
+                Vector((0.0, 0.0, z_start)))
+        if stray_vert:
+            bm.verts.new((0.0, 0.0, 0.3))
+        bmesh.ops.recalc_face_normals(bm, faces=list(bm.faces))
+        for f in bm.faces:
+            f.smooth = True
+        for e in bm.edges:
+            if len(e.link_faces) == 2 and e.calc_face_angle(0.0) > math.radians(35.0):
+                e.smooth = False
+        pack_uvs(bm, ctx)
+        bm.faces.layers.int.remove(ctx["isl"])
+        me = bpy.data.meshes.new(name)
+        bm.to_mesh(me)
+        me.update()
+    finally:
+        bm.free()
+    paint_pieces(me)
+    obj = bpy.data.objects.new(name, me)
+    bpy.context.collection.objects.link(obj)
+    return obj
+
+
+def pack_uvs(bm, ctx, margin=0.06):
+    """One grid cell per UV island: strip islands by their layer tag, else a face each."""
+    uv, isl = ctx["uv"], ctx["isl"]
+    bm.faces.index_update()
+    islands, order = {}, []
+    for face in bm.faces:
+        key = ("s", face[isl]) if face[isl] else ("f", face.index)
+        if key not in islands:
+            islands[key] = []
+            order.append(key)
+        islands[key].append(face)
+    cols = max(1, math.ceil(math.sqrt(len(order))))
+    rows = max(1, math.ceil(len(order) / cols))
+    cw, ch = 1.0 / cols, 1.0 / rows
+    pu, pv = margin * cw * 0.5, margin * ch * 0.5
+    for idx, key in enumerate(order):
+        faces = islands[key]
+        coords = {}
+        for face in faces:
+            if face[isl]:
+                coords[face.index] = [tuple(loop[uv].uv) for loop in face.loops]
+                continue
+            nrm = face.normal
+            ax, ay, az = abs(nrm.x), abs(nrm.y), abs(nrm.z)
+            pts = []
+            for loop in face.loops:
+                co = loop.vert.co
+                if az >= ax and az >= ay:
+                    pts.append((co.x, co.y))
+                elif ax >= ay:
+                    pts.append((co.y, co.z))
+                else:
+                    pts.append((co.x, co.z))
+            coords[face.index] = pts
+        allc = [c for cs in coords.values() for c in cs]
+        minx, maxx = min(c[0] for c in allc), max(c[0] for c in allc)
+        miny, maxy = min(c[1] for c in allc), max(c[1] for c in allc)
+        dx, dy = max(maxx - minx, 1e-8), max(maxy - miny, 1e-8)
+        ou, ov = (idx % cols) * cw + pu, (idx // cols) * ch + pv
+        for face in faces:
+            for loop, (x, y) in zip(face.loops, coords[face.index]):
+                loop[uv].uv = (ou + (x - minx) / dx * (cw - 2 * pu),
+                               ov + (y - miny) / dy * (ch - 2 * pv))
+
+
+def paint_pieces(me):
+    """Per-piece ``PlankTone`` and ``GrainDir`` (each shell's longest extent)."""
+    npoly = len(me.polygons)
+    tone = [0.5] * npoly
+    grain = [(0.0, 0.0, 1.0)] * npoly
+    vf = [[] for _ in range(len(me.vertices))]
+    for p in me.polygons:
+        for i in p.vertices:
+            vf[i].append(p.index)
+    for k, g in enumerate(shells(me)):
+        pts = [me.vertices[i].co for i in g]
+        ext = [max(p[a] for p in pts) - min(p[a] for p in pts) for a in range(3)]
+        axis = ext.index(max(ext))
+        d = tuple(1.0 if a == axis else 0.0 for a in range(3))
+        t = 0.5 + 0.34 * (((k * 0.6180339887 + 0.3) % 1.0) - 0.5)
+        for fi in {fi for i in g for fi in vf[i]}:
+            tone[fi] = t
+            grain[fi] = d
+    a = me.attributes.new("PlankTone", "FLOAT", "FACE")
+    a.data.foreach_set("value", tone)
+    b = me.attributes.new("GrainDir", "FLOAT_VECTOR", "FACE")
+    b.data.foreach_set("vector", [c for v in grain for c in v])
+
+
+# --- surface ----------------------------------------------------------------
+
+
+def _sock(sockets, identifier):
+    return next(sk for sk in sockets if sk.identifier == identifier)
+
+
+def wood_material(name, dark, light, rough=(0.72, 0.52)):
+    """Timber whose grain runs along ``GrainDir`` and whose tone varies by piece."""
+    mat = bpy.data.materials.new(name)
+    mat.use_nodes = True
+    nt = mat.node_tree
+    bsdf = nt.nodes["Principled BSDF"]
+    coord = nt.nodes.new("ShaderNodeTexCoord")
+    gdir = nt.nodes.new("ShaderNodeAttribute")
+    gdir.attribute_name = "GrainDir"
+    tone = nt.nodes.new("ShaderNodeAttribute")
+    tone.attribute_name = "PlankTone"
+    dot = nt.nodes.new("ShaderNodeVectorMath")
+    dot.operation = "DOT_PRODUCT"
+    nt.links.new(coord.outputs["Object"], dot.inputs[0])
+    nt.links.new(gdir.outputs["Vector"], dot.inputs[1])
+    squash = nt.nodes.new("ShaderNodeMath")
+    squash.operation = "MULTIPLY"
+    squash.inputs[1].default_value = 0.94
+    nt.links.new(dot.outputs["Value"], squash.inputs[0])
+    along = nt.nodes.new("ShaderNodeVectorMath")
+    along.operation = "SCALE"
+    nt.links.new(gdir.outputs["Vector"], along.inputs[0])
+    nt.links.new(squash.outputs["Value"], along.inputs["Scale"])
+    grain_co = nt.nodes.new("ShaderNodeVectorMath")
+    grain_co.operation = "SUBTRACT"
+    nt.links.new(coord.outputs["Object"], grain_co.inputs[0])
+    nt.links.new(along.outputs["Vector"], grain_co.inputs[1])
+    shift = nt.nodes.new("ShaderNodeVectorMath")
+    shift.operation = "ADD"
+    nt.links.new(grain_co.outputs["Vector"], shift.inputs[0])
+    nt.links.new(tone.outputs["Fac"], shift.inputs[1])
+    noise = nt.nodes.new("ShaderNodeTexNoise")
+    noise.inputs["Scale"].default_value = 34.0
+    noise.inputs["Detail"].default_value = 6.0
+    noise.inputs["Roughness"].default_value = 0.62
+    nt.links.new(shift.outputs["Vector"], noise.inputs["Vector"])
+    ramp = nt.nodes.new("ShaderNodeValToRGB")
+    ramp.color_ramp.elements[0].position = 0.30
+    ramp.color_ramp.elements[0].color = (*dark, 1.0)
+    ramp.color_ramp.elements[1].position = 0.72
+    ramp.color_ramp.elements[1].color = (*light, 1.0)
+    nt.links.new(noise.outputs["Fac"], ramp.inputs["Fac"])
+    gain = nt.nodes.new("ShaderNodeMath")
+    gain.operation = "MULTIPLY_ADD"
+    gain.inputs[1].default_value = 1.2
+    gain.inputs[2].default_value = 0.40
+    nt.links.new(tone.outputs["Fac"], gain.inputs[0])
+    mix = nt.nodes.new("ShaderNodeMix")
+    mix.data_type = "RGBA"
+    mix.blend_type = "MULTIPLY"
+    _sock(mix.inputs, "Factor_Float").default_value = 1.0
+    nt.links.new(ramp.outputs["Color"], _sock(mix.inputs, "A_Color"))
+    nt.links.new(gain.outputs["Value"], _sock(mix.inputs, "B_Color"))
+    nt.links.new(_sock(mix.outputs, "Result_Color"), bsdf.inputs["Base Color"])
+    rmap = nt.nodes.new("ShaderNodeMapRange")
+    rmap.inputs["To Min"].default_value = rough[0]
+    rmap.inputs["To Max"].default_value = rough[1]
+    nt.links.new(noise.outputs["Fac"], rmap.inputs["Value"])
+    nt.links.new(rmap.outputs["Result"], bsdf.inputs["Roughness"])
+    return mat
+
+
+def iron_material(name):
+    """Forged iron: near-black, rough, rusted in patches. Not chrome."""
+    mat = bpy.data.materials.new(name)
+    mat.use_nodes = True
+    nt = mat.node_tree
+    bsdf = nt.nodes["Principled BSDF"]
+    tc = nt.nodes.new("ShaderNodeTexCoord")
+    noise = nt.nodes.new("ShaderNodeTexNoise")
+    noise.inputs["Scale"].default_value = 40.0
+    noise.inputs["Detail"].default_value = 8.0
+    nt.links.new(tc.outputs["Object"], noise.inputs["Vector"])
+    ramp = nt.nodes.new("ShaderNodeValToRGB")
+    ramp.color_ramp.elements[0].position = 0.45
+    ramp.color_ramp.elements[0].color = (0.035, 0.033, 0.031, 1.0)
+    ramp.color_ramp.elements[1].position = 0.78
+    ramp.color_ramp.elements[1].color = (0.20, 0.085, 0.035, 1.0)
+    nt.links.new(noise.outputs["Fac"], ramp.inputs["Fac"])
+    nt.links.new(ramp.outputs["Color"], bsdf.inputs["Base Color"])
+    bsdf.inputs["Metallic"].default_value = 0.65
+    rough = nt.nodes.new("ShaderNodeMapRange")
+    rough.inputs["To Min"].default_value = 0.55
+    rough.inputs["To Max"].default_value = 0.85
+    nt.links.new(noise.outputs["Fac"], rough.inputs["Value"])
+    nt.links.new(rough.outputs["Result"], bsdf.inputs["Roughness"])
+    return mat
+
+
+def churn_materials():
+    return (
+        wood_material("ChurnOak", (0.085, 0.040, 0.016), (0.28, 0.14, 0.060)),
+        wood_material("ChurnMaple", (0.26, 0.17, 0.09), (0.55, 0.40, 0.24), rough=(0.62, 0.45)),
+        iron_material("ChurnIron"),
+    )
+
+
+def assign_slots(obj, mats):
+    slots = obj.data.materials
+    for i, mat in enumerate(mats):
+        if i < len(slots):
+            slots[i] = mat
+        else:
+            slots.append(mat)
+
+
+# --- measurement ------------------------------------------------------------
+
+
+def world_bbox(obj):
+    corners = [obj.matrix_world @ Vector(c) for c in obj.bound_box]
+    xs, ys, zs = [c.x for c in corners], [c.y for c in corners], [c.z for c in corners]
+    return (min(xs), min(ys), min(zs), max(xs), max(ys), max(zs))
+
+
+def uv_stats(mesh):
+    uv = mesh.uv_layers.active
+    if uv is None:
+        return 0.0, 0.0, 1.0, 1.0, 0.0, 0
+    data = uv.data
+    us = [loop.uv[0] for loop in data]
+    vs = [loop.uv[1] for loop in data]
+    aabbs = []
+    for poly in mesh.polygons:
+        pu = [data[i].uv[0] for i in poly.loop_indices]
+        pv = [data[i].uv[1] for i in poly.loop_indices]
+        aabbs.append((min(pu), min(pv), max(pu), max(pv)))
+    span = max(1e-6, max(a[2] - a[0] for a in aabbs), max(a[3] - a[1] for a in aabbs))
+    buckets = {}
+    for i, a in enumerate(aabbs):
+        for c in range(int(a[0] // span), int(a[2] // span) + 1):
+            for r in range(int(a[1] // span), int(a[3] // span) + 1):
+                buckets.setdefault((c, r), []).append(i)
+    overlap = 0.0
+    seen = set()
+    for members in buckets.values():
+        for ii in range(len(members)):
+            for jj in range(ii + 1, len(members)):
+                i, j = members[ii], members[jj]
+                key = (i, j) if i < j else (j, i)
+                if key in seen:
+                    continue
+                seen.add(key)
+                a, b = aabbs[i], aabbs[j]
+                overlap += max(0.0, min(a[2], b[2]) - max(a[0], b[0])) * max(
+                    0.0, min(a[3], b[3]) - max(a[1], b[1]))
+    return min(us), min(vs), max(us), max(vs), overlap, len(aabbs)
+
+
+def face_area(me, poly):
+    idxs = poly.vertices
+    v0 = me.vertices[idxs[0]].co
+    area = 0.0
+    for i in range(1, len(idxs) - 1):
+        area += (me.vertices[idxs[i]].co - v0).cross(me.vertices[idxs[i + 1]].co - v0).length * 0.5
+    return area
+
+
+def hygiene_audit(me):
+    ngons = sum(1 for p in me.polygons if len(p.vertices) > 4)
+    zero_area = sum(1 for p in me.polygons if face_area(me, p) <= AREA_EPS)
+    bm = bmesh.new()
+    try:
+        bm.from_mesh(me)
+        loose_v = sum(1 for v in bm.verts if len(v.link_edges) == 0)
+        loose_e = sum(1 for e in bm.edges if len(e.link_faces) == 0)
+        nonman = sum(1 for e in bm.edges if not e.is_manifold)
+        ret = bmesh.ops.find_doubles(bm, verts=list(bm.verts), dist=DOUBLES_EPS)
+        doubles = len(ret.get("targetmap") or {})
+    finally:
+        bm.free()
+    return {"ngons": ngons, "loose_v": loose_v, "loose_e": loose_e,
+            "nonman": nonman, "zero_area": zero_area, "doubles": doubles}
+
+
+def shells(me):
+    neighbors = [[] for _ in range(len(me.vertices))]
+    for edge in me.edges:
+        a, b = edge.vertices
+        neighbors[a].append(b)
+        neighbors[b].append(a)
+    seen = [False] * len(me.vertices)
+    groups = []
+    for start in range(len(me.vertices)):
+        if seen[start]:
+            continue
+        seen[start] = True
+        stack = [start]
+        group = []
+        while stack:
+            cur = stack.pop()
+            group.append(cur)
+            for nxt in neighbors[cur]:
+                if not seen[nxt]:
+                    seen[nxt] = True
+                    stack.append(nxt)
+        groups.append(group)
+    return groups
+
+
+def zfight_pairs(me):
+    """Coplanar face pairs from *different shells* (copied from showcase/grindstone)."""
+    owner = {}
+    for si, g in enumerate(shells(me)):
+        for vi in g:
+            owner[vi] = si
+    faces = [(p.normal.copy(), p.center.copy(), owner.get(p.vertices[0], -1))
+             for p in me.polygons]
+    kd = KDTree(len(faces))
+    for i, (_n, c, _s) in enumerate(faces):
+        kd.insert(c, i)
+    kd.balance()
+    hits = 0
+    for i, (ni, ci, si) in enumerate(faces):
+        for _co, j, _d in kd.find_range(ci, COPLANAR_CENTRE_MAX):
+            if j <= i:
+                continue
+            nj, cj, sj = faces[j]
+            if si == sj:
+                continue
+            if abs(abs(ni.dot(nj)) - 1.0) > COPLANAR_NORMAL_EPS:
+                continue
+            if abs(ni.dot(cj - ci)) > COPLANAR_PLANE_EPS:
+                continue
+            hits += 1
+    return hits
+
+
+def classify(me):
+    mats = {}
+    for p in me.polygons:
+        for i in p.vertices:
+            mats.setdefault(i, p.material_index)
+    out = {"stave": [], "board": [], "lid": [], "hoop": [], "slat": [], "handle": [], "other": []}
+    for g in shells(me):
+        pts = [me.vertices[i].co.copy() for i in g]
+        lo = Vector((min(p.x for p in pts), min(p.y for p in pts), min(p.z for p in pts)))
+        hi = Vector((max(p.x for p in pts), max(p.y for p in pts), max(p.z for p in pts)))
+        rec = {"g": g, "pts": pts, "lo": lo, "hi": hi, "ext": hi - lo,
+               "c": sum(pts, Vector()) / len(pts)}
+        m = mats.get(g[0], -1)
+        e = rec["ext"]
+        if m == OAK_IDX:
+            if e.z > HEIGHT * 0.5:
+                out["stave"].append(rec)
+            elif lo.z > HEIGHT * 0.5:
+                out["lid"].append(rec)
+            else:
+                out["board"].append(rec)
+        elif m == MAPLE_IDX:
+            out["handle" if e.z > 0.3 else "slat"].append(rec)
+        elif m == IRON_IDX:
+            out["hoop"].append(rec)
+        else:
+            out["other"].append(rec)
+    return out
+
+
+def radial(p):
+    return math.hypot(p.x, p.y)
+
+
+def churn_audit(me):
+    parts = classify(me)
+    out = {k: len(v) for k, v in parts.items()}
+    staves = parts["stave"]
+    out["stave_z"] = max((r["lo"].z for r in staves), default=99.0)
+
+    # Bottom boards: count and the seams between neighbours.
+    boards = sorted(parts["board"], key=lambda r: r["c"].x)
+    seams = [b["lo"].x - a["hi"].x for a, b in zip(boards, boards[1:])]
+    out["seam"] = (min(seams, default=-99.0), max(seams, default=99.0))
+
+    # Hoops on the staves: every hoop vertex against the stave vertex it
+    # was built over, measured radially.
+    spts = [p for r in staves for p in r["pts"]]
+    kd = KDTree(len(spts))
+    for i, p in enumerate(spts):
+        kd.insert(p, i)
+    kd.balance()
+    bites, prouds = [], []
+    for h in parts["hoop"]:
+        ds = sorted(radial(kd.find(p)[0]) - radial(p) for p in h["pts"])
+        n_in = len(ds) // 3
+        bites.append(min(ds[-n_in:]))
+        prouds.append(-max(ds[:n_in]))
+    out["hoop_bite"] = (min(bites, default=-99.0), max(bites, default=99.0))
+    out["hoop_proud"] = min(prouds, default=-99.0)
+
+    # The lid rests on the stave tops; the handle clears the lid's hole.
+    top = max((r["hi"].z for r in staves), default=0.0)
+    lids = parts["lid"]
+    seats = [top - r["lo"].z for r in lids]
+    out["lid_seat"] = (min(seats, default=-99.0), max(seats, default=99.0))
+    out["hole_clear"] = -99.0
+    handle = parts["handle"][0] if parts["handle"] else None
+    if handle and lids:
+        lz0 = min(r["lo"].z for r in lids)
+        lz1 = max(r["hi"].z for r in lids)
+        hr = max((radial(p) for p in handle["pts"] if lz0 - 1e-6 <= p.z <= lz1 + 1e-6), default=99.0)
+        lr = min(radial(p) for r in lids for p in r["pts"])
+        out["hole_clear"] = lr - hr
+
+    # The handle's foot bites the slats.
+    slats = parts["slat"]
+    out["handle_bite"] = -99.0
+    if handle and slats:
+        out["handle_bite"] = max(r["hi"].z for r in slats) - handle["lo"].z
+
+    # Stroke: the inner wall read off the staves, ring by ring, against the
+    # plunger's reach about the handle's axis.
+    out["stroke"] = -99.0
+    if slats and staves:
+        reach = max(radial(p) for r in slats for p in r["pts"])
+        p_top = max(r["hi"].z for r in slats)
+        walls = {}
+        for p in spts:
+            z = round(p.z, 5)
+            walls[z] = min(walls.get(z, 99.0), radial(p))
+        table = sorted(walls.items())
+        need = reach + WALL_CLEAR
+        limit = min((r["lo"].z for r in lids), default=top)
+        z_ok = None
+        for (za, ra), (zb, rb) in zip(table, table[1:]):
+            if za < p_top - 1e-6:
+                continue
+            if rb >= need:
+                continue
+            if ra >= need:
+                z_ok = za + (zb - za) * (ra - need) / (ra - rb)
+            else:
+                z_ok = za
+            break
+        if z_ok is None:
+            z_ok = limit
+        out["reach"] = reach
+        out["stroke"] = min(z_ok, limit) - p_top
+    return out
+
+
+def make_lod(obj, name, ratio, skip_decimate):
+    mesh = obj.data.copy()
+    lod = bpy.data.objects.new(name, mesh)
+    lod.matrix_world = obj.matrix_world.copy()
+    bpy.context.scene.collection.objects.link(lod)
+    if not skip_decimate and 0.0 < ratio < 1.0:
+        mod = lod.modifiers.new("DecimateBudget", "DECIMATE")
+        mod.decimate_type = "COLLAPSE"
+        mod.ratio = ratio
+    return lod
+
+
+def hull_collider(obj, name):
+    """Compound collider: one hull for the staves and lid, one for the handle above it.
+
+    The hoops stand 5 mm proud of the staves and are left out: in the hull
+    they add triangles and nothing a character could collide with.
+    """
+    me = obj.data
+    parts = classify(me)
+    body = [p for k in ("stave", "lid") for r in parts[k] for p in r["pts"]]
+    body = [p for i, p in enumerate(body) if i % 3 == 0]
+    groups = [body]
+    if parts["handle"]:
+        top = max(p.z for r in parts["lid"] for p in r["pts"]) if parts["lid"] else HEIGHT
+        groups.append([p for p in parts["handle"][0]["pts"] if p.z >= top - 0.01])
+    mesh = bpy.data.meshes.new(name)
+    bm = bmesh.new()
+    try:
+        for pts in groups:
+            tmp = bmesh.new()
+            try:
+                vs = [tmp.verts.new(p) for p in pts]
+                bmesh.ops.convex_hull(tmp, input=vs)
+                bmesh.ops.dissolve_limit(tmp, angle_limit=math.radians(4.0),
+                                         verts=list(tmp.verts), edges=list(tmp.edges))
+                bmesh.ops.triangulate(tmp, faces=list(tmp.faces))
+                remap = {}
+                for f in tmp.faces:
+                    for v in f.verts:
+                        if v not in remap:
+                            remap[v] = bm.verts.new(v.co)
+                    bm.faces.new([remap[v] for v in f.verts])
+            finally:
+                tmp.free()
+        bm.to_mesh(mesh)
+        mesh.update()
+    finally:
+        bm.free()
+    col = bpy.data.objects.new(name, mesh)
+    bpy.context.collection.objects.link(col)
+    return col
+
+
+def setup_bake_image(obj, target_mat, size):
+    img = bpy.data.images.new("ChurnNrm", size, size, alpha=True, float_buffer=False)
+    img.colorspace_settings.name = "Non-Color"
+    nodes = target_mat.node_tree.nodes
+    tex = nodes.new("ShaderNodeTexImage")
+    tex.image = img
+    nodes.active = tex
+    tex.select = True
+    obj.active_material_index = OAK_IDX
+    return img, tex
+
+
+def bake_normal(high, low):
+    scene = bpy.context.scene
+    scene.render.engine = "CYCLES"
+    scene.cycles.device = "CPU"
+    scene.cycles.samples = 1
+    scene.cycles.use_denoising = False
+    for ob in bpy.context.view_layer.objects:
+        ob.select_set(False)
+    high.select_set(True)
+    low.select_set(True)
+    bpy.context.view_layer.objects.active = low
+    return bpy.ops.object.bake(
+        type="NORMAL", use_selected_to_active=True, cage_extrusion=CAGE_EXTRUSION,
+        use_cage=False, normal_space="TANGENT", margin=4,
+        margin_type="ADJACENT_FACES", use_clear=True, target="IMAGE_TEXTURES",
+    )
+
+
+def export_unity(path, objects):
+    for ob in bpy.context.view_layer.objects:
+        ob.select_set(False)
+    for ob in objects:
+        ob.select_set(True)
+    bpy.context.view_layer.objects.active = objects[0]
+    bpy.ops.export_scene.gltf(
+        filepath=path, use_selection=True, export_yup=True, export_apply=True,
+        export_draco_mesh_compression_enable=False, export_animations=False,
+    )
+
+
+def check(skip_decimate, lift_z=False, **flags):
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+    nothing = (None,) * 5
+    low = build_churn_mesh("ChurnLow", **flags)
+    hi_flags = {k: v for k, v in flags.items() if k != "stray_vert"}
+    high = build_churn_mesh("ChurnHigh", **hi_flags)
+    mats = churn_materials()
+    assign_slots(low, mats)
+    assign_slots(high, mats)
+    if lift_z:
+        for v in low.data.vertices:
+            v.co.z += LIFT_Z
+        low.data.update()
+        bpy.context.view_layer.update()
+    if len(low.data.polygons) < 6 or not low.data.uv_layers:
+        return (fail("churn mesh did not build, or has no UV layer", 3),) + nothing
+
+    base_tris = triangle_count(low.data)
+    slots = [s for s in low.data.materials if s is not None]
+    nmat, distinct = len(slots), len({id(s) for s in slots})
+    idx_counts = {}
+    for poly in low.data.polygons:
+        idx_counts[poly.material_index] = idx_counts.get(poly.material_index, 0) + 1
+    u0, v0, u1, v1, overlap, nfaces = uv_stats(low.data)
+    bb = world_bbox(low)
+    size_x, size_y, size_z = bb[3] - bb[0], bb[4] - bb[1], bb[5] - bb[2]
+
+    img, tex = setup_bake_image(low, mats[OAK_IDX], BAKE_RES)
+    bake_result = bake_normal(high, low)
+
+    lod1 = make_lod(low, "ChurnLOD1", LOD1_TARGET, skip_decimate)
+    lod2 = make_lod(low, "ChurnLOD2", LOD2_TARGET, skip_decimate)
+    bpy.context.view_layer.update()
+    lod1_tris = evaluated_triangle_count(lod1)
+    lod2_tris = evaluated_triangle_count(lod2)
+    r1 = lod1_tris / base_tris if base_tris else 0.0
+    r2 = lod2_tris / base_tris if base_tris else 0.0
+
+    collider = hull_collider(high, "ChurnCollider")
+    col_tris = triangle_count(collider.data)
+
+    export_path = os.path.join(tempfile.gettempdir(), f"bdt_churn_{os.getpid()}.glb")
+    if os.path.exists(export_path):
+        os.remove(export_path)
+    export_unity(export_path, [low, collider])
+    export_size = os.path.getsize(export_path) if os.path.isfile(export_path) else 0
+    # Blender points TMPDIR at its own temp preference, which on a portable
+    # build is the working directory, so the export must not outlive this.
+    if os.path.isfile(export_path):
+        os.remove(export_path)
+
+    hyg = hygiene_audit(low.data)
+    zf = zfight_pairs(low.data)
+    ca = churn_audit(low.data)
+
+    print(f"blender={tuple(bpy.app.version)} skip_decimate={skip_decimate}")
+    print(f"measured mat_index_counts={dict(sorted(idx_counts.items()))}")
+    print(f"measured base_tris={base_tris} lod1_tris={lod1_tris} "
+          f"lod2_tris={lod2_tris} r1={r1:.4f} r2={r2:.4f}")
+    print(f"measured nmat={nmat} uv=({u0:.4f},{v0:.4f})-({u1:.4f},{v1:.4f}) "
+          f"overlap={overlap:.6f} nfaces={nfaces}")
+    print(f"measured bbox=({size_x:.4f},{size_y:.4f},{size_z:.4f}) "
+          f"outer={OUTER_SIZE} zmin={bb[2]:.5f}")
+    print(f"measured collider_tris={col_tris} bake={bake_result} "
+          f"bake_has_data={img.has_data} export_bytes={export_size}")
+    print(f"measured hygiene loose_v={hyg['loose_v']} loose_e={hyg['loose_e']} "
+          f"nonman={hyg['nonman']} zero_area={hyg['zero_area']} "
+          f"doubles={hyg['doubles']} ngons={hyg['ngons']} zfight={zf}")
+    print(f"measured parts staves={ca['stave']} boards={ca['board']} lid={ca['lid']} "
+          f"hoops={ca['hoop']} slats={ca['slat']} handle={ca['handle']} other={ca['other']} "
+          f"stave_z={ca['stave_z']:.5f}")
+    print(f"measured joints seam=({ca['seam'][0]:.5f},{ca['seam'][1]:.5f}) "
+          f"handle_bite={ca['handle_bite']:.5f}")
+    print(f"measured seats hoop_bite=({ca['hoop_bite'][0]:.5f},{ca['hoop_bite'][1]:.5f}) "
+          f"hoop_proud={ca['hoop_proud']:.5f} lid=({ca['lid_seat'][0]:.5f},{ca['lid_seat'][1]:.5f}) "
+          f"hole_clear={ca['hole_clear']:.5f}")
+    print(f"measured stroke={ca['stroke']:.5f} reach={ca.get('reach', 0.0):.5f}")
+
+    if not (BASE_TRIS_MIN <= base_tris <= BASE_TRIS_MAX):
+        return (fail(f"base tris {base_tris} not in [{BASE_TRIS_MIN}, {BASE_TRIS_MAX}]", 4),) + nothing
+    if nmat != MATERIAL_COUNT or distinct != MATERIAL_COUNT:
+        return (fail(f"material slots {nmat} distinct {distinct} != {MATERIAL_COUNT}", 5),) + nothing
+    for idx, floor in FACE_FLOORS.items():
+        if idx_counts.get(idx, 0) < floor:
+            return (fail(f"material {idx} faces {idx_counts.get(idx, 0)} < {floor}", 5),) + nothing
+    if u0 < -UV_EPS or v0 < -UV_EPS or u1 > 1.0 + UV_EPS or v1 > 1.0 + UV_EPS:
+        return (fail(f"UVs outside 0..1: ({u0:.4f},{v0:.4f})-({u1:.4f},{v1:.4f})", 6),) + nothing
+    if overlap > UV_OVERLAP_MAX:
+        return (fail(f"UV AABB overlap {overlap:.6f} > {UV_OVERLAP_MAX}", 7),) + nothing
+    if (abs(size_x - OUTER_SIZE[0]) > BBOX_TOL or abs(size_y - OUTER_SIZE[1]) > BBOX_TOL
+            or abs(size_z - OUTER_SIZE[2]) > BBOX_TOL):
+        return (fail(f"bbox ({size_x:.4f},{size_y:.4f},{size_z:.4f}) off outer {OUTER_SIZE}", 8),) + nothing
+    if not (LOD1_RATIO_MIN <= r1 <= LOD1_RATIO_MAX):
+        return (fail(f"LOD1 ratio {r1:.4f} not in [{LOD1_RATIO_MIN}, {LOD1_RATIO_MAX}] "
+                     "(--skip-decimate is the designed fail)", 9),) + nothing
+    if not (LOD2_RATIO_MIN <= r2 <= LOD2_RATIO_MAX):
+        return (fail(f"LOD2 ratio {r2:.4f} not in [{LOD2_RATIO_MIN}, {LOD2_RATIO_MAX}]", 9),) + nothing
+    if col_tris > COLLIDER_TRIS_MAX:
+        return (fail(f"collider tris {col_tris} > {COLLIDER_TRIS_MAX}", 11),) + nothing
+    if bake_result != {"FINISHED"} or not img.has_data:
+        return (fail(f"bake failed result={bake_result} has_data={img.has_data}", 12),) + nothing
+    if export_size <= 0:
+        return (fail("export file missing or empty", 13),) + nothing
+    if (hyg["loose_v"] or hyg["loose_e"] or hyg["nonman"] or hyg["zero_area"]
+            or hyg["doubles"] or hyg["ngons"] or zf):
+        return (fail(f"hygiene {hyg} zfight={zf} (--stray-vert is the designed fail)", 15),) + nothing
+    if abs(bb[2]) > ZMIN_EPS:
+        return (fail(f"zmin {bb[2]:.6f} not within {ZMIN_EPS} of 0 "
+                     "(--lift-z is the designed fail)", 16),) + nothing
+    if ca["stave"] != N_STAVES or ca["stave_z"] > STAVE_Z_MAX:
+        return (fail(f"staves: {ca['stave']} of {N_STAVES}, worst stave z={ca['stave_z']:.5f} "
+                     f"> {STAVE_Z_MAX} (--short-stave is the designed fail)", 16),) + nothing
+    if (ca["board"] != N_BOARDS or ca["seam"][0] < BOARD_SEAM_MIN
+            or ca["seam"][1] > BOARD_SEAM_MAX):
+        return (fail(f"{ca['board']} of {N_BOARDS} bottom boards, seams {ca['seam']} outside "
+                     f"[{BOARD_SEAM_MIN}, {BOARD_SEAM_MAX}] (--one-piece-bottom is the designed fail)",
+                     17),) + nothing
+    if not (HANDLE_BITE_MIN <= ca["handle_bite"] <= HANDLE_BITE_MAX):
+        return (fail(f"handle bite {ca['handle_bite']:.5f} outside [{HANDLE_BITE_MIN}, "
+                     f"{HANDLE_BITE_MAX}] (--short-handle is the designed fail)", 17),) + nothing
+    if (ca["hoop"] != len(HOOP_ZS) or ca["hoop_bite"][0] < HOOP_BITE_MIN
+            or ca["hoop_bite"][1] > HOOP_BITE_MAX or ca["hoop_proud"] < HOOP_PROUD_MIN):
+        return (fail(f"{ca['hoop']} of {len(HOOP_ZS)} hoops, bite {ca['hoop_bite']} outside "
+                     f"[{HOOP_BITE_MIN}, {HOOP_BITE_MAX}] or proud {ca['hoop_proud']:.5f} < "
+                     f"{HOOP_PROUD_MIN} (--float-hoops is the designed fail)", 18),) + nothing
+    if (ca["lid"] != 2 or ca["lid_seat"][0] < LID_SEAT_MIN or ca["lid_seat"][1] > LID_SEAT_MAX):
+        return (fail(f"{ca['lid']} of 2 lid boards, seat {ca['lid_seat']} outside "
+                     f"[{LID_SEAT_MIN}, {LID_SEAT_MAX}] (--float-lid is the designed fail)", 18),) + nothing
+    if not (HOLE_CLEAR_MIN <= ca["hole_clear"] <= HOLE_CLEAR_MAX):
+        return (fail(f"handle clears the lid hole by {ca['hole_clear']:.5f}, outside "
+                     f"[{HOLE_CLEAR_MIN}, {HOLE_CLEAR_MAX}] (--tight-hole is the designed fail)",
+                     18),) + nothing
+    if ca["stroke"] < STROKE_MIN:
+        return (fail(f"plunge stroke {ca['stroke']:.5f} < {STROKE_MIN} "
+                     "(--wide-dasher is the designed fail)", 20),) + nothing
+    return 0, low, high, mats, tex, collider
+
+
+def wire_normal(mat, tex):
+    nt = mat.node_tree
+    nrm = nt.nodes.new("ShaderNodeNormalMap")
+    nt.links.new(tex.outputs["Color"], nrm.inputs["Color"])
+    nt.links.new(nrm.outputs["Normal"], nt.nodes["Principled BSDF"].inputs["Normal"])
+
+
+def render_still(low, mats, tex, path, engine):
+    scene = bpy.context.scene
+    wire_normal(mats[OAK_IDX], tex)
+    for ob in list(scene.objects):
+        if ob.type == "MESH" and ob != low:
+            ob.hide_render = True
+            ob.hide_viewport = True
+    # Level on the floor: turned about Z only.
+    low.rotation_euler.z = math.radians(10.0)
+
+    floor_me = bpy.data.meshes.new("Floor")
+    bm = bmesh.new()
+    try:
+        bmesh.ops.create_grid(bm, x_segments=1, y_segments=1, size=60.0)
+        bm.to_mesh(floor_me)
+    finally:
+        bm.free()
+    fmat = bpy.data.materials.new("Floor")
+    fmat.use_nodes = True
+    fb = fmat.node_tree.nodes["Principled BSDF"]
+    fb.inputs["Base Color"].default_value = (0.03, 0.032, 0.037, 1.0)
+    fb.inputs["Roughness"].default_value = 0.7
+    floor_me.materials.append(fmat)
+    floor = bpy.data.objects.new("Floor", floor_me)
+    scene.collection.objects.link(floor)
+    wall = bpy.data.objects.new("Wall", floor_me.copy())
+    wall.location = (0.0, 8.5, 0.0)
+    wall.rotation_euler = (math.radians(90), 0.0, 0.0)
+    scene.collection.objects.link(wall)
+
+    world = bpy.data.worlds.new("World")
+    world.use_nodes = True
+    world.node_tree.nodes["Background"].inputs["Color"].default_value = (0.02, 0.021, 0.025, 1.0)
+    scene.world = world
+
+    def light(name, kind, loc, energy, size, col, rot=(0, 0, 0)):
+        ld = bpy.data.lights.new(name, kind)
+        ld.energy = energy
+        if kind == "AREA":
+            ld.size = size
+        else:
+            ld.shadow_soft_size = size
+        ld.color = col
+        ob = bpy.data.objects.new(name, ld)
+        ob.location = loc
+        ob.rotation_euler = tuple(math.radians(a) for a in rot)
+        scene.collection.objects.link(ob)
+
+    light("Key", "AREA", (-2.4, -3.2, 3.2), 360.0, 3.0, (1.0, 0.95, 0.88), (50, 0, -35))
+    light("Fill", "AREA", (3.2, -2.6, 1.6), 60.0, 5.0, (0.74, 0.84, 1.0), (68, 0, 50))
+    light("Rim", "AREA", (-1.6, 2.6, 2.4), 220.0, 3.0, (0.62, 0.78, 1.0), (-55, 0, 200))
+    ld = bpy.data.lights.new("Wedge", "SPOT")
+    ld.energy, ld.color = 220.0, (1.0, 0.66, 0.34)
+    ld.spot_size, ld.spot_blend, ld.shadow_soft_size = math.radians(50.0), 1.0, 0.3
+    wedge = bpy.data.objects.new("Wedge", ld)
+    wedge.location = (0.5, 1.6, 2.0)
+    wedge.rotation_euler = (Vector((0.25, 0.5, 0.0)) - wedge.location).to_track_quat(
+        "-Z", "Y").to_euler()
+    scene.collection.objects.link(wedge)
+
+    cam_data = bpy.data.cameras.new("Cam")
+    cam_data.lens = 50.0
+    cam = bpy.data.objects.new("Cam", cam_data)
+    cam.location = (1.23, -2.86, 1.28)
+    scene.collection.objects.link(cam)
+    aim = bpy.data.objects.new("Aim", None)
+    aim.location = (0.0, 0.0, 0.52)
+    scene.collection.objects.link(aim)
+    con = cam.constraints.new("TRACK_TO")
+    con.target = aim
+    con.track_axis = "TRACK_NEGATIVE_Z"
+    con.up_axis = "UP_Y"
+    scene.camera = cam
+
+    scene.render.engine = "CYCLES" if engine == "cycles" else eevee_engine_id()
+    if engine == "cycles":
+        scene.cycles.samples = 32
+        scene.cycles.device = "CPU"
+    else:
+        try:
+            scene.eevee.taa_render_samples = 64
+        except AttributeError:
+            pass
+    scene.render.resolution_x = 1280
+    scene.render.resolution_y = 720
+    scene.render.image_settings.file_format = "WEBP" if path.lower().endswith(".webp") else "PNG"
+    if path.lower().endswith(".webp"):
+        scene.render.image_settings.quality = 90
+    scene.render.filepath = path
+    scene.view_settings.view_transform = "Standard"
+
+    fcode = gallery_framing.check_framing(scene, cam, hero=[low], elements=[low], stage=[floor, wall])
+    if fcode:
+        return fcode
+    bpy.ops.render.render(write_still=True)
+    if not (os.path.exists(path) and os.path.getsize(path) > 0):
+        return fail("render produced no file", 14)
+    return 0
+
+
+def main():
+    argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
+    p = argparse.ArgumentParser()
+    p.add_argument("--output", default=None)
+    p.add_argument("--engine", default="eevee", choices=("eevee", "cycles"))
+    p.add_argument("--skip-decimate", action="store_true")
+    p.add_argument("--stray-vert", action="store_true")
+    p.add_argument("--lift-z", action="store_true")
+    p.add_argument("--short-stave", action="store_true")
+    p.add_argument("--one-piece-bottom", action="store_true")
+    p.add_argument("--short-handle", action="store_true")
+    p.add_argument("--float-hoops", action="store_true")
+    p.add_argument("--float-lid", action="store_true")
+    p.add_argument("--tight-hole", action="store_true")
+    p.add_argument("--wide-dasher", action="store_true")
+    args = p.parse_args(argv)
+
+    code, low, _high, mats, tex, _col = check(
+        args.skip_decimate,
+        lift_z=args.lift_z,
+        stray_vert=args.stray_vert,
+        short_stave=args.short_stave,
+        one_piece_bottom=args.one_piece_bottom,
+        short_handle=args.short_handle,
+        float_hoops=args.float_hoops,
+        float_lid=args.float_lid,
+        tight_hole=args.tight_hole,
+        wide_dasher=args.wide_dasher,
+    )
+    if code:
+        return code
+    if args.output:
+        rcode = render_still(low, mats, tex, os.path.abspath(args.output), args.engine)
+        if rcode:
+            return rcode
+        print(f"rendered still {args.output}")
+    print("butter churn OK")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as e:
+        traceback.print_exc()
+        print(f"FATAL: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+
+ + + A tall staved oak butter churn narrowing toward the top, bound by three dark iron hoops, with a two-board lid and a pale maple dasher handle rising through it. + +
+
+ generated from showcase/gallery.json + CC-BY-NC-ND-4.0 + exit 0 +
+
+ + + diff --git a/docs/gallery/contact-sheets/butter-churn-contact-sheet.webp b/docs/gallery/contact-sheets/butter-churn-contact-sheet.webp new file mode 100644 index 00000000..e82bb8a7 Binary files /dev/null and b/docs/gallery/contact-sheets/butter-churn-contact-sheet.webp differ diff --git a/docs/gallery/index.html b/docs/gallery/index.html index a7cb210c..48ed8007 100644 --- a/docs/gallery/index.html +++ b/docs/gallery/index.html @@ -291,7 +291,7 @@

Examples and Showcase

autocomplete="off" spellcheck="false" aria-label="Search examples and showcase pieces" /> - 51 examples, 33 showcase pieces + 51 examples, 34 showcase pieces
@@ -1265,6 +1265,17 @@

wooden-yoke

View showcase piece wooden-yoke
+
+ +
+

butter-churn

+

A procedural plunge butter churn — sixteen tapered oak staves, three iron hoops, a three-board bottom, a two-board lid and a maple cross dasher — carried through UVs, bake, LOD, compound collider, and Unity glTF, asserting recomputed budgets rather than an API contract.

+

witnesses Recomputed: 5684 tris, three materials with 2240 oak, 160 maple and 576 iron faces, UVs in 0..1 with zero AABB overlap, outer AABB 0.340×0.340×1.050 m, zmin 0, hygiene 0 including zero coplanar cross-shell pairs, all sixteen staves on the floor, three bottom boards with 1.2 mm seams, the handle 14 mm into the slats, three hoops 2.5 mm into the staves and 4.9 mm proud, the lid 1.4–2.0 mm onto the stave tops, 5 mm of clearance round the handle, and a 514 mm plunge stroke for a 101 mm reach. --wide-dasher exits 20 at 140 mm while the plunger still clears the staves at rest; --tight-hole exits 18.

+ View showcase piece butter-churn +
+
@@ -1294,7 +1305,7 @@

wooden-yoke

var tagsToggle = document.getElementById('tagsToggle'); var toTop = document.getElementById('toTop'); var total = cards.length; - var COUNT_LABEL = '51 examples, 33 showcase pieces'; + var COUNT_LABEL = '51 examples, 34 showcase pieces'; var LS_KEY = 'bdt-gallery-density'; var reduced = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches; diff --git a/showcase/butter-churn/README.md b/showcase/butter-churn/README.md new file mode 100644 index 00000000..4d3ba826 --- /dev/null +++ b/showcase/butter-churn/README.md @@ -0,0 +1,238 @@ +# butter-churn + +![A tall staved oak butter churn narrowing toward the top, bound by three dark iron hoops, with a two-board lid and a pale maple dasher handle rising through it](preview.webp) + +A plunge butter churn: a tall body of sixteen oak staves that narrows +toward the top, three forged iron hoops, a bottom of three boards set in +a croze, a lid of two boards with a hole for the handle, and a maple +cross dasher whose handle runs up through the lid. **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 content | Used for | +| --- | --- | +| `skills/mesh-editing-and-bmesh` | lofted staves, banded hoops, clipped board polygons, lathed handle, all in one `bmesh` | +| `skills/custom-properties` | face attributes (`PlankTone`, `GrainDir`) read by the wood shaders | +| `skills/procedural-materials-and-shaders` | oak with grain along each stave, pale maple, rusted rough iron | +| `skills/bake-high-to-low` | Cycles tangent-space normal bake, high onto low | +| `skills/engine-export-presets` | Unity glTF (`export_yup=True`) | +| `skills/depsgraph-and-evaluated-data` | evaluated triangle counts for the LOD ratios | +| `snippets/decimate_to_budget.py` | LOD1 / LOD2 COLLAPSE chain | +| `snippets/convex_hull_collider.py` | one hull for the body and lid, one for the handle above it | +| `snippets/lod_chain.py` | LOD naming and ratio pattern | +| `examples/mesh-hygiene-audit` | hygiene combinatorics (copied, not imported) | + +## The budget that matters + +A churn is for plunging. The body narrows toward the top, so a plunger +that clears the staves at the bottom can jam partway up the stroke, and +nothing else notices: + +- the plunger still sits inside the body without touching it; +- the handle still clears the lid's hole; +- the bounding box does not move. + +The piece reads the inner wall off the staves ring by ring and the +plunger's reach off the dasher's slats, about the handle's axis. It +finds the height at which the wall comes within `WALL_CLEAR` (10 mm) of +the plunger, stops at the lid if that comes first, and asserts the +travel from the plunger's rest height as a stroke floor of 400 mm. +Measured: 513.8 mm, for a 100.6 mm reach. + +`--wide-dasher` is the falsifier built for exactly this. It widens the +slats to 125 mm. The plunger still clears the staves at rest, but it can +travel only 140.4 mm before it would meet the wall, and the run exits +20. Every other budget passes and the AABB is unchanged. + +## 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 8 bytes, which is +exporter metadata and not a budget). + +| Budget | Band | Measured | +| --- | --- | --- | +| Base triangles | 5000–6500 | 5684 | +| LOD1 ratio | 0.32–0.62 | 0.5000 | +| LOD2 ratio | 0.10–0.35 | 0.2199 | +| Material slots | exactly 3, distinct | 3 | +| Oak / maple / iron faces | ≥ 2000 / 140 / 500 | 2240 / 160 / 576 | +| UV bounds | inside 0..1 | (0.0013, 0.0013)–(0.9987, 0.9987) | +| UV AABB overlap | ≤ 1e-5 | 0.000000 | +| Outer AABB | 0.340 × 0.340 × 1.050 m ± 0.020 | 0.3401 × 0.3401 × 1.0500 | +| Collider triangles | ≤ 200 | 178 (two hulls) | +| Normal bake | `{'FINISHED'}` with image data | `{'FINISHED'}`, `has_data=True` | +| glTF export | file written, non-empty | ~240 kB | +| Hygiene | all zero | loose 0/0, non-manifold 0, zero-area 0, doubles 0, n-gons 0, coplanar cross-shell pairs 0 | +| Grounded AABB | \|zmin\| ≤ 1e-4 | 0.00000 | +| Named staves | 16 staves, each zmin ≤ 1e-4 | 16 at 0.00000 | +| Bottom boards | 3 boards, seams 0.6–2.5 mm | 3, 1.20 mm | +| Handle bite | handle's foot 8–20 mm into the slats | 14.0 mm | +| Hoop seat | 3 hoops, inner face 1.0–4.5 mm into the staves, outer face ≥ 3 mm proud | 2.50 mm in, 4.90 mm proud | +| Lid seat | 2 boards, each 1–4 mm onto the stave tops | 1.40–2.00 mm | +| Handle clearance | lid hole over handle radius, 2–10 mm | 5.00 mm | +| Plunge stroke | ≥ 400 mm | 513.8 mm | + +Real-world size: 0.34 m across the foot, 0.75 m to the rim and 1.05 m to +the top of the handle. It is a farmhouse plunge churn. + +## Construction + +- **Staves.** Sixteen staves are lofted on a straight taper (`R_BOT` 170 mm + to `R_TOP` 120 mm), with a gap of `STAVE_GAP` between neighbours. + - Each stave's section has four vertices across its width at fractions + 0, ¼, ¾ and 1, outer face over inner face, and quads close both ends. + - Ring heights are a uniform run plus both edges of every hoop and of + the croze, so a hoop's edge and the bottom's faces meet stave + vertices. + - Each stave's foot and top are cut sloping inward (`END_CANT`, doubled + on alternate staves), so the churn stands on its outer edges. + - Every real edge is chamfered at 1.5 mm; the few-degree edges across a + stave's width are left alone. +- **Hoops.** Each hoop is a banded iron section: flat inner face, + chamfered outer edges. It is sampled at every stave's two interior + vertex angles, so every hoop vertex lies radially over a stave vertex at + the same height. The inner face is `HOOP_BITE` inside the stave's outer + face, read from the same taper; the outer face is `HOOP_PROUD` outside + it. +- **Bottom.** A 48-gon disk sized to the inner wall plus `CROZE`, cut + across X into three boards with a named seam (Sutherland–Hodgman clip). + Caps are chamfered as n-gons and then triangulated. +- **Lid.** Two half-annulus boards with the seam across the hole. The + hole is `HOLE_CLEAR` wider than the handle. The lid rests `LID_SEAT` on + the stave tops and overhangs by `LID_OVER`. +- **Dasher.** Two crossed maple slats, the second a step higher. The + handle's foot is driven `HANDLE_BITE` into them. The handle is a + 12-segment lathe with rings at both faces of the lid, so its clearance + is measured where it passes, and it ends in a swelled grip. + +## Findings the budgets forced + +- **Neighbouring ends in one plane.** The first build had 240 coplanar + cross-shell pairs: + - adjacent stave feet and tops; + - the two lid boards; + - the bottom boards' faces and a rim chord the seams split. + + The fixes: + - stave ends are canted inward, doubled on alternate staves (at one + cant, neighbours 5.6° apart in bearing still matched as one plane); + - one lid board stands 0.6 mm proud; + - the middle bottom board steps up and in by 0.6 mm. + + The count is 0. +- **A falsifier stolen by the collider.** `--float-hoops` exited 11 on + the collider ceiling (242 against 240) instead of 18. The hoops stand + 5 mm proud and add nothing a character could hit, so they were taken + out of the body hull rather than the ceiling raised. The collider is + now 178 triangles, and the falsifier exits 18. + +## Conventions walked + +Every convention in `showcase/README.md`, and whether it applies here. + +| Convention | Applies | How | +| --- | --- | --- | +| Deterministic, budgets declared, assertions recompute | yes | no RNG; every value above is read off the mesh | +| Falsifier fails the budget it targets | yes | table below, proven on all three binaries | +| Hygiene incl. cross-shell coplanar | yes | exit 15; canted stave ends and stepped boards keep it at 0 | +| Named supports | yes | all sixteen staves (`--short-stave`) | +| Seat conformance, sampled per segment | yes | every hoop vertex against the stave vertex under it (`--float-hoops`) | +| Bands on a curved host are built on the host's arc | yes | hoop vertices at the staves' own angles | +| A band wraps its host, never sunk into it | yes | inner face bites, outer face asserted proud | +| A head or bottom is boards, not a slab | yes | three bottom boards with a banded seam (`--one-piece-bottom`); the lid is two boards | +| A vessel holds its contents | n/a | the churn shows no contents | +| A joint bites; touching is not joining | yes | handle into the slats (`--short-handle`) | +| Carried parts bite their bearers | yes | lid on the stave tops (`--float-lid`) | +| What passes through a part must clear its mount | yes | handle through the lid's hole (`--tight-hole`) | +| Identical boards read as CG | yes | per-stave and per-board `PlankTone`, grain along each piece's longest extent | +| Hoops are forged iron, not bright | yes | near-black and rust, roughness 0.55–0.85, metallic 0.65 | +| Shading is part of the model | yes | staves smooth across their width with every edge over 35° hard, so they read as coopered boards; handle smooth (turned) | +| One substance, one slot | yes | oak, maple, iron | +| Chamfer n-gon caps, then triangulate | yes | bottom and lid boards | +| Sort bmesh operator inputs | yes | bevel edges sorted by index | +| Level on the stage; stage 60 m | yes | turned about Z only; 60 m floor and wall | +| Keep a falsifier's envelope still | yes | every falsifier leaves the AABB unchanged | +| Rope, masonry, roofs, rings, scatter, mirrored assemblies | no | the piece has none of these | + +## Falsifiers + +Each breaks one pipeline stage so a **named** budget fails. All ten were +run on 4.5.11, 5.1.2 and 5.2.1 and exited the same declared code on all +three. + +| Flag | Target budget | Breaks | Exit | +| --- | --- | --- | --- | +| `--skip-decimate` | LOD1 ratio | drops the DECIMATE modifiers, LOD1 ratio goes to 1.0000 | 9 | +| `--stray-vert` | mesh hygiene | adds one loose vertex inside the body | 15 | +| `--lift-z` | grounded zmin | lifts the whole mesh 50 mm | 16 | +| `--short-stave` | named staves | stops one stave's foot 6 mm above the floor; the rest ground the AABB | 16 | +| `--one-piece-bottom` | bottom boards | one disk instead of three boards | 17 | +| `--short-handle` | handle bite | starts the handle 5 mm above the slats; −5.0 mm | 17 | +| `--float-hoops` | hoop seat | builds every hoop 4 mm off the staves; −3.5 mm | 18 | +| `--float-lid` | lid seat | lifts the lid 5 mm; −3.6 to −3.0 mm | 18 | +| `--tight-hole` | handle clearance | cuts the hole 2 mm inside the handle; −2.0 mm | 18 | +| `--wide-dasher` | plunge stroke | widens the slats to 125 mm; 140.4 mm | 20 | + +## 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. + +| Code | Meaning | +| --- | --- | +| 0 | Success | +| 1 | Uncaught exception (FATAL wrapper) | +| 2 | argparse / usage | +| 3 | Mesh did not build, or has no UV layer | +| 4 | Base triangle count outside band | +| 5 | Material slots, or a material's face floor | +| 6 | UVs outside 0..1 | +| 7 | UV AABB overlap above tolerance | +| 8 | Outer AABB off declared size | +| 9 | LOD1 or LOD2 ratio outside band (`--skip-decimate`) | +| 10 | Framing gate (`examples/gallery_framing.py`, render path only) | +| 11 | Collider triangles above ceiling | +| 12 | Normal bake failed or produced no image data | +| 13 | glTF export missing or empty | +| 14 | `--output` produced no file | +| 15 | Mesh hygiene (`--stray-vert`) | +| 16 | Grounded zmin, or a stave floating (`--lift-z`, `--short-stave`) | +| 17 | Bottom boards or handle bite (`--one-piece-bottom`, `--short-handle`) | +| 18 | Hoop seat, lid seat or handle clearance (`--float-hoops`, `--float-lid`, `--tight-hole`) | +| 20 | Plunge stroke below floor (`--wide-dasher`) | + +## Run it + +```bash +# Budget check, no render. ~1.8 s on 4.5 and 5.2. +blender --background --python butter_churn.py -- + +# Falsifier: the plunger jams partway up the narrowing body. Must exit 20. +blender --background --python butter_churn.py -- --wide-dasher + +# Falsifier: the lid's hole is narrower than the handle. Must exit 18. +blender --background --python butter_churn.py -- --tight-hole + +# Render the gallery still (EEVEE; --engine cycles on a GPU-less host). +blender --background --python butter_churn.py -- --output butter_churn.webp +``` + +Smoke runs the check-only path. It does not pass `--output` or any falsifier. + +## Cross-version measurements + +| Value | 4.5.11 | 5.1.2 | 5.2.1 | +| --- | --- | --- | --- | +| Base triangles | 5684 | 5684 | 5684 | +| LOD1 / LOD2 tris | 2842 / 1250 | same | same | +| Face counts (oak / maple / iron) | 2240 / 160 / 576 | same | same | +| Outer AABB | 0.3401 × 0.3401 × 1.0500 | same | same | +| Collider tris | 178 | 178 | 178 | +| Plunge stroke / reach | 513.8 mm / 100.6 mm | same | same | +| glTF bytes | 239804 | 239804 | 239796 | diff --git a/showcase/butter-churn/butter_churn.py b/showcase/butter-churn/butter_churn.py new file mode 100644 index 00000000..c2ac7e07 --- /dev/null +++ b/showcase/butter-churn/butter_churn.py @@ -0,0 +1,1272 @@ +"""Game-ready butter churn — a showcase piece, not an example. + +Asserts budget conformance of a procedural plunge churn: a tall staved +body that narrows toward the top, three iron hoops, a bottom of three +boards set in a croze, a lid of two boards with a hole for the handle, +and a cross dasher whose handle runs up through the lid. Carried through +UVs, three materials (oak, maple, iron), a high-to-low normal bake, an +LOD chain, a compound convex collider, and a Unity glTF export. + +The budget that matters here is the one a churn fails invisibly: the +dasher has to plunge. The body narrows toward the top, so a plunger that +clears the staves at rest can jam a hand's width up the stroke. It still +sits inside the body without touching it, the handle still clears the lid +and the bounding box does not move; only the stroke knows. The piece +reads the inner wall off the staves and the plunger's reach off the +dasher, and asserts how far the plunger can travel before it would meet +the wall or the lid. + +Budgets are declared below and recomputed from the generated result. +They are not API-contract witnesses. Each falsifier violates one named +budget: ``--skip-decimate`` the LOD-ratio band, ``--stray-vert`` mesh +hygiene, ``--lift-z`` grounded zmin, ``--short-stave`` the named staves, +``--one-piece-bottom`` the bottom boards, ``--short-handle`` the handle +bite, ``--float-hoops`` the hoop seat, ``--float-lid`` the lid seat, +``--tight-hole`` the handle clearance, ``--wide-dasher`` the stroke. + +No randomness: every stave's tone is a closed-form term of its index. +DECIMATE COLLAPSE triangle counts are not byte-identical across Blender +versions — the LOD gate is a ratio band. + + blender --background --python butter_churn.py -- + blender --background --python butter_churn.py -- --wide-dasher + blender --background --python butter_churn.py -- --output butter_churn.png +""" +import argparse +import math +import os +import sys +import tempfile +import traceback + +import bmesh +import bpy +from mathutils import Matrix, Vector +from mathutils.kdtree import KDTree + +_REPO = os.path.abspath( + os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir, os.pardir) +) +sys.path.insert(0, os.path.join(_REPO, "examples")) +sys.dont_write_bytecode = True +import gallery_framing # noqa: E402 + +# The body: sixteen staves on a straight taper, wider at the foot. +HEIGHT = 0.750 +R_BOT = 0.170 +R_TOP = 0.120 +N_STAVES = 16 +STAVE_T = 0.018 +STAVE_GAP = 0.0008 +STAVE_FRACS = (0.0, 0.25, 0.75, 1.0) +BODY_RINGS = 6 +CHAMFER = 0.0015 +SHORT_STAVE = 0.006 +# Each stave's foot and top are cut sloping inward, so the churn stands on +# its outer edges. Alternate staves take a double cant: at one cant, two +# neighbours' end faces are only 5.6 degrees apart in bearing and still +# match as one plane. +END_CANT = 0.0015 + +# Hoops: banded iron sampled at each stave's interior vertices, so every +# hoop vertex sits radially over a stave vertex at the same height. +HOOP_ZS = (0.060, 0.360, 0.655) +HOOP_H = 0.024 +HOOP_BITE = 0.0025 +HOOP_PROUD = 0.005 +HOOP_CH = 0.0015 +FLOAT_HOOP = 0.004 + +# Bottom: three boards in a croze cut into the staves' inner face. +BOTTOM_Z = 0.012 +BOTTOM_T = 0.022 +CROZE = 0.0035 +N_BOARDS = 3 +BOARD_SEAM = 0.0012 +DISK_SEG = 48 +BOARD_STEP = 0.0006 + +# Lid: two boards resting on the stave tops, a hole for the handle. +LID_T = 0.022 +LID_SEAT = 0.002 +LID_OVER = 0.008 +LID_SEAM = 0.0012 +HOLE_CLEAR = 0.005 +TIGHT_HOLE = -0.002 +FLOAT_LID = 0.005 +LID_ARC = 24 +LID_STEP = 0.0006 + +# Dasher: a round maple handle through the lid, two crossed slats below. +HANDLE_R = 0.016 +HANDLE_TOP = 1.050 +HANDLE_BITE = 0.014 +SHORT_HANDLE = -0.005 +PLUNGER_Z = BOTTOM_Z + BOTTOM_T + 0.050 +SLAT_REACH = 0.100 +WIDE_REACH = 0.125 +SLAT_W = 0.024 +SLAT_T = 0.020 +SLAT_STEP = 0.004 +WALL_CLEAR = 0.010 + +BBOX_TOL = 0.020 +OUTER_SIZE = (0.340, 0.340, 1.050) + +BASE_TRIS_MIN = 5000 +BASE_TRIS_MAX = 6500 +LOD1_RATIO_MIN = 0.32 +LOD1_RATIO_MAX = 0.62 +LOD2_RATIO_MIN = 0.10 +LOD2_RATIO_MAX = 0.35 +LOD1_TARGET = 0.50 +LOD2_TARGET = 0.22 +MATERIAL_COUNT = 3 +FACE_FLOORS = {0: 2000, 1: 140, 2: 500} +UV_EPS = 1e-4 +UV_OVERLAP_MAX = 1e-5 +COLLIDER_TRIS_MAX = 200 +BAKE_RES = 512 +CAGE_EXTRUSION = 0.01 +ZMIN_EPS = 1e-4 +DOUBLES_EPS = 1e-5 +AREA_EPS = 1e-10 +COPLANAR_NORMAL_EPS = 1e-4 +COPLANAR_PLANE_EPS = 1e-4 +COPLANAR_CENTRE_MAX = 0.05 +LIFT_Z = 0.05 +STAVE_Z_MAX = 1e-4 +BOARD_SEAM_MIN = 0.0006 +BOARD_SEAM_MAX = 0.0025 +HANDLE_BITE_MIN = 0.008 +HANDLE_BITE_MAX = 0.020 +HOOP_BITE_MIN = 0.0010 +HOOP_BITE_MAX = 0.0045 +HOOP_PROUD_MIN = 0.0030 +LID_SEAT_MIN = 0.0010 +LID_SEAT_MAX = 0.0040 +HOLE_CLEAR_MIN = 0.002 +HOLE_CLEAR_MAX = 0.010 +STROKE_MIN = 0.400 + +OAK_IDX = 0 +MAPLE_IDX = 1 +IRON_IDX = 2 + + +def eevee_engine_id(): + """EEVEE id: 'BLENDER_EEVEE' on 5.0+, 'BLENDER_EEVEE_NEXT' on 4.2-4.5.""" + return "BLENDER_EEVEE" if bpy.app.version >= (5, 0, 0) else "BLENDER_EEVEE_NEXT" + + +def fail(msg, code): + print(f"FAIL[{code}]: {msg}", file=sys.stderr) + return code + + +def triangle_count(mesh): + mesh.calc_loop_triangles() + return len(mesh.loop_triangles) + + +def evaluated_triangle_count(obj): + deps = bpy.context.evaluated_depsgraph_get() + ev = obj.evaluated_get(deps) + mesh = ev.to_mesh() + try: + mesh.calc_loop_triangles() + return len(mesh.loop_triangles) + finally: + ev.to_mesh_clear() + + +def r_out(z): + return R_BOT + (R_TOP - R_BOT) * z / HEIGHT + + +def r_in(z): + return r_out(z) - STAVE_T + + +def stave_angles(k): + """Angles of stave ``k``'s vertices across its width, gap split either side.""" + span = 2.0 * math.pi / N_STAVES + gap = STAVE_GAP / R_TOP + a0 = k * span + gap * 0.5 + width = span - gap + return [a0 + width * f for f in STAVE_FRACS] + + +def ring_zs(): + """Stave ring heights: a uniform run plus both edges of every hoop and the croze.""" + zs = {round(HEIGHT * k / BODY_RINGS, 6) for k in range(BODY_RINGS + 1)} + for z in HOOP_ZS: + zs |= {round(z, 6), round(z + HOOP_H, 6)} + zs |= {round(BOTTOM_Z, 6), round(BOTTOM_Z + BOTTOM_T, 6)} + return sorted(zs) + + +# --- construction ----------------------------------------------------------- + + +def new_island(ctx): + ctx["next"] += 1 + return ctx["next"] + + +def stamp(ctx, face, island, uvmap): + face[ctx["isl"]] = island + for loop in face.loops: + loop[ctx["uv"]].uv = uvmap[loop.vert] + + +def loft(bm, rings, mat_idx, ctx, closed=True): + """Quads between consecutive rings of equal length; one strip island.""" + island = new_island(ctx) + n = len(rings[0]) + arc = [0.0] + for a, b in zip(rings, rings[1:]): + ca = sum((v.co for v in a), Vector()) / n + cb = sum((v.co for v in b), Vector()) / n + arc.append(arc[-1] + (cb - ca).length) + faces = [] + for k in range(len(rings) - 1): + a, b = rings[k], rings[k + 1] + for i in range(n if closed else n - 1): + j = (i + 1) % n + f = bm.faces.new((a[i], a[j], b[j], b[i])) + f.material_index = mat_idx + stamp(ctx, f, island, {a[i]: (arc[k], i / n), a[j]: (arc[k], (i + 1) / n), + b[j]: (arc[k + 1], (i + 1) / n), b[i]: (arc[k + 1], i / n)}) + faces.append(f) + return faces + + +def add_stave(bm, k, ctx, z0, verts_out): + """One stave: an annular sector on the taper, capped by quads at both ends.""" + angs = stave_angles(k) + rings = [] + for z in ring_zs(): + # ``z0`` lifts only the foot ring, so a short stave stops above the + # floor while its hoop and croze rings stay where the others are. + zz = z if z > 0.0 else z0 + c = END_CANT * (1 + k % 2) + cant = c if z <= 0.0 else (-c if z >= HEIGHT else 0.0) + outer = [Vector((r_out(z) * math.cos(a), r_out(z) * math.sin(a), zz)) for a in angs] + inner = [Vector((r_in(z) * math.cos(a), r_in(z) * math.sin(a), zz + cant)) + for a in reversed(angs)] + rings.append([bm.verts.new(p) for p in outer + inner]) + loft(bm, rings, OAK_IDX, ctx) + m = len(angs) + for ring, flip in ((rings[0], True), (rings[-1], False)): + for i in range(m - 1): + o0, o1 = ring[i], ring[i + 1] + i1, i0 = ring[2 * m - 2 - i], ring[2 * m - 1 - i] + vs = (o0, o1, i1, i0) + f = bm.faces.new(tuple(reversed(vs)) if flip else vs) + f.material_index = OAK_IDX + f[ctx["isl"]] = 0 + for r in rings: + verts_out.extend(r) + + +def add_hoop(bm, z, ctx, float_hoop=False): + """A banded hoop sampled at every stave's interior vertex angles. + + Its inner face sits HOOP_BITE inside the stave's outer face at each + edge height, read from the same taper, so the band follows the staves. + """ + angs = [a for k in range(N_STAVES) for a in stave_angles(k)[1:-1]] + off_in = FLOAT_HOOP if float_hoop else -HOOP_BITE + sec = [(off_in, 0.0), (HOOP_PROUD - HOOP_CH, 0.0), (HOOP_PROUD, HOOP_CH), + (HOOP_PROUD, HOOP_H - HOOP_CH), (HOOP_PROUD - HOOP_CH, HOOP_H), (off_in, HOOP_H)] + cols = [] + for a in angs: + c, s = math.cos(a), math.sin(a) + cols.append([bm.verts.new(((r_out(z + dz) + dr) * c, (r_out(z + dz) + dr) * s, z + dz)) + for dr, dz in sec]) + island = new_island(ctx) + n, m = len(cols), len(sec) + for i in range(n): + a, b = cols[i], cols[(i + 1) % n] + for j in range(m): + jj = (j + 1) % m + f = bm.faces.new((a[j], a[jj], b[jj], b[j])) + f.material_index = IRON_IDX + stamp(ctx, f, island, {a[j]: (i / n, j / m), a[jj]: (i / n, (j + 1) / m), + b[jj]: ((i + 1) / n, (j + 1) / m), b[j]: ((i + 1) / n, j / m)}) + + +def clip_x(poly, x0, x1): + """Clip a convex (x, y) polygon to x0 <= x <= x1 (Sutherland-Hodgman).""" + def cut(pts, keep, xc): + out = [] + for i, p in enumerate(pts): + q = pts[(i + 1) % len(pts)] + pin, qin = keep(p[0]), keep(q[0]) + if pin: + out.append(p) + if pin != qin: + t = (xc - p[0]) / (q[0] - p[0]) + out.append((xc, p[1] + (q[1] - p[1]) * t)) + return out + pts = cut(poly, lambda x: x >= x0, x0) + return cut(pts, lambda x: x <= x1, x1) + + +def extrude_polygon(bm, poly, z0, z1, mat_idx, verts_out): + """A board from an (x, y) outline: two n-gon caps and quad sides.""" + lo = [bm.verts.new((x, y, z0)) for x, y in poly] + hi = [bm.verts.new((x, y, z1)) for x, y in poly] + faces = [bm.faces.new(lo), bm.faces.new(list(reversed(hi)))] + n = len(poly) + for i in range(n): + j = (i + 1) % n + faces.append(bm.faces.new((lo[j], lo[i], hi[i], hi[j]))) + for f in faces: + f.material_index = mat_idx + verts_out.extend(lo + hi) + + +def add_bottom(bm, one_piece, verts_out): + zm = BOTTOM_Z + BOTTOM_T * 0.5 + rr = r_in(zm) + CROZE + disk = [(rr * math.cos(2 * math.pi * i / DISK_SEG), rr * math.sin(2 * math.pi * i / DISK_SEG)) + for i in range(DISK_SEG)] + if one_piece: + extrude_polygon(bm, disk, BOTTOM_Z, BOTTOM_Z + BOTTOM_T, OAK_IDX, verts_out) + return + w = (2.0 * rr - BOARD_SEAM * (N_BOARDS - 1)) / N_BOARDS + for k in range(N_BOARDS): + x0 = -rr + k * (w + BOARD_SEAM) + # Alternate boards step up and in by BOARD_STEP: level with their + # neighbours, their faces and the rim chord a seam splits would each + # be one plane shared by two boards. + step = BOARD_STEP if k % 2 else 0.0 + src = [(x * (rr - step) / rr, y * (rr - step) / rr) for x, y in disk] + poly = clip_x(src, x0 - (1.0 if k == 0 else 0.0), x0 + w + (1.0 if k == N_BOARDS - 1 else 0.0)) + extrude_polygon(bm, poly, BOTTOM_Z + step, BOTTOM_Z + BOTTOM_T + step, OAK_IDX, verts_out) + + +def add_lid(bm, hole_r, lift, verts_out): + """Two half-annulus boards, seam across the hole, resting on the stave tops.""" + ro = r_out(HEIGHT) + LID_OVER + z0 = HEIGHT - LID_SEAT + lift + s = LID_SEAM * 0.5 + t_o = math.acos(s / ro) + t_i = math.acos(s / hole_r) + for side in (1.0, -1.0): + outer = [(ro * math.cos(-t_o + 2 * t_o * k / LID_ARC), ro * math.sin(-t_o + 2 * t_o * k / LID_ARC)) + for k in range(LID_ARC + 1)] + inner = [(hole_r * math.cos(t_i - 2 * t_i * k / 8), hole_r * math.sin(t_i - 2 * t_i * k / 8)) + for k in range(9)] + poly = [(side * x, y) for x, y in outer + inner] + if side < 0: + poly.reverse() + # One board a step proud of the other, so the two do not share a face plane. + step = LID_STEP if side < 0 else 0.0 + extrude_polygon(bm, poly, z0 + step, z0 + step + LID_T, OAK_IDX, verts_out) + + +def lathe_z(bm, profile, n, mat_idx, ctx, base): + """Revolve an (r, z) profile about the vertical axis through ``base``.""" + rings, poles = [], [] + for p in profile: + if p.x <= 0.0: + poles.append(bm.verts.new(base + Vector((0.0, 0.0, p.y)))) + else: + rings.append([bm.verts.new(base + Vector((p.x * math.cos(2 * math.pi * k / n), + p.x * math.sin(2 * math.pi * k / n), p.y))) + for k in range(n)]) + loft(bm, rings, mat_idx, ctx) + island = new_island(ctx) + for pole, ring, flip in ((poles[0], rings[0], True), (poles[1], rings[-1], False)): + for i in range(n): + j = (i + 1) % n + vs = (pole, ring[j], ring[i]) if flip else (pole, ring[i], ring[j]) + f = bm.faces.new(vs) + f.material_index = mat_idx + stamp(ctx, f, island, {pole: (0.5 if flip else 1.5, (i + 0.5) / n), + ring[i]: (0.0 if flip else 1.0, i / n), + ring[j]: (0.0 if flip else 1.0, (i + 1) / n)}) + + +def handle_profile(z_start, lid_z0): + """(r, z) from the handle's foot, with rings at both faces of the lid.""" + r = HANDLE_R + top = HANDLE_TOP - z_start + rings = [(r * 0.85, 0.0), (r, 0.004), (r, lid_z0 - z_start), (r, lid_z0 + LID_T - z_start), + (r, top - 0.060), (r * 1.25, top - 0.035), (r * 1.35, top - 0.018), (r * 1.05, top)] + return [Vector((0.0, 0.0))] + [Vector(p) for p in rings] + [Vector((0.0, top))] + + +def build_churn_mesh( + name, + stray_vert=False, + short_stave=False, + one_piece_bottom=False, + short_handle=False, + float_hoops=False, + float_lid=False, + tight_hole=False, + wide_dasher=False, +): + bm = bmesh.new() + try: + ctx = {"uv": bm.loops.layers.uv.new("UVMap"), + "isl": bm.faces.layers.int.new("UVIsland"), "next": 0} + wood = [] + for k in range(N_STAVES): + add_stave(bm, k, ctx, SHORT_STAVE if (short_stave and k == 0) else 0.0, wood) + add_bottom(bm, one_piece_bottom, wood) + hole_r = HANDLE_R + (TIGHT_HOLE if tight_hole else HOLE_CLEAR) + lid_lift = FLOAT_LID if float_lid else 0.0 + add_lid(bm, hole_r, lid_lift, wood) + # Dasher: two crossed slats, the second a step higher so no two of + # their faces share a plane, and the handle's foot biting both. + reach = WIDE_REACH if wide_dasher else SLAT_REACH + maple = [] + extrude_polygon(bm, [(-reach, -SLAT_W / 2), (reach, -SLAT_W / 2), (reach, SLAT_W / 2), (-reach, SLAT_W / 2)], + PLUNGER_Z, PLUNGER_Z + SLAT_T, MAPLE_IDX, maple) + extrude_polygon(bm, [(-SLAT_W / 2, -reach), (SLAT_W / 2, -reach), (SLAT_W / 2, reach), (-SLAT_W / 2, reach)], + PLUNGER_Z + SLAT_STEP, PLUNGER_Z + SLAT_STEP + SLAT_T, MAPLE_IDX, maple) + # Real edges only (a stave's width and a disk's rim meet at a few + # degrees), sorted by index, each pass pinned to its own material. + for verts, mat_idx in ((wood, OAK_IDX), (maple, MAPLE_IDX)): + bm.edges.index_update() + edges = sorted({e for v in verts if v.is_valid for e in v.link_edges + if e.calc_face_angle(0.0) > math.radians(20.0)}, + key=lambda e: e.index) + bmesh.ops.bevel(bm, geom=edges, offset=CHAMFER, segments=1, profile=0.5, + affect="EDGES", clamp_overlap=True, material=mat_idx) + bmesh.ops.triangulate(bm, faces=[f for f in bm.faces if len(f.verts) > 4]) + for z in HOOP_ZS: + add_hoop(bm, z, ctx, float_hoop=float_hoops) + z_start = PLUNGER_Z + SLAT_STEP + SLAT_T - (SHORT_HANDLE if short_handle else HANDLE_BITE) + lathe_z(bm, handle_profile(z_start, HEIGHT - LID_SEAT + lid_lift), 12, MAPLE_IDX, ctx, + Vector((0.0, 0.0, z_start))) + if stray_vert: + bm.verts.new((0.0, 0.0, 0.3)) + bmesh.ops.recalc_face_normals(bm, faces=list(bm.faces)) + for f in bm.faces: + f.smooth = True + for e in bm.edges: + if len(e.link_faces) == 2 and e.calc_face_angle(0.0) > math.radians(35.0): + e.smooth = False + pack_uvs(bm, ctx) + bm.faces.layers.int.remove(ctx["isl"]) + me = bpy.data.meshes.new(name) + bm.to_mesh(me) + me.update() + finally: + bm.free() + paint_pieces(me) + obj = bpy.data.objects.new(name, me) + bpy.context.collection.objects.link(obj) + return obj + + +def pack_uvs(bm, ctx, margin=0.06): + """One grid cell per UV island: strip islands by their layer tag, else a face each.""" + uv, isl = ctx["uv"], ctx["isl"] + bm.faces.index_update() + islands, order = {}, [] + for face in bm.faces: + key = ("s", face[isl]) if face[isl] else ("f", face.index) + if key not in islands: + islands[key] = [] + order.append(key) + islands[key].append(face) + cols = max(1, math.ceil(math.sqrt(len(order)))) + rows = max(1, math.ceil(len(order) / cols)) + cw, ch = 1.0 / cols, 1.0 / rows + pu, pv = margin * cw * 0.5, margin * ch * 0.5 + for idx, key in enumerate(order): + faces = islands[key] + coords = {} + for face in faces: + if face[isl]: + coords[face.index] = [tuple(loop[uv].uv) for loop in face.loops] + continue + nrm = face.normal + ax, ay, az = abs(nrm.x), abs(nrm.y), abs(nrm.z) + pts = [] + for loop in face.loops: + co = loop.vert.co + if az >= ax and az >= ay: + pts.append((co.x, co.y)) + elif ax >= ay: + pts.append((co.y, co.z)) + else: + pts.append((co.x, co.z)) + coords[face.index] = pts + allc = [c for cs in coords.values() for c in cs] + minx, maxx = min(c[0] for c in allc), max(c[0] for c in allc) + miny, maxy = min(c[1] for c in allc), max(c[1] for c in allc) + dx, dy = max(maxx - minx, 1e-8), max(maxy - miny, 1e-8) + ou, ov = (idx % cols) * cw + pu, (idx // cols) * ch + pv + for face in faces: + for loop, (x, y) in zip(face.loops, coords[face.index]): + loop[uv].uv = (ou + (x - minx) / dx * (cw - 2 * pu), + ov + (y - miny) / dy * (ch - 2 * pv)) + + +def paint_pieces(me): + """Per-piece ``PlankTone`` and ``GrainDir`` (each shell's longest extent).""" + npoly = len(me.polygons) + tone = [0.5] * npoly + grain = [(0.0, 0.0, 1.0)] * npoly + vf = [[] for _ in range(len(me.vertices))] + for p in me.polygons: + for i in p.vertices: + vf[i].append(p.index) + for k, g in enumerate(shells(me)): + pts = [me.vertices[i].co for i in g] + ext = [max(p[a] for p in pts) - min(p[a] for p in pts) for a in range(3)] + axis = ext.index(max(ext)) + d = tuple(1.0 if a == axis else 0.0 for a in range(3)) + t = 0.5 + 0.34 * (((k * 0.6180339887 + 0.3) % 1.0) - 0.5) + for fi in {fi for i in g for fi in vf[i]}: + tone[fi] = t + grain[fi] = d + a = me.attributes.new("PlankTone", "FLOAT", "FACE") + a.data.foreach_set("value", tone) + b = me.attributes.new("GrainDir", "FLOAT_VECTOR", "FACE") + b.data.foreach_set("vector", [c for v in grain for c in v]) + + +# --- surface ---------------------------------------------------------------- + + +def _sock(sockets, identifier): + return next(sk for sk in sockets if sk.identifier == identifier) + + +def wood_material(name, dark, light, rough=(0.72, 0.52)): + """Timber whose grain runs along ``GrainDir`` and whose tone varies by piece.""" + mat = bpy.data.materials.new(name) + mat.use_nodes = True + nt = mat.node_tree + bsdf = nt.nodes["Principled BSDF"] + coord = nt.nodes.new("ShaderNodeTexCoord") + gdir = nt.nodes.new("ShaderNodeAttribute") + gdir.attribute_name = "GrainDir" + tone = nt.nodes.new("ShaderNodeAttribute") + tone.attribute_name = "PlankTone" + dot = nt.nodes.new("ShaderNodeVectorMath") + dot.operation = "DOT_PRODUCT" + nt.links.new(coord.outputs["Object"], dot.inputs[0]) + nt.links.new(gdir.outputs["Vector"], dot.inputs[1]) + squash = nt.nodes.new("ShaderNodeMath") + squash.operation = "MULTIPLY" + squash.inputs[1].default_value = 0.94 + nt.links.new(dot.outputs["Value"], squash.inputs[0]) + along = nt.nodes.new("ShaderNodeVectorMath") + along.operation = "SCALE" + nt.links.new(gdir.outputs["Vector"], along.inputs[0]) + nt.links.new(squash.outputs["Value"], along.inputs["Scale"]) + grain_co = nt.nodes.new("ShaderNodeVectorMath") + grain_co.operation = "SUBTRACT" + nt.links.new(coord.outputs["Object"], grain_co.inputs[0]) + nt.links.new(along.outputs["Vector"], grain_co.inputs[1]) + shift = nt.nodes.new("ShaderNodeVectorMath") + shift.operation = "ADD" + nt.links.new(grain_co.outputs["Vector"], shift.inputs[0]) + nt.links.new(tone.outputs["Fac"], shift.inputs[1]) + noise = nt.nodes.new("ShaderNodeTexNoise") + noise.inputs["Scale"].default_value = 34.0 + noise.inputs["Detail"].default_value = 6.0 + noise.inputs["Roughness"].default_value = 0.62 + nt.links.new(shift.outputs["Vector"], noise.inputs["Vector"]) + ramp = nt.nodes.new("ShaderNodeValToRGB") + ramp.color_ramp.elements[0].position = 0.30 + ramp.color_ramp.elements[0].color = (*dark, 1.0) + ramp.color_ramp.elements[1].position = 0.72 + ramp.color_ramp.elements[1].color = (*light, 1.0) + nt.links.new(noise.outputs["Fac"], ramp.inputs["Fac"]) + gain = nt.nodes.new("ShaderNodeMath") + gain.operation = "MULTIPLY_ADD" + gain.inputs[1].default_value = 1.2 + gain.inputs[2].default_value = 0.40 + nt.links.new(tone.outputs["Fac"], gain.inputs[0]) + mix = nt.nodes.new("ShaderNodeMix") + mix.data_type = "RGBA" + mix.blend_type = "MULTIPLY" + _sock(mix.inputs, "Factor_Float").default_value = 1.0 + nt.links.new(ramp.outputs["Color"], _sock(mix.inputs, "A_Color")) + nt.links.new(gain.outputs["Value"], _sock(mix.inputs, "B_Color")) + nt.links.new(_sock(mix.outputs, "Result_Color"), bsdf.inputs["Base Color"]) + rmap = nt.nodes.new("ShaderNodeMapRange") + rmap.inputs["To Min"].default_value = rough[0] + rmap.inputs["To Max"].default_value = rough[1] + nt.links.new(noise.outputs["Fac"], rmap.inputs["Value"]) + nt.links.new(rmap.outputs["Result"], bsdf.inputs["Roughness"]) + return mat + + +def iron_material(name): + """Forged iron: near-black, rough, rusted in patches. Not chrome.""" + mat = bpy.data.materials.new(name) + mat.use_nodes = True + nt = mat.node_tree + bsdf = nt.nodes["Principled BSDF"] + tc = nt.nodes.new("ShaderNodeTexCoord") + noise = nt.nodes.new("ShaderNodeTexNoise") + noise.inputs["Scale"].default_value = 40.0 + noise.inputs["Detail"].default_value = 8.0 + nt.links.new(tc.outputs["Object"], noise.inputs["Vector"]) + ramp = nt.nodes.new("ShaderNodeValToRGB") + ramp.color_ramp.elements[0].position = 0.45 + ramp.color_ramp.elements[0].color = (0.035, 0.033, 0.031, 1.0) + ramp.color_ramp.elements[1].position = 0.78 + ramp.color_ramp.elements[1].color = (0.20, 0.085, 0.035, 1.0) + nt.links.new(noise.outputs["Fac"], ramp.inputs["Fac"]) + nt.links.new(ramp.outputs["Color"], bsdf.inputs["Base Color"]) + bsdf.inputs["Metallic"].default_value = 0.65 + rough = nt.nodes.new("ShaderNodeMapRange") + rough.inputs["To Min"].default_value = 0.55 + rough.inputs["To Max"].default_value = 0.85 + nt.links.new(noise.outputs["Fac"], rough.inputs["Value"]) + nt.links.new(rough.outputs["Result"], bsdf.inputs["Roughness"]) + return mat + + +def churn_materials(): + return ( + wood_material("ChurnOak", (0.085, 0.040, 0.016), (0.28, 0.14, 0.060)), + wood_material("ChurnMaple", (0.26, 0.17, 0.09), (0.55, 0.40, 0.24), rough=(0.62, 0.45)), + iron_material("ChurnIron"), + ) + + +def assign_slots(obj, mats): + slots = obj.data.materials + for i, mat in enumerate(mats): + if i < len(slots): + slots[i] = mat + else: + slots.append(mat) + + +# --- measurement ------------------------------------------------------------ + + +def world_bbox(obj): + corners = [obj.matrix_world @ Vector(c) for c in obj.bound_box] + xs, ys, zs = [c.x for c in corners], [c.y for c in corners], [c.z for c in corners] + return (min(xs), min(ys), min(zs), max(xs), max(ys), max(zs)) + + +def uv_stats(mesh): + uv = mesh.uv_layers.active + if uv is None: + return 0.0, 0.0, 1.0, 1.0, 0.0, 0 + data = uv.data + us = [loop.uv[0] for loop in data] + vs = [loop.uv[1] for loop in data] + aabbs = [] + for poly in mesh.polygons: + pu = [data[i].uv[0] for i in poly.loop_indices] + pv = [data[i].uv[1] for i in poly.loop_indices] + aabbs.append((min(pu), min(pv), max(pu), max(pv))) + span = max(1e-6, max(a[2] - a[0] for a in aabbs), max(a[3] - a[1] for a in aabbs)) + buckets = {} + for i, a in enumerate(aabbs): + for c in range(int(a[0] // span), int(a[2] // span) + 1): + for r in range(int(a[1] // span), int(a[3] // span) + 1): + buckets.setdefault((c, r), []).append(i) + overlap = 0.0 + seen = set() + for members in buckets.values(): + for ii in range(len(members)): + for jj in range(ii + 1, len(members)): + i, j = members[ii], members[jj] + key = (i, j) if i < j else (j, i) + if key in seen: + continue + seen.add(key) + a, b = aabbs[i], aabbs[j] + overlap += max(0.0, min(a[2], b[2]) - max(a[0], b[0])) * max( + 0.0, min(a[3], b[3]) - max(a[1], b[1])) + return min(us), min(vs), max(us), max(vs), overlap, len(aabbs) + + +def face_area(me, poly): + idxs = poly.vertices + v0 = me.vertices[idxs[0]].co + area = 0.0 + for i in range(1, len(idxs) - 1): + area += (me.vertices[idxs[i]].co - v0).cross(me.vertices[idxs[i + 1]].co - v0).length * 0.5 + return area + + +def hygiene_audit(me): + ngons = sum(1 for p in me.polygons if len(p.vertices) > 4) + zero_area = sum(1 for p in me.polygons if face_area(me, p) <= AREA_EPS) + bm = bmesh.new() + try: + bm.from_mesh(me) + loose_v = sum(1 for v in bm.verts if len(v.link_edges) == 0) + loose_e = sum(1 for e in bm.edges if len(e.link_faces) == 0) + nonman = sum(1 for e in bm.edges if not e.is_manifold) + ret = bmesh.ops.find_doubles(bm, verts=list(bm.verts), dist=DOUBLES_EPS) + doubles = len(ret.get("targetmap") or {}) + finally: + bm.free() + return {"ngons": ngons, "loose_v": loose_v, "loose_e": loose_e, + "nonman": nonman, "zero_area": zero_area, "doubles": doubles} + + +def shells(me): + neighbors = [[] for _ in range(len(me.vertices))] + for edge in me.edges: + a, b = edge.vertices + neighbors[a].append(b) + neighbors[b].append(a) + seen = [False] * len(me.vertices) + groups = [] + for start in range(len(me.vertices)): + if seen[start]: + continue + seen[start] = True + stack = [start] + group = [] + while stack: + cur = stack.pop() + group.append(cur) + for nxt in neighbors[cur]: + if not seen[nxt]: + seen[nxt] = True + stack.append(nxt) + groups.append(group) + return groups + + +def zfight_pairs(me): + """Coplanar face pairs from *different shells* (copied from showcase/grindstone).""" + owner = {} + for si, g in enumerate(shells(me)): + for vi in g: + owner[vi] = si + faces = [(p.normal.copy(), p.center.copy(), owner.get(p.vertices[0], -1)) + for p in me.polygons] + kd = KDTree(len(faces)) + for i, (_n, c, _s) in enumerate(faces): + kd.insert(c, i) + kd.balance() + hits = 0 + for i, (ni, ci, si) in enumerate(faces): + for _co, j, _d in kd.find_range(ci, COPLANAR_CENTRE_MAX): + if j <= i: + continue + nj, cj, sj = faces[j] + if si == sj: + continue + if abs(abs(ni.dot(nj)) - 1.0) > COPLANAR_NORMAL_EPS: + continue + if abs(ni.dot(cj - ci)) > COPLANAR_PLANE_EPS: + continue + hits += 1 + return hits + + +def classify(me): + mats = {} + for p in me.polygons: + for i in p.vertices: + mats.setdefault(i, p.material_index) + out = {"stave": [], "board": [], "lid": [], "hoop": [], "slat": [], "handle": [], "other": []} + for g in shells(me): + pts = [me.vertices[i].co.copy() for i in g] + lo = Vector((min(p.x for p in pts), min(p.y for p in pts), min(p.z for p in pts))) + hi = Vector((max(p.x for p in pts), max(p.y for p in pts), max(p.z for p in pts))) + rec = {"g": g, "pts": pts, "lo": lo, "hi": hi, "ext": hi - lo, + "c": sum(pts, Vector()) / len(pts)} + m = mats.get(g[0], -1) + e = rec["ext"] + if m == OAK_IDX: + if e.z > HEIGHT * 0.5: + out["stave"].append(rec) + elif lo.z > HEIGHT * 0.5: + out["lid"].append(rec) + else: + out["board"].append(rec) + elif m == MAPLE_IDX: + out["handle" if e.z > 0.3 else "slat"].append(rec) + elif m == IRON_IDX: + out["hoop"].append(rec) + else: + out["other"].append(rec) + return out + + +def radial(p): + return math.hypot(p.x, p.y) + + +def churn_audit(me): + parts = classify(me) + out = {k: len(v) for k, v in parts.items()} + staves = parts["stave"] + out["stave_z"] = max((r["lo"].z for r in staves), default=99.0) + + # Bottom boards: count and the seams between neighbours. + boards = sorted(parts["board"], key=lambda r: r["c"].x) + seams = [b["lo"].x - a["hi"].x for a, b in zip(boards, boards[1:])] + out["seam"] = (min(seams, default=-99.0), max(seams, default=99.0)) + + # Hoops on the staves: every hoop vertex against the stave vertex it + # was built over, measured radially. + spts = [p for r in staves for p in r["pts"]] + kd = KDTree(len(spts)) + for i, p in enumerate(spts): + kd.insert(p, i) + kd.balance() + bites, prouds = [], [] + for h in parts["hoop"]: + ds = sorted(radial(kd.find(p)[0]) - radial(p) for p in h["pts"]) + n_in = len(ds) // 3 + bites.append(min(ds[-n_in:])) + prouds.append(-max(ds[:n_in])) + out["hoop_bite"] = (min(bites, default=-99.0), max(bites, default=99.0)) + out["hoop_proud"] = min(prouds, default=-99.0) + + # The lid rests on the stave tops; the handle clears the lid's hole. + top = max((r["hi"].z for r in staves), default=0.0) + lids = parts["lid"] + seats = [top - r["lo"].z for r in lids] + out["lid_seat"] = (min(seats, default=-99.0), max(seats, default=99.0)) + out["hole_clear"] = -99.0 + handle = parts["handle"][0] if parts["handle"] else None + if handle and lids: + lz0 = min(r["lo"].z for r in lids) + lz1 = max(r["hi"].z for r in lids) + hr = max((radial(p) for p in handle["pts"] if lz0 - 1e-6 <= p.z <= lz1 + 1e-6), default=99.0) + lr = min(radial(p) for r in lids for p in r["pts"]) + out["hole_clear"] = lr - hr + + # The handle's foot bites the slats. + slats = parts["slat"] + out["handle_bite"] = -99.0 + if handle and slats: + out["handle_bite"] = max(r["hi"].z for r in slats) - handle["lo"].z + + # Stroke: the inner wall read off the staves, ring by ring, against the + # plunger's reach about the handle's axis. + out["stroke"] = -99.0 + if slats and staves: + reach = max(radial(p) for r in slats for p in r["pts"]) + p_top = max(r["hi"].z for r in slats) + walls = {} + for p in spts: + z = round(p.z, 5) + walls[z] = min(walls.get(z, 99.0), radial(p)) + table = sorted(walls.items()) + need = reach + WALL_CLEAR + limit = min((r["lo"].z for r in lids), default=top) + z_ok = None + for (za, ra), (zb, rb) in zip(table, table[1:]): + if za < p_top - 1e-6: + continue + if rb >= need: + continue + if ra >= need: + z_ok = za + (zb - za) * (ra - need) / (ra - rb) + else: + z_ok = za + break + if z_ok is None: + z_ok = limit + out["reach"] = reach + out["stroke"] = min(z_ok, limit) - p_top + return out + + +def make_lod(obj, name, ratio, skip_decimate): + mesh = obj.data.copy() + lod = bpy.data.objects.new(name, mesh) + lod.matrix_world = obj.matrix_world.copy() + bpy.context.scene.collection.objects.link(lod) + if not skip_decimate and 0.0 < ratio < 1.0: + mod = lod.modifiers.new("DecimateBudget", "DECIMATE") + mod.decimate_type = "COLLAPSE" + mod.ratio = ratio + return lod + + +def hull_collider(obj, name): + """Compound collider: one hull for the staves and lid, one for the handle above it. + + The hoops stand 5 mm proud of the staves and are left out: in the hull + they add triangles and nothing a character could collide with. + """ + me = obj.data + parts = classify(me) + body = [p for k in ("stave", "lid") for r in parts[k] for p in r["pts"]] + body = [p for i, p in enumerate(body) if i % 3 == 0] + groups = [body] + if parts["handle"]: + top = max(p.z for r in parts["lid"] for p in r["pts"]) if parts["lid"] else HEIGHT + groups.append([p for p in parts["handle"][0]["pts"] if p.z >= top - 0.01]) + mesh = bpy.data.meshes.new(name) + bm = bmesh.new() + try: + for pts in groups: + tmp = bmesh.new() + try: + vs = [tmp.verts.new(p) for p in pts] + bmesh.ops.convex_hull(tmp, input=vs) + bmesh.ops.dissolve_limit(tmp, angle_limit=math.radians(4.0), + verts=list(tmp.verts), edges=list(tmp.edges)) + bmesh.ops.triangulate(tmp, faces=list(tmp.faces)) + remap = {} + for f in tmp.faces: + for v in f.verts: + if v not in remap: + remap[v] = bm.verts.new(v.co) + bm.faces.new([remap[v] for v in f.verts]) + finally: + tmp.free() + bm.to_mesh(mesh) + mesh.update() + finally: + bm.free() + col = bpy.data.objects.new(name, mesh) + bpy.context.collection.objects.link(col) + return col + + +def setup_bake_image(obj, target_mat, size): + img = bpy.data.images.new("ChurnNrm", size, size, alpha=True, float_buffer=False) + img.colorspace_settings.name = "Non-Color" + nodes = target_mat.node_tree.nodes + tex = nodes.new("ShaderNodeTexImage") + tex.image = img + nodes.active = tex + tex.select = True + obj.active_material_index = OAK_IDX + return img, tex + + +def bake_normal(high, low): + scene = bpy.context.scene + scene.render.engine = "CYCLES" + scene.cycles.device = "CPU" + scene.cycles.samples = 1 + scene.cycles.use_denoising = False + for ob in bpy.context.view_layer.objects: + ob.select_set(False) + high.select_set(True) + low.select_set(True) + bpy.context.view_layer.objects.active = low + return bpy.ops.object.bake( + type="NORMAL", use_selected_to_active=True, cage_extrusion=CAGE_EXTRUSION, + use_cage=False, normal_space="TANGENT", margin=4, + margin_type="ADJACENT_FACES", use_clear=True, target="IMAGE_TEXTURES", + ) + + +def export_unity(path, objects): + for ob in bpy.context.view_layer.objects: + ob.select_set(False) + for ob in objects: + ob.select_set(True) + bpy.context.view_layer.objects.active = objects[0] + bpy.ops.export_scene.gltf( + filepath=path, use_selection=True, export_yup=True, export_apply=True, + export_draco_mesh_compression_enable=False, export_animations=False, + ) + + +def check(skip_decimate, lift_z=False, **flags): + bpy.ops.wm.read_factory_settings(use_empty=True) + nothing = (None,) * 5 + low = build_churn_mesh("ChurnLow", **flags) + hi_flags = {k: v for k, v in flags.items() if k != "stray_vert"} + high = build_churn_mesh("ChurnHigh", **hi_flags) + mats = churn_materials() + assign_slots(low, mats) + assign_slots(high, mats) + if lift_z: + for v in low.data.vertices: + v.co.z += LIFT_Z + low.data.update() + bpy.context.view_layer.update() + if len(low.data.polygons) < 6 or not low.data.uv_layers: + return (fail("churn mesh did not build, or has no UV layer", 3),) + nothing + + base_tris = triangle_count(low.data) + slots = [s for s in low.data.materials if s is not None] + nmat, distinct = len(slots), len({id(s) for s in slots}) + idx_counts = {} + for poly in low.data.polygons: + idx_counts[poly.material_index] = idx_counts.get(poly.material_index, 0) + 1 + u0, v0, u1, v1, overlap, nfaces = uv_stats(low.data) + bb = world_bbox(low) + size_x, size_y, size_z = bb[3] - bb[0], bb[4] - bb[1], bb[5] - bb[2] + + img, tex = setup_bake_image(low, mats[OAK_IDX], BAKE_RES) + bake_result = bake_normal(high, low) + + lod1 = make_lod(low, "ChurnLOD1", LOD1_TARGET, skip_decimate) + lod2 = make_lod(low, "ChurnLOD2", LOD2_TARGET, skip_decimate) + bpy.context.view_layer.update() + lod1_tris = evaluated_triangle_count(lod1) + lod2_tris = evaluated_triangle_count(lod2) + r1 = lod1_tris / base_tris if base_tris else 0.0 + r2 = lod2_tris / base_tris if base_tris else 0.0 + + collider = hull_collider(high, "ChurnCollider") + col_tris = triangle_count(collider.data) + + export_path = os.path.join(tempfile.gettempdir(), f"bdt_churn_{os.getpid()}.glb") + if os.path.exists(export_path): + os.remove(export_path) + export_unity(export_path, [low, collider]) + export_size = os.path.getsize(export_path) if os.path.isfile(export_path) else 0 + # Blender points TMPDIR at its own temp preference, which on a portable + # build is the working directory, so the export must not outlive this. + if os.path.isfile(export_path): + os.remove(export_path) + + hyg = hygiene_audit(low.data) + zf = zfight_pairs(low.data) + ca = churn_audit(low.data) + + print(f"blender={tuple(bpy.app.version)} skip_decimate={skip_decimate}") + print(f"measured mat_index_counts={dict(sorted(idx_counts.items()))}") + print(f"measured base_tris={base_tris} lod1_tris={lod1_tris} " + f"lod2_tris={lod2_tris} r1={r1:.4f} r2={r2:.4f}") + print(f"measured nmat={nmat} uv=({u0:.4f},{v0:.4f})-({u1:.4f},{v1:.4f}) " + f"overlap={overlap:.6f} nfaces={nfaces}") + print(f"measured bbox=({size_x:.4f},{size_y:.4f},{size_z:.4f}) " + f"outer={OUTER_SIZE} zmin={bb[2]:.5f}") + print(f"measured collider_tris={col_tris} bake={bake_result} " + f"bake_has_data={img.has_data} export_bytes={export_size}") + print(f"measured hygiene loose_v={hyg['loose_v']} loose_e={hyg['loose_e']} " + f"nonman={hyg['nonman']} zero_area={hyg['zero_area']} " + f"doubles={hyg['doubles']} ngons={hyg['ngons']} zfight={zf}") + print(f"measured parts staves={ca['stave']} boards={ca['board']} lid={ca['lid']} " + f"hoops={ca['hoop']} slats={ca['slat']} handle={ca['handle']} other={ca['other']} " + f"stave_z={ca['stave_z']:.5f}") + print(f"measured joints seam=({ca['seam'][0]:.5f},{ca['seam'][1]:.5f}) " + f"handle_bite={ca['handle_bite']:.5f}") + print(f"measured seats hoop_bite=({ca['hoop_bite'][0]:.5f},{ca['hoop_bite'][1]:.5f}) " + f"hoop_proud={ca['hoop_proud']:.5f} lid=({ca['lid_seat'][0]:.5f},{ca['lid_seat'][1]:.5f}) " + f"hole_clear={ca['hole_clear']:.5f}") + print(f"measured stroke={ca['stroke']:.5f} reach={ca.get('reach', 0.0):.5f}") + + if not (BASE_TRIS_MIN <= base_tris <= BASE_TRIS_MAX): + return (fail(f"base tris {base_tris} not in [{BASE_TRIS_MIN}, {BASE_TRIS_MAX}]", 4),) + nothing + if nmat != MATERIAL_COUNT or distinct != MATERIAL_COUNT: + return (fail(f"material slots {nmat} distinct {distinct} != {MATERIAL_COUNT}", 5),) + nothing + for idx, floor in FACE_FLOORS.items(): + if idx_counts.get(idx, 0) < floor: + return (fail(f"material {idx} faces {idx_counts.get(idx, 0)} < {floor}", 5),) + nothing + if u0 < -UV_EPS or v0 < -UV_EPS or u1 > 1.0 + UV_EPS or v1 > 1.0 + UV_EPS: + return (fail(f"UVs outside 0..1: ({u0:.4f},{v0:.4f})-({u1:.4f},{v1:.4f})", 6),) + nothing + if overlap > UV_OVERLAP_MAX: + return (fail(f"UV AABB overlap {overlap:.6f} > {UV_OVERLAP_MAX}", 7),) + nothing + if (abs(size_x - OUTER_SIZE[0]) > BBOX_TOL or abs(size_y - OUTER_SIZE[1]) > BBOX_TOL + or abs(size_z - OUTER_SIZE[2]) > BBOX_TOL): + return (fail(f"bbox ({size_x:.4f},{size_y:.4f},{size_z:.4f}) off outer {OUTER_SIZE}", 8),) + nothing + if not (LOD1_RATIO_MIN <= r1 <= LOD1_RATIO_MAX): + return (fail(f"LOD1 ratio {r1:.4f} not in [{LOD1_RATIO_MIN}, {LOD1_RATIO_MAX}] " + "(--skip-decimate is the designed fail)", 9),) + nothing + if not (LOD2_RATIO_MIN <= r2 <= LOD2_RATIO_MAX): + return (fail(f"LOD2 ratio {r2:.4f} not in [{LOD2_RATIO_MIN}, {LOD2_RATIO_MAX}]", 9),) + nothing + if col_tris > COLLIDER_TRIS_MAX: + return (fail(f"collider tris {col_tris} > {COLLIDER_TRIS_MAX}", 11),) + nothing + if bake_result != {"FINISHED"} or not img.has_data: + return (fail(f"bake failed result={bake_result} has_data={img.has_data}", 12),) + nothing + if export_size <= 0: + return (fail("export file missing or empty", 13),) + nothing + if (hyg["loose_v"] or hyg["loose_e"] or hyg["nonman"] or hyg["zero_area"] + or hyg["doubles"] or hyg["ngons"] or zf): + return (fail(f"hygiene {hyg} zfight={zf} (--stray-vert is the designed fail)", 15),) + nothing + if abs(bb[2]) > ZMIN_EPS: + return (fail(f"zmin {bb[2]:.6f} not within {ZMIN_EPS} of 0 " + "(--lift-z is the designed fail)", 16),) + nothing + if ca["stave"] != N_STAVES or ca["stave_z"] > STAVE_Z_MAX: + return (fail(f"staves: {ca['stave']} of {N_STAVES}, worst stave z={ca['stave_z']:.5f} " + f"> {STAVE_Z_MAX} (--short-stave is the designed fail)", 16),) + nothing + if (ca["board"] != N_BOARDS or ca["seam"][0] < BOARD_SEAM_MIN + or ca["seam"][1] > BOARD_SEAM_MAX): + return (fail(f"{ca['board']} of {N_BOARDS} bottom boards, seams {ca['seam']} outside " + f"[{BOARD_SEAM_MIN}, {BOARD_SEAM_MAX}] (--one-piece-bottom is the designed fail)", + 17),) + nothing + if not (HANDLE_BITE_MIN <= ca["handle_bite"] <= HANDLE_BITE_MAX): + return (fail(f"handle bite {ca['handle_bite']:.5f} outside [{HANDLE_BITE_MIN}, " + f"{HANDLE_BITE_MAX}] (--short-handle is the designed fail)", 17),) + nothing + if (ca["hoop"] != len(HOOP_ZS) or ca["hoop_bite"][0] < HOOP_BITE_MIN + or ca["hoop_bite"][1] > HOOP_BITE_MAX or ca["hoop_proud"] < HOOP_PROUD_MIN): + return (fail(f"{ca['hoop']} of {len(HOOP_ZS)} hoops, bite {ca['hoop_bite']} outside " + f"[{HOOP_BITE_MIN}, {HOOP_BITE_MAX}] or proud {ca['hoop_proud']:.5f} < " + f"{HOOP_PROUD_MIN} (--float-hoops is the designed fail)", 18),) + nothing + if (ca["lid"] != 2 or ca["lid_seat"][0] < LID_SEAT_MIN or ca["lid_seat"][1] > LID_SEAT_MAX): + return (fail(f"{ca['lid']} of 2 lid boards, seat {ca['lid_seat']} outside " + f"[{LID_SEAT_MIN}, {LID_SEAT_MAX}] (--float-lid is the designed fail)", 18),) + nothing + if not (HOLE_CLEAR_MIN <= ca["hole_clear"] <= HOLE_CLEAR_MAX): + return (fail(f"handle clears the lid hole by {ca['hole_clear']:.5f}, outside " + f"[{HOLE_CLEAR_MIN}, {HOLE_CLEAR_MAX}] (--tight-hole is the designed fail)", + 18),) + nothing + if ca["stroke"] < STROKE_MIN: + return (fail(f"plunge stroke {ca['stroke']:.5f} < {STROKE_MIN} " + "(--wide-dasher is the designed fail)", 20),) + nothing + return 0, low, high, mats, tex, collider + + +def wire_normal(mat, tex): + nt = mat.node_tree + nrm = nt.nodes.new("ShaderNodeNormalMap") + nt.links.new(tex.outputs["Color"], nrm.inputs["Color"]) + nt.links.new(nrm.outputs["Normal"], nt.nodes["Principled BSDF"].inputs["Normal"]) + + +def render_still(low, mats, tex, path, engine): + scene = bpy.context.scene + wire_normal(mats[OAK_IDX], tex) + for ob in list(scene.objects): + if ob.type == "MESH" and ob != low: + ob.hide_render = True + ob.hide_viewport = True + # Level on the floor: turned about Z only. + low.rotation_euler.z = math.radians(10.0) + + floor_me = bpy.data.meshes.new("Floor") + bm = bmesh.new() + try: + bmesh.ops.create_grid(bm, x_segments=1, y_segments=1, size=60.0) + bm.to_mesh(floor_me) + finally: + bm.free() + fmat = bpy.data.materials.new("Floor") + fmat.use_nodes = True + fb = fmat.node_tree.nodes["Principled BSDF"] + fb.inputs["Base Color"].default_value = (0.03, 0.032, 0.037, 1.0) + fb.inputs["Roughness"].default_value = 0.7 + floor_me.materials.append(fmat) + floor = bpy.data.objects.new("Floor", floor_me) + scene.collection.objects.link(floor) + wall = bpy.data.objects.new("Wall", floor_me.copy()) + wall.location = (0.0, 8.5, 0.0) + wall.rotation_euler = (math.radians(90), 0.0, 0.0) + scene.collection.objects.link(wall) + + world = bpy.data.worlds.new("World") + world.use_nodes = True + world.node_tree.nodes["Background"].inputs["Color"].default_value = (0.02, 0.021, 0.025, 1.0) + scene.world = world + + def light(name, kind, loc, energy, size, col, rot=(0, 0, 0)): + ld = bpy.data.lights.new(name, kind) + ld.energy = energy + if kind == "AREA": + ld.size = size + else: + ld.shadow_soft_size = size + ld.color = col + ob = bpy.data.objects.new(name, ld) + ob.location = loc + ob.rotation_euler = tuple(math.radians(a) for a in rot) + scene.collection.objects.link(ob) + + light("Key", "AREA", (-2.4, -3.2, 3.2), 360.0, 3.0, (1.0, 0.95, 0.88), (50, 0, -35)) + light("Fill", "AREA", (3.2, -2.6, 1.6), 60.0, 5.0, (0.74, 0.84, 1.0), (68, 0, 50)) + light("Rim", "AREA", (-1.6, 2.6, 2.4), 220.0, 3.0, (0.62, 0.78, 1.0), (-55, 0, 200)) + ld = bpy.data.lights.new("Wedge", "SPOT") + ld.energy, ld.color = 220.0, (1.0, 0.66, 0.34) + ld.spot_size, ld.spot_blend, ld.shadow_soft_size = math.radians(50.0), 1.0, 0.3 + wedge = bpy.data.objects.new("Wedge", ld) + wedge.location = (0.5, 1.6, 2.0) + wedge.rotation_euler = (Vector((0.25, 0.5, 0.0)) - wedge.location).to_track_quat( + "-Z", "Y").to_euler() + scene.collection.objects.link(wedge) + + cam_data = bpy.data.cameras.new("Cam") + cam_data.lens = 50.0 + cam = bpy.data.objects.new("Cam", cam_data) + cam.location = (1.23, -2.86, 1.28) + scene.collection.objects.link(cam) + aim = bpy.data.objects.new("Aim", None) + aim.location = (0.0, 0.0, 0.52) + scene.collection.objects.link(aim) + con = cam.constraints.new("TRACK_TO") + con.target = aim + con.track_axis = "TRACK_NEGATIVE_Z" + con.up_axis = "UP_Y" + scene.camera = cam + + scene.render.engine = "CYCLES" if engine == "cycles" else eevee_engine_id() + if engine == "cycles": + scene.cycles.samples = 32 + scene.cycles.device = "CPU" + else: + try: + scene.eevee.taa_render_samples = 64 + except AttributeError: + pass + scene.render.resolution_x = 1280 + scene.render.resolution_y = 720 + scene.render.image_settings.file_format = "WEBP" if path.lower().endswith(".webp") else "PNG" + if path.lower().endswith(".webp"): + scene.render.image_settings.quality = 90 + scene.render.filepath = path + scene.view_settings.view_transform = "Standard" + + fcode = gallery_framing.check_framing(scene, cam, hero=[low], elements=[low], stage=[floor, wall]) + if fcode: + return fcode + bpy.ops.render.render(write_still=True) + if not (os.path.exists(path) and os.path.getsize(path) > 0): + return fail("render produced no file", 14) + return 0 + + +def main(): + argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else [] + p = argparse.ArgumentParser() + p.add_argument("--output", default=None) + p.add_argument("--engine", default="eevee", choices=("eevee", "cycles")) + p.add_argument("--skip-decimate", action="store_true") + p.add_argument("--stray-vert", action="store_true") + p.add_argument("--lift-z", action="store_true") + p.add_argument("--short-stave", action="store_true") + p.add_argument("--one-piece-bottom", action="store_true") + p.add_argument("--short-handle", action="store_true") + p.add_argument("--float-hoops", action="store_true") + p.add_argument("--float-lid", action="store_true") + p.add_argument("--tight-hole", action="store_true") + p.add_argument("--wide-dasher", action="store_true") + args = p.parse_args(argv) + + code, low, _high, mats, tex, _col = check( + args.skip_decimate, + lift_z=args.lift_z, + stray_vert=args.stray_vert, + short_stave=args.short_stave, + one_piece_bottom=args.one_piece_bottom, + short_handle=args.short_handle, + float_hoops=args.float_hoops, + float_lid=args.float_lid, + tight_hole=args.tight_hole, + wide_dasher=args.wide_dasher, + ) + if code: + return code + if args.output: + rcode = render_still(low, mats, tex, os.path.abspath(args.output), args.engine) + if rcode: + return rcode + print(f"rendered still {args.output}") + print("butter churn OK") + return 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except Exception as e: + traceback.print_exc() + print(f"FATAL: {e}", file=sys.stderr) + sys.exit(1) diff --git a/showcase/butter-churn/preview.webp b/showcase/butter-churn/preview.webp new file mode 100644 index 00000000..5c137449 Binary files /dev/null and b/showcase/butter-churn/preview.webp differ diff --git a/showcase/gallery.json b/showcase/gallery.json index 6ebeb97c..c31232bb 100644 --- a/showcase/gallery.json +++ b/showcase/gallery.json @@ -439,6 +439,19 @@ "mesh", "export" ] + }, + { + "name": "butter-churn", + "dir": "showcase/butter-churn", + "teaches": "A procedural plunge butter churn — sixteen tapered oak staves, three iron hoops, a three-board bottom, a two-board lid and a maple cross dasher — carried through UVs, bake, LOD, compound collider, and Unity glTF, asserting recomputed budgets rather than an API contract.", + "alt": "A tall staved oak butter churn narrowing toward the top, bound by three dark iron hoops, with a two-board lid and a pale maple dasher handle rising through it.", + "witnessesFix": "Recomputed: 5684 tris, three materials with 2240 oak, 160 maple and 576 iron faces, UVs in 0..1 with zero AABB overlap, outer AABB 0.340×0.340×1.050 m, zmin 0, hygiene 0 including zero coplanar cross-shell pairs, all sixteen staves on the floor, three bottom boards with 1.2 mm seams, the handle 14 mm into the slats, three hoops 2.5 mm into the staves and 4.9 mm proud, the lid 1.4–2.0 mm onto the stave tops, 5 mm of clearance round the handle, and a 514 mm plunge stroke for a 101 mm reach. --wide-dasher exits 20 at 140 mm while the plunger still clears the staves at rest; --tight-hole exits 18.", + "hero": "docs/gallery/assets/butter-churn-hero.webp", + "preview": "showcase/butter-churn/preview.webp", + "tags": [ + "mesh", + "export" + ] } ] } diff --git a/tests/smoke/catalog.json b/tests/smoke/catalog.json index 96d07ada..de48bb2d 100644 --- a/tests/smoke/catalog.json +++ b/tests/smoke/catalog.json @@ -106,5 +106,6 @@ {"name": "grain-sacks", "script": "showcase/grain-sacks/grain_sacks.py"}, {"name": "brazier", "script": "showcase/brazier/brazier.py"}, {"name": "apothecary-shelf", "script": "showcase/apothecary-shelf/apothecary_shelf.py"}, - {"name": "wooden-yoke", "script": "showcase/wooden-yoke/wooden_yoke.py"} + {"name": "wooden-yoke", "script": "showcase/wooden-yoke/wooden_yoke.py"}, + {"name": "butter-churn", "script": "showcase/butter-churn/butter_churn.py"} ]