embodichain.lab.sim

embodichain.lab.sim#

Submodules

`sim_manager`
`cfg`
`common`
`material`
`shapes`
`objects`
`sensors`
`solvers`
`utility`

Simulation Manager#

class embodichain.lab.sim.SimulationManager[source]#

Bases: object

Global Embodied AI simulation manager.

This class is used to manage the global simulation environment and simulated assets.

assets loading, creation, modification and deletion.
- assets include robots, fixed actors, dynamic actors and background.
manager the scenes and the simulation environment.
- parallel scenes simulation on both CPU and GPU.
- sensors arrangement
- lighting and indirect lighting
- physics simulation parameters control
…

Note

The arena is used as a standalone space for robots to simulate in. When build_multiple_arenas() is called,
it will create multiple arenas in a grid pattern. Meanwhile, each simulation assets adding interface will take an additional parameter arena_index to specify which arena to place the asset. The name of the asset to be added will be appended with the arena index to avoid name conflict.
In GUI mode, the physics will be set to a fps (or a wait time for manual mode) for better visualization.

Parameters:: sim_config (SimulationManagerCfg, optional) – simulation configuration. Defaults to SimulationManagerCfg().

Attributes:

`SUPPORTED_SENSOR_TYPES`
`asset_uids`	Get all assets uid in the simulation.
`is_physics_manually_update`
`is_rt_enabled`	Check if Ray Tracing rendering backend is enabled.
`is_use_gpu_physics`	Check if the physics simulation is using GPU.
`num_envs`	Get the number of arenas in the simulation.

Methods:

`__init__`([sim_config, bounce_threshold, ...])
`add_articulation`(cfg)	Add an articulation to the scene.
`add_light`(cfg)	Create a light in the scene.
`add_rigid_object`(cfg)	Add a rigid object to the scene.
`add_rigid_object_group`(cfg)	Add a rigid object group to the scene.
`add_robot`(cfg)	Add a Robot to the scene.
`add_sensor`(sensor_cfg)	General interface to add a sensor to the scene and returns a handle.
`add_soft_object`(cfg)	Add a soft object to the scene.
`build_multiple_arenas`(num[, space])	Build multiple arenas in a grid pattern.
`clean_materials`()
`close_window`()	Close the simulation window.
`create_visual_material`(cfg)	Create a visual material with given configuration.
`destroy`()	Destroy all simulated assets and release resources.
`disable_gizmo`(uid[, control_part])	Disable and remove gizmo for a robot.
`draw_marker`(cfg)	Draw visual markers in the simulation scene for debugging and visualization.
`enable_gizmo`(uid[, control_part, gizmo_cfg])	Enable gizmo control for any simulation object (Robot, RigidObject, Camera, etc.).
`enable_physics`(enable)	Enable or disable physics simulation.
`get_articulation`(uid)	Get an articulation by its unique ID.
`get_articulation_uid_list`()	Get current articulation uid list
`get_asset`(uid)	Get an asset by its UID.
`get_default_resources`()	Get the default resources instance.
`get_env`([arena_index])	Get the arena or env by index.
`get_gizmo`(uid[, control_part])	Get gizmo instance for a robot.
`get_light`(uid)	Get a light by its UID.
`get_rigid_object`(uid)	Get a rigid object by its unique ID.
`get_rigid_object_group`(uid)	Get a rigid object group by its unique ID.
`get_rigid_object_uid_list`()	Get current rigid body uid list
`get_robot`(uid)	Get a Robot by its unique ID.
`get_robot_uid_list`()	Retrieves a list of unique identifiers (UIDs) for all robots in the V2 system.
`get_sensor`(uid)	Get a sensor by its UID.
`get_sensor_uid_list`()	Get current sensor uid list
`get_texture_cache`([key])	Get the texture from the global texture cache.
`get_visual_material`(uid)	Get visual material by UID.
`get_world`()
`has_gizmo`(uid[, control_part])	Check if a gizmo exists for the given UID and control part.
`init_gpu_physics`()	Initialize the GPU physics simulation.
`list_gizmos`()	List all active gizmos and their status.
`open_window`()	Open the simulation window.
`remove_asset`(uid)	Remove an asset by its UID.
`remove_marker`(name)	Remove markers (including axis) with the given name.
`render_camera_group`()	Render all camera group in the simulation.
`reset_objects_state`([env_ids])	Reset the state of all objects in the scene.
`set_default_background`()	Set default background.
`set_emission_light`([color, intensity])	Set environment emission light.
`set_gizmo_visibility`(uid, visible[, ...])	Set the visibility of a gizmo by uid and optional control_part.
`set_indirect_lighting`(name)	Set indirect lighting.
`set_manual_update`(enable)	Set manual update for physics simulation.
`set_texture_cache`(key, texture)	Set the texture to the global texture cache.
`toggle_gizmo_visibility`(uid[, control_part])	Toggle the visibility of a gizmo by uid and optional control_part.
`update`([physics_dt, step])	Update the physics.
`update_gizmos`()	Update all active gizmos.

SUPPORTED_SENSOR_TYPES = {'Camera': <class 'embodichain.lab.sim.sensors.camera.Camera'>, 'StereoCamera': <class 'embodichain.lab.sim.sensors.stereo.StereoCamera'>}#

__init__(sim_config=SimulationManagerCfg(width=1920, height=1080, headless=False, enable_rt=False, enable_denoiser=True, spp=64, gpu_id=0, thread_mode=<ThreadMode.RENDER_SHARE_ENGINE: 0>, arena_space=5.0, physics_dt=0.01, sim_device='cpu', physics_config=PhysicsCfg(gravity=array([ 0., 0., -9.81]), bounce_threshold=2.0, enable_pcm=True, enable_tgs=True, enable_ccd=False, enable_enhanced_determinism=False, enable_friction_every_iteration=True, length_tolerance=0.05, speed_tolerance=0.25), gpu_memory_config=GPUMemoryCfg(temp_buffer_capacity=16777216, max_rigid_contact_count=524288, max_rigid_patch_count=262144, heap_capacity=67108864, found_lost_pairs_capacity=33554432, found_lost_aggregate_pairs_capacity=1024, total_aggregate_pairs_capacity=1024)))[source]#

add_articulation(cfg)[source]#

Add an articulation to the scene.

Parameters:: cfg (ArticulationCfg) – Configuration for the articulation.
Returns:: The added articulation instance handle.
Return type:: Articulation

add_light(cfg)[source]#

Create a light in the scene.

Parameters:: cfg (LightCfg) – Configuration for the light, including type, color, intensity, and radius.
Returns:: The created light instance.
Return type:: Light

add_rigid_object(cfg)[source]#

Add a rigid object to the scene.

Parameters:: cfg (RigidObjectCfg) – Configuration for the rigid object.
Returns:: The added rigid object instance handle.
Return type:: RigidObject

add_rigid_object_group(cfg)[source]#

Add a rigid object group to the scene.

Parameters:: cfg (RigidObjectGroupCfg) – Configuration for the rigid object group.
Return type:: RigidObjectGroup

add_robot(cfg)[source]#

Add a Robot to the scene.

Parameters:: cfg (RobotCfg) – Configuration for the robot.
Returns:: The added robot instance handle, or None if failed.
Return type:: Optional[Robot]

add_sensor(sensor_cfg)[source]#

General interface to add a sensor to the scene and returns a handle.

Parameters:: sensor_cfg (SensorCfg) – configuration for the sensor.
Returns:: The added sensor instance handle.
Return type:: BaseSensor

add_soft_object(cfg)[source]#

Add a soft object to the scene.

Parameters:: cfg (SoftObjectCfg) – Configuration for the soft object.
Returns:: The added soft object instance handle.
Return type:: SoftObject

property asset_uids: List[str]#

Get all assets uid in the simulation.

The assets include lights, sensors, robots, rigid objects and articulations.

Returns:: list of all assets uid.
Return type:: List[str]

build_multiple_arenas(num, space=None)[source]#

Build multiple arenas in a grid pattern.

This interface is used for vectorized simulation.

Parameters:

num (int) – number of arenas to build.
space (float, optional) – The distance between each arena. Defaults to the arena_space in sim_config.

Return type:

None

clean_materials()[source]#

close_window()[source]#

Close the simulation window.

Return type:: None

create_visual_material(cfg)[source]#

Create a visual material with given configuration.

Parameters:: cfg (VisualMaterialCfg) – configuration for the visual material.
Returns:: the created visual material instance handle.
Return type:: VisualMaterial

destroy()[source]#

Destroy all simulated assets and release resources.

Return type:: None

disable_gizmo(uid, control_part=None)[source]#

Disable and remove gizmo for a robot.

Parameters:

uid (str) – Object UID to disable gizmo for
control_part (Optional[str], optional) – Control part name for robots. Defaults to None.

Return type:

None

draw_marker(cfg)[source]#

Draw visual markers in the simulation scene for debugging and visualization.

Parameters:

cfg (MarkerCfg) –

Marker configuration with the following key parameters: - name (str): Unique identifier for the marker group - marker_type (str): Type of marker (“axis” currently supported) - axis_xpos (np.ndarray | List[np.ndarray]): 4x4 transformation matrices

for marker positions and orientations

axis_size (float): Thickness of axis arrows
axis_len (float): Length of axis arrows
arena_index (int): Arena index for placement (-1 for global)

Returns:

List of created marker handles, False if invalid input, None if no poses provided.

Return type:

List[MeshObject]

Example

`python cfg = MarkerCfg(name="test_axis", marker_type="axis", axis_xpos=np.eye(4)) markers = sim.draw_marker(cfg) `

enable_gizmo(uid, control_part=None, gizmo_cfg=None)[source]#

Enable gizmo control for any simulation object (Robot, RigidObject, Camera, etc.).

Parameters:

uid (str) – UID of the object to attach gizmo to (searches in robots, rigid_objects, sensors, etc.)
control_part (Optional[str], optional) – Control part name for robots. Defaults to “arm”.
gizmo_cfg (object, optional) – Gizmo configuration object. Defaults to None.

Return type:

None

enable_physics(enable)[source]#

Enable or disable physics simulation.

Parameters:: enable (bool) – whether to enable physics simulation.
Return type:: None

get_articulation(uid)[source]#

Get an articulation by its unique ID.

Parameters:: uid (str) – The unique ID of the articulation.
Returns:: The articulation instance if found, otherwise None.
Return type:: Optional[Articulation]

get_articulation_uid_list()[source]#

Get current articulation uid list

Returns:: list of articulation uid.
Return type:: List[str]

get_asset(uid)[source]#

Get an asset by its UID.

The asset can be a rigid object, articulation or robot.

Parameters:: uid (str) – The UID of the asset.
Return type:: Union[Light, BaseSensor, Robot, RigidObject, Articulation, None]

get_default_resources()[source]#

Get the default resources instance.

Returns:: The default resources path.
Return type:: SimResources

get_env(arena_index=-1)[source]#

Get the arena or env by index.

If arena_index is -1, return the global env. If arena_index is valid, return the corresponding arena.

Parameters:: arena_index (int, optional) – the index of arena to get, -1 for global env. Defaults to -1.
Returns:: The arena or global env.
Return type:: dexsim.environment.Arena

get_gizmo(uid, control_part=None)[source]#

Get gizmo instance for a robot.

Parameters:

uid (str) – Object UID
control_part (Optional[str], optional) – Control part name for robots. Defaults to None.

Returns:

Gizmo instance if found, None otherwise.

Return type:

object

get_light(uid)[source]#

Get a light by its UID.

Parameters:: uid (str) – The UID of the light.
Returns:: The light instance if found, otherwise None.
Return type:: Light | None

get_rigid_object(uid)[source]#

Get a rigid object by its unique ID.

Parameters:: uid (str) – The unique ID of the rigid object.
Returns:: The rigid object instance if found, otherwise None.
Return type:: Optional[RigidObject]

get_rigid_object_group(uid)[source]#

Get a rigid object group by its unique ID.

Parameters:: uid (str) – The unique ID of the rigid object group.
Returns:: The rigid object group instance if found, otherwise None.
Return type:: Optional[RigidObjectGroup]

get_rigid_object_uid_list()[source]#

Get current rigid body uid list

Returns:: list of rigid body uid.
Return type:: List[str]

get_robot(uid)[source]#

Get a Robot by its unique ID.

Parameters:: uid (str) – The unique ID of the robot.
Returns:: The robot instance if found, otherwise None.
Return type:: Optional[Robot]

get_robot_uid_list()[source]#

Retrieves a list of unique identifiers (UIDs) for all robots in the V2 system.

Returns:: A list containing the UIDs of the robots.
Return type:: list

get_sensor(uid)[source]#

Get a sensor by its UID.

Parameters:: uid (str) – The UID of the sensor.
Returns:: The sensor instance if found, otherwise None.
Return type:: BaseSensor | None

get_sensor_uid_list()[source]#

Get current sensor uid list

Returns:: list of sensor uid.
Return type:: List[str]

get_texture_cache(key=None)[source]#

Get the texture from the global texture cache.

Parameters:: key (str, optional) – The key of the texture. If None, return None. Defaults to None.
Returns:: The texture if found, otherwise None.
Return type:: Optional[Union[torch.Tensor, List[torch.Tensor]]]

get_visual_material(uid)[source]#

Get visual material by UID.

Parameters:: uid (str) – uid of visual material.
Return type:: VisualMaterial

get_world()[source]#

Return type:: World

has_gizmo(uid, control_part=None)[source]#

Check if a gizmo exists for the given UID and control part.

Parameters:

uid (str) – Object UID to check
control_part (Optional[str], optional) – Control part name for robots. Defaults to None.

Returns:

True if gizmo exists, False otherwise.

Return type:

bool

init_gpu_physics()[source]#

Initialize the GPU physics simulation.

Return type:: None

property is_physics_manually_update: bool#

property is_rt_enabled: bool#: Check if Ray Tracing rendering backend is enabled.

property is_use_gpu_physics: bool#: Check if the physics simulation is using GPU.

list_gizmos()[source]#

List all active gizmos and their status.

Returns:: Dictionary mapping gizmo keys (uid:control_part) to gizmo active status.
Return type:: Dict[str, bool]

property num_envs: int#

Get the number of arenas in the simulation.

Returns:: number of arenas.
Return type:: int

open_window()[source]#

Open the simulation window.

Return type:: None

remove_asset(uid)[source]#

Remove an asset by its UID.

The asset can be a light, sensor, robot, rigid object or articulation.

Note

Currently, lights and sensors are not supported to be removed.

Parameters:: uid (str) – The UID of the asset.
Returns:: True if the asset is removed successfully, otherwise False.
Return type:: bool

remove_marker(name)[source]#

Remove markers (including axis) with the given name.

Parameters:: name (str) – The name of the marker to remove.
Returns:: True if the marker was removed successfully, False otherwise.
Return type:: bool

render_camera_group()[source]#

Render all camera group in the simulation.

Note: This interface is only valid when Ray Tracing rendering backend is enabled.

Return type:: None

reset_objects_state(env_ids=None)[source]#

Reset the state of all objects in the scene.

Parameters:: env_ids (Optional[Sequence[int]]) – The environment IDs to reset. If None, reset all environments.
Return type:: None

set_default_background()[source]#

Set default background.

Return type:: None

set_emission_light(color=None, intensity=None)[source]#

Set environment emission light.

Parameters:

color (Sequence[float]) – color of the light.
intensity (float) – intensity of the light.

Return type:

None

set_gizmo_visibility(uid, visible, control_part=None)[source]#

Set the visibility of a gizmo by uid and optional control_part.

Return type:: None

set_indirect_lighting(name)[source]#

Set indirect lighting.

Parameters:: name (str) – name of path of the indirect lighting.
Return type:: None

set_manual_update(enable)[source]#

Set manual update for physics simulation.

If enable is True, the physics simulation will be updated manually by calling update(). If enable is False, the physics simulation will be updated automatically by the engine thread loop.

Parameters:: enable (bool) – whether to enable manual update.
Return type:: None

set_texture_cache(key, texture)[source]#

Set the texture to the global texture cache.

Parameters:

key (str) – The key of the texture.
texture (Union[torch.Tensor, List[torch.Tensor]]) – The texture data.

Return type:

None

toggle_gizmo_visibility(uid, control_part=None)[source]#

Toggle the visibility of a gizmo by uid and optional control_part. Returns the new visibility state (True=visible, False=hidden), or None if not found.

Return type:: bool

update(physics_dt=None, step=10)[source]#

Update the physics.

Parameters:

physics_dt (Optional[float], optional) – the time step for physics simulation. Defaults to None.
step (int, optional) – the number of steps to update physics. Defaults to 10.

Return type:

None

update_gizmos()[source]#: Update all active gizmos.

class embodichain.lab.sim.SimulationManagerCfg[source]#

Bases: object

Global robot simulation configuration.

Attributes:

`arena_space`	The distance between each arena when building multiple arenas.
`enable_denoiser`	Whether to enable denoising for ray tracing rendering.
`enable_rt`	Whether to enable ray tracing rendering.
`gpu_id`	The gpu index that the simulation engine will be used.
`gpu_memory_config`	The GPU memory configuration parameters.
`headless`	Whether to run the simulation in headless mode (no Window).
`height`	The height of the simulation window.
`physics_config`	The physics configuration parameters.
`physics_dt`	The time step for the physics simulation.
`sim_device`	The device for the simulation engine.
`spp`	Samples per pixel for ray tracing rendering.
`thread_mode`	The threading mode for the simulation engine.
`width`	The width of the simulation window.

arena_space: float#: The distance between each arena when building multiple arenas.

enable_denoiser: bool#: Whether to enable denoising for ray tracing rendering.

enable_rt: bool#: Whether to enable ray tracing rendering.

gpu_id: int#

The gpu index that the simulation engine will be used.

Note: it will affect the gpu physics device if using gpu physics.

gpu_memory_config: GPUMemoryCfg#: The GPU memory configuration parameters.

headless: bool#: Whether to run the simulation in headless mode (no Window).

height: int#: The height of the simulation window.

physics_config: PhysicsCfg#: The physics configuration parameters.

physics_dt: float#: The time step for the physics simulation.

sim_device: Union[str, device]#: The device for the simulation engine. Can be ‘cpu’, ‘cuda’, or a torch.device object.

spp: int#: Samples per pixel for ray tracing rendering. This parameter is only valid when ray tracing is enabled and enable_denoiser is False.

thread_mode: ThreadMode#

The threading mode for the simulation engine.

RENDER_SHARE_ENGINE: The rendering thread shares the same thread with the simulation engine.
RENDER_SCENE_SHARE_ENGINE: The rendering thread and scene update thread share the same thread with the simulation engine.

width: int#: The width of the simulation window.

Configurations#

Classes:

`ArticulationCfg`	Configuration for an articulation asset in the simulation.
`GPUMemoryCfg`	A gpu memory configuration dataclass that neatly holds all parameters that configure physics GPU memory for simulation
`JointDrivePropertiesCfg`	Properties to define the drive mechanism of a joint.
`LightCfg`	Configuration for a light asset in the simulation.
`MarkerCfg`	Configuration for visual markers in the simulation.
`ObjectBaseCfg`	Base configuration for an asset in the simulation.
`PhysicsCfg`	PhysicsCfg(gravity: 'np.ndarray' = <factory>, bounce_threshold: 'float' = <factory>, enable_pcm: 'bool' = <factory>, enable_tgs: 'bool' = <factory>, enable_ccd: 'bool' = <factory>, enable_enhanced_determinism: 'bool' = <factory>, enable_friction_every_iteration: 'bool' = <factory>, length_tolerance: 'float' = <factory>, speed_tolerance: 'float' = <factory>)
`RigidBodyAttributesCfg`	Physical attributes for rigid bodies.
`RigidObjectCfg`	Configuration for a rigid body asset in the simulation.
`RigidObjectGroupCfg`	Configuration for a rigid object group asset in the simulation.
`RobotCfg`	RobotCfg(uid: 'Union[str, None]' = <factory>, init_pos: 'tuple[float, float, float]' = <factory>, init_rot: 'tuple[float, float, float]' = <factory>, init_local_pose: 'Optional[np.ndarray]' = <factory>, fpath: 'str' = <factory>, drive_pros: 'JointDrivePropertiesCfg' = <factory>, body_scale: 'Union[tuple, list]' = <factory>, attrs: 'RigidBodyAttributesCfg' = <factory>, fix_base: 'bool' = <factory>, disable_self_collision: 'bool' = <factory>, init_qpos: 'Union[torch.Tensor, np.ndarray, Sequence[float]]' = <factory>, sleep_threshold: 'float' = <factory>, min_position_iters: 'int' = <factory>, min_velocity_iters: 'int' = <factory>, build_pk_chain: 'bool' = <factory>, control_parts: 'Union[Dict[str, List[str]], None]' = <factory>, urdf_cfg: 'Optional[URDFCfg]' = <factory>, solver_cfg: 'Union[SolverCfg, Dict[str, SolverCfg], None]' = <factory>)
`SoftObjectCfg`	Configuration for a soft body asset in the simulation.
`SoftbodyPhysicalAttributesCfg`	SoftbodyPhysicalAttributesCfg(youngs: 'float' = <factory>, poissons: 'float' = <factory>, dynamic_friction: 'float' = <factory>, elasticity_damping: 'float' = <factory>, material_model: 'SoftBodyMaterialModel' = <factory>, enable_kinematic: 'bool' = <factory>, enable_ccd: 'bool' = <factory>, enable_self_collision: 'bool' = <factory>, has_gravity: 'bool' = <factory>, self_collision_stress_tolerance: 'float' = <factory>, collision_mesh_simplification: 'bool' = <factory>, self_collision_filter_distance: 'float' = <factory>, vertex_velocity_damping: 'float' = <factory>, linear_damping: 'float' = <factory>, sleep_threshold: 'float' = <factory>, settling_threshold: 'float' = <factory>, settling_damping: 'float' = <factory>, mass: 'float' = <factory>, density: 'float' = <factory>, max_depenetration_velocity: 'float' = <factory>, max_velocity: 'float' = <factory>, min_position_iters: 'int' = <factory>, min_velocity_iters: 'int' = <factory>)
`SoftbodyVoxelAttributesCfg`	SoftbodyVoxelAttributesCfg(triangle_remesh_resolution: 'int' = <factory>, triangle_simplify_target: 'int' = <factory>, maximal_edge_length: 'float' = <factory>, simulation_mesh_resolution: 'int' = <factory>, simulation_mesh_output_obj: 'bool' = <factory>)
`URDFCfg`	Standalone configuration class for URDF assembly.

class embodichain.lab.sim.cfg.ArticulationCfg[source]#

Bases: ObjectBaseCfg

Configuration for an articulation asset in the simulation.

This class extends the base asset configuration to include specific properties for articulations, such as joint drive properties, physical attributes.

Attributes:

`attrs`	Physical attributes for all links .
`body_scale`	Scale of the articulation in the simulation world frame.
`build_pk_chain`	Whether to build pytorch-kinematics chain for forward kinematics and jacobian computation.
`disable_self_collision`	Whether to enable or disable self-collisions.
`drive_pros`	Properties to define the drive mechanism of a joint.
`fix_base`	Whether to fix the base of the articulation.
`fpath`	Path to the articulation asset file.
`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_qpos`	Initial joint positions of the articulation.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`min_position_iters`	[1,255].
`min_velocity_iters`	[0,255].
`sleep_threshold`	[0, max_float32]
`uid`

attrs: RigidBodyAttributesCfg#: Physical attributes for all links .

body_scale: Union[tuple, list]#: Scale of the articulation in the simulation world frame.

build_pk_chain: bool#: Whether to build pytorch-kinematics chain for forward kinematics and jacobian computation.

disable_self_collision: bool#: Whether to enable or disable self-collisions.

drive_pros: JointDrivePropertiesCfg#: Properties to define the drive mechanism of a joint.

fix_base: bool#

Whether to fix the base of the articulation.

Set to True for articulations that should not move, such as a fixed base robot arm or a door. Set to False for articulations that should move freely, such as a mobile robot or a humanoid robot.

fpath: str#: Path to the articulation asset file.

init_local_pose: Optional[ndarray]#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_qpos: Union[Tensor, ndarray, Sequence[float]]#

Initial joint positions of the articulation.

If None, the joint positions will be set to zero. If provided, it should be a array of shape (num_joints,).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

min_position_iters: int#

[1,255].

Type:: Number of position iterations the solver should perform for this articulation. Range

min_velocity_iters: int#

[0,255].

Type:: Number of velocity iterations the solver should perform for this articulation. Range

sleep_threshold: float#

[0, max_float32]

Type:: Energy below which the articulation may go to sleep. Range

uid: Optional[str]#

class embodichain.lab.sim.cfg.GPUMemoryCfg[source]#

Bases: object

A gpu memory configuration dataclass that neatly holds all parameters that configure physics GPU memory for simulation

Attributes:

`found_lost_aggregate_pairs_capacity`
`found_lost_pairs_capacity`
`heap_capacity`
`max_rigid_contact_count`	Increase this if you get 'Contact buffer overflow detected'
`max_rigid_patch_count`	Increase this if you get 'Patch buffer overflow detected'
`temp_buffer_capacity`	overflowing initial allocation size, increase capacity to at least %.'
`total_aggregate_pairs_capacity`

found_lost_aggregate_pairs_capacity: int#

found_lost_pairs_capacity: int#

heap_capacity: int#

max_rigid_contact_count: int#: Increase this if you get ‘Contact buffer overflow detected’

max_rigid_patch_count: int#: Increase this if you get ‘Patch buffer overflow detected’

temp_buffer_capacity: int#

overflowing initial allocation size, increase capacity to at least %.’

Type:: Increase this if you get ‘PxgPinnedHostLinearMemoryAllocator

total_aggregate_pairs_capacity: int#

class embodichain.lab.sim.cfg.JointDrivePropertiesCfg[source]#

Bases: object

Properties to define the drive mechanism of a joint.

Attributes:

`damping`	Damping of the joint drive.
`drive_type`	Joint drive type to apply.
`friction`	Friction coefficient of the joint
`max_effort`	Maximum effort that can be applied to the joint (in kg-m^2/s^2).
`max_velocity`	Maximum velocity that the joint can reach (in rad/s or m/s).
`stiffness`	Stiffness of the joint drive.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

damping: Union[Dict[str, float], float]#

Damping of the joint drive.

The unit depends on the joint model:

For linear joints, the unit is kg-m/s (N-s/m).
For angular joints, the unit is kg-m^2/s/rad (N-m-s/rad).

drive_type: Literal['force', 'acceleration']#

Joint drive type to apply.

If the drive type is “force”, then the joint is driven by a force and the acceleration is computed based on the force applied. If the drive type is “acceleration”, then the joint is driven by an acceleration and the force is computed based on the acceleration applied.

friction: Union[Dict[str, float], float]#: Friction coefficient of the joint

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: JointDrivePropertiesCfg

max_effort: Union[Dict[str, float], float]#: Maximum effort that can be applied to the joint (in kg-m^2/s^2).

max_velocity: Union[Dict[str, float], float]#

Maximum velocity that the joint can reach (in rad/s or m/s).

For linear joints, this is the maximum linear velocity with unit m/s. For angular joints, this is the maximum angular velocity with unit rad/s.

stiffness: Union[Dict[str, float], float]#

Stiffness of the joint drive.

The unit depends on the joint model:

For linear joints, the unit is kg-m/s^2 (N/m).
For angular joints, the unit is kg-m^2/s^2/rad (N-m/rad).

class embodichain.lab.sim.cfg.LightCfg[source]#

Bases: ObjectBaseCfg

Configuration for a light asset in the simulation.

This class extends the base asset configuration to include specific properties for lights,

Attributes:

`color`
`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`intensity`	Intensity of the light source with unit of watts/m^2.
`light_type`
`radius`	Falloff of the light, only used for point light.
`uid`

color: tuple[float, float, float]#

init_local_pose: Optional[ndarray]#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

intensity: float#: Intensity of the light source with unit of watts/m^2.

light_type: Literal['point']#

radius: float#: Falloff of the light, only used for point light.

uid: Optional[str]#

class embodichain.lab.sim.cfg.MarkerCfg[source]#

Bases: object

Configuration for visual markers in the simulation.

This class defines properties for creating visual markers such as coordinate frames, lines, and points that can be used for debugging, visualization, or reference purposes in the simulation environment.

Attributes:

`arena_index`	Index of the arena where the marker should be placed.
`arrow_type`	Type of arrow head for axis markers (e.g., CONE, ARROW, etc.).
`axis_len`	Length of each axis arm in meters.
`axis_size`	Thickness/size of the axis lines in meters.
`axis_xpos`	List of 4x4 transformation matrices defining the position and orientation of each axis marker.
`corner_type`	Type of corner/joint visualization for axis markers (e.g., SPHERE, CUBE, etc.).
`line_color`	RGBA color values for the marker lines.
`marker_type`	Type of marker to display.
`name`	Name of the marker for identification purposes.

arena_index: int#: Index of the arena where the marker should be placed. -1 means all arenas.

arrow_type: AxisArrowType#: Type of arrow head for axis markers (e.g., CONE, ARROW, etc.).

axis_len: float#: Length of each axis arm in meters.

axis_size: float#: Thickness/size of the axis lines in meters.

axis_xpos: List[ndarray]#: List of 4x4 transformation matrices defining the position and orientation of each axis marker.

corner_type: AxisCornerType#: Type of corner/joint visualization for axis markers (e.g., SPHERE, CUBE, etc.).

line_color: List[float]#: RGBA color values for the marker lines. Values should be between 0.0 and 1.0.

marker_type: Literal['axis', 'line', 'point']#: Type of marker to display. Can be ‘axis’ (3D coordinate frame), ‘line’, or ‘point’. (only axis supported now)

name: str#: Name of the marker for identification purposes.

class embodichain.lab.sim.cfg.ObjectBaseCfg[source]#

Bases: object

Base configuration for an asset in the simulation.

This class defines the basic properties of an asset, such as its type, initial state, and collision group. It is used as a base class for specific asset configurations.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

Attributes:

`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`uid`

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: ObjectBaseCfg

init_local_pose: Optional[ndarray]#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

uid: Optional[str]#

class embodichain.lab.sim.cfg.PhysicsCfg[source]#

Bases: object

PhysicsCfg(gravity: ‘np.ndarray’ = <factory>, bounce_threshold: ‘float’ = <factory>, enable_pcm: ‘bool’ = <factory>, enable_tgs: ‘bool’ = <factory>, enable_ccd: ‘bool’ = <factory>, enable_enhanced_determinism: ‘bool’ = <factory>, enable_friction_every_iteration: ‘bool’ = <factory>, length_tolerance: ‘float’ = <factory>, speed_tolerance: ‘float’ = <factory>)

Attributes:

`bounce_threshold`
`enable_ccd`
`enable_enhanced_determinism`
`enable_friction_every_iteration`
`enable_pcm`
`enable_tgs`
`gravity`
`length_tolerance`	The length tolerance for the simulation.
`speed_tolerance`	The speed tolerance for the simulation.

Methods:

to_dexsim_args()

Convert to dexsim physics args dictionary.

bounce_threshold: float#

enable_ccd: bool#

enable_enhanced_determinism: bool#

enable_friction_every_iteration: bool#

enable_pcm: bool#

enable_tgs: bool#

gravity: ndarray#

length_tolerance: float#

The length tolerance for the simulation.

Note: the larger the tolerance, the faster the simulation will be.

speed_tolerance: float#

The speed tolerance for the simulation.

Note: the larger the tolerance, the faster the simulation will be.

to_dexsim_args()[source]#

Convert to dexsim physics args dictionary.

Return type:: Dict[str, Any]

class embodichain.lab.sim.cfg.RigidBodyAttributesCfg[source]#

Bases: object

Physical attributes for rigid bodies.

There are three parts of attributes that can be set: 1. The dynamic properties, such as mass, damping, etc. 2. The collision properties. 3. The physics material properties.

Attributes:

`angular_damping`
`contact_offset`
`density`
`dynamic_friction`
`enable_ccd`
`enable_collision`
`linear_damping`
`mass`
`max_angular_velocity`
`max_depenetration_velocity`
`max_linear_velocity`
`min_position_iters`
`min_velocity_iters`
`rest_offset`
`restitution`
`sleep_threshold`
`static_friction`

Methods:

`attr`()	Convert to dexsim PhysicalAttr
`from_dict`(init_dict)	Initialize the configuration from a dictionary.

angular_damping: float#

attr()[source]#

Convert to dexsim PhysicalAttr

Return type:: PhysicalAttr

contact_offset: float#

density: float#

dynamic_friction: float#

enable_ccd: bool#

enable_collision: bool#

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: RigidBodyAttributesCfg

linear_damping: float#

mass: float#

max_angular_velocity: float#

max_depenetration_velocity: float#

max_linear_velocity: float#

min_position_iters: int#

min_velocity_iters: int#

rest_offset: float#

restitution: float#

sleep_threshold: float#

static_friction: float#

class embodichain.lab.sim.cfg.RigidObjectCfg[source]#

Bases: ObjectBaseCfg

Configuration for a rigid body asset in the simulation.

This class extends the base asset configuration to include specific properties for rigid bodies, such as physical attributes and collision group.

Attributes:

`attrs`
`body_scale`	Scale of the rigid body in the simulation world frame.
`body_type`
`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`max_convex_hull_num`	The maximum number of convex hulls that will be created for the rigid body.
`shape`	Shape configuration for the rigid body.
`uid`

Methods:

to_dexsim_body_type()

Convert the body type to dexsim ActorType.

attrs: RigidBodyAttributesCfg#

body_scale: Union[tuple, list]#: Scale of the rigid body in the simulation world frame.

body_type: Literal['dynamic', 'kinematic', 'static']#

init_local_pose: Optional[ndarray]#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

max_convex_hull_num: int#

The maximum number of convex hulls that will be created for the rigid body.

If max_convex_hull_num is set to larger than 1, the rigid body will be decomposed into multiple convex hulls using coacd alogorithm. Reference: SarahWeiii/CoACD

shape: ShapeCfg#: Shape configuration for the rigid body.

to_dexsim_body_type()[source]#

Convert the body type to dexsim ActorType.

Return type:: ActorType

uid: Optional[str]#

class embodichain.lab.sim.cfg.RigidObjectGroupCfg[source]#

Bases: object

Configuration for a rigid object group asset in the simulation.

Rigid object groups can be initialized from multiple rigid object configurations specified in a folder. If folder_path is specified, user should provide a RigidObjectCfg in rigid_objects as a template configuration for all objects in the group.

For example: ```python rigid_object_group: RigidObjectGroupCfg(

folder_path=”path/to/folder”, max_num=5, rigid_objects={

“template_obj”: RigidObjectCfg(

shape=MeshCfg(
fpath=””, # fpath will be ignored when folder_path is specified

), body_type=”dynamic”,

)

}

)

Attributes:

`body_type`	Body type for all rigid objects in the group.
`ext`	File extension for the rigid object assets.
`folder_path`	Path to the folder containing the rigid object assets.
`max_num`	Maximum number of rigid objects to initialize from the folder.
`rigid_objects`	Configuration for the rigid objects in the group.
`uid`

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

body_type: Literal['dynamic', 'kinematic']#: Body type for all rigid objects in the group.

ext: str#

File extension for the rigid object assets.

This is only used when folder_path is specified.

folder_path: Optional[str]#

Path to the folder containing the rigid object assets.

This is used to initialize multiple rigid object configurations from a folder.

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: RigidObjectGroupCfg

max_num: int#

Maximum number of rigid objects to initialize from the folder.

This is only used when folder_path is specified.

rigid_objects: Dict[str, RigidObjectCfg]#: Configuration for the rigid objects in the group.

uid: Optional[str]#

class embodichain.lab.sim.cfg.RobotCfg[source]#

Bases: ArticulationCfg

RobotCfg(uid: ‘Union[str, None]’ = <factory>, init_pos: ‘tuple[float, float, float]’ = <factory>, init_rot: ‘tuple[float, float, float]’ = <factory>, init_local_pose: ‘Optional[np.ndarray]’ = <factory>, fpath: ‘str’ = <factory>, drive_pros: ‘JointDrivePropertiesCfg’ = <factory>, body_scale: ‘Union[tuple, list]’ = <factory>, attrs: ‘RigidBodyAttributesCfg’ = <factory>, fix_base: ‘bool’ = <factory>, disable_self_collision: ‘bool’ = <factory>, init_qpos: ‘Union[torch.Tensor, np.ndarray, Sequence[float]]’ = <factory>, sleep_threshold: ‘float’ = <factory>, min_position_iters: ‘int’ = <factory>, min_velocity_iters: ‘int’ = <factory>, build_pk_chain: ‘bool’ = <factory>, control_parts: ‘Union[Dict[str, List[str]], None]’ = <factory>, urdf_cfg: ‘Optional[URDFCfg]’ = <factory>, solver_cfg: ‘Union[SolverCfg, Dict[str, SolverCfg], None]’ = <factory>)

Classes:

SolverCfg

Configuration for the kinematic solver used in the robot simulation.

Attributes:

`attrs`	Physical attributes for all links .
`body_scale`	Scale of the articulation in the simulation world frame.
`build_pk_chain`	Whether to build pytorch-kinematics chain for forward kinematics and jacobian computation.
`control_parts`	Control parts is the mapping from part name to joint names.
`disable_self_collision`	Whether to enable or disable self-collisions.
`drive_pros`	Properties to define the drive mechanism of a joint.
`fix_base`	Whether to fix the base of the articulation.
`fpath`	Path to the articulation asset file.
`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_qpos`	Initial joint positions of the articulation.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`min_position_iters`	[1,255].
`min_velocity_iters`	[0,255].
`sleep_threshold`	[0, max_float32]
`solver_cfg`	Solver is used to compute forward and inverse kinematics for the robot.
`uid`
`urdf_cfg`	URDF assembly configuration which allows for assembling a robot from multiple URDF components.

Methods:

`build_pk_serial_chain`([device])	Build the serial chain from the URDF file.
`from_dict`(init_dict)	Initialize the configuration from a dictionary.

class SolverCfg#

Bases: object

Configuration for the kinematic solver used in the robot simulation.

Attributes:

`class_type`	The class type of the solver to be used.
`end_link_name`	The name of the end-effector link for the solver.
`ik_nearest_weight`	Weights for the inverse kinematics nearest calculation.
`joint_names`	List of joint names for the solver.
`root_link_name`	The name of the root/base link for the solver.
`tcp`	The tool center point (TCP) position as a 4x4 homogeneous matrix.
`urdf_path`	The file path to the URDF model of the robot.

Methods:

`from_dict`(init_dict)	Initialize the configuration from a dictionary.
`init_solver`(device, **kwargs)

class_type: str#: The class type of the solver to be used.

end_link_name: str#

The name of the end-effector link for the solver.

This defines the target link for forward/inverse kinematics calculations. Must match a link name in the URDF file.

classmethod from_dict(init_dict)#

Initialize the configuration from a dictionary.

Return type:: SolverCfg

ik_nearest_weight: Optional[List[float]]#

Weights for the inverse kinematics nearest calculation.

The weights influence how the solver prioritizes closeness to the seed position when multiple solutions are available.

abstract init_solver(device, **kwargs)#

Return type:: BaseSolver

joint_names: Optional[list[str]]#

List of joint names for the solver.

If None, all joints in the URDF will be used. If specified, only these named joints will be included in the kinematic chain.

root_link_name: str#

The name of the root/base link for the solver.

This defines the starting point of the kinematic chain. Must match a link name in the URDF file.

tcp: Union[Tensor, ndarray]#

The tool center point (TCP) position as a 4x4 homogeneous matrix.

This represents the position and orientation of the tool in the robot’s end-effector frame.

urdf_path: Optional[str]#: The file path to the URDF model of the robot.

attrs: RigidBodyAttributesCfg#: Physical attributes for all links .

body_scale: Union[tuple, list]#: Scale of the articulation in the simulation world frame.

build_pk_chain: bool#: Whether to build pytorch-kinematics chain for forward kinematics and jacobian computation.

build_pk_serial_chain(device=device(type='cpu'), **kwargs)[source]#

Build the serial chain from the URDF file.

Note

This method is usually used in imitation dataset saving (compute eef pose from qpos using FK) and model training (provide a differentiable FK layer or loss computation).

Parameters:

device (torch.device) – The device to which the chain will be moved. Defaults to CPU.
**kwargs – Additional arguments for building the serial chain.

Returns:

The serial chain of the robot for specified control part.

Return type:

Dict[str, pk.SerialChain]

control_parts: Union[Dict[str, List[str]], None]#

Control parts is the mapping from part name to joint names.

For example, {‘left_arm’: [‘joint1’, ‘joint2’], ‘right_arm’: [‘joint3’, ‘joint4’]} If no control part is specified, the robot will use all joints as a single control part.

Note

if control_parts is specified, solver_cfg must be a dict with part names as
keys corresponding to the control parts name.
The joint names in the control parts support regular expressions, e.g., ‘joint[1-6]’.
After initialization of robot, the names will be expanded to a list of full joint names.

disable_self_collision: bool#: Whether to enable or disable self-collisions.

drive_pros: JointDrivePropertiesCfg#: Properties to define the drive mechanism of a joint.

fix_base: bool#

Whether to fix the base of the articulation.

Set to True for articulations that should not move, such as a fixed base robot arm or a door. Set to False for articulations that should move freely, such as a mobile robot or a humanoid robot.

fpath: str#: Path to the articulation asset file.

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: RobotCfg

init_local_pose: Optional[np.ndarray]#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_qpos: Union[torch.Tensor, np.ndarray, Sequence[float]]#

Initial joint positions of the articulation.

If None, the joint positions will be set to zero. If provided, it should be a array of shape (num_joints,).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

min_position_iters: int#

[1,255].

Type:: Number of position iterations the solver should perform for this articulation. Range

min_velocity_iters: int#

[0,255].

Type:: Number of velocity iterations the solver should perform for this articulation. Range

sleep_threshold: float#

[0, max_float32]

Type:: Energy below which the articulation may go to sleep. Range

solver_cfg: Union[SolverCfg, Dict[str, SolverCfg], None]#: Solver is used to compute forward and inverse kinematics for the robot.

uid: Union[str, None]#

urdf_cfg: Optional[URDFCfg]#: URDF assembly configuration which allows for assembling a robot from multiple URDF components.

class embodichain.lab.sim.cfg.SoftObjectCfg[source]#

Bases: ObjectBaseCfg

Configuration for a soft body asset in the simulation.

This class extends the base asset configuration to include specific properties for soft bodies, such as physical attributes and collision group.

Attributes:

`init_local_pose`	4x4 transformation matrix of the root in local frame.
`init_pos`	Position of the root in simulation world frame.
`init_rot`	Euler angles (in degree) of the root in simulation world frame.
`physical_attr`	Physical attributes for the soft body.
`shape`	Mesh configuration for the soft body.
`uid`
`voxel_attr`	Tetra mesh voxelization attributes for the soft body.

init_local_pose: Optional[ndarray]#: 4x4 transformation matrix of the root in local frame. If specified, it will override init_pos and init_rot.

init_pos: tuple[float, float, float]#: Position of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

init_rot: tuple[float, float, float]#: Euler angles (in degree) of the root in simulation world frame. Defaults to (0.0, 0.0, 0.0).

physical_attr: SoftbodyPhysicalAttributesCfg#: Physical attributes for the soft body.

shape: MeshCfg#: Mesh configuration for the soft body.

uid: Optional[str]#

voxel_attr: SoftbodyVoxelAttributesCfg#: Tetra mesh voxelization attributes for the soft body.

class embodichain.lab.sim.cfg.SoftbodyPhysicalAttributesCfg[source]#

Bases: object

SoftbodyPhysicalAttributesCfg(youngs: ‘float’ = <factory>, poissons: ‘float’ = <factory>, dynamic_friction: ‘float’ = <factory>, elasticity_damping: ‘float’ = <factory>, material_model: ‘SoftBodyMaterialModel’ = <factory>, enable_kinematic: ‘bool’ = <factory>, enable_ccd: ‘bool’ = <factory>, enable_self_collision: ‘bool’ = <factory>, has_gravity: ‘bool’ = <factory>, self_collision_stress_tolerance: ‘float’ = <factory>, collision_mesh_simplification: ‘bool’ = <factory>, self_collision_filter_distance: ‘float’ = <factory>, vertex_velocity_damping: ‘float’ = <factory>, linear_damping: ‘float’ = <factory>, sleep_threshold: ‘float’ = <factory>, settling_threshold: ‘float’ = <factory>, settling_damping: ‘float’ = <factory>, mass: ‘float’ = <factory>, density: ‘float’ = <factory>, max_depenetration_velocity: ‘float’ = <factory>, max_velocity: ‘float’ = <factory>, min_position_iters: ‘int’ = <factory>, min_velocity_iters: ‘int’ = <factory>)

Methods:

attr()

Attributes:

`collision_mesh_simplification`	Whether to simplify the collision mesh for self-collision.
`density`	Material density in kg/m^3.
`dynamic_friction`	Dynamic friction coefficient.
`elasticity_damping`	Elasticity damping factor.
`enable_ccd`	Enable continuous collision detection (CCD).
`enable_kinematic`	If True, (partially) kinematic behavior is enabled.
`enable_self_collision`	Enable self-collision handling.
`has_gravity`	Whether the soft body is affected by gravity.
`linear_damping`	Global linear damping applied to the soft body.
`mass`	Total mass of the soft body.
`material_model`	Material constitutive model.
`max_depenetration_velocity`	Maximum velocity used to resolve penetrations.
`max_velocity`	Clamp for linear (or vertex) velocity.
`min_position_iters`	Minimum solver iterations for position correction.
`min_velocity_iters`	Minimum solver iterations for velocity updates.
`poissons`	Poisson's ratio (higher = closer to incompressible).
`self_collision_filter_distance`	Distance threshold below which vertex pairs may be filtered from self-collision checks.
`self_collision_stress_tolerance`	Stress tolerance threshold for self-collision constraints.
`settling_damping`	Additional damping applied during settling phase.
`settling_threshold`	Threshold used to decide convergence/settling state.
`sleep_threshold`	Velocity/energy threshold below which the soft body can go to sleep.
`vertex_velocity_damping`	Per-vertex velocity damping.
`youngs`	Young's modulus (higher = stiffer).

attr()[source]#

Return type:: SoftBodyAttr

collision_mesh_simplification: bool#: Whether to simplify the collision mesh for self-collision.

density: float#: Material density in kg/m^3.

dynamic_friction: float#: Dynamic friction coefficient.

elasticity_damping: float#: Elasticity damping factor.

enable_ccd: bool#: Enable continuous collision detection (CCD).

enable_kinematic: bool#: If True, (partially) kinematic behavior is enabled.

enable_self_collision: bool#: Enable self-collision handling.

has_gravity: bool#: Whether the soft body is affected by gravity.

linear_damping: float#: Global linear damping applied to the soft body.

mass: float#: Total mass of the soft body. If set to a negative value, density will be used to compute mass.

material_model: SoftBodyMaterialModel#: Material constitutive model.

max_depenetration_velocity: float#: Maximum velocity used to resolve penetrations. Must be larger than zero.

max_velocity: float#: Clamp for linear (or vertex) velocity. If set to zero, the limit is ignored.

min_position_iters: int#: Minimum solver iterations for position correction.

min_velocity_iters: int#: Minimum solver iterations for velocity updates.

poissons: float#: Poisson’s ratio (higher = closer to incompressible).

self_collision_filter_distance: float#: Distance threshold below which vertex pairs may be filtered from self-collision checks.

self_collision_stress_tolerance: float#: Stress tolerance threshold for self-collision constraints.

settling_damping: float#: Additional damping applied during settling phase.

settling_threshold: float#: Threshold used to decide convergence/settling state.

sleep_threshold: float#: Velocity/energy threshold below which the soft body can go to sleep.

vertex_velocity_damping: float#: Per-vertex velocity damping.

youngs: float#: Young’s modulus (higher = stiffer).

class embodichain.lab.sim.cfg.SoftbodyVoxelAttributesCfg[source]#

Bases: object

SoftbodyVoxelAttributesCfg(triangle_remesh_resolution: ‘int’ = <factory>, triangle_simplify_target: ‘int’ = <factory>, maximal_edge_length: ‘float’ = <factory>, simulation_mesh_resolution: ‘int’ = <factory>, simulation_mesh_output_obj: ‘bool’ = <factory>)

Methods:

attr()

Convert to dexsim VoxelConfig

Attributes:

`maximal_edge_length`
`simulation_mesh_output_obj`	Whether to output the simulation mesh as an obj file for debugging.
`simulation_mesh_resolution`	Resolution to build simulation voxelize textra mesh.
`triangle_remesh_resolution`	Resolution to remesh the softbody mesh before building physx collision mesh.
`triangle_simplify_target`	Simplify mesh faces to target value.

attr()[source]#

Convert to dexsim VoxelConfig

Return type:: VoxelConfig

maximal_edge_length: float#

simulation_mesh_output_obj: bool#: Whether to output the simulation mesh as an obj file for debugging.

simulation_mesh_resolution: int#: Resolution to build simulation voxelize textra mesh. This value must be greater than 0.

triangle_remesh_resolution: int#: Resolution to remesh the softbody mesh before building physx collision mesh.

triangle_simplify_target: int#: Simplify mesh faces to target value. Do nothing if this value is zero.

class embodichain.lab.sim.cfg.URDFCfg[source]#

Bases: object

Standalone configuration class for URDF assembly.

Methods:

`add_component`(component_type, urdf_path[, ...])	Add a robot component to the assembly configuration.
`add_sensor`(sensor_name, **sensor_config)	Add a sensor to the robot configuration.
`assemble_urdf`()	Assemble URDF files for the robot based on the configuration.
`from_dict`(init_dict)
`set_urdf`(urdf_path)	Directly specify a single URDF file for the robot, compatible with the single-URDF robot case.

Attributes:

`base_link_name`	Name of the base link in the assembled robot.
`components`	Dictionary of robot components to be assembled.
`fname`	Name used for output file and directory.
`fpath`	Full output file path for the assembled URDF.
`fpath_prefix`	Output directory prefix for the assembled URDF file.
`sensors`	Dictionary of sensors to be attached to the robot.
`use_signature_check`	Whether to use signature check when merging URDFs.

add_component(component_type, urdf_path, transform=None, **params)[source]#

Add a robot component to the assembly configuration.

Parameters:

component_type (str) – The type/name of the component. Should be one of SUPPORTED_COMPONENTS (e.g., ‘chassis’, ‘torso’, ‘head’, ‘left_arm’, ‘right_hand’, ‘arm’, ‘hand’, etc.).
urdf_path (str) – Path to the component’s URDF file.
transform (Optional[np.ndarray]) – 4x4 transformation matrix for the component in the robot frame (default: None).
**params – Additional keyword parameters for the component (e.g., color, material, etc.).

Returns:

Returns self to allow method chaining.

Return type:

URDFCfg

add_sensor(sensor_name, **sensor_config)[source]#

Add a sensor to the robot configuration.

Parameters:

sensor_name (str) – The name of the sensor.
**sensor_config – Additional configuration parameters for the sensor.

Returns:

Returns self to allow method chaining.

Return type:

URDFCfg

assemble_urdf()[source]#

Assemble URDF files for the robot based on the configuration.

Returns:: The path to the resulting (possibly merged) URDF file.
Return type:: str

base_link_name: str#: Name of the base link in the assembled robot.

components: Dict[str, Dict[str, Union[str, Dict, ndarray]]]#: Dictionary of robot components to be assembled.

fname: Optional[str]#: Name used for output file and directory. If not specified, auto-generated from component names.

fpath: Optional[str]#: Full output file path for the assembled URDF. If specified, overrides fname and fpath_prefix.

fpath_prefix: str#: Output directory prefix for the assembled URDF file.

classmethod from_dict(init_dict)[source]#

Return type:: URDFCfg

sensors: Dict[str, Dict[str, Union[str, ndarray]]]#: Dictionary of sensors to be attached to the robot.

set_urdf(urdf_path)[source]#

Directly specify a single URDF file for the robot, compatible with the single-URDF robot case.

Parameters:: urdf_path (str) – Path to the robot’s URDF file.
Returns:: Returns self to allow method chaining.
Return type:: URDFCfg

use_signature_check: bool#: Whether to use signature check when merging URDFs.

Common Conponents#

Classes:

BatchEntity

Abstract base class for batch entity in the simulation engine.

class embodichain.lab.sim.common.BatchEntity[source]#

Bases: ABC

Abstract base class for batch entity in the simulation engine.

This class defines the interfaces for managing and manipulating a batch of entity. A single entity could be one of the following assets: - actor (eg. rigid object) - articulation (eg. robot) - camera - light - sensor (eg. force sensor)

Methods:

`__init__`(cfg[, entities, device])
`destroy`()	Destroy all entities managed by this batch entity.
`get_local_pose`([to_matrix])
`reset`([env_ids])	Reset the entity to its initial state.
`set_local_pose`(pose[, env_ids])

Attributes:

`cfg`
`device`
`num_instances`
`pose`
`uid`

__init__(cfg, entities=None, device=device(type='cpu'))[source]#

cfg: ObjectBaseCfg = None#

destroy()[source]#

Destroy all entities managed by this batch entity.

Return type:: None

device: device = None#

abstract get_local_pose(to_matrix=False)[source]#

Return type:: Tensor

property num_instances: int#

property pose: Tensor#

abstract reset(env_ids=None)[source]#

Reset the entity to its initial state.

Parameters:: env_ids (Optional[Sequence[int]]) – The environment IDs to reset. If None, reset all environments.
Return type:: None

abstract set_local_pose(pose, env_ids=None)[source]#

Return type:: None

uid: Optional[str] = None#

Materials#

Classes:

`VisualMaterial`	Visual material definition in the simulation environment.
`VisualMaterialCfg`	Configuration for visual material with PBR properties for rasterization and ray tracing.
`VisualMaterialInst`	Instance of a visual material in the simulation environment.

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.

Attributes:

`RT_MATERIAL_TYPES`
`is_rt_enabled`
`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)

RT_MATERIAL_TYPES = ['BRDF_GGX_SMITH', 'BTDF_GGX_SMITH', 'BSDF_GGX_SMITH']#

__init__(cfg, mat)[source]#

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 is_rt_enabled: bool#

property mat: Material#

set_default_properties(mat_inst, cfg)[source]#

Return type:: None

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

Bases: object

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

Methods:

`__init__`([uid, base_color, metallic, ...])
`copy`(**kwargs)	Return a new object replacing specified fields with new values.
`from_dict`(cfg_dict)
`replace`(**kwargs)	Return a new object replacing specified fields with new values.
`to_dict`()	Convert an object into dictionary recursively.
`validate`([prefix])	Check the validity of configclass object.

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 ray tracing materials
`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
`rt_material_type`	'BRDF_GGX_SMITH', 'BTDF_GGX_SMITH', 'BSDF_GGX_SMITH'
`uid`

__init__(uid=<factory>, base_color=<factory>, metallic=<factory>, roughness=<factory>, emissive=<factory>, emissive_intensity=<factory>, base_color_texture=<factory>, metallic_texture=<factory>, roughness_texture=<factory>, normal_texture=<factory>, ao_texture=<factory>, ior=<factory>, rt_material_type=<factory>)#

ao_texture: str#: Ambient occlusion map

base_color: list#: Base color/diffuse color (RGBA)

base_color_texture: str#: Base color texture map

copy(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

emissive: list#

emissive_intensity: float#

classmethod from_dict(cfg_dict)[source]#

Return type:: VisualMaterialCfg

ior: float#: Index of refraction for ray tracing materials

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

metallic_texture: str#: Metallic map

normal_texture: str#: Normal map

replace(**kwargs)#

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

obj (object) – The object to replace.
**kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

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

roughness_texture: str#: Roughness map

rt_material_type: str#

‘BRDF_GGX_SMITH’, ‘BTDF_GGX_SMITH’, ‘BSDF_GGX_SMITH’

Type:: Ray tracing material type. Options

to_dict()#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj (object) – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Return type:: dict[str, Any]
Returns:: Converted dictionary mapping.

uid: str#

validate(prefix='')#

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

obj (object) – The object to check.
prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

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

Bases: object

Instance of a visual material in the simulation environment.

Methods:

`__init__`(uid, mat)
`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 or texture data.
`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)[source]#

property mat: MaterialInst#

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

Set ambient occlusion texture from file path or texture data.

Parameters:

texture_path (Optional[str]) – Path to texture file
texture_data (Optional[Tensor]) – 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)[source]#

Set base color texture from file path or texture data.

Parameters:

texture_path (Optional[str]) – Path to texture file
texture_data (Optional[Tensor]) – Texture data as a torch.Tensor

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 (Optional[str]) – Path to texture file
texture_data (Optional[Tensor]) – 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 (Optional[str]) – Path to texture file
texture_data (Optional[Tensor]) – 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 (Optional[str]) – Path to texture file
texture_data (Optional[Tensor]) – Texture data as a torch.Tensor

Return type:

None

Shapes#

Classes:

`CubeCfg`	Configuration parameters for a cube shape.
`LoadOption`	LoadOption(rebuild_normals: 'bool' = <factory>, rebuild_tangent: 'bool' = <factory>, rebuild_3rdnormal: 'bool' = <factory>, rebuild_3rdtangent: 'bool' = <factory>, smooth: 'float' = <factory>)
`MeshCfg`	Configuration parameters for a triangle mesh shape.
`ShapeCfg`	ShapeCfg(shape_type: 'str' = <factory>, visual_material: 'Optional[VisualMaterialCfg]' = <factory>)
`SphereCfg`	Configuration parameters for a sphere shape.

class embodichain.lab.sim.shapes.CubeCfg[source]#

Bases: ShapeCfg

Configuration parameters for a cube shape.

Attributes:

`shape_type`	Type of the shape.
`size`	Size of the cube (in m) as [length, width, height].
`visual_material`	Configuration parameters for the visual material of the shape.

shape_type: str#: Type of the shape. Must be specified in subclasses.

size: List[float]#: Size of the cube (in m) as [length, width, height].

visual_material: Optional[VisualMaterialCfg]#: Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.LoadOption[source]#

Bases: object

LoadOption(rebuild_normals: ‘bool’ = <factory>, rebuild_tangent: ‘bool’ = <factory>, rebuild_3rdnormal: ‘bool’ = <factory>, rebuild_3rdtangent: ‘bool’ = <factory>, smooth: ‘float’ = <factory>)

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

Attributes:

`rebuild_3rdnormal`	Whether to rebuild the normal for the shape using 3rd party library.
`rebuild_3rdtangent`	Whether to rebuild the tangent for the shape using 3rd party library.
`rebuild_normals`	Whether to rebuild normals for the shape.
`rebuild_tangent`	Whether to rebuild tangents for the shape.
`smooth`	Angle threshold (in degrees) for smoothing normals.

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: LoadOption

rebuild_3rdnormal: bool#: Whether to rebuild the normal for the shape using 3rd party library. Defaults to False.

rebuild_3rdtangent: bool#: Whether to rebuild the tangent for the shape using 3rd party library. Defaults to False.

rebuild_normals: bool#: Whether to rebuild normals for the shape. Defaults to False.

rebuild_tangent: bool#: Whether to rebuild tangents for the shape. Defaults to False.

smooth: float#: Angle threshold (in degrees) for smoothing normals. Defaults to -1.0 (no smoothing).

class embodichain.lab.sim.shapes.MeshCfg[source]#

Bases: ShapeCfg

Configuration parameters for a triangle mesh shape.

Attributes:

`compute_uv`	Whether to compute UV coordinates for the shape.
`fpath`	File path to the shape mesh file.
`load_option`	Options for loading and processing the shape.
`project_direction`	Direction to project the UV coordinates.
`shape_type`	Type of the shape.
`visual_material`	Configuration parameters for the visual material of the shape.

compute_uv: bool#

Whether to compute UV coordinates for the shape. Defaults to False.

If the shape already has UV coordinates, setting this to True will recompute and overwrite them.

fpath: str#: File path to the shape mesh file.

load_option: LoadOption#: Options for loading and processing the shape.

project_direction: List[float]#: Direction to project the UV coordinates. Defaults to [1.0, 1.0, 1.0].

shape_type: str#: Type of the shape. Must be specified in subclasses.

visual_material: Optional[VisualMaterialCfg]#: Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.ShapeCfg[source]#

Bases: object

ShapeCfg(shape_type: ‘str’ = <factory>, visual_material: ‘Optional[VisualMaterialCfg]’ = <factory>)

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

Attributes:

`shape_type`	Type of the shape.
`visual_material`	Configuration parameters for the visual material of the shape.

classmethod from_dict(init_dict)[source]#

Initialize the configuration from a dictionary.

Return type:: ShapeCfg

shape_type: str#: Type of the shape. Must be specified in subclasses.

visual_material: Optional[VisualMaterialCfg]#: Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.SphereCfg[source]#

Bases: ShapeCfg

Configuration parameters for a sphere shape.

Attributes:

`radius`	Radius of the sphere (in m).
`resolution`	Resolution of the sphere mesh.
`shape_type`	Type of the shape.
`visual_material`	Configuration parameters for the visual material of the shape.

radius: float#: Radius of the sphere (in m).

resolution: int#: Resolution of the sphere mesh. Defaults to 20.

shape_type: str#: Type of the shape. Must be specified in subclasses.

visual_material: Optional[VisualMaterialCfg]#: Configuration parameters for the visual material of the shape. Defaults to None.

Objects#

embodichain.lab.sim.objects

Sensors#

embodichain.lab.sim.sensors

Solvers#

embodichain.lab.sim.solvers

Utility#

embodichain.lab.sim.utility

embodichain.lab.sim

Contents

embodichain.lab.sim#

Simulation Manager#

Configurations#

Common Conponents#

Materials#

Shapes#

Objects#

Sensors#

Solvers#

Utility#