Python API

Classes

RobotPoser	High-level IK controller bound to a specific robot.
PoseResult	Result of an IK solve or named-pose query.
KinematicChain	A cached kinematic chain between two robot links.
Transform	Rigid SE(3) transform (translation and quaternion rotation).
Joint	Single joint in a kinematic chain (screw axis and home pose).
IKSolver	Abstract base class for inverse-kinematics solvers.
IKSolverRegistry	Global registry of IK solver implementations.
IKSolverLM	Levenberg-Marquardt IK solver implementing the IKSolver interface.

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.
pose_error	Compute 6-DOF pose error between desired and actual transforms.
ik_lm	Solve IK using Levenberg-Marquardt with optional null-space bias.

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] | PoseResult,

) → 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 – Either a mapping of joint prim path to value (radians or meters), or a PoseResult. When a PoseResult with success=False is passed, the call is a no-op and a warning is logged: failed solves carry the lowest-error attempt across the cold-start ladder, which may be a random-restart configuration, and applying it would teleport the robot to an arbitrary pose.

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: Any,

) → PoseResult

Solve inverse kinematics for the configured chain.

Seeding strategy

The candidates the solver is started from depend on what the caller provides:

• seed=... (explicit caller-supplied seed): exactly one solve attempt from the given configuration. Lowest latency; recommended on hot paths.

• No seed= and a cached _last_solution: the cached configuration is tried first (lowest latency for tracking targets near the previous solve). If that attempt does not converge, the full cold-start ladder is run in parallel as a fallback so a stale cache cannot trap the solver in the wrong basin.

• No seed= and no cached solution: the full cold-start ladder (joint-limit midpoint, deterministic random restarts within joint limits, and the all-zero configuration) runs in parallel via a thread pool. The highest-priority converged result wins.

On every path, when no candidate converges the lowest-error attempt is returned with success=False and a single warning is logged recommending an explicit seed=.

Parallel ladder execution

Cold-start (and _last_solution fallback) ladders run candidate seeds concurrently on a ThreadPoolExecutor. The LM solver in this project is stateless and chain.compute_fk does not mutate the chain, so the only shared mutable state across attempts is the result aggregation, which happens after the threads join. The latency of a cold-start ladder is therefore bounded by the slowest single solve, not by the sum of all attempts.

param target:

Desired end-effector pose in the robot-base frame.

param seed:

Initial joint-value guess. When None, uses the last successful solution (with cold-start fallback) if available, otherwise runs the cold-start ladder directly.

param tolerance:

Convergence threshold on the pose-error norm.

param **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. On failure the joints field still contains the lowest-error attempt so callers can inspect or visualize near-misses; callers must gate calls to apply_pose() on success to avoid teleporting the robot to a random-restart configuration.

property chain: KinematicChain | None

Get the underlying KinematicChain, or None.

property end_prim: Usd.Prim | None

End prim of the current IK chain, or None.

property joints: list

Copy the internal joint chain.

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

class KinematicChain(

stage: Any,

robot_prim: Any,

start_prim: Any = None,

end_prim: Any = None,

*,

debug: bool = False,

)

Bases: object

A cached kinematic chain between two robot links.

Builds the kinematic tree once at construction and optionally builds the joint chain when start/end prims are provided. When constructed with only stage and robot_prim, the cached tree is available for teleport operations without IK.

Parameters:

• stage – USD stage containing the robot.

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

• start_prim – Chain start link or site prim. Optional.

• end_prim – Chain end link or site prim. Optional.

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

compute_fk(

q: ndarray,

*,

debug: bool = False,

) → tuple[Transform, list[Transform]]

Compute end-effector FK for joint configuration q.

Parameters:

• q – Joint values in chain order (radians / meters).

• debug – Print per-joint FK trace when True.

Returns:

(end_effector_transform, per_joint_transforms) in chain-local frame.

compute_fk_and_jacobian(

q: ndarray,

) → tuple[Transform, ndarray]

Compute end-effector FK and spatial Jacobian for joint configuration q.

Fused single-pass implementation; joint exponentials evaluated once.

Parameters:

q – Joint values in chain order (radians / meters).

Returns:

(end_effector_transform, 6×N_jacobian) in chain-local frame.

read_joint_states() → dict[str, float]

Read current USD state for the chain joints only (radians / meters).

Uses the cached kinematic tree — no tree rebuild.

Returns:

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

set_joint_attributes(

joint_dict: dict[str, float],

) → None

Write drive-target and physics-state attributes for the given joints.

Parameters:

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

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

Apply joint_dict by propagating FK body transforms.

Uses the cached kinematic tree — no tree rebuild. Use when simulation is stopped.

Parameters:

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

teleport_anchored(

joint_dict: dict[str, float],

*,

anchor_prim: Any = None,

) → None

Apply joint_dict keeping a fixed prim’s world position unchanged.

Merges joint_dict with the current USD state for all robot joints, propagates FK, then rigidly corrects the robot so the anchor prim returns to its original world position. Necessary when the chain contains backward (child-to-parent) joints.

Uses the cached kinematic tree — no tree rebuild. Use when simulation is stopped.

Parameters:

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

• anchor_prim – Prim to hold fixed. Defaults to start_prim.

property end_prim: Any

Chain end prim.

property joints: list[Joint]

Ordered joint chain (copy).

property robot_prim: Any

Robot root prim.

property stage: Any

USD stage.

property start_prim: Any

Chain start prim.

property tree_root: Any

Cached kinematic tree root (from GenerateRobotLinkTree).

class Transform(

t: ndarray | None = None,

q: ndarray | None = None,

)

Bases: object

Rigid SE(3) transform (translation and quaternion rotation).

Parameters:

• t – Translation [x, y, z]. Defaults to zeros.

• q – Quaternion [w, x, y, z]. Defaults to identity.

inv() → Transform

Return the inverse transform.

Returns:

Inverse of this transform.

q: ndarray

t: ndarray

class Joint(

w: ndarray,

v: ndarray,

home: Transform,

prim_path: str = '',

tip: Transform | None = None,

lower: float = -inf,

upper: float = inf,

forward: bool = True,

is_revolute: bool = True,

)

Bases: object

Single joint in a kinematic chain (screw axis and home pose).

exp(q: float) → Transform

Exponential map: joint value to relative transform.

Parameters:

q – Joint value (radians for revolute, meters for prismatic).

Returns:

Relative transform from parent to child.

forward: bool = True

home: Transform

is_revolute: bool = True

lower: float = -inf

prim_path: str = ''

tip: Transform | None = None

upper: float = inf

v: ndarray

w: ndarray

class IKSolver

Bases: ABC

Abstract base class for inverse-kinematics solvers.

Subclasses must implement solve(). Solver-specific parameters (damping, iteration count, etc.) are passed as keyword arguments.

abstract solve(

chain: KinematicChain,

target: Transform,

q0: VecN | None = None,

**kwargs: Any,

) → VecN

Solve IK for the given kinematic chain.

Parameters:

• chain – Kinematic chain providing joints and FK computation.

• target – Desired end-effector pose in chain-local coordinates.

• q0 – Initial joint configuration guess. When None the solver must start from the zero configuration.

• **kwargs – Solver-specific parameters.

Returns:

Joint values that (approximately) achieve the target.

class IKSolverRegistry

Bases: object

Global registry of IK solver implementations.

Solvers register themselves via register() (typically at module import time). Consumers obtain instances via get().

classmethod available() → list[str]

Return the names of all registered solvers.

Returns:

List of registered solver names.

classmethod default_name() → str

Return the name of the default solver.

Returns:

Default solver name.

classmethod get(

name: str | None = None,

) → IKSolver

Return a new instance of the solver registered under the given name.

Parameters:

name – Registry key, or None for the default solver.

Returns:

New solver instance.

Raises:

KeyError – When the requested solver name is not registered.

classmethod register(

name: str,

solver_cls: type[IKSolver],

*,

default: bool = False,

) → None

Register an IK solver class under the given name.

Parameters:

• name – Registry key for the solver.

• solver_cls – Solver class to register.

• default – If True, use as the default solver when name is None.

class IKSolverLM

Bases: IKSolver

Levenberg-Marquardt IK solver implementing the IKSolver interface.

Solver-specific keyword arguments accepted by solve():

• lam (float): LM damping factor (default 1e-3).

• iters (int): maximum iterations (default 30).

• tol (float): internal convergence tolerance (default 1e-6).

• w_rot (float): rotation error weight (default 1.0).

• w_pos (float): position error weight (default 1.0).

• max_step (float): maximum step magnitude (default 0.5).

• null_space_bias (float): null-space joint centering (default 0.05).

• joint_fixed (array-like of bool, optional): mask of chain length; True locks that DOF (Jacobian column set to zero and step zeroed).

solve(

chain: KinematicChain,

target: Transform,

q0: ndarray | None = None,

**kwargs: Any,

) → ndarray

Solve IK for the given kinematic chain. See class docstring for kwargs.

Parameters:

• chain – Kinematic chain providing joints and FK computation.

• target – Desired end-effector pose in chain-local coordinates.

• q0 – Initial joint configuration, or None for zero.

• **kwargs – Solver options (lam, iters, tol, w_rot, w_pos, etc.).

Returns:

Joint values that achieve the target.

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.

pose_name is sanitized to a valid USD identifier via pxr.Tf.MakeValidIdentifier() before use. Distinct inputs that sanitize to the same identifier (for example "home:v2" and "home/v2") refer to the same stored pose; this function logs a warning and overwrites the existing prim in that case.

Parameters:

• stage – USD stage.

• robot_prim – Robot root prim.

• pose_name – Human-readable name for the pose. Sanitized as described above before being used as a USD prim name.

• 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. Sanitized to a valid USD identifier using the same rules as store_named_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. Sanitized to a valid USD identifier using the same rules as store_named_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. Sanitized to a valid USD identifier using the same rules as store_named_pose().

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.

pose_error(

Td: Transform,

T: Transform,

) → ndarray

Compute 6-DOF pose error between desired and actual transforms.

Parameters:

• Td – Desired end-effector transform.

• T – Actual (current) transform.

Returns:

6-vector [rot_x, rot_y, rot_z, pos_x, pos_y, pos_z].

ik_lm(

chain: KinematicChain,

q0: ndarray,

target: Transform,

lam: float = 0.001,

iters: int = 30,

tol: float = 1e-06,

w_rot: float = 1.0,

w_pos: float = 1.0,

max_step: float = 0.5,

base_frame: Transform | None = None,

null_space_bias: float = 0.05,

joint_fixed: list[bool] | ndarray | None = None,

) → ndarray

Solve IK using Levenberg-Marquardt with optional null-space bias.

When a base_frame is provided the caller’s target is in robot-base frame but the FK chain is relative to base_frame (the start-site zero-config pose). Express the target in chain-local coordinates so the solver compares like with like.

Parameters:

• chain – Kinematic chain providing joints and FK computation.

• q0 – Initial joint configuration.

• target – Desired end-effector pose in chain-local coordinates.

• lam – Levenberg-Marquardt damping factor.

• iters – Maximum iterations.

• tol – Convergence tolerance on weighted cost.

• w_rot – Rotation weight in cost (x3 for rot components).

• w_pos – Position weight in cost (x3 for pos components).

• max_step – Maximum joint step per iteration.

• base_frame – If set, target is expressed in this frame.

• null_space_bias – Bias toward joint mid-range in null space.

• joint_fixed – Mask of fixed (locked) joints.

Returns:

Joint values that (approximately) achieve the target.