embodichain.lab.sim

Overview

The sim package provides simulation-core APIs including scene/object management, materials, sensors, planning/IK utilities, and action helpers.

Submodules

sim_manager
cfg
common
material
shapes
objects
robots
sensors
solvers
planners
atomic_actions	Atomic action abstraction layer for embodied AI motion generation.
types
utility

Simulation Manager

class embodichain.lab.sim.SimulationManager

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 rigid objects, soft objects, articulations, robots, sensors and lights.

• manager the scenes and the simulation environment.

  • parallel scenes simulation on both CPU and GPU.

  • create and setup the rendering related settings, eg. environment map, lighting, materials, etc.

  • physics simulation management, eg. time step, manual update, etc.

  • interactive control via gizmo and window callbacks events.

Parameters:

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

Attributes:

SUPPORTED_SENSOR_TYPES
arena_offsets	Get the arena offsets for all arenas.
asset_uids	Get all assets uid in the simulation.
is_physics_manually_update
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, gpu_id, thread_mode, ...])
__new__(cls[, sim_config, gpu_id, ...])	Create or return the instance based on instance_id.
add_articulation(cfg)	Add an articulation to the scene.
add_cloth_object(cfg)	Add a cloth object to the scene.
add_custom_window_control(controls)	Add one or more custom window input controls.
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.
clean_materials()
close_window()	Close the simulation window.
create_rigid_constraint(cfg[, env_ids])	Create a fixed constraint between two RigidObjects.
create_visual_material(cfg)	Create a visual material with given configuration.
destroy([exit_process])	No longer destructs C++ objects in place due to lingering deep local variables; instead, packages itself into a destruction task, submits to the cleanup queue, and waits for top-level delayed consumption.
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.
enable_window_camera_pose_hotkey([...])	Register p to print the current viewer camera pose.
enable_window_record_hotkey([save_path, ...])	Register the r key to start/stop viewer recording.
export_usd(fpath)	Export the current simulation scene to a USD file.
flush_cleanup_queue()	Dequeue executor and synchronization barrier provided for top-level main loop / Pytest Fixture calls
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_cloth_object(uid)	Get a cloth object by its unique ID.
get_cloth_object_uid_list()	Get current cloth body uid list
get_env([arena_index])	Get the arena or env by index.
get_gizmo(uid[, control_part])	Get gizmo instance for a robot.
get_instance([instance_id])	Get the instance of SimulationManager by id.
get_instance_num()	Get the number of instantiated SimulationManager instances.
get_light(uid)	Get a light by its UID.
get_light_uid_list()	Get current light uid list
get_rigid_constraint(name)	Get a rigid constraint by its base name.
get_rigid_constraint_uid_list()	Get the list of registered constraint base names.
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_group_uid_list()	Get current rigid body group uid list
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_soft_object(uid)	Get a soft object by its unique ID.
get_soft_object_uid_list()	Get current soft body 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.
has_non_static_rigid_object()	Check if there is any non-static rigid object in the simulation.
init_gpu_physics()	Initialize the GPU physics simulation.
is_instantiated([instance_id])	Check if the instance has been created.
is_window_recording()	Check whether the viewer window is currently recording.
list_gizmos()	List all active gizmos and their status.
open_window()	Open the simulation window.
print_window_camera_pose([convert_to_look_at])	Print the current viewer camera pose as reusable Python code.
remove_asset(uid)	Remove an asset by its UID.
remove_marker(name)	Remove markers (including axis) with the given name.
remove_rigid_constraint(name[, env_ids])	Remove a rigid constraint by name.
render_camera_group(group_ids)	Render all camera group in the simulation.
reset([instance_id])	Reset the instance.
reset_objects_state([env_ids, excluded_uids])	Reset the state of the simulated assets given the environment IDs and excluded UIDs.
set_default_background()	Set default background.
set_default_global_lighting()	Set default global lighting for the scene.
set_default_renderer([renderer, gpu_id])	Set the global default renderer used by new simulations.
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_ground_plane_visibility(visible)	_summary_
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.
start_window_record([save_path, fps, ...])	Start asynchronously recording the simulation to a video buffer.
stop_window_record([save_path])	Stop the active viewer recording and save frames in the background.
toggle_gizmo_visibility(uid[, control_part])	Toggle the visibility of a gizmo by uid and optional control_part.
toggle_window_record([save_path, fps, ...])	Toggle viewer recording on or off.
update([physics_dt, step])	Update the physics.
update_gizmos()	Update all active gizmos.
wait_scene_destruction([timeout_ms])	A public helper to wait for the underlying C++ scenes (dexsim.World) to destruct completely.
wait_window_record_saves()	Wait for all background video export threads to finish.

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

__init__(sim_config=SimulationManagerCfg(width=1920, height=1080, headless=False, render_cfg=RenderCfg(renderer='auto', spp=1, tone_mapping_enabled=False, tone_mapping_exposure=1.0), gpu_id=0, thread_mode=<ThreadMode.RENDER_SHARE_ENGINE: 0>, cpu_num=1, num_envs=1, 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), window_record=WindowRecordCfg(enable_hotkey=True, save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record'), window_camera_pose=WindowCameraPoseCfg(enable_hotkey=True, convert_to_look_at=True)))

static __new__(cls, sim_config=SimulationManagerCfg(width=1920, height=1080, headless=False, render_cfg=RenderCfg(renderer='auto', spp=1, tone_mapping_enabled=False, tone_mapping_exposure=1.0), gpu_id=0, thread_mode=<ThreadMode.RENDER_SHARE_ENGINE: 0>, cpu_num=1, num_envs=1, 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), window_record=WindowRecordCfg(enable_hotkey=True, save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record'), window_camera_pose=WindowCameraPoseCfg(enable_hotkey=True, convert_to_look_at=True)))

Create or return the instance based on instance_id.

add_articulation(cfg)

Add an articulation to the scene.

Parameters:

cfg (ArticulationCfg) – Configuration for the articulation.

Returns:

The added articulation instance handle.

Return type:

Articulation

add_cloth_object(cfg)

Add a cloth object to the scene.

Parameters:

cfg (ClothObjectCfg) – Configuration for the cloth object.

Returns:

The added cloth object instance handle.

Return type:

ClothObject

add_custom_window_control(controls)

Add one or more custom window input controls.

This method registers additional ObjectManipulator instances with the simulation window so they can handle input events alongside any default controls.

Parameters:

controls (list[ObjectManipulator]) – A list of initialized ObjectManipulator instances to add to the current window. Each control will be registered via window.add_input_control. If no window is available, the controls are not added and a warning is logged.

Return type:

None

add_light(cfg)

Create a light in the scene.

Supports six light types: "point", "sun", "direction", "spot", "rect", and "mesh". See LightCfg for type-specific configuration fields.

Attention

"sun" and "direction" lights are global scene lights (infinite-distance directional light sources). They are created as a single instance on the root environment, not batched per environment. All other types are created as per-environment batched lights.

Parameters:

cfg (LightCfg) – Configuration for the light, including type, color, intensity, and type-specific properties.

Returns:

The created light instance.

Return type:

Light

Raises:

RuntimeError – If cfg.light_type is not one of the supported types.

add_rigid_object(cfg)

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)

Add a rigid object group to the scene.

Parameters:

cfg (RigidObjectGroupCfg) – Configuration for the rigid object group.

Return type:

RigidObjectGroup

add_robot(cfg)

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:

Robot | None

add_sensor(sensor_cfg)

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)

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 arena_offsets: Tensor

Get the arena offsets for all arenas.

Returns:

The arena offsets of shape (num_arenas, 3).

Return type:

torch.Tensor

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]

clean_materials()

close_window()

Close the simulation window.

Return type:

None

create_rigid_constraint(cfg, env_ids=None)

Create a fixed constraint between two RigidObjects.

Binds rigid_object_a’s entity[i] to rigid_object_b’s entity[i] within arena[i], for each env in env_ids. Local frames default to welding the objects at their current relative pose: local_frame_a defaults to identity (object A’s origin) and local_frame_b defaults to inv(pose_B) @ pose_A (computed per env), so the offset is preserved rather than the two origins being pulled together. Pass explicit frames to define a specific joint frame.

Parameters:

• cfg (RigidConstraintCfg) – The constraint configuration.

• env_ids (Union[Sequence[int], Tensor, None]) – Target environment indices. Accepts a tensor (as passed by the EventManager) or a sequence of ints. None -> all arenas.

Return type:

RigidConstraint

Returns:

The created RigidConstraint.

Raises:

RuntimeError – If either object is missing, the name is already in use, a frame shape is invalid, or dexsim fails to create a handle.

create_visual_material(cfg)

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(exit_process=None)

No longer destructs C++ objects in place due to lingering deep local variables; instead, packages itself into a destruction task, submits to the cleanup queue, and waits for top-level delayed consumption.

Parameters:

exit_process (bool | None) – Whether to call os._exit(0) after queuing the destruction task. If None, reads EMBODICHAIN_SIM_EXIT_PROCESS.

Return type:

None

disable_gizmo(uid, control_part=None)

Disable and remove gizmo for a robot.

Parameters:

• uid (str) – Object UID to disable gizmo for

• control_part (str | None, optional) – Control part name for robots. Defaults to None.

Return type:

None

draw_marker(cfg)

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)

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 (str | None, optional) – Control part name for robots. Defaults to “arm”.

• gizmo_cfg (object, optional) – Gizmo configuration object. Defaults to None.

Return type:

Gizmo

enable_physics(enable)

Enable or disable physics simulation.

Parameters:

enable (bool) – whether to enable physics simulation.

Return type:

None

enable_window_camera_pose_hotkey(convert_to_look_at=True)

Register p to print the current viewer camera pose.

Parameters:

convert_to_look_at (bool) – Print a window.set_look_at(...) call when true, which is the default. Set false to print the raw matrix.

Return type:

bool

Returns:

Whether the control is registered on an available window.

enable_window_record_hotkey(save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record')

Register the r key to start/stop viewer recording.

Return type:

bool

export_usd(fpath)

Export the current simulation scene to a USD file.

Parameters:

fpath (str) – The file path to save the USD file.

Returns:

True if export is successful, False otherwise.

Return type:

bool

static flush_cleanup_queue()

Dequeue executor and synchronization barrier provided for top-level main loop / Pytest Fixture calls

get_articulation(uid)

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:

Articulation | None

get_articulation_uid_list()

Get current articulation uid list

Returns:

list of articulation uid.

Return type:

List[str]

get_asset(uid)

Get an asset by its UID.

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

Parameters:

uid (str) – The UID of the asset.

Returns:

The asset instance if found, otherwise None.

Return type:

Light | BaseSensor | Robot | RigidObject | Articulation | None

get_cloth_object(uid)

Get a cloth object by its unique ID.

Parameters:

uid (str) – The unique ID of the cloth object.

Returns:

The cloth object instance if found, otherwise None.

Return type:

ClothObject | None

get_cloth_object_uid_list()

Get current cloth body uid list

Returns:

list of cloth body uid.

Return type:

List[str]

get_env(arena_index=-1)

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)

Get gizmo instance for a robot.

Parameters:

• uid (str) – Object UID

• control_part (str | None, optional) – Control part name for robots. Defaults to None.

Returns:

Gizmo instance if found, None otherwise.

Return type:

object

classmethod get_instance(instance_id=0)

Get the instance of SimulationManager by id.

Parameters:

instance_id (int) – The instance id. Defaults to 0.

Returns:

The instance.

Return type:

SimulationManager

Raises:

RuntimeError – If the instance has not been created yet.

classmethod get_instance_num()

Get the number of instantiated SimulationManager instances.

Returns:

The number of instances.

Return type:

int

get_light(uid)

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

Get current light uid list

Returns:

list of light uid.

Return type:

List[str]

get_rigid_constraint(name)

Get a rigid constraint by its base name.

Parameters:

name (str) – The base constraint name.

Return type:

RigidConstraint | None

Returns:

The constraint, or None if not found.

get_rigid_constraint_uid_list()

Get the list of registered constraint base names.

Returns:

list of constraint names.

Return type:

List[str]

get_rigid_object(uid)

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:

RigidObject | None

get_rigid_object_group(uid)

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:

RigidObjectGroup | None

get_rigid_object_group_uid_list()

Get current rigid body group uid list

Returns:

list of rigid body group uid.

Return type:

List[str]

get_rigid_object_uid_list()

Get current rigid body uid list

Returns:

list of rigid body uid.

Return type:

List[str]

get_robot(uid)

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:

Robot | None

get_robot_uid_list()

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)

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

Get current sensor uid list

Returns:

list of sensor uid.

Return type:

List[str]

get_soft_object(uid)

Get a soft object by its unique ID.

Parameters:

uid (str) – The unique ID of the soft object.

Returns:

The soft object instance if found, otherwise None.

Return type:

SoftObject | None

get_soft_object_uid_list()

Get current soft body uid list

Returns:

list of soft body uid.

Return type:

List[str]

get_texture_cache(key=None)

Get the texture from the global texture cache.

Parameters:

key (str | None, optional) – The key of the texture. If None, return None. Defaults to None.

Returns:

The texture if found, otherwise None.

Return type:

torch.Tensor | list[torch.Tensor] | None

get_visual_material(uid)

Get visual material by UID.

Parameters:

uid (str) – uid of visual material.

Return type:

VisualMaterial

get_world()

Return type:

World

has_gizmo(uid, control_part=None)

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

Parameters:

• uid (str) – Object UID to check

• control_part (str | None, optional) – Control part name for robots. Defaults to None.

Returns:

True if gizmo exists, False otherwise.

Return type:

bool

has_non_static_rigid_object()

Check if there is any non-static rigid object in the simulation.

Returns:

True if there is at least one non-static rigid object, False otherwise.

Return type:

bool

init_gpu_physics()

Initialize the GPU physics simulation.

Return type:

None

classmethod is_instantiated(instance_id=0)

Check if the instance has been created.

Returns:

True if the instance exists, False otherwise.

Return type:

bool

property is_physics_manually_update: bool

property is_use_gpu_physics: bool

Check if the physics simulation is using GPU.

is_window_recording()

Check whether the viewer window is currently recording.

Return type:

bool

list_gizmos()

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

Open the simulation window.

Return type:

None

print_window_camera_pose(convert_to_look_at=True)

Print the current viewer camera pose as reusable Python code.

Parameters:

convert_to_look_at (bool) – Print window.set_look_at(...) by default. Set false to print the raw 4x4 pose matrix instead.

Return type:

str | None

Returns:

The printed snippet, or None when no viewer window is open.

remove_asset(uid)

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)

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

remove_rigid_constraint(name, env_ids=None)

Remove a rigid constraint by name.

With env_ids=None the constraint is removed from every arena and dropped from the registry. With a subset, only those arenas are cleared; the registry entry is kept until all handles become None.

Parameters:

• name (str) – The base constraint name.

• env_ids (Union[Sequence[int], Tensor, None]) – Subset of arenas to clear. Accepts a tensor (as passed by the EventManager) or a sequence of ints. None -> all.

Return type:

bool

Returns:

True if the constraint was found (and removed or partially removed), False if the name is unknown.

render_camera_group(group_ids)

Render all camera group in the simulation.

Parameters:

group_ids (list[int]) – The list of camera group ids to render.

Return type:

None

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

classmethod reset(instance_id=0)

Reset the instance.

This allows creating a new instance with different configuration.

Return type:

None

reset_objects_state(env_ids=None, excluded_uids=None)

Reset the state of the simulated assets given the environment IDs and excluded UIDs.

Parameters:

• env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

• excluded_uids (Sequence[str] | None) – List of asset UIDs to exclude from resetting. If None, reset all assets.

Return type:

None

set_default_background()

Set default background.

Return type:

None

set_default_global_lighting()

Set default global lighting for the scene.

Configures both the environment emission (ambient) light and a directional light to provide default scene illumination. The directional light is a global scene light (infinite distance) pointing downward along the -Z axis.

Return type:

None

classmethod set_default_renderer(renderer='auto', gpu_id=0)

Set the global default renderer used by new simulations.

This updates embodichain.lab.sim.cfg.DEFAULT_RENDERER, which is consulted by embodichain.lab.sim.utility.render_utils.select_default_renderer() when render_cfg.renderer="auto" is resolved during SimulationManager construction.

Parameters:

• renderer (str) – The renderer to set. One of "auto", "hybrid", "fast-rt", or "rt". When "auto", the renderer is resolved immediately from the detected GPU via embodichain.lab.sim.utility.render_utils.select_default_renderer().

• gpu_id (int) – The CUDA device index to query when renderer="auto".

Return type:

str

Returns:

The resolved renderer name that was set as the default.

set_emission_light(color=None, intensity=None)

Set environment emission light.

Parameters:

• color (Sequence[float] | None) – color of the light.

• intensity (float | None) – intensity of the light.

Return type:

None

set_gizmo_visibility(uid, visible, control_part=None)

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

Return type:

None

set_ground_plane_visibility(visible)

_summary_

Parameters:

visible (bool) – _description_

Return type:

None

set_indirect_lighting(name)

Set indirect lighting.

Parameters:

name (str) – name of path of the indirect lighting.

Return type:

None

set_manual_update(enable)

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)

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

start_window_record(save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record', pose_provider=None, fixed_pose=None, look_at=None, use_sim_time=None)

Start asynchronously recording the simulation to a video buffer.

The recorder can either follow the live viewer camera or run without a window by using a fixed pose or a pose callback supplied by the caller.

Parameters:

• save_path (str | None) – Optional output path for the recorded video.

• fps (int) – Target output frames per second. Must be positive.

• max_memory (int) – Maximum buffered frame memory in MB. Must be positive.

• video_prefix (str) – File name prefix used when save_path is not provided.

• pose_provider (Optional[Callable[[], ndarray]]) – Optional callback that returns the current camera pose.

• fixed_pose (ndarray | None) – Optional fixed 4x4 camera pose matrix.

• look_at (tuple[Sequence[float], Sequence[float], Sequence[float]] | None) – Optional (eye, target, up) tuple used to derive a fixed pose.

• use_sim_time (bool | None) – Whether to capture frames from simulation time instead of wall time. Defaults to headless mode when no viewer window exists.

Returns:

True if recording starts successfully, otherwise False.

Return type:

bool

stop_window_record(save_path=None)

Stop the active viewer recording and save frames in the background.

Return type:

bool

toggle_gizmo_visibility(uid, control_part=None)

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

toggle_window_record(save_path=None, fps=20, max_memory=1024, video_prefix='viewer_record')

Toggle viewer recording on or off.

Return type:

bool

update(physics_dt=None, step=10)

Update the physics.

Parameters:

• physics_dt (float | None, 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()

Update all active gizmos.

static wait_scene_destruction(timeout_ms=10000)

A public helper to wait for the underlying C++ scenes (dexsim.World) to destruct completely.

Return type:

None

wait_window_record_saves()

Wait for all background video export threads to finish.

Return type:

None

class embodichain.lab.sim.SimulationManagerCfg

Bases: object

Global robot simulation configuration.

Attributes:

arena_space	The distance between each arena when building multiple arenas.
cpu_num	The number of CPU threads to use for the simulation engine.
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.
num_envs	The number of parallel environments (arenas) to simulate.
physics_config	The physics configuration parameters.
physics_dt	The time step for the physics simulation.
render_cfg	The rendering configuration parameters.
sim_device	The device for the physics simulation.
thread_mode	The threading mode for the simulation engine.
width	The width of the simulation window.
window_camera_pose	Interactive viewer camera-pose printing settings.
window_record	Viewer window recording settings (hotkey, paths, FPS, memory budget).

arena_space: float

The distance between each arena when building multiple arenas.

cpu_num: int

The number of CPU threads to use for the simulation engine.

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.

num_envs: int

The number of parallel environments (arenas) to simulate.

physics_config: PhysicsCfg

The physics configuration parameters.

physics_dt: float

The time step for the physics simulation.

render_cfg: RenderCfg

The rendering configuration parameters.

sim_device: str | device

The device for the physics simulation. Can be ‘cpu’, ‘cuda’, or a torch.device object.

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.

window_camera_pose: WindowCameraPoseCfg

Interactive viewer camera-pose printing settings.

window_record: WindowRecordCfg

Viewer window recording settings (hotkey, paths, FPS, memory budget).

Configuration

Classes:

ArticulationCfg	Configuration for an articulation asset in the simulation.
ClothObjectCfg	Configuration for a cloth body asset in the simulation.
ClothPhysicalAttributesCfg	ClothPhysicalAttributesCfg(youngs: 'float' = <factory>, poissons: 'float' = <factory>, dynamic_friction: 'float' = <factory>, elasticity_damping: 'float' = <factory>, thickness: 'float' = <factory>, bending_stiffness: 'float' = <factory>, bending_damping: 'float' = <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>, vertex_velocity_damping: 'float' = <factory>, mass: 'float' = <factory>, density: 'float' = <factory>, max_depenetration_velocity: 'float' = <factory>, max_velocity: 'float' = <factory>, self_collision_filter_distance: 'float' = <factory>, linear_damping: 'float' = <factory>, sleep_threshold: 'float' = <factory>, settling_threshold: 'float' = <factory>, settling_damping: 'float' = <factory>, min_position_iters: 'int' = <factory>, min_velocity_iters: 'int' = <factory>)
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.
LinkPhysicsOverrideCfg	Per-link physics override matched by regex on articulation link names.
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>)
RenderCfg	RenderCfg(renderer: "Literal['auto', 'hybrid', 'fast-rt', 'rt']" = <factory>, spp: 'int' = <factory>, tone_mapping_enabled: 'bool' = <factory>, tone_mapping_exposure: 'float' = <factory>)
RigidBodyAttributesCfg	Physical attributes for rigid bodies.
RigidBodyAttributesOverrideCfg	Partial rigid-body attribute overrides for per-link physics configuration.
RigidConstraintCfg	Configuration for a fixed constraint between two RigidObjects.
RigidObjectCfg	Configuration for a rigid body asset in the simulation.
RigidObjectGroupCfg	Configuration for a rigid object group asset in the simulation.
RobotCfg	RobotCfg(uid: 'str | None' = <factory>, init_pos: 'tuple[float, float, float]' = <factory>, init_rot: 'tuple[float, float, float]' = <factory>, init_local_pose: 'np.ndarray | None' = <factory>, fpath: 'str' = <factory>, drive_pros: 'JointDrivePropertiesCfg' = <factory>, body_scale: 'tuple | list' = <factory>, attrs: 'RigidBodyAttributesCfg' = <factory>, link_attrs: 'dict[str, LinkPhysicsOverrideCfg] | None' = <factory>, fix_base: 'bool' = <factory>, disable_self_collision: 'bool' = <factory>, init_qpos: 'torch.Tensor | np.ndarray | Sequence[float]' = <factory>, qpos_limits: 'torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None' = <factory>, sleep_threshold: 'float' = <factory>, min_position_iters: 'int' = <factory>, min_velocity_iters: 'int' = <factory>, build_pk_chain: 'bool' = <factory>, compute_uv: 'bool' = <factory>, use_usd_properties: 'bool' = <factory>, control_parts: 'Dict[str, List[str]] | None' = <factory>, urdf_cfg: 'URDFCfg | None' = <factory>, solver_cfg: '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.
WindowCameraPoseCfg	Configuration for printing the interactive viewer camera pose.
WindowRecordCfg	Configuration for interactive viewer window recording.

Functions:

link_attrs_from_dict(value)

Parse a link_attrs mapping from YAML/JSON-style dicts.

class embodichain.lab.sim.cfg.ArticulationCfg

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.
compute_uv	Whether to compute the UV mapping for the articulation link.
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.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
qpos_limits	Override joint position limits of the articulation.
sleep_threshold	[0, max_float32]
uid
use_usd_properties	Whether to use physical properties from USD file instead of config.

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: 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.

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

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)

Initialize the configuration from a dictionary.

Return type:

ArticulationCfg

init_local_pose: ndarray | None

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: 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).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

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

qpos_limits: Tensor | ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

uid: str | None

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.

class embodichain.lab.sim.cfg.ClothObjectCfg

Bases: ObjectBaseCfg

Configuration for a cloth body asset in the simulation.

This class extends the base asset configuration to include specific properties for cloth 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 cloth body.
shape	Mesh configuration for the cloth body.
uid

init_local_pose: ndarray | None

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: ClothPhysicalAttributesCfg

Physical attributes for the cloth body.

shape: MeshCfg

Mesh configuration for the cloth body.

uid: str | None

class embodichain.lab.sim.cfg.ClothPhysicalAttributesCfg

Bases: object

ClothPhysicalAttributesCfg(youngs: ‘float’ = <factory>, poissons: ‘float’ = <factory>, dynamic_friction: ‘float’ = <factory>, elasticity_damping: ‘float’ = <factory>, thickness: ‘float’ = <factory>, bending_stiffness: ‘float’ = <factory>, bending_damping: ‘float’ = <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>, vertex_velocity_damping: ‘float’ = <factory>, mass: ‘float’ = <factory>, density: ‘float’ = <factory>, max_depenetration_velocity: ‘float’ = <factory>, max_velocity: ‘float’ = <factory>, self_collision_filter_distance: ‘float’ = <factory>, linear_damping: ‘float’ = <factory>, sleep_threshold: ‘float’ = <factory>, settling_threshold: ‘float’ = <factory>, settling_damping: ‘float’ = <factory>, min_position_iters: ‘int’ = <factory>, min_velocity_iters: ‘int’ = <factory>)

Methods:

attr()

Convert to dexsim ClothBodyAttr.

Attributes:

bending_damping	Bending damping.
bending_stiffness	Bending stiffness.
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 cloth is affected by gravity.
linear_damping	Global linear damping applied to the cloth.
mass	Total mass of the cloth.
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.
self_collision_filter_distance	Distance threshold for filtering self-collision vertex pairs.
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 cloth can go to sleep.
thickness	Cloth thickness (m).
vertex_velocity_damping	Per-vertex velocity damping.
youngs	Young's modulus (higher = stiffer).

attr()

Convert to dexsim ClothBodyAttr.

Return type:

ClothBodyAttr

bending_damping: float

Bending damping.

bending_stiffness: float

Bending stiffness.

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 cloth is affected by gravity.

linear_damping: float

Global linear damping applied to the cloth.

mass: float

Total mass of the cloth. If negative, density is used to compute mass.

max_depenetration_velocity: float

Maximum velocity used to resolve penetrations.

max_velocity: float

Clamp for linear (or vertex) velocity.

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.

self_collision_filter_distance: float

Distance threshold for filtering self-collision vertex pairs.

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 cloth can go to sleep.

thickness: float

Cloth thickness (m).

vertex_velocity_damping: float

Per-vertex velocity damping.

youngs: float

Young’s modulus (higher = stiffer).

class embodichain.lab.sim.cfg.GPUMemoryCfg

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

Bases: object

Properties to define the drive mechanism of a joint.

Attributes:

armature	Joint armature added to joint-space spatial inertia.
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.

armature: Dict[str, float] | float

Joint armature added to joint-space spatial inertia.

Units depend on the joint model:

• For prismatic (linear) joints, the unit is mass [kg].

• For revolute (angular) joints, the unit is mass * scene_length^2 [kg-m^2].

damping: 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', 'none']

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. If the drive type is “none”, then no force will be applied to joint.

friction: Dict[str, float] | float

Friction coefficient of the joint

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

JointDrivePropertiesCfg

max_effort: Dict[str, float] | float

Maximum effort that can be applied to the joint (in kg-m^2/s^2).

max_velocity: 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: 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

Bases: ObjectBaseCfg

Configuration for a light asset in the simulation.

Supports six light types matching the dexsim rendering backend:

• "point": Per-environment omnidirectional point light with position and falloff radius. Created as a batched light (one per environment).

• "sun": Global directional sun light (infinite distance). Created as a single scene-level instance. Uses direction only; position is ignored. Sun-specific fields (angular_radius, halo_size, halo_falloff) are reserved for future backend support.

• "direction": Global pure directional light at infinite distance. Created as a single scene-level instance. Direction only; no position.

• "spot": Per-environment spotlight with position, direction, and inner/outer cone angles. Created as a batched light.

• "rect": Per-environment rectangular area light with position, direction, width, and height. Created as a batched light.

• "mesh": Per-environment mesh-based emissive light. Requires a MeshObject via embodichain.lab.sim.objects.light.Light.set_mesh() (not tensor-batched). Created as a batched light.

Attention

The angular_radius, halo_size, and halo_falloff fields are reserved for future use. The dexsim Python bindings do not yet expose setters for these sun-specific properties.

Attributes:

angular_radius	Angular radius of the sun disc in degrees.
color	RGB color of the light source.
direction	Direction vector for directional, spot, rect, and mesh lights.
enable_shadow	Whether the light casts shadows.
halo_falloff	Halo falloff for sun light.
halo_size	Halo size for sun light.
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 in watts/m^2.
light_type	"point", "sun", "direction", "spot", "rect", "mesh".
mesh_path	Asset path for mesh-based emissive lights.
radius	Falloff radius for point lights.
rect_height	Height of the rectangular area light.
rect_width	Width of the rectangular area light.
spot_angle_inner	Inner cone angle of the spotlight in degrees.
spot_angle_outer	Outer cone angle of the spotlight in degrees.
uid

angular_radius: float

Angular radius of the sun disc in degrees. Reserved for future use.

color: tuple[float, float, float]

RGB color of the light source. Defaults to white (1.0, 1.0, 1.0).

direction: tuple[float, float, float]

Direction vector for directional, spot, rect, and mesh lights. Defaults to (0.0, 0.0, -1.0) (pointing down along -Z).

enable_shadow: bool

Whether the light casts shadows. Defaults to True.

halo_falloff: float

Halo falloff for sun light. Reserved for future use.

halo_size: float

Halo size for sun light. Reserved for future use.

init_local_pose: ndarray | None

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 in watts/m^2. Defaults to 30.0.

light_type: Literal['point', 'sun', 'direction', 'spot', 'rect', 'mesh']

"point", "sun", "direction", "spot", "rect", "mesh".

Type:

Light type. Supported

mesh_path: str

Asset path for mesh-based emissive lights. Only used when light_type="mesh". The actual mesh assignment is done via embodichain.lab.sim.objects.light.Light.set_mesh() which accepts a dexsim.models.MeshObject. This field stores the path for reference.

radius: float

Falloff radius for point lights. Only used when light_type="point". Defaults to 10.0.

rect_height: float

Height of the rectangular area light. Only used when light_type="rect". Defaults to 1.0.

rect_width: float

Width of the rectangular area light. Only used when light_type="rect". Defaults to 1.0.

spot_angle_inner: float

Inner cone angle of the spotlight in degrees. Only used when light_type="spot". Defaults to 30.0.

spot_angle_outer: float

Outer cone angle of the spotlight in degrees. Only used when light_type="spot". Defaults to 45.0.

uid: str | None

class embodichain.lab.sim.cfg.LinkPhysicsOverrideCfg

Bases: object

Per-link physics override matched by regex on articulation link names.

Attributes:

attrs	Partial attribute overrides applied on top of ArticulationCfg.attrs.
link_names_expr	Regex patterns matched against link names (full match).
replace_inertial	Whether to recompute inertia when mass is overridden (DexSim flag).

Methods:

from_dict(init_dict)

Initialize the configuration from a dictionary.

attrs: RigidBodyAttributesOverrideCfg

Partial attribute overrides applied on top of ArticulationCfg.attrs.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

LinkPhysicsOverrideCfg

link_names_expr: list[str]

Regex patterns matched against link names (full match).

replace_inertial: bool

Whether to recompute inertia when mass is overridden (DexSim flag).

class embodichain.lab.sim.cfg.MarkerCfg

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: Tensor | None

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

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)

Initialize the configuration from a dictionary.

Return type:

ObjectBaseCfg

init_local_pose: ndarray | None

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: str | None

class embodichain.lab.sim.cfg.PhysicsCfg

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	The speed threshold below which collisions will not produce bounce effects.
enable_ccd	Enable continuous collision detection (CCD) for fast-moving objects.
enable_enhanced_determinism	Enable enhanced determinism for consistent simulation results.
enable_friction_every_iteration	Enable friction calculations at every solver iteration.
enable_pcm	Enable persistent contact manifold (PCM) for improved collision handling.
enable_tgs	Enable temporal gauss-seidel (TGS) solver for better stability.
gravity	Gravity vector for the simulation environment.
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

The speed threshold below which collisions will not produce bounce effects.

enable_ccd: bool

Enable continuous collision detection (CCD) for fast-moving objects.

enable_enhanced_determinism: bool

Enable enhanced determinism for consistent simulation results.

enable_friction_every_iteration: bool

Enable friction calculations at every solver iteration.

enable_pcm: bool

Enable persistent contact manifold (PCM) for improved collision handling.

enable_tgs: bool

Enable temporal gauss-seidel (TGS) solver for better stability.

gravity: ndarray

Gravity vector for the simulation environment.

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

Convert to dexsim physics args dictionary.

Return type:

Dict[str, Any]

class embodichain.lab.sim.cfg.RenderCfg

Bases: object

RenderCfg(renderer: “Literal[‘auto’, ‘hybrid’, ‘fast-rt’, ‘rt’]” = <factory>, spp: ‘int’ = <factory>, tone_mapping_enabled: ‘bool’ = <factory>, tone_mapping_exposure: ‘float’ = <factory>)

Methods:

apply_to_dexsim_config(world_config)	Apply rendering settings to a DexSim world configuration.
to_dexsim_flags()	Convert the renderer name to DexSim's renderer enum.

Attributes:

renderer	Renderer backend to use for the simulation.
spp	Samples per pixel for ray tracing rendering.
tone_mapping_enabled	Whether to map HDR RGB output with the modified Reinhard curve.
tone_mapping_exposure	Fixed linear exposure multiplier applied before tone mapping.

apply_to_dexsim_config(world_config)

Apply rendering settings to a DexSim world configuration.

Parameters:

world_config (WorldConfig) – DexSim world configuration to update in place.

Return type:

None

renderer: Literal['auto', 'hybrid', 'fast-rt', 'rt']

Renderer backend to use for the simulation. Options are ‘auto’, ‘hybrid’, ‘fast-rt’, and ‘rt’.

Note: - ‘auto’ selects a default renderer based on the detected GPU: RTX-series cards use

‘hybrid’, while datacenter cards (A100/A800, H100/H800/H200/H20) use ‘fast-rt’. If no CUDA device is available or the GPU is unknown, it falls back to ‘hybrid’.

• ‘hybrid’ uses ray tracing for shadows and reflections while keeping rasterization for primary rendering,

  providing a balance between performance and visual quality.

• ‘fast-rt’ is a fully ray-traced renderer for maximum visual fidelity, but may have higher computational cost.

• ‘rt’ is an offline ray-traced renderer for maximum visual fidelity, suitable for high-quality rendering tasks.

spp: int

Samples per pixel for ray tracing rendering. This parameter is only valid when renderer is ‘hybrid’, ‘fast-rt’ or ‘rt’.

to_dexsim_flags()

Convert the renderer name to DexSim’s renderer enum.

Return type:

Renderer

tone_mapping_enabled: bool

Whether to map HDR RGB output with the modified Reinhard curve.

tone_mapping_exposure: float

Fixed linear exposure multiplier applied before tone mapping.

class embodichain.lab.sim.cfg.RigidBodyAttributesCfg

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	Angular damping coefficient.
contact_offset	Contact offset for collision detection.
density	Density of the rigid body in kg/m^3.
dynamic_friction	Dynamic friction coefficient.
enable_ccd	Enable continuous collision detection (CCD).
enable_collision	Enable collision for the rigid body.
linear_damping	Linear damping coefficient.
mass	Mass of the rigid body in kilograms.
max_angular_velocity	Maximum angular velocity.
max_depenetration_velocity	Maximum depenetration velocity.
max_linear_velocity	Maximum linear velocity.
min_position_iters	Minimum position iterations.
min_velocity_iters	Minimum velocity iterations.
rest_offset	Rest offset for collision detection.
restitution	Restitution (bounciness) coefficient.
sleep_threshold	Threshold below which the body can go to sleep.
static_friction	Static friction coefficient.

Methods:

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

angular_damping: float

Angular damping coefficient.

attr()

Convert to dexsim PhysicalAttr

Return type:

PhysicalAttr

contact_offset: float

Contact offset for collision detection.

density: float

Density of the rigid body in kg/m^3.

dynamic_friction: float

Dynamic friction coefficient.

enable_ccd: bool

Enable continuous collision detection (CCD).

enable_collision: bool

Enable collision for the rigid body.

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

RigidBodyAttributesCfg

linear_damping: float

Linear damping coefficient.

mass: float

Mass of the rigid body in kilograms.

Set to 0 will use density to calculate mass.

max_angular_velocity: float

Maximum angular velocity.

max_depenetration_velocity: float

Maximum depenetration velocity.

max_linear_velocity: float

Maximum linear velocity.

min_position_iters: int

Minimum position iterations.

min_velocity_iters: int

Minimum velocity iterations.

rest_offset: float

Rest offset for collision detection.

restitution: float

Restitution (bounciness) coefficient.

sleep_threshold: float

Threshold below which the body can go to sleep.

static_friction: float

Static friction coefficient.

class embodichain.lab.sim.cfg.RigidBodyAttributesOverrideCfg

Bases: object

Partial rigid-body attribute overrides for per-link physics configuration.

Fields set to None are not applied and retain values from the base RigidBodyAttributesCfg.

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:

from_dict(init_dict)	Initialize the configuration from a dictionary.
merge_with(base)	Build a PhysicalAttr from base values and overrides.

angular_damping: float | None

contact_offset: float | None

density: float | None

dynamic_friction: float | None

enable_ccd: bool | None

enable_collision: bool | None

classmethod from_dict(init_dict)

Initialize the configuration from a dictionary.

Return type:

RigidBodyAttributesOverrideCfg

linear_damping: float | None

mass: float | None

max_angular_velocity: float | None

max_depenetration_velocity: float | None

max_linear_velocity: float | None

merge_with(base)

Build a PhysicalAttr from base values and overrides.

Return type:

PhysicalAttr

min_position_iters: int | None

min_velocity_iters: int | None

rest_offset: float | None

restitution: float | None

sleep_threshold: float | None

static_friction: float | None

class embodichain.lab.sim.cfg.RigidConstraintCfg

Bases: object

Configuration for a fixed constraint between two RigidObjects.

The constraint binds rigid_object_a’s entity[i] to rigid_object_b’s entity[i] within arena[i] (one constraint per arena).

Parameters:

• name (str) – Base constraint name. Per-arena names are derived as f"{name}" (single env) or f"{name}_{i}" (multi env).

• rigid_object_a_uid (str) – UID of the first RigidObject (must exist in the sim).

• rigid_object_b_uid (str) – UID of the second RigidObject (must exist in the sim).

• local_frame_a (ndarray | None) – 4x4 joint frame in object A’s local coordinates. None -> identity (object A’s origin). Accepts a single (4, 4) matrix (shared by all envs) or an (N, 4, 4) array (one frame per env). Defaults to None.

• local_frame_b (ndarray | None) – 4x4 joint frame in object B’s local coordinates. None -> the frame is computed per env as inv(pose_B) @ pose_A from the objects’ current poses, so the constraint welds the objects at their current relative pose (rather than pulling their origins together). An explicit (4, 4) or (N, 4, 4) value is used verbatim. Defaults to None.

• constraint_type (Literal['fixed']) – Reserved for future typed constraints (prismatic, revolute, spherical, d6). Only "fixed" is supported in v1.

Attention

Both objects must be RigidObject instances and must share the same number of arenas.

Attributes:

constraint_type	Constraint type.
local_frame_a	Local joint frame on object A.
local_frame_b	Local joint frame on object B.
name	Base name of the constraint (per-arena names are derived from this).
rigid_object_a_uid	UID of the first RigidObject.
rigid_object_b_uid	UID of the second RigidObject.

constraint_type: Literal['fixed']

Constraint type. Only "fixed" is supported in v1.

local_frame_a: ndarray | None

Local joint frame on object A. None -> identity (object A’s origin).

local_frame_b: ndarray | None

Local joint frame on object B. None -> inv(pose_B) @ pose_A per env (weld at the objects’ current relative pose).

name: str

Base name of the constraint (per-arena names are derived from this).

rigid_object_a_uid: str

UID of the first RigidObject.

rigid_object_b_uid: str

UID of the second RigidObject.

class embodichain.lab.sim.cfg.RigidObjectCfg

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:

acd_method	The method used for approximate convex decomposition (ACD) of the mesh.
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.
sdf_resolution	Resolution for the signed distance field (SDF) of the rigid body.
shape	Shape configuration for the rigid body.
uid
use_usd_properties	Whether to use physical properties from USD file instead of config.

Methods:

to_dexsim_body_type()

Convert the body type to dexsim ActorType.

acd_method: str

The method used for approximate convex decomposition (ACD) of the mesh.

Deprecated since version Use: MeshCfg.acd_method instead. This field is kept for backward compatibility and overrides the shape-level value when explicitly set.

Currently, "coacd" and "vhacd" are supported. Only used when max_convex_hull_num is set to larger than 1.

attrs: RigidBodyAttributesCfg

body_scale: tuple | list

Scale of the rigid body in the simulation world frame.

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

init_local_pose: ndarray | None

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.

Deprecated since version Use: MeshCfg.max_convex_hull_num instead. This field is kept for backward compatibility and overrides the shape-level value when explicitly set.

If set to larger than 1, the rigid body will be decomposed into multiple convex hulls using the approximate convex decomposition method specified by acd_method. Reference: SarahWeiii/CoACD

sdf_resolution: int

Resolution for the signed distance field (SDF) of the rigid body.

Deprecated since version Use: MeshCfg.sdf_resolution instead. This field is kept for backward compatibility and overrides the shape-level value when explicitly set.

The spacing of the uniformly sampled SDF is equal to the largest AABB extent of the mesh, divided by the resolution. If sdf_resolution is set to larger than 0, an SDF will be generated for collision detection. SDF will increase the accuracy of collision, but also takes more time to initialize and simulate.

shape: ShapeCfg

Shape configuration for the rigid body.

to_dexsim_body_type()

Convert the body type to dexsim ActorType.

Return type:

ActorType

uid: str | None

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values. Only effective for USD files.

class embodichain.lab.sim.cfg.RigidObjectGroupCfg

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: str | None

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)

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: str | None

class embodichain.lab.sim.cfg.RobotCfg

Bases: ArticulationCfg

RobotCfg(uid: ‘str | None’ = <factory>, init_pos: ‘tuple[float, float, float]’ = <factory>, init_rot: ‘tuple[float, float, float]’ = <factory>, init_local_pose: ‘np.ndarray | None’ = <factory>, fpath: ‘str’ = <factory>, drive_pros: ‘JointDrivePropertiesCfg’ = <factory>, body_scale: ‘tuple | list’ = <factory>, attrs: ‘RigidBodyAttributesCfg’ = <factory>, link_attrs: ‘dict[str, LinkPhysicsOverrideCfg] | None’ = <factory>, fix_base: ‘bool’ = <factory>, disable_self_collision: ‘bool’ = <factory>, init_qpos: ‘torch.Tensor | np.ndarray | Sequence[float]’ = <factory>, qpos_limits: ‘torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None’ = <factory>, sleep_threshold: ‘float’ = <factory>, min_position_iters: ‘int’ = <factory>, min_velocity_iters: ‘int’ = <factory>, build_pk_chain: ‘bool’ = <factory>, compute_uv: ‘bool’ = <factory>, use_usd_properties: ‘bool’ = <factory>, control_parts: ‘Dict[str, List[str]] | None’ = <factory>, urdf_cfg: ‘URDFCfg | None’ = <factory>, solver_cfg: ‘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.
compute_uv	Whether to compute the UV mapping for the articulation link.
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.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
qpos_limits	Override joint position limits of the articulation.
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.
use_usd_properties	Whether to use physical properties from USD file instead of config.

Methods:

build_pk_serial_chain([device])	Build the serial chain from the URDF file.
from_dict(init_dict)	Initialize the configuration from a dictionary.
save_to_file(filepath)	Save config to a local file as JSON.
to_string()	Return config as a JSON string.

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.
user_qpos_limits	User defined Joint position limits [2, DOF] for the solver.

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: List[float] | None

Weights for the inverse kinematics nearest calculation.

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

abstractmethod init_solver(device, **kwargs)

Return type:

BaseSolver

joint_names: list[str] | None

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: 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: str | None

The file path to the URDF model of the robot.

user_qpos_limits: List[float] | None

User defined Joint position limits [2, DOF] for the solver. If not provided (None), this value will replace by joint limits defined in urdf when solver init from robot. If provided, the solver will use the intersection of user defined limits and urdf limits as the final joint limits.

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: 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)

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]

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

control_parts: 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.

• Robot is a derived class of Articulation, with control parts support. So the drive_pros

  in ArticulationCfg can use control part as key to specify the corresponding joint drive properties, which will be overridden if these joint names are already specified.

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)

Initialize the configuration from a dictionary.

Return type:

RobotCfg

init_local_pose: np.ndarray | None

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: 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).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

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

qpos_limits: torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

save_to_file(filepath)

Save config to a local file as JSON.

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

solver_cfg: SolverCfg | Dict[str, SolverCfg] | None

Solver is used to compute forward and inverse kinematics for the robot.

to_string()

Return config as a JSON string.

uid: str | None

urdf_cfg: URDFCfg | None

URDF assembly configuration which allows for assembling a robot from multiple URDF components.

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.

class embodichain.lab.sim.cfg.SoftObjectCfg

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: ndarray | None

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: str | None

voxel_attr: SoftbodyVoxelAttributesCfg

Tetra mesh voxelization attributes for the soft body.

class embodichain.lab.sim.cfg.SoftbodyPhysicalAttributesCfg

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

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

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 physics collision mesh.
triangle_simplify_target	Simplify mesh faces to target value.

attr()

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 physics 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

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.
component_prefix	Component name prefixes used during URDF assembly.
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.
name_case	Case normalization policy applied to joint/link names during URDF assembly.
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)

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 (np.ndarray | None) – 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)

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

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.

component_prefix: List[tuple[str, str | None]]

Component name prefixes used during URDF assembly.

Preferred form is a list of (component_name, prefix) tuples. For convenience, a mapping {component_name: prefix} is also accepted when constructing URDFCfg and will be normalized internally.

components: Dict[str, Dict[str, str | Dict | ndarray]]

Dictionary of robot components to be assembled.

fname: str | None

Name used for output file and directory. If not specified, auto-generated from component names.

fpath: str | None

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)

Return type:

URDFCfg

name_case: dict[str, str]

Case normalization policy applied to joint/link names during URDF assembly.

Supported values per key are "upper", "lower" or "original" (legacy alias "none"). The default upper-cases joints and lower-cases links. Set {"joint": "original"} to preserve the source URDF casing.

sensors: Dict[str, Dict[str, str | ndarray]]

Dictionary of sensors to be attached to the robot.

set_urdf(urdf_path)

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.

class embodichain.lab.sim.cfg.WindowCameraPoseCfg

Bases: object

Configuration for printing the interactive viewer camera pose.

Attributes:

convert_to_look_at	Whether the hotkey prints a set_look_at call instead of a matrix.
enable_hotkey	Whether to register the p hotkey when the window opens.

convert_to_look_at: bool

Whether the hotkey prints a set_look_at call instead of a matrix.

enable_hotkey: bool

Whether to register the p hotkey when the window opens.

class embodichain.lab.sim.cfg.WindowRecordCfg

Bases: object

Configuration for interactive viewer window recording.

Attributes:

enable_hotkey	Whether to register the r hotkey for viewer recording when the window opens.
fps	Frames per second for viewer recording.
max_memory	Maximum buffered recording memory in MB before auto-stopping capture.
save_path	Optional output path for viewer recordings.
video_prefix	Video file prefix used when no explicit save path is provided.

enable_hotkey: bool

Whether to register the r hotkey for viewer recording when the window opens.

fps: int

Frames per second for viewer recording.

max_memory: int

Maximum buffered recording memory in MB before auto-stopping capture.

save_path: str | None

Optional output path for viewer recordings. If None, use the default outputs directory.

video_prefix: str

Video file prefix used when no explicit save path is provided.

embodichain.lab.sim.cfg.link_attrs_from_dict(value)

Parse a link_attrs mapping from YAML/JSON-style dicts.

Return type:

dict[str, LinkPhysicsOverrideCfg]

Common Components

Classes:

BatchEntity

Abstract base class for batch entity in the simulation engine.

class embodichain.lab.sim.common.BatchEntity

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

cfg: ObjectBaseCfg = None

destroy()

Destroy all entities managed by this batch entity.

Return type:

None

device: device = None

abstractmethod get_local_pose(to_matrix=False)

Return type:

Tensor

property num_instances: int

property pose: Tensor

abstractmethod reset(env_ids=None)

Reset the entity to its initial state.

Parameters:

env_ids (Sequence[int] | None) – The environment IDs to reset. If None, reset all environments.

Return type:

None

abstractmethod set_local_pose(pose, env_ids=None)

Return type:

None

uid: str | None = None

Materials

Classes:

ReuseSegmentState	Reuse state for one render-body segment of a parsed object.
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.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

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.VisualMaterialCfg

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

__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>, 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)

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

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

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

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

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: 'VisualMaterialCfg | None' = <factory>)
SphereCfg	Configuration parameters for a sphere shape.

class embodichain.lab.sim.shapes.CubeCfg

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: VisualMaterialCfg | None

Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.LoadOption

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)

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

Bases: ShapeCfg

Configuration parameters for a triangle mesh shape.

Attributes:

acd_method	The method used for approximate convex decomposition (ACD) of the mesh.
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.
max_convex_hull_num	The maximum number of convex hulls that will be created for the mesh.
project_direction	Direction to project the UV coordinates.
sdf_resolution	Resolution for the signed distance field (SDF) of the mesh.
shape_type	Type of the shape.
visual_material	Configuration parameters for the visual material of the shape.

acd_method: str

The method used for approximate convex decomposition (ACD) of the mesh.

Currently, "coacd" and "vhacd" are supported. Only used when max_convex_hull_num is set to larger than 1.

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.

max_convex_hull_num: int

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

If set to larger than 1, the mesh will be decomposed into multiple convex hulls using the approximate convex decomposition method specified by acd_method. Reference: SarahWeiii/CoACD

project_direction: List[float]

Direction to project the UV coordinates. Defaults to [1.0, 1.0, 1.0].

sdf_resolution: int

Resolution for the signed distance field (SDF) of the mesh.

The spacing of the uniformly sampled SDF is equal to the largest AABB extent of the mesh, divided by the resolution. If sdf_resolution is set to larger than 0, an SDF will be generated for collision detection. SDF increases the accuracy of collision, but also takes more time to initialize and simulate.

shape_type: str

Type of the shape. Must be specified in subclasses.

visual_material: VisualMaterialCfg | None

Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.ShapeCfg

Bases: object

ShapeCfg(shape_type: ‘str’ = <factory>, visual_material: ‘VisualMaterialCfg | None’ = <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)

Initialize the configuration from a dictionary.

Return type:

ShapeCfg

shape_type: str

Type of the shape. Must be specified in subclasses.

visual_material: VisualMaterialCfg | None

Configuration parameters for the visual material of the shape. Defaults to None.

class embodichain.lab.sim.shapes.SphereCfg

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: VisualMaterialCfg | None

Configuration parameters for the visual material of the shape. Defaults to None.

Atomic Actions

Functions:

back_to_initial_pose(robot_name[, env])
close_gripper(robot_name[, env])
drive([left_arm_action, right_arm_action, env])
grasp(robot_name, obj_name[, pre_grasp_dis, ...])
move_by_relative_offset(robot_name[, dx, ...])
move_relative_to_object(robot_name, obj_name)
move_to_absolute_position(robot_name[, x, ...])
open_gripper(robot_name[, env])
orient_eef(robot_name[, direction, env, ...])
place_on_table(robot_name, obj_name[, x, y, ...])
rotate_eef(robot_name[, degree, env])
save_observations([step_id, step_name, env])

embodichain.lab.sim.atom_actions.back_to_initial_pose(robot_name, env=None, **kwargs)

embodichain.lab.sim.atom_actions.close_gripper(robot_name, env=None, **kwargs)

embodichain.lab.sim.atom_actions.drive(left_arm_action=None, right_arm_action=None, env=None, **kwargs)

embodichain.lab.sim.atom_actions.grasp(robot_name, obj_name, pre_grasp_dis=0.05, env=None, force_valid=False, **kwargs)

embodichain.lab.sim.atom_actions.move_by_relative_offset(robot_name, dx=0.0, dy=0.0, dz=0.0, mode='extrinsic', env=None, force_valid=False, **kwargs)

embodichain.lab.sim.atom_actions.move_relative_to_object(robot_name, obj_name, x_offset=0, y_offset=0, z_offset=0, env=None, force_valid=False, **kwargs)

embodichain.lab.sim.atom_actions.move_to_absolute_position(robot_name, x=None, y=None, z=None, env=None, force_valid=False, **kwargs)

embodichain.lab.sim.atom_actions.open_gripper(robot_name, env=None, **kwargs)

embodichain.lab.sim.atom_actions.orient_eef(robot_name, direction='front', env=None, force_valid=False, **kwargs)

embodichain.lab.sim.atom_actions.place_on_table(robot_name, obj_name, x=None, y=None, pre_place_dis=0.08, env=None, force_valid=False, **kwargs)

embodichain.lab.sim.atom_actions.rotate_eef(robot_name, degree=0, env=None, **kwargs)

embodichain.lab.sim.atom_actions.save_observations(step_id=0, step_name=None, env=None, **kwargs)

Objects

• embodichain.lab.sim.objects

Sensors

• embodichain.lab.sim.sensors

Robot Configurations

Classes:

CobotMagicCfg	CobotMagicCfg(uid: 'str | None' = <factory>, init_pos: 'tuple[float, float, float]' = <factory>, init_rot: 'tuple[float, float, float]' = <factory>, init_local_pose: 'np.ndarray | None' = <factory>, fpath: 'str' = <factory>, drive_pros: 'JointDrivePropertiesCfg' = <factory>, body_scale: 'tuple | list' = <factory>, attrs: 'RigidBodyAttributesCfg' = <factory>, link_attrs: 'dict[str, LinkPhysicsOverrideCfg] | None' = <factory>, fix_base: 'bool' = <factory>, disable_self_collision: 'bool' = <factory>, init_qpos: 'torch.Tensor | np.ndarray | Sequence[float]' = <factory>, qpos_limits: 'torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None' = <factory>, sleep_threshold: 'float' = <factory>, min_position_iters: 'int' = <factory>, min_velocity_iters: 'int' = <factory>, build_pk_chain: 'bool' = <factory>, compute_uv: 'bool' = <factory>, use_usd_properties: 'bool' = <factory>, control_parts: 'Dict[str, List[str]] | None' = <factory>, urdf_cfg: 'URDFCfg' = <factory>, solver_cfg: "Dict[str, 'SolverCfg'] | None" = <factory>)
DexforceW1Cfg	DexforceW1 specific configuration, inherits from RobotCfg and allows custom parameters.
DualArmRobotCfg	Configuration for a dual-manipulator composed from a single-arm robot.
FrankaPandaCfg	Configuration for the Franka Emika Panda robot with Panda hand.
URRobotCfg	Configuration for the UR family of robots.

Functions:

build_dual_arm_cfg(base_cfg, mounts, *[, ...])

Build a dual-arm cfg from a single-arm robot cfg.

class embodichain.lab.sim.robots.CobotMagicCfg

Bases: RobotCfg

CobotMagicCfg(uid: ‘str | None’ = <factory>, init_pos: ‘tuple[float, float, float]’ = <factory>, init_rot: ‘tuple[float, float, float]’ = <factory>, init_local_pose: ‘np.ndarray | None’ = <factory>, fpath: ‘str’ = <factory>, drive_pros: ‘JointDrivePropertiesCfg’ = <factory>, body_scale: ‘tuple | list’ = <factory>, attrs: ‘RigidBodyAttributesCfg’ = <factory>, link_attrs: ‘dict[str, LinkPhysicsOverrideCfg] | None’ = <factory>, fix_base: ‘bool’ = <factory>, disable_self_collision: ‘bool’ = <factory>, init_qpos: ‘torch.Tensor | np.ndarray | Sequence[float]’ = <factory>, qpos_limits: ‘torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None’ = <factory>, sleep_threshold: ‘float’ = <factory>, min_position_iters: ‘int’ = <factory>, min_velocity_iters: ‘int’ = <factory>, build_pk_chain: ‘bool’ = <factory>, compute_uv: ‘bool’ = <factory>, use_usd_properties: ‘bool’ = <factory>, control_parts: ‘Dict[str, List[str]] | None’ = <factory>, urdf_cfg: ‘URDFCfg’ = <factory>, solver_cfg: “Dict[str, ‘SolverCfg’] | None” = <factory>)

Methods:

__init__([uid, init_pos, init_rot, ...])
build_pk_serial_chain([device])	Build the serial chain from the URDF file.
copy(**kwargs)	Return a new object replacing specified fields with new values.
from_dict(init_dict)	Initialize the configuration from a dictionary.
replace(**kwargs)	Return a new object replacing specified fields with new values.
validate([prefix])	Check the validity of configclass object.

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.
compute_uv	Whether to compute the UV mapping for the articulation link.
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.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
qpos_limits	Override joint position limits of the articulation.
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.
use_usd_properties	Whether to use physical properties from USD file instead of config.

__init__(uid=<factory>, init_pos=<factory>, init_rot=<factory>, init_local_pose=<factory>, fpath=<factory>, drive_pros=<factory>, body_scale=<factory>, attrs=<factory>, link_attrs=<factory>, fix_base=<factory>, disable_self_collision=<factory>, init_qpos=<factory>, qpos_limits=<factory>, sleep_threshold=<factory>, min_position_iters=<factory>, min_velocity_iters=<factory>, build_pk_chain=<factory>, compute_uv=<factory>, use_usd_properties=<factory>, control_parts=<factory>, urdf_cfg=<factory>, solver_cfg=<factory>)

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: 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)

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]

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

control_parts: 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.

• Robot is a derived class of Articulation, with control parts support. So the drive_pros

  in ArticulationCfg can use control part as key to specify the corresponding joint drive properties, which will be overridden if these joint names are already specified.

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.

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)

Initialize the configuration from a dictionary.

Return type:

CobotMagicCfg

init_local_pose: np.ndarray | None

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: 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).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

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

qpos_limits: torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

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.

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

solver_cfg: Dict[str, 'SolverCfg'] | None

Solver is used to compute forward and inverse kinematics for the robot.

uid: str | None

urdf_cfg: URDFCfg

URDF assembly configuration which allows for assembling a robot from multiple URDF components.

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.

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.robots.DexforceW1Cfg

Bases: RobotCfg

DexforceW1 specific configuration, inherits from RobotCfg and allows custom parameters.

Methods:

__init__([uid, init_pos, init_rot, ...])
build_pk_serial_chain([device])	Build the serial chain from the URDF file.
copy(**kwargs)	Return a new object replacing specified fields with new values.
from_dict(init_dict)	Initialize DexforceW1Cfg from a dictionary.
replace(**kwargs)	Return a new object replacing specified fields with new values.
validate([prefix])	Check the validity of configclass object.

Attributes:

arm_kind
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.
compute_uv	Whether to compute the UV mapping for the articulation link.
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.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
qpos_limits	Override joint position limits of the articulation.
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.
use_usd_properties	Whether to use physical properties from USD file instead of config.
version
with_default_eef

__init__(uid=<factory>, init_pos=<factory>, init_rot=<factory>, init_local_pose=<factory>, fpath=<factory>, drive_pros=<factory>, body_scale=<factory>, attrs=<factory>, link_attrs=<factory>, fix_base=<factory>, disable_self_collision=<factory>, init_qpos=<factory>, qpos_limits=<factory>, sleep_threshold=<factory>, min_position_iters=<factory>, min_velocity_iters=<factory>, build_pk_chain=<factory>, compute_uv=<factory>, use_usd_properties=<factory>, control_parts=<factory>, urdf_cfg=<factory>, solver_cfg=<factory>, version=<factory>, arm_kind=<factory>, with_default_eef=<factory>)

arm_kind: DexforceW1ArmKind

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: 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)

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]

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

control_parts: 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.

• Robot is a derived class of Articulation, with control parts support. So the drive_pros

  in ArticulationCfg can use control part as key to specify the corresponding joint drive properties, which will be overridden if these joint names are already specified.

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.

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)

Initialize DexforceW1Cfg from a dictionary.

Parameters:

init_dict (Dict[str, str | float | tuple | dict]) – Dictionary of configuration parameters.

Return type:

DexforceW1Cfg

Returns:

A DexforceW1Cfg instance. Defaults are built via _build_defaults(), then init_dict overrides are merged.

init_local_pose: np.ndarray | None

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: 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).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

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

qpos_limits: torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

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.

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

solver_cfg: SolverCfg | Dict[str, SolverCfg] | None

Solver is used to compute forward and inverse kinematics for the robot.

uid: str | None

urdf_cfg: URDFCfg | None

URDF assembly configuration which allows for assembling a robot from multiple URDF components.

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.

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.

version: DexforceW1Version

with_default_eef: bool

class embodichain.lab.sim.robots.DualArmRobotCfg

Bases: RobotCfg

Configuration for a dual-manipulator composed from a single-arm robot.

Two identical arms (the base_robot) are mounted on a shared synthetic base_link. The left/right control_parts, per-arm solver_cfg and mirrored drive_pros are derived automatically by build_dual_arm_cfg().

Example

cfg = DualArmRobotCfg.from_dict(

{“base_robot”: “ur5”,

“mount”: {“preset”: “side_by_side”, “separation”: 0.6}}

) robot = sim.add_robot(cfg=cfg)

Methods:

__init__([uid, init_pos, init_rot, ...])
build_pk_serial_chain([device])	Build the per-arm pytorch-kinematics serial chains.
copy(**kwargs)	Return a new object replacing specified fields with new values.
from_dict(init_dict)	Initialize from a dictionary.
replace(**kwargs)	Return a new object replacing specified fields with new values.
validate([prefix])	Check the validity of configclass object.

Attributes:

arm_part	Name of the base robot's manipulator control part.
attrs	Physical attributes for all links.
base_robot	Registry key (e.g. "ur5") or {"type": ..., "init": {...}}.
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.
compute_uv	Whether to compute the UV mapping for the articulation link.
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.
dual_part	Whether to emit a "dual_arm" composite control part.
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.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
mount	Mount configuration consumed by resolve_mounts().
qpos_limits	Override joint position limits of the articulation.
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.
use_usd_properties	Whether to use physical properties from USD file instead of config.

__init__(uid=<factory>, init_pos=<factory>, init_rot=<factory>, init_local_pose=<factory>, fpath=<factory>, drive_pros=<factory>, body_scale=<factory>, attrs=<factory>, link_attrs=<factory>, fix_base=<factory>, disable_self_collision=<factory>, init_qpos=<factory>, qpos_limits=<factory>, sleep_threshold=<factory>, min_position_iters=<factory>, min_velocity_iters=<factory>, build_pk_chain=<factory>, compute_uv=<factory>, use_usd_properties=<factory>, control_parts=<factory>, urdf_cfg=<factory>, solver_cfg=<factory>, base_robot=<factory>, arm_part=<factory>, dual_part=<factory>, mount=<factory>)

arm_part: str

Name of the base robot’s manipulator control part.

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

base_robot: str | dict

Registry key (e.g. "ur5") or {"type": ..., "init": {...}}.

body_scale: 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)

Build the per-arm pytorch-kinematics serial chains.

Each chain is built from the single-arm URDF with the (arm-local) root and end link names taken from the left-arm solver, mirroring the CobotMagicCfg pattern. Both arms share one URDF; the chains are keyed "left_arm" / "right_arm" for API symmetry.

Parameters:

• device (device) – The device to move the chains to. Defaults to CPU.

• **kwargs – Additional arguments for building the serial chains.

Return type:

Dict[str, SerialChain]

Returns:

A {"left_arm": chain, "right_arm": chain} mapping.

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

control_parts: 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.

• Robot is a derived class of Articulation, with control parts support. So the drive_pros

  in ArticulationCfg can use control part as key to specify the corresponding joint drive properties, which will be overridden if these joint names are already specified.

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.

disable_self_collision: bool

Whether to enable or disable self-collisions.

drive_pros: JointDrivePropertiesCfg

Properties to define the drive mechanism of a joint.

dual_part: bool

Whether to emit a "dual_arm" composite control part.

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)

Initialize from a dictionary.

Parameters:

init_dict (dict) – Configuration dict. base_robot, mount, arm_part and dual_part drive the dual-arm derivation; all other recognized RobotCfg keys are merged on top via merge_robot_cfg().

Return type:

DualArmRobotCfg

Returns:

A DualArmRobotCfg instance.

init_local_pose: np.ndarray | None

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: 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).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

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

mount: dict

Mount configuration consumed by resolve_mounts().

qpos_limits: torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

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.

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

solver_cfg: SolverCfg | Dict[str, SolverCfg] | None

Solver is used to compute forward and inverse kinematics for the robot.

uid: str | None

urdf_cfg: URDFCfg | None

URDF assembly configuration which allows for assembling a robot from multiple URDF components.

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.

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.robots.FrankaPandaCfg

Bases: RobotCfg

Configuration for the Franka Emika Panda robot with Panda hand.

The PandaWithHand URDF includes both the 7-DOF arm and the parallel-jaw gripper in a single file. The solver defaults to PytorchSolverCfg.

Example

cfg = FrankaPandaCfg.from_dict({“robot_type”: “panda”}) robot = sim.add_robot(cfg=cfg)

Methods:

__init__([uid, init_pos, init_rot, ...])
build_pk_serial_chain([device])	Build the pytorch-kinematics serial chain for the arm.
copy(**kwargs)	Return a new object replacing specified fields with new values.
from_dict(init_dict)	Initialize FrankaPandaCfg from a dictionary.
replace(**kwargs)	Return a new object replacing specified fields with new values.
validate([prefix])	Check the validity of configclass object.

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.
compute_uv	Whether to compute the UV mapping for the articulation link.
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.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
qpos_limits	Override joint position limits of the articulation.
robot_type
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.
use_usd_properties	Whether to use physical properties from USD file instead of config.

__init__(uid=<factory>, init_pos=<factory>, init_rot=<factory>, init_local_pose=<factory>, fpath=<factory>, drive_pros=<factory>, body_scale=<factory>, attrs=<factory>, link_attrs=<factory>, fix_base=<factory>, disable_self_collision=<factory>, init_qpos=<factory>, qpos_limits=<factory>, sleep_threshold=<factory>, min_position_iters=<factory>, min_velocity_iters=<factory>, build_pk_chain=<factory>, compute_uv=<factory>, use_usd_properties=<factory>, control_parts=<factory>, urdf_cfg=<factory>, solver_cfg=<factory>, robot_type=<factory>)

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: 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)

Build the pytorch-kinematics serial chain for the arm.

Parameters:

• device (device) – The device to which the chain will be moved. Defaults to CPU.

• **kwargs – Additional arguments for building the serial chain.

Return type:

Dict[str, SerialChain]

Returns:

A {"arm": pk.SerialChain} mapping.

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

control_parts: 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.

• Robot is a derived class of Articulation, with control parts support. So the drive_pros

  in ArticulationCfg can use control part as key to specify the corresponding joint drive properties, which will be overridden if these joint names are already specified.

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.

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)

Initialize FrankaPandaCfg from a dictionary.

Parameters:

init_dict – Dictionary of configuration parameters. robot_type selects the Franka variant (currently "panda"). All other keys are merged on top of the defaults via merge_robot_cfg().

Returns:

A FrankaPandaCfg instance.

init_local_pose: np.ndarray | None

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: 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).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

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

qpos_limits: torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

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.

robot_type: str

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

solver_cfg: SolverCfg | Dict[str, SolverCfg] | None

Solver is used to compute forward and inverse kinematics for the robot.

uid: str | None

urdf_cfg: URDFCfg | None

URDF assembly configuration which allows for assembling a robot from multiple URDF components.

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.

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.robots.URRobotCfg

Bases: RobotCfg

Configuration for the UR family of robots.

One config class covers UR3 / UR3e / UR5 / UR5e / UR10 / UR10e, selected via robot_type. The kinematic (DH) parameters are owned by URSolverCfg; this config owns the URDF, control parts, drive properties and rigid-body attributes.

Example

cfg = URRobotCfg.from_dict({“robot_type”: “ur5”}) robot = sim.add_robot(cfg=cfg)

Methods:

__init__([uid, init_pos, init_rot, ...])
build_pk_serial_chain([device])	Build the pytorch-kinematics serial chain for the arm.
copy(**kwargs)	Return a new object replacing specified fields with new values.
from_dict(init_dict)	Initialize URRobotCfg from a dictionary.
replace(**kwargs)	Return a new object replacing specified fields with new values.
validate([prefix])	Check the validity of configclass object.

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.
compute_uv	Whether to compute the UV mapping for the articulation link.
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.
link_attrs	Named per-link physics override groups keyed by regex on link names.
min_position_iters	[1,255].
min_velocity_iters	[0,255].
qpos_limits	Override joint position limits of the articulation.
robot_type
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.
use_usd_properties	Whether to use physical properties from USD file instead of config.

__init__(uid=<factory>, init_pos=<factory>, init_rot=<factory>, init_local_pose=<factory>, fpath=<factory>, drive_pros=<factory>, body_scale=<factory>, attrs=<factory>, link_attrs=<factory>, fix_base=<factory>, disable_self_collision=<factory>, init_qpos=<factory>, qpos_limits=<factory>, sleep_threshold=<factory>, min_position_iters=<factory>, min_velocity_iters=<factory>, build_pk_chain=<factory>, compute_uv=<factory>, use_usd_properties=<factory>, control_parts=<factory>, urdf_cfg=<factory>, solver_cfg=<factory>, robot_type=<factory>)

attrs: RigidBodyAttributesCfg

Physical attributes for all links. We use default mass from the USD/URDF file if available. The mass and density in attrs will only be used if specified.

body_scale: 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)

Build the pytorch-kinematics serial chain for the arm.

Parameters:

• device (device) – The device to which the chain will be moved. Defaults to CPU.

• **kwargs – Additional arguments for building the serial chain.

Return type:

Dict[str, SerialChain]

Returns:

A {"arm": pk.SerialChain} mapping.

compute_uv: bool

Whether to compute the UV mapping for the articulation link.

Currently, the uv mapping is computed for each link with projection uv mapping method.

control_parts: 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.

• Robot is a derived class of Articulation, with control parts support. So the drive_pros

  in ArticulationCfg can use control part as key to specify the corresponding joint drive properties, which will be overridden if these joint names are already specified.

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.

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)

Initialize URRobotCfg from a dictionary.

Parameters:

init_dict – Dictionary of configuration parameters. robot_type selects the UR variant (ur3/ur3e/ur5/ur5e/ ur10/ur10e); all other keys are merged on top of the defaults via merge_robot_cfg().

Returns:

A URRobotCfg instance.

init_local_pose: np.ndarray | None

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: 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).

link_attrs: dict[str, LinkPhysicsOverrideCfg] | None

Named per-link physics override groups keyed by regex on link names.

Each group applies LinkPhysicsOverrideCfg.attrs on top of attrs for matched links only. A link must not match more than one group.

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

qpos_limits: torch.Tensor | np.ndarray | Sequence[float] | Dict[str, List[float]] | None

Override joint position limits of the articulation.

If None, the joint position limits from the asset file (URDF/USD) are used. If provided as a tensor/array of shape (num_joints, 2), it is applied to all joints in the order of joint_names. If provided as a dictionary, keys are joint names or regular expressions and values are [min, max] limits.

This field replaces the asset limits for the articulation and can be used to either tighten or expand the allowed range.

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.

robot_type: str

sleep_threshold: float

[0, max_float32]

Type:

Energy below which the articulation may go to sleep. Range

solver_cfg: SolverCfg | Dict[str, SolverCfg] | None

Solver is used to compute forward and inverse kinematics for the robot.

uid: str | None

urdf_cfg: URDFCfg | None

URDF assembly configuration which allows for assembling a robot from multiple URDF components.

use_usd_properties: bool

Whether to use physical properties from USD file instead of config.

When True: Keep all physical properties (drive, physics attrs, etc.) from USD file. When False (default): Override USD properties with config values (URDF behavior). Only effective for USD files, ignored for URDF files.

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.

embodichain.lab.sim.robots.build_dual_arm_cfg(base_cfg, mounts, *, dual_part=True, arm_part='arm')

Build a dual-arm cfg from a single-arm robot cfg.

Parameters:

• base_cfg (RobotCfg) – A constructed single-arm RobotCfg following the "arm" convention.

• mounts (Dict[str, ndarray]) – {"left": T, "right": T} 4x4 mount transforms from resolve_mounts().

• dual_part (bool) – Whether to include a "dual_arm" composite control part.

• arm_part (str) – The base cfg’s manipulator part name.

Return type:

DualArmRobotCfg

Returns:

A populated DualArmRobotCfg.

Example

base = URRobotCfg.from_dict({“robot_type”: “ur5”}) mounts = resolve_mounts({“preset”: “side_by_side”, “separation”: 0.6}) cfg = build_dual_arm_cfg(base, mounts)

Solvers

• embodichain.lab.sim.solvers

Planners

• embodichain.lab.sim.planners

Atomic Actions

• embodichain.lab.sim.atomic_actions

Shared Types

Utility

• embodichain.lab.sim.utility