API#

Python API#

Note

Entries and autoclass/autofunction directives in all sections below are ordered by name.

controllers

`AckermannController`	Ackermann steering controller using a bicycle model.
`DifferentialController`	Unicycle differential drive controller.
`HolonomicController`	QP-based holonomic controller for mecanum-wheeled robots.

robots

`HolonomicRobotUsdSetup`	Read holonomic (mecanum) robot parameters from USD for use with HolonomicController.
`WheeledRobot`	Wheeled robot wrapper built on the experimental Articulation API.

utilities (controllers)

`pid_control`	Compute proportional control output for speed tracking.
`QuinticPolynomial`	Quintic (5th-order) polynomial for one-dimensional trajectory interpolation.
`quintic_polynomials_planner`	Plan a trajectory using quintic polynomials between start and goal states.
`stanley_control`	Compute the Stanley steering control output.

Controllers#

class AckermannController( *, wheel_base: float, track_width: float, front_wheel_radius: float = 0.0, back_wheel_radius: float = 0.0, max_wheel_velocity: float = 0.0, invert_steering: bool = False, max_wheel_rotation_angle: float = 6.28, max_acceleration: float = 0.0, max_steering_angle_velocity: float = 0.0, )#

Bases: object

Ackermann steering controller using a bicycle model.

Computes left and right steering angles and per-wheel rotation velocities for a four-wheel Ackermann robot. Returns plain tuples (no ArticulationAction).

Parameters:

wheel_base – Distance between front and rear axles in m.
track_width – Distance between left and right wheels in m.
front_wheel_radius – Radius of front wheels in m.
back_wheel_radius – Radius of back wheels in m.
max_wheel_velocity – Maximum angular velocity of wheels in rad/s. Ignored if 0.
invert_steering – True for rear wheel steering.
max_wheel_rotation_angle – Maximum steering angle in rad. Ignored if 0.
max_acceleration – Maximum linear acceleration in m/s^2. Ignored if 0.
max_steering_angle_velocity – Maximum steering rate in rad/s. Ignored if 0.

forward( command: ndarray, ) → tuple[tuple[float, float] | None, tuple[float, float, float, float] | None]#

Compute wheel angles and wheel rotation velocities from an Ackermann command.

Parameters:: command – Length 5 — [steering_angle (rad), steering_angle_velocity (rad/s), speed (m/s), acceleration (m/s^2), dt (s)].
Returns:: Tuple of (joint_positions, joint_velocities). joint_positions is (left_wheel_angle, right_wheel_angle); joint_velocities is (v_FL, v_FR, v_BL, v_BR). Returns (None, None) on invalid input.

class DifferentialController( *, wheel_radius: float, wheel_base: float, max_linear_speed: float = 1e+20, max_angular_speed: float = 1e+20, max_wheel_speed: float = 1e+20, )#

Bases: object

Unicycle differential drive controller.

Convert [linear_speed, angular_speed] commands into [left, right] wheel velocities using the standard differential-drive kinematic model.

Parameters:

wheel_radius – Radius of each drive wheel in m.
wheel_base – Distance between left and right wheels in m.
max_linear_speed – Maximum forward/backward speed in m/s.
max_angular_speed – Maximum yaw rate in rad/s.
max_wheel_speed – Maximum individual wheel angular velocity in rad/s.

Raises:

ValueError – If any speed limit is negative.

forward( command: ndarray, ) → ndarray#

Convert [linear_speed, angular_speed] to [left_wheel, right_wheel] velocities.

Parameters:: command – Shape (2,) — [forward speed, angular speed].
Returns:: Shape (2,) — [left wheel velocity, right wheel velocity].
Raises:: ValueError – If command does not have length 2.

Bases: object

QP-based holonomic controller for mecanum-wheeled robots.

Convert [forward, lateral, yaw] velocity commands into per-wheel angular velocities by solving a quadratic program.

Parameters:

wheel_radius – Radius of each wheel (scalar broadcast to all wheels, or per-wheel array).
wheel_positions – Positions of each wheel relative to the robot center, shape (N, 3).
wheel_orientations – Quaternion orientations of each wheel, shape (N, 4) as [w, x, y, z].
mecanum_angles – Mecanum roller angles in degrees for each wheel.
wheel_axis – Local rotation axis of the wheel joint.
up_axis – Up direction of the robot frame.
max_linear_speed – Maximum linear speed in m/s.
max_angular_speed – Maximum angular speed in rad/s.
max_wheel_speed – Maximum individual wheel speed in rad/s.
linear_gain – Gain applied to the linear velocity command.
angular_gain – Gain applied to the angular velocity command.

forward(command: ndarray) → ndarray#

Compute wheel velocities from [forward, lateral, yaw] command.

Parameters:: command – Shape (3,) — [forward speed, lateral speed, yaw speed].
Returns:: Shape (num_wheels,) — wheel joint velocities.
Raises:: ValueError – If command does not have length 3.

Robots#

class HolonomicRobotUsdSetup(robot_prim_path: str, com_prim_path: str)#

Bases: object

Read holonomic (mecanum) robot parameters from USD for use with HolonomicController.

Parameters:

robot_prim_path – USD path to the robot articulation root prim.
com_prim_path – USD path to the center-of-mass reference prim.

get_articulation_controller_params() → list[str]#

Return the DOF names for the mecanum wheel joints.

Returns:: List of wheel joint DOF name strings.

get_holonomic_controller_params() → tuple[list, ndarray, ndarray, list, ndarray, ndarray]#

Return parameters needed to construct a HolonomicController.

Returns:: Tuple of (wheel_radius, wheel_positions, wheel_orientations, mecanum_angles, wheel_axis, up_axis).

Bases: Articulation

Wheeled robot wrapper built on the experimental Articulation API.

Parameters:

paths – USD prim path for the robot articulation.
wheel_dof_names – Joint names identifying the wheel DOFs.
wheel_dof_indices – Joint indices identifying the wheel DOFs.
usd_path – Optional USD asset path to reference onto the stage.
positions – Initial world position(s) as [x, y, z].
orientations – Initial world orientation(s) as [w, x, y, z] quaternion.

Apply visual materials to the prims, and optionally, to their descendants.

Backends: usd.

Parameters:

visual_materials – Visual materials to be applied to the prims (shape (N,)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
weaker_than_descendants – Boolean flags to indicate whether descendant materials should be overridden (shape (N, 1)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> from isaacsim.core.experimental.materials import OmniGlassMaterial
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlassMaterial("/World/material/glass")
>>> material.set_input_values("glass_ior", [1.25])
>>> material.set_input_values("depth", [0.001])
>>> material.set_input_values("thin_walled", [False])
>>> material.set_input_values("glass_color", [0.5, 0.0, 0.0])
>>>
>>> prims.apply_visual_materials(material)

apply_wheel_actions(velocities: ndarray) → None#

Apply angular velocity targets to the wheel joints.

Parameters:: velocities – Target angular velocities, one per wheel.
Raises:: ValueError – If the length of velocities does not match the number of wheels.

static ensure_api(

prims: list[Usd.Prim],

api: type,

*args,

**kwargs,

) → list[type['UsdAPISchemaBase']]#

Ensure that all prims have the specified API schema applied.

Backends: usd.

If a prim doesn’t have the API schema, it will be applied. If it already has it, the existing API schema will be returned.

Parameters:

prims – List of USD Prims to ensure API schema on.
api – The API schema type to ensure.
*args – Additional positional arguments passed to API schema when applying it.
**kwargs – Additional keyword arguments passed to API schema when applying it.

Returns:

List of API schema objects, one for each input prim.

Example:

>>> import isaacsim.core.experimental.utils.prim as prim_utils
>>> from pxr import UsdPhysics
>>> from isaacsim.core.experimental.prims import Prim
>>>
>>> # given a USD stage with 3 prims at paths /World/prim_0, /World/prim_1, /World/prim_2,
>>> # ensure all prims have physics API schema
>>> usd_prims = [prim_utils.get_prim_at_path(f"/World/prim_{i}") for i in range(3)]
>>> physics_apis = Prim.ensure_api(usd_prims, UsdPhysics.RigidBodyAPI)

static fetch_articulation_root_api_prim_paths( paths: str | list[str], ) → list[str | None]#

Fetch the prim paths that have the Articulation Root API applied.

Parameters:: paths – Single path or list of paths to USD prims. Can include regular expressions for matching multiple prims.
Returns:: List of prim paths that have the Articulation Root API applied.

Example:

>>> from isaacsim.core.experimental.prims import Articulation
>>>
>>> Articulation.fetch_articulation_root_api_prim_paths("/World/prim_.*")
['/World/prim_0', '/World/prim_1', '/World/prim_2']
>>> # check for a sub-tree of prims on which the ArticulationRootAPI has not been applied
>>> Articulation.fetch_articulation_root_api_prim_paths("/World/prim_0/panda_link0")
[None]

Get the applied visual materials.

Backends: usd.

Parameters:: indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
Returns:: List of applied visual materials (shape (N,)). If a prim does not have a material, None is returned.
Raises:: AssertionError – Wrapped prims are not valid.

Example:

>>> # get the applied visual material of the last wrapped prim
>>> prims.get_applied_visual_materials(indices=[2])[0]
<isaacsim.core.experimental.materials.impl.visual_materials.omni_glass.OmniGlassMaterial object at 0x...>

Get the default state (root positions, orientations, linear velocities and angular velocities, and DOF positions, velocities and efforts) of the prims.

Backends: usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

Seven-elements tuple. 1) The default root positions in the world frame (shape (N, 3)). 2) The default root orientations in the world frame (shape (N, 4), quaternion wxyz). 3) The default root linear velocities (shape (N, 3)). 4) The default root angular velocities (shape (N, 3)). 5) The default DOF positions (shape (N, D)). 6) The default DOF velocities (shape (N, D)). 7) The default DOF efforts (shape (N, D)). If the default state is not set using the set_default_state() method, None is returned.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not initialized.

Get the armatures of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Search for Armature in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

Armatures (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF armatures of all prims
>>> armatures = prims.get_dof_armatures()
>>> armatures.shape
(3, 9)
>>>
>>> # get the DOF armatures of the first and last prims' finger DOFs
>>> armatures = prims.get_dof_armatures(indices=[0, 2], dof_indices=[7, 8])
>>> armatures.shape
(2, 2)

Get the Coriolis and centrifugal compensation forces (DOF forces required to counteract Coriolis and centrifugal forces for the given articulation state) of the prims

Backends: tensor.

Search for Coriolis and Centrifugal Compensation Force in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

The Coriolis and centrifugal compensation forces of the prims. For fixed articulation base shape is (N, D). For non-fixed (floating) articulation base shape is (N, D + 6) since the forces acting on the root are also provided.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the coriolis and centrifugal compensation forces (fixed articulation base) of all prims
>>> forces = prims.get_dof_coriolis_and_centrifugal_compensation_forces()
>>> forces.shape
(3, 9)

Get the drive model properties of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

Three-element tuple. 1) Speed effort gradients (shape (N, D)). 2) Maximum actuator velocities (shape (N, D)). 3) Velocity-dependent resistances (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF drive model properties of all prims
>>> speed_effort_gradients, maximum_actuator_velocities, velocity_dependent_resistances = prims.get_dof_drive_model_properties()
>>> speed_effort_gradients.shape, maximum_actuator_velocities.shape, velocity_dependent_resistances.shape
((3, 9), (3, 9), (3, 9))
>>>
>>> # get the DOF drive model properties of the first and last prims
>>> speed_effort_gradients, maximum_actuator_velocities, velocity_dependent_resistances = prims.get_dof_drive_model_properties(indices=[0, 2])
>>> speed_effort_gradients.shape, maximum_actuator_velocities.shape, velocity_dependent_resistances.shape
((2, 9), (2, 9), (2, 9))

Get the drive types of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

The drive types. Possible values are acceleration or force (shape (N, D)). If the drive type is not set, None is returned.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the drive types of the first prim
>>> drive_types = prims.get_dof_drive_types(indices=[0])
>>> print(drive_types)
[['force', 'force', 'force', 'force', 'force', 'force', 'force', 'force', 'none']]

Get the efforts of the degrees of freedom (DOFs) of the prims.

Backends: tensor.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

DOF efforts (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the DOF efforts of all prims
>>> efforts = prims.get_dof_efforts()
>>> efforts.shape
(3, 9)
>>>
>>> # get the DOF efforts of the first and last prims' finger DOFs
>>> efforts = prims.get_dof_efforts(indices=[0, 2], dof_indices=[7, 8])
>>> efforts.shape
(2, 2)

Get the friction properties of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

Three-element tuple. 1) Static friction efforts (shape (N, D)). 2) Dynamic friction efforts (shape (N, D)). 3) Viscous friction coefficients (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF friction properties of all prims
>>> static_frictions, dynamic_frictions, viscous_frictions = prims.get_dof_friction_properties()
>>> static_frictions.shape, dynamic_frictions.shape, viscous_frictions.shape
((3, 9), (3, 9), (3, 9))
>>>
>>> # get the DOF friction properties of the first and last prims
>>> static_frictions, dynamic_frictions, viscous_frictions = prims.get_dof_friction_properties(indices=[0, 2])
>>> static_frictions.shape, dynamic_frictions.shape, viscous_frictions.shape
((2, 9), (2, 9), (2, 9))

Get the implicit Proportional-Derivative (PD) controller’s gains (stiffnesses and dampings) of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

Two-elements tuple. 1) Stiffnesses (shape (N, D)). 2) Dampings (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF gains of all prims
>>> stiffnesses, dampings = prims.get_dof_gains()
>>> stiffnesses.shape, dampings.shape
((3, 9), (3, 9))
>>>
>>> # get the DOF gains of the first and last prims' finger DOFs
>>> stiffnesses, dampings = prims.get_dof_gains(indices=[0, 2], dof_indices=[7, 8])
>>> stiffnesses.shape, dampings.shape
((2, 2), (2, 2))

Get the gravity compensation forces (DOF forces required to counteract gravitational forces for the given articulation pose) of the prims

Backends: tensor.

Search for Gravity Compensation Force in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

The gravity compensation forces of the prims. For fixed articulation base shape is (N, D). For non-fixed (floating) articulation base shape is (N, D + 6) since the forces acting on the root are also provided.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the gravity compensation forces of all prims
>>> forces = prims.get_dof_gravity_compensation_forces()
>>> forces.shape
(3, 9)
>>>
>>> # get the gravity compensation forces of the first and last prims' finger DOFs
>>> forces = prims.get_dof_gravity_compensation_forces(indices=[0, 2], dof_indices=[7, 8])
>>> forces.shape
(2, 2)

get_dof_indices(names: str | list[str]) → warp.array#

Get the indices of one or more degrees of freedom (DOFs) of the prims.

Backends: usd, tensor.

Parameters:: names – Single name or list of names of DOFs to get indices for.
Returns:: Indices of the specified DOF names.

Example:

>>> # show all DOF names and their indices
>>> for name in prims.dof_names:
...     print(prims.get_dof_indices(name), name)
[0] panda_joint1
[1] panda_joint2
[2] panda_joint3
[3] panda_joint4
[4] panda_joint5
[5] panda_joint6
[6] panda_joint7
[7] panda_finger_joint1
[8] panda_finger_joint2
>>>
>>> # get the indices of Franka Panda's finger DOFs
>>> indices = prims.get_dof_indices(["panda_finger_joint1", "panda_finger_joint2"])
>>> print(indices)
[7 8]

Get the limits of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

Lower limits (shape (N, D)). 2) Upper limits (shape (N, D)).

Return type:

Two-element tuple

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF limits of all prims
>>> lower, upper = prims.get_dof_limits()
>>> lower.shape, upper.shape
((3, 9), (3, 9))
>>>
>>> # get the DOF limits of the first and last prims
>>> lower, upper = prims.get_dof_limits(indices=[0, 2])
>>> lower.shape, upper.shape
((2, 9), (2, 9))

Get the maximum forces applied by the drive of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

Maximum forces applied by the drive (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF maximum efforts of all prims
>>> max_efforts = prims.get_dof_max_efforts()
>>> max_efforts.shape
(3, 9)
>>>
>>> # get the DOF maximum efforts of the first and last prims' finger DOFs
>>> max_efforts = prims.get_dof_max_efforts(indices=[0, 2], dof_indices=[7, 8])
>>> max_efforts.shape
(2, 2)

Get the maximum velocities of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

Maximum velocities (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF maximum velocities of all prims
>>> max_velocities = prims.get_dof_max_velocities()
>>> max_velocities.shape
(3, 9)
>>>
>>> # get the DOF maximum velocities of the first and last prims' finger DOFs
>>> max_velocities = prims.get_dof_max_velocities(indices=[0, 2], dof_indices=[7, 8])
>>> max_velocities.shape
(2, 2)

Get the position targets of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

DOF position targets (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF position targets of all prims
>>> position_targets = prims.get_dof_position_targets()
>>> position_targets.shape
(3, 9)
>>>
>>> # get the DOF position targets of the first and last prims' finger DOFs
>>> position_targets = prims.get_dof_position_targets(indices=[0, 2], dof_indices=[7, 8])
>>> position_targets.shape
(2, 2)

Get the positions of the degrees of freedom (DOFs) of the prims.

Backends: tensor.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

DOF positions (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the DOF position of all prims
>>> positions = prims.get_dof_positions()
>>> positions.shape
(3, 9)
>>>
>>> # get the DOF position of the first and last prims' finger DOFs
>>> positions = prims.get_dof_positions(indices=[0, 2], dof_indices=[7, 8])
>>> positions.shape
(2, 2)

Get the degrees of freedom (DOF) projected joint forces of the prims.

Backends: tensor.

This method projects the links incoming joint forces in the motion direction and hence is the active component of the force.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

DOF projected joint forces (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the DOF projected joint forces of all prims
>>> forces = prims.get_dof_projected_joint_forces()
>>> forces.shape
(3, 9)
>>>
>>> # get the projected joint forces of the first and last prims' finger DOFs
>>> forces = prims.get_dof_projected_joint_forces(indices=[0, 2], dof_indices=[7, 8])
>>> forces.shape
(2, 2)

Get the velocities of the degrees of freedom (DOFs) of the prims.

Backends: tensor.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

DOF velocities (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the DOF velocities of all prims
>>> velocities = prims.get_dof_velocities()
>>> velocities.shape
(3, 9)
>>>
>>> # get the DOF velocity of the first and last prims' finger DOFs
>>> velocities = prims.get_dof_velocities(indices=[0, 2], dof_indices=[7, 8])
>>> velocities.shape
(2, 2)

Get the velocity targets of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Returns:

DOF velocity targets (shape (N, D)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the DOF velocity targets of all prims
>>> velocity_targets = prims.get_dof_velocity_targets()
>>> velocity_targets.shape
(3, 9)
>>>
>>> # get the DOF velocity target of the first and last prims' finger DOFs
>>> velocity_targets = prims.get_dof_velocity_targets(indices=[0, 2], dof_indices=[7, 8])
>>> velocity_targets.shape
(2, 2)

get_enabled_self_collisions( *, indices: int | list | np.ndarray | wp.array | None = None, ) → wp.array#

Get the enable state of the self-collisions processing of the prims.

Backends: usd.

Parameters:: indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
Returns:: Boolean flags indicating if the self-collisions processing is enabled (shape (N, 1)).
Raises:: AssertionError – Wrapped prims are not valid.

Example:

>>> # get the self-collisions enabled state of all prims
>>> print(prims.get_enabled_self_collisions())
[[False]
 [False]
 [False]]

Get the dampings of the fixed tendons of the prims.

Backends: tensor.

Search for Fixed Tendons in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

The dampings of the fixed tendons (shape (N, T)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Get the limit stiffnesses of the fixed tendons of the prims.

Backends: tensor.

Search for Fixed Tendons in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

The limit stiffnesses of the fixed tendons (shape (N, T)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Get the limits of the fixed tendons of the prims.

Backends: tensor.

Search for Fixed Tendons in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

Two-elements tuple. 1) The lower limits of the fixed tendons (shape (N, T)). 2) The upper limits of the fixed tendons (shape (N, T)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Get the offsets of the fixed tendons of the prims.

Backends: tensor.

Search for Fixed Tendons in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

The offsets of the fixed tendons (shape (N, T)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Get the rest length of the fixed tendons of the prims.

Backends: tensor.

Search for Fixed Tendons in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

The rest lengths of the fixed tendons (shape (N, T)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Get the stiffness of the fixed tendons of the prims.

Backends: tensor.

Search for Fixed Tendons in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

The stiffnesses of the fixed tendons (shape (N, T)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

get_jacobian_matrices( *, indices: int | list | np.ndarray | wp.array | None = None, ) → wp.array#

Get the Jacobian matrices of the prims.

Backends: tensor.

Note

The first dimension corresponds to the amount of wrapped prims while the last 3 dimensions are the Jacobian matrix shape. Refer to the jacobian_matrix_shape property for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

The Jacobian matrices of the prims (shape (N, *jacobian_matrix_shape)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the Jacobian matrices of all prims
>>> jacobians = prims.get_jacobian_matrices()
>>> jacobians.shape
(3, 10, 6, 9)

get_joint_indices(names: str | list[str]) → warp.array#

Get the indices of one or more joints of the prims.

Backends: usd, tensor.

Parameters:: names – Single name or list of names of joints to get indices for.
Returns:: Indices of the specified joint names.

Example:

>>> # show all joint names and their indices
>>> for name in prims.joint_names:
...     print(prims.get_joint_indices(name), name)
[0] panda_joint1
[1] panda_joint2
[2] panda_joint3
[3] panda_joint4
[4] panda_joint5
[5] panda_joint6
[6] panda_joint7
[7] panda_hand_joint
[8] panda_finger_joint1
[9] panda_finger_joint2
>>>
>>> # get the indices of Franka Panda's finger joints
>>> indices = prims.get_joint_indices(["panda_finger_joint1", "panda_finger_joint2"])
>>> print(indices)
[8 9]

Get the center of mass (COM) pose (position and orientation) of the links of the prims.

Backends: tensor.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.

Returns:

Two-elements tuple. 1) The center of mass positions (shape (N, L, 3)). 2) The center of mass orientations (shape (N, L, 4), quaternion wxyz).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the COM poses of the links of all prims
>>> positions, orientations = prims.get_link_coms()
>>> positions.shape, orientations.shape
((3, 11, 3), (3, 11, 4))
>>>
>>> # get the COM poses of the first and last prims' finger links
>>> positions, orientations = prims.get_link_coms(indices=[0, 2], link_indices=[9, 10])
>>> positions.shape, orientations.shape
((2, 2, 3), (2, 2, 4))

Get the enabled state of the gravity on the links of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.

Returns:

Boolean flags indicating if the gravity is enabled on the links (shape (N, L)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the gravity enabled state of the links of all prims
>>> enabled = prims.get_link_enabled_gravities()
>>> enabled.shape
(3, 11)
>>>
>>> # get the gravity enabled state of the first and last prims' finger links
>>> enabled = prims.get_link_enabled_gravities(indices=[0, 2], link_indices=[9, 10])
>>> enabled.shape
(2, 2)

Get the link incoming joint forces and torques to external loads of the prims.

Backends: tensor.

In a kinematic tree, each link has a single incoming joint. This method provides the total 6D force/torque of links incoming joints.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.

Returns:

Two-elements tuple. 1) The link incoming joint forces (shape (N, L, 3)). 2) The link incoming joint torques (shape (N, L, 3)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the incoming joint forces and torques of the links of all prims
>>> forces, torques = prims.get_link_incoming_joint_force()
>>> forces.shape, torques.shape
((3, 11, 3), (3, 11, 3))
>>>
>>> # get the incoming joint forces and torques of the first and last prims' finger links
>>> forces, torques = prims.get_link_incoming_joint_force(indices=[0, 2], link_indices=[9, 10])
>>> forces.shape, torques.shape
((2, 2, 3), (2, 2, 3))

get_link_indices(names: str | list[str]) → warp.array#

Get the indices of one or more links of the prims.

Backends: usd, tensor.

Parameters:: names – Single name or list of names of links to get indices for.
Returns:: Indices of the specified link names.

Example:

>>> # show all link names and their indices
>>> for name in prims.link_names:
...     print(prims.get_link_indices(name), name)
[0] panda_link0
[1] panda_link1
[2] panda_link2
[3] panda_link3
[4] panda_link4
[5] panda_link5
[6] panda_link6
[7] panda_link7
[8] panda_hand
[9] panda_leftfinger
[10] panda_rightfinger
>>>
>>> # get the indices of Franka Panda's finger links
>>> indices = prims.get_link_indices(["panda_leftfinger", "panda_rightfinger"])
>>> print(indices)
[ 9 10]

Get the inertias tensors of the links of the prims.

Backends: tensor.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.
inverse – Whether to return inverse inertia tensors (true) or inertia tensors (false).

Returns:

The inertia tensors or inverse inertia tensors (shape (N, L, 9)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the inertia tensors of the links of all prims
>>> inertias = prims.get_link_inertias()
>>> inertias.shape
(3, 11, 9)
>>>
>>> # get the inverse inertia tensors of the first and last prims' finger links
>>> inertias = prims.get_link_inertias(indices=[0, 2], link_indices=[9, 10], inverse=True)
>>> inertias.shape
(2, 2, 9)

Get the masses of the links of the prims.

Backends: tensor, usd.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.
inverse – Whether to return inverse masses (true) or masses (false).

Returns:

The link masses (shape (N, L)).

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # get the masses of the links of all prims
>>> masses = prims.get_link_masses()
>>> masses.shape
(3, 11)
>>>
>>> # get the inverse masses of the first and last prims' finger links
>>> inverse_masses = prims.get_link_masses(indices=[0, 2], link_indices=[9, 10], inverse=True)
>>> inverse_masses.shape
(2, 2)

get_local_poses( *, indices: int | list | np.ndarray | wp.array | None = None, ) → tuple[wp.array, wp.array]#

Get the root poses (translations and orientations) in the local frame of the prims.

Backends: tensor, usd, usdrt, fabric.

Parameters:: indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
Returns:: Two-elements tuple. 1) The root translations in the local frame (shape (N, 3)). 2) The root orientations in the local frame (shape (N, 4), quaternion wxyz).
Raises:: AssertionError – Wrapped prims are not valid.

Example:

>>> # get the local poses of all prims
>>> translations, orientations = prims.get_local_poses()
>>> translations.shape, orientations.shape
((3, 3), (3, 4))
>>>
>>> # get the local pose of the first prim
>>> translations, orientations = prims.get_local_poses(indices=[0])
>>> translations.shape, orientations.shape
((1, 3), (1, 4))

get_local_scales( *, indices: int | list | np.ndarray | wp.array | None = None, ) → wp.array#

Get the local scales of the prims.

Backends: usd, usdrt, fabric.

Parameters:: indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
Returns:: Scales of the prims (shape (N, 3)).
Raises:: AssertionError – Wrapped prims are not valid.

Example:

>>> # get local scales of all prims
>>> scales = prims.get_local_scales()
>>> scales.shape
(3, 3)

get_mass_matrices( *, indices: int | list | np.ndarray | wp.array | None = None, ) → wp.array#

Get the mass matrices of the prims.

Backends: tensor.

Note

The first dimension corresponds to the amount of wrapped prims while the last 2 dimensions are the mass matrix shape. Refer to the mass_matrix_shape property for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

The mass matrices of the prims (shape (N, *mass_matrix_shape)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the mass matrices of all prims
>>> mass_matrices = prims.get_mass_matrices()
>>> mass_matrices.shape
(3, 9, 9)

get_sleep_thresholds( *, indices: int | list | np.ndarray | wp.array | None = None, ) → wp.array#

Get the sleep thresholds of the prims.

Backends: usd.

Search for Articulations and Sleeping in PhysX docs for more details

Parameters:: indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
Returns:: The sleep thresholds (shape (N, 1)).
Raises:: AssertionError – Wrapped prims are not valid.

Example:

>>> # get the sleep thresholds of all prims
>>> thresholds = prims.get_sleep_thresholds()
>>> thresholds.shape
(3, 1)
>>>
>>> # get the sleep threshold of the first and last prims
>>> thresholds = prims.get_sleep_thresholds(indices=[0, 2])
>>> thresholds.shape
(2, 1)

get_solver_iteration_counts( *, indices: int | list | np.ndarray | wp.array | None = None, ) → tuple[wp.array, wp.array]#

Get the physics solver iteration counts (position and velocity) of the prims.

Backends: usd.

The solver iteration count determines how accurately contacts, drives, and limits are resolved. Search for Solver Iteration Count in PhysX docs for more details.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

Position iteration counts (shape (N, 1)).
Velocity iteration counts (shape (N, 1)).

Return type:

Two-element tuple

Example:

>>> # get the solver iteration counts of all prims
>>> position_counts, velocity_counts = prims.get_solver_iteration_counts()
>>> position_counts.shape, velocity_counts.shape
((3, 1), (3, 1))
>>>
>>> # get the solver iteration counts of the first and last prims
>>> position_counts, velocity_counts = prims.get_solver_iteration_counts(indices=[0, 2])
>>> position_counts.shape, velocity_counts.shape
((2, 1), (2, 1))

get_stabilization_thresholds( *, indices: int | list | np.ndarray | wp.array | None = None, ) → wp.array#

Get the mass-normalized kinetic energy below which the prims may participate in stabilization.

Backends: usd.

Search for Stabilization Threshold in PhysX docs for more details.

Parameters:: indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
Returns:: Stabilization thresholds (shape (N, 1)).

Example:

>>> # get the stabilization thresholds of all prims
>>> thresholds = prims.get_stabilization_thresholds()
>>> thresholds.shape
(3, 1)
>>>
>>> # get the stabilization threshold of the first and last prims
>>> thresholds = prims.get_stabilization_thresholds(indices=[0, 2])
>>> thresholds.shape
(2, 1)

get_velocities( *, indices: int | list | np.ndarray | wp.array | None = None, ) → tuple[wp.array, wp.array]#

Get the root velocities (linear and angular) of the prims.

Backends: tensor.

Parameters:

indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Returns:

Two-elements tuple. 1) The root linear velocities (shape (N, 3)). 2) The root angular velocities (shape (N, 3)).

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get the velocities of all prims
>>> linear_velocities, angular_velocities = prims.get_velocities()
>>> linear_velocities.shape, angular_velocities.shape
((3, 3), (3, 3))
>>>
>>> # get the velocities of the first prim
>>> linear_velocities, angular_velocities = prims.get_velocities(indices=[0])
>>> linear_velocities.shape, angular_velocities.shape
((1, 3), (1, 3))

get_visibilities( *, indices: int | list | np.ndarray | wp.array | None = None, ) → wp.array#

Get the visibility state (whether prims are visible or invisible during rendering) of the prims.

Backends: usd.

Parameters:: indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
Returns:: Boolean flags indicating the visibility state (shape (N, 1)).
Raises:: AssertionError – Wrapped prims are not valid.

Example:

>>> # get the visibility states of all prims
>>> visibilities = prims.get_visibilities()
>>> print(visibilities)
[[ True] [ True] [ True]]
>>>
>>> # get the visibility states of the first and last prims
>>> visibilities = prims.get_visibilities(indices=[0, 2])
>>> print(visibilities)
[[ True] [ True]]

get_world_poses( *, indices: int | list | np.ndarray | wp.array | None = None, ) → tuple[wp.array, wp.array]#

Get the root poses (positions and orientations) in the world frame of the prims.

Backends: tensor, usd, usdrt, fabric.

Parameters:: indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
Returns:: Two-elements tuple. 1) The root positions in the world frame (shape (N, 3)). 2) The root orientations in the world frame (shape (N, 4), quaternion wxyz).
Raises:: AssertionError – Wrapped prims are not valid.

Example:

>>> # get the world poses of all prims
>>> positions, orientations = prims.get_world_poses()
>>> positions.shape, orientations.shape
((3, 3), (3, 4))
>>>
>>> # get the world pose of the first prim
>>> positions, orientations = prims.get_world_poses(indices=[0])
>>> positions.shape, orientations.shape
((1, 3), (1, 4))

initialize_cpp_data_view()#

Initialize the optional C++ read-only data view.

This method is opt-in and can be called by users that need C++ consumers to read articulation data through IPrimDataReader.

is_physics_tensor_entity_initialized() → bool#

Check if the physics tensor entity is initialized.

Returns:: Whether the physics tensor entity is initialized.

is_physics_tensor_entity_valid() → bool#

Check if the physics tensor entity is valid.

Returns:: Whether the physics tensor entity is valid.

reset_to_default_state( *, warn_on_non_default_state: bool = False, ) → None#

Reset the prims to the specified default state.

Backends: tensor.

This method applies the default state defined using the set_default_state() method.

Note

This method teleports prims to the specified default state (positions and orientations) and sets the linear and angular velocities and the DOF positions, velocities and efforts immediately.

Warning

This method has no effect when no default state is set. In this case, a warning message is logged if warn_on_non_default_state is True.

Parameters:

warn_on_non_default_state – Whether to log a warning message when no default state is set.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # get default state (no default state set at this point)
>>> prims.get_default_state()
(None, None, None, None, None, None, None)
>>>
>>> # set default state
>>> # - random root positions for each prim
>>> # - same fixed orientation for all prims
>>> # - zero root velocities for all prims
>>> # - random DOF positions for all DOFs
>>> # - zero DOF velocities for all DOFs
>>> # - zero DOF efforts for all DOFs
>>> positions = np.random.uniform(low=-1, high=1, size=(3, 3))
>>> prims.set_default_state(
...     positions=positions,
...     orientations=[1.0, 0.0, 0.0, 0.0],
...     linear_velocities=np.zeros(3),
...     angular_velocities=np.zeros(3),
...     dof_positions=np.random.uniform(low=-0.25, high=0.25, size=(3, 9)),
...     dof_velocities=np.zeros(9),
...     dof_efforts=np.zeros(9),
... )
>>>
>>> # get default state (default state is set)
>>> prims.get_default_state()
(array(shape=(3, 3), dtype=float32),
 array(shape=(3, 4), dtype=float32),
 array(shape=(3, 3), dtype=float32),
 array(shape=(3, 3), dtype=float32),
 array(shape=(3, 9), dtype=float32),
 array(shape=(3, 9), dtype=float32),
 array(shape=(3, 9), dtype=float32))
>>>
>>> # reset prims to default state
>>> prims.reset_to_default_state()

reset_xform_op_properties() → None#

Reset the transformation operation attributes of the prims to a standard set.

Backends: usd.

It ensures that each prim has only the following transformations in the specified order. Any other transformation operations are removed, so they are not consumed.

xformOp:translate (double precision)
xformOp:orient (double precision)
xformOp:scale (double precision)

Note

This method preserves the poses of the prims in the world frame while reorganizing the transformation operations.

Raises:: AssertionError – Wrapped prims are not valid.

Example:

>>> # reset transform operations of all prims
>>> prims.reset_xform_op_properties()
>>>
>>> # verify transform operations of the first wrapped prim
>>> prims.prims[0].GetPropertyNames()
[... 'xformOp:orient', 'xformOp:scale', 'xformOp:translate', 'xformOpOrder']

static resolve_paths( paths: str | list[str], raise_on_mixed_paths: bool = True, ) → tuple[list[str], list[str]]#

Resolve paths to prims in the stage to get existing and non-existing paths.

Backends: usd.

Parameters:

paths – Single path or list of paths to USD prims. Paths may contain regular expressions to match multiple prims.
raise_on_mixed_paths – Whether to raise an error if resulting paths are mixed or invalid.

Returns:

Two-elements tuple. 1) List of existing paths. 2) List of non-existing paths.

Raises:

ValueError – If resulting paths are mixed or invalid and raise_on_mixed_paths is True.

Set the default state (root positions, orientations, linear velocities and angular velocities, and DOF positions, velocities and efforts) of the prims.

Backends: usd.

Hint

Prims can be reset to their default state by calling the reset_to_default_state() method.

Parameters:

positions – Default root positions in the world frame (shape (N, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
orientations – Default root orientations in the world frame (shape (N, 4), quaternion wxyz). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
linear_velocities – Default root linear velocities (shape (N, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
angular_velocities – Default root angular velocities (shape (N, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
dof_positions – Default DOF positions (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
dof_velocities – Default DOF velocities (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
dof_efforts – Default DOF efforts (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Set the armatures of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Search for Armature in PhysX docs for more details.

Parameters:

armatures – Armatures (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set the DOF armatures for all prims
>>> prims.set_dof_armatures([0.5])
>>>
>>> # set the armatures for the first and last prims' finger DOFs
>>> prims.set_dof_armatures([1.5], indices=[0, 2], dof_indices=[7, 8])

Set the drive model properties of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

speed_effort_gradients – Speed effort gradients (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
maximum_actuator_velocities – Maximum actuator velocities (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
velocity_dependent_resistances – Velocity-dependent resistances (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – If neither speed_effort_gradients, maximum_actuator_velocities, or velocity_dependent_resistances are specified.
AssertionError – Wrapped prims are not valid.

Example:

>>> # set the DOF drive model properties for all prims
>>> prims.set_dof_drive_model_properties(
...     speed_effort_gradients=[2.0],
...     maximum_actuator_velocities=[1.0],
...     velocity_dependent_resistances=[1.5],
... )

Set the drive types of the degrees of freedom (DOFs) of the prims.

Backends: usd.

Parameters:

types – Drive types. Can be a single string or list of strings (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set the DOF drive types for all prims to 'acceleration'
>>> # note that dof indices 8 is a mimic joint, it does not have a DOF drive
>>> prims.set_dof_drive_types("acceleration", dof_indices=[0, 1, 2, 3, 4, 5, 6, 7])
>>>
>>> # set the drive types for the all prims' finger DOFs to 'force'
>>> prims.set_dof_drive_types("force", dof_indices=[7])

Set the efforts of the degrees of freedom (DOFs) of the prims.

Backends: tensor.

Note

For effort control, this method must be used. In contrast to the methods that set a target for DOF position/velocity, this method must be called at every update step to ensure effort control.

Hint

For effort control, set zero stiffness and damping, or remove DOF’s drive.

Parameters:

efforts – Efforts (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # set random DOF efforts for all prims
>>> prims.set_dof_efforts(np.random.randn(3, 9))
>>>
>>> # set random efforts for the first and last prims' finger DOFs
>>> prims.set_dof_efforts(np.random.randn(2, 2), indices=[0, 2], dof_indices=[7, 8])

Set the friction properties of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Warning

The static_frictions must be greater than or equal to the dynamic_frictions.

Parameters:

static_frictions – Static friction efforts (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
dynamic_frictions – Dynamic friction efforts (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
viscous_frictions – Viscous friction coefficients (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – If neither static_frictions, dynamic_frictions, or viscous_frictions are specified.
AssertionError – Wrapped prims are not valid.

Example:

>>> # set the DOF friction properties for all prims
>>> prims.set_dof_friction_properties(static_frictions=[0.5], dynamic_frictions=[0.2], viscous_frictions=[0.1])

Set the implicit Proportional-Derivative (PD) controller’s gains (stiffnesses and dampings) of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

stiffnesses – Stiffnesses (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
dampings – Dampings (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.
update_default_gains – Whether to update the default gains with the given values.

Raises:

AssertionError – If neither stiffnesses nor dampings are specified.
AssertionError – Wrapped prims are not valid.

Example:

>>> # set the DOF gains for all prims
>>> stiffnesses = np.array([100000, 100000, 100000, 100000, 80000, 80000, 80000, 50000, 50000])
>>> dampings = np.array([8000, 8000, 8000, 8000, 5000, 5000, 5000, 2000, 2000])
>>> prims.set_dof_gains(stiffnesses, dampings)

Set the limits of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

lower – Lower limits (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
upper – Upper limits (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – If neither lower nor upper limits are specified.
AssertionError – Wrapped prims are not valid.

Example:

>>> # set the DOF lower limits for all prims to -0.25
>>> prims.set_dof_limits(lower=[-0.25])

Set the maximum forces applied by the drive of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

max_efforts – Maximum forces (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set the maximum DOF efforts for all prims to 1000
>>> prims.set_dof_max_efforts([1000])

Set the maximum velocities of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Parameters:

max_velocities – Maximum velocities (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set the maximum DOF velocities for all prims to 100
>>> prims.set_dof_max_velocities([100])

Set the position targets of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Note

This method set the desired target position for the DOFs, not the instantaneous positions. It may take several simulation steps to reach the target position (depending on the DOFs’ stiffness and damping values).

Hint

High stiffness causes the DOF to move faster and harder towards the desired target, while high damping softens but also slows the DOF’s movement towards the target.

For position control, set relatively high stiffness and non-zero low damping (to reduce vibrations).

Parameters:

positions – Position targets (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set random DOF position targets for all prims
>>> prims.set_dof_position_targets(np.random.uniform(low=-0.25, high=0.25, size=(3, 9)))
>>>
>>> # open all the Franka Panda fingers (finger DOFs to 0.04)
>>> prims.set_dof_position_targets([0.04], dof_indices=[7, 8])

Set the positions of the degrees of freedom (DOFs) of the prims.

Backends: tensor.

Warning

This method teleports prims to the specified DOF positions. Use the set_dof_position_targets() method to control the DOFs’ positions.

Parameters:

positions – Positions (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # set random DOF positions for all prims
>>> prims.set_dof_positions(np.random.uniform(low=-0.25, high=0.25, size=(3, 9)))
>>>
>>> # set all the Franka Panda fingers to closed position immediately (finger DOFs to 0.0)
>>> prims.set_dof_positions([0.0], dof_indices=[7, 8])

Set the velocities of the degrees of freedom (DOFs) of the prims.

Backends: tensor.

Warning

This method set the specified DOF velocities immediately. Use the set_dof_velocity_targets() method to control the DOFs’ velocities.

Parameters:

velocities – Velocities (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # set random DOF velocities for all prims
>>> prims.set_dof_velocities(np.random.uniform(low=-10, high=10, size=(3, 9)))

Set the velocity targets of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

Note

This method set the desired target velocity for the DOFs, not the instantaneous velocities. It may take several simulation steps to reach the target velocity (depending on the DOFs’ stiffness and damping values).

Hint

High stiffness causes the DOF to move faster and harder towards the desired target, while high damping softens but also slows the DOF’s movement towards the target.

For velocity control, set zero stiffness and non-zero damping.

Parameters:

velocities – Velocity targets (shape (N, D)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set random DOF velocity targets for all prims
>>> prims.set_dof_velocity_targets(np.random.uniform(low=-10, high=10, size=(3, 9)))

Enable or disable the self-collisions processing of the prims.

Backends: usd.

Parameters:

enabled – Boolean flags to enable/disable self-collisions (shape (N, 1)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # disable the self-collisions for all prims
>>> prims.set_enabled_self_collisions([False])

Set the fixed tendon properties of the prims.

Backends: tensor.

Search for Fixed Tendons in PhysX docs for more details.

Parameters:

stiffnesses – The stiffnesses (shape (N, T)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
dampings – The dampings (shape (N, T)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
limit_stiffnesses – The limit stiffnesses (shape (N, T)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
lower_limits – The lower limits (shape (N, T)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
upper_limits – The upper limits (shape (N, T)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
rest_lengths – The rest lengths (shape (N, T)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
offsets – The offsets (shape (N, T)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
tendon_indices – Indices of tendons to process (shape (T,)). If not defined, all tendons are processed.

Raises:

AssertionError – None of the fixed tendon properties are defined.
AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Set the center of mass (COM) pose (position and orientation) of the links of the prims.

Backends: tensor.

Parameters:

positions – Center of mass positions (shape (N, L, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
orientations – Center of mass orientations (shape (N, L, 4), quaternion wxyz). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.

Raises:

AssertionError – If neither positions nor orientations are specified.
AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # set random COM link positions for all prims
>>> positions = np.random.uniform(low=-1, high=1, size=(3, 11, 3))
>>> prims.set_link_coms(positions)

Set the enabled state of the gravity on the links of the prims.

Backends: tensor, usd.

Parameters:

enabled – Boolean flags to enable/disable gravity on the links (shape (N, L)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # enable the gravity of the links for all prims
>>> prims.set_link_enabled_gravities([True])
>>>
>>> # disable the gravity for the first and last prims' finger links
>>> prims.set_link_enabled_gravities([False], indices=[0, 2], link_indices=[9, 10])

Set the inertias of the links of the prims.

Backends: tensor.

Parameters:

inertias – The link inertias (shape (N, L, 9)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # set the inertia tensors of the links for all prims
>>> inertias = np.diag([0.1, 0.1, 0.1]).flatten()  # shape: (9,)
>>> prims.set_link_inertias(inertias)
>>>
>>> # set the inertia tensors for the first and last prims' finger links
>>> inertias = np.diag([0.2, 0.2, 0.2]).flatten()  # shape: (9,)
>>> prims.set_link_inertias(inertias, indices=[0, 2], link_indices=[9, 10])

Set the masses of the links of the prims.

Backends: tensor, usd.

Parameters:

masses – The link masses (shape (N, L)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
link_indices – Indices of links to process (shape (L,)). If not defined, all links are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set the masses of the links for all prims
>>> prims.set_link_masses([10.0])
>>>
>>> # set the masses for the first and last prims' finger links
>>> prims.set_link_masses([0.5], indices=[0, 2], link_indices=[9, 10])

Set the root poses (translations and orientations) in the local frame of the prims.

Backends: tensor, usd, usdrt, fabric.

Note

This method teleports prims to the specified poses.

Parameters:

translations – Root translations in the local frame (shape (N, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
orientations – Root orientations in the local frame (shape (N, 4), quaternion wxyz). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – If neither translations nor orientations are specified.
AssertionError – Wrapped prims are not valid.

Example:

>>> # set poses (fixed translations and random orientations) for all prims
>>> translations = [[0, y, 0] for y in range(3)]
>>> orientations = np.random.randn(3, 4)
>>> orientations = orientations / np.linalg.norm(orientations, axis=-1, keepdims=True)  # normalize quaternions
>>> prims.set_local_poses(translations, orientations)

Set the local scales of the prims.

Backends: usd, usdrt, fabric.

Parameters:

scales – Scales to be applied to the prims (shape (N, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set random positive scales for all prims
>>> scales = np.random.uniform(low=0.5, high=1.5, size=(3, 3))
>>> prims.set_local_scales(scales)

Set the sleep thresholds of the prims.

Backends: usd.

Search for Articulations and Sleeping in PhysX docs for more details.

Parameters:

thresholds – Sleep thresholds (shape (N, 1)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set the sleep thresholds for all prims
>>> prims.set_sleep_thresholds([1e-5])
>>>
>>> # set the sleep thresholds for the first and last prims
>>> prims.set_sleep_thresholds([1.5e-5], indices=[0, 2])

Set the physics solver iteration counts (position and velocity) of the prims.

Backends: usd.

The solver iteration count determines how accurately contacts, drives, and limits are resolved. Search for Solver Iteration Count in PhysX docs for more details.

Warning

The more iterations, the more accurate the results, at the cost of decreasing simulation performance.

Parameters:

position_counts – Number of iterations for the position solver (shape (N, 1)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
velocity_counts – Number of iterations for the velocity solver (shape (N, 1)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – Neither position_counts nor velocity_counts are defined.
AssertionError – Wrapped prims are not valid.

Example:

>>> # set the solver iteration counts (position: 16, velocity: 4) for all prims
>>> prims.set_solver_iteration_counts([16], [4])

Set the mass-normalized kinetic energy below which the prims may participate in stabilization.

Backends: usd.

Search for Stabilization Threshold in PhysX docs for more details.

Parameters:

thresholds – Stabilization thresholds to be applied (shape (N, 1)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # set the stabilization thresholds for all prims
>>> prims.set_stabilization_thresholds([1e-5])
>>>
>>> # set the stabilization thresholds for the first and last prims
>>> prims.set_stabilization_thresholds([1.5e-5], indices=[0, 2])

Set the root velocities (linear and angular) of the prims.

Backends: tensor.

Parameters:

linear_velocities – Root linear velocities (shape (N, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
angular_velocities – Root angular velocities (shape (N, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – If neither linear_velocities nor angular_velocities are specified.
AssertionError – Wrapped prims are not valid.
AssertionError – Physics tensor entity is not valid.

Example:

>>> # set random velocities for all prims
>>> linear_velocities = np.random.uniform(low=-1, high=1, size=(3, 3))
>>> angular_velocities = np.random.uniform(low=-1, high=1, size=(3, 3))
>>> prims.set_velocities(linear_velocities, angular_velocities)

Set the visibility state (whether prims are visible or invisible during rendering) of the prims.

Backends: usd.

Parameters:

visibilities – Boolean flags to set the visibility state (shape (N, 1)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – Wrapped prims are not valid.

Example:

>>> # make all prims invisible
>>> prims.set_visibilities([False])
>>>
>>> # make first and last prims invisible
>>> prims.set_visibilities([True])  # restore visibility from previous call
>>> prims.set_visibilities([False], indices=[0, 2])

Set the root poses (positions and orientations) in the world frame of the prims.

Backends: tensor, usd, usdrt, fabric.

Note

This method teleports prims to the specified poses.

Parameters:

positions – Root positions in the world frame (shape (N, 3)). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
orientations – Root orientations in the world frame (shape (N, 4), quaternion wxyz). If the input shape is smaller than expected, data will be broadcasted (following NumPy broadcast rules).
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.

Raises:

AssertionError – If neither positions nor orientations are specified.
AssertionError – Wrapped prims are not valid.

Example:

>>> # set poses (fixed positions and random orientations) for all prims
>>> positions = [[0, y, 0] for y in range(3)]
>>> orientations = np.random.randn(3, 4)
>>> orientations = orientations / np.linalg.norm(orientations, axis=-1, keepdims=True)  # normalize quaternions
>>> prims.set_world_poses(positions, orientations)

Switch the control mode (understood as the gain adjustment) of the degrees of freedom (DOFs) of the prims.

Backends: tensor, usd.

This method sets the implicit Proportional-Derivative (PD) controller’s gains (stiffnesses and dampings) according to the following rules:

Control mode	Stiffnesses	Dampings
`"position"`	default stiffnesses	default dampings
`"velocity"`	0.0	default dampings
`"effort"`	0.0	0.0

Parameters:

mode – Control mode. Supported modes are "position", "velocity" and "effort".
indices – Indices of prims to process (shape (N,)). If not defined, all wrapped prims are processed.
dof_indices – Indices of DOFs to process (shape (D,)). If not defined, all DOFs are processed.

Raises:

AssertionError – Wrapped prims are not valid.
ValueError – Invalid control mode.

Example:

>>> # switch to 'velocity' control mode for all prims' arm DOFs (except for the fingers)
>>> prims.switch_dof_control_mode("velocity", dof_indices=np.arange(7))
>>>
>>> # switch to 'effort' control mode for all prims' fingers (last 2 DOFs)
>>> prims.switch_dof_control_mode("effort", dof_indices=[7, 8])

property dof_names: list[str]#

Degree of freedom (DOFs) names of the prims.

Backends: usd, tensor.

Returns:: Ordered list of DOF names.

Example:

>>> prims.dof_names
['panda_joint1', 'panda_joint2', 'panda_joint3',
 'panda_joint4', 'panda_joint5', 'panda_joint6',
 'panda_joint7', 'panda_finger_joint1', 'panda_finger_joint2']

property dof_paths: list[list[str]]#

Degree of freedom (DOFs) paths of the prims.

Backends: usd, tensor.

Returns:: Ordered list of DOF names.

Example:

>>> prims.dof_paths
[['/World/prim_0/panda_link0/panda_joint1', '/World/prim_0/panda_link1/panda_joint2', '/World/prim_0/panda_link2/panda_joint3',
  '/World/prim_0/panda_link3/panda_joint4', '/World/prim_0/panda_link4/panda_joint5', '/World/prim_0/panda_link5/panda_joint6',
  '/World/prim_0/panda_link6/panda_joint7', '/World/prim_0/panda_hand/panda_finger_joint1', '/World/prim_0/panda_hand/panda_finger_joint2'],
 ['/World/prim_1/panda_link0/panda_joint1', '/World/prim_1/panda_link1/panda_joint2', '/World/prim_1/panda_link2/panda_joint3',
  '/World/prim_1/panda_link3/panda_joint4', '/World/prim_1/panda_link4/panda_joint5', '/World/prim_1/panda_link5/panda_joint6',
  '/World/prim_1/panda_link6/panda_joint7', '/World/prim_1/panda_hand/panda_finger_joint1', '/World/prim_1/panda_hand/panda_finger_joint2'],
 ['/World/prim_2/panda_link0/panda_joint1', '/World/prim_2/panda_link1/panda_joint2', '/World/prim_2/panda_link2/panda_joint3',
  '/World/prim_2/panda_link3/panda_joint4', '/World/prim_2/panda_link4/panda_joint5', '/World/prim_2/panda_link5/panda_joint6',
  '/World/prim_2/panda_link6/panda_joint7', '/World/prim_2/panda_hand/panda_finger_joint1', '/World/prim_2/panda_hand/panda_finger_joint2']]

property dof_types: list[omni.physics.tensors.DofType]#

Degree of freedom (DOFs) types of the prims.

Backends: usd, tensor.

Returns:: Ordered list of DOF types.

Example:

>>> prims.dof_types
[<DofType.Rotation: 0>, <DofType.Rotation: 0>, <DofType.Rotation: 0>,
 <DofType.Rotation: 0>, <DofType.Rotation: 0>, <DofType.Rotation: 0>,
 <DofType.Rotation: 0>, <DofType.Translation: 1>, <DofType.Translation: 1>]

property is_non_root_articulation_link: bool#

Indicate if the wrapped prims are a non-root link in an articulation tree.

Backends: usd.

Warning

Transformation of the poses of non-root links in an articulation tree are not supported.

Returns:: Whether the prims are a non-root link in an articulation tree.

property jacobian_matrix_shape: tuple[int, int, int]#

Jacobian matrix shape.

Backends: tensor.

The Jacobian matrix shape depends on the number of links, DOFs, and whether the articulation base is fixed (e.g.: robotic manipulators) or not (e.g.: mobile robots).

Fixed articulation base: (num_links - 1, 6, num_dofs)
Non-fixed (floating) articulation base: (num_links, 6, num_dofs + 6)

Each link has 6 values in the Jacobian representing its linear and angular motion along the three coordinate axes. The extra 6 DOFs in the last dimension, for floating bases, correspond to the linear and angular degrees of freedom of the free root link.

Returns:: Shape of Jacobian matrix (for one prim).
Raises:: AssertionError – Physics tensor entity is not valid.

Example:

>>> # for the Franka Panda (a robotic manipulator with fixed base):
>>> # - num_links: 11
>>> # - num_dofs: 9
>>> prims.jacobian_matrix_shape
(10, 6, 9)

property joint_names: list[str]#

Joint names of the prims.

Backends: usd, tensor.

Returns:: Ordered list of joint names.

Example:

>>> prims.joint_names
['panda_joint1', 'panda_joint2', 'panda_joint3', 'panda_joint4',
 'panda_joint5', 'panda_joint6', 'panda_joint7',
 'panda_hand_joint', 'panda_finger_joint1', 'panda_finger_joint2']

property joint_paths: list[list[str]]#

Joint paths of the prims.

Backends: usd, tensor.

Returns:: Ordered list of joint paths.

Example:

>>> prims.joint_paths
[['/World/prim_0/panda_link0/panda_joint1', '/World/prim_0/panda_link1/panda_joint2', '/World/prim_0/panda_link2/panda_joint3',
  '/World/prim_0/panda_link3/panda_joint4', '/World/prim_0/panda_link4/panda_joint5', '/World/prim_0/panda_link5/panda_joint6',
  '/World/prim_0/panda_link6/panda_joint7', '/World/prim_0/panda_link7/panda_hand_joint',
  '/World/prim_0/panda_hand/panda_finger_joint1', '/World/prim_0/panda_hand/panda_finger_joint2'],
 ['/World/prim_1/panda_link0/panda_joint1', '/World/prim_1/panda_link1/panda_joint2', '/World/prim_1/panda_link2/panda_joint3',
  '/World/prim_1/panda_link3/panda_joint4', '/World/prim_1/panda_link4/panda_joint5', '/World/prim_1/panda_link5/panda_joint6',
  '/World/prim_1/panda_link6/panda_joint7', '/World/prim_1/panda_link7/panda_hand_joint',
  '/World/prim_1/panda_hand/panda_finger_joint1', '/World/prim_1/panda_hand/panda_finger_joint2'],
 ['/World/prim_2/panda_link0/panda_joint1', '/World/prim_2/panda_link1/panda_joint2', '/World/prim_2/panda_link2/panda_joint3',
  '/World/prim_2/panda_link3/panda_joint4', '/World/prim_2/panda_link4/panda_joint5', '/World/prim_2/panda_link5/panda_joint6',
  '/World/prim_2/panda_link6/panda_joint7', '/World/prim_2/panda_link7/panda_hand_joint',
  '/World/prim_2/panda_hand/panda_finger_joint1', '/World/prim_2/panda_hand/panda_finger_joint2']]

property joint_types: list[omni.physics.tensors.JointType]#

Joint types of the prims.

Backends: tensor.

Returns:: Ordered list of joint types.
Raises:: AssertionError – Physics tensor entity is not initialized.

Example:

>>> prims.joint_types
[<JointType.Revolute: 1>, <JointType.Revolute: 1>, <JointType.Revolute: 1>, <JointType.Revolute: 1>,
 <JointType.Revolute: 1>, <JointType.Revolute: 1>, <JointType.Revolute: 1>,
 <JointType.Fixed: 0>, <JointType.Prismatic: 2>, <JointType.Prismatic: 2>]

property link_names: list[str]#

Link names of the prims.

Backends: usd, tensor.

Returns:: Ordered list of link names.

Example:

>>> prims.link_names
['panda_link0', 'panda_link1', 'panda_link2', 'panda_link3',
 'panda_link4', 'panda_link5', 'panda_link6', 'panda_link7',
 'panda_hand', 'panda_leftfinger', 'panda_rightfinger']

property link_paths: list[list[str]]#

Link paths of the prims.

Backends: usd, tensor.

Returns:: Ordered list of link paths.

Example:

>>> prims.link_paths
[['/World/prim_0/panda_link0', '/World/prim_0/panda_link1', '/World/prim_0/panda_link2', '/World/prim_0/panda_link3',
  '/World/prim_0/panda_link4', '/World/prim_0/panda_link5', '/World/prim_0/panda_link6', '/World/prim_0/panda_link7',
  '/World/prim_0/panda_hand', '/World/prim_0/panda_leftfinger', '/World/prim_0/panda_rightfinger'],
 ['/World/prim_1/panda_link0', '/World/prim_1/panda_link1', '/World/prim_1/panda_link2', '/World/prim_1/panda_link3',
  '/World/prim_1/panda_link4', '/World/prim_1/panda_link5', '/World/prim_1/panda_link6', '/World/prim_1/panda_link7',
  '/World/prim_1/panda_hand', '/World/prim_1/panda_leftfinger', '/World/prim_1/panda_rightfinger'],
 ['/World/prim_2/panda_link0', '/World/prim_2/panda_link1', '/World/prim_2/panda_link2', '/World/prim_2/panda_link3',
  '/World/prim_2/panda_link4', '/World/prim_2/panda_link5', '/World/prim_2/panda_link6', '/World/prim_2/panda_link7',
  '/World/prim_2/panda_hand', '/World/prim_2/panda_leftfinger', '/World/prim_2/panda_rightfinger']]

property mass_matrix_shape: tuple[int, int]#

Mass matrix shape.

Backends: tensor.

The mass matrix shape depends on the number of DOFs, and whether the articulation base is fixed (e.g.: robotic manipulators) or not (e.g.: mobile robots).

Fixed articulation base: (num_dofs, num_dofs)
Non-fixed (floating) articulation base: (num_dofs + 6, num_dofs + 6)

Returns:: Shape of mass matrix (for one prim).
Raises:: AssertionError – Physics tensor entity is not valid.

Example:

>>> # for the Franka Panda:
>>> # - num_dofs: 9
>>> prims.mass_matrix_shape
(9, 9)

property num_dofs: int#

Number of degrees of freedom (DOFs) of the prims.

Backends: usd, tensor.

Returns:: Number of DOFs.

Example:

>>> prims.num_dofs
9

property num_fixed_tendons: int#

Number of fixed tendons of the prims.

Backends: tensor.

Returns:: Number of fixed tendons.
Raises:: AssertionError – Physics tensor entity is not initialized.

Example:

>>> prims.num_fixed_tendons
0

property num_joints: int#

Number of joints of the prims.

Backends: usd, tensor.

Returns:: Number of joints.

Example:

>>> prims.num_joints
10

property num_links: int#

Number of links of the prims.

Backends: usd, tensor.

Returns:: Number of links.

Example:

>>> prims.num_links
11

property num_shapes: int#

Number of rigid shapes of the prims.

Backends: tensor.

Returns:: Number of rigid shapes.
Raises:: AssertionError – Physics tensor entity is not initialized.

Example:

>>> prims.num_shapes
13

property paths: list[str]#

Prim paths in the stage encapsulated by the wrapper.

Returns:: List of prim paths as strings.

Example:

>>> prims.paths
['/World/prim_0', '/World/prim_1', '/World/prim_2']

property prims: list[pxr.Usd.Prim]#

USD Prim objects encapsulated by the wrapper.

Returns:: List of USD Prim objects.

Example:

>>> prims.prims
[Usd.Prim(</World/prim_0>), Usd.Prim(</World/prim_1>), Usd.Prim(</World/prim_2>)]

property valid: bool#

Whether all prims in the wrapper are valid.

Returns:: True if all prim paths specified in the wrapper correspond to valid prims in stage, False otherwise.

Example:

>>> prims.valid
True

Utilities (controllers)#

pid_control(target: float, current: float, kp: float = 0.1) → float#

Compute proportional control output for speed tracking.

Parameters:

target – Desired speed in m/s.
current – Current speed in m/s.
kp – Proportional gain.

Returns:

Control output (acceleration command).

class QuinticPolynomial( xs: float, vxs: float, axs: float, xe: float, vxe: float, axe: float, time: float, )#

Bases: object

Quintic (5th-order) polynomial for one-dimensional trajectory interpolation.

Solves for coefficients a0..a5 that satisfy the boundary conditions on position, velocity, and acceleration at times 0 and time.

Parameters:

xs – Start position.
vxs – Start velocity.
axs – Start acceleration.
xe – End position.
vxe – End velocity.
axe – End acceleration.
time – Duration of the segment in seconds.

calc_first_derivative(t: float) → float#

Evaluate the first derivative (velocity) at time t.

Parameters:: t – Time in seconds.
Returns:: Velocity at time t.

calc_point(t: float) → float#

Evaluate the polynomial at time t.

Parameters:: t – Time in seconds.
Returns:: Position at time t.

calc_second_derivative(t: float) → float#

Evaluate the second derivative (acceleration) at time t.

Parameters:: t – Time in seconds.
Returns:: Acceleration at time t.

calc_third_derivative(t: float) → float#

Evaluate the third derivative (jerk) at time t.

Parameters:: t – Time in seconds.
Returns:: Jerk at time t.

quintic_polynomials_planner( sx: float, sy: float, syaw: float, sv: float, sa: float, gx: float, gy: float, gyaw: float, gv: float, ga: float, max_accel: float, max_jerk: float, dt: float, ) → tuple[list[float], list[float], list[float], list[float], list[float], list[float], list[float]]#

Plan a trajectory using quintic polynomials between start and goal states.

Parameters:

sx – Start x position in m.
sy – Start y position in m.
syaw – Start yaw angle in rad.
sv – Start velocity in m/s.
sa – Start acceleration in m/s^2.
gx – Goal x position in m.
gy – Goal y position in m.
gyaw – Goal yaw angle in rad.
gv – Goal velocity in m/s.
ga – Goal acceleration in m/s^2.
max_accel – Maximum acceleration in m/s^2.
max_jerk – Maximum jerk in m/s^3.
dt – Time tick in s.

Returns:

Tuple of (time, rx, ry, ryaw, rv, ra, rj) lists for the planned trajectory.

stanley_control( state: State, cx: list[float], cy: list[float], cyaw: list[float], last_target_idx: int, p: float = 0.5, i: float = 0.01, d: float = 10.0, k: float = 0.5, ) → tuple[float, int]#

Compute the Stanley steering control output.

Parameters:

state – Current vehicle state.
cx – Reference path x-coordinates.
cy – Reference path y-coordinates.
cyaw – Reference path yaw angles.
last_target_idx – Previous target index on the path.
p – Proportional gain (unused, reserved for PID extension).
i – Integral gain (unused, reserved for PID extension).
d – Derivative gain (unused, reserved for PID extension).
k – Cross-track error gain.

Returns:

Tuple of (steering_angle, target_index).