Stone Archway

showcase/stone-archway/

A procedural masonry archway — coursed piers, projecting imposts, nine voussoirs and a proud keystone — carried through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract.

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

witnesses Recomputed: 1140 tris, three materials with 182 dressed, 364 ashlar and 108 mortar faces re-stamped after the chamfer, UVs in 0..1 with zero AABB overlap, outer AABB 1.644×0.510×2.057 m, clear opening 1.203 m, zmin 0, hygiene 0 including zero coplanar disjoint pairs, both piers grounded, the springing joint an overlap, all eight mortar joints at 9.70 mm inside the 6–17 mm band, and every intrados vertex within 0.97 mm of the declared 0.60 m radius over 178°. --off-circle exits 19 on the circle fit; --wide-mortar exits 18 on the joint band.

category Village

tags mesh export showcase

blender --background --python showcase/stone-archway/stone_archway.py --

A freestanding masonry arch — two coursed piers, projecting imposts, nine voussoirs turning a semicircle, and a keystone standing proud at the crown, every joint filled with a recessed mortar bed. 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-bmeshwedge and box construction, chamfer, UVs in one bmesh
skills/procedural-materials-and-shadersashlar, dressed stone and mortar: object-space mottling, speckle, bump, per-block tone
skills/bake-high-to-lowCycles tangent-space normal bake, high onto low
skills/engine-export-presetsUnity glTF (export_yup=True)
skills/depsgraph-and-evaluated-dataevaluated triangle counts for the LOD ratios
snippets/decimate_to_budget.pyLOD1 / LOD2 COLLAPSE chain
snippets/convex_hull_collider.pyconvex collider
snippets/lod_chain.pyLOD naming and ratio pattern
examples/mesh-hygiene-audithygiene combinatorics (copied, not imported)

The budget that matters#

An arch can fail invisibly. Nine wedge blocks laid in a row are still nine wedge blocks; the thing that makes them an arch is that their intrados vertices sit on a circle. So the piece recomputes that circle from vertex positions — not from the angles the generator used — and asserts every intrados vertex lands within 4 mm of the declared 0.60 m radius, over an arc spanning at least 168°.

--off-circle is the falsifier built for exactly this. It keeps the angles, the joints, the materials, the triangle count and the bounding box identical, and only wanders the intrados radius by ±18 mm. Every other budget in the piece still passes. Only the circle fit sees it.

Measuring it took two corrections#

The first attempt selected intrados vertices by radius. That swept in the chamfer vertices sitting one bevel-width out on each radial face and reported a 5.1 mm error on a true arch. The fit now runs over the vertices of faces that actually face the springing centre — normal inward in XZ and with a small Y component, which is what excludes the chamfer strips running along the intrados edges.

Budgets#

Declared in the script as named constants, recomputed from the generated mesh. Measured values are from Blender 5.2.1; the cross-version table is at the end.

BudgetBandMeasured
Base triangles950–14501140
LOD1 ratio0.32–0.620.5000
LOD2 ratio0.10–0.350.2140 (5.2) / 0.2193 (4.5, 5.1)
Material slotsexactly 3, distinct3
Dressed faces (keystone, imposts, plinth and head courses)≥ 100182
Ashlar faces≥ 280364
Mortar faces≥ 100108
UV boundsinside 0..1(0.0015, 0.0015)–(0.9985, 0.9985)
UV AABB overlap≤ 1e-50.000000
Outer AABB1.644 × 0.510 × 2.057 m ± 0.0201.6440 × 0.5100 × 2.0568
Clear opening1.200 m ± 0.015, measured between the pier faces1.2033
Collider triangles≤ 260132
Normal bake{'FINISHED'} with image data{'FINISHED'}, has_data=True
glTF exportfile written, non-empty~100 kB
Hygieneall zeroloose 0/0, non-manifold 0, zero-area 0, doubles 0, n-gons 0, coplanar disjoint pairs 0
Grounded AABB\zmin\≤ 1e-40.00000
Pier supports2 piers, each base course zmin ≤ 1e-32 at 0.00000
Keystone proud of the wall face≥ 0.020 m0.03500
Springing jointoverlap, surface gap ≤ 1e-40.00000
Mortar jointsevery adjacent pair in 0.006–0.017 mall eight at 0.00970
Intrados circle fitevery vertex within 0.004 m of R = 0.600.00097
Intrados arc span≥ 168°178.0°
Mortar contact18 joints, each overlapping exactly 2 stones18, all 2

Real-world size: a 1.20 m clear opening under a semicircular head, 1.64 m across the piers and 2.06 m to the top of the keystone — a garden gate arch.

Mortar#

Every joint used to be air. The pier courses stood 7 mm apart and the voussoirs 9.7 mm apart, none of them touching: each pier was a stack of floating blocks, with daylight through every joint in the ground-contact and joint close-ups. The mortar-band budget measured the gaps and passed, because the gaps were the right width. Nothing asked what was in them.

Each joint now holds a mortar shell sized from the two blocks it sits between (add_mortar): beds between courses and under each impost, and wedges between voussoirs. Each is recessed MORTAR_RECESS (chamfer plus 3 mm) behind the stone faces, so it reads as a raked joint, and bites MORTAR_BITE (1.5 mm) into both blocks. Mortar is added after the chamfer pass and left unchamfered, and classify skips mortar shells, so every stone budget — circle fit, joint band, keystone, supports — still measures stone against stone.

mortar_audit asserts that each of the 18 mortar shells BVH-overlaps exactly two stones. --short-mortar stops every joint 1 mm shy of both blocks, so each shell touches none, and the piece exits 18.

Surface#

The stone used to read as wood. Its noise-driven colour mix streaked at hero scale into long brown grain, and under neutral light it looked like cream plaster. stone_material now samples object space with isotropic noise: mottling for colour, fine speckle driving roughness, and a small bump for pitting. A seeded BlockTone face attribute (paint_blocks) shades each stone differently. Dressed stone is paler and smoother than ashlar; mortar is a flat grey-beige. The baked normal map is chained under the bump (wire_normal) rather than replacing it.

Determinism#

Fixed seed 23; no unseeded randomness. Every measured value above is byte-identical on 4.5.11, 5.1.2 and 5.2.1 except LOD2, where DECIMATE COLLAPSE produces 244 triangles on 5.2 and 250 on 4.5 and 5.1. That is why the LOD gate is a ratio band (0.10–0.35, measured 0.2140 and 0.2193) and not an exact count.

Falsifiers#

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

FlagBreaksExit
--skip-decimatedrops the DECIMATE modifiers, LOD1 ratio goes to 1.00009
--stray-vertadds one loose vertex inside the opening, so hygiene catches it rather than the bounding box15
--lift-zlifts the whole mesh 50 mm off the floor16
--float-pierfloats one pier 12 mm; the other still grounds the AABB, so only the named-support budget sees it16
--sink-keystonesinks the keystone to a quarter of its projection (8.75 mm) — the imposts still set the Y envelope, so the bounding box is unchanged17
--wide-mortartriples the joint angle, opening every joint to 29.1 mm18
--off-circlewanders the intrados radius ±18 mm while keeping angles, joints and envelope19
--short-mortarstops every mortar joint 1 mm shy of both stones; each of the 18 touches none, mortar-contact budget18

Three of these needed the model changed, not the budget:

Findings the budgets forced#

Exit codes#

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

CodeMeaning
0Success
1Uncaught exception (FATAL wrapper)
2argparse / usage
3Mesh did not build, or has no UV layer
4Base triangle count outside band
5Material slots, or a material's face floor
6UVs outside 0..1
7UV AABB overlap above tolerance
8Outer AABB off declared size
9LOD1 or LOD2 ratio outside band (--skip-decimate)
10Framing gate (examples/gallery_framing.py, render path only)
11Collider triangles above ceiling
12Normal bake failed or produced no image data
13glTF export missing or empty
14--output produced no file
15Mesh hygiene (--stray-vert)
16Grounded zmin, or a pier base floating (--lift-z, --float-pier)
17Keystone projection or springing joint (--sink-keystone)
18Mortar joint outside band (--wide-mortar), or a mortar shell not seated in exactly two stones (--short-mortar)
19Intrados circle fit, or clear opening (--off-circle)
20Gallery asset-quality violation (render path; the floors' 11 is remapped here)

Run it#

# Budget check, no render. ~1.1 s on 4.5, ~1.2 s on 5.1, ~1.4 s on 5.2.
blender --background --python stone_archway.py --

# Falsifier: the intrados stops being a circle. Must exit 19.
blender --background --python stone_archway.py -- --off-circle

# Falsifier: every mortar joint opens to 29 mm. Must exit 18.
blender --background --python stone_archway.py -- --wide-mortar

# Render the gallery still (EEVEE; --engine cycles on a GPU-less host).
blender --background --python stone_archway.py -- --output arch.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 triangles114011401140
LOD1 tris / ratio570 / 0.5000570 / 0.5000570 / 0.5000
LOD2 tris / ratio250 / 0.2193250 / 0.2193244 / 0.2140
Face counts (ashlar / dressed / mortar)364 / 182 / 108samesame
Outer AABB1.6440 × 0.5100 × 2.0568samesame
Collider tris132132132
Intrados deviation0.000970.000970.00097
Mortar jointsall 0.00970all 0.00970all 0.00970
Mortar contact18 × 2 stonessamesame
Check wall-clock~1.11 s~1.18 s~1.37 s

Source

showcase/stone-archway/stone_archway.py View the script on GitHub →
A freestanding grey stone archway of coursed piers and a semicircular arch with a keystone, laid in pale recessed mortar joints.