embodichain.lab.gym.envs

Submodules

managers

Environment Classes

class embodichain.lab.gym.envs.BaseEnv

Bases: Env

Base environment for robot learning.

Parameters:

• cfg (EnvCfg) – The environment configuration.

• **kwargs – Additional keyword arguments.

Methods:

__init__(cfg, **kwargs)
add_camera_group_id(group_id)	Add a camera group ID for rendering.
add_detached_uids_for_reset(uids)	Add the UIDs of objects that are detached from automatic reset.
check_truncated(obs, info)	Check if the episode is truncated.
close()	Close the environment and release resources.
evaluate(**kwargs)	Evaluate whether the environment is currently in a success state by returning a dictionary with a "success" key or a failure state via a "fail" key
get_info(**kwargs)	Get info about the current environment state, include elapsed steps, success, fail, etc.
get_obs(**kwargs)	Get the observation from the robot agent and the environment.
get_reward(obs, action, info)	Get the reward for the current step.
get_sensor(name, **kwargs)	Get the sensor instance by name.
get_wrapper_attr(name)	Gets the attribute name from the environment.
has_wrapper_attr(name)	Checks if the attribute name exists in the environment.
is_task_success(**kwargs)	Determine if the task is successfully completed.
render()	Compute the render frames as specified by render_mode during the initialization of the environment.
reset([seed, options])	Reset the SimulationManager environment and return the observation and info.
set_wrapper_attr(name, value, *[, force])	Sets the attribute name on the environment with value, see Wrapper.set_wrapper_attr for more info.
step(action, **kwargs)	Step the environment with the given action.

Attributes:

device	Return the device used by the environment.
flattened_observation_space	Flattened observation space for RL training.
has_sensors	Return whether the environment has sensors.
np_random	Returns the environment's internal _np_random that if not set will initialise with a random seed.
np_random_seed	Returns the environment's internal _np_random_seed that if not set will first initialise with a random int as seed.
num_envs	Return the number of environments simulated in parallel.
unwrapped	Returns the base non-wrapped environment.

__init__(cfg, **kwargs)

add_camera_group_id(group_id)

Add a camera group ID for rendering.

Parameters:

group_id (int) – The camera group ID to be added.

Return type:

None

add_detached_uids_for_reset(uids)

Add the UIDs of objects that are detached from automatic reset.

Parameters:

uids (List[str]) – The list of UIDs to be detached from automatic reset.

Return type:

None

check_truncated(obs, info)

Check if the episode is truncated.

Parameters:

• obs (TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]]) – The observation from the environment.

• info (TensorDict[str, Any]) – The info dictionary.

Return type:

Tensor

Returns:

A boolean tensor indicating truncation for each environment in the batch.

close()

Close the environment and release resources.

Return type:

None

property device: device

Return the device used by the environment.

evaluate(**kwargs)

Evaluate whether the environment is currently in a success state by returning a dictionary with a “success” key or a failure state via a “fail” key

This function may also return additional data that has been computed (e.g. is the robot grasping some object) that may be reused when generating observations and rewards.

By default if not overridden, this function returns an empty dictionary

Parameters:

**kwargs – Additional keyword arguments to be passed to the evaluate() function.

Return type:

Dict[str, Any]

Returns:

The evaluation dictionary.

property flattened_observation_space: Box

Flattened observation space for RL training.

Returns a Box space by computing total dimensions from nested dict observations. This is needed because RL algorithms (PPO, SAC, etc.) require flat vector inputs.

get_info(**kwargs)

Get info about the current environment state, include elapsed steps, success, fail, etc.

The returned info dictionary must contain at the success and fail status of the current step.

Parameters:

**kwargs – Additional keyword arguments to be passed to the get_info() function.

Return type:

TensorDict[str, Any]

Returns:

The info dictionary.

get_obs(**kwargs)

Get the observation from the robot agent and the environment.

The default observation are:

• robot: the robot proprioception.

• sensor (optional): the sensor readings.

• extra (optional): any extra information.

Parameters:

**kwargs – Additional keyword arguments to be passed to the _get_sensor_obs() functions.

Return type:

TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]]

Returns:

The observation dictionary.

get_reward(obs, action, info)

Get the reward for the current step.

Each SimulationManager env must implement its own get_reward function to define the reward function for the task, If the env is considered for RL/IL training.

Parameters:

• obs (TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]]) – The observation from the environment.

• action (Union[Tensor, TensorDict[str, Tensor]]) – The action applied to the robot agent.

• info (Dict[str, Any]) – The info dictionary.

Return type:

float

Returns:

The reward for the current step.

get_sensor(name, **kwargs)

Get the sensor instance by name.

Parameters:

• name (str) – The name of the sensor.

• kwargs – Additional keyword arguments.

Return type:

BaseSensor

Returns:

The sensor instance.

get_wrapper_attr(name)

Gets the attribute name from the environment.

Return type:

Any

property has_sensors: bool

Return whether the environment has sensors.

has_wrapper_attr(name)

Checks if the attribute name exists in the environment.

Return type:

bool

is_task_success(**kwargs)

Determine if the task is successfully completed. This is mainly used in the data generation process of the imitation learning.

Parameters:

**kwargs – Additional arguments for task-specific success criteria.

Returns:

A boolean tensor indicating success for each environment in the batch.

Return type:

torch.Tensor

property np_random: Generator

Returns the environment’s internal _np_random that if not set will initialise with a random seed.

Returns:

Instances of np.random.Generator

property np_random_seed: int

Returns the environment’s internal _np_random_seed that if not set will first initialise with a random int as seed.

If np_random_seed was set directly instead of through reset() or set_np_random_through_seed(), the seed will take the value -1.

Returns:

the seed of the current np_random or -1, if the seed of the rng is unknown

Return type:

int

property num_envs: int

Return the number of environments simulated in parallel.

render()

Compute the render frames as specified by render_mode during the initialization of the environment.

The environment’s metadata render modes (env.metadata[“render_modes”]) should contain the possible ways to implement the render modes. In addition, list versions for most render modes is achieved through gymnasium.make which automatically applies a wrapper to collect rendered frames. :rtype: Union[TypeVar(RenderFrame), list[TypeVar(RenderFrame)], None]

Note

As the render_mode is known during __init__, the objects used to render the environment state should be initialised in __init__.

By convention, if the render_mode is:

• None (default): no render is computed.

• “human”: The environment is continuously rendered in the current display or terminal, usually for human consumption. This rendering should occur during step() and render() doesn’t need to be called. Returns None.

• “rgb_array”: Return a single frame representing the current state of the environment. A frame is a np.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.

• “ansi”: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors).

• “rgb_array_list” and “ansi_list”: List based version of render modes are possible (except Human) through the wrapper, gymnasium.wrappers.RenderCollection that is automatically applied during gymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped after render() is called or reset().

Note

Make sure that your class’s metadata "render_modes" key includes the list of supported modes.

Changed in version 0.25.0: The render function was changed to no longer accept parameters, rather these parameters should be specified in the environment initialised, i.e., gymnasium.make("CartPole-v1", render_mode="human")

reset(seed=None, options=None)

Reset the SimulationManager environment and return the observation and info.

Parameters:

• seed (Optional[int]) – The seed for the random number generator. Defaults to None, in which case the seed is not set.

• options (Optional[dict]) – Additional options for resetting the environment. This can include:

Return type:

Tuple[TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]], Dict]

Returns:

A tuple containing the observations and infos.

set_wrapper_attr(name, value, *, force=True)

Sets the attribute name on the environment with value, see Wrapper.set_wrapper_attr for more info.

Return type:

bool

step(action, **kwargs)

Step the environment with the given action.

Parameters:

action (Union[Tensor, TensorDict[str, Tensor]]) – The action applied to the robot agent.

Return type:

Tuple[TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]], Tensor, Tensor, Tensor, Dict[str, Any]]

Returns:

A tuple contraining the observation, reward, terminated, truncated, and info dictionary.

property unwrapped: Env[ObsType, ActType]

Returns the base non-wrapped environment.

Returns:

The base non-wrapped gymnasium.Env instance

Return type:

Env

class embodichain.lab.gym.envs.EnvCfg

Configuration for an Robot Learning Environment.

Methods:

copy(**kwargs)	Return a new object replacing specified fields with new values.
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:

ignore_terminations	Whether to ignore terminations when deciding when to auto reset.
max_episode_steps	The maximum number of steps per episode.
num_envs	The number of sub environments (arena in dexsim context) to be simulated in parallel.
seed	The seed for the random number generator.
sim_cfg	Simulation configuration for the environment.
sim_steps_per_control	Number of simulation steps per control (env) step.

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.

ignore_terminations: bool

Whether to ignore terminations when deciding when to auto reset. Terminations can be caused by the task reaching a success or fail state as defined in a task’s evaluation function.

If set to False, meaning there is early stop in episode rollouts. If set to True, this would generally for situations where you may want to model a task as infinite horizon where a task stops only due to the timelimit.

max_episode_steps: int

The maximum number of steps per episode. If set to -1, there is no limit on the episode length, and the episode will only end when the task is successfully completed or failed.

num_envs: int

The number of sub environments (arena in dexsim context) to be simulated in parallel.

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.

seed: int | None

The seed for the random number generator. Defaults to -1, in which case the seed is not set.

Note

The seed is set at the beginning of the environment initialization. This ensures that the environment creation is deterministic and behaves similarly across different runs.

sim_cfg: SimulationManagerCfg

Simulation configuration for the environment.

sim_steps_per_control: int

Number of simulation steps per control (env) step.

For instance, if the simulation dt is 0.01s and the control dt is 0.1s, then the sim_steps_per_control is 10. This means that the control action is updated every 10 simulation steps.

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.

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.gym.envs.EmbodiedEnv

Bases: BaseEnv

Embodied AI environment that is used to simulate the Embodied AI tasks.

Core simulation components for Embodied AI environments. - sensor: The sensors used to perceive the environment, which could be attached to the agent or the environment. - robot: The robot which will be used to interact with the environment. - light: The lights in the environment, which could be used to illuminate the environment.

• indirect: the indirect light sources, such as ambient light, IBL, etc.

  The indirect light sources are used for global illumination which affects the entire scene.

• direct: The direct light sources, such as point light, spot light, etc.

  The direct light sources are used for local illumination which mainly affects the arena in the scene.

• background: Kinematic or Static rigid objects, such as obstacles or landmarks.

• rigid_object: Dynamic objects that can be interacted with.

• rigid_object_group: Groups of rigid objects that can be interacted with.

• deformable_object(TODO: supported in the future): Deformable volumes or surfaces (cloth) that can be interacted with.

• articulation: Articulated objects that can be manipulated, such as doors, drawers, etc.

• event manager: The event manager is used to manage the events in the environment, such as randomization,

  perturbation, etc.

• observation manager: The observation manager is used to manage the observations in the environment,

  such as depth, segmentation, etc.

• action bank: The action bank is used to manage the actions in the environment, such as action composition, action graph, etc.

• affordance_datas: The affordance data that can be used to store the intermediate results or information

Methods:

__init__(cfg, **kwargs)
add_camera_group_id(group_id)	Add a camera group ID for rendering.
add_detached_uids_for_reset(uids)	Add the UIDs of objects that are detached from automatic reset.
check_truncated(obs, info)	Check if the episode is truncated.
close()	Close the environment and release resources.
compute_task_state(**kwargs)	Compute task-specific state: success, fail, and metrics.
create_demo_action_list(*args, **kwargs)	Create a demonstration action list for the environment.
evaluate(**kwargs)	Evaluate the environment state.
get_affordance(key[, default])	Get an affordance value by key.
get_info(**kwargs)	Get environment info dictionary.
get_obs(**kwargs)	Get the observation from the robot agent and the environment.
get_reward(obs, action, info)	Get the reward for the current step.
get_sensor(name, **kwargs)	Get the sensor instance by name.
get_wrapper_attr(name)	Gets the attribute name from the environment.
has_wrapper_attr(name)	Checks if the attribute name exists in the environment.
is_task_success(**kwargs)	Determine if the task is successfully completed.
preview_sensor_data(name[, data_type, ...])	Preview the sensor data by matplotlib
render()	Compute the render frames as specified by render_mode during the initialization of the environment.
reset([seed, options])	Reset the SimulationManager environment and return the observation and info.
set_affordance(key, value)	Set an affordance value by key.
set_rollout_buffer(rollout_buffer)	Set the rollout buffer for episode data collection.
set_wrapper_attr(name, value, *[, force])	Sets the attribute name on the environment with value, see Wrapper.set_wrapper_attr for more info.
step(action, **kwargs)	Step the environment with the given action.

Attributes:

device	Return the device used by the environment.
flattened_observation_space	Flattened observation space for RL training.
has_sensors	Return whether the environment has sensors.
np_random	Returns the environment's internal _np_random that if not set will initialise with a random seed.
np_random_seed	Returns the environment's internal _np_random_seed that if not set will first initialise with a random int as seed.
num_envs	Return the number of environments simulated in parallel.
unwrapped	Returns the base non-wrapped environment.

__init__(cfg, **kwargs)

add_camera_group_id(group_id)

Add a camera group ID for rendering.

Parameters:

group_id (int) – The camera group ID to be added.

Return type:

None

add_detached_uids_for_reset(uids)

Add the UIDs of objects that are detached from automatic reset.

Parameters:

uids (List[str]) – The list of UIDs to be detached from automatic reset.

Return type:

None

check_truncated(obs, info)

Check if the episode is truncated.

Parameters:

• obs (TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]]) – The observation from the environment.

• info (TensorDict[str, Any]) – The info dictionary.

Return type:

Tensor

Returns:

A boolean tensor indicating truncation for each environment in the batch.

close()

Close the environment and release resources.

Return type:

None

compute_task_state(**kwargs)

Compute task-specific state: success, fail, and metrics.

Override this method in subclass to define task-specific logic for RL tasks.

Returns:

• success: Boolean tensor of shape (num_envs,)

• fail: Boolean tensor of shape (num_envs,)

• metrics: Dict of metric tensors

Return type:

Tuple of (success, fail, metrics)

create_demo_action_list(*args, **kwargs)

Create a demonstration action list for the environment.

This function should be implemented in subclasses to generate a sequence of actions that demonstrate a specific task or behavior within the environment.

Returns:

A list of actions if a demonstration is available, otherwise None.

Return type:

Sequence[EnvAction] | None

property device: device

Return the device used by the environment.

evaluate(**kwargs)

Evaluate the environment state.

Return type:

Dict[str, Any]

Returns:

Evaluation dictionary with success and metrics

property flattened_observation_space: Box

Flattened observation space for RL training.

Returns a Box space by computing total dimensions from nested dict observations. This is needed because RL algorithms (PPO, SAC, etc.) require flat vector inputs.

get_affordance(key, default=None)

Get an affordance value by key.

Parameters:

• key (str) – The affordance key.

• default (Any, optional) – Default value if key not found.

Returns:

The affordance value or default.

Return type:

Any

get_info(**kwargs)

Get environment info dictionary.

Calls compute_task_state() to get task-specific success/fail/metrics when available. Subclasses should override compute_task_state() for RL tasks.

Return type:

Dict[str, Any]

Returns:

Info dictionary with success, fail, elapsed_steps, metrics

get_obs(**kwargs)

Get the observation from the robot agent and the environment.

The default observation are:

• robot: the robot proprioception.

• sensor (optional): the sensor readings.

• extra (optional): any extra information.

Parameters:

**kwargs – Additional keyword arguments to be passed to the _get_sensor_obs() functions.

Return type:

TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]]

Returns:

The observation dictionary.

get_reward(obs, action, info)

Get the reward for the current step.

Each SimulationManager env must implement its own get_reward function to define the reward function for the task, If the env is considered for RL/IL training.

Parameters:

• obs (TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]]) – The observation from the environment.

• action (Union[Tensor, TensorDict[str, Tensor]]) – The action applied to the robot agent.

• info (Dict[str, Any]) – The info dictionary.

Return type:

float

Returns:

The reward for the current step.

get_sensor(name, **kwargs)

Get the sensor instance by name.

Parameters:

• name (str) – The name of the sensor.

• kwargs – Additional keyword arguments.

Return type:

BaseSensor

Returns:

The sensor instance.

get_wrapper_attr(name)

Gets the attribute name from the environment.

Return type:

Any

property has_sensors: bool

Return whether the environment has sensors.

has_wrapper_attr(name)

Checks if the attribute name exists in the environment.

Return type:

bool

is_task_success(**kwargs)

Determine if the task is successfully completed. This is mainly used in the data generation process of the imitation learning.

Parameters:

**kwargs – Additional arguments for task-specific success criteria.

Returns:

A boolean tensor indicating success for each environment in the batch.

Return type:

torch.Tensor

property np_random: Generator

Returns the environment’s internal _np_random that if not set will initialise with a random seed.

Returns:

Instances of np.random.Generator

property np_random_seed: int

Returns the environment’s internal _np_random_seed that if not set will first initialise with a random int as seed.

If np_random_seed was set directly instead of through reset() or set_np_random_through_seed(), the seed will take the value -1.

Returns:

the seed of the current np_random or -1, if the seed of the rng is unknown

Return type:

int

property num_envs: int

Return the number of environments simulated in parallel.

preview_sensor_data(name, data_type='color', env_ids=0, method='cv2', save=False)

Preview the sensor data by matplotlib

Note

Currently only support RGB image preview.

Parameters:

• name (str) – name of the sensor to preview.

• data_type (str) – type of the sensor data to preview.

• env_ids (int) – index of the arena to preview. Defaults to 0.

• method (str) – method to preview the sensor data. Currently support “plt” and “cv2”. Defaults to “cv2”.

• save (bool) – whether to save the preview image. Defaults to False.

Return type:

None

render()

Compute the render frames as specified by render_mode during the initialization of the environment.

The environment’s metadata render modes (env.metadata[“render_modes”]) should contain the possible ways to implement the render modes. In addition, list versions for most render modes is achieved through gymnasium.make which automatically applies a wrapper to collect rendered frames. :rtype: Union[TypeVar(RenderFrame), list[TypeVar(RenderFrame)], None]

Note

As the render_mode is known during __init__, the objects used to render the environment state should be initialised in __init__.

By convention, if the render_mode is:

• None (default): no render is computed.

• “human”: The environment is continuously rendered in the current display or terminal, usually for human consumption. This rendering should occur during step() and render() doesn’t need to be called. Returns None.

• “rgb_array”: Return a single frame representing the current state of the environment. A frame is a np.ndarray with shape (x, y, 3) representing RGB values for an x-by-y pixel image.

• “ansi”: Return a strings (str) or StringIO.StringIO containing a terminal-style text representation for each time step. The text can include newlines and ANSI escape sequences (e.g. for colors).

• “rgb_array_list” and “ansi_list”: List based version of render modes are possible (except Human) through the wrapper, gymnasium.wrappers.RenderCollection that is automatically applied during gymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped after render() is called or reset().

Note

Make sure that your class’s metadata "render_modes" key includes the list of supported modes.

Changed in version 0.25.0: The render function was changed to no longer accept parameters, rather these parameters should be specified in the environment initialised, i.e., gymnasium.make("CartPole-v1", render_mode="human")

reset(seed=None, options=None)

Reset the SimulationManager environment and return the observation and info.

Parameters:

• seed (Optional[int]) – The seed for the random number generator. Defaults to None, in which case the seed is not set.

• options (Optional[dict]) – Additional options for resetting the environment. This can include:

Return type:

Tuple[TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]], Dict]

Returns:

A tuple containing the observations and infos.

set_affordance(key, value)

Set an affordance value by key.

Parameters:

• key (str) – The affordance key.

• value (Any) – The affordance value.

set_rollout_buffer(rollout_buffer)

Set the rollout buffer for episode data collection.

This function can be used to set the rollout buffer from outside of the environment, such as a shared rollout buffer initialized in model training process and passed to the environment for data collection.

Parameters:

rollout_buffer (TensorDict) – The rollout buffer to be set. The shape of the buffer should be (num_envs, max_episode_steps, *data_shape) for each key.

Return type:

None

set_wrapper_attr(name, value, *, force=True)

Sets the attribute name on the environment with value, see Wrapper.set_wrapper_attr for more info.

Return type:

bool

step(action, **kwargs)

Step the environment with the given action.

Parameters:

action (Union[Tensor, TensorDict[str, Tensor]]) – The action applied to the robot agent.

Return type:

Tuple[TensorDict[str, Union[Tensor, TensorDict[str, Tensor]]], Tensor, Tensor, Tensor, Dict[str, Any]]

Returns:

A tuple contraining the observation, reward, terminated, truncated, and info dictionary.

property unwrapped: Env[ObsType, ActType]

Returns the base non-wrapped environment.

Returns:

The base non-wrapped gymnasium.Env instance

Return type:

Env

class embodichain.lab.gym.envs.EmbodiedEnvCfg

Configuration for Embodied AI environments.

EmbodiedEnvCfg extends EnvCfg with high-level scene, robot, sensor, object and manager declarations used to build modular embodied environments. The configuration is intended to be declarative: the environment and its managers (events, observations, rewards, dataset) are assembled from the provided config fields with minimal additional code.

Typical usage: declare robots, sensors, lights, rigid objects/articulations, and manager configurations. Additional task-specific parameters can be supplied via the extensions dict and will be bound to the environment instance as attributes during initialization.

Key fields - robot: RobotCfg (required) — the agent definition (URDF/MJCF, initial

state, control mode, etc.).

• control_parts: Optional[List[str]] — named robot parts to control. If

  None, all controllable joints are used.

• active_joint_ids: List[int] — explicit joint indices to use for

  control (alternative to control_parts).

• sensor: List[SensorCfg] — sensors attached to the robot or scene

  (cameras, depth, segmentation, force sensors, …).

• light: EnvLightCfg — lighting configuration (direct lights now,

  indirect/IBL planned for future releases).

• background, rigid_object, rigid_object_group, articulation:

  scene object lists for static/kinematic props, dynamic objects, grouped object pools, and articulated mechanisms respectively.

• events: Optional manager config — event functors for startup/reset/

  periodic randomization and scripted behaviors.

• observations, rewards, dataset: Optional manager configs to

  compose observation transforms, reward functors, and dataset/recorder settings (auto-saving on episode completion).

• extensions: Optional[Dict[str, Any]] — arbitrary task-specific key/value

  pairs (e.g. success_threshold, control_frequency) that are automatically set on the config and bound to the environment instance.

• filter_visual_rand / filter_dataset_saving: booleans to disable

  visual randomization or dataset saving for debugging purposes.

• init_rollout_buffer: bool — when true (or when a dataset manager is

  present and dataset saving is enabled) the environment will initialize a rollout buffer matching the observation/action spaces for episode recording.

See EmbodiedEnv for usage patterns and the project documentation for full examples showing how to declare environments from these configs.

Classes:

EnvLightCfg

EnvLightCfg(direct: List[embodichain.lab.sim.cfg.LightCfg] = <factory>, indirect: dict[str, typing.Any] | None = <factory>)

Attributes:

actions	Action manager settings.
active_joint_ids	List of active joint IDs for control.
control_parts	List of robot parts to control.
dataset	Dataset settings.
events	Event settings.
extensions	Extension parameters for task-specific configurations.
filter_dataset_saving	Whether to filter out dataset saving
filter_visual_rand	Whether to filter out visual randomization
ignore_terminations	Whether to ignore terminations when deciding when to auto reset.
init_rollout_buffer	Whether to initialize the rollout buffer in the environment.
max_episode_steps	The maximum number of steps per episode.
num_envs	The number of sub environments (arena in dexsim context) to be simulated in parallel.
observations	Observation settings.
rewards	Reward settings.
seed	The seed for the random number generator.
sim_cfg	Simulation configuration for the environment.
sim_steps_per_control	Number of simulation steps per control (env) step.

Methods:

copy(**kwargs)	Return a new object replacing specified fields with new values.
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.

class EnvLightCfg

EnvLightCfg(direct: List[embodichain.lab.sim.cfg.LightCfg] = <factory>, indirect: dict[str, typing.Any] | None = <factory>)

Methods:

copy(**kwargs)	Return a new object replacing specified fields with new values.
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.

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.

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.

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.

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.

actions: Optional[object]

Action manager settings. Defaults to None, in which case no action preprocessing is applied.

When configured, the ActionManager preprocesses raw policy actions (e.g., delta_qpos, eef_pose) into robot control format.

Please refer to the embodichain.lab.gym.envs.managers.ActionManager class for more details.

active_joint_ids: List[int]

List of active joint IDs for control. User also can directly specify the active joint IDs instead of control parts. This is useful when the control parts are not well defined or we want to have more fine-grained control.

control_parts: list[str] | None

List of robot parts to control. If None, all controllable joints will be used. This is useful when we want to control only a subset of the robot joints for certain tasks or demonstrations.

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.

dataset: Optional[object]

Dataset settings. Defaults to None, in which case no dataset collection is performed.

Please refer to the embodichain.lab.gym.managers.DatasetManager class for more details.

events: Optional[object]

Event settings. Defaults to None, in which case no events are applied through the event manager.

Please refer to the embodichain.lab.gym.managers.EventManager class for more details.

extensions: Optional[Dict[str, Any]]

Extension parameters for task-specific configurations.

This field can be used to pass additional parameters that are specific to certain environments or tasks without modifying the base configuration class. For example: - success_threshold: Task-specific success distance threshold - vr_joint_mapping: VR joint mapping for teleoperation - control_frequency: Control frequency for VR teleoperation

Note: Action configuration (e.g., delta_qpos, scale) should use the actions field and ActionManager, not extensions.

filter_dataset_saving: bool

Whether to filter out dataset saving

This is useful when we want to disable dataset saving for debug motion and physics issues. If no dataset manager is configured, this flag will have no effect.

filter_visual_rand: bool

Whether to filter out visual randomization

This is useful when we want to disable visual randomization for debug motion and physics issues.

ignore_terminations: bool

Whether to ignore terminations when deciding when to auto reset. Terminations can be caused by the task reaching a success or fail state as defined in a task’s evaluation function.

If set to False, meaning there is early stop in episode rollouts. If set to True, this would generally for situations where you may want to model a task as infinite horizon where a task stops only due to the timelimit.

init_rollout_buffer: bool

Whether to initialize the rollout buffer in the environment.

If filter_dataset_saving is False and a dataset manager is configured, the rollout buffer will be initialized by default

max_episode_steps: int

The maximum number of steps per episode. If set to -1, there is no limit on the episode length, and the episode will only end when the task is successfully completed or failed.

num_envs: int

The number of sub environments (arena in dexsim context) to be simulated in parallel.

observations: Optional[object]

Observation settings. Defaults to None, in which case no additional observations are applied through the observation manager.

Please refer to the embodichain.lab.gym.managers.ObservationManager class for more details.

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.

rewards: Optional[object]

Reward settings. Defaults to None, in which case no reward computation is performed through the reward manager.

Please refer to the embodichain.lab.gym.managers.RewardManager class for more details.

seed: int | None

The seed for the random number generator. Defaults to -1, in which case the seed is not set.

Note

The seed is set at the beginning of the environment initialization. This ensures that the environment creation is deterministic and behaves similarly across different runs.

sim_cfg: SimulationManagerCfg

Simulation configuration for the environment.

sim_steps_per_control: int

Number of simulation steps per control (env) step.

For instance, if the simulation dt is 0.01s and the control dt is 0.1s, then the sim_steps_per_control is 10. This means that the control action is updated every 10 simulation steps.

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.

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.