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.

Classes

VisualMaterialCfg	Configuration for visual material with PBR properties for rasterization and ray tracing.
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

Bases: object

Configuration for visual material with PBR properties for rasterization and ray tracing.

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.
material_type	'BRDF', 'BTDF', 'BSDF'
metallic	Metallic factor (0.0 = dielectric, 1.0 = metallic)
metallic_texture	Metallic map
normal_texture	Normal map
roughness	Surface roughness (0.0 = smooth, 1.0 = rough)
roughness_texture	Roughness map
uid

Methods:

from_dict(cfg_dict)

ao_texture: str

Ambient occlusion map

base_color: list

Base color/diffuse color (RGBA)

base_color_texture: str

Base color texture map

emissive: list

emissive_intensity: float

classmethod from_dict(cfg_dict)

Return type:

VisualMaterialCfg

ior: float

Index of refraction for PBR materials, only used in ray tracing.

material_type: str

‘BRDF’, ‘BTDF’, ‘BSDF’

Type:

Ray tracing material type. Options

metallic: float

Metallic factor (0.0 = dielectric, 1.0 = metallic)

metallic_texture: str

Metallic map

normal_texture: str

Normal map

roughness: float

Surface roughness (0.0 = smooth, 1.0 = rough)

roughness_texture: str

Roughness map

uid: str

class embodichain.lab.sim.material.VisualMaterial

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.

Attributes:

MAT_TYPE_MAPPING
RT_MATERIAL_TYPES
inst
mat

Methods:

__init__(cfg, mat)
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)

MAT_TYPE_MAPPING: Dict[str, str] = {'BRDF': 'BRDF_GGX_SMITH', 'BSDF': 'BSDF_GGX_SMITH', 'BTDF': 'BTDF_GGX_SMITH'}

RT_MATERIAL_TYPES = ['BRDF', 'BTDF', 'BSDF']

__init__(cfg, mat)

create_instance(uid)

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()

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)

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)

Return type:

None

class embodichain.lab.sim.material.VisualMaterialInst

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:

mat

__init__(uid, mat, mat_inst=None)

classmethod from_existing(mat_inst)

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 mat: MaterialInst

set_ao_texture(texture_path=None, texture_data=None)

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)

Set base color/diffuse color.

Return type:

None

set_base_color_texture(texture_path=None, texture_data=None, texture_obj=None)

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)

Set emissive color.

Return type:

None

set_emissive_intensity(intensity)

Set emissive intensity multiplier.

Return type:

None

set_ior(ior)

Set index of refraction.

Return type:

None

set_metallic(metallic)

Set metallic factor.

Return type:

None

set_metallic_texture(texture_path=None, texture_data=None)

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)

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)

Set surface roughness.

Return type:

None

set_roughness_texture(texture_path=None, texture_data=None)

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

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