Python API#

Authoring (USD prim)

`Contact`	Authoring wrapper for an Isaac contact sensor USD prim.
`IMU`	Authoring wrapper for an Isaac IMU sensor USD prim.
`Raycast`	Authoring wrapper for an Isaac raycast sensor USD prim.

Sensors (runtime)

`ContactSensor`	Runtime wrapper for an Isaac contact sensor with frame-based data access.
`EffortSensorReading`	Effort sensor reading data.
`EffortSensor`	Sensor for measuring joint effort (torque/force).
`IMUSensor`	Runtime wrapper for an Isaac IMU sensor with frame-based data access.
`JointStateSensorReading`	Joint state sensor reading data for all DOFs of an articulation.
`JointStateSensor`	Sensor for reading all DOF joint states from an articulation.
`RaycastSensor`	Runtime wrapper for an Isaac raycast sensor with frame-based data access.

Authoring#

Bases: _PhysicsSensorAuthoring

Authoring wrapper for an Isaac contact sensor USD prim.

Creates or wraps an IsaacContactSensor prim. Use this class when you only need to author the prim (set transforms, configure thresholds and radius) without bringing up the C++ backend. For data acquisition, use ContactSensor.

Parameters:

path – USD path where the sensor should be located.
positions – World-frame positions (shape (N, 3)). Mutually exclusive with translations.
translations – Local-frame translations (shape (N, 3)).
orientations – Orientations as wxyz quaternions (shape (N, 4)).
scales – Local scales forwarded to XformPrim.
reset_xform_op_properties – Whether to reset existing xform op properties.
min_threshold – Minimum force threshold in Newtons. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
max_threshold – Maximum force threshold in Newtons. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
radius – Contact detection radius. Negative means no radius filtering. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
color – Sensor visualization color as RGBA. Applied only when creating a new prim.

Raises:

ValueError – If the sensor does not have an enabled rigid-body ancestor.

Example:

>>> from isaacsim.sensors.experimental.physics import Contact
>>>
>>> contact = Contact.create(
...     "/World/Robot/foot/contact_sensor",
...     min_threshold=1.0,
...     max_threshold=1000.0,
...     translations=[[0.0, 0.0, 0.0]],
... )  

Apply physics materials to the prims, optionally preserving descendant bindings.

Backends: usd.

Parameters:

materials – Physics 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 indicating whether descendant bindings take precedence (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 RigidBodyMaterial
>>>
>>> material = RigidBodyMaterial("/World/material/rubber", static_frictions=[0.9])
>>> prims.apply_physics_materials(material, weaker_than_descendants=True)

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

Backends: usd.

Parameters:

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)

classmethod create(

path: str,

**kwargs: Any,

) → _PhysicsSensorAuthoring#

Create a new sensor at the specified path.

Always creates a fresh prim, auto-numbering the path if it already exists (e.g. /World/Cube/Sensor → /World/Cube/Sensor_01).

Parameters:

path – Full USD path for the sensor (e.g. /World/Robot/body/sensor). Trailing slashes are stripped.
**kwargs – Sensor-specific keyword arguments forwarded to __init__.

Returns:

New authoring instance wrapping the created prim.

Raises:

RuntimeError – If the path does not include a parent prim.

static ensure_api(

prims: list[Usd.Prim],

api: type,

*args: Any,

**kwargs: Any,

) → 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. For the api is multi-apply, instance name must be provided as the first argument in *args.

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.

Raises:

ValueError – If the API schema is multi-apply, but no instance name is provided.

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)

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 (positions and orientations) of the prims.

Backends: usd.

Parameters:

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

Returns:

Two-elements tuple. 1) The default positions in the world frame (shape (N, 3)). 2) The default orientations in the world frame (shape (N, 4), quaternion wxyz). If the default state is not set using the set_default_state() method, None is returned.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – If prims are non-root articulation links.

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

Get the poses (translations and orientations) in the local frame 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:: Two-elements tuple. 1) The translations in the local frame (shape (N, 3)). 2) The 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 | ndarray | array | None = None, ) → 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_max_threshold() → float | None#

Maximum force threshold in Newtons.

Returns:: Maximum threshold in Newtons, or None if not set.

get_min_threshold() → float | None#

Minimum force threshold in Newtons.

Returns:: Minimum threshold in Newtons, or None if not set.

get_radius() → float | None#

Get the contact detection radius.

Returns:: Radius in stage units. Negative means no radius filtering.

get_visibilities( *, indices: int | list | ndarray | array | None = None, ) → 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 | ndarray | array | None = None, ) → tuple[array, array]#

Get the poses (positions and orientations) in the world frame 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:: Two-elements tuple. 1) The positions in the world frame (shape (N, 3)). 2) The 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))

get_world_scales( *, indices: int | list | ndarray | array | None = None, ) → array#

Get the scales in the world frame 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 the world scales of all prims
>>> scales = prims.get_world_scales()
>>> scales.shape
(3, 3)
>>>
>>> # get the world scale of the first prim
>>> scales = prims.get_world_scales(indices=[0])
>>> scales.shape
(1, 3)

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

Reset the prims to the specified default state.

Backends: usd, usdrt, fabric.

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).

Warning

This method has no effect on non-root articulation links or 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.

Example:

>>> # get default state (no default state set at this point)
>>> prims.get_default_state()
(None, None)
>>>
>>> # set default state
>>> # - random positions for each prim
>>> # - same fixed orientation for all prim
>>> positions = np.random.uniform(low=-1, high=1, size=(3, 3))
>>> prims.set_default_state(positions, orientations=[1.0, 0.0, 0.0, 0.0])
>>>
>>> # get default state (default state is set)
>>> prims.get_default_state()
(array(shape=(3, 3), dtype=float32), array(shape=(3, 4), 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.

USD Xform schema supports a wide range of transformation operation types. This method ensures that each wrapped 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 (positions and orientations) 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 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 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.
AssertionError – If prims are non-root articulation links.

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

Backends: usd, usdrt, fabric.

Note

This method teleports prims to the specified poses.

Parameters:

translations – 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 – 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 random poses for all prims
>>> translations = np.random.uniform(low=-1, high=1, size=(3, 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_max_threshold(value: float) → None#

Set the maximum force threshold.

Contact forces are clamped to this maximum value.

Parameters:: value – Threshold in Newtons.

set_min_threshold(value: float) → None#

Set the minimum force threshold.

Contacts with force below this threshold are ignored.

Parameters:: value – Threshold in Newtons.

set_radius(value: float) → None#

Set the contact detection radius.

Parameters:: value – Radius in stage units. Use negative to disable radius filtering.

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 poses (positions and orientations) in the world frame of the prims.

Backends: usd, usdrt, fabric.

Note

This method teleports prims to the specified poses.

Parameters:

positions – 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 – 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 random poses for all prims
>>> positions = np.random.uniform(low=-1, high=1, size=(3, 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)

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 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

Bases: _PhysicsSensorAuthoring

Authoring wrapper for an Isaac IMU sensor USD prim.

Creates or wraps an IsaacImuSensor prim. Use this class when you only need to author the prim (set transforms, configure filter widths) without bringing up the C++ backend. For data acquisition, use IMUSensor.

Parameters:

path – USD path where the sensor should be located.
positions – World-frame positions (shape (N, 3)). Mutually exclusive with translations.
translations – Local-frame translations (shape (N, 3)).
orientations – Orientations as wxyz quaternions (shape (N, 4)).
scales – Local scales forwarded to XformPrim.
reset_xform_op_properties – Whether to reset existing xform op properties.
linear_acceleration_filter_size – Rolling average window for acceleration. Applied only when creating a new prim; ignored when wrapping an existing one.
angular_velocity_filter_size – Rolling average window for angular velocity. Applied only when creating a new prim; ignored when wrapping an existing one.
orientation_filter_size – Rolling average window for orientation. Applied only when creating a new prim; ignored when wrapping an existing one.

Example:

>>> from isaacsim.sensors.experimental.physics import IMU
>>>
>>> imu = IMU.create(
...     "/World/Robot/body/imu",
...     translations=[[0.0, 0.0, 0.0]],
...     orientations=[[1.0, 0.0, 0.0, 0.0]],
...     linear_acceleration_filter_size=5,
... )  

Apply physics materials to the prims, optionally preserving descendant bindings.

Backends: usd.

Parameters:

materials – Physics 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 indicating whether descendant bindings take precedence (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 RigidBodyMaterial
>>>
>>> material = RigidBodyMaterial("/World/material/rubber", static_frictions=[0.9])
>>> prims.apply_physics_materials(material, weaker_than_descendants=True)

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

Backends: usd.

Parameters:

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)

classmethod create(

path: str,

**kwargs: Any,

) → _PhysicsSensorAuthoring#

Create a new sensor at the specified path.

Always creates a fresh prim, auto-numbering the path if it already exists (e.g. /World/Cube/Sensor → /World/Cube/Sensor_01).

Parameters:

path – Full USD path for the sensor (e.g. /World/Robot/body/sensor). Trailing slashes are stripped.
**kwargs – Sensor-specific keyword arguments forwarded to __init__.

Returns:

New authoring instance wrapping the created prim.

Raises:

RuntimeError – If the path does not include a parent prim.

static ensure_api(

prims: list[Usd.Prim],

api: type,

*args: Any,

**kwargs: Any,

) → 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. For the api is multi-apply, instance name must be provided as the first argument in *args.

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.

Raises:

ValueError – If the API schema is multi-apply, but no instance name is provided.

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)

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 (positions and orientations) of the prims.

Backends: usd.

Parameters:

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

Returns:

Two-elements tuple. 1) The default positions in the world frame (shape (N, 3)). 2) The default orientations in the world frame (shape (N, 4), quaternion wxyz). If the default state is not set using the set_default_state() method, None is returned.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – If prims are non-root articulation links.

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

Get the poses (translations and orientations) in the local frame 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:: Two-elements tuple. 1) The translations in the local frame (shape (N, 3)). 2) The 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 | ndarray | array | None = None, ) → 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_visibilities( *, indices: int | list | ndarray | array | None = None, ) → 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 | ndarray | array | None = None, ) → tuple[array, array]#

Get the poses (positions and orientations) in the world frame 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:: Two-elements tuple. 1) The positions in the world frame (shape (N, 3)). 2) The 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))

get_world_scales( *, indices: int | list | ndarray | array | None = None, ) → array#

Get the scales in the world frame 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 the world scales of all prims
>>> scales = prims.get_world_scales()
>>> scales.shape
(3, 3)
>>>
>>> # get the world scale of the first prim
>>> scales = prims.get_world_scales(indices=[0])
>>> scales.shape
(1, 3)

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

Reset the prims to the specified default state.

Backends: usd, usdrt, fabric.

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).

Warning

This method has no effect on non-root articulation links or 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.

Example:

>>> # get default state (no default state set at this point)
>>> prims.get_default_state()
(None, None)
>>>
>>> # set default state
>>> # - random positions for each prim
>>> # - same fixed orientation for all prim
>>> positions = np.random.uniform(low=-1, high=1, size=(3, 3))
>>> prims.set_default_state(positions, orientations=[1.0, 0.0, 0.0, 0.0])
>>>
>>> # get default state (default state is set)
>>> prims.get_default_state()
(array(shape=(3, 3), dtype=float32), array(shape=(3, 4), 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.

USD Xform schema supports a wide range of transformation operation types. This method ensures that each wrapped 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 (positions and orientations) 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 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 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.
AssertionError – If prims are non-root articulation links.

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

Backends: usd, usdrt, fabric.

Note

This method teleports prims to the specified poses.

Parameters:

translations – 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 – 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 random poses for all prims
>>> translations = np.random.uniform(low=-1, high=1, size=(3, 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 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 poses (positions and orientations) in the world frame of the prims.

Backends: usd, usdrt, fabric.

Note

This method teleports prims to the specified poses.

Parameters:

positions – 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 – 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 random poses for all prims
>>> positions = np.random.uniform(low=-1, high=1, size=(3, 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)

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 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

Bases: _PhysicsSensorAuthoring

Authoring wrapper for an Isaac raycast sensor USD prim.

Creates or wraps an IsaacRaycastSensor prim. Use this class when you only need to author the prim (set transforms, configure ray geometry) without bringing up the C++ backend. For data acquisition, use RaycastSensor.

Parameters:

path – USD path where the sensor should be located.
positions – World-frame positions (shape (N, 3)). Mutually exclusive with translations.
translations – Local-frame translations (shape (N, 3)).
orientations – Orientations as wxyz quaternions (shape (N, 4)).
scales – Local scales forwarded to XformPrim.
reset_xform_op_properties – Whether to reset existing xform op properties.
min_range – Minimum detection range in stage length units. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
max_range – Maximum detection range in stage length units. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
ray_origins – Per-ray origin translations as Nx3 array. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
ray_directions – Per-ray direction vectors as Nx3 array. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
ray_time_offsets – Per-ray time offsets in seconds. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
output_frame – Output coordinate frame ("SENSOR" or "WORLD"). When wrapping an existing prim, applied as an override; None leaves the prim unchanged.
report_hit_prim_paths – Whether to resolve hit prim USD paths. When wrapping an existing prim, applied as an override; None leaves the prim unchanged.

Example:

>>> from isaacsim.sensors.experimental.physics import Raycast
>>>
>>> raycast = Raycast.create(
...     "/World/Robot/body/raycast",
...     ray_origins=[[0, 0, 0]],
...     ray_directions=[[1, 0, 0]],
...     translations=[[0.0, 0.0, 0.0]],
... )  

Apply physics materials to the prims, optionally preserving descendant bindings.

Backends: usd.

Parameters:

materials – Physics 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 indicating whether descendant bindings take precedence (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 RigidBodyMaterial
>>>
>>> material = RigidBodyMaterial("/World/material/rubber", static_frictions=[0.9])
>>> prims.apply_physics_materials(material, weaker_than_descendants=True)

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

Backends: usd.

Parameters:

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)

classmethod create(

path: str,

**kwargs: Any,

) → _PhysicsSensorAuthoring#

Create a new sensor at the specified path.

Always creates a fresh prim, auto-numbering the path if it already exists (e.g. /World/Cube/Sensor → /World/Cube/Sensor_01).

Parameters:

path – Full USD path for the sensor (e.g. /World/Robot/body/sensor). Trailing slashes are stripped.
**kwargs – Sensor-specific keyword arguments forwarded to __init__.

Returns:

New authoring instance wrapping the created prim.

Raises:

RuntimeError – If the path does not include a parent prim.

static ensure_api(

prims: list[Usd.Prim],

api: type,

*args: Any,

**kwargs: Any,

) → 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. For the api is multi-apply, instance name must be provided as the first argument in *args.

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.

Raises:

ValueError – If the API schema is multi-apply, but no instance name is provided.

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)

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 (positions and orientations) of the prims.

Backends: usd.

Parameters:

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

Returns:

Two-elements tuple. 1) The default positions in the world frame (shape (N, 3)). 2) The default orientations in the world frame (shape (N, 4), quaternion wxyz). If the default state is not set using the set_default_state() method, None is returned.

Raises:

AssertionError – Wrapped prims are not valid.
AssertionError – If prims are non-root articulation links.

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

Get the poses (translations and orientations) in the local frame 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:: Two-elements tuple. 1) The translations in the local frame (shape (N, 3)). 2) The 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 | ndarray | array | None = None, ) → 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_visibilities( *, indices: int | list | ndarray | array | None = None, ) → 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 | ndarray | array | None = None, ) → tuple[array, array]#

Get the poses (positions and orientations) in the world frame 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:: Two-elements tuple. 1) The positions in the world frame (shape (N, 3)). 2) The 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))

get_world_scales( *, indices: int | list | ndarray | array | None = None, ) → array#

Get the scales in the world frame 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 the world scales of all prims
>>> scales = prims.get_world_scales()
>>> scales.shape
(3, 3)
>>>
>>> # get the world scale of the first prim
>>> scales = prims.get_world_scales(indices=[0])
>>> scales.shape
(1, 3)

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

Reset the prims to the specified default state.

Backends: usd, usdrt, fabric.

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).

Warning

This method has no effect on non-root articulation links or 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.

Example:

>>> # get default state (no default state set at this point)
>>> prims.get_default_state()
(None, None)
>>>
>>> # set default state
>>> # - random positions for each prim
>>> # - same fixed orientation for all prim
>>> positions = np.random.uniform(low=-1, high=1, size=(3, 3))
>>> prims.set_default_state(positions, orientations=[1.0, 0.0, 0.0, 0.0])
>>>
>>> # get default state (default state is set)
>>> prims.get_default_state()
(array(shape=(3, 3), dtype=float32), array(shape=(3, 4), 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.

USD Xform schema supports a wide range of transformation operation types. This method ensures that each wrapped 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 (positions and orientations) 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 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 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.
AssertionError – If prims are non-root articulation links.

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

Backends: usd, usdrt, fabric.

Note

This method teleports prims to the specified poses.

Parameters:

translations – 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 – 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 random poses for all prims
>>> translations = np.random.uniform(low=-1, high=1, size=(3, 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 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 poses (positions and orientations) in the world frame of the prims.

Backends: usd, usdrt, fabric.

Note

This method teleports prims to the specified poses.

Parameters:

positions – 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 – 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 random poses for all prims
>>> positions = np.random.uniform(low=-1, high=1, size=(3, 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)

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 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

Sensors#

class ContactSensor( path: str | Contact, )#

Bases: _PhysicsSensorRuntime

Runtime wrapper for an Isaac contact sensor with frame-based data access.

Wraps a Contact authoring object and owns the C++ IContactSensor Carbonite interface. Exposes get_data() for a structured per-step dictionary, get_sensor_reading() for the cached ContactSensorReading, and get_raw_data() for raw contact records.

Parameters:: path – Either a string USD path to an existing IsaacContactSensor prim, or a pre-built Contact authoring object. To create a new prim, use Contact.create().

Example:

from isaacsim.sensors.experimental.physics import Contact, ContactSensor

sensor = ContactSensor(
    Contact.create(
        "/World/Robot/foot/contact_sensor",
        min_threshold=1.0,
        max_threshold=1000.0,
        radius=0.05,
    )
)

frame = sensor.get_data()
if frame["in_contact"]:
    print(f"Contact force: {frame['force']}")

add_raw_contact_data_to_frame() → None#

Enable raw contact data in frame output.

After calling this, get_data() will include a "contacts" list with detailed per-contact information.

get_data() → dict#

Get the current contact sensor data as a structured frame.

Returns:

"in_contact": Whether contact is detected.
"force": Contact force magnitude.
"time": Simulation time of reading.
"physics_step": Physics step number.
"number_of_contacts": Number of contact points.
"contacts": Raw contact data if enabled via add_raw_contact_data_to_frame.

Return type:

Newly allocated frame data, independent of any other call, containing

Note

The frame is refreshed only on a valid reading; otherwise the previous values are returned. Use get_sensor_reading() and check is_valid to tell them apart.

"contacts" is rebuilt only on a valid reading, so a returned frame shares that list with the sensor until the next one. Treat it as read-only.

get_raw_data() → list[dict[str, object]]#

Get raw contact data for the sensor’s parent body.

Returns:: Raw contact dictionaries containing body0, body1, position, normal, impulse, time, and dt fields. Empty when the sensor is invalid.

get_sensor_reading() → ContactSensorReading#

Get the latest cached contact sensor reading.

Returns:: Reading with contact state and force value. Returns an invalid reading if the sensor is disabled or the prim is invalid.

on_physics_step(step_dt: float) → None#

Called by _SensorStepManager after each physics step.

Reads the latest C++ sensor reading and caches it locally.

Parameters:: step_dt – Duration of the physics step in seconds.

on_timeline_stop() → None#: Reset sensor state when the timeline stops.

remove_raw_contact_data_from_frame() → None#

Disable raw contact data in frame output.

Removes the "contacts" key from frame output to reduce overhead.

reset() → None#: Remove the sensor from the simulation and reset state.

property authoring_object: _PhysicsSensorAuthoring#

Authoring object encapsulated by this sensor.

Returns:: The authoring object (e.g. IMU, Contact, Raycast) wrapping the underlying USD prim.

property contact: Contact#

Authoring object encapsulated by this sensor.

Returns:: The Contact instance wrapping the underlying USD prim.

class EffortSensorReading( is_valid: bool = False, time: float = 0, value: float = 0, )#

Bases: object

Effort sensor reading data.

Parameters:

is_valid – Whether this reading contains valid data.
time – Simulation time when the reading was taken.
value – Effort (torque/force) value at the joint.

class EffortSensor(path: str, enabled: bool = True)#

Bases: _PhysicsSensorRuntimeBase

Sensor for measuring joint effort (torque/force).

Owns the C++ IEffortSensor Carbonite interface directly and maintains a Python-side circular buffer of readings for historical access. Newton does not currently expose projected joint forces, so readings are invalid while Newton is active.

Parameters:

path – USD path to the joint, formatted as articulation_path/joint_name.
enabled – Whether the sensor is initially enabled.

Example

from isaacsim.sensors.experimental.physics import EffortSensor

# Create sensor for a robot joint
sensor = EffortSensor("/World/Robot/joint_1")

# Read joint effort
reading = sensor.get_sensor_reading()
if reading.is_valid:
    print(f"Joint torque: {reading.value}")

change_buffer_size(new_buffer_size: int) → None#

Change the size of the sensor reading buffer.

Deprecated since version 3.3.0: The reading history buffer is not consumed within Isaac Sim. This method will be removed in Isaac Sim 7.0.

Parameters:

new_buffer_size – New buffer size (number of readings to store). Must be a positive integer. Booleans are rejected, even though bool is an integer subclass.

Raises:

TypeError – If new_buffer_size is a boolean or is not an integer.
ValueError – If new_buffer_size is less than 1.

get_data() → dict#

Get the current effort sensor data as a structured frame.

Returns:

"value": Effort (torque/force) value at the joint.
"is_valid": Whether the reading contains valid data.
"time": Simulation time of the reading.
"physics_step": Physics step number.

Return type:

Frame data containing

get_sensor_reading() → EffortSensorReading#

Get the current effort sensor reading.

Returns:: Reading with effort value and validity state. The reading is invalid when the active backend does not expose projected joint forces.

on_physics_step(step_dt: float) → None#

Called after each physics step. Override for custom per-step logic.

Parameters:: step_dt – Physics step duration in seconds.

on_timeline_stop() → None#: Reset C++ interface state and clear the reading buffer.

reset() → None#: Remove the sensor from the simulation and reset state.

update_dof_name(dof_name: str) → None#

Update the DOF (degree of freedom) name being measured.

Resets the C++ sensor and rebinds the runtime to the new joint path.

Deprecated since version 3.3.0: Construct a new EffortSensor with the target joint path instead. This method will be removed in Isaac Sim 7.0.

Parameters:: dof_name – Name of the joint DOF to monitor.

class IMUSensor( path: str | IMU, )#

Bases: _PhysicsSensorRuntime

Runtime wrapper for an Isaac IMU sensor with frame-based data access.

Wraps an IMU authoring object and owns the C++ IImuSensor Carbonite interface. Exposes get_data() for a structured per-step dictionary and get_sensor_reading() for the raw C++ struct.

Parameters:: path – Either a string USD path to an existing IsaacImuSensor prim, or a pre-built IMU authoring object. To create a new prim, use IMU.create().

Example:

from isaacsim.sensors.experimental.physics import IMU, IMUSensor

# Wrap an existing IsaacImuSensor prim
sensor = IMUSensor("/World/Robot/body/imu")

# Create a new sensor with custom parameters
sensor = IMUSensor(
    IMU.create(
        "/World/Robot/body/imu",
        linear_acceleration_filter_size=5,
    )
)

frame = sensor.get_data()
print(f"Linear acceleration: {frame['linear_acceleration']}")

get_data(read_gravity: bool = True) → dict#

Get the current IMU sensor data as a structured frame.

read_gravity=True reports specific force, what an accelerometer measures: +g at rest and 0 in free fall. read_gravity=False reports coordinate acceleration: 0 at rest and -g in free fall. g is in stage linear units per second squared (981 on a centimetre stage), on the sensor axis opposing gravity.

Deprecated since version 3.2.0:
read_gravity is deprecated and still honored. IsaacComputeOdometry’s globalLinearAcceleration is gravity-free, but reports world-frame acceleration of the body rather than sensor-frame acceleration at this prim.

Parameters:

read_gravity – Whether the accelerometer channel includes the gravity reaction term.

Returns:

"linear_acceleration": Linear acceleration [x, y, z].
"angular_velocity": Angular velocity [x, y, z].
"orientation": Orientation as [w, x, y, z] quaternion.
"time": Simulation time of reading.
"physics_step": Physics step number.

Return type:

Newly allocated frame data, independent of any other call, containing

Note

The frame is refreshed only on a valid reading; otherwise the previous values are returned. Use get_sensor_reading() and check is_valid to tell them apart, or on a hot path to read the values without allocating a frame.

get_sensor_reading(read_gravity: bool = True) → object#

Get the current IMU sensor reading as the raw C++ struct.

See get_data() for what read_gravity selects.

Deprecated since version 3.2.0:
read_gravity is deprecated and still honored. IsaacComputeOdometry’s globalLinearAcceleration is gravity-free, but reports world-frame acceleration of the body rather than sensor-frame acceleration at this prim.

Parameters:: read_gravity – Whether the accelerometer channel includes the gravity reaction term.
Returns:: The C++ ImuSensorReading struct, with scalar linear_acceleration_x / _y / _z, angular_velocity_x / _y / _z, and orientation_w / _x / _y / _z fields; use get_data() for numpy arrays. A valid reading is a fresh struct, an invalid one (is_valid is False) a shared placeholder, so check is_valid before retaining it.

on_physics_step(step_dt: float) → None#

Called after each physics step. Override for custom per-step logic.

Parameters:: step_dt – Physics step duration in seconds.

on_timeline_stop() → None#: Reset sensor state when the timeline stops.

reset() → None#: Remove the sensor from the simulation and reset state.

property authoring_object: _PhysicsSensorAuthoring#

Authoring object encapsulated by this sensor.

Returns:: The authoring object (e.g. IMU, Contact, Raycast) wrapping the underlying USD prim.

property imu: IMU#

Authoring object encapsulated by this sensor.

Returns:: The IMU instance wrapping the underlying USD prim.

class JointStateSensorReading( is_valid: bool = False, time: float = 0.0, dof_names: list[str] | None = None, positions: ndarray | None = None, velocities: ndarray | None = None, efforts: ndarray | None = None, dof_types: ndarray | None = None, stage_meters_per_unit: float = 0.0, )#

Bases: object

Joint state sensor reading data for all DOFs of an articulation.

Every attribute is read-only, matching the native snapshot: a reading describes one capture, so its values do not change afterwards. The arrays and the name list are owned by the reading and their contents stay mutable.

Parameters:

is_valid – Whether this reading contains valid data.
time – Simulation time when the reading was taken.
dof_names – List of DOF name strings in articulation order.
positions – DOF positions array (rad for revolute, m for prismatic).
velocities – DOF velocities array (rad/s or m/s).
efforts – DOF efforts array (Nm or N).
dof_types – Per-DOF type: 0 = rotation (revolute), 1 = translation (prismatic).
stage_meters_per_unit – Stage meters per USD unit for SI conversion.

property dof_names: list[str]#: Mutable list of degree-of-freedom names owned by the reading.

property dof_types: ndarray#: Mutable degree-of-freedom type array owned by the reading.

property efforts: ndarray#: Mutable effort array (Nm or N) owned by the reading.

property is_valid: bool#: Whether the reading was valid when captured.

property positions: ndarray#: Mutable position array (rad or m) owned by the reading.

property stage_meters_per_unit: float#: Stage scale in meters per unit at capture time.

property time: float#: Capture time in seconds.

property velocities: ndarray#: Mutable velocity array (rad/s or m/s) owned by the reading.

class JointStateSensor(path: str, enabled: bool = True)#

Bases: _PhysicsSensorRuntimeBase

Sensor for reading all DOF joint states from an articulation.

Reads positions, velocities, and efforts for every DOF in the articulation via the C++ IJointStateSensor Carbonite interface. Analogous to a ROS2 JointState message.

Parameters:

path – USD path to the articulation root prim.
enabled – Whether the sensor is initially enabled.

Example

from isaacsim.sensors.experimental.physics import JointStateSensor

sensor = JointStateSensor("/World/Robot")

# After playing the simulation:
reading = sensor.get_sensor_reading()
if reading.is_valid:
    for name, pos in zip(reading.dof_names, reading.positions):
        print(f"{name}: {pos:.4f} rad")

get_data() → dict#

Get the current joint state as a structured frame.

Returns:

"dof_names": List of DOF names in articulation order.
"positions": Per-DOF positions (rad or m).
"velocities": Per-DOF velocities (rad/s or m/s).
"efforts": Per-DOF efforts (Nm or N).
"dof_types": Per-DOF type (0 = revolute, 1 = prismatic).
"stage_meters_per_unit": Stage meters per USD unit.
"is_valid": Whether the reading contains valid data.
"time": Simulation time of the reading.
"physics_step": Physics step number.

Return type:

Frame data containing

get_sensor_reading() → JointStateSensorReading#

Get a mutable owned snapshot of the joint state for all DOFs.

The snapshot and its NumPy arrays remain valid after later physics steps, sensor reset, or removal. Its values and is_valid flag do not change after capture.

Returns:: Reading with DOF names, positions, velocities, efforts, and validity.

get_sensor_reading_view() → object#

Get a read-only zero-copy view of the live joint-state buffers.

Numeric arrays returned from the view retain its native backing frame even if the view variable is released. Their values and view.time update on each physics step. view.is_valid becomes False after reset, removal, or timeline stop; retained arrays then remain readable with their last values. A numeric property lookup creates a NumPy array header without copying data; cache the returned array in a tight loop.

The view performs no synchronization with the physics step that writes its buffers, so reading it while a step is in flight yields torn values that mix the current and the previous reading. Read it only from the thread that drives physics and only between steps; use get_sensor_reading() when a reader cannot be ordered against the step.

Returns:: A JointStateSensorReadingView with read-only NumPy arrays.

Example:

view = sensor.get_sensor_reading_view()
if view.is_valid:
    positions = view.positions  # read-only and owner-backed

on_physics_step(step_dt: float) → None#

Called after each physics step. Override for custom per-step logic.

Parameters:: step_dt – Physics step duration in seconds.

on_timeline_stop() → None#: Reset sensor state when the timeline stops.

reset() → None#: Remove the sensor from the simulation and reset state.

class RaycastSensor( path: str | _PhysicsSensorAuthoring, )#

Bases: _PhysicsSensorRuntime

Runtime wrapper for an Isaac raycast sensor with frame-based data access.

Wraps a Raycast authoring object and owns the C++ IRaycastSensor Carbonite interface. Exposes get_data() for a structured per-step dictionary, get_sensor_reading() for an owned snapshot, and get_sensor_reading_view() for a read-only view of live buffers.

Parameters:: path – Either a string USD path to an existing IsaacRaycastSensor prim, or a pre-built Raycast authoring object. To create a new prim, use Raycast.create().

Example:

from isaacsim.sensors.experimental.physics import Raycast, RaycastSensor

sensor = RaycastSensor(
    Raycast.create(
        "/World/Robot/body/raycast",
        ray_origins=[[0, 0, 0]],
        ray_directions=[[1, 0, 0]],
    )
)

frame = sensor.get_data()
print(f"Depths: {frame['depths']}")

get_data() → dict#

Get the current raycast sensor data as a structured frame.

Returns:

"depths": Per-ray depth values.
"hit_positions": Per-ray hit positions as Nx3 array.
"hit_normals": Per-ray surface normals as Nx3 array.
"hit_prim_paths": Per-ray hit prim USD paths.
"time": Simulation time of reading.
"physics_step": Physics step number.

Return type:

Frame data containing

get_sensor_reading() → object#

Get a mutable owned snapshot of the current raycast reading.

The snapshot and its NumPy arrays remain valid after later physics steps, sensor reset, or removal. Its values and is_valid flag do not change after capture.

Returns:: An owned RaycastSensorReading snapshot. Access fields via reading.depths, reading.hit_positions, and related properties.

get_sensor_reading_view() → object#

Get a read-only zero-copy view of the live raycast buffers.

Numeric arrays returned from the view retain its native backing frame even if the view variable is released. Their values and view.time update on each physics step. view.is_valid becomes False after reset, removal, or timeline stop; retained arrays then remain readable with their last values. A numeric property lookup creates a NumPy array header without copying data; cache the returned array in a tight loop.

The view performs no synchronization with the physics step that writes its buffers, so reading it while a step is in flight yields torn values that mix the current and the previous reading. Read it only from the thread that drives physics and only between steps; use get_sensor_reading() when a reader cannot be ordered against the step.

Returns:: A RaycastSensorReadingView with read-only NumPy arrays.

Example:

view = sensor.get_sensor_reading_view()
if view.is_valid:
    depths = view.depths  # read-only and owner-backed

on_physics_step(step_dt: float) → None#

Called after each physics step. Override for custom per-step logic.

Parameters:: step_dt – Physics step duration in seconds.

on_timeline_stop() → None#: Reset sensor state when the timeline stops.

reset() → None#: Remove the sensor from the simulation and reset state.

property authoring_object: _PhysicsSensorAuthoring#

Authoring object encapsulated by this sensor.

Returns:: The authoring object (e.g. IMU, Contact, Raycast) wrapping the underlying USD prim.

property raycast: Raycast#

Authoring object encapsulated by this sensor.

Returns:: The Raycast instance wrapping the underlying USD prim.