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>, cartesian_path_sampler: 'Callable[[torch.Tensor], torch.Tensor] | None' = <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_heterogeneous_waypoints	Whether the selected backend accepts mixed waypoint movement types.
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"). Unsupported backend target types raise rather than silently switching to interpolation. Joint-only planners that own sparse waypoints receive IK solutions only at the requested Cartesian goals unless options.is_linear requests a dense Cartesian path. Quantity sampling retains every required joint waypoint. Automatically resolved trapezoidal options treat the requested count as a lower bound; explicit planner options remain authoritative.

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

Raises:

ValueError – If any required Cartesian waypoint fails IK or FK consistency. Use generate() for per-environment failures.

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_heterogeneous_waypoints: bool

Whether the selected backend accepts mixed waypoint movement types.

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>, cartesian_path_sampler: ‘Callable[[torch.Tensor], torch.Tensor] | None’ = <factory>, interpolate_position_step: ‘float’ = <factory>, interpolate_angle_step: ‘float’ = <factory>)

Attributes:

acceleration_limit	Optional scalar planner-owned joint acceleration budget.
cartesian_path_sampler	Optional exact-path sampler for normalized progress values.
control_part	Name of the robot part to control, e.g. 'left_arm'.
interpolate_angle_step	Orientation step in radians for Cartesian pre-interpolation.
interpolate_nums	Number of interpolation points to generate between each pair of waypoints.
interpolate_position_step	Position step in meters for Cartesian pre-interpolation.
interpolation_dt	Explicit waypoint interval for deterministic interpolation.
is_interpolate	Whether to allow interpolation before planning when the backend needs it.
is_linear	Request Cartesian pre-interpolation for joint-only backends.
plan_opts	Options to pass to the underlying planner during the planning phase.
preserve_cartesian_samples	Treat Cartesian targets as an exact sampled path in ik_interp only.
sample_count	Requested output sample count; None preserves backend defaults.
start_qpos	Observed controlled-joint start, shape (B, DOF).
strategy	backend planning or deterministic IK interpolation.
velocity_limit	Optional scalar speed request, capped by effective Robot joint limits.

acceleration_limit: float | None

Optional scalar planner-owned joint acceleration budget.

cartesian_path_sampler: Callable[[Tensor], Tensor] | None

Optional exact-path sampler for normalized progress values.

The callback receives a one-dimensional tensor spanning zero through one and returns poses with shape (B, T, 4, 4). Use it for paths whose geometry cannot be recovered from Cartesian chords, such as rotation about an external hinge. It is valid only with preserve_cartesian_samples.

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

Orientation step in radians for Cartesian pre-interpolation.

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

Position step in meters for Cartesian pre-interpolation.

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

Request Cartesian pre-interpolation for joint-only backends.

With ik_interp, requires explicit preserve_cartesian_samples; sparse endpoint IK followed by joint interpolation is not a Cartesian line.

plan_opts: PlanOptions | None

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

preserve_cartesian_samples: bool

Treat Cartesian targets as an exact sampled path in ik_interp only.

This constrained mode requires exactly sample_count - 1 target states; the observed start configuration supplies the first sample. Without motion limits, targets are emitted unchanged. With limits, their Cartesian path is resampled by a minimum-jerk progress law and every emitted pose is solved by IK.

sample_count: int | None

Requested output sample count; None preserves backend defaults.

start_qpos: Tensor | None

Observed controlled-joint start, shape (B, DOF).

Required for ik_interp. Backend pre-interpolation reads the current robot state when omitted; native backend requests use backend defaults.

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

backend planning or deterministic IK interpolation.

Type:

Motion strategy

velocity_limit: float | None

Optional scalar speed request, capped by effective Robot joint limits.