Unify parameter-driven visual materials on DexSim 0.5.1rc1

agent_context/MAP.yaml

@@ -11,7 +11,7 @@ topics:
   aliases: [simulation system, simulation manager, Newton physics backend, motion module, sim motion, camera attachment, 运动能力模块, 仿真系统, 仿真管理器]
   keywords: [SimulationManager, SimulationManagerCfg, RenderCfg, DenoisingCfg, DenoisingMode, DLSSCfg,
     NRDCfg, DLSS, NRD, frame_time_delta_ms, explicit physics stepping, arena, DexSim, PhysicsBackendCfg,
-    DefaultPhysicsCfg, NewtonPhysicsCfg, VisualObject, VisualObjectCfg, UsdSourceCfg, source_prim_path, add_visual_object, 纯渲染对象, AutoSolverCfg, DexUniSolverCfg, DexUni, runtime control, deformable, particle set,
+    DefaultPhysicsCfg, NewtonPhysicsCfg, VisualObject, VisualObjectCfg, VisualMaterial, VisualMaterialCfg, VisualMaterialInst, preview-material, 材质预览, UsdSourceCfg, source_prim_path, add_visual_object, 纯渲染对象, AutoSolverCfg, DexUniSolverCfg, DexUni, runtime control, deformable, particle set,
     ArticulationJointKinematics, get_parent_joint_chain, asset_physics_mode, joint_drive_props, enable_gravity,
     fixed-cadence playback, quaternion, xyzw]
   paths: [topics/simulation-system/simulation-system.md]
@@ -24,6 +24,9 @@ topics:
   - embodichain/lab/sim/cfg/
   - embodichain/lab/sim/physics/
   - embodichain/lab/sim/spawn/
+  - embodichain/lab/sim/material.py
+  - embodichain/lab/sim/_material_presets.py
+  - embodichain/lab/scripts/preview_material.py
   - embodichain/lab/sim/common.py
   - embodichain/lab/sim/_startup_summary.py
   - embodichain/lab/sim/_runtime_controls.py
@@ -34,7 +37,7 @@ topics:
   - embodichain/lab/sim/objects/gizmo.py
   - embodichain/lab/gym/envs/base_env.py
   watch_paths: [embodichain/lab/sim/sim_manager.py, embodichain/lab/sim/cfg/, embodichain/lab/sim/physics/,
-    embodichain/lab/sim/spawn/, embodichain/lab/sim/objects/, tests/sim/]
+    embodichain/lab/sim/spawn/, embodichain/lab/sim/material.py, embodichain/lab/sim/_material_presets.py, embodichain/lab/scripts/preview_material.py, tests/lab/scripts/test_preview_material.py, embodichain/lab/sim/objects/, tests/sim/]
   related_topics: [env-framework, robot-system, sensor-system, sim-visualization, ik-solvers, motion-planning,
     atomic-actions, rl-learning, configclass-pattern, robot-workspace]
   status: active
@@ -422,15 +425,19 @@ topics:
   title: Data Assets
   aliases: [data assets, data path, asset download, 数据资产, 资产下载, 数据路径]
   keywords: [get_data_path, get_data_class, EmbodiChainDataset, TabletopFourBases, demo assets, EMBODICHAIN_DATA_ROOT, EMBODICHAIN_DATASET_ROOT,
-    CATEGORY_MODULES, download lock, get_registry]
+    CATEGORY_MODULES, download lock, get_registry, DefaultMaterials, list_default_materials, get_default_material_info]
   paths: [topics/data-assets/data-assets.md]
   source_of_truth:
   - embodichain/data/dataset.py
   - embodichain/data/constants.py
   - embodichain/data/download.py
   - embodichain/data/__init__.py
   - embodichain/data/assets/__init__.py
-  watch_paths: [embodichain/data/, embodichain/cli/main.py, tests/data/]
+  - embodichain/data/assets/materials.py
+  - embodichain/data/default_materials.py
+  - embodichain/data/default_materials.json
+  - embodichain/_material_catalog.py
+  watch_paths: [embodichain/data/, embodichain/_material_catalog.py, embodichain/cli/main.py, tests/data/]
   related_topics: [gen-sim, robot-system, data-pipeline]
   status: active
 - id: data-pipeline

agent_context/topics/data-assets/data-assets.md

@@ -12,6 +12,8 @@ Online sampling and demonstration persistence belong to
 | Cache roots / mirror prefix | `embodichain/data/constants.py` |
 | Locked download and ZIP integrity | `embodichain/data/dataset.py`: `EmbodiChainDataset`, `_dataset_download_lock()` |
 | CLI list/download | `embodichain/data/download.py`: `CATEGORY_MODULES`, `get_registry()`, `download_asset()` |
+| Default material catalog / provenance | `embodichain/_material_catalog.py` → `embodichain/data/default_materials.py`; `embodichain/data/default_materials.json` |
+| Default material archive | `embodichain/data/assets/materials.py`: `DefaultMaterials` |
 | Dataset class visibility | `embodichain/data/__init__.py`, `embodichain/data/assets/__init__.py` |
 | Pretrained policy bundles | `embodichain/data/assets/policy_assets.py`: `download_pretrained_policy()` |
 | Unified CLI registration | `embodichain/cli/main.py`: `embodichain data` |
@@ -44,6 +46,8 @@ Keep the lock outside the directory repair may delete. POSIX uses `flock`;
 Windows uses a polled byte lock. Direct Open3D subclasses do not automatically
 receive the project's locking/repair behavior.
 
+The CLI honors an asset class's optional `cache_prefix` when checking readiness
+and ensuring extraction; otherwise the class name is the cache entry.
 The CLI imports the fixed `CATEGORY_MODULES` and finds `DownloadDataset`
 subclasses defined in each module. Adding an asset module alone does not add a
 CLI category. `get_registry()` also appends public classes from
@@ -72,6 +76,32 @@ The registered descriptor respects the configured host and falls back to the
 official Hugging Face dataset. The scene tutorial downloads by asset reference
 by default and accepts local exports through `--source`.
 
+## Default material resources
+
+`list_default_materials()` and `get_default_material_info()` are exported from
+`embodichain.data` and query wheel-packaged metadata without a World or download.
+The shared implementation lives in `_material_catalog.py` so CLI catalog queries
+can avoid importing the data package's Open3D/download dependencies. Preserve the
+public data exports and one catalog implementation. `setup.py` must include
+that catalog explicitly. `DefaultMaterials` uses a
+revision-specific cache prefix and the shared dataset lock, verifies archive
+SHA256 and member digests, and repairs extraction from the verified archive.
+Its data CLI registration follows the existing materials category.
+
+The same catalog includes six built-in parameter presets with their own revision,
+native parameters and no texture size. Metadata distinguishes `source` and
+`requires_download`; only resource entries belong to the `DefaultMaterials`
+archive. The runtime resolves built-ins directly from wheel metadata before any
+dataset construction. Keep their definitions out of the upstream ZIP checksum.
+
+The original DexSim archive is currently on its internal resource server; an
+explicit `EMBODICHAIN_DOWNLOAD_PREFIX` selects the catalog's versioned mirror
+path. Do not substitute an unverified public URL or depend on a DexSim source
+checkout. Preserve upstream manifests, relative auxiliary texture dependencies
+and attribution. The material runtime stages JSON only and does not copy PNGs;
+see [visual materials](../simulation-system/materials.md) for renderer, override
+and native ownership rules.
+
 ## Pretrained policy bundles
 
 `eval-policy --pretrained` reads the official model index at a pinned HF commit,

agent_context/topics/randomization/randomization.md

@@ -62,6 +62,13 @@ randomization remains active. See the owning
 
 - Camera extrinsics auto-detect the representation and frame: if `extrinsics.eye` is set → look-at mode (eye/target/up perturbation via `look_at`); otherwise → pose mode (pos/euler perturbation via `set_local_pose`), with `extrinsics.parent` selecting parent-relative pose and `parent=None` selecting arena-frame pose.
 - `set_rigid_object_visual_material` is deterministic (not random) but uses the same functor mechanism for fixed material assignment at reset.
+- Visual material randomization preserves selected environments. Shared material
+  instances require a full-environment selection and are mutated once per call;
+  partial shared selections fail before mutation. Empty selections are no-ops.
+  Solid and library tiers apply configured scalar PBR ranges. Texture pools use
+  normalized source paths and remain bounded after initialization. See
+  [material identity and lifetime](../simulation-system/materials.md) for
+  configuration conversion, instance reuse and topology replay.
 - Light randomization applies the **same values across all envs** (documented limitation).
 - HDR indirect-lighting events inform the environment's automatic native-ground
   visibility; emissive mode does not. See the deployment-owned

agent_context/topics/simulation-system/lifecycle.md

@@ -12,7 +12,8 @@ readiness; `spawn/scene.py` owns declaration coordination. The ordering is:
    native parents. Resolve/configure sources and commit Spawn topology.
 2. Apply Default articulation root properties before Direct GPU buffers capture
    them. Delegate runtime setup to `PhysicsBackend.prepare_spawn_runtime()`.
-3. Bind declared facades in place; publish their state through
+3. Replay the current per-segment [material assignments](materials.md) captured
+   before rebuilding, then bind declared facades in place; publish their state through
    `PhysicsBackend.sync_render_state()` without a physics step.
 4. Attach parented cameras and publish the ready topology revision only after
    every stage succeeds.

agent_context/topics/simulation-system/materials.md

@@ -0,0 +1,101 @@
+# Visual materials
+
+`embodichain/lab/sim/material.py` owns `VisualMaterialCfg`, material templates,
+native instance wrappers and segment assignment helpers. Its private
+`_material_desc_from_cfg()` validates and normalizes both runtime creation and
+`spawn/descriptors.py` lowering. Handwritten configurations fill historical
+defaults during construction. Preset configurations keep unspecified fields
+as `None`; only explicit values override resources. `from_dict()` constructs in
+that mode before filling defaults. Construction moves common parameter aliases
+to flat fields so `replace(field=None)` can restore inheritance. Do not infer
+override intent from equality
+with a default, or modify generic `configclass` for this policy.
+
+Scattering is parameter-driven in both modes. `VisualMaterialCfg` has no
+`material_type` field, and wrappers never force a native BRDF/BTDF/BSDF model.
+Basic handwritten materials keep native descriptor creation without a lobe
+override; advanced handwritten parameters use the manifest resolver and its
+renderer preflight. Dictionary input rejects the removed field rather than
+silently losing a legacy transmission choice. Migration examples live in the
+material guide linked below.
+
+`_material_presets.py` owns validated schema-v1 overrides, renderer preflight and
+World-scoped manifest/template caches. `SpawnScene._resolve_materials()` shares
+that path with runtime creation. Its resource definition registry reserves UIDs
+alongside native Spawn's simplified material registry; full resource definitions
+must not pass through the simplified `MaterialDesc` initializer. Bind the exact
+loaded child on `RenderDesc.material`, including across rebuilds. NoRender keeps
+resource definitions without downloading or creating native materials. Render-only
+facades stay declared and are skipped by runtime binding/reset in that mode.
+
+Built-in parameter presets resolve from wheel metadata without constructing the
+downloadable resource dataset. Both sources use complete manifests and the same
+override, identity and reset path. Human-facing previews and parameter tables
+live in the [material guide](../../../docs/source/overview/sim/sim_manager/rendering/materials.md).
+`embodichain/lab/scripts/preview_material.py` owns `preview-material`; the example
+delegates to it with a headless default. Help/list use the lightweight catalog
+without simulator imports. Rendering preflights the same configurations/backend
+validator as production before World creation. Batch exclusions require explicit
+`--compatible-only` and are reported; never switch renderers or silently drop
+parameters. Geometry, studio settings and direct-native comparisons belong to
+the preview, not the material factory. See the
+[CLI guide](../../../docs/source/guides/preview_material.md) and
+`tests/lab/scripts/test_preview_material.py`; keep capabilities in the catalog.
+
+Resource templates remain immutable. Each public UID and instance receives a
+separate child; canonical revision/preset/overrides select shared templates.
+Stage parameter variations before binding and keep texture paths in the shared
+resource cache. Full resource reset uses native `Material.reset_inst()` instead
+of rewriting only common fields. Native model changes after binding and NRD
+resource fixes are outside this contract. Catalog/distribution ownership lives
+in [data assets](../data-assets/data-assets.md); public usage and renderer limits
+are documented in the
+[material API](../../../docs/source/api_reference/embodichain/embodichain.lab.sim.material.rst).
+
+## Identity and state
+
+An unnamed configuration has no shared identity. Spawn derives its name from
+the object and normalized appearance; the manager names standalone runtime
+creations uniquely. Runtime and Spawn share the definition registry. Explicit
+UIDs share only equivalent definitions; conflicting properties fail before
+native writes. Equivalent aliases borrow current state without resetting it.
+Definitions remain reserved for the World lifetime, including across native
+unused-material cleanup. A template retains one wrapper per instance UID. Repeated
+creation returns that wrapper without resetting properties; explicit
+`set_default_properties()` applies a reset intentionally.
+
+Wrappers retain the exact native instance, including asset-parsed and reuse
+instances. Every setter uses that handle. Scalar/color reads query native
+state; DexSim's color getter supplies display-sRGB RGB, while configuration
+and setters accept RGBA. Alpha cannot be verified through that getter.
+Segment binding compares native material IDs rather than names.
+
+## Assignment lifetime
+
+Objects own their original per-segment assignments and selective reset
+baselines. Before a topology rebuild, `SpawnScene` captures current assignments
+of bound facades and replays them during binding. This preserves both deliberate
+runtime replacements and completed restores even when retained native
+descriptors still name an earlier replacement. A failed replay retains its
+snapshot for preparation retry; successful replay and close release it. Removal
+discards that object's pending entries before a same-UID replacement can bind.
+
+VisualObject additionally owns pose/visibility replay. Neither material replay
+nor rendering advances physics. Native material handles and texture pools must
+outlive their bindings and be released before their owning World.
+
+## Randomization boundary and validation
+
+[Visual randomization](../randomization/randomization.md) owns bounded native
+texture pools, selected-environment sampling and tier choices. Imported asset
+materials remain reset baselines; working instances are separate handles.
+For repeated updates, prefer pre-created textures from the owning simulation
+over per-call Tensor uploads.
+
+Primary CPU contracts are in `tests/sim/test_material.py`,
+`tests/sim/spawn/test_scene.py` and
+`tests/gym/envs/managers/test_randomize_visual_material.py`. Native parity,
+selective mutation, stable instance capacity and topology replay live in
+`tests/sim/test_material_integration.py`. The
+[acceptance plan](../../../docs/architecture/visual-material-acceptance.md)
+separates these checks from optical image and longer resource qualification.

agent_context/topics/simulation-system/simulation-system.md

@@ -10,6 +10,7 @@
 | Manager-level backend hooks and capabilities | `embodichain/lab/sim/physics/` |
 | Object-level Scene batch adapters | `embodichain/lab/sim/objects/backends/scene.py`, `newton.py` |
 | Object, renderer and physics configuration | `embodichain/lab/sim/cfg/` (`cfg/__init__.py` is the public facade) |
+| Visual material configuration, templates and native instances | `embodichain/lab/sim/material.py`; [material identity and lifetime](materials.md) |
 | Gym lifecycle and task scene construction | `embodichain/lab/gym/envs/base_env.py`, `embodied_env.py` |
 
 `embodichain.cli.sim` owns standalone simulation arguments without importing