embodichain.lab.sim.material

embodichain.lab.sim.material#

Overview#

Visual materials control how scene objects are rendered. A VisualMaterialCfg describes PBR appearance properties (base color, metallic, roughness, emissive, …) used by both rasterization and ray-tracing passes; VisualMaterial is the resolved material definition and VisualMaterialInst is a per-object instance bound into the scene. ReuseSegmentState tracks per-render-body segment reuse so that segmentation masks stay consistent across replicated environments.

Default material presets#

The 24-preset catalog contains six built-in parameter definitions and 18 downloadable resources. See the material guide for parameter tables, individual previews and OfflineRT galleries.

Handwritten and asset-based materials use the same configuration type:

from embodichain.data import list_default_materials, get_default_material_info
from embodichain.lab.sim import VisualMaterialCfg
from embodichain.lab.sim.shapes import SphereCfg

cfg = VisualMaterialCfg.from_preset(
    "GlassClear", uid="glass", ior=1.6,
    parameters={"volume_attenuation_distance": 8.0},
)
material = sim.create_visual_material(cfg)
shape = SphereCfg(radius=0.25, visual_material=cfg)

The equivalent YAML is:

visual_material:
  preset: GlassClear
  uid: glass
  ior: 1.6
  parameters:
    volume_attenuation_distance: 8.0

With a preset, unspecified common fields remain None and inherit authored values. GlassClear therefore retains IOR 1.52 unless an override is supplied; explicit ior=1.5 sets 1.5. Zero and false values are explicit overrides. cfg.replace(ior=None) restores inheritance. copy(), replace() and dictionary/YAML round trips preserve the other explicit fields. Construct a new source with from_preset(); replace() retains the original fields. Handwritten configurations still fill the historical defaults at construction.

Common fields stay flat; native schema-v1 advanced parameters belong in parameters. emissive_intensity normalizes to emission_intensity. Common properties supplied through parameters are moved to their flat fields during construction, so replace(ior=None) also clears that form of override. The remaining advanced properties stay in parameters. Specifying the same native property in both places is an error. Unknown, nonfinite, incorrectly typed and out-of-range parameters fail before native loading. Presets reject texture replacement. Both handwritten and preset materials select scattering from optical parameters; material_type and the VisualMaterial.RT_MATERIAL_TYPES / MAT_TYPE_MAPPING constants have been removed. No default BRDF is explicitly written to native instances. Manual configurations with advanced parameters use a complete native manifest:

ice = VisualMaterialCfg(
    base_color=[1, 1, 1, 1], roughness=0.2, ior=1.31,
    parameters={"transmission": 1.0},
)

Transmission and other advanced handwritten parameters require OfflineRT. Remove material_type from stored Python/YAML configurations; from_dict rejects the removed key even if its value is None. Legacy BRDF/BTDF/BSDF labels are not silently converted because their scattering semantics are not interchangeable. See the migration example.

BrickRed, WoodOak, CeramicTileWhite, MarbleWhite, AsphaltDark, FabricGray, LeatherBrown, PlasticABSBlack, RubberBlack and SteelBrushed support hybrid, fast-rt and rt. ChromePolished, GoldPolished, CopperPolished, GlassClear, GlassFrosted, GlassSmoke, SkinHumanLight and SoapBubble require rt (OfflineRT). The built-ins PlasticMatteBlue, PlasticGlossyRed, GoldMetal and MirrorMetal support all three renderers. GlassClearSurface and GlassFrostedSurface require rt and configure surface transmission without volume absorption. Advanced parameter variations of a basic preset also require rt; the factory rejects incompatible renderers before downloading or loading assets. NoRender stores declarations without downloading or creating native materials. Render-only VisualObject facades remain unbound in that mode; their declarations are retained, while physics assets still prepare normally.

Variants stage only JSON before binding. Textures stay in the shared resource cache. Equivalent definitions reuse immutable native templates, while each UID has a separate child instance. Explicit resets restore the entire template, including advanced parameters and textures. Repeated creation preserves state. Native shader-model changes after binding are outside this interface’s scope; pre-create variants and bind their instances instead.

Catalog queries do not require a World or asset download. The six built-ins include native parameter defaults in the wheel and do not request the texture archive. Their metadata exposes source="builtin" and requires_download=False. Resource metadata uses source="resource". The archive is lazy, revisioned and checksum-verified. Pre-download with embodichain data download --name DefaultMaterials. The current upstream archive is hosted on the DexSim internal resource server. To use a mirror, set EMBODICHAIN_DOWNLOAD_PREFIX before importing EmbodiChain and place the same archive at materials/default-materials/ec9f748242c50b85/offlinert_materials.zip below that prefix. The wheel contains metadata, not PNGs. The downloaded archive retains the upstream README and manifests; source attribution and file digests are recorded in embodichain/data/default_materials.json.

The optional SoapBubbleInterior auxiliary material references SoapBubble’s textures. Hollow bubble shells and segmented skin meshes belong to preview geometry. The factory neither creates those shapes nor changes UVs. SkinHumanLight approximates diffuse transmission rather than random-walk subsurface scattering. Use embodichain preview-material for previews, optional segmented-face geometry and direct-native image comparisons; see the CLI guide.

Classes

`VisualMaterialCfg`	Manual PBR properties or explicit overrides of a default material preset.
`VisualMaterial`	Visual material definition in the simulation environment.
`VisualMaterialInst`	Instance of a visual material in the simulation environment.
`ReuseSegmentState`	Reuse state for one render-body segment of a parsed object.

class embodichain.lab.sim.material.VisualMaterialCfg[source]#

Bases: object

Manual PBR properties or explicit overrides of a default material preset.

With preset=None, unspecified common fields receive the historical defaults at construction. With a preset, None inherits the authored resource value. Serialization retains that distinction. Use from_preset() to construct a new preset configuration; replace preserves existing fields rather than switching configuration sources. Native scattering is selected by optical parameters, including parameters={"transmission": 1.0} for a transmitting material. Explicit BRDF/BTDF/BSDF model selection is not part of this configuration.

Attributes:

`ao_texture`	Ambient occlusion map
`base_color`	Base color/diffuse color (RGBA)
`base_color_texture`	Base color texture map
`emissive`
`emissive_intensity`
`ior`	Index of refraction for PBR materials, only used in ray tracing.
`metallic`	Metallic factor (0.0 = dielectric, 1.0 = metallic)
`metallic_texture`	Metallic map
`normal_texture`	Normal map
`parameters`	Native schema-v1 advanced parameters; cannot duplicate common fields.
`preset`	Default material name.
`roughness`	Surface roughness (0.0 = smooth, 1.0 = rough)
`roughness_texture`	Roughness map
`uid`	Explicit shared identity, or None for an automatically named material.

Methods:

`from_dict`(cfg_dict)	Construct manual defaults or preset overrides from Python/YAML data.
`from_preset`(name, *[, uid, parameters])	Construct explicit overrides of an authored default material.

ao_texture: str | None#: Ambient occlusion map

base_color: list[float] | None#: Base color/diffuse color (RGBA)

base_color_texture: str | None#: Base color texture map

emissive: list[float] | None#

emissive_intensity: float | None#

classmethod from_dict(cfg_dict)[source]#

Construct manual defaults or preset overrides from Python/YAML data.

Parameters:: cfg_dict (dict[str, Any]) – Serialized configuration, including optional preset.
Return type:: VisualMaterialCfg
Returns:: Configuration with inheritance preserved before defaults are filled.
Raises:: ValueError – The removed scattering selector or an unknown preset field is supplied. Describe optical properties explicitly.

classmethod from_preset(name, *, uid=None, parameters=None, **properties)[source]#

Construct explicit overrides of an authored default material.

Parameters:

name (str) – Case-sensitive catalog name, or SoapBubbleInterior.
uid (str | None) – Optional shared identity within the simulation World.
parameters (dict[str, Any] | None) – Advanced native parameters, such as volume absorption.
**properties (Any) – Common fields such as ior or roughness.

Return type:

VisualMaterialCfg

Returns:

A configuration retaining None for inherited common fields.

Raises:

ValueError – A preset, override, duplicate property or texture edit is invalid.
TypeError – An unknown configuration field is supplied.

ior: float | None#: Index of refraction for PBR materials, only used in ray tracing.

metallic: float | None#: Metallic factor (0.0 = dielectric, 1.0 = metallic)

metallic_texture: str | None#: Metallic map

normal_texture: str | None#: Normal map

parameters: dict[str, Any]#: Native schema-v1 advanced parameters; cannot duplicate common fields.

preset: str | None#: Default material name. Presets select scattering from native parameters.

roughness: float | None#: Surface roughness (0.0 = smooth, 1.0 = rough)

roughness_texture: str | None#: Roughness map

uid: str | None#: Explicit shared identity, or None for an automatically named material.

class embodichain.lab.sim.material.VisualMaterial[source]#

Bases: object

Visual material definition in the simulation environment.

A visual material is actually a material template from which material instances can be created. It holds multiple material instances, which is used to assign to different objects in the environment.

Methods:

`__init__`(cfg, mat, *[, initialize_default, ...])	Create a template wrapper or borrow an already configured native one.
`create_instance`(uid)	Create a new material instance from this material template.
`get_default_instance`()	Get the default material instance created with the same uid as the material template.
`get_instance`(uid)	Get an existing material instance by its uid.
`set_default_properties`(mat_inst, cfg)	Explicitly apply validated configuration to an existing instance.

Attributes:

`inst`
`mat`

__init__(cfg, mat, *, initialize_default=True, mat_inst=None)[source]#

Create a template wrapper or borrow an already configured native one.

Parameters:

cfg (VisualMaterialCfg) – Defaults for newly created material instances.
mat (Material) – Native template owned by the simulation.
initialize_default (bool) – Apply configuration to the native default instance. Disable for a known existing template to preserve runtime edits.
mat_inst (MaterialInst | None) – Exact child instance of an immutable native resource template.

create_instance(uid)[source]#

Create a new material instance from this material template.

Note

If the uid already exists, the existing instance will be returned.

Parameters:: uid (str) – Unique identifier for the material instance.
Returns:: The created material instance.
Return type:: VisualMaterialInst

get_default_instance()[source]#

Get the default material instance created with the same uid as the material template.

Returns:: The default material instance.
Return type:: VisualMaterialInst

get_instance(uid)[source]#

Get an existing material instance by its uid.

Parameters:: uid (str) – Unique identifier for the material instance.
Returns:: The material instance.
Return type:: VisualMaterialInst

property inst: VisualMaterialInst#

property mat: Material#

set_default_properties(mat_inst, cfg)[source]#

Explicitly apply validated configuration to an existing instance.

Parameters:

mat_inst (VisualMaterialInst) – Instance whose properties will be replaced.
cfg (VisualMaterialCfg) – Material properties to apply.

Return type:

None

class embodichain.lab.sim.material.VisualMaterialInst[source]#

Bases: object

Instance of a visual material in the simulation environment.

Methods:

`__init__`(uid, mat[, mat_inst])
`from_existing`(mat_inst)	Wrap an existing dexsim material instance without copying it.
`set_ao_texture`([texture_path, texture_data])	Set ambient occlusion texture from file path or texture data.
`set_base_color`(color)	Set base color/diffuse color.
`set_base_color_texture`([texture_path, ...])	Set base color texture from file path, tensor data, or a pre-created Texture.
`set_emissive`(emissive)	Set emissive color.
`set_emissive_intensity`(intensity)	Set emissive intensity multiplier.
`set_ior`(ior)	Set index of refraction.
`set_metallic`(metallic)	Set metallic factor.
`set_metallic_texture`([texture_path, ...])	Set metallic texture from file path or texture data.
`set_normal_texture`([texture_path, texture_data])	Set normal texture from file path or texture data.
`set_roughness`(roughness)	Set surface roughness.
`set_roughness_texture`([texture_path, ...])	Set roughness texture from file path or texture data.

Attributes:

`base_color`	Current native display-sRGB color (RGB); DexSim exposes no alpha getter.
`emissive`	Unscaled emissive RGB, including when intensity is zero.
`emissive_intensity`	Multiplier applied to emissive RGB by this wrapper.
`ior`	Current native index of refraction.
`mat`
`metallic`	Current native metallic factor.
`roughness`	Current native roughness.

__init__(uid, mat, mat_inst=None)[source]#

property base_color: list[float]#: Current native display-sRGB color (RGB); DexSim exposes no alpha getter.

property emissive: list[float]#: Unscaled emissive RGB, including when intensity is zero.

property emissive_intensity: float#: Multiplier applied to emissive RGB by this wrapper.

classmethod from_existing(mat_inst)[source]#

Wrap an existing dexsim material instance without copying it.

Parameters:: mat_inst (MaterialInst) – Existing dexsim material instance parsed from an asset.
Return type:: VisualMaterialInst
Returns:: The EmbodiChain wrapper for the existing instance.
Raises:: ValueError – If the material instance has no template.

property ior: float#: Current native index of refraction.

property mat: MaterialInst#

property metallic: float#: Current native metallic factor.

property roughness: float#: Current native roughness.

set_ao_texture(texture_path=None, texture_data=None)[source]#

Set ambient occlusion texture from file path or texture data.

Parameters:

texture_path (str) – Path to texture file
texture_data (Tensor | None) – Texture data as a torch.Tensor

Return type:

None

set_base_color(color)[source]#

Set base color/diffuse color.

Return type:: None

set_base_color_texture(texture_path=None, texture_data=None, texture_obj=None)[source]#

Set base color texture from file path, tensor data, or a pre-created Texture.

Parameters:

texture_path (str) – Path to texture file.
texture_data (Tensor | None) – Texture data as a torch.Tensor (uploaded each call).
texture_obj – A pre-created dexsim Texture object. When provided, it is bound directly without re-uploading (priority over texture_data).

Return type:

None

set_emissive(emissive)[source]#

Set emissive color.

Return type:: None

set_emissive_intensity(intensity)[source]#

Set emissive intensity multiplier.

Return type:: None

set_ior(ior)[source]#

Set index of refraction.

Return type:: None

set_metallic(metallic)[source]#

Set metallic factor.

Return type:: None

set_metallic_texture(texture_path=None, texture_data=None)[source]#

Set metallic texture from file path or texture data.

Parameters:

texture_path (str) – Path to texture file
texture_data (Tensor | None) – Texture data as a torch.Tensor

Return type:

None

set_normal_texture(texture_path=None, texture_data=None)[source]#

Set normal texture from file path or texture data.

Parameters:

texture_path (str) – Path to texture file
texture_data (Tensor | None) – Texture data as a torch.Tensor

Return type:

None

set_roughness(roughness)[source]#

Set surface roughness.

Return type:: None

set_roughness_texture(texture_path=None, texture_data=None)[source]#

Set roughness texture from file path or texture data.

Parameters:

texture_path (str) – Path to texture file
texture_data (Tensor | None) – Texture data as a torch.Tensor

Return type:

None

class embodichain.lab.sim.material.ReuseSegmentState[source]#

Bases: object

Reuse state for one render-body segment of a parsed object.

Used by randomize_visual_material to randomize on top of the material dexsim parsed from the asset. It creates a working material instance from the existing template, but does not create a new material template.

mesh_id#: The render-body segment index.

original_inst#: The dexsim MaterialInst parsed from the asset. Kept immutable and swapped back onto the render body for the “original” tier.

working_inst#: A VisualMaterialInst created from the first segment’s template and shared by sibling segments; mutated in place for the “library”/”solid” tiers.

Methods:

__init__(mesh_id, original_inst, working_inst)

Attributes:

`mesh_id`
`original_inst`
`working_inst`

__init__(mesh_id, original_inst, working_inst)#

mesh_id: int#

original_inst: MaterialInst#

working_inst: VisualMaterialInst#

embodichain.lab.sim.material

Contents

embodichain.lab.sim.material#

Overview#

Default material presets#