Preview default materials

Preview default materials#

embodichain preview-material previews a default material in a native DexSim window or exports images from a fixed studio scene. It uses the same VisualMaterialCfg.from_preset() resolver as runtime and Spawn material creation. python -m embodichain preview-material is equivalent and works outside the source checkout after installing the wheel.

See the material catalog for all 24 public presets, their parameters, OfflineRT images and download setup.

Query and preview#

# Metadata only: no simulator imports, GPU initialization or material download.
embodichain preview-material --list
embodichain preview-material --list --source builtin

# Open the native window after saving a reference capture.
embodichain preview-material --material GlassClear

# Export one image and exit without a window.
embodichain preview-material --material PlasticMatteBlue --headless \
  --output outputs/blue

The default material is GlassClear and the default renderer is rt (OfflineRT), which supports the complete catalog. A single preview stays open until Ctrl+C; --max-steps 100 bounds its preview updates. Physics is disabled. Use --gpu-id to select the render GPU; --size, --frames and --spp control capture resolution, accumulation frames and DexSim render iterations per frame. The defaults are 320 pixels, four frames and 16 iterations.

Override a preset#

Pass a JSON object containing VisualMaterialCfg fields. Common fields stay flat, while advanced fields belong inside parameters:

embodichain preview-material --material GlassClear --headless \
  --material-params '{"ior":1.6,"parameters":{"volume_attenuation_distance":8.0}}' \
  --output outputs/glass-variant

embodichain preview-material --material PlasticMatteBlue --headless \
  --material-params '{"roughness":0}' --output outputs/smooth-blue

Omitted fields and JSON null inherit the preset. Explicit 0 and false remain overrides. Duplicate flat/native properties, invalid values, the removed material_type field and texture edits fail before creating a World or loading assets. Both handwritten and preset configurations now select scattering from optical parameters; see the catalog’s migration example. The command owns material UIDs; select the preset using --material.

Variants are created before binding. The preview does not depend on native cross-model hot mutation or change the material factory’s geometry/UV behavior.

Batch export and renderer requirements#

# All 24 presets, individual WebPs and grouped galleries. Batch mode has no window.
embodichain preview-material --all --headless --gallery \
  --size 640 --frames 6 --spp 12 --output outputs/material-catalog

# Only the six built-in parameter definitions; no material-archive download.
embodichain preview-material --all --source builtin --gallery

# Explicitly export the 14 presets supported by Hybrid.
embodichain preview-material --all --renderer hybrid --compatible-only \
  --output outputs/materials-hybrid

Hybrid and FastRT support ten basic resource presets and four built-in parameter presets. The remaining ten public presets and advanced parameter variations require OfflineRT. An incompatible request fails before resource download or native loading; the command never changes the renderer or downgrades material parameters. With --all --compatible-only, excluded names and reasons are printed to stderr and recorded in results.json. If no presets remain, the command fails. --source filters --list and --all; --material-params applies the supplied overrides to every selected preset.

Each renderer must run in a separate process. --gallery requires Pillow and matplotlib; install those packages if they are absent. Gallery composition runs after native renderer cleanup and uses the saved captures.

Studio lighting#

The default material-studio-v2 recipe uses the same lighting for every preset so material appearances can be compared:

Setting

Value

Linear exposure multiplier

1.6

Environment emission intensity

48

Key rectangle light intensity

150

Fill rectangle light intensity

120

Light colors, geometry and camera poses are fixed by the preview scene. These settings are recorded in results.json under lighting, alongside the scene recipe identifier. The catalog images use this recipe at 640×640, six accumulation frames and 12 render iterations per frame. Material parameters remain the authored preset values.

Outputs and direct-native verification#

Every render writes <PresetName>_preset.png and results.json under --output (default outputs/default-materials). Use a separate directory per variant or renderer to retain previous results. The report records the scene recipe and lighting, renderer and DexSim version, capture settings, material source/revision, serialized configuration, geometry choice, parameter readback and exclusions. Unspecified configuration fields stay null; authored resource defaults are not expanded into explicit overrides.

--gallery additionally writes <PresetName>.webp, default-materials.webp and nonempty built-in, basic-resource and advanced-resource galleries.

# Compare the preset resolver with the original native definitions.
embodichain preview-material --all --headless --compare-native \
  --renderer rt --output outputs/material-parity

--compare-native also saves *_native.png and *_native_repeat.png, checks parameter readback and compares the center crop with a repeat-render noise control. A mismatch fails the command. This mode verifies authored presets and cannot be combined with --material-params.

The scene uses fixed colored cards, a checkerboard, rectangular lights and exposure. Architecture/wood/stone/ground presets use a slab; other presets use a sphere. SoapBubble has an explicit inward-facing inner shell. An optional --model /path/to/skin_face.glb supplies a segmented face for SkinHumanLight or a batch containing it; that model is not downloaded with the materials.

The existing examples/sim/rendering/default_materials.py delegates to this command and retains its headless default. Use the production CLI for window preview or add --no-headless to the example.

Contents