LOD Decimate Chain

A runnable example that builds a retro rocket — a lathed hull with a hollow nozzle bell, brass collar, red skirt, recessed panel seams, a raised brass shoulder band, a tangent-ogive nose and a brass antenna; four swept fins with chamfered brass-trimmed rims; a flanged porthole with a domed glass; two rows of rivets; six materials, every count a closed form — and evaluates it at LOD0/1/2 through the Decimate modifier via the depsgraph, following depsgraph-and-evaluated-data and mesh-editing-and-bmesh.

Pipeline arc: modeling/LOD here, weighting in vertex-weight-limit, export in gltf-export-roundtrip.

What it witnesses: the modifier-based LOD contract that game asset pipelines rely on.

• Decimate is non-destructive and lives in the depsgraph. The evaluated mesh carries the reduction; the original datablock is byte-identical before and after evaluation. The check proves both — evaluated counts drop while obj.data keeps the closed-form counts (2,511 verts / 2,488 faces / 4,784 tris) — and every evaluated reference is released with to_mesh_clear(). An LOD chain that bakes the reduction into obj.data destroys the asset's LOD0 (applying the modifier instead: exit 7, caught).
• The COLLAPSE ratio is a target, not a guarantee. Each LOD's evaluated triangle count must land within 5% of ratio x base_tris — measured 0.00% at ratio 0.5 (2,392 tris) and 0.13% at ratio 0.18 (860 tris). A stacked second Decimate halves the effective ratio (50.0% excursion, caught); a dropped modifier leaves evaluated == original (caught).
• LODs preserve silhouette-critical dimensions. Height (the antenna tip at 3.40) and fin span (2.04) are the rocket's readability; the evaluated bbox holds the base bbox within 1e-3 at every level (measured 2.6e-10). Decimate has no vertex pinning, so this is a real risk, not a formality, and it shaped the model: each fin ends in a straight tip cap and a flat foot, and the four fins sit on the local axes, so every bbox extreme is a fin's mid-rim vertex on a straight edge. The three-fin layout this replaced put an extreme on an oblique fin's plate corner, and a collapse at 0.18 shaved it by 4.7e-3 (caught).

The Decimate modifier API (decimate_type='COLLAPSE', ratio) is stable across Blender 4.5 LTS, 5.1 and 5.2 — the example runs identically on all three, which is itself the version witness (measured values match to the digit).

The render stages the three LODs left to right with a dark triangle wireframe laid over each: the same mesh through the same Decimate, then Triangulate and Wireframe, so the overlay draws exactly the triangles the check counts (measured 4,784 / 2,392 / 860 faces on the overlay's input). The density drop reads at thumbnail size — a fine mesh on LOD0, large facets on LOD2, where the porthole flange collapses to an octagon — while the silhouettes stay identical, which is contract 3 made visible. One label per LOD carries the evaluated triangle count from the check.

Run#

# Cheap correctness check (no render) — the CI check:
blender --background --python lod_decimate_chain.py --

# Falsifier: no Decimate on the LOD copies. Must exit non-zero (no reduction).
blender --background --python lod_decimate_chain.py -- --no-decimate

# Also render a still (EEVEE on a GPU host; use --engine cycles on GPU-less hosts):
blender --background --python lod_decimate_chain.py -- --output rocket.png
blender --background --python lod_decimate_chain.py -- --output rocket.png --engine cycles

Exit codes#

Per-script sequential checks. 9 is a valid check code; there is no rule against it.

The blender-smoke workflow runs the check on Blender 5.2 LTS and 4.5 LTS (5.1 on the weekly cron, the needs-5.1 PR label, or manual dispatch). Smoke does not pass --output. Its catalog falsifier is --no-decimate (expects exit 6).