Wooden Yoke

showcase/wooden-yoke/

A procedural double ox yoke — a carved oak beam with neck saddles and upturned ends on two bent hickory bows pinned above it, with a staple and a hung iron ring — 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. Select it to enlarge.

witnesses Recomputed: 5288 tris, three materials with 1088 oak, 720 hickory and 936 iron faces, UVs in 0..1 with zero AABB overlap, outer AABB 1.424×0.140×0.640 m, zmin 0, hygiene 0 including zero coplanar cross-shell pairs, both bows standing on the floor, every leg 52.7 mm proud of the beam, the staple 17.5 mm into it, four pins resting 1.5 mm into its crown, a ring threaded along the staple's bar and hung 1.0 mm onto it, two mirrored bows, and each neck opening 266 mm wide and 371 mm high. --pinch-bows exits 19 at 196 mm while the bows still ground and the envelope is unchanged; --edge-on-ring exits 17.

category Village

tags mesh export showcase

blender --background --python showcase/wooden-yoke/wooden_yoke.py --

A double ox yoke: a carved oak beam with two neck saddles and upturned ends, two bent-hickory oxbows whose legs pass up through the beam and are pinned above it, and a forged staple under the centre carrying a hung iron ring. It stands on the bottoms of its two bows. 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 beam, swept bows and staple, lathed pins, torus ring, all in one bmesh
skills/custom-propertiesface attributes (PlankTone, GrainDir) read by the wood shaders
skills/procedural-materials-and-shadersoak and hickory with grain along each piece, 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.pya hull for the beam and for each bow leg and foot, merged into a compound
snippets/lod_chain.pyLOD naming and ratio pattern
examples/mesh-hygiene-audithygiene combinatorics (copied, not imported)

The budget that matters#

A yoke exists to close round two necks. Each bow and the saddle above it make an opening an ox's neck passes through. A bow bent too tight fails its job, and nothing else notices:

The piece measures each opening off the finished mesh:

--pinch-bows is the falsifier built for exactly this. It brings each bow's legs 35 mm closer to its centre, so the opening closes to 196 mm and the run exits 19. Every other budget still 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 4 bytes, which is exporter metadata and not a budget).

BudgetBandMeasured
Base triangles4800–58005288
LOD1 ratio0.32–0.620.5000
LOD2 ratio0.10–0.350.2197
Material slotsexactly 3, distinct3
Oak / hickory / iron faces≥ 950 / 650 / 7501088 / 720 / 936
UV boundsinside 0..1(0.0100, 0.0100)–(0.9900, 0.9900)
UV AABB overlap≤ 1e-50.000000
Outer AABB1.424 × 0.140 × 0.640 m ± 0.0201.4240 × 0.1400 × 0.6400
Collider triangles≤ 300260 (seven hulls)
Normal bake{'FINISHED'} with image data{'FINISHED'}, has_data=True
glTF exportfile written, non-empty~160 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 bows2 bows, each zmin ≤ 1e-42 at 0.00000
Leg protrusion4 legs, each 25–70 mm above the beam's top at that leg52.7 mm
Staple bite8–30 mm into the beam17.5 mm
Threaded ringring's hole axis against the staple's bar, cos ≥ cos 20°1.0000
Pin seat4 pins, shank 0.5–3.0 mm into the beam's top1.50 mm
Hung ringring's inner edge against the bar's top, −3.0 to +0.5 mm−1.00 mm
Neck openingwidth 240–300 mm, height 300–400 mm266.0 / 370.9 mm
Mirrored bowsextents mirrored through x = 0 within 0.1 mm0.000 mm

Real-world size: a 1.42 m beam over two 266 mm openings 0.80 m apart, standing 0.64 m to the tips of its upturned ends. It is a pair yoke for draught oxen.

Construction#

Stations are a uniform run plus one at every leg and bow centre, so the top a pin is measured against, and the saddle apex, are vertices rather than chords. The ends close on a pole a few millimetres past the last ring.

Findings the budgets forced#

Conventions walked#

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

ConventionAppliesHow
Deterministic, budgets declared, assertions recomputeyesno RNG; every value above is read off the mesh
Falsifier fails the budget it targetsyestable below, proven on all three binaries
Hygiene incl. cross-shell coplanaryesexit 15
Named supportsyesthe two bows (--float-bow)
Even shaping terms and mirror symmetryyesevery beam term even in x; mirrored bows asserted (--skew-bow)
Plumb and real-world sizeyesthe neck opening is the real-world size that matters (--pinch-bows)
A joint bites; touching is not joiningyeslegs through the beam (--short-bows), staple into it (--short-staple)
Hung ringyestorus hung on the bar, inner edge on its top (--clip-ring)
A ring is threaded across its holeyeshole axis along the bar (--edge-on-ring)
Carried parts bite their bearersyespins resting into the beam's crown (--float-pins)
Rope, masonry, timber boards, roofs, vessels, scatter, paintnothe piece has none of these
A bent bar is one sweepyeseach bow and the staple is one sweep
Shading is part of the modelyesbeam and bows smooth (carved, bent); every edge over 40° hard (sawn beam ends, pin heads)
One substance, one slotyesoak, hickory, iron
Iron is not chromeyesnear-black and rust, roughness 0.55–0.85, metallic 0.65
Identical boards read as CGyesper-piece PlankTone; grain along the beam and up each bow
Edge treatment: no right anglesn/alofted and swept, no box edges; not a separate budget
Sort bmesh operator inputsn/ano set-fed operator is run
The bake cage is narrower than the nearest neighbouryesCAGE_EXTRUSION 0.01 m
Level on the stage; stage 60 myesturned about Z only; 60 m floor and wall
Keep a falsifier's envelope stillyesevery falsifier leaves the AABB unchanged

Falsifiers#

Each breaks one pipeline stage so a named budget fails. All eleven 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 under the beam15
--lift-zgrounded zminlifts the whole mesh 50 mm16
--float-bownamed bowslifts the left bow 8 mm; the right still grounds the AABB16
--short-bowsleg protrusionstops every leg 10 mm under the beam's top; −2.3 mm at the tip17
--short-staplestaple bitestops the staple 5 mm under the beam; −2.6 mm17
--edge-on-ringthreaded ringturns the ring into the staple's plane; cos 0.000017
--float-pinspin seatlifts every pin 5 mm off the beam; −3.5 mm18
--clip-ringhung ringlifts the ring 6 mm off its bar; +5.0 mm18
--pinch-bowsneck openingbrings each bow's legs 35 mm in; 196 mm wide19
--skew-bowmirrored bowsmoves the right bow 6 mm along the beam; 6.0 mm19

Exit codes#

File-local and sequential. 9 is a valid check code. 1 is the FATAL wrapper — a crash, never a named check.

CodeMeaning
0Success
1Uncaught exception (FATAL wrapper)
2argparse / usage
3Mesh did not build, or has no UV layer
4Base triangle count outside band
5Material slots, or a material's face floor
6UVs outside 0..1
7UV AABB overlap above tolerance
8Outer AABB off declared size
9LOD1 or LOD2 ratio outside band (--skip-decimate)
10Framing gate (examples/gallery_framing.py, render path only)
11Collider triangles above ceiling
12Normal bake failed or produced no image data
13glTF export missing or empty
14--output produced no file
15Mesh hygiene (--stray-vert)
16Grounded zmin, or a bow floating (--lift-z, --float-bow)
17Leg protrusion, staple bite or threaded ring (--short-bows, --short-staple, --edge-on-ring)
18Pin seat or hung ring (--float-pins, --clip-ring)
19Neck opening or mirrored bows (--pinch-bows, --skew-bow)
20Gallery asset-quality violation (render path; the floors' 11 is remapped here)

Run it#

# Budget check, no render. ~2.5 s on 4.5, ~4.6 s on 5.2.
blender --background --python wooden_yoke.py --

# Falsifier: the bows close too tight for a neck. Must exit 19.
blender --background --python wooden_yoke.py -- --pinch-bows

# Falsifier: the ring turns into the staple's plane. Must exit 17.
blender --background --python wooden_yoke.py -- --edge-on-ring

# Render the gallery still (EEVEE; --engine cycles on a GPU-less host).
blender --background --python wooden_yoke.py -- --output wooden_yoke.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 triangles528852885288
LOD1 / LOD2 tris2644 / 1162samesame
Face counts (oak / hickory / iron)1088 / 720 / 936samesame
Outer AABB1.4240 × 0.1400 × 0.6400samesame
Collider tris260260260
Neck opening266.0 × 370.9 mmsamesame
glTF bytes159764159764159760

Source

showcase/wooden-yoke/wooden_yoke.py View the script on GitHub →
A carved oak ox yoke with upturned ends standing on two bent hickory bows pinned above the beam, with a rusted iron ring hung from a staple under its centre.