embodichain.lab.sim.motion.motion_generator

Motion generation coordinates planner backends, IK interpolation, collision-world options and normalized trajectory results. Import its configuration and strategy options from this module; backend contracts remain under motion.planners.

MotionGenerator	Unified motion generator for robot trajectory planning.
MotionGenCfg	MotionGenCfg(planner_cfg: 'BasePlannerCfg' = <factory>)
MotionGenOptions	MotionGenOptions(strategy: "Literal['motion_gen', 'ik_interp']" = <factory>, sample_count: 'int | None' = <factory>, velocity_limit: 'float | None' = <factory>, acceleration_limit: 'float | None' = <factory>, start_qpos: 'torch.Tensor | None' = <factory>, control_part: 'str | None' = <factory>, plan_opts: 'PlanOptions | None' = <factory>, is_interpolate: 'bool' = <factory>, interpolation_dt: 'float | None' = <factory>, interpolate_nums: 'int | list[int]' = <factory>, is_linear: 'bool' = <factory>, preserve_cartesian_samples: 'bool' = <factory>, interpolate_position_step: 'float' = <factory>, interpolate_angle_step: 'float' = <factory>)

Motion Generator

class embodichain.lab.sim.motion.motion_generator.MotionGenCfg

MotionGenCfg(planner_cfg: ‘BasePlannerCfg’ = <factory>)

Attributes:

planner_cfg

Configuration for the underlying planner.

planner_cfg: BasePlannerCfg

Configuration for the underlying planner. Must include ‘planner_type’ attribute to specify which planner to use, and any additional parameters required by that planner.

class embodichain.lab.sim.motion.motion_generator.MotionGenerator

Bases: object

Unified motion generator for robot trajectory planning.

This class provides a unified interface for trajectory planning with and without collision checking.

Parameters:

cfg (MotionGenCfg) – Configuration object for motion generation, must include ‘planner_cfg’ attribute

Methods:

__init__(cfg)
bind_collision_world(plan_opts, *, ...)	Bind live obstacle poses to owned planner options.
estimate_trajectory_sample_count([...])	Estimate the number of trajectory sampling points required.
generate(target_states[, options])	Generate one normalized, environment-batched motion plan.
interpolate_trajectory([control_part, ...])	Interpolate trajectory based on provided waypoints.
plot_trajectory(positions[, vels, accs])	Plot trajectory data.
register_planner_type(name, planner_class, ...)	Register a new planner type.
resolve_plan_options(plan_opts, *, sample_count)	Resolve owned backend options from backend-neutral motion limits.
validate_joint_trajectory(trajectory, *, ...)	Check exact joint samples through the selected planner backend.

Attributes:

collision_world_batch_mode	Return the backend's dynamic collision-world batch-sharing mode.
collision_world_entity_ids	Return every canonical entity ID in the planner collision world.
collision_world_info	Return the selected planner's collision-world contract.
dynamic_collision_entity_ids	Return canonical dynamic-obstacle IDs declared by the planner.
supports_dynamic_collision_world	Whether the planner accepts per-plan dynamic obstacle poses.
supports_joint_trajectory_validation	Whether the backend checks exact joint samples for collisions.

__init__(cfg)

bind_collision_world(plan_opts, *, obstacle_poses)

Bind live obstacle poses to owned planner options.

Parameters:

• plan_opts (PlanOptions | None) – Optional reusable caller-owned planner options.

• obstacle_poses (Mapping[str, Tensor]) – Batched world poses keyed by stable obstacle ID.

Return type:

PlanOptions

Returns:

Backend-specific options bound to the supplied collision world.

Raises:

ValueError – If the selected planner cannot consume dynamic obstacles.

property collision_world_batch_mode: Literal['shared', 'per_env'] | None

Return the backend’s dynamic collision-world batch-sharing mode.

property collision_world_entity_ids: tuple[str, ...]

Return every canonical entity ID in the planner collision world.

property collision_world_info: CollisionWorldInfo | None

Return the selected planner’s collision-world contract.

property dynamic_collision_entity_ids: tuple[str, ...]

Return canonical dynamic-obstacle IDs declared by the planner.

estimate_trajectory_sample_count(xpos_list=None, qpos_list=None, step_size=0.01, angle_step=0.03490658503988659, control_part=None)

Estimate the number of trajectory sampling points required.

This function estimates the total number of sampling points needed to generate a trajectory based on the given waypoints and sampling parameters. Supports parallel computation for batched input trajectories.

Parameters:

• xpos_list (Tensor | list[Tensor] | None) – Tensor of 4x4 transformation matrices, shape [B, N, 4, 4] or [N, 4, 4]

• qpos_list (Tensor | list[Tensor] | None) – Tensor of joint positions, shape [B, N, D] or [N, D] (optional)

• step_size (float | Tensor) – Maximum allowed distance between points (meters). Float or Tensor [B]

• angle_step (float | Tensor) – Maximum allowed angular difference between points (radians). Float or Tensor [B]

Returns:

Estimated number of sampling points per trajectory, shape [B]

(or scalar tensor if single trajectory)

Return type:

torch.Tensor

generate(target_states, options=None)

Generate one normalized, environment-batched motion plan.

options.strategy selects either the configured planner backend ("motion_gen") or deterministic waypoint IK followed by joint-space interpolation ("ik_interp"). Joint targets fall back to interpolation when the configured backend cannot consume MoveType.JOINT_MOVE.

Parameters:

• target_states (list[PlanState]) – Batched planner waypoints.

• options (MotionGenOptions | None) – Motion-generation strategy and runtime options.

Return type:

PlanResult

Returns:

Normalized result with a per-environment success mask and joint positions. Failed rows hold start_qpos when it is supplied.

Raises:

ValueError – If targets or options violate the motion contract.

interpolate_trajectory(control_part=None, xpos_list=None, qpos_list=None, options=None)

Interpolate trajectory based on provided waypoints.

This method performs interpolation on the provided waypoints to generate a smoother trajectory. It supports both Cartesian (end-effector) and joint space interpolation based on the control part and options specified.

Parameters:

• control_part (str | None) – Name of the robot part to control, e.g. ‘left_arm’. Must correspond to a valid control part defined in the robot’s configuration.

• xpos_list (Tensor | None) – End-effector poses, shape (B, N, 4, 4) or (N, 4, 4). Required if control_part is an end-effector control part.

• qpos_list (Tensor | None) – Joint positions, shape (B, N, DOF) or (N, DOF). Required if control_part is a joint control part.

• options (MotionGenOptions | None) – MotionGenOptions containing interpolation settings such as step size and whether to use linear interpolation.

Returns:

• interpolate_qpos_list: Interpolated joint positions, shape (B, M, DOF).

• feasible_pose_targets: Corresponding end-effector poses, shape (B, M, 4, 4), or None if not applicable.

Return type:

Tuple containing

plot_trajectory(positions, vels=None, accs=None)

Plot trajectory data.

This method visualizes the trajectory by plotting position, velocity, and acceleration curves for each joint over time. It also displays the constraint limits for reference. Supports plotting batched trajectories.

Parameters:

• positions (Tensor) – Position tensor (N, DOF) or (B, N, DOF)

• vels (Tensor | None) – Velocity tensor (N, DOF) or (B, N, DOF), optional

• accs (Tensor | None) – Acceleration tensor (N, DOF) or (B, N, DOF), optional

Return type:

None

Note

• Creates a multi-subplot figure (position, and optional velocity/acceleration)

• Shows constraint limits as dashed lines

• If input is (B, N, DOF), plots elements separately per batch sequence.

• Requires matplotlib to be installed

classmethod register_planner_type(name, planner_class, planner_cfg_class)

Register a new planner type.

Return type:

None

resolve_plan_options(plan_opts, *, sample_count, velocity_limit=None, acceleration_limit=None)

Resolve owned backend options from backend-neutral motion limits.

Parameters:

• plan_opts (PlanOptions | None) – Optional caller-owned backend-specific options.

• sample_count (int | None) – Requested output sample count, or None to use the backend default.

• velocity_limit (float | None) – Optional scalar joint velocity limit.

• acceleration_limit (float | None) – Optional scalar joint acceleration limit.

Return type:

PlanOptions

Returns:

An independently owned options object for the configured backend.

Raises:

ValueError – If a supplied sample_count is smaller than two.

property supports_dynamic_collision_world: bool

Whether the planner accepts per-plan dynamic obstacle poses.

Returns:

True when the selected planner supports collision-world updates.

property supports_joint_trajectory_validation: bool

Whether the backend checks exact joint samples for collisions.

validate_joint_trajectory(trajectory, *, control_part, obstacle_poses=None)

Check exact joint samples through the selected planner backend.

Parameters:

• trajectory (Tensor) – Simulator-order joint samples with shape (B, T, D).

• control_part (str) – Robot control part whose ordered joints form D.

• obstacle_poses (Mapping[str, Tensor] | None) – Optional live dynamic-obstacle poses.

Return type:

Tensor

Returns:

Boolean validity mask with shape (B, T) on the trajectory device.

class embodichain.lab.sim.motion.motion_generator.MotionGenOptions

MotionGenOptions(strategy: “Literal[‘motion_gen’, ‘ik_interp’]” = <factory>, sample_count: ‘int | None’ = <factory>, velocity_limit: ‘float | None’ = <factory>, acceleration_limit: ‘float | None’ = <factory>, start_qpos: ‘torch.Tensor | None’ = <factory>, control_part: ‘str | None’ = <factory>, plan_opts: ‘PlanOptions | None’ = <factory>, is_interpolate: ‘bool’ = <factory>, interpolation_dt: ‘float | None’ = <factory>, interpolate_nums: ‘int | list[int]’ = <factory>, is_linear: ‘bool’ = <factory>, preserve_cartesian_samples: ‘bool’ = <factory>, interpolate_position_step: ‘float’ = <factory>, interpolate_angle_step: ‘float’ = <factory>)

Attributes:

acceleration_limit	Optional scalar joint acceleration limit used by compatible backends.
control_part	Name of the robot part to control, e.g. 'left_arm'.
interpolate_angle_step	Angular step size for interpolation in joint space (radians).
interpolate_nums	Number of interpolation points to generate between each pair of waypoints.
interpolate_position_step	Step size for interpolation.
interpolation_dt	Explicit waypoint interval for deterministic interpolation.
is_interpolate	Whether to allow interpolation before planning when the backend needs it.
is_linear	If True, use cartesian linear interpolation, else joint space
plan_opts	Options to pass to the underlying planner during the planning phase.
preserve_cartesian_samples	Treat Cartesian targets as exact output samples and solve each with IK.
sample_count	Requested output sample count; None preserves backend defaults.
start_qpos	Optional starting joint configuration for the trajectory, shape (B, DOF).
strategy	backend planning or deterministic IK interpolation.
velocity_limit	Optional scalar joint velocity limit used by compatible backends.

acceleration_limit: float | None

Optional scalar joint acceleration limit used by compatible backends.

control_part: str | None

Name of the robot part to control, e.g. ‘left_arm’. Must correspond to a valid control part defined in the robot’s configuration.

interpolate_angle_step: float

Angular step size for interpolation in joint space (radians). Only used if is_linear is False.

interpolate_nums: int | list[int]

Number of interpolation points to generate between each pair of waypoints.

Can be an integer (same for all segments) or a list of integers with len(PlanState) specifying the number of points for each segment.

interpolate_position_step: float

Step size for interpolation. If is_linear is True, this is the step size in Cartesian space (meters). If is_linear is False, this is the step size in joint space (radians).

interpolation_dt: float | None

Explicit waypoint interval for deterministic interpolation.

is_interpolate: bool

Whether to allow interpolation before planning when the backend needs it.

Joint-only backends use this to convert Cartesian targets into joint waypoints. Backends that accept Cartesian targets directly receive the original targets unchanged.

Note

• The pre-interpolation only works for PlanState with MoveType.EEF_MOVE or MoveType.JOINT_MOVE.

is_linear: bool

If True, use cartesian linear interpolation, else joint space

plan_opts: PlanOptions | None

Options to pass to the underlying planner during the planning phase.

preserve_cartesian_samples: bool

Treat Cartesian targets as exact output samples and solve each with IK.

This constrained mode requires exactly sample_count - 1 target states; the observed start configuration supplies the first output sample.

sample_count: int | None

Requested output sample count; None preserves backend defaults.

start_qpos: Tensor | None

Optional starting joint configuration for the trajectory, shape (B, DOF). If provided, the planner will ensure that the trajectory starts from this configuration. If not provided, the planner will use the current joint configuration of the robot as the starting point.

strategy: Literal['motion_gen', 'ik_interp']

backend planning or deterministic IK interpolation.

Type:

Motion strategy

velocity_limit: float | None

Optional scalar joint velocity limit used by compatible backends.