embodichain.lab.gym.envs.managers

Submodules

randomization

Classes

FunctorCfg	Configuration for a functor.
SceneEntityCfg	Configuration for a scene entity that is used by the manager's functor.
EventCfg	Configuration for a event functor.
ObservationCfg	Configuration for an observation functor.
Functor	Base class for Functor.
ManagerBase	Base class for all managers.
EventManager	Manager for orchestrating operations based on different simulation events.
ObservationManager	Manager for orchestrating operations based on different simulation observations.

Functions

observations.get_rigid_object_pose(env, obs, ...)	Get the world poses of the rigid objects in the environment.
observations.normalize_robot_joint_data(env, ...)	Normalize the robot joint positions to the range of [0, 1] based on the joint limits.
observations.compute_semantic_mask(env, obs, ...)	Compute the semantic mask for the specified scene entity.
observations.compute_exteroception	Compute the exteroception for the observation space.
events.replace_assets_from_group	Replace assets in the environment from a specified group of assets.
record.record_camera_data	Record camera data in the environment.
randomization.rendering.randomize_light(env, ...)	Randomize light properties by adding, scaling, or setting random values.
randomization.rendering.randomize_camera_intrinsics(...)	Randomize camera intrinsic properties by adding, scaling, or setting random values.
randomization.rendering.randomize_visual_material	Randomize the the visual material properties of a RigidObject or an Articulation.
randomization.spatial.get_random_pose(...[, ...])	Generate a random pose based on the initial position and rotation.
randomization.spatial.randomize_rigid_object_pose(...)	Randomize the pose of a rigid object in the environment.
randomization.spatial.randomize_robot_eef_pose(...)	Randomize the initial end-effector pose of a robot in the environment.
randomization.spatial.randomize_robot_qpos(...)	Randomize the initial joint positions of a robot in the environment.

Configuration Classes

class embodichain.lab.gym.envs.managers.FunctorCfg

Configuration for a functor.

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:

func	The function or class to be called for the functor.
params	The parameters to be passed to the function as keyword arguments.

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.

func: Callable | Functor

The function or class to be called for the functor.

The function must take the environment object as the first argument. The remaining arguments are specified in the params attribute.

It also supports callable classes, i.e. classes that implement the __call__() method. In this case, the class should inherit from the Functor class and implement the required methods.

params: dict[str, Union[Any, SceneEntityCfg]]

The parameters to be passed to the function as keyword arguments. Defaults to an empty dict.

Note

If the value is a SceneEntityCfg object, the manager will query the scene entity from the SimulationManager and process the entity’s joints and bodies as specified in the SceneEntityCfg 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.

class embodichain.lab.gym.envs.managers.SceneEntityCfg

Configuration for a scene entity that is used by the manager’s functor.

This class is used to specify the name of the scene entity that is queried from the SimulationManager and passed to the manager’s functor.

Attributes:

body_ids	The indices of the bodies from the asset required by the functor.
body_names	The names of the bodies from the asset required by the functor.
control_parts	The names of the control parts from the asset(only support for robot) required by the functor.
joint_ids	The indices of the joints from the asset required by the functor.
joint_names	The names of the joints from the scene entity.
link_names	The names of the links from the asset required by the functor.
preserve_order	Whether to preserve indices ordering to match with that in the specified joint, body, or object collection names.
uid	The name of the scene entity.

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.
resolve(scene)	Resolves the scene entity and converts the joint and body names to indices.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

body_ids: list[int] | slice

The indices of the bodies from the asset required by the functor. Defaults to slice(None), which means all the bodies in the asset.

If body_names is specified, this is filled in automatically on initialization of the manager.

body_names: str | list[str] | None

The names of the bodies from the asset required by the functor. Defaults to None.

The names can be either body names or a regular expression matching the body names.

These are converted to body indices on initialization of the manager and passed to the functor function as a list of body indices under body_ids.

control_parts: str | list[str] | None

The names of the control parts from the asset(only support for robot) required by the functor. Defaults to None.

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.

joint_ids: list[int] | slice

The indices of the joints from the asset required by the functor. Defaults to slice(None), which means all the joints in the asset (if present).

If joint_names is specified, this is filled in automatically on initialization of the manager.

joint_names: str | list[str] | None

The names of the joints from the scene entity. Defaults to None.

The names can be either joint names or a regular expression matching the joint names.

These are converted to joint indices on initialization of the manager and passed to the functor as a list of joint indices under joint_ids.

link_names: str | list[str] | None

The names of the links from the asset required by the functor. Defaults to None.

The names can be either link names or a regular expression matching the link names.

preserve_order: bool

Whether to preserve indices ordering to match with that in the specified joint, body, or object collection names. Defaults to False.

If False, the ordering of the indices are sorted in ascending order (i.e. the ordering in the entity’s joints, bodies, or object in the object collection). Otherwise, the indices are preserved in the order of the specified joint, body, or object collection names.

For more details, see the isaaclab.utils.string.resolve_matching_names() function.

Note

This attribute is only used when joint_names, body_names are specified.

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.

resolve(scene)

Resolves the scene entity and converts the joint and body names to indices.

This function examines the scene entity from the SimulationManager and resolves the indices and names of the joints and bodies. It is an expensive operation as it resolves regular expressions and should be called only once.

Parameters:

scene (SimulationManager) – The interactive scene instance.

Raises:

• ValueError – If the scene entity is not found.

• ValueError – If both joint_names and joint_ids are specified and are not consistent.

• ValueError – If both body_names and body_ids are specified and are not consistent.

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

The name of the scene entity.

This is the name defined in the scene configuration file. See the SimulationManagerCfg class for more details.

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.managers.EventCfg

Configuration for a event functor.

The event functor is used to trigger events in the environment at specific times or under specific conditions. The mode attribute determines when the functor is applied. - startup: The functor is applied when the environment is started. - interval: The functor is applied at each env step. - reset: The functor is applied when the environment is reset.

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:

func	The function or class to be called for the functor.
interval_step	The number of environment step after which the functor is applied.
is_global	Whether the event should be tracked on a per-environment basis.
mode	The mode in which the event functor is applied.
params	The parameters to be passed to the function as keyword arguments.

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.

func: Callable | Functor

The function or class to be called for the functor.

The function must take the environment object as the first argument. The remaining arguments are specified in the params attribute.

It also supports callable classes, i.e. classes that implement the __call__() method. In this case, the class should inherit from the Functor class and implement the required methods.

interval_step: int

The number of environment step after which the functor is applied. Defaults to 4.

is_global: bool

Whether the event should be tracked on a per-environment basis. Defaults to False.

If True, the same interval step is used for all the environment instances. If False, the interval step is sampled independently for each environment instance and the functor is applied when the current step hits the interval step for that instance.

Note

This is only used if the mode is "interval".

mode: Literal['startup', 'interval', 'reset']

The mode in which the event functor is applied.

Note

The mode name "interval" is a special mode that is handled by the manager Hence, its name is reserved and cannot be used for other modes.

params: dict[str, Union[Any, SceneEntityCfg]]

The parameters to be passed to the function as keyword arguments. Defaults to an empty dict.

Note

If the value is a SceneEntityCfg object, the manager will query the scene entity from the SimulationManager and process the entity’s joints and bodies as specified in the SceneEntityCfg 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.

class embodichain.lab.gym.envs.managers.ObservationCfg

Configuration for an observation functor.

The observation functor is used to compute observations for the environment. The mode attribute determines whether the observation is already present in the observation space or not.

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:

func	The function or class to be called for the functor.
mode	The mode for the observation computation.
name	The name of the observation.
params	The parameters to be passed to the function as keyword arguments.

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.

func: Callable | Functor

The function or class to be called for the functor.

The function must take the environment object as the first argument. The remaining arguments are specified in the params attribute.

It also supports callable classes, i.e. classes that implement the __call__() method. In this case, the class should inherit from the Functor class and implement the required methods.

mode: Literal['modify', 'add']

The mode for the observation computation.

• modify: The observation is already present in the observation space, updated the value in-place.

• add: The observation is not present in the observation space, add a new entry to the observation space.

name: str

The name of the observation.

The name can be a new key to observation space, eg:

• object_position: shape of (num_envs, 3)

• robot/eef_pose: shape of (num_envs, 7) or (num_envs, 4, 4)

• sensor/cam_high/mask: shape of (num_envs, H, W)

or a existing key to modify, eg:

• robot/qpos: shape of (num_envs, num_dofs)

/ is used to separate different levels of hierarchy in the observation dictionary.

params: dict[str, Union[Any, SceneEntityCfg]]

The parameters to be passed to the function as keyword arguments. Defaults to an empty dict.

Note

If the value is a SceneEntityCfg object, the manager will query the scene entity from the SimulationManager and process the entity’s joints and bodies as specified in the SceneEntityCfg 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.

Base Classes

class embodichain.lab.gym.envs.managers.Functor

Bases: ABC

Base class for Functor.

Functor implementations can be functions or classes. If the functor is a class, it should inherit from this base class and implement the required methods.

Each manager is implemented as a class that inherits from the ManagerBase class. Each manager class should also have a corresponding configuration class that defines the configuration functors for the manager. Each functor should the FunctorCfg class or its subclass.

Example pseudo-code for creating a manager:

from embodichain.utils import configclass
from embodichain.lab.gym.managers import ManagerBase
from embodichain.lab.gym.managers FunctorCfg

@configclass
class MyManagerCfg:

    functor1: FunctorCfg = FunctorCfg(...)
    functor2: FunctorCfg = FunctorCfg(...)
    functor3: FunctorCfg = FunctorCfg(...)

# define manager instance
my_manager = ManagerBase(cfg=ManagerCfg(), env=env)

Methods:

__init__(cfg, env)	Initialize the functor.
reset([env_ids])	Resets the functor.
serialize()	General serialization call.

Attributes:

device	Device on which to perform computations.
num_envs	Number of environments.

__init__(cfg, env)

Initialize the functor.

Parameters:

• cfg (FunctorCfg) – The configuration object.

• env (EmbodiedEnv) – The environment instance.

property device: str

Device on which to perform computations.

property num_envs: int

Number of environments.

reset(env_ids=None)

Resets the functor.

Parameters:

env_ids (Optional[Sequence[int]]) – The environment ids. Defaults to None, in which case all environments are considered.

Return type:

None

serialize()

General serialization call. Includes the configuration dict.

Return type:

dict

class embodichain.lab.gym.envs.managers.ManagerBase

Bases: ABC

Base class for all managers.

Methods:

__init__(cfg, env)	Initialize the manager.
find_functors(name_keys)	Find functors in the manager based on the names.
get_active_iterable_functors(env_idx)	Returns the active functors as iterable sequence of tuples.
reset([env_ids])	Resets the manager and returns logging information for the current time-step.

Attributes:

active_functors	Name of active functors.
device	Device on which to perform computations.
num_envs	Number of environments.

__init__(cfg, env)

Initialize the manager.

This function is responsible for parsing the configuration object and creating the functors.

If the simulation is not playing, the scene entities are not resolved immediately. Instead, the resolution is deferred until the simulation starts. This is done to ensure that the scene entities are resolved even if the manager is created after the simulation has already started.

Parameters:

• cfg (object) – The configuration object. If None, the manager is initialized without any functors.

• env (EmbodiedEnv) – The environment instance.

abstract property active_functors: list[str] | dict[str, list[str]]

Name of active functors.

property device: str

Device on which to perform computations.

find_functors(name_keys)

Find functors in the manager based on the names.

This function searches the manager for functors based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active functors in the manager.

Please check the resolve_matching_names() function for more information on the name matching.

Parameters:

name_keys (Union[str, Sequence[str]]) – A regular expression or a list of regular expressions to match the functor names.

Return type:

list[str]

Returns:

A list of functor names that match the input keys.

get_active_iterable_functors(env_idx)

Returns the active functors as iterable sequence of tuples.

The first element of the tuple is the name of the functor and the second element is the raw value(s) of the functor.

Return type:

Sequence[tuple[str, Sequence[float]]]

Returns:

The active functors.

property num_envs: int

Number of environments.

reset(env_ids=None)

Resets the manager and returns logging information for the current time-step.

Parameters:

env_ids (Optional[Sequence[int]]) – The environment ids for which to log data. Defaults None, which logs data for all environments.

Return type:

dict[str, float]

Returns:

Dictionary containing the logging information.

Managers

class embodichain.lab.gym.envs.managers.EventManager

Bases: ManagerBase

Manager for orchestrating operations based on different simulation events.

The event manager applies operations to the environment based on different simulation events. For example, changing the masses of objects or their friction coefficients during initialization/ reset, or applying random pushes to the robot at a fixed interval of steps. The user can specify several modes of events to fine-tune the behavior based on when to apply the event.

The event functors are parsed from a config class containing the manager’s settings and each functor’s parameters. Each event functor should instantiate the EventCfg class.

Event functors can be grouped by their mode. The mode is a user-defined string that specifies when the event functor should be applied. This provides the user complete control over when event functors should be applied.

For a typical training process, you may want to apply events in the following modes:

• “prestartup”: Event is applied once at the beginning of the training before the simulation starts. This is used to randomize USD-level properties of the simulation stage.

• “startup”: Event is applied once at the beginning of the training once simulation is started.

• “reset”: Event is applied at every reset.

• “interval”: Event is applied at pre-specified intervals of time.

However, you can also define your own modes and use them in the training process as you see fit. For this you will need to add the triggering of that mode in the environment implementation as well.

Note

The triggering of operations corresponding to the mode "interval" are the only mode that are directly handled by the manager itself. The other modes are handled by the environment implementation.

Methods:

__init__(cfg, env)	Initialize the event manager.
apply(mode[, env_ids])	Calls each event functor in the specified mode.
find_functors(name_keys)	Find functors in the manager based on the names.
get_active_iterable_functors(env_idx)	Returns the active functors as iterable sequence of tuples.
get_functor(functor_name)	Retrieve a functor from the configuration by its name.
get_functor_cfg(functor_name)	Gets the configuration for the specified functor.
reset([env_ids])	Resets the manager and returns logging information for the current time-step.
set_functor_cfg(functor_name, cfg)	Sets the configuration of the specified functor into the manager.

Attributes:

active_functors	Name of active event functors.
available_modes	Modes of events.
device	Device on which to perform computations.
num_envs	Number of environments.

__init__(cfg, env)

Initialize the event manager.

Parameters:

• cfg (object) – A configuration object or dictionary (dict[str, EventCfg]).

• env (EmbodiedEnv) – An environment object.

property active_functors: dict[str, list[str]]

Name of active event functors.

The keys are the modes of event and the values are the names of the event functors.

apply(mode, env_ids=None)

Calls each event functor in the specified mode.

This function iterates over all the event functors in the specified mode and calls the function corresponding to the functor. The function is called with the environment instance and the environment indices to apply the event to.

For the “interval” mode, the function is called when the time interval has passed. This requires specifying the time step of the environment.

For the “reset” mode, the function is called when the mode is “reset” and the total number of environment steps that have happened since the last trigger of the function is equal to its configured parameter for the number of environment steps between resets.

Parameters:

• mode (str) – The mode of event.

• env_ids (Optional[Sequence[int]]) – The indices of the environments to apply the event to. Defaults to None, in which case the event is applied to all environments when applicable.

Raises:

• ValueError – If the mode is "interval" and the environment indices are provided. This is an undefined behavior as the environment indices are computed based on the time left for each environment.

• ValueError – If the mode is "reset" and the total number of environment steps that have happened is not provided.

property available_modes: list[str]

Modes of events.

property device: str

Device on which to perform computations.

find_functors(name_keys)

Find functors in the manager based on the names.

This function searches the manager for functors based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active functors in the manager.

Please check the resolve_matching_names() function for more information on the name matching.

Parameters:

name_keys (Union[str, Sequence[str]]) – A regular expression or a list of regular expressions to match the functor names.

Return type:

list[str]

Returns:

A list of functor names that match the input keys.

get_active_iterable_functors(env_idx)

Returns the active functors as iterable sequence of tuples.

The first element of the tuple is the name of the functor and the second element is the raw value(s) of the functor.

Return type:

Sequence[tuple[str, Sequence[float]]]

Returns:

The active functors.

get_functor(functor_name)

Retrieve a functor from the configuration by its name.

Parameters:

functor_name (str) – The name of the functor to retrieve.

Returns:

The functor if it exists in the configuration, otherwise None.

get_functor_cfg(functor_name)

Gets the configuration for the specified functor.

The method finds the functor by name by searching through all the modes. It then returns the configuration of the functor with the first matching name.

Parameters:

functor_name (str) – The name of the event functor.

Return type:

EventCfg

Returns:

The configuration of the event functor.

Raises:

ValueError – If the functor name is not found.

property num_envs: int

Number of environments.

reset(env_ids=None)

Resets the manager and returns logging information for the current time-step.

Parameters:

env_ids (Optional[Sequence[int]]) – The environment ids for which to log data. Defaults None, which logs data for all environments.

Return type:

dict[str, float]

Returns:

Dictionary containing the logging information.

set_functor_cfg(functor_name, cfg)

Sets the configuration of the specified functor into the manager.

The method finds the functor by name by searching through all the modes. It then updates the configuration of the functor with the first matching name.

Parameters:

• functor_name (str) – The name of the event functor.

• cfg (EventCfg) – The configuration for the event functor.

Raises:

ValueError – If the functor name is not found.

class embodichain.lab.gym.envs.managers.ObservationManager

Bases: ManagerBase

Manager for orchestrating operations based on different simulation observations.

The default observation space will contain two observation groups:

• robot: Contains the default observations related to the robot.

  • qpos: The joint positions of the robot.

  • qvel: The joint velocities of the robot.

  • qf: The joint forces of the robot.

• sensor: Contains the observations related to the sensors which are enabled in the environment.

The observation manager offers two modes of operation:

• modify: This mode perform data fetching and modification on existing observation data.

• add: This mode perform new observation computation and add new observation data to the observation space.

Methods:

__init__(cfg, env)	Initialize the observation manager.
compute(obs)	Calls each observation functor in the specified mode.
find_functors(name_keys)	Find functors in the manager based on the names.
get_active_iterable_functors(env_idx)	Returns the active functors as iterable sequence of tuples.
get_functor_cfg(functor_name)	Gets the configuration for the specified functor.
reset([env_ids])	Resets the manager and returns logging information for the current time-step.

Attributes:

active_functors	Name of active observation functors.
device	Device on which to perform computations.
num_envs	Number of environments.

__init__(cfg, env)

Initialize the observation manager.

Parameters:

• cfg (object) – A configuration object or dictionary (dict[str, ObservationCfg]).

• env (EmbodiedEnv) – An environment object.

property active_functors: dict[str, list[str]]

Name of active observation functors.

The keys are the modes of observation and the values are the names of the observation functors.

compute(obs)

Calls each observation functor in the specified mode.

This function iterates over all the observation functors in the specified mode and calls the function corresponding to the functor. The function is called with the environment instance and the environment indices to apply the observation to.

Parameters:

obs (Dict[str, Union[Tensor, Dict[str, Tensor]]]) – The observation data to apply the observation to.

Return type:

Dict[str, Union[Tensor, Dict[str, Tensor]]]

Returns:

The modified observation data.

Raises:

ValueError – If the mode is not supported.

property device: str

Device on which to perform computations.

find_functors(name_keys)

Find functors in the manager based on the names.

This function searches the manager for functors based on the names. The names can be specified as regular expressions or a list of regular expressions. The search is performed on the active functors in the manager.

Please check the resolve_matching_names() function for more information on the name matching.

Parameters:

name_keys (Union[str, Sequence[str]]) – A regular expression or a list of regular expressions to match the functor names.

Return type:

list[str]

Returns:

A list of functor names that match the input keys.

get_active_iterable_functors(env_idx)

Returns the active functors as iterable sequence of tuples.

The first element of the tuple is the name of the functor and the second element is the raw value(s) of the functor.

Return type:

Sequence[tuple[str, Sequence[float]]]

Returns:

The active functors.

get_functor_cfg(functor_name)

Gets the configuration for the specified functor.

The method finds the functor by name by searching through all the modes. It then returns the configuration of the functor with the first matching name.

Parameters:

functor_name (str) – The name of the observation functor.

Return type:

ObservationCfg

Returns:

The configuration of the observation functor.

Raises:

ValueError – If the functor name is not found.

property num_envs: int

Number of environments.

reset(env_ids=None)

Resets the manager and returns logging information for the current time-step.

Parameters:

env_ids (Optional[Sequence[int]]) – The environment ids for which to log data. Defaults None, which logs data for all environments.

Return type:

dict[str, float]

Returns:

Dictionary containing the logging information.

Observation Functions

Classes:

compute_exteroception

Compute the exteroception for the observation space.

Functions:

compute_semantic_mask(env, obs, entity_cfg, ...)	Compute the semantic mask for the specified scene entity.
get_rigid_object_pose(env, obs, entity_cfg)	Get the world poses of the rigid objects in the environment.
normalize_robot_joint_data(env, data, joint_ids)	Normalize the robot joint positions to the range of [0, 1] based on the joint limits.

class embodichain.lab.gym.envs.managers.observations.compute_exteroception

Compute the exteroception for the observation space.

The exteroception is currently defined as a set of keypoints around a reference pose, which are prjected from 3D space to 2D image plane. The reference pose can derive from the following sources:

• Pose from robot control part (e.g., end-effector, usually tcp pose)

• Object affordance pose (e.g., handle pose of a mug or a pick pose of a cube)

Therefore, the exteroception are defined in the camera-like sensor, for example. descriptor = {

“cam_high”: [

{

“type”: “affordance”, “obj_uid”: “obj1”, “key”: “grasp_pose”, “is_arena_coord”: True

}, {

“type”: “affordance”, “obj_uid”: “obj1”, “key”: “place_pose”,

}, {

“type”: “robot”, “control_part”: “left_arm”,

}, {

“type”: “robot”, “control_part”: “right_arm”,

}

}

Explanation of the parameters:

• The key of the dictionary is the sensor uid.

• The value is another dictionary, where the key is the source type, and the value is a dictionary of parameters.

• For affordance source type, the parameters are:

  • obj_uid: The uid of the object to get the affordance pose from.

  • key: The key of the affordance pose in the affordance data.

  • is_arena_coord: Whether the affordance pose is in the arena coordinate system. Default is False.

• For robot source type, the parameters are:

  • control_part: The control part of the robot to get the pose from.

Methods:

__init__(cfg, env)	Initialize the functor.
expand_pose(pose, x_interval, y_interval, ...)	Expand pose with keypoints along x and y axes.
shift_pose(pose, axis, shift)	Shift the pose along the specified axis by the given amount.

__init__(cfg, env)

Initialize the functor.

Parameters:

• cfg (FunctorCfg) – The configuration object.

• env (EmbodiedEnv) – The environment instance.

static expand_pose(pose, x_interval, y_interval, kpnts_number, ref_pose=None)

Expand pose with keypoints along x and y axes.

Parameters:

• pose (Tensor) – The original pose tensor of shape (B, 4, 4).

• x_interval (float) – The interval for expanding along x-axis.

• y_interval (float) – The interval for expanding along y-axis.

• kpnts_number (int) – Number of keypoints to generate for each axis.

• ref_pose (Optional[Tensor]) – Reference pose tensor of shape (B, 4, 4). If None, uses identity matrix.

Return type:

Tensor

Returns:

Expanded poses tensor of shape (B, 1 + 2*kpnts_number, 4, 4).

static shift_pose(pose, axis, shift)

Shift the pose along the specified axis by the given amount.

Parameters:

• pose (Tensor) – The original pose tensor of shape (B, 4, 4).

• axis (int) – The axis along which to shift (0 for x, 1 for y, 2 for z).

• shift (float) – The amount to shift along the specified axis.

Return type:

Tensor

embodichain.lab.gym.envs.managers.observations.compute_semantic_mask(env, obs, entity_cfg, foreground_uids, is_right=False)

Compute the semantic mask for the specified scene entity.

Note

The semantic mask is defined as (B, H, W, 3) where the three channels represents: - robot channel: the instance id of the robot is set to 1 (0 if not robot) - background channel: the instance id of the background is set to 1 (0 if not background) - foreground channel: the instance id of the foreground objects is set to 1 (0 if not foreground)

Parameters:

• env (EmbodiedEnv) – The environment instance.

• obs (Dict[str, Union[Tensor, Dict[str, Tensor]]]) – The observation dictionary.

• entity_cfg (SceneEntityCfg) – The configuration of the scene entity.

• foreground_uids (Sequence[str]) – The list of uids for the foreground objects.

• is_right (bool) – Whether to use the right camera for stereo cameras. Default is False. Only applicable if the sensor is a StereoCamera.

Return type:

Tensor

Returns:

A tensor of shape (num_envs, height, width) representing the semantic mask.

embodichain.lab.gym.envs.managers.observations.get_rigid_object_pose(env, obs, entity_cfg)

Get the world poses of the rigid objects in the environment.

Parameters:

• env (EmbodiedEnv) – The environment instance.

• obs (Dict[str, Union[Tensor, Dict[str, Tensor]]]) – The observation dictionary.

• entity_cfg (SceneEntityCfg) – The configuration of the scene entity.

Return type:

Tensor

Returns:

A tensor of shape (num_envs, 4, 4) representing the world poses of the rigid objects.

embodichain.lab.gym.envs.managers.observations.normalize_robot_joint_data(env, data, joint_ids, limit='qpos_limits')

Normalize the robot joint positions to the range of [0, 1] based on the joint limits.

Parameters:

• env (EmbodiedEnv) – The environment instance.

• obs – The observation dictionary.

• joint_ids (Sequence[int]) – The indices of the joints to be normalized.

• limit (Literal['qpos_limits', 'qvel_limits']) – The type of joint limits to be used for normalization. Options are: - qpos_limits: Use the joint position limits for normalization. - qvel_limits: Use the joint velocity limits for normalization.

Return type:

Tensor

Event Functions

Functions:

drop_rigid_object_group_sequentially(env, ...)	Drop rigid object group from a specified height sequentially in the environment.
register_entity_attrs(env, env_ids, entity_cfg)	Register the atrributes of an entity to the env.registration dict.

Classes:

prepare_extra_attr
replace_assets_from_group	Replace assets in the environment from a specified group of assets.

embodichain.lab.gym.envs.managers.events.drop_rigid_object_group_sequentially(env, env_ids, entity_cfg, drop_position=[0.0, 0.0, 1.0], position_range=([-0.1, -0.1, 0.0], [0.1, 0.1, 0.0]), physics_step=2)

Drop rigid object group from a specified height sequentially in the environment.

Parameters:

• env (EmbodiedEnv) – The environment instance.

• env_ids (Union[torch.Tensor, None]) – The environment IDs to apply the randomization.

• entity_cfg (SceneEntityCfg) – The configuration of the scene entity to randomize.

• drop_position (List[float]) – The base position from which to drop the objects. Default is [0.0, 0.0, 1.0].

• position_range (Tuple[List[float], List[float]]) – The range for randomizing the drop position around the base position.

• physics_step (int) – The number of physics steps to simulate after dropping the objects. Default is 2.

Return type:

None

class embodichain.lab.gym.envs.managers.events.prepare_extra_attr

Methods:

__init__(cfg, env)

Initializes the event manager with the given configuration and environment.

__init__(cfg, env)

Initializes the event manager with the given configuration and environment.

Parameters:

• cfg (FunctorCfg) – The configuration object for the functor.

• env (EmbodiedEnv) – The embodied environment instance.

extra_attrs

A dictionary to hold additional attributes.

Type:

dict

embodichain.lab.gym.envs.managers.events.register_entity_attrs(env, env_ids, entity_cfg, registration='affordance_datas', attrs=[], prefix=True)

Register the atrributes of an entity to the env.registration dict.

TODO: Currently this method only support 1 env or multi-envs that reset() together,

as it’s behavior is to update a overall dict every time it’s called.

In the future, asynchronously reset mode shall be supported.

Parameters:

• env (EmbodiedEnv) – The environment the entity is in.

• env_ids (Union[torch.Tensor, None]) – The ids of the envs that the entity should be registered.

• entity_cfg (SceneEntityCfg) – The config of the entity.

• attrs (List[str]) – The list of entity attributes that asked to be registered.

• registration (str, optional) – The env’s registration string where the attributes should be injected to.

class embodichain.lab.gym.envs.managers.events.replace_assets_from_group

Replace assets in the environment from a specified group of assets.

The group of assets can be defined in the following ways:

• A directory containing multiple asset files.

• A json file listing multiple assets with their properties. (not supported yet)

• … (other methods can be added in the future)

Methods:

__init__(cfg, env)

Initialize the term.

__init__(cfg, env)

Initialize the term.

Parameters:

• cfg (FunctorCfg) – The configuration of the functor.

• env (EmbodiedEnv) – The environment instance.

Raises:

ValueError – If the asset is not a RigidObject or an Articulation.

Recording Functions

Classes:

record_camera_data	Record camera data in the environment.
record_camera_data_async	Record camera data for multiple environments, merge and save as a single video at episode end.

class embodichain.lab.gym.envs.managers.record.record_camera_data

Record camera data in the environment. The camera is usually setup with third-person view, and is used to record the scene during the episode. It is helpful for debugging and visualization.

Note

Currently, the functor is implemented in interval’ mode such that, it can only save the recorded frames when in :meth:`env.step() function call. For example: `python env.step() # perform multiple steps in the same episode env.reset() env.step()  # the video of the first episode will be saved here. ` The final episode frames will not be saved in the current implementation. We may improve it in the future.

Methods:

__init__(cfg, env)

Initialize the functor.

__init__(cfg, env)

Initialize the functor.

Parameters:

• cfg (FunctorCfg) – The configuration of the functor.

• env (EmbodiedEnv) – The environment instance.

Raises:

ValueError – If the asset is not a RigidObject or an Articulation.

class embodichain.lab.gym.envs.managers.record.record_camera_data_async

Record camera data for multiple environments, merge and save as a single video at episode end.

Methods:

__init__(cfg, env)

Initialize the functor.

__init__(cfg, env)

Initialize the functor.

Parameters:

• cfg (FunctorCfg) – The configuration of the functor.

• env (EmbodiedEnv) – The environment instance.

Raises:

ValueError – If the asset is not a RigidObject or an Articulation.

Randomization

Submodules

rendering
spatial

Rendering

Functions:

randomize_camera_intrinsics(env, env_ids, ...)	Randomize camera intrinsic properties by adding, scaling, or setting random values.
randomize_light(env, env_ids, entity_cfg[, ...])	Randomize light properties by adding, scaling, or setting random values.

Classes:

randomize_visual_material

Randomize the the visual material properties of a RigidObject or an Articulation.

embodichain.lab.gym.envs.managers.randomization.rendering.randomize_camera_intrinsics(env, env_ids, entity_cfg, focal_x_range=None, focal_y_range=None, cx_range=None, cy_range=None)

Randomize camera intrinsic properties by adding, scaling, or setting random values.

This function allows randomizing camera intrinsic parameters in the scene. The function samples random values from the given distribution parameters and adds, scales, or sets the values into the physics simulation based on the operation.

The distribution parameters are tuples of two elements each, representing the lower and upper bounds of the distribution for the focal length (fx, fy) and principal point (cx, cy) components of the camera intrinsics. The function samples random values for each component independently.

Attention

This function applies the same intrinsic properties for all the environments.

focal_x_range and focal_y_range are values added to the camera’s current fx and fy values. focal_xy_range is a combined range for both fx and fy, where the range is specified as [[fx_min, fy_min], [fx_max, fy_max]]. cx_range and cy_range are values added to the camera’s current cx and cy values.

Tip

This function uses CPU tensors to assign camera intrinsic properties.

Parameters:

• env (EmbodiedEnv) – The environment instance.

• env_ids (Union[torch.Tensor, None]) – The environment IDs to apply the randomization.

• entity_cfg (SceneEntityCfg) – The configuration of the scene entity to randomize.

• focal_x_range (Optional[tuple[float, float]]) – The range for the focal length x randomization.

• focal_y_range (Optional[tuple[float, float]]) – The range for the focal length y randomization.

• cx_range (Optional[tuple[float, float]]) – The range for the principal point x randomization.

• cy_range (Optional[tuple[float, float]]) – The range for the principal point y randomization.

Return type:

None

embodichain.lab.gym.envs.managers.randomization.rendering.randomize_light(env, env_ids, entity_cfg, position_range=None, color_range=None, intensity_range=None)

Randomize light properties by adding, scaling, or setting random values.

This function allows randomizing light properties in the scene. The function samples random values from the given distribution parameters and adds, scales, or sets the values into the physics simulation based on the operation.

The distribution parameters are lists of two elements each, representing the lower and upper bounds of the distribution for the x, y, and z components of the light properties. The function samples random values for each component independently.

Attention

This function applied the same light properties for all the environments.

position_range is the x, y, z value added into light’s cfg.init_pos. color_range is the absolute r, g, b value set to the light object. intensity_range is the value added into light’s cfg.intensity.

Tip

This function uses CPU tensors to assign light properties.

Parameters:

• env (EmbodiedEnv) – The environment instance.

• env_ids (Union[torch.Tensor, None]) – The environment IDs to apply the randomization.

• entity_cfg (SceneEntityCfg) – The configuration of the scene entity to randomize.

• position_range (Optional[tuple[list[float], list[float]]]) – The range for the position randomization.

• color_range (Optional[tuple[list[float], list[float]]]) – The range for the color randomization.

• intensity_range (Optional[tuple[float, float]]) – The range for the intensity randomization.

Return type:

None

class embodichain.lab.gym.envs.managers.randomization.rendering.randomize_visual_material

Randomize the the visual material properties of a RigidObject or an Articulation.

Note

1. Currently supported randomized properties include:

   • base_color: RGB color of the material. Value should be in [0, 1], shape of (3,)

   • base_color_texture: Texture image for the base color of the material.

     The textures will be preloaded from the given texture_path during initialization.

   • metallic: Metallic property of the material. Value should be in [0, 1].

   • roughness: Roughness property of the material. Value should be in [0, 1].

   • ior: Index of Refraction of the material (only supported in ray tracing mode).

2. The default ground plane can also be randomized by setting entity_cfg.uid to “default_plane”.

Methods:

__init__(cfg, env)	Initialize the term.
gen_random_base_color_texture(width, height)	Generate a random base color texture.

__init__(cfg, env)

Initialize the term.

Parameters:

• cfg (FunctorCfg) – The configuration of the functor.

• env (EmbodiedEnv) – The environment instance.

Raises:

ValueError – If the asset is not a RigidObject or an Articulation.

static gen_random_base_color_texture(width, height)

Generate a random base color texture.

Parameters:

• width (int) – The width of the texture.

• height (int) – The height of the texture.

Return type:

Tensor

Returns:

A torch tensor representing the random base color texture with shape (height, width, 4).

Spatial

Functions:

get_random_pose(init_pos, init_rot[, ...])	Generate a random pose based on the initial position and rotation.
randomize_rigid_object_pose(env, env_ids, ...)	Randomize the pose of a rigid object in the environment.
randomize_robot_eef_pose(env, env_ids, ...)	Randomize the initial end-effector pose of a robot in the environment.
randomize_robot_qpos(env, env_ids, entity_cfg)	Randomize the initial joint positions of a robot in the environment.

embodichain.lab.gym.envs.managers.randomization.spatial.get_random_pose(init_pos, init_rot, position_range=None, rotation_range=None, relative_position=True, relative_rotation=False)

Generate a random pose based on the initial position and rotation.

Parameters:

• init_pos (torch.Tensor) – The initial position tensor of shape (num_instance, 3).

• init_rot (torch.Tensor) – The initial rotation tensor of shape (num_instance, 3, 3).

• position_range (Optional[tuple[list[float], list[float]]]) – The range for the position randomization.

• rotation_range (Optional[tuple[list[float], list[float]]]) – The range for the rotation randomization. The rotation is represented as Euler angles (roll, pitch, yaw) in degree.

• relative_position (bool) – Whether to randomize the position relative to the initial position. Default is True.

• relative_rotation (bool) – Whether to randomize the rotation relative to the initial rotation. Default is False.

Returns:

The generated random pose tensor of shape (num_instance, 4, 4).

Return type:

torch.Tensor

embodichain.lab.gym.envs.managers.randomization.spatial.randomize_rigid_object_pose(env, env_ids, entity_cfg, position_range=None, rotation_range=None, relative_position=True, relative_rotation=False)

Randomize the pose of a rigid object in the environment.

Parameters:

• env (EmbodiedEnv) – The environment instance.

• env_ids (Union[torch.Tensor, None]) – The environment IDs to apply the randomization.

• entity_cfg (SceneEntityCfg) – The configuration of the scene entity to randomize.

• position_range (Optional[tuple[list[float], list[float]]]) – The range for the position randomization.

• rotation_range (Optional[tuple[list[float], list[float]]]) – The range for the rotation randomization. The rotation is represented as Euler angles (roll, pitch, yaw) in degree.

• relative_position (bool) – Whether to randomize the position relative to the object’s initial position. Default is True.

• relative_rotation (bool) – Whether to randomize the rotation relative to the object’s initial rotation. Default is False.

Return type:

None

embodichain.lab.gym.envs.managers.randomization.spatial.randomize_robot_eef_pose(env, env_ids, entity_cfg, position_range=None, rotation_range=None)

Randomize the initial end-effector pose of a robot in the environment.

Note

• The position and rotation are performed randomization in a relative manner.

• The current state of eef pose is computed based on the current joint positions of the robot.

Parameters:

• env (EmbodiedEnv) – The environment instance.

• env_ids (Union[torch.Tensor, None]) – The environment IDs to apply the randomization.

• robot_name (str) – The name of the robot.

• entity_cfg (SceneEntityCfg) – The configuration of the scene entity to randomize.

• position_range (Optional[tuple[list[float], list[float]]]) – The range for the position randomization.

• rotation_range (Optional[tuple[list[float], list[float]]]) – The range for the rotation randomization. The rotation is represented as Euler angles (roll, pitch, yaw) in degree.

Return type:

None

embodichain.lab.gym.envs.managers.randomization.spatial.randomize_robot_qpos(env, env_ids, entity_cfg, qpos_range=None, relative_qpos=True, joint_ids=None)

Randomize the initial joint positions of a robot in the environment.

Parameters:

• env (EmbodiedEnv) – The environment instance.

• env_ids (Union[torch.Tensor, None]) – The environment IDs to apply the randomization.

• entity_cfg (SceneEntityCfg) – The configuration of the scene entity to randomize.

• qpos_range (Optional[tuple[list[float], list[float]]]) – The range for the joint position randomization.

• relative_qpos (bool) – Whether to randomize the joint positions relative to the current joint positions. Default is True.

• joint_ids (Optional[List[int]]) – The list of joint IDs to randomize. If None, all joints will be randomized.

Return type:

None