[isaacsim.robot_motion.cumotion] cumotion#

Version: 1.4.0

Overview#

The isaacsim.robot_motion.cumotion extension provides access to cuMotion planners and controllers within Isaac Sim’s motion generation framework. This extension bridges NVIDIA’s cuMotion library with Isaac Sim, offering high-performance motion planning, trajectory generation, and reactive control for robotic manipulators.

Concepts#

cuMotion Integration#

The extension serves as a wrapper around NVIDIA’s cuMotion library, translating between Isaac Sim’s coordinate systems and data structures and cuMotion’s internal representations. All cuMotion operations work in the robot base frame, while Isaac Sim typically works in the world frame - the extension handles these coordinate transformations automatically.

Robot Configuration#

Robot setup requires both URDF (Unified Robot Description Format) and XRDF (Extended Robot Description Format) files. The URDF describes the robot’s kinematic structure, while the XRDF contains cuMotion-specific configuration parameters for planning and control.

Key Components#

`CumotionRobot`#

The CumotionRobot dataclass encapsulates all robot-specific data needed for cuMotion operations, including the robot description, kinematics solver, and controlled joint names. You can load robots using load_cumotion_robot for custom configurations or load_cumotion_supported_robot for pre-configured robots.

`CumotionWorldInterface`#

CumotionWorldInterface manages collision geometry and obstacle tracking between Isaac Sim’s USD scene and cuMotion’s collision world. It handles coordinate frame transformations and provides methods to add various collision primitives (spheres, cubes, meshes, planes, capsules) and update their poses dynamically.

Motion Planners#

GraphBasedMotionPlanner implements sampling-based planning algorithms (RRT variants) for finding collision-free paths. It supports planning to configuration space targets, full pose targets (position + orientation), and translation-only targets where orientation is unconstrained.

TrajectoryOptimizer uses cuMotion’s optimization-based approach to generate smooth, collision-free trajectories. It optimizes over multiple cost functions including smoothness, collision avoidance, and goal achievement.

Controllers and Generators#

RmpFlowController implements cuMotion’s RMPflow algorithm for reactive motion control. This controller continuously computes joint commands based on multiple task-space and configuration-space attractors, providing smooth and collision-aware motion.

TrajectoryGenerator creates smooth, time-optimal trajectories from discrete waypoints without collision checking. It handles conversion between configuration space and task space representations.

`CumotionTrajectory`#

CumotionTrajectory wraps cuMotion trajectories within Isaac Sim’s trajectory interface, allowing queries for robot states at specific times along continuous-time trajectories.

Integration#

The extension integrates with Isaac Sim’s experimental motion generation framework through the isaacsim.robot_motion.experimental.motion_generation dependency. Controllers implement the BaseController interface, trajectories implement the Trajectory interface, and world interfaces implement the WorldInterface interface, ensuring compatibility with Isaac Sim’s broader motion generation ecosystem.

Enable Extension#

The extension can be enabled (if not already) in one of the following ways:

Command-line interface

Define the next entry as an application argument from a terminal.

APP_SCRIPT.(sh|bat) --enable isaacsim.robot_motion.cumotion

Experience/extension configuration

Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.

[dependencies]
"isaacsim.robot_motion.cumotion" = {}

Extension Manager UI

Open the Window > Extensions menu in a running application instance and search for isaacsim.robot_motion.cumotion. Then, toggle the enable control button if it is not already active.

Python API#

Configuration Loading

`load_cumotion_robot`	Load a cuMotion robot from URDF and XRDF files.
`load_cumotion_supported_robot`	Load a cuMotion robot for a supported robot.
`CumotionRobot`	Robot for cuMotion planning and control.

World Interface

CumotionWorldInterface

World interface for cuMotion collision checking and planning.

Motion Policies

RmpFlowController

Reactive motion policy controller using cuMotion's RMPflow algorithm.

Motion Planning

GraphBasedMotionPlanner

Graph-based motion planner using cuMotion for collision-free path planning.

Trajectory Generation

`TrajectoryGenerator`	Trajectory generator for creating smooth, time-optimal trajectories (not collision-aware).
`TrajectoryOptimizer`	Trajectory optimizer using cuMotion's Trajectory Optimizer algorithm.
`CumotionTrajectory`	Continuous-time trajectory for a robot using cuMotion.

Transform Utilities

`impl.utils.isaac_sim_to_cumotion_pose`	Convert Isaac Sim pose to cuMotion pose in the robot base frame.
`impl.utils.isaac_sim_to_cumotion_translation`	Convert Isaac Sim position to cuMotion position in robot base frame.
`impl.utils.isaac_sim_to_cumotion_rotation`	Convert Isaac Sim orientation to cuMotion rotation in robot base frame.
`impl.utils.cumotion_to_isaac_sim_pose`	Convert cuMotion pose in base frame to Isaac Sim pose in world frame.
`impl.utils.cumotion_to_isaac_sim_translation`	Convert cuMotion position to Isaac Sim position in world frame.
`impl.utils.cumotion_to_isaac_sim_rotation`	Convert cuMotion rotation to Isaac Sim orientation in world frame.

Configuration Loading#

load_cumotion_robot( directory: Path | str, urdf_filename: Path | str = 'robot.urdf', xrdf_filename: Path | str = 'robot.xrdf', ) → CumotionRobot#

Load a cuMotion robot from URDF and XRDF files.

Loads the robot description from the specified URDF and XRDF files and creates a robot object containing the robot description, kinematics solver, and controlled joint names.

Parameters:

directory – Path to the directory containing the robot configuration files.
urdf_filename – Name of the URDF file. Defaults to “robot.urdf”.
xrdf_filename – Name of the XRDF file. Defaults to “robot.xrdf”.

Returns:

Robot object containing all necessary data for cuMotion.

Raises:

FileNotFoundError – If the URDF/XRDF files cannot be found.
Exception – If the URDF/XRDF files cannot be loaded or parsed.

Example

robot = load_cumotion_robot(
    directory="/path/to/franka",
    urdf_filename="robot.urdf",
    xrdf_filename="robot.xrdf"
)

load_cumotion_supported_robot( robot_name: str, ) → CumotionRobot#

Load a cuMotion robot for a supported robot.

Loads a pre-configured robot from the extension’s robot_configurations directory. This is a convenience function for commonly used robots that come packaged with the extension.

Parameters:: robot_name – Name of the robot (e.g., “franka”, “ur10”).
Returns:: Robot object for the specified robot.
Raises:: FileNotFoundError – If the robot cannot be found or loaded.

Example

robot = load_cumotion_supported_robot("franka")

class CumotionRobot( directory: Path, robot_description: RobotDescription, kinematics: Kinematics, controlled_joint_names: list[str], )#

Bases: object

Robot for cuMotion planning and control.

This dataclass encapsulates all the necessary data for a robot to be used with cuMotion, including the robot description, kinematics solver, and controlled joint names.

Parameters:

directory – Path to the robot configuration directory containing URDF/XRDF files.
robot_description – cuMotion robot description loaded from URDF/XRDF files.
kinematics – cuMotion kinematics solver for the robot.
controlled_joint_names – List of joint names that are controlled by the planner.

controlled_joint_names: list[str]#

directory: Path#

kinematics: Kinematics#

robot_description: RobotDescription#

World Interface#

class CumotionWorldInterface( world_to_robot_base: tuple[array, array] | None = None, debug_visualizer: CumotionDebugVisualizer | None = None, device: Device | str | None = None, )#

Bases: WorldInterface

World interface for cuMotion collision checking and planning.

This class provides the bridge between Isaac Sim’s USD scene representation and cuMotion’s collision world. It manages obstacle registration, updates, and coordinate frame transformations between Isaac Sim (world frame) and cuMotion (robot base frame).

Parameters:

world_to_robot_base – Transform from world frame to robot base frame. Defaults to None (identity transform). This is a tuple of position and quaternion, where the quaternion is in the form (w, x, y, z).
debug_visualizer – Optional visualizer used to display collision geometry.
device – Device used by the interface for internally-allocated warp arrays and for the per-frame collider transform composition. Accepts the same values as wp.get_device() (None, "cpu", "cuda", "cuda:0", or a wp.Device); None resolves to warp’s current default device. CPU devices run the transform composition in vectorized NumPy on the host; CUDA devices run the Warp kernel path on the GPU.

world_view#: cuMotion world view for collision queries.

Example

world_interface = CumotionWorldInterface()

add_capsules( prim_paths: list[str], axes: list[Literal['X', 'Y', 'Z']], radii: array, lengths: array, scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → None#

Add capsule collision obstacles to the cuMotion world.

Parameters:

prim_paths – USD prim paths for each capsule.
axes – Capsule axis for each capsule.
radii – Capsule radii.
lengths – Capsule lengths.
scales – Local scale factors for each capsule.
safety_tolerances – Safety margin around each capsule.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each capsule.

add_cones( prim_paths: list[str], axes: list[Literal['X', 'Y', 'Z']], radii: array, lengths: array, scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → NoReturn#

Add cone obstacles to the planning world.

Parameters:

prim_paths – USD prim paths for each cone.
axes – Orientation axis for each cone.
radii – Cone base radii.
lengths – Cone heights.
scales – Local scale factors for each cone.
safety_tolerances – Safety margin around each cone.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each cone.

Raises:

NotImplementedError – If not overridden by subclass.

add_cubes( prim_paths: list[str], sizes: array, scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → None#

Add cuboid collision obstacles to the cuMotion world.

Parameters:

prim_paths – USD prim paths for each cube.
sizes – Cube side lengths.
scales – Local scale factors for each cube.
safety_tolerances – Safety margin around each cube.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each cube.

add_cylinders( prim_paths: list[str], axes: list[Literal['X', 'Y', 'Z']], radii: array, lengths: array, scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → NoReturn#

Add cylinder obstacles to the planning world.

Parameters:

prim_paths – USD prim paths for each cylinder.
axes – Orientation axis for each cylinder.
radii – Cylinder radii.
lengths – Cylinder heights.
scales – Local scale factors for each cylinder.
safety_tolerances – Safety margin around each cylinder.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each cylinder.

Raises:

NotImplementedError – If not overridden by subclass.

add_meshes( prim_paths: list[str], points: list[array], face_vertex_indices: list[array], face_vertex_counts: list[array], normals: list[array], scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → NoReturn#

Add mesh obstacles to the planning world.

Parameters:

prim_paths – USD prim paths for each mesh.
points – Vertex positions for each mesh.
face_vertex_indices – Face vertex indices for each mesh.
face_vertex_counts – Number of vertices per face for each mesh.
normals – Face normals for each mesh.
scales – Local scale factors for each mesh.
safety_tolerances – Safety margin around each mesh.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each mesh.

Raises:

NotImplementedError – If not overridden by subclass.

add_oriented_bounding_boxes( prim_paths: list[str], centers: array, rotations: array, half_side_lengths: array, scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → None#

Add oriented bounding box collision obstacles to the cuMotion world as cuboids.

Parameters:

prim_paths – USD prim paths for each oriented bounding box.
centers – OBB centers relative to the object frame.
rotations – OBB rotation quaternions relative to the object frame.
half_side_lengths – Half side lengths of each OBB.
scales – Local scale factors for each OBB.
safety_tolerances – Safety margin around each OBB.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each OBB.

add_planes( prim_paths: list[str], axes: list[Literal['X', 'Y', 'Z']], lengths: array, widths: array, scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → None#

Add plane collision obstacles to the cuMotion world as thin cuboids.

Parameters:

prim_paths – USD prim paths for each plane.
axes – Plane normal axis for each plane.
lengths – Plane lengths.
widths – Plane widths.
scales – Local scale factors for each plane.
safety_tolerances – Safety margin around each plane.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each plane.

add_spheres( prim_paths: list[str], radii: array, scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → None#

Add sphere collision obstacles to the cuMotion world.

Parameters:

prim_paths – USD prim paths for each sphere.
radii – Sphere radii.
scales – Local scale factors for each sphere.
safety_tolerances – Safety margin around each sphere.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each sphere.

add_triangulated_meshes( prim_paths: list[str], points: list[array], face_vertex_indices: list[array], scales: array, safety_tolerances: array, poses: tuple[array, array], enabled_array: array, ) → None#

Add triangulated mesh collision obstacles to the cuMotion world using sphere decomposition.

Parameters:

prim_paths – USD prim paths for each mesh.
points – List of vertex position arrays for each mesh.
face_vertex_indices – List of triangle index arrays for each mesh.
scales – Local scale factors for each mesh.
safety_tolerances – Safety margin around each mesh.
poses – Tuple of (positions, orientations) arrays.
enabled_array – Collision enabled state for each mesh.

get_world_to_robot_base_transform() → tuple[array, array]#

Get the transform from world frame to robot base frame.

Returns the current transform that maps coordinates from the Isaac Sim world frame to the cuMotion robot base frame. The result is memoized: the same wp.array objects are returned on every call until the base-frame pose is updated via update_world_to_robot_root_transforms.

Returns:: Tuple of (position, quaternion) as warp arrays where position has shape (3,) and quaternion has shape (4,) in (w, x, y, z) format.

update_capsule_properties( prim_paths: list[str], axes: list[Literal['X', 'Y', 'Z']] | None, radii: array | None, lengths: array | None, ) → NoReturn#

Update capsule-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of capsules to update.
axes – New orientation axes. Pass None to skip updating.
radii – New capsule radii. Pass None to skip updating.
lengths – New capsule heights. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_cone_properties( prim_paths: list[str], axes: list[Literal['X', 'Y', 'Z']] | None, radii: array | None, lengths: array | None, ) → NoReturn#

Update cone-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of cones to update.
axes – New orientation axes. Pass None to skip updating.
radii – New cone base radii. Pass None to skip updating.
lengths – New cone heights. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_cube_properties( prim_paths: list[str], sizes: array | None, ) → NoReturn#

Update cube-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of cubes to update.
sizes – New cube side lengths. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_cylinder_properties( prim_paths: list[str], axes: list[Literal['X', 'Y', 'Z']] | None, radii: array | None, lengths: array | None, ) → NoReturn#

Update cylinder-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of cylinders to update.
axes – New orientation axes. Pass None to skip updating.
radii – New cylinder radii. Pass None to skip updating.
lengths – New cylinder heights. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_mesh_properties( prim_paths: list[str], points: list[array] | None, face_vertex_indices: list[array] | None, face_vertex_counts: list[array] | None, normals: list[array] | None, ) → NoReturn#

Update mesh-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of meshes to update.
points – New vertex positions. Pass None to skip updating.
face_vertex_indices – New face vertex indices. Pass None to skip updating.
face_vertex_counts – New face vertex counts. Pass None to skip updating.
normals – New face normals. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_obstacle_enables( prim_paths: list[str], enabled_array: array, ) → None#

Update the enabled/disabled state of tracked obstacles.

Enables or disables collision checking for obstacles that have already been added to the world. Disabled obstacles are ignored during collision checking.

Parameters:

prim_paths – List of prim paths identifying the obstacles to update.
enabled_array – Warp array of boolean values indicating enabled state, shape (N,) where N is the number of prim paths.

Raises:

RuntimeError – If any prim paths are not currently tracked.
ValueError – If input arrays have mismatched lengths or are empty.

update_obstacle_scales( prim_paths: list[str], scales: array, ) → NoReturn#

Update local scales for existing obstacles.

Parameters:

prim_paths – USD prim paths of obstacles to update.
scales – New local scale factors.

Raises:

NotImplementedError – If not overridden by subclass.

update_obstacle_transforms( prim_paths: list[str], poses: tuple[array, array], ) → None#

Update the world-to-object transforms for tracked obstacles.

Updates the poses of obstacles that have already been added to the world.

Parameters:

prim_paths – List of prim paths identifying the obstacles to update.
poses – Tuple of (positions, quaternions) where positions has shape (N, 3) and quaternions has shape (N, 4) in (w, x, y, z) format.

Raises:

RuntimeError – If any prim paths are not currently tracked.
ValueError – If input arrays have mismatched lengths or are empty.

update_obstacle_twists( prim_paths: list[str], poses: tuple[array, array], ) → NoReturn#

Update twist velocities for existing obstacles.

Parameters:

prim_paths – USD prim paths of obstacles to update.
poses – Tuple of (linear velocities, angular velocities) arrays.

Raises:

NotImplementedError – If not overridden by subclass.

update_oriented_bounding_box_properties( prim_paths: list[str], centers: array | None, rotations: array | None, half_side_lengths: array | None, ) → NoReturn#

Update oriented bounding box-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of bounding boxes to update.
centers – New local center positions. Pass None to skip updating.
rotations – New local rotations as quaternions (w, x, y, z). Pass None to skip updating.
half_side_lengths – New half extents. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_plane_properties( prim_paths: list[str], axes: list[Literal['X', 'Y', 'Z']] | None, lengths: array | None, widths: array | None, ) → NoReturn#

Update plane-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of planes to update.
axes – New normal axes. Pass None to skip updating.
lengths – New plane lengths. Pass None to skip updating.
widths – New plane widths. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_sphere_properties( prim_paths: list[str], radii: array | None, ) → NoReturn#

Update sphere-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of spheres to update.
radii – New sphere radii. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_triangulated_mesh_properties( prim_paths: list[str], points: list[array] | None, face_vertex_indices: list[array] | None, ) → NoReturn#

Update triangulated mesh-specific properties for existing obstacles.

Parameters:

prim_paths – USD prim paths of triangulated meshes to update.
points – New vertex positions. Pass None to skip updating.
face_vertex_indices – New triangle vertex indices. Pass None to skip updating.

Raises:

NotImplementedError – If not overridden by subclass.

update_world_to_robot_root_transforms( poses: tuple[array, array], ) → None#

Update the transform from world frame to robot base frame.

cuMotion plans relative to the robot base frame. This method updates the base frame pose and recomputes all collider transforms in the base frame.

Parameters:

poses – Tuple of (positions, quaternions) where positions has shape (1, 3) and quaternions has shape (1, 4) in (w, x, y, z) format.

Raises:

ValueError – If the number of transforms is not exactly 1.
ValueError – If positions don’t have 3 elements.
ValueError – If quaternions don’t have 4 elements.

property world_view: cumotion.WorldView#: Get the world_view associated with the cumotion.World object.

Motion Policies#

class RmpFlowController( cumotion_robot: CumotionRobot, cumotion_world_interface: CumotionWorldInterface, robot_joint_space: list[str], robot_site_space: list[str], rmp_flow_configuration_filename: Path | str = 'rmp_flow.yaml', tool_frame: str | None = None, maximum_substep_size: float = 0.008333333333333333, )#

Bases: BaseController

Reactive motion policy controller using cuMotion’s RMPflow algorithm.

RMPflow (Riemannian Motion Policies) is a reactive control algorithm that generates smooth, collision-free motions by combining multiple motion policies in task and configuration space. This controller continuously updates joint commands based on the desired targets.

Note

For performance, reset() pre-allocates a single output RobotState and forward() returns that same instance on every call, mutating its joint buffer in place. Callers that need to retain a value across forward() calls must copy it out (see forward() for details).

Parameters:

cumotion_robot – Robot containing kinematics and joint information.
cumotion_world_interface – World interface providing collision geometry.
robot_joint_space – The full ordered joint-space of the controlled robot.
robot_site_space – The full ordered site-space of the controlled robot (used for validation of tool-frame name only).
rmp_flow_configuration_filename – Path to the RMPflow YAML configuration file. If a relative path is provided, it is resolved relative to cumotion_robot.directory. If an absolute path is provided, it is used as-is. Defaults to “rmp_flow.yaml”.
tool_frame – Name of the tool frame for end-effector control. Defaults to None, which uses the first tool frame defined in the robot description.
maximum_substep_size – Maximum timestep size (in seconds) used during Euler integration. When the frame duration exceeds this value, the integration is split into multiple substeps to improve numerical stability.

Raises:

ValueError – If cumotion_robot.controlled_joint_names is not a subset of robot_joint_space.
ValueError – If tool_frame is not found in robot_site_space.
ValueError – If maximum_substep_size is not strictly positive.
RuntimeError – If no tool frames are available in the robot description and tool_frame is None.

Example

controller = RmpFlowController(
    cumotion_robot=robot,
    cumotion_world_interface=world_interface,
    rmp_flow_configuration_filename="rmp_flow.yaml"
)
controller.reset(estimated_state, setpoint_state, t=0.0)
desired_state = controller.forward(estimated_state, setpoint_state, t=0.1)

forward(

estimated_state: RobotState,

setpoint_state: RobotState | None,

t: float,

**kwargs: Any,

) → RobotState | None#

Compute the desired joint action for the next time-step.

Evaluates the RMPflow controller to compute desired joint positions and velocities based on the current desired robot state and target attractors. The controller integrates the computed accelerations over time.

Parameters:

estimated_state – Current estimated state of the robot.
setpoint_state – Desired setpoint state containing target attractors. Can include joint positions, end-effector positions, and/or orientations. End-effector inputs must match the tool frame defined at initialization for this controller.
t – Current clock time (simulation or real).
**kwargs – Additional arguments for the controller.

Returns:

Robot state containing desired joint positions and velocities, or None if the controller is not initialized.

Warning

For performance, forward() returns the same RobotState instance on every call and mutates its underlying joint buffer in place. The returned object is a live view, not a snapshot.

state_a is state_b is True for any two values returned by forward() between reset() calls.
state.joints.data_array aliases the controller’s internal buffer and reflects the most recent forward() result.
state.joints.positions / .velocities are lazily rebuilt after each forward(); reading them after a subsequent forward() returns the new values.
reset() re-allocates these objects, so references taken before a reset() are orphaned (they keep their last values but are no longer updated).

If you need to retain a value across forward() calls (for interpolation, logging, etc.), copy it out immediately, e.g. positions = desired_state.joints.positions.numpy().copy().

Example

desired_state = controller.forward(current_state, target_state, t=1.0)
if desired_state is not None:
    robot.set_dof_position_targets(
        desired_state.joints.positions,
        indices=[0],
        dof_indices=robot.get_joint_indices(desired_state.joints.names)
    )

# Snapshot for later use; do not hold desired_state itself,
# since the next forward() call will overwrite it.
positions_t1 = desired_state.joints.positions.numpy().copy()

get_rmp_flow_config() → RmpFlowConfig#

Get the RMPflow configuration object.

Returns the underlying cuMotion configuration object, allowing users to modify controller parameters before initialization.

Returns:: The cuMotion RMPflow configuration object.

Example

config = controller.get_rmp_flow_config()
config.set_param("cspace_target_rmp/damping_gain", 0.9)

reset(

estimated_state: RobotState,

setpoint_state: RobotState | None,

t: float,

**kwargs: Any,

) → bool#

Reset the controller to a safe initial state.

Initializes the RMPflow controller and sets the internal state to match the current robot configuration. This should be called before running the controller for the first time.

Note

reset() allocates a fresh output RobotState / JointState pair (the objects subsequently returned by forward()). Any RobotState reference obtained from a prior forward() call becomes orphaned after reset(): it retains its last values but is no longer updated by future forward() calls.

Parameters:

estimated_state – Current estimated state of the robot.
setpoint_state – Initial setpoint state (currently unused).
t – Current clock time (simulation or real).
**kwargs – Additional arguments for the controller.

Returns:

True if reset was successful, False otherwise.

Example

success = controller.reset(current_state, None, t=0.0)
if success:
    print("Controller initialized successfully")

Motion Planning#

class GraphBasedMotionPlanner( cumotion_robot: CumotionRobot, cumotion_world_interface: CumotionWorldInterface, tool_frame: str | None = None, graph_planner_config_filename: Path | str | None = None, )#

Bases: object

Graph-based motion planner using cuMotion for collision-free path planning.

This planner uses sampling-based algorithms (RRT variants) to find collision-free paths for robotic manipulators. It supports planning to configuration space targets, task space pose targets, and translation-only targets.

Parameters:

cumotion_robot – Robot configuration containing the robot description (URDF/XRDF) and configuration directory.
cumotion_world_interface – World interface providing collision geometry and world view.
tool_frame – Name of the tool frame to use for task space planning. Defaults to None, which uses the first tool frame defined in the robot description.
graph_planner_config_filename – Path to a YAML configuration file for the planner parameters. If a relative path is provided, it is resolved relative to cumotion_robot.directory. If an absolute path is provided, it is used as-is. Defaults to None, which uses default planner parameters.

Example

from isaacsim.robot_motion.cumotion import (
    CumotionRobot,
    CumotionWorldInterface,
    GraphBasedMotionPlanner,
)

robot_config = CumotionRobot(franka_directory)
world_interface = CumotionWorldInterface(robot_config)
planner = GraphBasedMotionPlanner(robot_config, world_interface)

# Plan to a joint configuration target
path = planner.plan_to_cspace_target(q_initial, q_target)

get_cumotion_robot() → CumotionRobot#

Get the robot configuration.

Returns:: The robot configuration used by this planner.

get_graph_planner_config() → MotionPlannerConfig#

Get the motion planner configuration.

Returns the underlying cuMotion configuration object, allowing users to modify planner parameters before planning.

Returns:: The cuMotion motion planner configuration object.

Example

config = planner.get_graph_planner_config()
config.set_param("max_iterations", cumotion.MotionPlannerConfig.ParamValue(1000))

Plan a collision-free path to a target joint configuration.

Uses graph-based planning (RRT) to find a collision-free path from the initial joint configuration to the target joint configuration in configuration space.

Parameters:

q_initial – Initial joint configuration.
q_final – Target joint configuration.

Returns:

Path object if a path was found, None otherwise.

Example

q_initial = [0.0, -0.5, 0.0, -2.0, 0.0, 1.5, 0.75]
q_target = [1.0, -0.3, 0.2, -1.8, 0.1, 1.2, 0.5]
path = planner.plan_to_cspace_target(q_initial, q_target)
if path is not None:
    trajectory = path.to_minimal_time_joint_trajectory()

Plan a collision-free path to a target pose (position + orientation) defined relative to the world frame.

Uses JtRRT (Jacobian-transpose RRT) to find a collision-free path from the initial joint configuration to a task space pose target. The orientation is fully constrained.

Parameters:

q_initial – Initial joint configuration.
position – Target position as [x, y, z] relative to world origin.
orientation – Target orientation as quaternion [w, x, y, z] or 3x3 rotation matrix relative to world frame.

Returns:

Path object if a path was found, None otherwise.

Raises:

ValueError – If orientation is not a valid quaternion (4 elements) or 3x3 rotation matrix.

Example

q_initial = [0.0, -0.5, 0.0, -2.0, 0.0, 1.5, 0.75]
position = [0.5, 0.2, 0.4]
orientation = [1.0, 0.0, 0.0, 0.0]  # wxyz quaternion (identity)
path = planner.plan_to_pose_target(q_initial, position, orientation)

Plan a collision-free path to a target position (translation only) defined relative to the world frame.

Uses JtRRT (Jacobian-transpose RRT) to find a collision-free path from the initial joint configuration to a task space translation target. The end-effector orientation is unconstrained, allowing the planner more flexibility in finding a valid path.

Parameters:

q_initial – Initial joint configuration.
translation_target – Target position as [x, y, z] relative to world frame origin.

Returns:

Path object if a path was found, None otherwise.

Example

q_initial = [0.0, -0.5, 0.0, -2.0, 0.0, 1.5, 0.75]
translation_target = [0.5, 0.2, 0.4]
path = planner.plan_to_translation_target(q_initial, translation_target)

Trajectory Generation#

class TrajectoryGenerator( cumotion_robot: CumotionRobot, robot_joint_space: list[str], )#

Bases: object

Trajectory generator for creating smooth, time-optimal trajectories (not collision-aware).

This class provides utilities for generating smooth trajectories from discrete waypoints or path specifications. It handles conversion between configuration space and task space representations and generates time-optimal trajectories respecting joint velocity and acceleration limits.

Parameters:

cumotion_robot – Robot configuration containing kinematics and joint information.
robot_joint_space – List of joint names defining the robot’s joint space.

Raises:

ValueError – If cumotion controlled joints are not a subset of the robot_joint_space.

Example

generator = TrajectoryGenerator(robot_config, joint_names)
trajectory = generator.generate_trajectory_from_cspace_waypoints(
    waypoints=[[0, 0, 0], [1, 1, 1], [2, 2, 2]]
)

Generate a trajectory from configuration space waypoints.

Creates a smooth time-optimal trajectory passing through the specified joint configuration waypoints. Optionally, specific timing for each waypoint can be provided, or an interpolation mode can be specified.

Parameters:

waypoints – Array of joint configurations, shape (n_waypoints, n_joints).
times – Optional time stamps for each waypoint. Defaults to None (automatic timing).
interpolation_mode – Interpolation method to use. Defaults to None (cuMotion default).

Returns:

Generated trajectory, or None if generation failed.

Raises:

RuntimeError – If waypoints is not two-dimensional.
RuntimeError – If fewer than 2 waypoints are provided.
RuntimeError – If waypoint dimension doesn’t match the number of controlled joints.
RuntimeError – If times is not one-dimensional.
RuntimeError – If the number of times doesn’t match the number of waypoints.
RuntimeError – If any time value is negative.
RuntimeError – If times are not strictly increasing.

Example

waypoints = [[0.0, -0.5, 0.0], [0.5, 0.0, 0.5], [1.0, 0.5, 1.0]]
trajectory = generator.generate_trajectory_from_cspace_waypoints(waypoints)

# With explicit timing
waypoints = [[0, 0], [1, 1], [2, 2]]
times = [0.0, 1.0, 2.0]
trajectory = generator.generate_trajectory_from_cspace_waypoints(
    waypoints, times
)

generate_trajectory_from_path_specification( path_specification: CSpacePathSpec | TaskSpacePathSpec | CompositePathSpec, tool_frame_name: str | None = None, task_space_conversion_config: TaskSpacePathConversionConfig | None = None, inverse_kinematics_config: IkConfig | None = None, ) → CumotionTrajectory | None#

Generate a trajectory from a cuMotion path specification.

Converts the provided path specification (which may be in configuration space, task space, or composite) into a smooth time-optimal trajectory (not collision-aware). Task space paths are converted to configuration space using inverse kinematics.

Parameters:

path_specification – Path specification in cuMotion format (defined in base frame).
tool_frame_name – Name of the tool frame for task space planning. Defaults to None, which uses the first tool frame in the robot description.
task_space_conversion_config – Configuration for task space to configuration space conversion. Defaults to None.
inverse_kinematics_config – Configuration for inverse kinematics solver. Defaults to None.

Returns:

Generated trajectory, or None if generation failed.

Raises:

RuntimeError – If the path specification has fewer than 2 waypoints.

Example

path_spec = cumotion.create_cspace_path_spec(
    initial_cspace_position=np.array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]),
)
path_spec.add_cspace_waypoint(np.array([1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]))
path_spec.add_cspace_waypoint(np.array([2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0]))
trajectory = generator.generate_trajectory_from_path_specification(path_spec)

get_cspace_trajectory_generator() → CSpaceTrajectoryGenerator#

Get the underlying cuMotion trajectory generator.

Returns the cuMotion generator object, allowing users to modify parameters directly.

Returns:: The cuMotion configuration space trajectory generator.

Example

gen = generator.get_cspace_trajectory_generator()
gen.set_velocity_limits(np.array([0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]))

class TrajectoryOptimizer( cumotion_robot: CumotionRobot, robot_joint_space: list[str], cumotion_world_interface: CumotionWorldInterface, tool_frame: str | None = None, trajectory_optimizer_config_filename: Path | str | None = None, )#

Bases: object

Trajectory optimizer using cuMotion’s Trajectory Optimizer algorithm.

This class provides trajectory optimization capabilities. It generates smooth, collision-free trajectories to configuration space or task space targets by optimizing over trajectory costs including smoothness, collision avoidance, and goal achievement.

Parameters:

cumotion_robot – Robot configuration containing kinematics and joint information.
robot_joint_space – List of joint names defining the robot’s joint space.
cumotion_world_interface – World interface providing collision geometry.
tool_frame – Name of the tool frame for task space planning. Defaults to None, which uses the first tool frame defined in the robot description.
trajectory_optimizer_config_filename – Path to the YAML configuration file. If a relative path is provided, it is resolved relative to cumotion_robot.directory. If an absolute path is provided, it is used as-is. Defaults to None (uses default parameters).

Example

optimizer = TrajectoryOptimizer(
    cumotion_robot=robot_config,
    robot_joint_space=joint_names,
    cumotion_world_interface=world_interface,
)
# See cuMotion documentation for creating target specifications
trajectory = optimizer.plan_to_goal(q_initial, cspace_target)

get_cumotion_robot() → CumotionRobot#

Get the robot configuration.

Returns:: The robot configuration used by this optimizer.

get_trajectory_optimizer_config() → TrajectoryOptimizerConfig#

Get the trajectory optimizer configuration.

Returns the underlying cuMotion configuration object, allowing users to modify optimizer parameters before planning.

Returns:: The cuMotion trajectory optimizer configuration object.

Example

config = optimizer.get_trajectory_optimizer_config()
config.set_param("trajopt/pbo/num_iterations", cumotion.TrajectoryOptimizerConfig.ParamValue(100))

Plan a trajectory to a specified goal.

Generates a smooth, collision-free trajectory from the initial configuration to the specified goal. The goal can be a configuration space target, task space target, or task space goalset.

Parameters:

initial_cspace_position – Initial joint configuration.
goal – Target goal specification (CSpaceTarget, TaskSpaceTarget, or TaskSpaceTargetGoalset). Note that all goals must be defined in the base frame.

Returns:

Optimized trajectory if successful, None if planning failed.

Raises:

ValueError – If goal type is not one of the supported types.

Example

# Configuration space target
q_initial = [0.0, -0.5, 0.0, -2.0, 0.0, 1.5, 0.75]
# See cuMotion documentation for constructing CSpaceTarget,
# TaskSpaceTarget, or TaskSpaceTargetGoalset objects
trajectory = optimizer.plan_to_goal(q_initial, target)

class CumotionTrajectory( trajectory: Trajectory, robot_joint_space: list[str], cumotion_robot: CumotionRobot, device: Device | None = None, )#

Bases: Trajectory

Continuous-time trajectory for a robot using cuMotion.

This class wraps a cuMotion trajectory and provides the Isaac Sim trajectory interface for querying robot states at specific times. All trajectories start at time 0.0 and end after their duration.

Parameters:

trajectory – cuMotion trajectory object.
robot_joint_space – List of robot joint names in the joint space.
cumotion_robot – Robot configuration containing joint names and descriptions.
device – Warp device for computation. Defaults to None.

Raises:

ValueError – If cuMotion active joints are not a subset of the robot_joint_space.

Example

trajectory = CumotionTrajectory(
    trajectory=cumotion_traj,
    robot_joint_space=joint_names,
    cumotion_robot=robot_config
)
state = trajectory.get_target_state(time=1.0)

get_active_joints() → list[str]#

Get the list of controlled joint names.

Returns:: List of joint names that are controlled in this trajectory.

get_target_state( time: float, ) → RobotState | None#

Get the target robot state at a specified time.

Returns joint positions and velocities for the robot at the given time along the trajectory. If the time is outside the trajectory domain, None is returned.

Parameters:: time – Time in trajectory at which to return joint targets.
Returns:: Robot state containing joint positions and velocities, or None if time is outside the trajectory domain.

Example:

state = trajectory.get_target_state(time=2.5)
if state is not None:
    print(state.joints.positions)

property duration: float#

Get the duration of the trajectory.

Returns:: Duration of the trajectory in seconds.

Transform Utilities#

The transform utilities provide coordinate conversion between Isaac Sim world frame and cuMotion robot base frame.

Convert Isaac Sim pose to cuMotion pose in the robot base frame.

Transforms a pose from Isaac Sim world frame to cuMotion’s robot base frame. If base frame transform is not provided, returns the pose in world frame.

Parameters:

position_world_to_target – Target position in world frame [x, y, z].
orientation_world_to_target – Target orientation in world frame as quaternion [w, x, y, z].
position_world_to_base – Robot base position in world frame.
orientation_world_to_base – Robot base orientation in world frame as quaternion [w, x, y, z].

Returns:

cuMotion Pose3 object representing the target pose in robot base frame.

Example

pose = isaac_sim_to_cumotion_pose(
    position_world_to_target=[1.0, 2.0, 3.0],
    orientation_world_to_target=[1.0, 0.0, 0.0, 0.0],
    position_world_to_base=[0.5, 0.5, 0.0],
    orientation_world_to_base=[1.0, 0.0, 0.0, 0.0]
)

Convert Isaac Sim position to cuMotion position in robot base frame.

Transforms a position vector from Isaac Sim world frame to cuMotion’s robot base frame.

Parameters:

position_world_to_target – Target position in world frame [x, y, z].
position_world_to_base – Robot base position in world frame.
orientation_world_to_base – Robot base orientation in world frame as quaternion [w, x, y, z].

Returns:

Position vector in robot base frame as numpy array of shape (3,).

Raises:

ValueError – If position_world_to_target is not size 3.

Example

position_base = isaac_sim_to_cumotion_translation(
    position_world_to_target=[1.0, 2.0, 3.0],
    position_world_to_base=[0.5, 0.5, 0.0],
    orientation_world_to_base=[1.0, 0.0, 0.0, 0.0]
)

Convert Isaac Sim orientation to cuMotion rotation in robot base frame.

Transforms an orientation from Isaac Sim world frame to cuMotion’s robot base frame.

Parameters:

orientation_world_to_target – Target orientation in world frame as quaternion [w, x, y, z].
orientation_world_to_base – Robot base orientation in world frame as quaternion [w, x, y, z].

Returns:

cuMotion Rotation3 object representing the orientation in robot base frame.

Raises:

ValueError – If orientation is not size 4.

Example

rotation_base = isaac_sim_to_cumotion_rotation(
    orientation_world_to_target=[1.0, 0.0, 0.0, 0.0],
    orientation_world_to_base=[1.0, 0.0, 0.0, 0.0]
)

Convert cuMotion pose in base frame to Isaac Sim pose in world frame.

Transforms a pose from cuMotion’s robot base frame to Isaac Sim world frame. If base frame transform is not provided, assumes identity transform.

Parameters:

pose_base_to_target – Target pose in robot base frame.
position_world_to_base – Robot base position in world frame.
orientation_world_to_base – Robot base orientation in world frame as quaternion [w, x, y, z].

Returns:

Tuple of (position, quaternion) as warp arrays where position has shape (3,): and quaternion has shape (4,) in (w, x, y, z) format.

Example

position, quaternion = cumotion_to_isaac_sim_pose(
    pose_base_to_target,
    position_world_to_base=[0.5, 0.5, 0.0],
    orientation_world_to_base=[1.0, 0.0, 0.0, 0.0]
)

Convert cuMotion position to Isaac Sim position in world frame.

Transforms a position vector from cuMotion’s robot base frame to Isaac Sim world frame.

Parameters:

position_base_to_target – Target position in robot base frame [x, y, z].
position_world_to_base – Robot base position in world frame.
orientation_world_to_base – Robot base orientation in world frame as quaternion [w, x, y, z].

Returns:

Position vector in world frame as warp array of shape (3,).

Raises:

ValueError – If position_base_to_target is not size 3.

Example

position_world = cumotion_to_isaac_sim_translation(
    position_base_to_target=np.array([0.5, 1.0, 0.5]),
    position_world_to_base=[0.5, 0.5, 0.0],
    orientation_world_to_base=[1.0, 0.0, 0.0, 0.0]
)

Convert cuMotion rotation to Isaac Sim orientation in world frame.

Transforms an orientation from cuMotion’s robot base frame to Isaac Sim world frame.

Parameters:

orientation_base_to_target – Target orientation in robot base frame.
position_world_to_base – Robot base position in world frame (unused, kept for consistency).
orientation_world_to_base – Robot base orientation in world frame as quaternion [w, x, y, z].

Returns:

Orientation as warp array quaternion [w, x, y, z] of shape (4,).

Example

quaternion = cumotion_to_isaac_sim_rotation(
    orientation_base_to_target,
    orientation_world_to_base=[1.0, 0.0, 0.0, 0.0]
)

Python API

[isaacsim.robot_motion.cumotion] cumotion#

Overview#

Concepts#

cuMotion Integration#

Robot Configuration#

Key Components#

CumotionRobot#

CumotionWorldInterface#

Motion Planners#

Controllers and Generators#

CumotionTrajectory#

Integration#

Enable Extension#

Python API#

Configuration Loading#

World Interface#

Motion Policies#

Motion Planning#

Trajectory Generation#

Transform Utilities#

`CumotionRobot`#

`CumotionWorldInterface`#

`CumotionTrajectory`#