Swatch Grid

examples/swatch-grid/

Procedural Principled materials — metal and dielectric, the emission pattern, and the cross-version set_specular shim.

Rendered headless by the example itself. Select it to enlarge.

witnesses EEVEE engine-id mapping: BLENDER_EEVEE on 5.x, BLENDER_EEVEE_NEXT on 4.2–4.5.

tags materials rendering

runs on 4.5 LTS · 5.1 · 5.2 LTS

blender --background --python examples/swatch-grid/swatch_grid.py --

falsify it Breaks the contract on purpose and must exit 6

blender --background --python examples/swatch-grid/swatch_grid.py -- --output swatch.png --engine cycles --samples 8 --width 640 --same-base

A runnable example that renders a tiered 3×2 material library — one sphere per material, each seated in a gunmetal collar on a two-tier walnut riser behind an engraved brass name plaque — to a single PNG. It demonstrates the procedural-materials-and-shaders patterns end to end:

It doubles as a live proof of the EEVEE engine-id behavior: the version-branch helper resolves BLENDER_EEVEE on Blender 5.x and BLENDER_EEVEE_NEXT on 4.2–4.5, and the check witnesses the inversion for real — the other era's id must be rejected by the running build (assignment raises TypeError) and the helper's id accepted — so a regression in that mapping fails the example, not just the docs.

Run#

# Cheap correctness check (materials + engine-id witness, no render):
blender --background --python swatch_grid.py --

# Falsifiers (smoke runs them with --output; see the exit table):
blender --background --python swatch_grid.py -- --output s.png --engine cycles --same-base
blender --background --python swatch_grid.py -- --invert-engine-id
blender --background --python swatch_grid.py -- --no-specular-shim

# Render and pixel-verify with the build's EEVEE engine (needs a GPU/display):
blender --background --python swatch_grid.py -- --output swatch.png

# GPU-less / CI hosts: render the pixels with Cycles (CPU). The EEVEE id is still
# asserted; only the final pixels use Cycles.
blender --background --python swatch_grid.py -- --output swatch.png --engine cycles --samples 16 --width 960

Staging#

The swatches stand as a tiered material library on the default stage (floor, wall at y = 9, warm key, cool fill and rim, warm wedge pooling on the floor behind the display). Each sphere sits in a gunmetal collar on a two-tier walnut riser (oiled-grain wave texture in object space); the back tier stands taller so every sphere clears the one in front of it. A brass plaque leans in front of each collar with the material's name set into it as an extruded text object (LABELS, in grid order), so the display reads as a labelled sample case. The plaques sit below the sphere centres the pixel check samples, so verify_png is unaffected. A 50 mm camera looks down on the display with a TRACK_TO aim, which keeps the floor/wall seam above the back row.

The emissive swatch used to be a bare Emission at strength 1.4: under the Standard view transform its red channel clipped across the whole face and it rendered as a flat orange disk. Now the same ShaderNodeEmission (color and strength asserted) owns the face toward the camera at strength 0.95, below clipping, and a Layer Weight facing ramp hands it over to a dark dielectric shell at the silhouette, so the globe has a limb. A shadowless warm point light at its center stands in for the glow it throws on its own collar, plinth and the floor; the shell is lit from inside only on back faces, so the ball itself still shows only the asserted emission.

The world is a reflection-only sky: glossy rays see a warm overhead gradient above a dark horizon, and camera and diffuse rays see the dark stage. The mirror-finish gold otherwise reflects the near-black world as a black ball.

verify_png samples each swatch where the camera sees it: the sphere center is projected through the render camera (world_to_camera_view) rather than assumed to sit at the center of a third of the frame, so the six-region check follows the layout.

Exit codes#

Per-script sequential checks. 9 is a valid check code; there is no rule against it. 10 is the shared framing helper.

CodeMeaning
0Success
1Uncaught exception (FATAL wrapper)
2argparse / usage
3Distinct swatch material colors ≠ 6 (check-only path; with --output a diagnostic after check 6)
4--output produced no file
5Wrong-era EEVEE engine id was accepted (--invert-engine-id lands here)
6Rendered still is black or not six distinct swatch regions (--same-base lands here)
7set_specular did not resolve Specular IOR Level or the value did not land (--no-specular-shim lands here)
10Gallery framing violation

--no-verify was a skip-flag and has been removed. Pixel verification always runs when --output is passed.

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 passes --output (Cycles, 8 samples, 640 px) so the pixel check runs. Its catalog falsifiers are --same-base (expects exit 6, the rendered regions), --invert-engine-id (expects exit 5) and --no-specular-shim (expects exit 7).

Verified#

Runs headless on Blender 4.5.10 LTS and 5.1.1; exercised on both by the blender-smoke workflow on every PR and weekly schedule. The --output render path additionally measures framing against the Layer 1 band via examples/gallery_framing.py (exit 10 on violation) before writing the still.

Source

examples/swatch-grid/swatch_grid.py View the script on GitHub →
Six material spheres in gunmetal collars on a two-tier walnut riser, each over an engraved brass plaque: gold, copper, red plastic behind; blue plastic, emissive, white rough in front.