API

Python API

Classes

RobotPoser	High-level IK controller bound to a specific robot.
PoseResult	Result of an IK solve or named-pose query.

Functions

validate_robot_schema	Return True if robot_prim carries the IsaacRobotAPI schema.
apply_joint_state	Apply a joint-state dictionary to the robot.
apply_joint_state_anchored	Apply a joint-state dictionary, keeping anchor_prim fixed.
store_named_pose	Store a named pose in the robot asset.
apply_pose_by_name	Apply a previously stored named pose.
get_named_pose	Retrieve a named pose from the robot asset.
list_named_poses	Return the names of all named poses registered on robot_prim.
delete_named_pose	Remove a named pose from the robot asset.
export_poses	Export all named poses on robot_prim to a JSON file.
import_poses	Import named poses from a JSON file and store them on robot_prim.

Classes

class RobotPoser(

stage: Usd.Stage,

robot_prim: Usd.Prim,

start_prim: Usd.Prim | None = None,

end_prim: Usd.Prim | None = None,

solver_name: str | None = None,

*,

debug: bool = False,

)

Bases: object

High-level IK controller bound to a specific robot.

Wraps a KinematicChain (which owns the joint chain, kinematic tree, and FK/USD I/O) and adds IK solving, solution seeding, and unit conversion on top.

Construct with a Usd.Stage and robot prim, optionally providing start/end prims to configure the kinematic chain immediately. The chain can be switched at any time via set_chain(). Once configured, solve_ik() only requires a target transform and optional solver keyword arguments.

Parameters:

• stage – USD stage containing the robot.

• robot_prim – Robot root prim (must carry IsaacRobotAPI).

• start_prim – Start of the IK chain. Optional.

• end_prim – End of the IK chain. Optional.

• solver_name – Name of the registered IK solver. Defaults to registry default.

• debug – Enable verbose debug output for chain building and FK.

apply_pose(joint_dict: dict[str, float]) → None

Apply joint values to the robot, anchoring at the start link.

For chains that include backward (child-to-parent) joints the standard root-anchored teleport would move the start link. This method applies the joints and then rigidly corrects the entire robot so the start link remains at its original world position. During simulation delegates to _drive_robot directly.

Parameters:

joint_dict – Mapping of joint prim path to value (radians or meters).

classmethod apply_pose_by_target(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

start_prim: pxr.Usd.Prim,

end_prim: pxr.Usd.Prim,

target: Transform,

seed: ndarray | None = None,

) → PoseResult

Solve IK and immediately apply the result to the robot.

Constructs a RobotPoser, solves IK, and applies the solution in a single call — reusing the same kinematic chain for both operations.

Parameters:

• stage – USD stage containing the robot.

• robot_prim – Robot root prim (must carry IsaacRobotAPI).

• start_prim – Start of the IK chain (link or site).

• end_prim – End of the IK chain (link or site).

• target – Desired end-effector pose in robot-base frame.

• seed – Initial joint guess, or None for zero.

Returns:

PoseResult with success, joints, and target info.

joints_to_native_values(

joint_dict: dict[str, float],

) → list[float]

Convert a joint dict (radians) to native USD units.

Revolute joints are converted to degrees; prismatic joints are left unchanged. Values are returned in joint-chain order.

Parameters:

joint_dict – Mapping of joint prim path to value in radians (or meters).

Returns:

Values in joint-chain order (degrees for revolute, meters for prismatic).

set_chain(

start_prim: pxr.Usd.Prim,

end_prim: pxr.Usd.Prim,

) → None

Set or switch the kinematic chain.

Builds a new KinematicChain and resets the solution seed.

Parameters:

• start_prim – Start of the IK chain (link or site).

• end_prim – End of the IK chain (link or site).

set_seed(

seed: dict[str, float] | ndarray | list[float] | None,

) → None

Set the solution seed for the next solve_ik call.

Parameters:

seed – When a dict, maps joint prim paths to values (as in PoseResult.joints). When array-like, values are in joint-chain order. None clears the seed.

solve_ik(

target: Transform,

seed: dict[str, float] | ndarray | list[float] | None = None,

*,

tolerance: float = 0.0001,

**solver_kwargs,

) → PoseResult

Solve inverse kinematics for the configured chain.

Parameters:

• target – Desired end-effector pose in the robot-base frame.

• seed – Initial joint-value guess. When None, uses the last successful solution or zeros.

• tolerance – Convergence threshold on the pose-error norm.

• **solver_kwargs – Forwarded to the IK solver (e.g. lam, iters, null_space_bias, joint_fixed). joint_fixed can be a dict mapping joint prim path to bool to lock DOFs.

Returns:

PoseResult with success, joints, and target info.

property chain: KinematicChain | None

The underlying KinematicChain, or None.

property end_prim: Usd.Prim | None

End prim of the current IK chain, or None.

property joints: list

Copy of the internal joint chain (list of Joint).

property robot_prim: pxr.Usd.Prim

The robot root prim.

property solver: IKSolver

The active IKSolver instance.

property stage: pxr.Usd.Stage

The USD stage.

property start_prim: Usd.Prim | None

Start prim of the current IK chain, or None.

class PoseResult(

success: bool,

joints: dict[str,

float] = <factory>,

joint_fixed: dict[str,

bool] = <factory>,

start_link: str = '',

end_link: str = '',

target_position: list[float] | None = None,

target_orientation: list[float] | None = None,

)

Bases: object

Result of an IK solve or named-pose query.

Parameters:

• success – Whether the IK solve converged or the stored pose is valid.

• joints – Mapping of joint prim path to joint value (radians for revolute, meters for prismatic).

• joint_fixed – Mapping of joint prim path to fixed flag. False for every movable joint in the chain.

• start_link – Prim path of the chain start link.

• end_link – Prim path of the chain end link / site.

• target_position – Target position [x, y, z] in robot-base frame.

• target_orientation – Target orientation [w, x, y, z] quaternion in robot-base frame.

end_link: str = ''

joint_fixed: dict[str, bool]

joints: dict[str, float]

start_link: str = ''

success: bool

target_orientation: list[float] | None = None

target_position: list[float] | None = None

Functions

validate_robot_schema(robot_prim: pxr.Usd.Prim) → bool

Return True if robot_prim carries the IsaacRobotAPI schema.

Parameters:

robot_prim – Robot root USD prim to check.

Returns:

True if the prim has IsaacRobotAPI.

apply_joint_state(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

joint_dict: dict[str, float],

) → None

Apply a joint-state dictionary to the robot.

When simulation is stopped, teleports via FK and joint attributes. When simulation is running, sends DOF targets via Articulation.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim (must carry IsaacRobotAPI).

• joint_dict – Joint prim path to value (radians or meters).

apply_joint_state_anchored(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

joint_dict: dict[str, float],

anchor_prim: pxr.Usd.Prim,

) → None

Apply a joint-state dictionary, keeping anchor_prim fixed.

Like apply_joint_state but rigidly corrects so anchor_prim stays at its original world position. During simulation sends DOF targets directly.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

• joint_dict – Joint prim path to value (radians or meters).

• anchor_prim – Prim to keep fixed.

store_named_pose(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

pose_name: str,

pose_result: PoseResult,

) → bool

Store a named pose in the robot asset.

Creates an IsaacNamedPose prim under Named_Poses and registers it in the robot’s namedPoses relationship. The prim’s Xform is set to the end-link target pose.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

• pose_name – Human-readable name for the pose.

• pose_result – Must have success=True.

Returns:

True when the pose was persisted.

apply_pose_by_name(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

pose_name: str,

) → bool

Apply a previously stored named pose.

Teleports when simulation is stopped, drives via joint targets when running.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

• pose_name – Name of the stored pose.

Returns:

True if the pose was found and applied.

get_named_pose(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

pose_name: str,

) → PoseResult | None

Retrieve a named pose from the robot asset.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

• pose_name – Name of the stored pose.

Returns:

PoseResult, or None when no pose with that name exists.

list_named_poses(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

) → list[str]

Return the names of all named poses registered on robot_prim.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

Returns:

List of pose names.

delete_named_pose(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

pose_name: str,

) → bool

Remove a named pose from the robot asset.

Deletes the IsaacNamedPose prim and removes it from namedPoses.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

• pose_name – Name of the pose to remove.

Returns:

True when the pose existed and was removed.

export_poses(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

filepath: str,

*,

degrees: bool = False,

) → bool

Export all named poses on robot_prim to a JSON file.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

• filepath – Destination file path.

• degrees – If True, revolute joint values are written in degrees (native USD units) instead of the default radians.

Returns:

True on success.

import_poses(

stage: pxr.Usd.Stage,

robot_prim: pxr.Usd.Prim,

filepath: str,

) → int

Import named poses from a JSON file and store them on robot_prim.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

• filepath – Source file path (as written by export_poses).

Returns:

Number of poses successfully imported.