embodichain.lab.gym.envs#
Submodules
Environment Classes#
- class embodichain.lab.gym.envs.BaseEnv[source]#
Bases:
EnvBase environment for robot learning.
- Parameters:
cfg (EnvCfg) – The environment configuration.
**kwargs – Additional keyword arguments.
Methods:
__init__(cfg, **kwargs)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.
render()Compute the render frames as specified by
render_modeduring the initialization of the environment.reset([seed, options])Reset the SimulationManager environment and return the observation and info.
step(action, **kwargs)Step the environment with the given action.
Attributes:
Return the device used by the environment.
Returns the environment's internal
_np_randomthat if not set will initialise with a random seed.Returns the base non-wrapped environment.
- check_truncated(obs, info)[source]#
Check if the episode is truncated.
- Parameters:
obs (
Dict[str,Union[Tensor,Dict[str,Tensor]]]) – The observation from the environment.info (
Dict[str,Any]) – The info dictionary.
- Return type:
bool- Returns:
True if the episode is truncated, False otherwise.
- property device: Tensor#
Return the device used by the environment.
- evaluate(**kwargs)[source]#
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.
- get_info(**kwargs)[source]#
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:
Dict[str,Any]- Returns:
The info dictionary.
- get_obs(**kwargs)[source]#
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.
Note
If self.num_envs == 1, return the observation in single_observation_space format. If self.num_envs > 1, return the observation in observation_space format.
- Parameters:
**kwargs – Additional keyword arguments to be passed to the
_get_sensor_obs()functions.- Return type:
Dict[str,Union[Tensor,Dict[str,Tensor]]]- Returns:
The observation dictionary.
- get_reward(obs, action, info)[source]#
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 (
Dict[str,Union[Tensor,Dict[str,Tensor]]]) – The observation from the environment.action (
Union[Tensor,Dict[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)[source]#
Get the sensor instance by name.
- Parameters:
name (
str) – The name of the sensor.kwargs – Additional keyword arguments.
- Return type:
- Returns:
The sensor instance.
- get_wrapper_attr(name)#
Gets the attribute name from the environment.
- Return type:
Any
- property np_random: Generator#
Returns the environment’s internal
_np_randomthat if not set will initialise with a random seed.- Returns:
Instances of np.random.Generator
- render()#
Compute the render frames as specified by
render_modeduring the initialization of the environment.The environment’s
metadatarender 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_modeis known during__init__, the objects used to render the environment state should be initialised in__init__.By convention, if the
render_modeis: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()andrender()doesn’t need to be called. ReturnsNone.“rgb_array”: Return a single frame representing the current state of the environment. A frame is a
np.ndarraywith shape(x, y, 3)representing RGB values for an x-by-y pixel image.“ansi”: Return a strings (
str) orStringIO.StringIOcontaining 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.RenderCollectionthat is automatically applied duringgymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped afterrender()is called orreset().
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)[source]#
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[Dict[str,Union[Tensor,Dict[str,Tensor]]],Dict]- Returns:
A tuple containing the observations and infos.
- step(action, **kwargs)[source]#
Step the environment with the given action.
- Parameters:
action (
Union[Tensor,Dict[str,Tensor]]) – The action applied to the robot agent.- Return type:
Tuple[Dict[str,Union[Tensor,Dict[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.Envinstance- Return type:
Env
- class embodichain.lab.gym.envs.EnvCfg[source]#
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:
Whether to ignore terminations when deciding when to auto reset.
The number of sub environments (arena in dexsim context) to be simulated in parallel.
The seed for the random number generator.
Simulation configuration for the environment.
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.
-
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:
Optional[int]# 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[source]#
Bases:
BaseEnvEmbodied 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)check_truncated(obs, info)Check if the episode is truncated.
close()Close the environment and release resources.
create_demo_action_list(*args, **kwargs)Create a demonstration action list for 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
get_affordance(key[, default])Get an affordance value by 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.
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_modeduring 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.
step(action, **kwargs)Step the environment with the given action.
to_dataset(id[, save_path])Convert the recorded episode data to a dataset format.
Attributes:
Return the device used by the environment.
Returns the environment's internal
_np_randomthat if not set will initialise with a random seed.Returns the base non-wrapped environment.
- check_truncated(obs, info)#
Check if the episode is truncated.
- Parameters:
obs (
Dict[str,Union[Tensor,Dict[str,Tensor]]]) – The observation from the environment.info (
Dict[str,Any]) – The info dictionary.
- Return type:
bool- Returns:
True if the episode is truncated, False otherwise.
- close()#
Close the environment and release resources.
- Return type:
None
- create_demo_action_list(*args, **kwargs)[source]#
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:
Optional[Sequence[EnvAction]]
- property device: Tensor#
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.
- get_affordance(key, default=None)[source]#
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 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:
Dict[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.
Note
If self.num_envs == 1, return the observation in single_observation_space format. If self.num_envs > 1, return the observation in observation_space format.
- Parameters:
**kwargs – Additional keyword arguments to be passed to the
_get_sensor_obs()functions.- Return type:
Dict[str,Union[Tensor,Dict[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 (
Dict[str,Union[Tensor,Dict[str,Tensor]]]) – The observation from the environment.action (
Union[Tensor,Dict[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:
- Returns:
The sensor instance.
- get_wrapper_attr(name)#
Gets the attribute name from the environment.
- Return type:
Any
- is_task_success(**kwargs)[source]#
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_randomthat if not set will initialise with a random seed.- Returns:
Instances of np.random.Generator
- preview_sensor_data(name, data_type='color', env_ids=0, method='plt')[source]#
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 “plt”.
- Return type:
None
- render()#
Compute the render frames as specified by
render_modeduring the initialization of the environment.The environment’s
metadatarender 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_modeis known during__init__, the objects used to render the environment state should be initialised in__init__.By convention, if the
render_modeis: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()andrender()doesn’t need to be called. ReturnsNone.“rgb_array”: Return a single frame representing the current state of the environment. A frame is a
np.ndarraywith shape(x, y, 3)representing RGB values for an x-by-y pixel image.“ansi”: Return a strings (
str) orStringIO.StringIOcontaining 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.RenderCollectionthat is automatically applied duringgymnasium.make(..., render_mode="rgb_array_list"). The frames collected are popped afterrender()is called orreset().
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)[source]#
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[Dict[str,Union[Tensor,Dict[str,Tensor]]],Dict]- Returns:
A tuple containing the observations and infos.
- set_affordance(key, value)[source]#
Set an affordance value by key.
- Parameters:
key (str) – The affordance key.
value (Any) – The affordance value.
- step(action, **kwargs)[source]#
Step the environment with the given action.
- Parameters:
action (
Union[Tensor,Dict[str,Tensor]]) – The action applied to the robot agent.- Return type:
Tuple[Dict[str,Union[Tensor,Dict[str,Tensor]]],Tensor,Tensor,Tensor,Dict[str,Any]]- Returns:
A tuple contraining the observation, reward, terminated, truncated, and info dictionary.
- to_dataset(id, save_path=None)[source]#
Convert the recorded episode data to a dataset format.
- Parameters:
id (str) – Unique identifier for the dataset.
save_path (str, optional) – Path to save the dataset. If None, use config or default.
- Returns:
The path to the saved dataset, or None if failed.
- Return type:
Optional[str]
- property unwrapped: Env[ObsType, ActType]#
Returns the base non-wrapped environment.
- Returns:
The base non-wrapped
gymnasium.Envinstance- Return type:
Env
- class embodichain.lab.gym.envs.EmbodiedEnvCfg[source]#
Configuration class for the Embodied Environment. Inherits from EnvCfg and can be extended with additional parameters if needed.
Classes:
EnvLightCfg(direct: List[embodichain.lab.sim.cfg.LightCfg] = <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.
Attributes:
Data pipeline configuration.
Event settings.
Whether to filter out visual randomization
Whether to ignore terminations when deciding when to auto reset.
The number of sub environments (arena in dexsim context) to be simulated in parallel.
Observation settings.
The seed for the random number generator.
Simulation configuration for the environment.
Number of simulation steps per control (env) step.
- class EnvLightCfg[source]#
EnvLightCfg(direct: List[embodichain.lab.sim.cfg.LightCfg] = <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.
- 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[Dict[str,Any]]# Data pipeline configuration. Defaults to None.
-
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.EventManagerclass for more details.
-
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.
-
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.ObservationManagerclass 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.
-
seed:
Optional[int]# 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.