embodichain.lab.sim.atomic_actions

embodichain.lab.sim.atomic_actions#

Atomic action abstraction layer for embodied AI motion generation.

This module provides a unified interface for atomic actions like reach, grasp, move, etc., with support for semantic object understanding and extensible custom action registration.

Classes

`Affordance`	Base class for affordance data.
`InteractionPoints`	Interaction points affordance containing a batch of 3D positions.
`ObjectSemantics`	Semantic information about interaction target.
`ActionCfg`	Configuration for atomic actions.
`AtomicAction`	Abstract base class for atomic actions.
`MoveActionCfg`	MoveActionCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'Optional[float]' = <factory>, acceleration_limit: 'Optional[float]' = <factory>, sample_interval: 'int' = <factory>)
`MoveAction`
`PickUpActionCfg`	PickUpActionCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'Optional[float]' = <factory>, acceleration_limit: 'Optional[float]' = <factory>, sample_interval: 'int' = <factory>, hand_open_qpos: 'torch.Tensor \| None' = <factory>, hand_close_qpos: 'torch.Tensor \| None' = <factory>, hand_control_part: 'str' = <factory>, lift_height: 'float' = <factory>, hand_interp_steps: 'int' = <factory>, pre_grasp_distance: 'float' = <factory>, approach_direction: 'torch.Tensor' = <factory>)
`PickUpAction`
`PlaceActionCfg`	PlaceActionCfg(name: 'str' = <factory>, control_part: 'str' = <factory>, interpolation_type: 'str' = <factory>, velocity_limit: 'Optional[float]' = <factory>, acceleration_limit: 'Optional[float]' = <factory>, sample_interval: 'int' = <factory>, hand_open_qpos: 'torch.Tensor \| None' = <factory>, hand_close_qpos: 'torch.Tensor \| None' = <factory>, hand_control_part: 'str' = <factory>, lift_height: 'float' = <factory>, hand_interp_steps: 'int' = <factory>)
`PlaceAction`
`AtomicActionEngine`	Central engine for managing and executing atomic actions.

Core#

class embodichain.lab.sim.atomic_actions.Affordance[source]#

Bases: object

Base class for affordance data.

Affordance represents interaction possibilities for an object. This is the base class for specific affordance types.

Methods:

`__init__`([object_label, geometry, custom_config])
`get_batch_size`()	Return the batch size of this affordance data.
`get_custom_config`(key[, default])	Get a custom affordance configuration value.
`set_custom_config`(key, value)	Set a custom affordance configuration value.

Attributes:

`custom_config`	User-defined configuration payload for affordance creation and usage.
`geometry`	Geometry dictionary shared with ObjectSemantics.
`mesh_triangles`	Get mesh triangles from geometry.
`mesh_vertices`	Get mesh vertices from geometry.
`object_label`	Label of the object this affordance belongs to.

__init__(object_label='', geometry=<factory>, custom_config=<factory>)#

custom_config: Dict[str, Any]#: User-defined configuration payload for affordance creation and usage.

geometry: Dict[str, Any]#

Geometry dictionary shared with ObjectSemantics.

The mesh payload is expected to be stored in: - mesh_vertices: torch.Tensor with shape [N, 3] - mesh_triangles: torch.Tensor with shape [M, 3]

get_batch_size()[source]#

Return the batch size of this affordance data.

Return type:: int

get_custom_config(key, default=None)[source]#

Get a custom affordance configuration value.

Return type:: Any

property mesh_triangles: Tensor | None#

Get mesh triangles from geometry.

Returns:: Mesh triangle index tensor [M, 3], or None if unavailable.
Raises:: TypeError – If mesh_triangles exists but is not a torch tensor.

property mesh_vertices: Tensor | None#

Get mesh vertices from geometry.

Returns:: Mesh vertices tensor [N, 3], or None if unavailable.
Raises:: TypeError – If mesh_vertices exists but is not a torch tensor.

object_label: str = ''#: Label of the object this affordance belongs to.

set_custom_config(key, value)[source]#

Set a custom affordance configuration value.

Return type:: None

class embodichain.lab.sim.atomic_actions.InteractionPoints[source]#

Bases: Affordance

Interaction points affordance containing a batch of 3D positions.

Interaction points define specific locations on an object surface that can be used for contact-based interactions (pushing, poking, touching) rather than full grasping.

Methods:

`__init__`([object_label, geometry, ...])
`get_approach_direction`(point_idx)	Get recommended approach direction for a given point.
`get_batch_size`()	Return the number of interaction points in this affordance.
`get_points_by_type`(point_type)	Get points by their interaction type.

Attributes:

`normals`	Optional surface normals at each interaction point with shape [B, 3].
`point_types`	Optional labels for each point's interaction type.
`points`	Batch of 3D interaction points with shape [B, 3].

__init__(object_label='', geometry=<factory>, custom_config=<factory>, points=<factory>, normals=None, point_types=<factory>)#

custom_config: Dict[str, Any]#: User-defined configuration payload for affordance creation and usage.

geometry: Dict[str, Any]#

Geometry dictionary shared with ObjectSemantics.

The mesh payload is expected to be stored in: - mesh_vertices: torch.Tensor with shape [N, 3] - mesh_triangles: torch.Tensor with shape [M, 3]

get_approach_direction(point_idx)[source]#

Get recommended approach direction for a given point.

Parameters:: point_idx (int) – Index of the point
Return type:: Tensor
Returns:: 3D approach direction vector (normalized)

get_batch_size()[source]#

Return the number of interaction points in this affordance.

Return type:: int

get_points_by_type(point_type)[source]#

Get points by their interaction type.

Parameters:: point_type (str) – Type of interaction (e.g., “push”, “poke”)
Return type:: Tensor | None
Returns:: Tensor of points if found, None otherwise

normals: Tensor | None = None#

Optional surface normals at each interaction point with shape [B, 3].

Normals indicate the surface orientation at each point, useful for determining approach directions.

point_types: List[str]#

Optional labels for each point’s interaction type.

Examples: “push”, “poke”, “touch”, “pinch”

points: Tensor#

Batch of 3D interaction points with shape [B, 3].

Each point is a 3D coordinate in the object’s local coordinate frame.

class embodichain.lab.sim.atomic_actions.ObjectSemantics[source]#

Bases: object

Semantic information about interaction target.

This class encapsulates all semantic and geometric information about an object needed for intelligent interaction planning.

Methods:

__init__(affordance, geometry[, properties, ...])

Attributes:

`affordance`	Affordance data (GraspPose, InteractionPoints, etc.).
`entity`	Optional reference to the underlying simulation entity representing this object.
`geometry`	Geometric information including bounding box, mesh data.
`label`	Object category label (e.g., 'apple', 'bottle').
`properties`	mass, friction, etc.

__init__(affordance, geometry, properties=<factory>, label='none', entity=None)#

affordance: Affordance#: Affordance data (GraspPose, InteractionPoints, etc.).

entity: BatchEntity | None = None#: Optional reference to the underlying simulation entity representing this object.

geometry: Dict[str, Any]#: Geometric information including bounding box, mesh data.

label: str = 'none'#: Object category label (e.g., ‘apple’, ‘bottle’).

properties: Dict[str, Any]#

mass, friction, etc.

Type:: Physical properties

class embodichain.lab.sim.atomic_actions.ActionCfg[source]#

Configuration for atomic actions.

Attributes:

`acceleration_limit`	Optional acceleration limit for the motion.
`control_part`	Control part name for the action.
`interpolation_type`	'linear', 'cubic'.
`name`	Name of the action, used for identification and logging.
`velocity_limit`	Optional velocity limit for the motion.

acceleration_limit: Optional[float]#: Optional acceleration limit for the motion.

control_part: str#: Control part name for the action.

interpolation_type: str#

‘linear’, ‘cubic’.

Type:: Interpolation type

name: str#: Name of the action, used for identification and logging.

velocity_limit: Optional[float]#: Optional velocity limit for the motion.

class embodichain.lab.sim.atomic_actions.AtomicAction[source]#

Bases: ABC

Abstract base class for atomic actions.

All atomic actions use PlanResult from embodichain.lab.sim.planners as the return type for execute() method, ensuring consistency with the existing motion planning infrastructure.

Methods:

`__init__`(motion_generator[, cfg])	Initialize the atomic action.
`execute`(target[, start_qpos])	execute pick up action
`plan_trajectory`(target_states[, options])	Plan trajectory using motion generator.
`validate`(target[, start_qpos])	Validate if the action is feasible without executing.

__init__(motion_generator, cfg=ActionCfg(name='default', control_part='arm', interpolation_type='linear', velocity_limit=None, acceleration_limit=None))[source]#: Initialize the atomic action. :type motion_generator: MotionGenerator :param motion_generator: The motion generator instance to use for planning. :type cfg: ActionCfg :param cfg: Configuration for the action.

abstract execute(target, start_qpos=None, **kwargs)[source]#

execute pick up action

Parameters:

target (ObjectSemantics) – object semantics containing grasp affordance and entity information
start_qpos (Optional[torch.Tensor], optional) – Planning start qpos. Defaults to None.

Returns:

is_success, trajectory of shape (n_envs, n_waypoints, dof), joint_ids corresponding to trajectory

Return type:

tuple[bool, torch.Tensor, list[float]]

plan_trajectory(target_states, options=None)[source]#

Plan trajectory using motion generator.

Return type:: PlanResult

abstract validate(target, start_qpos=None, **kwargs)[source]#

Validate if the action is feasible without executing.

This method performs a quick feasibility check (e.g., IK solvability) without generating a full trajectory.

Return type:: bool
Returns:: True if action appears feasible, False otherwise

Actions#

class embodichain.lab.sim.atomic_actions.MoveActionCfg[source]#

Bases: ActionCfg

MoveActionCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘Optional[float]’ = <factory>, acceleration_limit: ‘Optional[float]’ = <factory>, sample_interval: ‘int’ = <factory>)

Attributes:

`acceleration_limit`	Optional acceleration limit for the motion.
`control_part`	Control part name for the action.
`interpolation_type`	'linear', 'cubic'.
`name`	Name of the action, used for identification and logging.
`sample_interval`	Number of waypoints to sample for the motion trajectory.
`velocity_limit`	Optional velocity limit for the motion.

acceleration_limit: Optional[float]#: Optional acceleration limit for the motion.

control_part: str#: Control part name for the action.

interpolation_type: str#

‘linear’, ‘cubic’.

Type:: Interpolation type

name: str#: Name of the action, used for identification and logging.

sample_interval: int#: Number of waypoints to sample for the motion trajectory. Should be large enough to ensure smooth motion, but not too large to cause unnecessary computation overhead.

velocity_limit: Optional[float]#: Optional velocity limit for the motion.

class embodichain.lab.sim.atomic_actions.MoveAction[source]#

Bases: AtomicAction

Methods:

`__init__`(motion_generator[, cfg])	Initialize the atomic action.
`execute`(target[, start_qpos])	execute pick up action
`validate`(target[, start_qpos])	Validate if the action is feasible without executing.

__init__(motion_generator, cfg=None)[source]#: Initialize the atomic action. :type motion_generator: MotionGenerator :param motion_generator: The motion generator instance to use for planning. :type cfg: Optional[MoveActionCfg] :param cfg: Configuration for the action.

execute(target, start_qpos=None, **kwargs)[source]#

execute pick up action

Parameters:

target (ObjectSemantics) – object semantics containing grasp affordance and entity information
start_qpos (Optional[torch.Tensor], optional) – Planning start qpos. Defaults to None.

Returns:

is_success, trajectory of shape (n_envs, n_waypoints, dof), joint_ids corresponding to trajectory

Return type:

tuple[bool, torch.Tensor, list[float]]

validate(target, start_qpos=None, **kwargs)[source]#

Validate if the action is feasible without executing.

This method performs a quick feasibility check (e.g., IK solvability) without generating a full trajectory.

Returns:: True if action appears feasible, False otherwise

class embodichain.lab.sim.atomic_actions.PickUpActionCfg[source]#

Bases: GraspActionCfg

PickUpActionCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘Optional[float]’ = <factory>, acceleration_limit: ‘Optional[float]’ = <factory>, sample_interval: ‘int’ = <factory>, hand_open_qpos: ‘torch.Tensor | None’ = <factory>, hand_close_qpos: ‘torch.Tensor | None’ = <factory>, hand_control_part: ‘str’ = <factory>, lift_height: ‘float’ = <factory>, hand_interp_steps: ‘int’ = <factory>, pre_grasp_distance: ‘float’ = <factory>, approach_direction: ‘torch.Tensor’ = <factory>)

Attributes:

`acceleration_limit`	Optional acceleration limit for the motion.
`approach_direction`	Direction from which the gripper approaches the object for grasping, expressed in the object local frame.
`control_part`	Control part name for the action.
`hand_close_qpos`	[hand_dof,] of float.
`hand_control_part`	Name of the robot part that controls the hand joints.
`hand_interp_steps`	Number of waypoints for the gripper open/close interpolation phase.
`hand_open_qpos`	[hand_dof,] of float.
`interpolation_type`	'linear', 'cubic'.
`lift_height`	Height (m) to lift the end-effector after the gripper phase.
`name`	Name of the action, used for identification and logging.
`pre_grasp_distance`	Distance to offset back from the grasp pose along the approach direction to get the pre-grasp pose.
`sample_interval`	Number of waypoints for the full trajectory (approach + hand + lift/back).
`velocity_limit`	Optional velocity limit for the motion.

acceleration_limit: Optional[float]#: Optional acceleration limit for the motion.

approach_direction: Tensor#: Direction from which the gripper approaches the object for grasping, expressed in the object local frame. Default [0, 0, -1] means approaching from above.

control_part: str#: Control part name for the action.

hand_close_qpos: Tensor | None#: [hand_dof,] of float. Joint positions for closed hand state.

hand_control_part: str#: Name of the robot part that controls the hand joints.

hand_interp_steps: int#: Number of waypoints for the gripper open/close interpolation phase.

hand_open_qpos: Tensor | None#: [hand_dof,] of float. Joint positions for open hand state.

interpolation_type: str#

‘linear’, ‘cubic’.

Type:: Interpolation type

lift_height: float#: Height (m) to lift the end-effector after the gripper phase.

name: str#: Name of the action, used for identification and logging.

pre_grasp_distance: float#: Distance to offset back from the grasp pose along the approach direction to get the pre-grasp pose. Should be large enough to avoid collision during approach.

sample_interval: int#: Number of waypoints for the full trajectory (approach + hand + lift/back).

velocity_limit: Optional[float]#: Optional velocity limit for the motion.

class embodichain.lab.sim.atomic_actions.PickUpAction[source]#

Bases: MoveAction

Methods:

`__init__`(motion_generator[, cfg])	Initialize the atomic action.
`execute`(target[, start_qpos])	execute pick up action
`validate`(target[, start_qpos])	Validate if the action is feasible without executing.

__init__(motion_generator, cfg=None)[source]#: Initialize the atomic action. :type motion_generator: MotionGenerator :param motion_generator: The motion generator instance to use for planning. :type cfg: Optional[PickUpActionCfg] :param cfg: Configuration for the action.

execute(target, start_qpos=None, **kwargs)[source]#

execute pick up action

Parameters:

target (Union[ObjectSemantics, torch.Tensor]) – target object semantics or target pose for grasping
start_qpos (Optional[torch.Tensor], optional) – Planning start qpos. Defaults to None.

Returns:

is_success, trajectory of shape (n_envs, n_waypoints, dof), joint_ids corresponding to trajectory

Return type:

tuple[bool, torch.Tensor, list[float]]

validate(target, start_qpos=None, **kwargs)[source]#

Validate if the action is feasible without executing.

This method performs a quick feasibility check (e.g., IK solvability) without generating a full trajectory.

Returns:: True if action appears feasible, False otherwise

class embodichain.lab.sim.atomic_actions.PlaceActionCfg[source]#

Bases: GraspActionCfg

PlaceActionCfg(name: ‘str’ = <factory>, control_part: ‘str’ = <factory>, interpolation_type: ‘str’ = <factory>, velocity_limit: ‘Optional[float]’ = <factory>, acceleration_limit: ‘Optional[float]’ = <factory>, sample_interval: ‘int’ = <factory>, hand_open_qpos: ‘torch.Tensor | None’ = <factory>, hand_close_qpos: ‘torch.Tensor | None’ = <factory>, hand_control_part: ‘str’ = <factory>, lift_height: ‘float’ = <factory>, hand_interp_steps: ‘int’ = <factory>)

Attributes:

`acceleration_limit`	Optional acceleration limit for the motion.
`control_part`	Control part name for the action.
`hand_close_qpos`	[hand_dof,] of float.
`hand_control_part`	Name of the robot part that controls the hand joints.
`hand_interp_steps`	Number of waypoints for the gripper open/close interpolation phase.
`hand_open_qpos`	[hand_dof,] of float.
`interpolation_type`	'linear', 'cubic'.
`lift_height`	Height (m) to lift the end-effector after the gripper phase.
`name`	Name of the action, used for identification and logging.
`sample_interval`	Number of waypoints for the full trajectory (approach + hand + lift/back).
`velocity_limit`	Optional velocity limit for the motion.

acceleration_limit: Optional[float]#: Optional acceleration limit for the motion.

control_part: str#: Control part name for the action.

hand_close_qpos: Tensor | None#: [hand_dof,] of float. Joint positions for closed hand state.

hand_control_part: str#: Name of the robot part that controls the hand joints.

hand_interp_steps: int#: Number of waypoints for the gripper open/close interpolation phase.

hand_open_qpos: Tensor | None#: [hand_dof,] of float. Joint positions for open hand state.

interpolation_type: str#

‘linear’, ‘cubic’.

Type:: Interpolation type

lift_height: float#: Height (m) to lift the end-effector after the gripper phase.

name: str#: Name of the action, used for identification and logging.

sample_interval: int#: Number of waypoints for the full trajectory (approach + hand + lift/back).

velocity_limit: Optional[float]#: Optional velocity limit for the motion.

class embodichain.lab.sim.atomic_actions.PlaceAction[source]#

Bases: MoveAction

Methods:

`__init__`(motion_generator[, cfg])	Initialize the atomic action.
`execute`(target[, start_qpos])	execute pick up action
`validate`(target[, start_qpos])	Validate if the action is feasible without executing.

__init__(motion_generator, cfg=None)[source]#: Initialize the atomic action. :type motion_generator: MotionGenerator :param motion_generator: The motion generator instance to use for planning. :type cfg: Optional[PlaceActionCfg] :param cfg: Configuration for the action.

execute(target, start_qpos=None, **kwargs)[source]#

execute pick up action

Parameters:

target (ObjectSemantics) – object semantics containing grasp affordance and entity information
start_qpos (Optional[torch.Tensor], optional) – Planning start qpos. Defaults to None.

Returns:

is_success, trajectory of shape (n_envs, n_waypoints, dof), joint_ids corresponding to trajectory

Return type:

tuple[bool, torch.Tensor, list[float]]

validate(target, start_qpos=None, **kwargs)[source]#

Validate if the action is feasible without executing.

This method performs a quick feasibility check (e.g., IK solvability) without generating a full trajectory.

Returns:: True if action appears feasible, False otherwise

Engine & Registry#

class embodichain.lab.sim.atomic_actions.AtomicActionEngine[source]#

Bases: object

Central engine for managing and executing atomic actions.

Methods:

`__init__`(motion_generator[, actions_cfg_list])
`execute_static`(target_list)	Execute a sequence of actions to target poses.
`get_semantic_analyzer`()	Get the semantic analyzer for object understanding.
`set_semantic_analyzer`(analyzer)	Set a custom semantic analyzer.
`validate`(action_name, target, **kwargs)	Validate if a named action is feasible without executing.

__init__(motion_generator, actions_cfg_list=None)[source]#

execute_static(target_list)[source]#

Execute a sequence of actions to target poses.

Each element in target_list corresponds to an action in the order they were registered via actions_cfg_list.

Return type:: tuple[bool, Tensor]

get_semantic_analyzer()[source]#

Get the semantic analyzer for object understanding.

Return type:: SemanticAnalyzer

set_semantic_analyzer(analyzer)[source]#

Set a custom semantic analyzer.

Return type:: None

validate(action_name, target, **kwargs)[source]#

Validate if a named action is feasible without executing.

Return type:: bool

embodichain.lab.sim.atomic_actions.register_action(name, action_class, config_class=None)[source]#

Register a custom atomic action class globally.

This function allows registration of custom action types that can then be instantiated by the AtomicActionEngine.

Parameters:

name (str) – Unique identifier for the action type
action_class (Type[AtomicAction]) – The AtomicAction subclass to register
config_class (Optional[Type[ActionCfg]]) – Optional configuration class for the action

Return type:

None

Example

>>> class MyCustomAction(AtomicAction):
...     def execute(self, target, **kwargs):
...         # Implementation
...         pass
...     def validate(self, target, **kwargs):
...         return True
>>> register_action("my_custom", MyCustomAction)

embodichain.lab.sim.atomic_actions.unregister_action(name)[source]#

Unregister an action type.

Parameters:: name (str) – The action type identifier to remove
Return type:: None

embodichain.lab.sim.atomic_actions.get_registered_actions()[source]#

Get all registered action types.

Return type:: Dict[str, Type[AtomicAction]]
Returns:: Dictionary mapping action names to their classes

embodichain.lab.sim.atomic_actions

Contents

embodichain.lab.sim.atomic_actions#

Core#

Actions#

Engine & Registry#