[isaacsim.core.api] Isaac Sim Core#

Warning

Deprecation: Extension deprecated since Isaac Sim 6.0.0 in favor of the Core Experimental extensions: isaacsim.core.experimental.*

Version: 5.3.2

Overview#

Deprecated since version 6.0.0: This extension is deprecated in favor of the Core Experimental extensions: isaacsim.core.experimental.*.

The isaacsim.core.api extension provides the legacy Isaac Sim core layer for controlling simulation state and physics scenes. It also supports working with USD objects, physics materials, and visual materials in Isaac Sim workflows.

New work should use the Core Experimental extensions under isaacsim.core.experimental.*. Use isaacsim.core.api only when maintaining existing workflows that still depend on the older core behavior.

Key Components#

Simulation control#

World is the main entry point for most workflows. It extends SimulationContext with a managed Scene, task registration, observations, metrics, and a data logger.
SimulationContext controls the simulation lifecycle (play, pause, stop, step, reset) and manages physics, stage, timeline, and render callbacks.
PhysicsContext wraps the USD physics scene and exposes solver, GPU, gravity, and timestep settings.

from isaacsim.core.api import World
from isaacsim.core.api.objects import DynamicCuboid

world = World()
world.scene.add_default_ground_plane()
cube = world.scene.add(DynamicCuboid(prim_path="/World/Cube", name="cube"))

world.reset()
for _ in range(100):
    world.step(render=True)

Scene helpers#

The extension groups higher-level building blocks into submodules:

isaacsim.core.api.objects: visual, fixed, and dynamic primitive shapes such as DynamicCuboid, VisualSphere, FixedCylinder, DynamicCone, VisualCapsule, and GroundPlane.
isaacsim.core.api.materials: visual and physics material wrappers including VisualMaterial, PreviewSurface, OmniPBR, OmniGlass, PhysicsMaterial, ParticleMaterial, and DeformableMaterial (with matching view classes).
isaacsim.core.api.robots: Robot and RobotView.
isaacsim.core.api.controllers: BaseController, ArticulationController, and BaseGripperController.
isaacsim.core.api.tasks: BaseTask and ready-made tasks such as FollowTarget, PickPlace, and Stacking.
isaacsim.core.api.scenes: Scene and SceneRegistry.
isaacsim.core.api.sensors: BaseSensor and RigidContactView.
isaacsim.core.api.loggers: DataLogger for recording simulation data.

Prim-level state wrappers used by these helpers (rigid bodies, articulations, geometry, and so on) live in the isaacsim.core.prims extension.

Enable Extension#

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

Command-line interface

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

APP_SCRIPT.(sh|bat) --enable isaacsim.core.api

Experience/extension configuration

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

[dependencies]
"isaacsim.core.api" = {}

Extension Manager UI

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

Python API#

controllers

`ArticulationController`	PD controller of all degrees of freedom of an articulation.
`BaseController`	Abstract base class for robot controllers.
`BaseGripperController`	Abstract base class for gripper controllers.

loggers

DataLogger

Provide data collection, storage, and replay functionality for simulation data.

materials

`VisualMaterial`	Base class for visual material representations.
`PreviewSurface`	USD PreviewSurface material for basic rendering.
`OmniPBR`	OmniPBR physically-based rendering material.
`OmniGlass`	High-level wrapper for creating/encapsulating Omniverse Glass (`OmniGlass`) material prims.
`PhysicsMaterial`	Physics material for defining friction and restitution properties.
`ParticleMaterial`	A wrapper around position-based-dynamics (PBD) material for particles used to simulate fluids, cloth and inflatables.
`ParticleMaterialView`	The view class to deal with particle material prims.
`DeformableMaterial`	Stub for the removed DeformableMaterial class.
`DeformableMaterialView`	Stub for the removed DeformableMaterialView class.

objects

`GroundPlane`	High level wrapper to create or encapsulate a ground plane.
`VisualCapsule`	High-level wrapper to create or encapsulate a visual capsule.
`VisualCone`	High level wrapper to create or encapsulate a visual cone.
`VisualCuboid`	High-level wrapper to create or encapsulate a visual cuboid.
`VisualCylinder`	High-level wrapper to create or encapsulate a visual cylinder.
`VisualSphere`	High level wrapper to create or encapsulate a visual sphere.
`FixedCapsule`	High level wrapper to create or encapsulate a fixed capsule.
`FixedCone`	High-level wrapper to create or encapsulate a fixed cone.
`FixedCuboid`	High level wrapper to create/encapsulate a fixed cuboid.
`FixedCylinder`	High-level wrapper to create/encapsulate a fixed cylinder.
`FixedSphere`	High level wrapper to create/encapsulate a fixed sphere.
`DynamicCapsule`	High level wrapper to create/encapsulate a dynamic capsule.
`DynamicCone`	High-level wrapper to create or encapsulate a dynamic cone.
`DynamicCuboid`	High level wrapper to create/encapsulate a dynamic cuboid.
`DynamicCylinder`	High level wrapper to create/encapsulate a dynamic cylinder.
`DynamicSphere`	High level wrapper to create/encapsulate a dynamic sphere.

physics_context

PhysicsContext

Provide high-level functions for managing physics scene and simulation settings.

robots

`Robot`	Implementation (on `SingleArticulation` class) to deal with an articulation prim as a robot.
`RobotView`	Implementation on the `Articulation` class to deal with articulation prims as robots.

scenes

`Scene`	Provides methods to add objects of interest in the stage, retrieve their information, and reset their default state in an easy way.
`SceneRegistry`	Class to keep track of the different types of objects added to the scene.

sensors

`BaseSensor`	Provides common properties and methods to deal with prims as a sensor.
`RigidContactView`	Provides high-level functions to deal with rigid prims (one or many) that track their contacts through filters, as well as their attributes/properties.

simulation_context

SimulationContext

Provides functions for managing time-related events and simulation control.

world

World

Provide a comprehensive physics simulation world environment with scene management and task orchestration.

tasks

`BaseTask`	This class provides a way to set up a task in a scene and modularize adding objects to a stage.
`FollowTarget`	Abstract task for following a target with a robot end effector.
`PickPlace`	Abstract task for picking and placing a cube with a robot.
`Stacking`	Abstract task for stacking multiple cubes with a robot.

Controllers#

class ArticulationController#

Bases: object

PD controller of all degrees of freedom of an articulation. Can apply position targets, velocity targets, and efforts.

Check out the required tutorials at https://docs.isaacsim.omniverse.nvidia.com/latest/index.html

apply_action( control_actions: ArticulationAction, ) → None#

Apply control actions to the articulation for the next physics step.

Parameters:: control_actions – Actions to be applied for next physics step.
Raises:: RuntimeError – If the articulation view is not initialized.

get_applied_action() → ArticulationAction#

Get the last applied articulation action.

Raises:: RuntimeError – If the articulation view is not initialized.
Returns:: Last applied action.

get_effort_modes() → list[str]#

Get the effort modes for all joints.

Raises:: Exception – If the articulation view is not initialized.
Returns:: Effort mode strings for each joint.

get_gains() → tuple[ndarray, ndarray]#

Get the current PD controller gains.

Raises:: Exception – If the articulation view is not initialized.
Returns:: The current proportional and derivative gains as (kps, kds).

get_joint_limits() → ndarray | None#

Get the joint limits for all DOFs.

Raises:: Exception – If the articulation view is not initialized.
Returns:: A tuple of (lower_limits, upper_limits) arrays.

get_max_efforts() → ndarray#

Get the maximum efforts for all joints.

Raises:: Exception – If the articulation view is not initialized.
Returns:: Maximum effort values for each joint, or None if the articulation view returns no values.

initialize(articulation_view: object) → None#

Initialize the controller with an articulation view.

Parameters:: articulation_view – The articulation view to control.

set_effort_modes( mode: str, joint_indices: ndarray | list | None = None, ) → None#

Set effort modes for specified joints.

Parameters:

mode – The effort mode to set.
joint_indices – Indices of joints to set.

Raises:

Exception – If the articulation view is not initialized.

Returns:

Result from the articulation view’s set_effort_modes method.

set_gains( kps: ndarray | None = None, kds: ndarray | None = None, save_to_usd: bool = False, ) → None#

Set the PD controller gains.

Parameters:

kps – Proportional gains for each DOF.
kds – Derivative gains for each DOF.
save_to_usd – Whether to save the gains to USD.

Raises:

Exception – If the articulation view is not initialized.

set_max_efforts( values: ndarray, joint_indices: ndarray | list | None = None, ) → None#

Set maximum efforts for specified joints.

Parameters:

values – Maximum effort values to set.
joint_indices – Indices of joints to set.

Raises:

Exception – If the articulation view is not initialized.

switch_control_mode(mode: str) → None#

Switch the control mode for all DOFs.

Parameters:: mode – The control mode, such as “position”, “velocity”, or “effort”.
Raises:: Exception – If the articulation view is not initialized.

switch_dof_control_mode( dof_index: int, mode: str, ) → None#

Switch the control mode for a specific DOF.

Parameters:

dof_index – Index of the DOF to switch control mode for.
mode – The control mode, such as “position”, “velocity”, or “effort”.

Raises:

Exception – If the articulation view is not initialized.

class BaseController(name: str)#

Bases: ABC

Abstract base class for robot controllers.

Parameters:: name – Name identifier for the controller.

abstract forward(

*args: object,

**kwargs: object,

) → ArticulationAction#

Compute forward action for the given inputs.

Controllers should take inputs and return an ArticulationAction to be passed to the ArticulationController.

Parameters:

*args – Variable length argument list.
**kwargs – Arbitrary keyword arguments.

Raises:

NotImplementedError – Must be implemented by subclass.

Returns:

Action containing joint positions, velocities, or efforts to apply.

reset() → None#: Resets state of the controller.

class BaseGripperController(name: str)#

Bases: BaseController

Abstract base class for gripper controllers.

Parameters:: name – Name identifier for the controller.

abstract close( current_joint_positions: ndarray, ) → ArticulationAction#

Close the gripper.

Parameters:: current_joint_positions – Current positions of the gripper joints.
Raises:: NotImplementedError – Must be implemented by a subclass.
Returns:: Action to close the gripper.

forward( action: str, current_joint_positions: ndarray, ) → ArticulationAction#

Routes gripper actions to appropriate open or close methods.

Parameters:

action – “open” or “close”.
current_joint_positions – Current positions of the gripper joints.

Raises:

Exception – If action is not “open” or “close”.

Returns:

Action to apply to the gripper joints.

abstract open( current_joint_positions: ndarray, ) → ArticulationAction#

Open the gripper.

Parameters:: current_joint_positions – Current positions of the gripper joints.
Raises:: NotImplementedError – Must be implemented by a subclass.
Returns:: Action to open the gripper.

reset() → None#: Reset the gripper controller state.

Loggers#

class DataLogger#

Bases: object

Provide data collection, storage, and replay functionality for simulation data.

Collects simulation data at runtime and saves it to disk for later replay or analysis. Supports pausing and resuming data collection during simulation.

add_data( data: dict, current_time_step: float, current_time: float, ) → None#

Add data to the log when data collection is started.

Parameters:

data – Dictionary representing the data to be logged at this time index.
current_time_step – Time step corresponding to the data collected.
current_time – Time in seconds corresponding to the data collected.

add_data_frame_logging_func( func: Callable[[list[BaseTask], Scene], dict], ) → None#

Add a data collection function to be called at every step when the logger is started.

Parameters:

func –

Function to be called at every step when the logger is started. Should follow:

def dummy_data_collection_fn(tasks, scene):
    return {"data 1": [data]}

get_data_frame( data_frame_index: int, ) → DataFrame#

Retrieve a specific data frame from the logger.

Parameters:: data_frame_index – Index of the data frame to retrieve.
Returns:: Data frame collected at the specified data frame index.
Raises:: IndexError – If data_frame_index is outside the collected data frame range.

get_num_of_data_frames() → int#

Get the number of data frames in the logger.

Returns:: The number of data frames collected in the data logger.

is_started() → bool#

Check if data collection is currently active.

Returns:: True if data collection is started or resumed, False otherwise.

load(log_path: str) → None#

Load data from a json file to read back previously saved data or resume recording data from another time step.

Parameters:

log_path – Path of the json file to be used to load the data.

Raises:

OSError – If log_path cannot be opened or read.
json.JSONDecodeError – If log_path does not contain valid json.
KeyError – If the json data does not contain “Isaac Sim Data”.

pause() → None#: Pause data collection.

reset() → None#: Clear the data in the logger and pause data collection.

save(log_path: str) → None#

Save the current data in the logger to a json file.

Parameters:

log_path – Path of the json file to be used to save the data.

Raises:

OSError – If log_path cannot be opened or written.
TypeError – If logged data cannot be serialized to json.

start() → None#: Resume or start data collection.

Materials#

class VisualMaterial( name: str, prim_path: str, prim: pxr.Usd.Prim, shaders_list: list[pxr.UsdShade.Shader], material: pxr.UsdShade.Material, )#

Bases: object

Base class for visual material representations.

Parameters:

name – Name identifier for the material.
prim_path – USD prim path for the material.
prim – The USD prim object.
shaders_list – List of shaders used by the material.
material – The USD material object.

property material: pxr.UsdShade.Material#

USD material object associated with this VisualMaterial.

Returns:: The USD material object.

property name: str#

Material name.

Returns:: The material name.

property prim: pxr.Usd.Prim#

USD prim object for the material.

Returns:: The USD prim object.

property prim_path: str#

USD prim path for the material.

Returns:: The prim path string.

property shaders_list: list[pxr.UsdShade.Shader]#

List of shaders used by the material.

Returns:: The shaders used by the material.

class PreviewSurface( prim_path: str, name: str = 'preview_surface', shader: UsdShade.Shader | None = None, color: np.ndarray | None = None, roughness: float | None = None, metallic: float | None = None, )#

Bases: VisualMaterial

USD PreviewSurface material for basic rendering.

Parameters:

prim_path – USD prim path for the material.
name – Name identifier.
shader – Existing shader to use.
color – Diffuse color RGB.
roughness – Surface roughness (0-1).
metallic – Metallic value (0-1).

Raises:

ValueError – If the material’s shader is not of type USD Preview Surface.

get_color() → ndarray#

Get the diffuse color.

Returns:: RGB color array or None if not set.

get_metallic() → float#

Get the metallic value.

Returns:: Metallic value or None if not set.

get_roughness() → float#

Get the surface roughness.

Returns:: Roughness value or None if not set.

set_color(color: ndarray) → None#

Set the diffuse color.

Parameters:: color – RGB color array.

set_metallic(metallic: float) → None#

Set the metallic value.

Parameters:: metallic – Metallic value (0-1).

set_roughness(roughness: float) → None#

Set the surface roughness.

Parameters:: roughness – Roughness value (0-1).

property material: pxr.UsdShade.Material#

USD material object associated with this VisualMaterial.

Returns:: The USD material object.

property name: str#

Material name.

Returns:: The material name.

property prim: pxr.Usd.Prim#

USD prim object for the material.

Returns:: The USD prim object.

property prim_path: str#

USD prim path for the material.

Returns:: The prim path string.

property shaders_list: list[pxr.UsdShade.Shader]#

List of shaders used by the material.

Returns:: The shaders used by the material.

class OmniPBR( prim_path: str, name: str = 'omni_pbr', shader: UsdShade.Shader | None = None, texture_path: str | None = None, texture_scale: np.ndarray | None = None, texture_translate: np.ndarray | None = None, color: np.ndarray | None = None, )#

Bases: VisualMaterial

OmniPBR physically-based rendering material.

Parameters:

prim_path – USD prim path for the material.
name – Name identifier.
shader – Existing shader to use.
texture_path – Path to diffuse texture.
texture_scale – Texture UV scale (x, y).
texture_translate – Texture UV translation (x, y).
color – Diffuse color RGB.

get_color() → ndarray#

Get the diffuse color.

Returns:: RGB color array.

get_metallic_constant() → float#

Get the metallic constant.

Returns:: Metallic value.

get_project_uvw() → bool#

Get the UVW projection state.

Returns:: True if projection is enabled, False otherwise.

get_reflection_roughness() → float#

Get the reflection roughness.

Returns:: Roughness value.

get_texture() → str#

Get the diffuse texture path.

Returns:: Path to the texture file.

get_texture_scale() → ndarray#

Get the texture UV scale.

Returns:: Array with (x, y) scale values.

get_texture_translate() → ndarray#

Get the texture UV translation.

Returns:: Array with (x, y) translation values.

set_color(color: ndarray) → None#

Set the diffuse color.

Parameters:: color – RGB color array.

set_metallic_constant(amount: float) → None#

Set the metallic constant.

Parameters:: amount – Metallic value (0-1).

set_project_uvw(flag: bool) → None#

Enable or disable UVW projection.

Parameters:: flag – True to enable projection, False to disable.

set_reflection_roughness(amount: float) → None#

Set the reflection roughness.

Parameters:: amount – Roughness value (0-1).

set_texture(path: str) → None#

Set the diffuse texture path.

Parameters:: path – Path to the texture file.

set_texture_scale(x: float, y: float) → None#

Set the texture UV scale.

Parameters:

x – Scale in U direction.
y – Scale in V direction.

set_texture_translate(x: float, y: float) → None#

Set the texture UV translation.

Parameters:

x – Translation in U direction.
y – Translation in V direction.

property material: pxr.UsdShade.Material#

USD material object associated with this VisualMaterial.

Returns:: The USD material object.

property name: str#

Material name.

Returns:: The material name.

property prim: pxr.Usd.Prim#

USD prim object for the material.

Returns:: The USD prim object.

property prim_path: str#

USD prim path for the material.

Returns:: The prim path string.

property shaders_list: list[pxr.UsdShade.Shader]#

List of shaders used by the material.

Returns:: The shaders used by the material.

Bases: VisualMaterial

High-level wrapper for creating/encapsulating Omniverse Glass (OmniGlass) material prims.

Parameters:

prim_path – USD prim path for the material.
name – Name identifier.
shader – Existing shader to use.
color – Glass tint color RGB.
ior – Index of refraction.
depth – Glass depth/thickness.
thin_walled – Whether to use thin-walled mode.

Raises:

RuntimeError – If omni.kit.material.library extension is not enabled.
Exception – If the shader is not defined.
ValueError – If the material’s shader is not of type OmniGlass.

get_color() → ndarray | None#

Get the glass tint color.

Returns:: RGB color array, or None if not set.

get_depth() → float | None#

Glass depth/thickness.

Returns:: Glass depth/thickness value, or None if not set.

get_ior() → float | None#

Index of refraction for the glass material.

Returns:: Index of refraction value, or None if not set.

get_thin_walled() → float | None#

Thin-walled mode for the glass material.

Returns:: Thin-walled mode value, or None if not set.

set_color(color: ndarray) → None#

Set the glass tint color.

Parameters:: color – RGB color array.

set_depth(depth: float) → None#

Set the glass depth/thickness.

Parameters:: depth – Glass depth/thickness value.

set_ior(ior: float) → None#

Set the index of refraction for the glass material.

Parameters:: ior – Index of refraction value.

set_thin_walled(thin_walled: float) → None#

Set the thin-walled mode for the glass material.

Parameters:: thin_walled – Thin-walled mode value.

property material: pxr.UsdShade.Material#

USD material object associated with this VisualMaterial.

Returns:: The USD material object.

property name: str#

Material name.

Returns:: The material name.

property prim: pxr.Usd.Prim#

USD prim object for the material.

Returns:: The USD prim object.

property prim_path: str#

USD prim path for the material.

Returns:: The prim path string.

property shaders_list: list[pxr.UsdShade.Shader]#

List of shaders used by the material.

Returns:: The shaders used by the material.

class PhysicsMaterial( prim_path: str, name: str = 'physics_material', static_friction: float | None = None, dynamic_friction: float | None = None, restitution: float | None = None, )#

Bases: object

Physics material for defining friction and restitution properties.

Parameters:

prim_path – USD prim path for the material.
name – Name identifier.
static_friction – Static friction coefficient.
dynamic_friction – Dynamic friction coefficient.
restitution – Restitution (bounciness) coefficient.

get_dynamic_friction() → float#

Get the dynamic friction coefficient.

Returns:: The dynamic friction coefficient value.

get_restitution() → float#

Get the restitution (bounciness) coefficient.

Returns:: The restitution coefficient value.

get_static_friction() → float#

Get the static friction coefficient.

Returns:: The static friction coefficient value.

set_dynamic_friction(friction: float) → None#

Set the dynamic friction coefficient.

Parameters:: friction – The dynamic friction coefficient value.

set_restitution(restitution: float) → None#

Set the restitution (bounciness) coefficient.

Parameters:: restitution – The restitution coefficient value.

set_static_friction(friction: float) → None#

Set the static friction coefficient.

Parameters:: friction – The static friction coefficient value.

property material: pxr.UsdShade.Material#

USD material object for the physics material.

Returns:: The material object.

property name: str#

Material name identifier.

Returns:: The material name.

property prim: pxr.Usd.Prim#

USD prim object for the material.

Returns:: The prim object.

property prim_path: str#

USD prim path for the material.

Returns:: The prim path.

Bases: object

A wrapper around position-based-dynamics (PBD) material for particles used to simulate fluids, cloth and inflatables.

Applies the PhysxSchema.PhysxPBDMaterialAPI to a material prim.

Note

Currently, only a single material per particle system is supported which applies to all objects that are associated with the system. If a prim does not exist at the specified path, then a new UsdShade.Material prim is created.

Parameters:

prim_path – The prim path to create/apply PBD material properties.
name – Name given to the prim when instantiating it.
friction – The friction coefficient.
particle_friction_scale – The coefficient that scales friction for solid particle-particle interactions.
damping – The global velocity damping coefficient.
viscosity – The viscosity of fluid particles.
vorticity_confinement – The vorticity confinement for fluid particles.
surface_tension – The surface tension.
cohesion – The cohesion for interaction between fluid particles.
adhesion – The adhesion for interaction between particles (solid or fluid), and rigid or deformable objects.
particle_adhesion_scale – The coefficient that scales adhesion for solid particle-particle interactions.
adhesion_offset_scale – The offset scale that defines where adhesion ceases to take effect.
gravity_scale – The gravitational acceleration scaling factor. It can be used to approximate lighter-than-air inflatables.
lift – The lift coefficient for cloth and inflatable particle objects.
drag – The drag coefficient for cloth and inflatable particle objects.

Raises:

ValueError – If a prim exists at prim_path but is not a UsdShade.Material prim.

get_adhesion() → float#

Adhesion for interaction between particles and rigid or deformable objects.

Returns:: The adhesion for interaction between particles (solid or fluid), and rigids or deformables.

get_adhesion_offset_scale() → float#

Adhesion offset scale.

Returns:: The adhesion offset scale.

get_cohesion() → float#

Cohesion for interaction between fluid particles.

Returns:: The cohesion for interaction between fluid particles.

get_damping() → float#

Global velocity damping coefficient.

Returns:: The global velocity damping coefficient.

get_drag() → float#

Drag coefficient for the basic aerodynamic drag model.

Deprecated since version physxPBDMaterial:drag: was deprecated by PhysX. Always returns 0.0.

Returns:: Always 0.0 since the drag attribute was removed by PhysX.

get_friction() → float#

Friction coefficient.

Returns:: The friction coefficient.

get_gravity_scale() → float#

Gravitational acceleration scaling factor.

Returns:: The gravitational acceleration scaling factor.

get_lift() → float#

Lift coefficient for the basic aerodynamic lift model.

Deprecated since version physxPBDMaterial:lift: was deprecated by PhysX. Always returns 0.0.

Returns:: Always 0.0 since the lift attribute was removed by PhysX.

get_particle_adhesion_scale() → float#

Particle adhesion scale.

Returns:: The particle adhesion scale.

get_particle_friction_scale() → float#

Particle friction scale.

Returns:: The particle friction scale.

get_surface_tension() → float#

Surface tension for fluid particles.

Returns:: The surface tension for fluid particles.

get_viscosity() → float#

Viscosity for fluid particles.

Returns:: The viscosity.

get_vorticity_confinement() → float#

Vorticity confinement for fluid particles.

Returns:: The vorticity confinement for fluid particles.

initialize(physics_sim_view: object = None) → None#

Initializes the particle material.

Parameters:: physics_sim_view – Physics simulation view to use for initialization.

is_valid() → bool#

Whether the current prim path corresponds to a valid prim in stage.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

post_reset() → None#: Resets the prim to its default state.

set_adhesion(value: float) → None#

Sets the adhesion for interaction between particles (solid or fluid), and rigid or deformable objects.

Note

Adhesion also applies to solid-solid particle interactions, but is multiplied with the particle adhesion scale.

Parameters:: value – The adhesion. Range: [0, inf), Units: dimensionless

set_adhesion_offset_scale(value: float) → None#

Sets the adhesion offset scale.

It defines the offset at which adhesion ceases to take effect. For interactions between particles (fluid or solid), and rigids or deformables, the adhesion offset is defined relative to the rest offset. For solid particle-particle interactions, the adhesion offset is defined relative to the solid rest offset.

Parameters:: value – The adhesion offset scale. Range: [0, inf), Units: dimensionless

set_cohesion(value: float) → None#

Sets the cohesion for interaction between fluid particles.

Parameters:: value – The cohesion. Range: [0, inf), Units: dimensionless

set_damping(value: float) → None#

Sets the global velocity damping coefficient.

Parameters:: value – The damping coefficient. Range: [0, inf), Units: dimensionless

set_drag(value: float) → None#

Sets the drag coefficient, i.e. basic aerodynamic drag model coefficient.

Deprecated since version physxPBDMaterial:drag: was deprecated by PhysX. This method is a no-op.

Parameters:: value – The drag coefficient (ignored).

set_friction(value: float) → None#

Sets the friction coefficient.

The friction takes effect in all interactions between particles and rigids or deformables. For solid particle-particle interactions it is multiplied by the particle friction scale.

Parameters:: value – The friction coefficient. Range: [0, inf), Units: dimensionless

set_gravity_scale(value: float) → None#

Sets the gravitational acceleration scaling factor.

It can be used to approximate lighter-than-air inflatable. For example (-1.0 would invert gravity).

Parameters:: value – The gravity scale. Range: (-inf , inf), Units: dimensionless

set_lift(value: float) → None#

Sets the lift coefficient, i.e. basic aerodynamic lift model coefficient.

Deprecated since version physxPBDMaterial:lift: was deprecated by PhysX. This method is a no-op.

Parameters:: value – The lift coefficient (ignored).

set_particle_adhesion_scale(value: float) → None#

Sets the particle adhesion scale.

This coefficient scales the adhesion for solid particle-particle interaction.

Parameters:: value – The adhesion scale. Range: [0, inf), Units: dimensionless

set_particle_friction_scale(value: float) → None#

Sets the particle friction scale.

The coefficient that scales friction for solid particle-particle interaction.

Parameters:: value – The particle friction scale. Range: [0, inf), Units: dimensionless

set_surface_tension(value: float) → None#

Sets the surface tension for fluid particles.

Parameters:: value – The surface tension. Range: [0, inf), Units: 1 / (distance * distance * distance)

set_viscosity(value: float) → None#

Sets the viscosity for fluid particles.

Parameters:: value – The viscosity. Range: [0, inf), Units: dimensionless

set_vorticity_confinement(value: float) → None#

Sets the vorticity confinement for fluid particles.

This helps prevent energy loss due to numerical solver by adding vortex-like accelerations to the particles.

Parameters:: value – The vorticity confinement. Range: [0, inf), Units: dimensionless

property material: pxr.UsdShade.Material#

USD Material object.

Returns:: The USD Material object.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property prim: pxr.Usd.Prim#

USD prim present.

Returns:: The USD prim present.

property prim_path: str#

Stage path to the material.

Returns:: The stage path to the material.

Bases: object

The view class to deal with particle material prims.

Provides high-level functions to deal with particle material (1 or more particle materials) as well as its attributes/properties. This object wraps all matching materials found at the regex provided at prim_paths_expr. This object wraps all matching material prims found at the regex provided at prim_paths_expr.

Parameters:

prim_paths_expr – Prim paths regex to encapsulate all prims that match it.
name – Short name to be used as a key by Scene class.
frictions – The friction coefficient tensor, shape is (N, ).
particle_friction_scales – The coefficient that scales friction for solid particle-particle interactions, shape is (N, ).
dampings – The global velocity damping tensor, shape is (N, ).
viscosities – The viscosity tensor of fluid particles, shape is (N, ).
vorticity_confinements – The vorticity confinement tensor for fluid particles, shape is (N, ).
surface_tensions – The surface tension tensor, shape is (N, ).
cohesions – The cohesion tensor for interaction between fluid particles, shape is (N, ).
adhesions – The adhesion tensor for interaction between particles (solid or fluid), and rigid or deformable objects, shape is (N, ).
particle_adhesion_scales – The coefficient tensor that scales adhesion for solid particle-particle interactions, shape is (N, ).
adhesion_offset_scales – The offset scale tensor defines where adhesion ceases to take effect, shape is (N, ).
gravity_scales – The gravitational acceleration scaling tensor. It can be used to approximate lighter-than-air inflatables, shape is (N, ).
lifts – The lift coefficient tensor for cloth and inflatable particle objects, shape is (N, ).
drags – The drag coefficient tensor for cloth and inflatable particle objects, shape is (N, ).

Raises:

Exception – If prim_paths_expr does not match any prims.

get_adhesion_offset_scales( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the adhesion offset scale of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Unused compatibility argument.

Returns:

Adhesion offset scale tensor with shape (M, ).

get_adhesions( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the adhesion of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Unused compatibility argument.

Returns:

Adhesion tensor with shape (M, ).

get_cohesions( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the cohesion of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Unused compatibility argument.

Returns:

Cohesion tensor with shape (M, ).

get_dampings( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the dampings of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Dampings tensor with shape (M, ).

get_drags( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the drags of materials indicated by the indices.

Note

drag attribute was removed from PhysxPBDMaterialAPI. Always returns zeros.

Parameters:

indices – Indices to specify which material prims to query.
clone – Accepted for API compatibility.

Returns:

Tensor of zeros with shape (M, ).

get_frictions( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the friction of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Friction tensor with shape (M, ).

get_gravity_scales( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the gravity scale of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Gravity scale tensor with shape (M, ).

get_lifts( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the lifts of materials indicated by the indices.

Note

lift attribute was removed from PhysxPBDMaterialAPI. Always returns zeros.

Parameters:

indices – Indices to specify which material prims to query.
clone – Accepted for API compatibility.

Returns:

Tensor of zeros with shape (M, ).

get_particle_adhesion_scales( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the adhesion scale of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Unused compatibility argument.

Returns:

Adhesion scale tensor with shape (M, ).

get_particle_friction_scales( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the particle friction scale of materials indicated by the indices.

Parameters:

indices – Indices that specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Unused.

Returns:

Particle friction scale tensor with shape (M, ).

get_surface_tensions( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the surface tension of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Unused compatibility argument.

Returns:

Surface tension tensor with shape (M, ).

get_viscosities( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the viscosity of materials indicated by the indices.

Parameters:

indices – Indices to specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Viscosity tensor with shape (M, ).

get_vorticity_confinements( indices: ndarray | list | Tensor | None = None, clone: bool = True, ) → ndarray | Tensor#

Gets the vorticity confinement of materials indicated by the indices.

Parameters:

indices – Indices that specify which material prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Unused.

Returns:

Vorticity confinement tensor with shape (M, ).

initialize( physics_sim_view: omni.physics.tensors.SimulationView = None, ) → None#

Creates a physics simulation view if not passed and initializes particle material USD attribute access.

Parameters:: physics_sim_view – Current physics simulation view.

is_physics_handle_valid() → bool#

Checks if the physics handle of the view is valid.

Returns:: True if the physics handle of the view is valid, i.e., physics is initialized for the view. Otherwise False.

is_valid( indices: ndarray | list | Tensor | None = None, ) → bool#

Checks if all prim paths specified in the view correspond to valid prims in the stage.

Parameters:: indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: True if all prim paths specified in the view correspond to a valid prim in stage. False otherwise.

post_reset() → None#: Resets the particles to their initial states.

Sets the adhesion offset scale for the material prims indicated by the indices.

Parameters:

values – Material adhesion offset scale tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Sets the particle adhesion for the material prims indicated by the indices.

Parameters:

values – Material particle adhesion scale tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Sets the particle cohesion for the material prims indicated by the indices.

Parameters:

values – Material particle cohesion scale tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Sets the dampings for the material prims indicated by the indices.

Parameters:

values – Material damping tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Keeps compatibility for setting drags on material prims indicated by the indices.

Note

drag attribute was removed from PhysxPBDMaterialAPI. This is a no-op.

Parameters:

values – Material drag tensor with the shape (M, ) (ignored).
indices – Indices to specify which material prims to manipulate (ignored).

Sets the friction for the material prims indicated by the indices.

Parameters:

values – Material friction tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Sets the gravity scale for the material prims indicated by the indices.

Parameters:

values – Material gravity scale tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Keeps compatibility for setting lifts on material prims indicated by the indices.

Note

lift attribute was removed from PhysxPBDMaterialAPI. This is a no-op.

Parameters:

values – Material lift tensor with the shape (M, ) (ignored).
indices – Indices to specify which material prims to manipulate. Shape (M,) (ignored). Where M <= size of the encapsulated prims in the view.

Sets the particle adhesion scale for the material prims indicated by the indices.

Parameters:

values – Material particle adhesion scale tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Sets the particle friction scale for the material prims indicated by the indices.

Parameters:

values – Material particle friction scale tensor with the shape (M, ).
indices – Indices that specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Sets the particle surface tension for the material prims indicated by the indices.

Parameters:

values – Material particle surface tension scale tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Sets the particle viscosity for the material prims indicated by the indices.

Parameters:

values – Material particle viscosity scale tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Sets the vorticity confinement for the material prims indicated by the indices.

Parameters:

values – Material particle vorticity confinement scale tensor with the shape (M, ).
indices – Indices to specify which material prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

property count: int#

Number of particle material prims in the view.

Returns:: Number of particle material prims in the view.

property name: str#

Name given to the view when instantiating it.

Returns:: Name given to the view when instantiating it.

class DeformableMaterial(*args: Any, **kwargs: Any)#

Bases: object

Stub for the removed DeformableMaterial class.

DeformableMaterial is no longer available because Omniverse PhysX removed the deprecated deformable body features it depended on. Use the new material APIs in isaacsim.core.experimental.materials instead.

Parameters:

*args – Positional arguments (ignored; class always raises NotImplementedError).
**kwargs – Keyword arguments (ignored; class always raises NotImplementedError).

Raises:

NotImplementedError – Always raised because DeformableMaterial is no longer available.

class DeformableMaterialView(*args: Any, **kwargs: Any)#

Bases: object

Stub for the removed DeformableMaterialView class.

DeformableMaterialView is no longer available because Omniverse PhysX removed the deprecated deformable body features it depended on. Use the new material APIs in isaacsim.core.experimental.materials instead.

Parameters:

*args – Positional arguments (ignored; class always raises NotImplementedError).
**kwargs – Keyword arguments (ignored; class always raises NotImplementedError).

Raises:

NotImplementedError – Always raised because DeformableMaterialView is no longer available.

Objects#

Modules to create/encapsulate visual, fixed, and dynamic shapes (Capsule, Cone, Cuboid, Cylinder, Sphere) as well as ground planes

Type	Collider API	Rigid Body API
Visual	No	No
Fixed	Yes	No
Dynamic	Yes	Yes

Bases: object

High level wrapper to create or encapsulate a ground plane.

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
size – Length of each edge.
z_position – Ground plane position in the z-axis.
scale – Local scale to be applied to the prim’s dimensions.
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual plane.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.

Example:

>>> from isaacsim.core.api.objects import GroundPlane
>>> import numpy as np
>>>
>>> # create a ground plane placed at 0 in the z-axis
>>> plane = GroundPlane(prim_path="/World/GroundPlane", z_position=0)
>>> plane
<isaacsim.core.api.objects.ground_plane.GroundPlane object at 0x7f15d003fb50>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to be applied to the held prim. This is where you want to define friction, restitution, etc. Note: if a physics material is not defined, the defaults will be used from PhysX.
weaker_than_descendants – True if the material should not override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> plane.apply_physics_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material in case it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example:

>>> plane.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7f517ff62920>

get_default_state() → XFormPrimState#

Gets the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = plane.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f6efff41cf0>
>>>
>>> state.position
[0. 0. 0.]
>>> state.orientation
[1. 0. 0. 0.]

get_world_pose() → tuple[ndarray, ndarray]#

Gets the prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (0.0, 0.0, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[0. 0. 0.]
>>> orientation
[1. 0. 0. 0.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> plane.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> plane.is_valid()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Example:

>>> plane.post_reset()

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Sets the default state of the prim (position and orientation), which will be used after each reset.

Parameters:

position – Position in the world frame of the prim. Shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). Shape is (4, ).

Example:

>>> # configure default state
>>> plane.set_default_state(
...     position=np.array([0.0, 0.0, -1.0]), orientation=np.array([1, 0, 0, 0])
... )
>>>
>>> # set default states during post-reset
>>> plane.post_reset()

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Sets the prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. Shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). Shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> plane.set_world_pose(
...     position=np.array([0.0, 0.0, 0.5]), orientation=np.array([1., 0., 0., 0.])
... )

property collision_geometry_prim: SingleGeometryPrim#

Wrapped object as a SingleGeometryPrim.

Returns:: Wrapped object as a SingleGeometryPrim.

Example:

>>> plane.collision_geometry_prim
<isaacsim.core.prims.single_geometry_prim.SingleGeometryPrim object at 0x7f15ff3461a0>

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

Example:

>>> plane.name
ground_plane

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

Example:

>>> plane.prim
Usd.Prim(</World/GroundPlane>)

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Example:

>>> plane.prim_path
/World/GroundPlane

property xform_prim: SingleXFormPrim#

Wrapped object as a SingleXFormPrim.

Returns:: Wrapped object as a SingleXFormPrim.

Example:

>>> plane.xform_prim
<isaacsim.core.prims.single_xform_prim.SingleXFormPrim object at 0x7f1578d32560>

Bases: SingleGeometryPrim

High-level wrapper to create or encapsulate a visual capsule.

Note

Visual capsules (Capsule shape) have no collisions (Collider API) or rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world or local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Capsule radius.
height – Capsule height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.

Raises:

Exception – If an existing prim at prim_path cannot be parsed as a Capsule object.

Example:

>>> from isaacsim.core.api.objects import VisualCapsule
>>> import numpy as np
>>>
>>> # create a red visual capsule at the given path
... prim = VisualCapsule(
...     prim_path="/World/Xform/Capsule",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0])
... )
>>> prim
<isaacsim.core.api.objects.capsule.VisualCapsule object at 0x7f4ff958b0d0>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Capsule height.

Returns:: Capsule height.

Example:

>>> prim.get_height()
1.0

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Capsule radius.

Returns:: Capsule radius.

Example:

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_height(height: float) → None#

Set the capsule height.

Parameters:: height – Capsule height.

Example:

>>> prim.set_height(2.0)

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the capsule radius.

Parameters:: radius – Capsule radius.

Example:

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: SingleGeometryPrim

High level wrapper to create or encapsulate a visual cone.

Note

Visual cones (Cone shape) have no collisions (Collider API) or rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world or local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to false for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Base radius.
height – Cone height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.

Raises:

TypeError – If an existing prim at prim_path cannot be parsed as a Cone object.

Example:

>>> from isaacsim.core.api.objects import VisualCone
>>> import numpy as np
>>>
>>> # create a red visual cone at the given path
>>> prim = VisualCone(
...     prim_path="/World/Xform/Cone",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0])
... )
>>> prim
<isaacsim.core.api.objects.cone.VisualCone object at 0x7f513413aa70>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Get the cone height.

Returns:: The cone height.

Example

>>> prim.get_height()
1.0

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Get the base radius.

Returns:: The base radius.

Example

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_height(height: float) → None#

Set the cone height.

Parameters:: height – Cone height.

Example

>>> prim.set_height(2.0)

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the base radius.

Parameters:: radius – Base radius.

Example

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: SingleGeometryPrim

High-level wrapper to create or encapsulate a visual cuboid.

Note

Visual cuboids (Cube shapes) have no collisions (Collider API) or rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
size – Length of each cube edge.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.

Raises:

Exception – If the prim at prim_path exists and cannot be parsed as a Cube object.

Example:

>>> from isaacsim.core.api.objects import VisualCuboid
>>> import numpy as np
>>>
>>> # create a red visual cube at the given path
>>> prim = VisualCuboid(prim_path="/World/Xform/Cube", color=np.array([1.0, 0.0, 0.0]))
>>> prim
<isaacsim.core.api.objects.cuboid.VisualCuboid object at 0x7f12e756fa00>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_size() → ndarray#

Get the length of each cube edge.

Returns:: Edge length.

Example

>>> prim.get_size()
1.0

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_size(size: float) → None#

Set the length of each cube edge.

Parameters:: size – Edge length.

Example

>>> prim.set_size(2.0)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: SingleGeometryPrim

High-level wrapper to create or encapsulate a visual cylinder.

Note

Visual cylinders (Cylinder shape) have no collisions (Collider API) or rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Base radius.
height – Cylinder height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.

Raises:

Exception – If the prim at prim_path cannot be parsed as a Cylinder object.

Example:

>>> from isaacsim.core.api.objects import VisualCylinder
>>> import numpy as np
>>>
>>> # create a red visual cylinder at the given path
>>> prim = VisualCylinder(
...     prim_path="/World/Xform/Cylinder",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0])
... )
>>> prim
<isaacsim.core.api.objects.cylinder.VisualCylinder object at 0x7f4e433f22c0>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Cylinder height.

Returns:: Cylinder height.

Example:

>>> prim.get_height()
1.0

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Base radius.

Returns:: Base radius.

Example:

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_height(height: float) → None#

Set the cylinder height.

Parameters:: height – Cylinder height.

Example:

>>> prim.set_height(2.0)

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the base radius.

Parameters:: radius – Base radius.

Example:

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

class VisualSphere( prim_path: str, name: str = 'visual_sphere', position: Sequence[float] | None = None, translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, scale: Sequence[float] | None = None, visible: bool | None = True, color: ndarray | None = None, radius: float | None = None, visual_material: VisualMaterial | None = None, )#

Bases: SingleGeometryPrim

High level wrapper to create or encapsulate a visual sphere.

Note

Visual spheres (Sphere shape) have no collisions (Collider API) or rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world or local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Sphere radius.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.

Example:

>>> from isaacsim.core.api.objects import VisualSphere
>>> import numpy as np
>>>
>>> # create a red visual sphere at the given path
>>> prim = VisualSphere(prim_path="/World/Xform/Sphere", color=np.array([1.0, 0.0, 0.0]))
>>> prim
<isaacsim.core.api.objects.sphere.VisualSphere object at 0x7f4e3eb3ea70>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Sphere radius.

Returns:: Sphere radius.

Example:

>>> prim.get_radius()
1.0

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the sphere radius.

Parameters:: radius – Sphere radius.

Example:

>>> prim.set_radius(2.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: VisualCapsule

High level wrapper to create or encapsulate a fixed capsule.

Note

Fixed capsules (Capsule shape) have collisions (Collider API) but no rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Capsule radius.
height – Capsule height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.

Example:

>>> from isaacsim.core.api.objects import FixedCapsule
>>> import numpy as np
>>>
>>> # create a red fixed capsule at the given path
>>> prim = FixedCapsule(
...     prim_path="/World/Xform/Capsule",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0])
... )
>>> print(prim)
<isaacsim.core.api.objects.capsule.FixedCapsule object at 0x7f520c0d4790>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Capsule height.

Returns:: Capsule height.

Example:

>>> prim.get_height()
1.0

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Capsule radius.

Returns:: Capsule radius.

Example:

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_height(height: float) → None#

Set the capsule height.

Parameters:: height – Capsule height.

Example:

>>> prim.set_height(2.0)

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the capsule radius.

Parameters:: radius – Capsule radius.

Example:

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: VisualCone

High-level wrapper to create or encapsulate a fixed cone.

Note

Fixed cones (Cone shape) have collisions (Collider API) but no rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world or local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Base radius.
height – Cone height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.

Example:

>>> from isaacsim.core.api.objects import FixedCone
>>> import numpy as np
>>>
>>> # create a red fixed cone at the given path
>>> prim = FixedCone(
...     prim_path="/World/Xform/Cone",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0])
... )
>>> prim
<isaacsim.core.api.objects.cone.FixedCone object at 0x7f51489f09a0>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Get the cone height.

Returns:: The cone height.

Example

>>> prim.get_height()
1.0

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Get the base radius.

Returns:: The base radius.

Example

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation(approximation_type: str) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_height(height: float) → None#

Set the cone height.

Parameters:: height – Cone height.

Example

>>> prim.set_height(2.0)

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the base radius.

Parameters:: radius – Base radius.

Example

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: VisualCuboid

High level wrapper to create/encapsulate a fixed cuboid.

Note

Fixed cuboids (Cube shape) have collisions (Collider API) but no rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Shortname to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to false for an invisible prim in the stage while rendering.
color – Color of the visual shape.
size – Length of each cube edge.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.

Example:

>>> from isaacsim.core.api.objects import FixedCuboid
>>> import numpy as np
>>>
>>> # create a red fixed cube at the given path
>>> prim = FixedCuboid(prim_path="/World/Xform/Cube", color=np.array([1.0, 0.0, 0.0]))
>>> prim
<isaacsim.core.api.objects.cuboid.FixedCuboid object at 0x7f7b4d91da80>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_size() → ndarray#

Get the length of each cube edge.

Returns:: Edge length.

Example

>>> prim.get_size()
1.0

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_size(size: float) → None#

Set the length of each cube edge.

Parameters:: size – Edge length.

Example

>>> prim.set_size(2.0)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: VisualCylinder

High-level wrapper to create/encapsulate a fixed cylinder.

Note

Fixed cylinders (Cylinder shape) have collisions (Collider API) but no rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Base radius.
height – Cylinder height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.

Example:

>>> from isaacsim.core.api.objects import FixedCylinder
>>> import numpy as np
>>>
>>> # create a red fixed cylinder at the given path
>>> prim = FixedCylinder(
...     prim_path="/World/Xform/Cylinder",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0])
... )
>>> print(prim)
<isaacsim.core.api.objects.cylinder.FixedCylinder object at 0x7f4f24144f40>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Cylinder height.

Returns:: Cylinder height.

Example:

>>> prim.get_height()
1.0

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Base radius.

Returns:: Base radius.

Example:

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_height(height: float) → None#

Set the cylinder height.

Parameters:: height – Cylinder height.

Example:

>>> prim.set_height(2.0)

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the base radius.

Parameters:: radius – Base radius.

Example:

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: VisualSphere

High level wrapper to create/encapsulate a fixed sphere.

Note

Fixed spheres (Sphere shape) have collisions (Collider API) but no rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to false for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Sphere radius.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.

Example:

>>> from isaacsim.core.api.objects import FixedSphere
>>> import numpy as np
>>>
>>> # create a red fixed sphere at the given path
>>> prim = FixedSphere(prim_path="/World/Xform/Sphere", color=np.array([1.0, 0.0, 0.0]))
>>> prim
<isaacsim.core.api.objects.sphere.FixedSphere object at 0x7f4e433f2140>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Sphere radius.

Returns:: Sphere radius.

Example:

>>> prim.get_radius()
1.0

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the sphere radius.

Parameters:: radius – Sphere radius.

Example:

>>> prim.set_radius(2.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: SingleRigidPrim, FixedCapsule

High level wrapper to create/encapsulate a dynamic capsule.

Note

Dynamic capsules (Capsule shape) have collisions (Collider API) and rigid body dynamics (Rigid Body API)

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends on whether translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to false for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Capsule radius.
height – Capsule height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.
mass – Mass in kg.
density – Density.
linear_velocity – Linear velocity in the world frame.
angular_velocity – Angular velocity in the world frame.

Example:

>>> from isaacsim.core.api.objects import DynamicCapsule
>>> import numpy as np
>>>
>>> # create a red dynamic capsule of mass 1kg at the given path
>>> prim = DynamicCapsule(
...     prim_path="/World/Xform/Capsule",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0]),
...     mass=1.0
... )
>>> prim
<isaacsim.core.api.objects.capsule.DynamicCapsule object at 0x7f4ff915f8e0>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

disable_rigid_body_physics() → None#

Disable the rigid body physics.

When disabled, the object will not be moved by external forces such as gravity and collisions.

Example:

>>> prim.disable_rigid_body_physics()

enable_rigid_body_physics() → None#

Enable the rigid body physics.

When enabled, the object will be moved by external forces such as gravity and collisions.

Example:

>>> prim.enable_rigid_body_physics()

get_angular_velocity() → ndarray#

Get the angular velocity of the rigid body.

Returns:: Current angular velocity of the rigid prim. Shape (3,).

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_com() → tuple[ndarray, ndarray]#

Get the center of mass pose of the rigid body.

Returns:: A tuple of (position, orientation) where position is the center of mass position and orientation is the center of mass orientation.

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_current_dynamic_state() → DynamicState#

Get the current rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The dynamic state of the rigid body prim.

Example:

>>> # for the example the rigid body is in free fall
>>> state = prim.get_current_dynamic_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f740b36f670>
>>> state.position
[  0.99999857   2.0000017  -74.2862    ]
>>> state.orientation
[ 1.0000000e+00 -2.3961178e-07 -4.9891562e-09  4.9388258e-09]
>>> state.linear_velocity
[  0.        0.      -38.09554]
>>> state.angular_velocity
[0. 0. 0.]

get_default_state() → DynamicState#

Get the default rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The default state of the prim that is used after each reset.

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f7411fcbe20>
>>> state.position
[-7.8622378e-07  1.4450421e-06  1.6135601e-07]
>>> state.orientation
[ 9.9999994e-01 -2.7194994e-07  2.9607077e-07  2.7016510e-08]
>>> state.linear_velocity
[0. 0. 0.]
>>> state.angular_velocity
[0. 0. 0.]

get_density() → float#

Get the density of the rigid body.

Returns:: Density of the rigid body.

Example:

>>> prim.get_density()
0

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Capsule height.

Returns:: Capsule height.

Example:

>>> prim.get_height()
1.0

get_linear_velocity() → ndarray#

Get the linear velocity of the rigid body.

Returns:: Current linear velocity of the rigid prim. Shape (3,).

Example:

>>> prim.get_linear_velocity()
[ 1.0812164e-04  6.1415871e-05 -2.1341663e-04]

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_mass() → float#

Get the mass of the rigid body.

Returns:: Mass of the rigid body in kg.

Example:

>>> prim.get_mass()
0

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Capsule radius.

Returns:: Capsule radius.

Example:

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_sleep_threshold() → float#

Get the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Returns:: Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range is [0, inf). Units are distance^2 / second^2.

Example:

>>> prim.get_sleep_threshold()
5e-05

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_angular_velocity(velocity: ndarray) → None#

Set the angular velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid body state.

Parameters:: velocity – Angular velocity to set the rigid prim to. Shape (3,).

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_com( position: ndarray, orientation: ndarray, ) → None#

Set the center of mass pose of the rigid body.

Parameters:

position – Center of mass position. Shape (3,).
orientation – Center of mass orientation. Shape (4,).

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, linear_velocity: ndarray | None = None, angular_velocity: ndarray | None = None, ) → None#

Set the default state of the prim (position, orientation, linear velocity, and angular velocity).

The default state is used after each reset.

Note

The default states will be set during post-reset (e.g., calling .post_reset() or world.reset() methods)

Parameters:

position – Position in the world frame of the prim. Shape is (3, ). If not specified, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). Shape is (4, ). If not specified, the orientation is left unchanged.
linear_velocity – Linear velocity to set the rigid prim to. Shape (3,).
angular_velocity – Angular velocity to set the rigid prim to. Shape (3,).

Example:

>>> prim.set_default_state(
...     position=np.array([1.0, 2.0, 3.0]),
...     orientation=np.array([1.0, 0.0, 0.0, 0.0]),
...     linear_velocity=np.array([0.0, 0.0, 0.0]),
...     angular_velocity=np.array([0.0, 0.0, 0.0])
... )
>>>
>>> prim.post_reset()

set_density(density: float) → None#

Set the density of the rigid body.

Parameters:: density – Density of the rigid body.

Example:

>>> prim.set_density(0.9)

set_height(height: float) → None#

Set the capsule height.

Parameters:: height – Capsule height.

Example:

>>> prim.set_height(2.0)

set_linear_velocity(velocity: ndarray) → None#

Set the linear velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid prim state.

Parameters:: velocity – Linear velocity to set the rigid prim to. Shape (3,).

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_mass(mass: float) → None#

Set the mass of the rigid body.

Parameters:: mass – Mass of the rigid body in kg.

Example:

>>> prim.set_mass(1.0)

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the capsule radius.

Parameters:: radius – Capsule radius.

Example:

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_sleep_threshold(threshold: float) → None#

Set the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Parameters:: threshold – Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range: [0, inf). Units: distance^2 / second^2.

Example:

>>> prim.set_sleep_threshold(1e-5)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: SingleRigidPrim, FixedCone

High-level wrapper to create or encapsulate a dynamic cone.

Note

Dynamic cones (Cone shape) have collisions (Collider API) and rigid body dynamics (Rigid Body API)

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world or local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Base radius.
height – Cone height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.
mass – Mass in kg.
density – Density.
linear_velocity – Linear velocity in the world frame.
angular_velocity – Angular velocity in the world frame.

Raises:

TypeError – If the prim at prim_path cannot be parsed as a Cone object.

Example:

>>> from isaacsim.core.api.objects import DynamicCone
>>> import numpy as np
>>>
>>> # create a red dynamic cone of mass 1kg at the given path
>>> prim = DynamicCone(
...     prim_path="/World/Xform/Cone",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0]),
...     mass=1.0
... )
>>> prim
<isaacsim.core.api.objects.cone.DynamicCone object at 0x7f4f9f5d11b0>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

disable_rigid_body_physics() → None#

Disable the rigid body physics.

When disabled, the object will not be moved by external forces such as gravity and collisions.

Example:

>>> prim.disable_rigid_body_physics()

enable_rigid_body_physics() → None#

Enable the rigid body physics.

When enabled, the object will be moved by external forces such as gravity and collisions.

Example:

>>> prim.enable_rigid_body_physics()

get_angular_velocity() → ndarray#

Get the angular velocity of the rigid body.

Returns:: Current angular velocity of the rigid prim. Shape (3,).

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_com() → tuple[ndarray, ndarray]#

Get the center of mass pose of the rigid body.

Returns:: A tuple of (position, orientation) where position is the center of mass position and orientation is the center of mass orientation.

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_current_dynamic_state() → DynamicState#

Get the current rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The dynamic state of the rigid body prim.

Example:

>>> # for the example the rigid body is in free fall
>>> state = prim.get_current_dynamic_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f740b36f670>
>>> state.position
[  0.99999857   2.0000017  -74.2862    ]
>>> state.orientation
[ 1.0000000e+00 -2.3961178e-07 -4.9891562e-09  4.9388258e-09]
>>> state.linear_velocity
[  0.        0.      -38.09554]
>>> state.angular_velocity
[0. 0. 0.]

get_default_state() → DynamicState#

Get the default rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The default state of the prim that is used after each reset.

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f7411fcbe20>
>>> state.position
[-7.8622378e-07  1.4450421e-06  1.6135601e-07]
>>> state.orientation
[ 9.9999994e-01 -2.7194994e-07  2.9607077e-07  2.7016510e-08]
>>> state.linear_velocity
[0. 0. 0.]
>>> state.angular_velocity
[0. 0. 0.]

get_density() → float#

Get the density of the rigid body.

Returns:: Density of the rigid body.

Example:

>>> prim.get_density()
0

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Get the cone height.

Returns:: The cone height.

Example

>>> prim.get_height()
1.0

get_linear_velocity() → ndarray#

Get the linear velocity of the rigid body.

Returns:: Current linear velocity of the rigid prim. Shape (3,).

Example:

>>> prim.get_linear_velocity()
[ 1.0812164e-04  6.1415871e-05 -2.1341663e-04]

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_mass() → float#

Get the mass of the rigid body.

Returns:: Mass of the rigid body in kg.

Example:

>>> prim.get_mass()
0

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Get the base radius.

Returns:: The base radius.

Example

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_sleep_threshold() → float#

Get the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Returns:: Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range is [0, inf). Units are distance^2 / second^2.

Example:

>>> prim.get_sleep_threshold()
5e-05

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_angular_velocity(velocity: ndarray) → None#

Set the angular velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid body state.

Parameters:: velocity – Angular velocity to set the rigid prim to. Shape (3,).

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_com( position: ndarray, orientation: ndarray, ) → None#

Set the center of mass pose of the rigid body.

Parameters:

position – Center of mass position. Shape (3,).
orientation – Center of mass orientation. Shape (4,).

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, linear_velocity: ndarray | None = None, angular_velocity: ndarray | None = None, ) → None#

Set the default state of the prim (position, orientation, linear velocity, and angular velocity).

The default state is used after each reset.

Note

The default states will be set during post-reset (e.g., calling .post_reset() or world.reset() methods)

Parameters:

position – Position in the world frame of the prim. Shape is (3, ). If not specified, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). Shape is (4, ). If not specified, the orientation is left unchanged.
linear_velocity – Linear velocity to set the rigid prim to. Shape (3,).
angular_velocity – Angular velocity to set the rigid prim to. Shape (3,).

Example:

>>> prim.set_default_state(
...     position=np.array([1.0, 2.0, 3.0]),
...     orientation=np.array([1.0, 0.0, 0.0, 0.0]),
...     linear_velocity=np.array([0.0, 0.0, 0.0]),
...     angular_velocity=np.array([0.0, 0.0, 0.0])
... )
>>>
>>> prim.post_reset()

set_density(density: float) → None#

Set the density of the rigid body.

Parameters:: density – Density of the rigid body.

Example:

>>> prim.set_density(0.9)

set_height(height: float) → None#

Set the cone height.

Parameters:: height – Cone height.

Example

>>> prim.set_height(2.0)

set_linear_velocity(velocity: ndarray) → None#

Set the linear velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid prim state.

Parameters:: velocity – Linear velocity to set the rigid prim to. Shape (3,).

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_mass(mass: float) → None#

Set the mass of the rigid body.

Parameters:: mass – Mass of the rigid body in kg.

Example:

>>> prim.set_mass(1.0)

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the base radius.

Parameters:: radius – Base radius.

Example

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_sleep_threshold(threshold: float) → None#

Set the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Parameters:: threshold – Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range: [0, inf). Units: distance^2 / second^2.

Example:

>>> prim.set_sleep_threshold(1e-5)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: SingleRigidPrim, FixedCuboid

High level wrapper to create/encapsulate a dynamic cuboid.

Note

Dynamic cuboids (Cube shape) have collisions (Collider API) and rigid body dynamics (Rigid Body API)

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to false for an invisible prim in the stage while rendering.
color – Color of the visual shape.
size – Length of each cube edge.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.
mass – Mass in kg.
density – Density.
linear_velocity – Linear velocity in the world frame.
angular_velocity – Angular velocity in the world frame.

Raises:

Exception – If the prim at prim_path cannot be parsed as a Cube object.

Example:

>>> from isaacsim.core.api.objects import DynamicCuboid
>>> import numpy as np
>>>
>>> # create a red dynamic cube of mass 1kg at the given path
>>> prim = DynamicCuboid(prim_path="/World/Xform/Cube", color=np.array([1.0, 0.0, 0.0]), mass=1.0)
>>> prim
<isaacsim.core.api.objects.cuboid.DynamicCuboid object at 0x7ff14c04d990>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

disable_rigid_body_physics() → None#

Disable the rigid body physics.

When disabled, the object will not be moved by external forces such as gravity and collisions.

Example:

>>> prim.disable_rigid_body_physics()

enable_rigid_body_physics() → None#

Enable the rigid body physics.

When enabled, the object will be moved by external forces such as gravity and collisions.

Example:

>>> prim.enable_rigid_body_physics()

get_angular_velocity() → ndarray#

Get the angular velocity of the rigid body.

Returns:: Current angular velocity of the rigid prim. Shape (3,).

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_com() → tuple[ndarray, ndarray]#

Get the center of mass pose of the rigid body.

Returns:: A tuple of (position, orientation) where position is the center of mass position and orientation is the center of mass orientation.

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_current_dynamic_state() → DynamicState#

Get the current rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The dynamic state of the rigid body prim.

Example:

>>> # for the example the rigid body is in free fall
>>> state = prim.get_current_dynamic_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f740b36f670>
>>> state.position
[  0.99999857   2.0000017  -74.2862    ]
>>> state.orientation
[ 1.0000000e+00 -2.3961178e-07 -4.9891562e-09  4.9388258e-09]
>>> state.linear_velocity
[  0.        0.      -38.09554]
>>> state.angular_velocity
[0. 0. 0.]

get_default_state() → DynamicState#

Get the default rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The default state of the prim that is used after each reset.

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f7411fcbe20>
>>> state.position
[-7.8622378e-07  1.4450421e-06  1.6135601e-07]
>>> state.orientation
[ 9.9999994e-01 -2.7194994e-07  2.9607077e-07  2.7016510e-08]
>>> state.linear_velocity
[0. 0. 0.]
>>> state.angular_velocity
[0. 0. 0.]

get_density() → float#

Get the density of the rigid body.

Returns:: Density of the rigid body.

Example:

>>> prim.get_density()
0

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_linear_velocity() → ndarray#

Get the linear velocity of the rigid body.

Returns:: Current linear velocity of the rigid prim. Shape (3,).

Example:

>>> prim.get_linear_velocity()
[ 1.0812164e-04  6.1415871e-05 -2.1341663e-04]

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_mass() → float#

Get the mass of the rigid body.

Returns:: Mass of the rigid body in kg.

Example:

>>> prim.get_mass()
0

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_size() → ndarray#

Get the length of each cube edge.

Returns:: Edge length.

Example

>>> prim.get_size()
1.0

get_sleep_threshold() → float#

Get the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Returns:: Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range is [0, inf). Units are distance^2 / second^2.

Example:

>>> prim.get_sleep_threshold()
5e-05

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_angular_velocity(velocity: ndarray) → None#

Set the angular velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid body state.

Parameters:: velocity – Angular velocity to set the rigid prim to. Shape (3,).

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_com( position: ndarray, orientation: ndarray, ) → None#

Set the center of mass pose of the rigid body.

Parameters:

position – Center of mass position. Shape (3,).
orientation – Center of mass orientation. Shape (4,).

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, linear_velocity: ndarray | None = None, angular_velocity: ndarray | None = None, ) → None#

Set the default state of the prim (position, orientation, linear velocity, and angular velocity).

The default state is used after each reset.

Note

The default states will be set during post-reset (e.g., calling .post_reset() or world.reset() methods)

Parameters:

position – Position in the world frame of the prim. Shape is (3, ). If not specified, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). Shape is (4, ). If not specified, the orientation is left unchanged.
linear_velocity – Linear velocity to set the rigid prim to. Shape (3,).
angular_velocity – Angular velocity to set the rigid prim to. Shape (3,).

Example:

>>> prim.set_default_state(
...     position=np.array([1.0, 2.0, 3.0]),
...     orientation=np.array([1.0, 0.0, 0.0, 0.0]),
...     linear_velocity=np.array([0.0, 0.0, 0.0]),
...     angular_velocity=np.array([0.0, 0.0, 0.0])
... )
>>>
>>> prim.post_reset()

set_density(density: float) → None#

Set the density of the rigid body.

Parameters:: density – Density of the rigid body.

Example:

>>> prim.set_density(0.9)

set_linear_velocity(velocity: ndarray) → None#

Set the linear velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid prim state.

Parameters:: velocity – Linear velocity to set the rigid prim to. Shape (3,).

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_mass(mass: float) → None#

Set the mass of the rigid body.

Parameters:: mass – Mass of the rigid body in kg.

Example:

>>> prim.set_mass(1.0)

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_size(size: float) → None#

Set the length of each cube edge.

Parameters:: size – Edge length.

Example

>>> prim.set_size(2.0)

set_sleep_threshold(threshold: float) → None#

Set the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Parameters:: threshold – Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range: [0, inf). Units: distance^2 / second^2.

Example:

>>> prim.set_sleep_threshold(1e-5)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: SingleRigidPrim, FixedCylinder

High level wrapper to create/encapsulate a dynamic cylinder.

Note

Dynamic cylinders (Cylinder shape) have collisions (Collider API) and rigid body dynamics (Rigid Body API).

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Shortname to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world/ local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to false for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Base radius.
height – Cylinder height.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.
mass – Mass in kg.
density – Density.
linear_velocity – Linear velocity in the world frame.
angular_velocity – Angular velocity in the world frame.

Example:

>>> from isaacsim.core.api.objects import DynamicCylinder
>>> import numpy as np
>>>
>>> # create a red dynamic cylinder of mass 1kg at the given path
>>> prim = DynamicCylinder(
...     prim_path="/World/Xform/Cylinder",
...     radius=0.5,
...     height=1.0,
...     color=np.array([1.0, 0.0, 0.0]),
...     mass=1.0
... )
>>> prim
<isaacsim.core.api.objects.cylinder.DynamicCylinder object at 0x7f4e8f5c4a60>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

disable_rigid_body_physics() → None#

Disable the rigid body physics.

When disabled, the object will not be moved by external forces such as gravity and collisions.

Example:

>>> prim.disable_rigid_body_physics()

enable_rigid_body_physics() → None#

Enable the rigid body physics.

When enabled, the object will be moved by external forces such as gravity and collisions.

Example:

>>> prim.enable_rigid_body_physics()

get_angular_velocity() → ndarray#

Get the angular velocity of the rigid body.

Returns:: Current angular velocity of the rigid prim. Shape (3,).

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_com() → tuple[ndarray, ndarray]#

Get the center of mass pose of the rigid body.

Returns:: A tuple of (position, orientation) where position is the center of mass position and orientation is the center of mass orientation.

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_current_dynamic_state() → DynamicState#

Get the current rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The dynamic state of the rigid body prim.

Example:

>>> # for the example the rigid body is in free fall
>>> state = prim.get_current_dynamic_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f740b36f670>
>>> state.position
[  0.99999857   2.0000017  -74.2862    ]
>>> state.orientation
[ 1.0000000e+00 -2.3961178e-07 -4.9891562e-09  4.9388258e-09]
>>> state.linear_velocity
[  0.        0.      -38.09554]
>>> state.angular_velocity
[0. 0. 0.]

get_default_state() → DynamicState#

Get the default rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The default state of the prim that is used after each reset.

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f7411fcbe20>
>>> state.position
[-7.8622378e-07  1.4450421e-06  1.6135601e-07]
>>> state.orientation
[ 9.9999994e-01 -2.7194994e-07  2.9607077e-07  2.7016510e-08]
>>> state.linear_velocity
[0. 0. 0.]
>>> state.angular_velocity
[0. 0. 0.]

get_density() → float#

Get the density of the rigid body.

Returns:: Density of the rigid body.

Example:

>>> prim.get_density()
0

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_height() → float#

Cylinder height.

Returns:: Cylinder height.

Example:

>>> prim.get_height()
1.0

get_linear_velocity() → ndarray#

Get the linear velocity of the rigid body.

Returns:: Current linear velocity of the rigid prim. Shape (3,).

Example:

>>> prim.get_linear_velocity()
[ 1.0812164e-04  6.1415871e-05 -2.1341663e-04]

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_mass() → float#

Get the mass of the rigid body.

Returns:: Mass of the rigid body in kg.

Example:

>>> prim.get_mass()
0

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Base radius.

Returns:: Base radius.

Example:

>>> prim.get_radius()
0.5

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_sleep_threshold() → float#

Get the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Returns:: Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range is [0, inf). Units are distance^2 / second^2.

Example:

>>> prim.get_sleep_threshold()
5e-05

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_angular_velocity(velocity: ndarray) → None#

Set the angular velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid body state.

Parameters:: velocity – Angular velocity to set the rigid prim to. Shape (3,).

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_com( position: ndarray, orientation: ndarray, ) → None#

Set the center of mass pose of the rigid body.

Parameters:

position – Center of mass position. Shape (3,).
orientation – Center of mass orientation. Shape (4,).

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, linear_velocity: ndarray | None = None, angular_velocity: ndarray | None = None, ) → None#

Set the default state of the prim (position, orientation, linear velocity, and angular velocity).

The default state is used after each reset.

Note

The default states will be set during post-reset (e.g., calling .post_reset() or world.reset() methods)

Parameters:

position – Position in the world frame of the prim. Shape is (3, ). If not specified, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). Shape is (4, ). If not specified, the orientation is left unchanged.
linear_velocity – Linear velocity to set the rigid prim to. Shape (3,).
angular_velocity – Angular velocity to set the rigid prim to. Shape (3,).

Example:

>>> prim.set_default_state(
...     position=np.array([1.0, 2.0, 3.0]),
...     orientation=np.array([1.0, 0.0, 0.0, 0.0]),
...     linear_velocity=np.array([0.0, 0.0, 0.0]),
...     angular_velocity=np.array([0.0, 0.0, 0.0])
... )
>>>
>>> prim.post_reset()

set_density(density: float) → None#

Set the density of the rigid body.

Parameters:: density – Density of the rigid body.

Example:

>>> prim.set_density(0.9)

set_height(height: float) → None#

Set the cylinder height.

Parameters:: height – Cylinder height.

Example:

>>> prim.set_height(2.0)

set_linear_velocity(velocity: ndarray) → None#

Set the linear velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid prim state.

Parameters:: velocity – Linear velocity to set the rigid prim to. Shape (3,).

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_mass(mass: float) → None#

Set the mass of the rigid body.

Parameters:: mass – Mass of the rigid body in kg.

Example:

>>> prim.set_mass(1.0)

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the base radius.

Parameters:: radius – Base radius.

Example:

>>> prim.set_radius(1.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_sleep_threshold(threshold: float) → None#

Set the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Parameters:: threshold – Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range: [0, inf). Units: distance^2 / second^2.

Example:

>>> prim.set_sleep_threshold(1e-5)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: SingleRigidPrim, FixedSphere

High level wrapper to create/encapsulate a dynamic sphere.

Note

Dynamic spheres (Sphere shape) have collisions (Collider API) and rigid body dynamics (Rigid Body API)

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the world/local frame of the prim (depends if translation or position is specified). Quaternion is scalar-first (w, x, y, z). shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
color – Color of the visual shape.
radius – Sphere radius.
visual_material – Visual material to be applied to the held prim. If not specified, a default visual material will be added.
physics_material – Physics material to be applied to the held prim. If not specified, a default physics material will be added.
mass – Mass in kg.
density – Density.
linear_velocity – Linear velocity in the world frame.
angular_velocity – Angular velocity in the world frame.

Example:

>>> from isaacsim.core.api.objects import DynamicSphere
>>> import numpy as np
>>>
>>> # create a red dynamic sphere of mass 1 kg at the given path
>>> prim = DynamicSphere(prim_path="/World/Xform/Sphere", color=np.array([1.0, 0.0, 0.0]), mass=1.0)
>>> prim
<isaacsim.core.api.objects.sphere.DynamicSphere object at 0x7f4deaf8f010>

apply_physics_material( physics_material: PhysicsMaterial, weaker_than_descendants: bool = False, ) → None#

Apply physics material to the held prim and optionally its descendants.

Parameters:

physics_material – Physics material to apply to the held prim. Use it to define friction, restitution, and related values. If a physics material is not defined, PhysX defaults are used.
weaker_than_descendants – Whether the material should not override descendant materials.

Example

>>> from isaacsim.core.api.materials import PhysicsMaterial
>>>
>>> # create a rigid body physical material
>>> material = PhysicsMaterial(
...     prim_path="/World/physics_material/aluminum",  # path to the material prim to create
...     dynamic_friction=0.4,
...     static_friction=1.1,
...     restitution=0.1
... )
>>> prim.apply_physics_material(material)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

disable_rigid_body_physics() → None#

Disable the rigid body physics.

When disabled, the object will not be moved by external forces such as gravity and collisions.

Example:

>>> prim.disable_rigid_body_physics()

enable_rigid_body_physics() → None#

Enable the rigid body physics.

When enabled, the object will be moved by external forces such as gravity and collisions.

Example:

>>> prim.enable_rigid_body_physics()

get_angular_velocity() → ndarray#

Get the angular velocity of the rigid body.

Returns:: Current angular velocity of the rigid prim. Shape (3,).

get_applied_physics_material() → PhysicsMaterial#

Return the current applied physics material, whether it was applied using apply_physics_material or not.

Returns:: The current applied physics material.

Example

>>> # given a physics material applied
>>> prim.get_applied_physics_material()
<isaacsim.core.api.materials.physics_material.PhysicsMaterial object at 0x7fb66c30cd30>

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_collision_approximation() → str#

Get the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) use high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Returns:: Approximation used for collision.

Example

>>> prim.get_collision_approximation()
none

get_collision_enabled() → bool#

Check if the Collision API is enabled.

Returns:: True if the Collision API is enabled. Otherwise False.

Example

>>> prim.get_collision_enabled()
True

get_com() → tuple[ndarray, ndarray]#

Get the center of mass pose of the rigid body.

Returns:: A tuple of (position, orientation) where position is the center of mass position and orientation is the center of mass orientation.

get_contact_force_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed contact forces between the prim and filter prims if initialized with filter_paths_expr.

This includes normal contact forces, normal directions, contact points, and separations. The number of contacts per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_contact_force_matrix( dt: float = 1.0, ) → ndarray | Tensor#

Return contact forces between the prim and filter prims if initialized with filter_paths_expr.

The returned data has dimension (self._contact_view.num_filters, 3), where num_filters is determined according to filter_paths_expr.

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (self._geometry_prim_view._contact_view.num_filters, 3).

get_contact_offset() → float#

Get the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Contact offset of the collision shape. Default value is -inf, means default is picked by simulation.

Example:

>>> prim.get_contact_offset()
-inf

get_current_dynamic_state() → DynamicState#

Get the current rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The dynamic state of the rigid body prim.

Example:

>>> # for the example the rigid body is in free fall
>>> state = prim.get_current_dynamic_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f740b36f670>
>>> state.position
[  0.99999857   2.0000017  -74.2862    ]
>>> state.orientation
[ 1.0000000e+00 -2.3961178e-07 -4.9891562e-09  4.9388258e-09]
>>> state.linear_velocity
[  0.        0.      -38.09554]
>>> state.angular_velocity
[0. 0. 0.]

get_default_state() → DynamicState#

Get the default rigid body state (position, orientation, linear velocity, and angular velocity).

Returns:: The default state of the prim that is used after each reset.

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.DynamicState object at 0x7f7411fcbe20>
>>> state.position
[-7.8622378e-07  1.4450421e-06  1.6135601e-07]
>>> state.orientation
[ 9.9999994e-01 -2.7194994e-07  2.9607077e-07  2.7016510e-08]
>>> state.linear_velocity
[0. 0. 0.]
>>> state.angular_velocity
[0. 0. 0.]

get_density() → float#

Get the density of the rigid body.

Returns:: Density of the rigid body.

Example:

>>> prim.get_density()
0

get_friction_data( dt: float = 1.0, ) → ndarray | Tensor#

Return detailed friction forces between the prim and filter prims if initialized with filter_paths_expr.

This includes tangential forces and points. The number of points per pair is determined from a static tensor of dimension (self._contact_view.num_filters), while the starting index of the associated contact in the above tensors is determined from another static tensor of dimension (self._contact_view.num_filters).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), as well as two tensors with shape (self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

get_linear_velocity() → ndarray#

Get the linear velocity of the rigid body.

Returns:: Current linear velocity of the rigid prim. Shape (3,).

Example:

>>> prim.get_linear_velocity()
[ 1.0812164e-04  6.1415871e-05 -2.1341663e-04]

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_mass() → float#

Get the mass of the rigid body.

Returns:: Mass of the rigid body in kg.

Example:

>>> prim.get_mass()
0

get_min_torsional_patch_radius() → float#

Get the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_min_torsional_patch_radius()
0.0

get_net_contact_forces( dt: float = 1.0, ) → ndarray | Tensor#

Return the net contact forces on the prim if contact forces are tracked.

The returned data has dimension (1, 3).

Parameters:: dt – Time step multiplier to convert the underlying impulses to forces. A value of 1.0 leaves the result as contact impulses.
Returns:: Net contact forces of the prim with shape (3).

get_radius() → float#

Sphere radius.

Returns:: Sphere radius.

Example:

>>> prim.get_radius()
1.0

get_rest_offset() → float#

Get the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Returns:: Rest offset of the collision shape.

Example:

>>> prim.get_rest_offset()
-inf

get_sleep_threshold() → float#

Get the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Returns:: Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range is [0, inf). Units are distance^2 / second^2.

Example:

>>> prim.get_sleep_threshold()
5e-05

get_torsional_patch_radius() → float#

Get the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Returns:: Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.get_torsional_patch_radius()
0.0

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Create a physics simulation view if not passed and using PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the prim to its default state (position and orientation).

Note

For an articulation, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed.

Example:

>>> prim.post_reset()

set_angular_velocity(velocity: ndarray) → None#

Set the angular velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid body state.

Parameters:: velocity – Angular velocity to set the rigid prim to. Shape (3,).

set_collision_approximation( approximation_type: str, ) → None#

Set the collision approximation.

Approximation	Full name	Description
`"none"`	Triangle Mesh	The mesh geometry is used directly as a collider without any approximation
`"convexDecomposition"`	Convex Decomposition	A convex mesh decomposition is performed. This results in a set of convex mesh colliders
`"convexHull"`	Convex Hull	A convex hull of the mesh is generated and used as the collider
`"boundingSphere"`	Bounding Sphere	A bounding sphere is computed around the mesh and used as a collider
`"boundingCube"`	Bounding Cube	An optimally fitting box collider is computed around the mesh
`"meshSimplification"`	Mesh Simplification	A mesh simplification step is performed, resulting in a simplified triangle mesh collider
`"sdf"`	SDF Mesh	SDF (Signed-Distance-Field) uses high-detail triangle meshes as collision shape
`"sphereFill"`	Sphere Approximation	A sphere mesh decomposition is performed. This results in a set of sphere colliders

Note

Use Convex Decomposition or SDF (Signed-Distance-Field) tri-meshes to capture details better

Warning

Switching to Convex Decomposition or SDF (Signed-Distance-Field) will have a simulation performance impact due to higher computational cost

Parameters:: approximation_type – Approximation used for collision.

Example:

>>> prim.set_collision_approximation("convexDecomposition")

set_collision_enabled(enabled: bool) → None#

Enable or disable the Collision API.

Parameters:: enabled – Whether to enable the Collision API.

Example

>>> # disable collisions
>>> prim.set_collision_enabled(False)

set_com( position: ndarray, orientation: ndarray, ) → None#

Set the center of mass pose of the rigid body.

Parameters:

position – Center of mass position. Shape (3,).
orientation – Center of mass orientation. Shape (4,).

set_contact_offset(offset: float) → None#

Set the contact offset.

Shapes whose distance is less than the sum of their contact offset values will generate contacts.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Contact offset of a collision shape. Allowed range [maximum(0, rest_offset), 0]. Default value is -inf, means default is picked by simulation based on the shape extent.

Example:

>>> prim.set_contact_offset(0.02)

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, linear_velocity: ndarray | None = None, angular_velocity: ndarray | None = None, ) → None#

Set the default state of the prim (position, orientation, linear velocity, and angular velocity).

The default state is used after each reset.

Note

The default states will be set during post-reset (e.g., calling .post_reset() or world.reset() methods)

Parameters:

position – Position in the world frame of the prim. Shape is (3, ). If not specified, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). Shape is (4, ). If not specified, the orientation is left unchanged.
linear_velocity – Linear velocity to set the rigid prim to. Shape (3,).
angular_velocity – Angular velocity to set the rigid prim to. Shape (3,).

Example:

>>> prim.set_default_state(
...     position=np.array([1.0, 2.0, 3.0]),
...     orientation=np.array([1.0, 0.0, 0.0, 0.0]),
...     linear_velocity=np.array([0.0, 0.0, 0.0]),
...     angular_velocity=np.array([0.0, 0.0, 0.0])
... )
>>>
>>> prim.post_reset()

set_density(density: float) → None#

Set the density of the rigid body.

Parameters:: density – Density of the rigid body.

Example:

>>> prim.set_density(0.9)

set_linear_velocity(velocity: ndarray) → None#

Set the linear velocity of the rigid body in the stage.

Warning

This method will immediately set the rigid prim state.

Parameters:: velocity – Linear velocity to set the rigid prim to. Shape (3,).

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_mass(mass: float) → None#

Set the mass of the rigid body.

Parameters:: mass – Mass of the rigid body in kg.

Example:

>>> prim.set_mass(1.0)

set_min_torsional_patch_radius(radius: float) → None#

Set the minimum radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Minimum radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_min_torsional_patch_radius(0.05)

set_radius(radius: float) → None#

Set the sphere radius.

Parameters:: radius – Sphere radius.

Example:

>>> prim.set_radius(2.0)

set_rest_offset(offset: float) → None#

Set the rest offset.

Two shapes will come to rest at a distance equal to the sum of their rest offset values. If the rest offset is 0, they should converge to touching exactly.

Search for Advanced Collision Detection in PhysX docs for more details.

Warning

The contact offset must be positive and greater than the rest offset

Parameters:: offset – Rest offset of a collision shape. Allowed range [-max_float, contact_offset]. Default value is -inf, means default is picked by simulation. For rigid bodies its zero.

Example:

>>> prim.set_rest_offset(0.01)

set_sleep_threshold(threshold: float) → None#

Set the threshold for the rigid body to enter a sleep state.

Search for Rigid Body Dynamics > Sleeping in PhysX docs for more details.

Parameters:: threshold – Mass-normalized kinetic energy threshold below which an actor may go to sleep. Range: [0, inf). Units: distance^2 / second^2.

Example:

>>> prim.set_sleep_threshold(1e-5)

set_torsional_patch_radius(radius: float) → None#

Set the radius of the contact patch used to apply torsional friction.

Search for “Torsional Patch Radius” in PhysX docs for more details.

Parameters:: radius – Radius of the contact patch used to apply torsional friction. Allowed range [0, max_float].

Example:

>>> prim.set_torsional_patch_radius(0.1)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property geom: pxr.UsdGeom.Gprim#

USD geometry object encapsulated.

Returns:: USD geometry object encapsulated.

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Physics Context#

class PhysicsContext( physics_dt: float | None = None, prim_path: str = '/physicsScene', sim_params: dict = None, set_defaults: bool = True, )#

Bases: object

Provide high-level functions for managing physics scene and simulation settings.

Create a PhysicsScene prim at the specified prim path when no PhysicsScene is present in the current stage. If a PhysicsScene already exists, use the existing scene and apply default settings regardless of the specified prim_path.

Parameters:

physics_dt – Specifies the physics_dt of the simulation.
prim_path – Specifies the prim path to create a PhysicsScene at, only when no PhysicsScene is already defined.
sim_params – Dictionary of simulation parameters to configure physics settings.
set_defaults – Set to True to use the default physics parameters [physics_dt = 1.0/ 60.0, gravity = -9.81 m / s ccd_enabled, stabilization_enabled, GPU dynamics turned off, broadphase type is MBP, solver type is TGS].

Raises:

Exception – If prim_path is not absolute.
Exception – If prim_path already exists and its type is not a PhysicsScene.

enable_ccd(flag: bool) → None#

Enable a second broad phase after integration that makes it possible to prevent objects from tunneling through each other. If GPU is enabled, CCD is not supported and the request will be ignored. If CCD is enabled and then the GPU pipeline is requested, CCD will be disabled automatically.

Parameters:: flag – Enables or disables ccd on the PhysicsScene. CCD is not supported on GPU, so the request will be ignored if GPU is enabled.
Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.

enable_fabric(enable: bool) → None#

Enable or disable fabric for physics simulation.

Parameters:: enable – Whether to enable fabric.

enable_gpu_dynamics(flag: bool) → None#

Enable gpu dynamics pipeline, required for deformables for instance.

Parameters:: flag – Enables or disables gpu dynamics on the PhysicsScene.
Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.

enable_stabilization(flag: bool) → None#

Enable additional stabilization pass in the solver.

Parameters:: flag – Enables or disables stabilization on the PhysicsScene.
Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.

enable_stablization(flag: bool) → None#

Enable additional stabilization pass in the solver.

Deprecated since version Use: enable_stabilization() instead.

Parameters:: flag – Enables or disables stabilization on the PhysicsScene.
Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.

get_bounce_threshold() → float#

Bounce threshold for contact resolution.

Returns:: The current bounce threshold value.
Raises:: Exception – If the physics scene path is invalid.

get_broadphase_type() → str#

Current broadphase algorithm type.

Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
Returns:: Broadphase algorithm used.

get_current_physics_scene_prim() → Usd.Prim | None#

Finds the PhysicsScene prim in the current USD stage.

Returns:: A PhysicsScene prim if found in current stage. Otherwise, None.

get_enable_scene_query_support() → bool#

Enable Scene Query Support attribute in Physx Scene.

Returns:: Enable scene query support attribute.
Raises:: Exception – If the physics scene path is invalid.

get_friction_correlation_distance() → float#

Get the friction correlation distance.

Returns:: The current friction correlation distance value.
Raises:: Exception – If the physics scene path is invalid.

get_friction_offset_threshold() → float#

Get the friction offset threshold.

Returns:: The current friction offset threshold value.
Raises:: Exception – If the physics scene path is invalid.

get_gpu_collision_stack_size() → int#

Get the GPU collision stack size.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The collision stack size.

get_gpu_found_lost_aggregate_pairs_capacity() → int#

Get the GPU capacity for found/lost aggregate contact pairs.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The found/lost aggregate pairs capacity.

get_gpu_found_lost_pairs_capacity() → int#

Get the GPU capacity for found/lost contact pairs.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The found/lost pairs capacity.

get_gpu_heap_capacity() → int#

Get the GPU heap capacity for physics simulation.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The GPU heap capacity in bytes.

get_gpu_max_num_partitions() → int#

Get the maximum number of GPU partitions for simulation.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The maximum number of partitions.

get_gpu_max_particle_contacts() → int#

Get the maximum number of particle contacts on GPU.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The maximum particle contacts count.

get_gpu_max_rigid_contact_count() → int#

Get the maximum number of rigid body contacts on GPU.

Returns:: The maximum rigid contact count.
Raises:: Exception – If the physics scene path is invalid.

get_gpu_max_rigid_patch_count() → int#

Get the maximum number of rigid body contact patches on GPU.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The maximum rigid patch count.

get_gpu_max_soft_body_contacts() → int#

Get the maximum number of soft body contacts on GPU.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The maximum soft body contacts count.

get_gpu_temp_buffer_capacity() → int#

Get the GPU temporary buffer capacity.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The GPU temp buffer capacity in bytes.

get_gpu_total_aggregate_pairs_capacity() → int#

Get the GPU capacity for total aggregate contact pairs.

Raises:: Exception – If the physics scene path is invalid.
Returns:: The total aggregate pairs capacity.

get_gravity() → tuple[list, float]#

Get current gravity.

Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
Returns:: A tuple where the first element is the gravity direction vector and the second element is the magnitude.

get_invert_collision_group_filter() → int#

Get whether collision group filter is inverted.

Raises:: Exception – If the physics scene path is invalid.
Returns:: Whether collision group filtering is inverted.

get_physics_dt() → float#

Current physics dt.

Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
Returns:: Physics dt.

get_physx_update_transformations_settings() → tuple[bool, bool, bool]#

Get how PhysX syncs with USD when transformations are updated.

Returns:: A tuple containing (update_to_usd, update_velocities_to_usd, output_velocities_local_space).

get_solve_articulation_contact_last() → bool#

Retrieve the solveArticulationContactLast state in PhysX scene.

Raises:: Exception – The physics scene path is invalid.
Returns:: Whether the articulation contact constraints and the articulation joint maximum velocity constraints are ordered to be solved last.

get_solver_type() → str#

Get current solver type.

Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
Returns:: Solver used for simulation.

is_ccd_enabled() → bool#

Check if ccd is enabled.

Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
Returns:: True if ccd is enabled, otherwise False.

is_gpu_dynamics_enabled() → bool#

Check if Gpu Dynamics is enabled.

Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
Returns:: True if Gpu Dynamics is enabled, otherwise False.

is_stablization_enabled() → bool#

Check if stabilization is enabled.

Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
Returns:: True if stabilization is enabled, otherwise False.

set_bounce_threshold(value: float) → None#

Set the bounce threshold for contact resolution.

Parameters:: value – The bounce threshold value.
Raises:: Exception – If the physics scene path is invalid.

set_broadphase_type(broadcast_type: str) → None#

Set the broadphase algorithm used in simulation.

Parameters:: broadcast_type – Broadphase algorithm type, such as MBP, GPU, or SAP.
Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.

set_enable_scene_query_support( enable_scene_query_support: bool, ) → None#

Set the Enable Scene Query Support attribute in Physx Scene.

Parameters:: enable_scene_query_support – Whether to enable scene query support.
Raises:: Exception – If the physics scene path is invalid.

set_friction_correlation_distance(value: float) → None#

Set the friction correlation distance.

Parameters:: value – The friction correlation distance value.
Raises:: Exception – If the physics scene path is invalid.

set_friction_offset_threshold(value: float) → None#

Set the friction offset threshold.

Parameters:: value – The friction offset threshold value.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_collision_stack_size(value: int) → None#

Set the GPU collision stack size.

Parameters:: value – The collision stack size.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_found_lost_aggregate_pairs_capacity( value: int, ) → None#

Set the GPU capacity for found/lost aggregate contact pairs.

Parameters:: value – The found/lost aggregate pairs capacity.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_found_lost_pairs_capacity(value: int) → None#

Set the GPU capacity for found/lost contact pairs.

Parameters:: value – The found/lost pairs capacity.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_heap_capacity(value: int) → None#

Set the GPU heap capacity for physics simulation.

Parameters:: value – The GPU heap capacity in bytes.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_max_num_partitions(value: int) → None#

Set the maximum number of GPU partitions for simulation.

Parameters:: value – The maximum number of partitions.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_max_particle_contacts(value: int) → None#

Set the maximum number of particle contacts on GPU.

Parameters:: value – The maximum particle contacts count.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_max_rigid_contact_count(value: int) → None#

Set the maximum number of rigid body contacts on GPU.

Parameters:: value – The maximum rigid contact count.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_max_rigid_patch_count(value: int) → None#

Set the maximum number of rigid body contact patches on GPU.

Parameters:: value – The maximum rigid patch count.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_max_soft_body_contacts(value: int) → None#

Set the maximum number of soft body contacts on GPU.

Parameters:: value – The maximum soft body contacts count.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_temp_buffer_capacity(value: int) → None#

Set the GPU temporary buffer capacity.

Parameters:: value – The GPU temp buffer capacity in bytes.
Raises:: Exception – If the physics scene path is invalid.

set_gpu_total_aggregate_pairs_capacity( value: int, ) → None#

Set the GPU capacity for total aggregate contact pairs.

Parameters:: value – The total aggregate pairs capacity.
Raises:: Exception – If the physics scene path is invalid.

set_gravity(value: float) → None#

Set the gravity direction and magnitude.

Parameters:: value – Gravity value to be used in simulation.
Raises:: Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.

set_invert_collision_group_filter( invert_collision_group_filter: bool, ) → None#

Set whether to invert the collision group filter.

Parameters:: invert_collision_group_filter – Whether to invert collision group filtering.
Raises:: Exception – If the physics scene path is invalid.

set_physics_dt( dt: float = 0.016666666666666666, substeps: int = 1, ) → None#

Set the physics dt on the PhysicsScene.

Parameters:

dt – Physics dt.
substeps – Number of physics steps to run for before rendering a frame.

Raises:

Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
ValueError – Physics dt must be a >= 0.
ValueError – Physics dt must be a <= 1.0.

set_physx_update_transformations_settings( update_to_usd: bool | None = None, update_velocities_to_usd: bool | None = None, output_velocities_local_space: bool | None = None, ) → None#

Set how PhysX syncs with USD when transformations are updated.

Parameters:

update_to_usd – Whether to update transformations to USD.
update_velocities_to_usd – Whether to update velocities to USD.
output_velocities_local_space – Whether to output velocities in the local frame instead of the world frame.

set_solve_articulation_contact_last( solve_articulation_contact_last: bool, ) → None#

Set the solveArticulationContactLast state in PhysX scene.

When enabled, the solver orders the articulation contact constraints and the articulation joint maximum velocity constraints to be solved after all the other constraints.

Parameters:: solve_articulation_contact_last – Whether to reorder the constraints to be solved last.
Raises:: Exception – The physics scene path is invalid.

set_solver_type(solver_type: str) → None#

Set the solver used for simulation.

Parameters:

solver_type – Can be “TGS” or “PGS”.

Raises:

Exception – If the prim path registered in context doesn’t correspond to a valid prim path currently.
ValueError – If solver_type is not “TGS” or “PGS”.

warm_start() → None#: Deprecated method for physics simulation warm start.

Note

This method is deprecated and no longer performs any operations.

property device: str#

Physics simulation device being used.

Returns:: The device name, such as ‘cpu’ or ‘cuda’.

property prim_path: str#

Path to the PhysicsScene prim in the USD stage.

Returns:: The absolute prim path of the PhysicsScene.

property use_fabric: bool#

Whether Fabric is enabled for physics simulation.

Returns:: True if Fabric is enabled, False otherwise.

property use_gpu_pipeline: bool#

Whether GPU pipeline is enabled for physics simulation.

Returns:: True if using CUDA device for physics simulation, False otherwise.

property use_gpu_sim: bool#

Whether GPU simulation is enabled.

Returns:: True if using CUDA device for physics simulation, False otherwise.

Robots#

class Robot( prim_path: str, name: str = 'robot', position: Sequence[float] | None = None, translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, scale: Sequence[float] | None = None, visible: bool | None = None, articulation_controller: ArticulationController | None = None, )#

Bases: SingleArticulation

Implementation (on SingleArticulation class) to deal with an articulation prim as a robot.

Warning

The robot (articulation) object must be initialized in order to be able to operate on it. See the initialize method for more details.

Parameters:

prim_path – Prim path of the Prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
position – Position in the world frame of the prim. shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the world or local frame of the prim (depends if translation or position is specified). quaternion is scalar-first (w, x, y, z). shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.
articulation_controller – A custom ArticulationController which inherits from it.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>> from isaacsim.core.api.robots import Robot
>>>
>>> usd_path = "/home/<user>/Documents/Assets/Robots/FrankaRobotics/FrankaPanda/franka.usd"
>>> prim_path = "/World/envs/env_0/panda"
>>>
>>> # load the Franka Panda robot USD file
>>> stage_utils.add_reference_to_stage(usd_path, prim_path)
>>>
>>> # wrap the prim as a robot (articulation)
>>> prim = Robot(prim_path=prim_path, name="franka_panda")
>>> print(prim)
<isaacsim.core.api.robots.robot.Robot object at 0x7fdd4875a1d0>

apply_action( control_actions: ArticulationAction, ) → None#

Apply joint positions, velocities and/or efforts to control an articulation.

Parameters:: control_actions – Actions to be applied for next physics step.

Hint

High stiffness makes the joints snap faster and harder to the desired target, and higher damping smoothes but also slows down the joint’s movement to target

For position control, set relatively high stiffness and low damping (to reduce vibrations)
For velocity control, stiffness must be set to zero with a non-zero damping
For effort control, stiffness and damping must be set to zero

Example:

>>> from isaacsim.core.utils.types import ArticulationAction
>>>
>>> # move all the robot joints to the indicated position
>>> action = ArticulationAction(joint_positions=np.array([0.0, -1.0, 0.0, -2.2, 0.0, 2.4, 0.8, 0.04, 0.04]))
>>> prim.apply_action(action)
>>>
>>> # close the robot fingers: panda_finger_joint1 (7) and panda_finger_joint2 (8) to 0.0
>>> action = ArticulationAction(joint_positions=np.array([0.0, 0.0]), joint_indices=np.array([7, 8]))
>>> prim.apply_action(action)

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

disable_gravity() → None#

Keep gravity from affecting the robot.

Example:

>>> prim.disable_gravity()

enable_gravity() → None#

Allow gravity to affect the robot.

Example:

>>> prim.enable_gravity()

get_angular_velocity() → ndarray#

Angular velocity of the root articulation prim.

Returns:: 3D angular velocity vector. Shape (3,).

Example:

>>> prim.get_angular_velocity()
[0. 0. 0.]

get_applied_action() → ArticulationAction#

Last applied action.

Returns:: Last applied action. Note that a dictionary is used as the object’s string representation.

Example:

>>> # last applied action: joint_positions -> [0.0, -1.0, 0.0, -2.2, 0.0, 2.4, 0.8, 0.04, 0.04]
>>> prim.get_applied_action()
{'joint_positions': [0.0, -1.0, 0.0, -2.200000047683716, 0.0, 2.4000000953674316,
                     0.800000011920929, 0.03999999910593033, 0.03999999910593033],
 'joint_velocities': [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
 'joint_efforts': [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]}

get_applied_joint_efforts( joint_indices: list | ndarray | None = None, ) → ndarray#

Get the efforts applied to the joints set by the set_joint_efforts method.

Parameters:: joint_indices – Indices to specify which joints to read. If not specified, all joints are read.
Raises:: Exception – If the handlers are not initialized.
Returns:: All or selected articulation joint applied efforts.

Example

>>> # get all applied joint efforts
>>> prim.get_applied_joint_efforts()
[ 0.  0.  0.  0.  0.  0.  0.  0.  0.]
>>>
>>> # get finger applied efforts: panda_finger_joint1 (7) and panda_finger_joint2 (8)
>>> prim.get_applied_joint_efforts(joint_indices=np.array([7, 8]))
[0.  0.]

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_articulation_body_count() → int#

Get the number of bodies (links) that make up the articulation.

Returns:: Amount of bodies.

Example:

>>> prim.get_articulation_body_count()
12

get_articulation_controller() → ArticulationController#

Get the articulation controller.

Note

If no articulation_controller was passed during class instantiation, a default controller of type ArticulationController (a Proportional-Derivative controller that can apply position targets, velocity targets and efforts) will be used

Returns:: Articulation controller.

Example:

>>> prim.get_articulation_controller()
<isaacsim.core.api.controllers.articulation_controller.ArticulationController object at 0x7f04a0060190>

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_dof_index(dof_name: str) → int#

Get a DOF index given its name.

Parameters:: dof_name – Name of the DOF.
Returns:: DOF index.

Example:

>>> prim.get_dof_index("panda_finger_joint2")
8

get_enabled_self_collisions() → uint8#

Get the enable self collisions flag (physxArticulation:enabledSelfCollisions).

Returns:: Self collisions flag, with boolean values interpreted as integers.

Example:

>>> prim.get_enabled_self_collisions()
0

get_joint_positions( joint_indices: list | ndarray | None = None, ) → ndarray#

Get the articulation joint positions.

Parameters:: joint_indices – Indices to specify which joints to read. If not specified, all joints are read.
Returns:: All or selected articulation joint positions.

Example

>>> # get all joint positions
>>> prim.get_joint_positions()
[ 1.1999920e-02 -5.6962633e-01  1.3480479e-08 -2.8105433e+00  6.8284894e-06
  3.0301569e+00  7.3234749e-01  3.9912373e-02  3.9999999e-02]
>>>
>>> # get finger positions: panda_finger_joint1 (7) and panda_finger_joint2 (8)
>>> prim.get_joint_positions(joint_indices=np.array([7, 8]))
[0.03991237  3.9999999e-02]

get_joint_velocities( joint_indices: list | ndarray | None = None, ) → ndarray#

Get the articulation joint velocities.

Parameters:: joint_indices – Indices to specify which joints to read. If not specified, all joints are read.
Returns:: All or selected articulation joint velocities.

Example

>>> # get all joint velocities
>>> prim.get_joint_velocities()
[ 1.91603772e-06 -7.67638255e-03 -2.19138826e-07  1.10636465e-02 -4.63412944e-05
  3.48245539e-02  8.84692147e-02  5.40335372e-04 1.02849208e-05]
>>>
>>> # get finger velocities: panda_finger_joint1 (7) and panda_finger_joint2 (8)
>>> prim.get_joint_velocities(joint_indices=np.array([7, 8]))
[5.4033537e-04 1.0284921e-05]

get_joints_default_state() → JointsState#

Default joint states (positions and velocities).

Returns:: An object that contains the default joint positions and velocities.

Example:

>>> state = prim.get_joints_default_state()
>>> state
<isaacsim.core.utils.types.JointsState object at 0x7f04a0061240>
>>>
>>> state.positions
[ 0.012  -0.57000005  0.  -2.81  0.  3.037  0.785398  0.04  0.04 ]
>>> state.velocities
[0. 0. 0. 0. 0. 0. 0. 0. 0.]

get_joints_state() → JointsState#

Current joint states (positions and velocities).

Returns:: An object that contains the current joint positions and velocities.

Example:

>>> state = prim.get_joints_state()
>>> state
<isaacsim.core.utils.types.JointsState object at 0x7f02f6df57b0>
>>>
>>> state.positions
[ 1.1999920e-02 -5.6962633e-01  1.3480479e-08 -2.8105433e+00 6.8284894e-06
  3.0301569e+00  7.3234749e-01  3.9912373e-02  3.9999999e-02]
>>> state.velocities
[ 1.91603772e-06 -7.67638255e-03 -2.19138826e-07  1.10636465e-02 -4.63412944e-05
  245539e-02  8.84692147e-02  5.40335372e-04  1.02849208e-05]

get_linear_velocity() → ndarray#

Linear velocity of the root articulation prim.

Returns:: 3D linear velocity vector. Shape (3,).

Example:

>>> prim.get_linear_velocity()
[0. 0. 0.]

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_measured_joint_efforts( joint_indices: list | ndarray | None = None, ) → ndarray#

Returns the efforts computed/measured by the physics solver of the joint forces in the DOF motion direction.

Parameters:: joint_indices – Indices to specify which joints to read. If not specified, all joints are read.
Raises:: Exception – If the handlers are not initialized.
Returns:: All or selected articulation joint measured efforts.

Example

>>> # get all joint efforts
>>> prim.get_measured_joint_efforts()
[ 2.7897308e-06 -6.9083519e+00 -3.6398471e-06  1.9158335e+01 -4.3552645e-06
  1.1866090e+00 -4.7079347e-06  3.2339853e-04 -3.2044132e-04]
>>>
>>> # get finger efforts: panda_finger_joint1 (7) and panda_finger_joint2 (8)
>>> prim.get_measured_joint_efforts(joint_indices=np.array([7, 8]))
[ 0.0003234  -0.00032044]

get_measured_joint_forces( joint_indices: list | ndarray | None = None, ) → ndarray#

Get the measured joint reaction forces and torques (link incoming joint forces and torques) to external loads.

Forces and torques are reported in the local body reference frame (child joint frame of the link’s incoming joint).

Note

Since the name->index map for joints has not been exposed yet, it is possible to access the joint names and their indices through the articulation metadata.

prim._articulation_view._metadata.joint_names  # list of names
prim._articulation_view._metadata.joint_indices  # dict of name: index

To retrieve a specific row for the link incoming joint force/torque use joint_index + 1

Parameters:: joint_indices – Indices to specify which joints to read. If not specified, all joints are read.
Raises:: Exception – If the handlers are not initialized.
Returns:: Measured joint forces and torques. Shape is (num_joint + 1, 6). Row index 0 is the incoming joint of the base link. For the last dimension the first 3 values are for forces and the last 3 for torques.

Example

>>> # get all measured joint forces and torques
>>> prim.get_measured_joint_forces()
[[ 0.0000000e+00  0.0000000e+00  0.0000000e+00  0.0000000e+00  0.0000000e+00  0.0000000e+00]
 [ 1.4995076e+02  4.2574748e-06  5.6364370e-04  4.8701895e-05 -6.9072924e+00  3.1881387e-05]
 [-2.8971717e-05 -1.0677823e+02 -6.8384506e+01 -6.9072924e+00 -5.4927128e-05  6.1222494e-07]
 [ 8.7120995e+01 -4.3871860e-05 -5.5795174e+01  5.3687054e-05 -2.4538563e+01  1.3333466e-05]
 [ 5.3519474e-05 -4.8109909e+01  6.0709282e+01  1.9157074e+01 -5.9258469e-05  8.2744418e-07]
 [-3.1691040e+01  2.3313689e-04  3.9990173e+01 -5.8968733e-05 -1.1863431e+00  2.2335558e-05]
 [-1.0809851e-04  1.5340537e+01 -1.5458489e+01  1.1863426e+00  6.1094368e-05 -1.5940281e-05]
 [-7.5418940e+00 -5.0814648e+00 -5.6512990e+00 -5.6385466e-05  3.8859999e-01 -3.4943256e-01]
 [ 4.7421460e+00 -3.1945827e+00  3.5528181e+00  5.5852943e-05  8.4794536e-03  7.6405057e-03]
 [ 4.0760727e+00  2.1640673e-01 -4.0513167e+00 -5.9565349e-04  1.1407082e-02  2.1432268e-06]
 [ 5.1680198e-03 -9.7754575e-02 -9.7093947e-02 -8.4155556e-12 -1.2910691e-12 -1.9347857e-11]
 [-5.1910793e-03  9.7588278e-02 -9.7106412e-02  8.4155573e-12  1.2910637e-12 -1.9347855e-11]]
>>>
>>> # get measured joint force and torque for the fingers
>>> metadata = prim._articulation_view._metadata
>>> joint_indices = 1 + np.array([
...     metadata.joint_indices["panda_finger_joint1"],
...     metadata.joint_indices["panda_finger_joint2"],
... ])
>>> joint_indices
[10 11]
>>> prim.get_measured_joint_forces(joint_indices)
[[ 5.1680198e-03 -9.7754575e-02 -9.7093947e-02 -8.4155556e-12 -1.2910691e-12 -1.9347857e-11]
 [-5.1910793e-03  9.7588278e-02 -9.7106412e-02  8.4155573e-12  1.2910637e-12 -1.9347855e-11]]

get_sleep_threshold() → float#

Get the threshold for articulations to enter a sleep state.

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

Returns:: Sleep threshold.

Example:

>>> prim.get_sleep_threshold()
0.005

get_solver_position_iteration_count() → int#

Get the solver (position) iteration count for the articulation.

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

Returns:: Position iteration count.

Example:

>>> prim.get_solver_position_iteration_count()
32

get_solver_velocity_iteration_count() → int#

Get the solver (velocity) iteration count for the articulation.

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

Returns:: Velocity iteration count.

Example:

>>> prim.get_solver_velocity_iteration_count()
32

get_stabilization_threshold() → float#

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

Search for Stabilization Threshold in PhysX docs for more details.

Returns:: Stabilization threshold.

Example:

>>> prim.get_stabilization_threshold()
0.0009999999

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

get_world_velocity() → ndarray#

Get the articulation root velocity.

Returns:: Current velocity of the root prim. Shape (6,).

initialize( physics_sim_view: omni.physics.tensors.SimulationView = None, ) → None#

Create a physics simulation view if not passed and an articulation view using PhysX tensor API.

Note

If the articulation has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Warning

This method needs to be called after each hard reset (e.g., Stop + Play on the timeline) before interacting with any other class method.

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#

Reset the robot to its default state.

Note

For a robot, in addition to configuring the root prim’s default position and spatial orientation (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) are imposed

Example:

>>> prim.post_reset()

set_angular_velocity(velocity: ndarray) → None#

Set the angular velocity of the root articulation prim.

Warning

This method will immediately set the articulation state

Parameters:: velocity – 3D angular velocity vector. Shape (3,).

Hint

This method belongs to the methods used to set the articulation kinematic state:

set_linear_velocity, set_angular_velocity, set_joint_positions, set_joint_velocities, set_joint_efforts

Example:

>>> prim.set_angular_velocity(np.array([0.1, 0.0, 0.0]))

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_enabled_self_collisions(flag: bool) → None#

Set the enable self collisions flag (physxArticulation:enabledSelfCollisions).

Parameters:: flag – Whether to enable self collisions.

Example:

>>> prim.set_enabled_self_collisions(True)

set_joint_efforts( efforts: ndarray, joint_indices: list | ndarray | None = None, ) → None#

Set the articulation joint efforts.

Note

This method can be used for effort control. For this purpose, there must be no joint drive or the stiffness and damping must be set to zero.

Parameters:

efforts – Articulation joint efforts.
joint_indices – Indices to specify which joints to manipulate. If not specified, all joints are manipulated.

Hint

This method belongs to the methods used to set the articulation kinematic state:

set_linear_velocity, set_angular_velocity, set_joint_positions, set_joint_velocities, set_joint_efforts

Example

>>> # set all the robot joint efforts to 0.0
>>> prim.set_joint_efforts(np.array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]))
>>>
>>> # set only the fingers efforts: panda_finger_joint1 (7) and panda_finger_joint2 (8) to 10
>>> prim.set_joint_efforts(np.array([10, 10]), joint_indices=np.array([7, 8]))

set_joint_positions( positions: ndarray, joint_indices: list | ndarray | None = None, ) → None#

Set the articulation joint positions.

Warning

This method will immediately set (teleport) the affected joints to the indicated value. Use the apply_action method to control robot joints.

Parameters:

positions – Articulation joint positions.
joint_indices – Indices to specify which joints to manipulate. If not specified, all joints are manipulated.

Hint

This method belongs to the methods used to set the articulation kinematic state:

set_linear_velocity, set_angular_velocity, set_joint_positions, set_joint_velocities, set_joint_efforts

Example

>>> # set all the robot joints
>>> prim.set_joint_positions(np.array([0.0, -1.0, 0.0, -2.2, 0.0, 2.4, 0.8, 0.04, 0.04]))
>>>
>>> # set only the fingers in closed position: panda_finger_joint1 (7) and panda_finger_joint2 (8) to 0.0
>>> prim.set_joint_positions(np.array([0.04, 0.04]), joint_indices=np.array([7, 8]))

set_joint_velocities( velocities: ndarray, joint_indices: list | ndarray | None = None, ) → None#

Set the articulation joint velocities.

Warning

This method will immediately set the affected joints to the indicated value. Use the apply_action method to control robot joints.

Parameters:

velocities – Articulation joint velocities.
joint_indices – Indices to specify which joints to manipulate. If not specified, all joints are manipulated.

Hint

This method belongs to the methods used to set the articulation kinematic state:

set_linear_velocity, set_angular_velocity, set_joint_positions, set_joint_velocities, set_joint_efforts

Example

>>> # set all the robot joint velocities to 0.0
>>> prim.set_joint_velocities(np.array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]))
>>>
>>> # set only the fingers velocities: panda_finger_joint1 (7) and panda_finger_joint2 (8) to -0.01
>>> prim.set_joint_velocities(np.array([-0.01, -0.01]), joint_indices=np.array([7, 8]))

set_joints_default_state( positions: ndarray | None = None, velocities: ndarray | None = None, efforts: ndarray | None = None, ) → None#

Set the joint default states (positions, velocities and/or efforts) to be applied after each reset.

Note

The default states will be set during post-reset (e.g., calling .post_reset() or world.reset() methods)

Parameters:

positions – Joint positions.
velocities – Joint velocities.
efforts – Joint efforts.

Example:

>>> # configure default joint states
>>> prim.set_joints_default_state(
...     positions=np.array([0.0, -1.0, 0.0, -2.2, 0.0, 2.4, 0.8, 0.04, 0.04]),
...     velocities=np.zeros(shape=(prim.num_dof,)),
...     efforts=np.zeros(shape=(prim.num_dof,))
... )
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_linear_velocity(velocity: ndarray) → None#

Set the linear velocity of the root articulation prim.

Warning

This method will immediately set the articulation state

Parameters:: velocity – 3D linear velocity vector. Shape (3,).

Hint

This method belongs to the methods used to set the articulation kinematic state:

set_linear_velocity, set_angular_velocity, set_joint_positions, set_joint_velocities, set_joint_efforts

Example:

>>> prim.set_linear_velocity(np.array([0.1, 0.0, 0.0]))

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_sleep_threshold(threshold: float) → None#

Set the threshold for articulations to enter a sleep state.

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

Parameters:: threshold – Sleep threshold.

Example:

>>> prim.set_sleep_threshold(0.01)

set_solver_position_iteration_count(count: int) → None#

Set the solver (position) iteration count for the articulation.

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

Setting a higher number of iterations may improve the fidelity of the simulation, although it may affect its performance.

Parameters:: count – Position iteration count.

Example:

>>> prim.set_solver_position_iteration_count(64)

set_solver_velocity_iteration_count(count: int) → None#

Set the solver (velocity) iteration count for the articulation.

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

Setting a higher number of iterations may improve the fidelity of the simulation, although it may affect its performance.

Parameters:: count – Velocity iteration count.

Example:

>>> prim.set_solver_velocity_iteration_count(64)

set_stabilization_threshold(threshold: float) → None#

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

Search for Stabilization Threshold in PhysX docs for more details.

Parameters:: threshold – Stabilization threshold.

Example:

>>> prim.set_stabilization_threshold(0.005)

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_world_velocity(velocity: ndarray) → None#

Set the articulation root velocity.

Parameters:: velocity – Linear and angular velocity to set on the root prim. Shape (6,).

property dof_names: list[str]#

Prim names for each DOF.

Returns:: Prim names.

Example:

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

property dof_properties: ndarray#

Articulation DOF properties.

DOF properties#
Index	Property name	Description
0	`type`	DOF type: invalid/unknown/uninitialized (0), rotation (1), translation (2)
1	`hasLimits`	Whether the DOF has limits
2	`lower`	Lower DOF limit (in radians or meters)
3	`upper`	Upper DOF limit (in radians or meters)
4	`driveMode`	Drive mode for the DOF: force (1), acceleration (2)
5	`maxVelocity`	Maximum DOF velocity. In radians/s, or stage_units/s
6	`maxEffort`	Maximum DOF effort. In N or N*stage_units
7	`stiffness`	DOF stiffness
8	`damping`	DOF damping

Returns:: Named NumPy array of shape (num_dof, 9).

Example:

>>> # get properties for all DOFs
>>> prim.dof_properties
[(1,  True, -2.8973,  2.8973, 1, 1.0000000e+01, 5220., 60000., 3000.)
 (1,  True, -1.7628,  1.7628, 1, 1.0000000e+01, 5220., 60000., 3000.)
 (1,  True, -2.8973,  2.8973, 1, 5.9390470e+36, 5220., 60000., 3000.)
 (1,  True, -3.0718, -0.0698, 1, 5.9390470e+36, 5220., 60000., 3000.)
 (1,  True, -2.8973,  2.8973, 1, 5.9390470e+36,  720., 25000., 3000.)
 (1,  True, -0.0175,  3.7525, 1, 5.9390470e+36,  720., 15000., 3000.)
 (1,  True, -2.8973,  2.8973, 1, 1.0000000e+01,  720.,  5000., 3000.)
 (2,  True,  0.    ,  0.04  , 1, 3.4028235e+38,  720.,  6000., 1000.)
 (2,  True,  0.    ,  0.04  , 1, 3.4028235e+38,  720.,  6000., 1000.)]
>>>
>>> # property names
>>> prim.dof_properties.dtype.names
('type', 'hasLimits', 'lower', 'upper', 'driveMode', 'maxVelocity', 'maxEffort', 'stiffness', 'damping')
>>>
>>> # get DOF upper limits
>>> prim.dof_properties["upper"]
[ 2.8973  1.7628  2.8973 -0.0698  2.8973  3.7525  2.8973  0.04    0.04  ]
>>>
>>> # get the last DOF (panda_finger_joint2) upper limit
>>> prim.dof_properties["upper"][8]  # or prim.dof_properties[8][3]
0.04

property handles_initialized: bool#

Whether the articulation handler is initialized.

Returns:: Whether the handler was initialized.

Example:

>>> prim.handles_initialized
True

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property num_bodies: int#

Number of articulation links.

Returns:: Number of links.

Example:

>>> prim.num_bodies
9

property num_dof: int#

Number of degrees of freedom of the articulation.

Returns:: Amount of DOFs.

Example:

>>> prim.num_dof
9

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

Bases: Articulation

Implementation on the Articulation class to deal with articulation prims as robots.

This class wraps all matching articulations found at the regex provided in the prim_paths_expr argument.

Warning

The robot articulation view object must be initialized in order to be able to operate on it. See the initialize method for more details.

Parameters:

prim_paths_expr – Prim paths regex to encapsulate all prims that match it. Example: “/World/Env[1-5]/Franka” will match /World/Env1/Franka, /World/Env2/Franka, etc. A non-regex prim path can also be used to encapsulate one rigid prim.
name – Short name to be used as a key by Scene class. Note: Needs to be unique if the object is added to the Scene.
positions – Default positions in the world frame of the prims. Shape is (N, 3).
translations – Default translations in the local frame of the prims with respect to its parent prims. Shape is (N, 3).
orientations – Default quaternion orientations in the world or local frame of the prims, depending on whether translation or position is specified. Quaternion is scalar-first (w, x, y, z). Shape is (N, 4).
scales – Local scales to be applied to the prim’s dimensions in the view. Shape is (N, 3).
visibilities – Set to False for an invisible prim in the stage while rendering. Shape is (N,).

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>> from isaacsim.core.cloner import GridCloner
>>> from isaacsim.core.api.robots import RobotView
>>> from pxr import UsdGeom
>>>
>>> usd_path = "/home/<user>/Documents/Assets/Robots/FrankaRobotics/FrankaPanda/frankas.usd"
>>> env_zero_path = "/World/envs/env_0"
>>> num_envs = 5
>>>
>>> # load the Franka Panda robot USD file
>>> stage_utils.add_reference_to_stage(usd_path, prim_path=f"{env_zero_path}/panda")  # /World/envs/env_0/panda
>>>
>>> # clone the environment (num_envs)
>>> cloner = GridCloner(spacing=1.5)
>>> cloner.define_base_env(env_zero_path)
>>> UsdGeom.Xform.Define(stage_utils.get_current_stage(), env_zero_path)
>>> cloner.clone(source_prim_path=env_zero_path, prim_paths=cloner.generate_paths("/World/envs/env", num_envs))
>>>
>>> # wrap all robots
>>> prims = RobotView(prim_paths_expr="/World/envs/env.*/panda", name="franka_panda_view")
>>> print(prims)
<isaacsim.core.api.robots.robot_view.RobotView object at 0x7f12785a5fc0>

apply_action( control_actions: ArticulationActions, indices: ndarray | list | Tensor | array | None = None, ) → None#

Apply joint position targets, velocity targets, and efforts to control articulations.

Note

This method can be used instead of the separate set_joint_position_targets, set_joint_velocity_targets and set_joint_efforts.

Parameters:

control_actions – Actions to apply for the next physics step.
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Hint

High stiffness makes joints snap faster and harder to the desired target, and higher damping smooths but also slows the joint movement to the target. For position control, set relatively high stiffness and low damping to reduce vibrations. For velocity control, stiffness must be set to zero with non-zero damping. For effort control, stiffness and damping must be set to zero.

Apply visual material to the prims and optionally their prim descendants.

Parameters:

visual_materials – Visual materials to be applied to the prims. Currently supports PreviewSurface, OmniPBR and OmniGlass. If a list is provided then its size has to be equal the view’s size or indices size. If one material is provided it will be applied to all prims in the view.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False. If a list of visual materials is provided then a list has to be provided with the same size for this arg as well.
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Raises:

Exception – length of visual materials != length of prims indexed
Exception – length of visual materials != length of weaker descendants bools arg
Exception – If the prim view is not valid.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prims.apply_visual_materials(material)

destroy() → None#: Clean up and invalidate the prim view by deregistering callbacks and clearing internal state.

Get the angular velocities of prims in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Angular velocities of the prims in the view. Shape is (M, 3).

get_applied_actions( clone: bool = True, ) → ArticulationActions#

Get the last applied articulation actions.

Parameters:: clone – True to return clones of the internal buffers. Otherwise False.
Returns:: Current applied actions, including current position targets, velocity targets, and joint efforts.

Get the joint efforts of articulations in the view.

This method will return the efforts set by the set_joint_efforts method.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Joint efforts of articulations in the view. Shape is (M, K).

Raises:

Exception – If both joint_indices and joint_names are specified.

get_applied_visual_materials( indices: np.ndarray | list | torch.Tensor | wp.array | None = None, ) → list['VisualMaterial']#

Get the current applied visual materials.

Parameters:: indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: A list of the current applied visual materials to the prims if its type is currently supported.
Raises:: Exception – If the prim view is not valid.

Example:

>>> # get all applied visual materials. Returned size is 5 for the example: 5 envs
>>> prims.get_applied_visual_materials()
[<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f829c165de0>,
 <isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f829c165de0>,
 <isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f829c165de0>,
 <isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f829c165de0>,
 <isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f829c165de0>]
>>>
>>> # get the applied visual materials for the first, middle and last of the 5 envs. Returned size is 3
>>> prims.get_applied_visual_materials(indices=np.array([0, 2, 4]))
[<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f829c165de0>,
 <isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f829c165de0>,
 <isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f829c165de0>]

Get armatures for articulation joints in the view.

Search for “Joint Armature” in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Joint armatures for articulations in the view. Shape (M, K).

Raises:

Exception – If both joint_indices and joint_names are specified.

get_articulation_body_count() → int#

Get the number of rigid bodies (links) of the articulations.

Returns:: Maximum number of rigid bodies (links) in the articulation.

Get rigid body center of mass (COM) of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to query. Shape (K,). Where K <= num of bodies.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Rigid body center of mass positions and orientations of articulations in the view. Position shape is (M, K, 3), orientation shape is (M, K, 4).

Get whether gravity is disabled for rigid bodies of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to query. Shape (K,). Where K <= num of bodies.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Rigid body gravity disabled flags of articulations in the view. Shape is (M, K).

get_body_index(body_name: str) → int#

Get a rigid body (link) index in the articulation view given its name.

Parameters:: body_name – Name of the rigid body to query.
Returns:: Index of the rigid body in the articulation buffers.

Example:

>>> # get the index of the left finger: panda_leftfinger
>>> prims.get_body_index("panda_leftfinger")
10

Get rigid body inertias of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to query. Shape (K,). Where K <= num of bodies.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Rigid body inertias of articulations in the view. Shape is (M, K, 9).

Get rigid body inverse inertias of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to query. Shape (K,). Where K <= num of bodies.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Rigid body inverse inertias of articulations in the view. Shape is (M, K, 9).

Example

>>> # get all body inverse inertias. Returned shape is (5, 12, 9) for the example: 5 envs, 12 rigid bodies
>>> prims.get_body_inv_inertias()
[[[7.6990012e+05  0.0  0.0  0.0  6.0475844e+05  0.0  0.0  0.0  4.9185578e+05]
  [5.3514888e+05  0.0  0.0  0.0  6.9545931e+05  0.0  0.0  0.0  1.1027645e+06]
  ...
  [2.3786132e+09  0.0  0.0  0.0  2.5623703e+09  0.0  0.0  0.0  7.4920422e+09]
  [2.3786132e+09  0.0  0.0  0.0  2.5623703e+09  0.0  0.0  0.0  7.4920422e+09]]]
>>>
>>> # get finger body inverse inertias: panda_leftfinger (10) and panda_rightfinger (11)
>>> # for the first, middle and last of the 5 envs. Returned shape is (3, 2, 9)
>>> prims.get_body_inv_inertias(indices=np.array([0, 2, 4]), body_indices=np.array([10, 11]))
[[[2.3786132e+09  0.0  0.0  0.0  2.5623703e+09  0.0  0.0  0.0  7.4920422e+09]
  [2.3786132e+09  0.0  0.0  0.0  2.5623703e+09  0.0  0.0  0.0  7.4920422e+09]]
 ...
 [[2.3786132e+09  0.0  0.0  0.0  2.5623703e+09  0.0  0.0  0.0  7.4920422e+09]
  [2.3786132e+09  0.0  0.0  0.0  2.5623703e+09  0.0  0.0  0.0  7.4920422e+09]]]

Get rigid body inverse masses of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to query. Shape (K,). Where K <= num of bodies.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Rigid body inverse masses of articulations in the view. Shape is (M, K).

Get rigid body masses of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to query. Shape (K,). Where K <= num of bodies.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Rigid body masses of articulations in the view. Shape is (M, K).

Get the Coriolis and centrifugal forces of articulations in the view.

These forces are the joint DOF forces required to counteract Coriolis and centrifugal forces for the given articulation state.

Search for Coriolis and Centrifugal Forces in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs for fixed-base articulations and K <= num of dofs + 6 for floating-base articulations.
joint_names – Joint names to specify which joints to manipulate. Cannot be specified together with joint_indices. Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Coriolis and centrifugal forces of articulations in the view. Shape is (M, K).

Raises:

Exception – If both joint_indices and joint_names are specified.

get_default_state() → XFormPrimViewState#

Get the default states (positions and orientations) defined with the set_default_state method.

Returns:: The default state of the prims that is used after each reset.
Raises:: Exception – If the prim view is not valid.

Example:

>>> state = prims.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimViewState object at 0x7f82f73e3070>
>>> state.positions
[[ 1.5  -0.75  0.  ]
 [ 1.5   0.75  0.  ]
 [ 0.   -0.75  0.  ]
 [ 0.    0.75  0.  ]
 [-1.5  -0.75  0.  ]]
>>> state.orientations
[[1. 0. 0. 0.]
 [1. 0. 0. 0.]
 [1. 0. 0. 0.]
 [1. 0. 0. 0.]
 [1. 0. 0. 0.]]

get_dof_index(dof_name: str) → int#

Get a DOF index in the joint buffers given its name.

Parameters:: dof_name – Name of the joint that corresponds to the degree of freedom to query.
Returns:: Index of the degree of freedom in the joint buffers.

Example:

>>> # get the index of the left finger joint: panda_finger_joint1
>>> prims.get_dof_index("panda_finger_joint1")
7

get_dof_limits() → ndarray | Tensor#

Get the articulations DOF limits (lower and upper).

Returns:: Degrees of freedom position limits. Shape is (N, num_dof, 2). For the last dimension, index 0 is lower limits and index 1 is upper limits.

Example:

>>> # get DOF limits. Returned shape is (5, 9, 2) for the example: 5 envs, 9 DOFs
>>> prims.get_dof_limits()
[[[-2.8973  2.8973]
 [-1.7628  1.7628]
 [-2.8973  2.8973]
 [-3.0718 -0.0698]
 [-2.8973  2.8973]
 [-0.0175  3.7525]
 [-2.8973  2.8973]
 [ 0.      0.04  ]
 [ 0.      0.04  ]]
...
[[-2.8973  2.8973]
 [-1.7628  1.7628]
 [-2.8973  2.8973]
 [-3.0718 -0.0698]
 [-2.8973  2.8973]
 [-0.0175  3.7525]
 [-2.8973  2.8973]
 [ 0.      0.04  ]
 [ 0.      0.04  ]]]

get_dof_types(dof_names: list[str] = None) → list[str]#

Get the DOF types given the DOF names.

Parameters:: dof_names – Names of the joints that correspond to the degrees of freedom to query.
Returns:: Types of the joints that correspond to the degrees of freedom. Types can be invalid, translation, or rotation.

Example:

>>> # get all DOF types
>>> prims.get_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>]
>>>
>>> # get only the finger DOF types: panda_finger_joint1 and panda_finger_joint2
>>> prims.get_dof_types(dof_names=["panda_finger_joint1", "panda_finger_joint2"])
[<DofType.Translation: 1>, <DofType.Translation: 1>]

get_drive_types() → ndarray | Tensor#

Get the articulations DOF drive types.

Returns:: Degrees of freedom drive types. Shape is (N, num_dof).

Get effort modes for articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to query. Cannot be specified together with joint_indices. Shape (K,). Where K <= num of dofs.

Returns:

A list of size (M, K) indicating the effort modes, acceleration or force.

Raises:

Exception – If joint_indices and joint_names are both specified.

Get the enable self collisions flag (physxArticulation:enabledSelfCollisions) for all articulations.

Parameters:: indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: Self collisions flags, with booleans interpreted as integers. Shape (M,).

Example:

>>> # get all self collisions flags. Returned shape is (5,) for the example: 5 envs
>>> prims.get_enabled_self_collisions()
[0 0 0 0 0]
>>>
>>> # get the self collisions flags for the first, middle and last of the 5 envs. Returned shape is (3,)
>>> prims.get_enabled_self_collisions(indices=np.array([0, 2, 4]))
[0 0 0]

Get the dampings of fixed tendons for articulations in the view.

Search for Fixed Tendon in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Fixed tendon dampings of articulations in the view. Shape is (M, K).

Example

>>> # get the fixed tendon dampings
>>> # for the ShadowHand articulation that has 4 fixed tendons (prims.num_fixed_tendons)
>>> prims.get_fixed_tendon_dampings()
[[0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]]

Get the limit stiffness of fixed tendons for articulations in the view.

Search for Fixed Tendon in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Fixed tendon limit stiffnesses of articulations in the view. Shape is (M, K).

Example

>>> # get the fixed tendon limit stiffnesses
>>> # for the ShadowHand articulation that has 4 fixed tendons (prims.num_fixed_tendons)
>>> prims.get_fixed_tendon_limit_stiffnesses()
[[0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]]

Get the limits of fixed tendons for articulations in the view.

Search for Fixed Tendon in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Fixed tendon limits of articulations in the view. Shape is (M, K, 2).

Example

>>> # get the fixed tendon limits
>>> # for the ShadowHand articulation that has 4 fixed tendons (prims.num_fixed_tendons)
>>> prims.get_fixed_tendon_limits()
[[[-0.001  0.001] [-0.001  0.001] [-0.001  0.001] [-0.001  0.001]]
 [[-0.001  0.001] [-0.001  0.001] [-0.001  0.001] [-0.001  0.001]]
 [[-0.001  0.001] [-0.001  0.001] [-0.001  0.001] [-0.001  0.001]]
 [[-0.001  0.001] [-0.001  0.001] [-0.001  0.001] [-0.001  0.001]]
 [[-0.001  0.001] [-0.001  0.001] [-0.001  0.001] [-0.001  0.001]]]

Get the offsets of fixed tendons for articulations in the view.

Search for Fixed Tendon in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Fixed tendon offsets of articulations in the view. Shape is (M, K).

Example:

>>> # get the fixed tendon offsets
>>> # for the ShadowHand articulation that has 4 fixed tendons (prims.num_fixed_tendons)
>>> prims.get_fixed_tendon_offsets()
[[0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]]

Get the rest length of fixed tendons for articulations in the view.

Search for Fixed Tendon in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Fixed tendon rest lengths of articulations in the view. Shape is (M, K).

Example:

>>> # get the fixed tendon rest lengths
>>> # for the ShadowHand articulation that has 4 fixed tendons (prims.num_fixed_tendons)
>>> prims.get_fixed_tendon_rest_lengths()
[[0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]]

Get the stiffness of fixed tendons for articulations in the view.

Search for Fixed Tendon in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Fixed tendon stiffnesses of articulations in the view. Shape is (M, K).

Example

>>> # get the fixed tendon stiffnesses
>>> # for the ShadowHand articulation that has 4 fixed tendons (prims.num_fixed_tendons)
>>> prims.get_fixed_tendon_stiffnesses()
[[0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]
 [0. 0. 0. 0.]]

Get the friction coefficients for the articulation joints in the view.

Search for “Joint Friction Coefficient” in PhysX docs for more details.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Joint friction coefficients for articulations in the view. Shape (M, K).

Raises:

Exception – If both joint_indices and joint_names are specified.

Get the implicit Proportional-Derivative (PD) controller’s Kps (stiffnesses) and Kds (dampings) of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.
clone – True to return clones of the internal buffers. Otherwise False.

Raises:

Exception – If both joint_indices and joint_names are specified.

Returns:

Stiffness and damping of articulations in the view respectively. shapes are (M, K).

Example

>>> # get all joint stiffness and damping. Returned shape is (5, 9) for the example: 5 envs, 9 DOFs
>>> stiffnesses, dampings = prims.get_gains()
>>> stiffnesses
[[60000. 60000. 60000. 60000. 25000. 15000.  5000.  6000.  6000.]
 [60000. 60000. 60000. 60000. 25000. 15000.  5000.  6000.  6000.]
 [60000. 60000. 60000. 60000. 25000. 15000.  5000.  6000.  6000.]
 [60000. 60000. 60000. 60000. 25000. 15000.  5000.  6000.  6000.]
 [60000. 60000. 60000. 60000. 25000. 15000.  5000.  6000.  6000.]]
>>> dampings
[[3000. 3000. 3000. 3000. 3000. 3000. 3000. 1000. 1000.]
 [3000. 3000. 3000. 3000. 3000. 3000. 3000. 1000. 1000.]
 [3000. 3000. 3000. 3000. 3000. 3000. 3000. 1000. 1000.]
 [3000. 3000. 3000. 3000. 3000. 3000. 3000. 1000. 1000.]
 [3000. 3000. 3000. 3000. 3000. 3000. 3000. 1000. 1000.]]
>>>
>>> # get finger joints stiffness and damping: panda_finger_joint1 (7) and panda_finger_joint2 (8)
>>> # for the first, middle and last of the 5 envs. Returned shape is (3, 2)
>>> stiffnesses, dampings = prims.get_gains(indices=np.array([0, 2, 4]), joint_indices=np.array([7, 8]))
>>> stiffnesses
[[6000. 6000.]
 [6000. 6000.]
 [6000. 6000.]]
>>> dampings
[[1000. 1000.]
 [1000. 1000.]
 [1000. 1000.]]

Get the generalized gravity forces of articulations in the view.

These forces are the joint DOF forces required to counteract gravitational forces for the given articulation pose.

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

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs for fixed-base articulations and K <= num of dofs + 6 for floating-base articulations.
joint_names – Joint names to specify which joints to manipulate. Cannot be specified together with joint_indices. Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Generalized gravity forces of articulations in the view. Shape is (M, K).

Raises:

Exception – If both joint_indices and joint_names are specified.

get_jacobian_shape() → ndarray | Tensor | array#

Get the Jacobian matrix shape of a single articulation.

The Jacobian matrix maps the joint space velocities of a DOF to its Cartesian and angular velocities.

The shape of the Jacobian depends on the number of links (rigid bodies), DOFs, and whether the articulation base is fixed, such as robotic manipulators, or not fixed, such as mobile robots.

Fixed articulation base: (num_bodies - 1, 6, num_dof)
Non-fixed articulation base: (num_bodies, 6, num_dof + 6)

Each body 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 non-fixed base cases, correspond to the linear and angular degrees of freedom of the free root link.

Returns:: Shape of Jacobian for a single articulation.

Get the Jacobian matrices of articulations in the view.

Note

The first dimension corresponds to the amount of wrapped articulations while the last 3 dimensions are the Jacobian matrix shape. Refer to the get_jacobian_shape method for details about the Jacobian matrix shape.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Jacobian matrices of articulations in the view. Shape is (M, jacobian_shape).

get_joint_index(joint_name: str) → int#

Get a joint index in the joint buffers given its name.

Parameters:: joint_name – Name of the joint that corresponds to the index of the joint in the articulation.
Returns:: Index of the joint in the joint buffers.

Get the maximum joint velocities for articulation dofs in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Raises:

Exception – If both joint_indices and joint_names are specified.

Returns:

Maximum joint velocities for articulations dofs in the view. shape (M, K).

Get the joint positions of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate. Cannot be specified together with joint_indices. Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Joint positions of articulations in the view. Shape is (M, K).

Raises:

Exception – If joint_indices and joint_names are both specified.

Get the joint velocities of articulations in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate. Cannot be specified together with joint_indices. Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Joint velocities of articulations in the view. Shape is (M, K).

Raises:

Exception – If joint_indices and joint_names are both specified.

get_joints_default_state() → JointsState#

Get the default joint states defined with the set_joints_default_state method.

Returns:: An object that contains the default joint states.

get_joints_state() → JointsState#

Get the current joint states (positions and velocities).

Returns:: An object that contains the current joint positions and velocities.

Get the linear velocities of prims in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Linear velocities of the prims in the view. Shape is (M, 3).

get_link_index(link_name: str) → int#

Get a link index in the link buffers given its name.

Parameters:: link_name – Name of the link that corresponds to the index of the link in the articulation.
Returns:: Index of the link in the link buffers.

Get prim poses in the view with respect to the local frame, which is the prim’s parent frame.

Parameters:: indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: A tuple containing positions in the local frame of the prims and quaternion orientations in the local frame of the prims. Position shape is (M, 3). Quaternion is scalar-first (w, x, y, z), and orientation shape is (M, 4).

Get prim scales in the view with respect to the local frame (the parent’s frame).

Parameters:: indices – indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: scales applied to the prim’s dimensions in the local frame. shape is (M, 3).
Raises:: Exception – If the prim view is not valid.

Example:

>>> # get all prims scales with respect to the local frame.
>>> # Returned shape is (5, 3) for the example: 5 envs
>>> prims.get_local_scales()
[[1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]]
>>>
>>> # get only the prims scales with respect to the local frame for the first, middle and last of the 5 envs.
>>> # Returned shape is (3, 3) for the example: 3 envs selected
>>> prims.get_local_scales(indices=np.array([0, 2, 4]))
[[1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]]

Get the mass matrices of articulations in the view.

Note

The first dimension corresponds to the amount of wrapped articulations while the last 2 dimensions are the mass matrix shape. Refer to the get_mass_matrix_shape method for details about the mass matrix shape.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Mass matrices of articulations in the view. Shape is (M, mass_matrix_shape).

get_mass_matrix_shape() → ndarray | Tensor | array#

Get the mass matrix shape of a single articulation.

The mass matrix contains the generalized mass of the robot depending on the current configuration.

The shape of the mass matrix depends on the number of DOFs and whether the articulation is fixed-base or floating-base. For fixed-base articulations the shape is (num_dof, num_dof). For floating-base articulations the shape is (num_dof + 6, num_dof + 6).

Returns:: Shape of mass matrix for a single articulation.

Get the maximum efforts for articulation in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Raises:

Exception – If both joint_indices and joint_names are specified.

Returns:

Maximum efforts for articulations in the view. shape (M, K).

Example

>>> # get all joint maximum efforts. Returned shape is (5, 9) for the example: 5 envs, 9 DOFs
>>> prims.get_max_efforts()
[[5220. 5220. 5220. 5220.  720.  720.  720.  720.  720.]
 [5220. 5220. 5220. 5220.  720.  720.  720.  720.  720.]
 [5220. 5220. 5220. 5220.  720.  720.  720.  720.  720.]
 [5220. 5220. 5220. 5220.  720.  720.  720.  720.  720.]
 [5220. 5220. 5220. 5220.  720.  720.  720.  720.  720.]]
>>>
>>> # get finger joint maximum efforts: panda_finger_joint1 (7) and panda_finger_joint2 (8)
>>> # for the first, middle and last of the 5 envs. Returned shape is (3, 2)
>>> prims.get_max_efforts(indices=np.array([0, 2, 4]), joint_indices=np.array([7, 8]))
[[720. 720.]
 [720. 720.]
 [720. 720.]]

Return the efforts computed or measured by the physics solver from joint forces in the DOF motion direction.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to query. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate. Cannot be specified together with joint_indices. Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Computed joint efforts of articulations in the view. Shape is (M, K).

Raises:

Exception – If joint_indices and joint_names are both specified.

Get the measured joint reaction forces and torques to external loads.

Forces and torques are reported in the local body reference frame, which is the child joint frame of the link’s incoming joint.

Note

To retrieve a specific row for the link incoming joint force or torque, use joint_index + 1 when specifying the joint_indices parameter. For the joint_names parameter, the conversion is done internally.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Link indices to specify which link incoming joints to query. Shape (K,). Where K <= num of links or bodies.
joint_names – Joint names to specify which joints to manipulate. Cannot be specified together with joint_indices. Shape (K,). Where K <= num of dofs.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Joint forces and torques of articulations in the view. Shape is (M, num_joint + 1, 6). Column index 0 is the incoming joint of the base link. For the last dimension, the first 3 values are forces and the last 3 values are torques.

Raises:

Exception – If joint_indices and joint_names are both specified.

Get the threshold for articulations to enter a sleep state.

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

Parameters:: indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: Sleep thresholds. Shape (M,).

Example:

>>> # get all sleep thresholds. Returned shape is (5,) for the example: 5 envs
>>> prims.get_sleep_thresholds()
[0.005 0.005 0.005 0.005 0.005]
>>>
>>> # get the sleep thresholds for the first, middle and last of the 5 envs. Returned shape is (3,)
>>> prims.get_sleep_thresholds(indices=np.array([0, 2, 4]))
[0.005 0.005 0.005]

Get the solver (position) iteration count for the articulations.

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 to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: Position iteration count. Shape (M,).

Example:

>>> # get all position iteration count. Returned shape is (5,) for the example: 5 envs
>>> prims.get_solver_position_iteration_counts()
[32 32 32 32 32]
>>>
>>> # get the position iteration count for the first, middle and last of the 5 envs. Returned shape is (3,)
>>> prims.get_solver_position_iteration_counts(indices=np.array([0, 2, 4]))
[32 32 32]

Get the solver (velocity) iteration count for the articulations.

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 to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: Velocity iteration count. Shape (M,).

Example:

>>> # get all velocity iteration count. Returned shape is (5,) for the example: 5 envs
>>> prims.get_solver_velocity_iteration_counts()
[32 32 32 32 32]
>>>
>>> # get the velocity iteration count for the first, middle and last of the 5 envs. Returned shape is (3,)
>>> prims.get_solver_velocity_iteration_counts(indices=np.array([0, 2, 4]))
[32 32 32]

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

Search for Stabilization Threshold in PhysX docs for more details.

Parameters:: indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: Stabilization threshold. Shape (M,).

Example:

>>> # get all stabilization thresholds. Returned shape is (5,) for the example: 5 envs
>>> prims.get_solver_velocity_iteration_counts()
[0.001 0.001 0.001 0.001 0.001]
>>>
>>> # get the stabilization thresholds for the first, middle and last of the 5 envs. Returned shape is (3,)
>>> prims.get_solver_velocity_iteration_counts(indices=np.array([0, 2, 4]))
[0.001 0.001 0.001]

Get the linear and angular velocities of prims in the view.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.

Returns:

Linear and angular velocities of the prims in the view concatenated. Shape is (M, 6). For the last dimension, the first 3 values are for linear velocities and the last 3 are for angular velocities.

Return the current visibilities of the prims in stage.

Parameters:: indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: Shape (M,) with type bool, where each item holds True if the prim is visible in stage. False otherwise.
Raises:: Exception – If the prim view is not valid.

Example:

>>> # get all visibilities. Returned shape is (5,) for the example: 5 envs
>>> prims.get_visibilities()
[ True  True  True  True  True]
>>>
>>> # get the visibilities for the first, middle and last of the 5 envs. Returned shape is (3,)
>>> prims.get_visibilities(indices=np.array([0, 2, 4]))
[ True  True  True]

Get the poses of the prims in the view with respect to the world’s frame.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – True to return a clone of the internal buffer. Otherwise False.
usd – True to query from USD. Otherwise False to query from Fabric data.

Returns:

A tuple containing positions in the world frame of the prims and quaternion orientations in the world frame of the prims. Position shape is (M, 3). Quaternion is scalar-first (w, x, y, z), and orientation shape is (M, 4).

Get prim scales in the view with respect to the world’s frame.

Parameters:: indices – indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: scales applied to the prim’s dimensions in the world frame. shape is (M, 3).
Raises:: Exception – If the prim view is not valid.

Example:

>>> # get all prims scales with respect to the world's frame.
>>> # Returned shape is (5, 3) for the example: 5 envs
>>> prims.get_world_scales()
[[1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]]
>>>
>>> # get only the prims scales with respect to the world's frame for the first, middle and last of the 5 envs.
>>> # Returned shape is (3, 3) for the example: 3 envs selected
>>> prims.get_world_scales(indices=np.array([0, 2, 4]))
[[1. 1. 1.]
 [1. 1. 1.]
 [1. 1. 1.]]

initialize( physics_sim_view: omni.physics.tensors.SimulationView = None, ) → None#

Initialize the articulation physics view when the physics handle is not valid.

Parameters:

physics_sim_view – Current physics simulation view.

Raises:

Exception – If no articulations match the articulation prim path expressions.
AssertionError – If the articulation physics view is not homogeneous.

Example:

>>> prims.initialize()

is_physics_handle_valid() → bool#

Check whether the articulation view’s physics handler is initialized.

Warning

If the physics handler is not valid, many methods that require PhysX return None.

Returns:: False if .initialize() must be called again for the physics handle to be valid. Otherwise True.

Example:

>>> prims.is_physics_handle_valid()
True

is_valid( indices: ndarray | list | Tensor | array | None = None, ) → bool#

Check whether the prim view is valid.

Parameters:: indices – Indices accepted for API compatibility. The current view validity is returned regardless of indices.
Returns:: True if the prim view has not been invalidated by destroy or matching prim deletion. False otherwise.

Example:

>>> prims.is_valid()
True

is_visual_material_applied( indices: ndarray | list | Tensor | array | None = None, ) → list[bool]#

Check if there is a visual material applied.

Parameters:: indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
Returns:: True if there is a visual material applied to the corresponding prim in the view. False otherwise.
Raises:: Exception – If the prim view is not valid.

Example:

>>> # given a visual material that is applied only to the first and the last environment
>>> prims.is_visual_material_applied()
[True, False, False, False, True]
>>>
>>> # check for the first, middle and last of the 5 envs
>>> prims.is_visual_material_applied(indices=np.array([0, 2, 4]))
[True, False, True]

pause_motion() → None#: Pause the motion of all articulations wrapped under the Articulation.

post_reset() → None#

Reset the robots to their default states.

Note

For the robots, in addition to configuring the root prim’s default positions and spatial orientations (defined via the set_default_state method), the joint’s positions, velocities, and efforts (defined via the set_joints_default_state method) and the joint’s stiffness and dampings (defined via the set_gains method) are imposed

Example:

>>> prims.post_reset()

resume_motion() → None#: Resume the motion of all articulations wrapped under the Articulation using the position and velocity DOF targets cached when pause_motion was called.

Set the angular velocities of the prims in the view.

The method does this through the PhysX API only. It has to be called after initialization. Note: This method is not supported for the GPU pipeline. set_velocities method should be used instead.

Warning

This method will immediately set the articulation state.

Parameters:

velocities – Angular velocities to set the rigid prims to. Shape is (M, 3).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Hint

This method belongs to the methods used to set the articulation kinematic state:

set_velocities (set_linear_velocities, set_angular_velocities), set_joint_positions, set_joint_velocities, set_joint_efforts.

Set armatures for articulation joints in the view.

Search for “Joint Armature” in PhysX docs for more details.

Parameters:

values – Armatures for articulation joints in the view. Shape (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Set body center of mass (COM) positions and orientations for articulation bodies in the view.

Parameters:

positions – Body center of mass positions for articulations in the view. shape (M, K, 3).
orientations – Body center of mass orientations for articulations in the view. shape (M, K, 4).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to manipulate. Shape (K,). Where K <= num of bodies.

Example

>>> # set the center of mass for all the articulation rigid bodies to the indicated values.
>>> # Since there are 5 envs, the inertias are repeated 5 times
>>> positions = np.tile(np.array([0.01, 0.02, 0.03]), (num_envs, prims.num_bodies, 1))
>>> orientations = np.tile(np.array([1.0, 0.0, 0.0, 0.0]), (num_envs, prims.num_bodies, 1))
>>> prims.set_body_coms(positions, orientations)
>>>
>>> # set the fingers center of mass: panda_leftfinger (10) and panda_rightfinger (11) to 0.2
>>> # for the first, middle and last of the 5 envs
>>> positions = np.tile(np.array([0.01, 0.02, 0.03]), (3, 2, 1))
>>> orientations = np.tile(np.array([1.0, 0.0, 0.0, 0.0]), (3, 2, 1))
>>> prims.set_body_coms(
...     positions, orientations, indices=np.array([0, 2, 4]), body_indices=np.array([10, 11])
... )

Set whether gravity is disabled for articulation bodies in the view.

Parameters:

values – Gravity disabled flags for articulations in the view. shape (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to manipulate. Shape (K,). Where K <= num of bodies.

Set body inertias for articulation bodies in the view.

Parameters:

values – Body inertias for articulations in the view. shape (M, K, 9).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to manipulate. Shape (K,). Where K <= num of bodies.

Example

>>> # set the inertias for all the articulation rigid bodies to the indicated values.
>>> # Since there are 5 envs, the inertias are repeated 5 times
>>> inertias = np.tile(
...     np.array([0.1, 0.0, 0.0, 0.0, 0.1, 0.0, 0.0, 0.0, 0.1]),
...     (num_envs, prims.num_bodies, 1),
... )
>>> prims.set_body_inertias(inertias)
>>>
>>> # set the fingers inertias: panda_leftfinger (10) and panda_rightfinger (11) to 0.2
>>> # for the first, middle and last of the 5 envs
>>> inertias = np.tile(np.array([0.1, 0.0, 0.0, 0.0, 0.1, 0.0, 0.0, 0.0, 0.1]), (3, 2, 1))
>>> prims.set_body_inertias(inertias, indices=np.array([0, 2, 4]), body_indices=np.array([10, 11]))

Set body masses for articulation bodies in the view.

Parameters:

values – Body masses for articulations in the view. shape (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
body_indices – Body indices to specify which bodies to manipulate. Shape (K,). Where K <= num of bodies.

Example

>>> # set the masses for all the articulation rigid bodies to the indicated values.
>>> # Since there are 5 envs, the masses are repeated 5 times
>>> masses = np.tile(
...     np.array([1.2, 1.1, 1.0, 0.9, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2, 0.2]),
...     (num_envs, 1),
... )
>>> prims.set_body_masses(masses)
>>>
>>> # set the fingers masses: panda_leftfinger (10) and panda_rightfinger (11) to 0.2
>>> # for the first, middle and last of the 5 envs
>>> masses = np.tile(np.array([0.2, 0.2]), (3, 1))
>>> prims.set_body_masses(masses, indices=np.array([0, 2, 4]), body_indices=np.array([10, 11]))

Set the default state of the prims (positions and orientations), that will be used after each reset.

Note

The default states will be set during post-reset (e.g., calling .post_reset() or world.reset() methods)

Parameters:

positions – Positions in the world frame of the prim. shape is (M, 3).
orientations – Quaternion orientations in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (M, 4).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Raises:

Exception – If the prim view is not valid.

Example:

>>> # configure default states for all prims
>>> positions = np.zeros((num_envs, 3))
>>> positions[:, 0] = np.arange(num_envs)
>>> orientations = np.tile(np.array([1.0, 0.0, 0.0, 0.0]), (num_envs, 1))
>>> prims.set_default_state(positions=positions, orientations=orientations)
>>>
>>> # set default states during post-reset
>>> prims.post_reset()

Set effort modes for articulations in the view.

Parameters:

mode – Effort mode to be applied to prims in the view, either acceleration or force.
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If mode is not force or acceleration.
Exception – If both joint_indices and joint_names are specified.

Example

>>> # set the effort mode for all joints to 'force'
>>> prims.set_effort_modes("force")
>>>
>>> # set only the finger joints effort mode to 'force' for the first, middle and last of the 5 envs
>>> prims.set_effort_modes("force", indices=np.array([0, 2, 4]), joint_indices=np.array([7, 8]))

Set the enable self collisions flag (physxArticulation:enabledSelfCollisions).

Parameters:

flags – True to enable self collision. Otherwise False. Shape (M,).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Example:

>>> # enable the self collisions flag for all envs
>>> prims.set_enabled_self_collisions(np.full((num_envs,), True))
>>>
>>> # enable the self collisions flag only for the first, middle and last of the 5 envs
>>> prims.set_enabled_self_collisions(np.full((3,), True), indices=np.array([0, 2, 4]))

Set fixed tendon properties for articulations in the view.

Search for Fixed Tendon in PhysX docs for more details.

Parameters:

stiffnesses – Fixed tendon stiffnesses for articulations in the view. Shape (M, K).
dampings – Fixed tendon dampings for articulations in the view. Shape (M, K).
limit_stiffnesses – Fixed tendon limit stiffnesses for articulations in the view. Shape (M, K).
limits – Fixed tendon limits for articulations in the view. Shape (M, K, 2).
rest_lengths – Fixed tendon rest lengths for articulations in the view. Shape (M, K).
offsets – Fixed tendon offsets for articulations in the view. Shape (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Example:

>>> # set the limit stiffnesses and dampings
>>> # for the ShadowHand articulation that has 4 fixed tendons (prims.num_fixed_tendons)
>>> limit_stiffnesses = np.full((num_envs, prims.num_fixed_tendons), fill_value=10.0)
>>> dampings = np.full((num_envs, prims.num_fixed_tendons), fill_value=0.1)
>>> prims.set_fixed_tendon_properties(dampings=dampings, limit_stiffnesses=limit_stiffnesses)

Set the friction coefficients for articulation joints in the view.

Search for “Joint Friction Coefficient” in PhysX docs for more details.

Parameters:

values – Friction coefficients for articulation joints in the view. Shape (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_names and joint_indices are specified.

Example:

>>> # set all joint friction coefficients to 0.05 for all envs
>>> prims.set_friction_coefficients(np.full((num_envs, prims.num_dof), 0.05))
>>>
>>> # set only the finger joint (panda_finger_joint1 (7) and panda_finger_joint2 (8)) friction coefficients
>>> # for the first, middle and last of the 5 envs to 0.05
>>> prims.set_friction_coefficients(
...     np.full((3, 2), 0.05), indices=np.array([0, 2, 4]), joint_indices=np.array([7, 8])
... )

Set the implicit Proportional-Derivative (PD) controller’s Kps (stiffnesses) and Kds (dampings) of articulations in the view.

Parameters:

kps – Stiffness of the drives. shape is (M, K).
kds – Damping of the drives. shape is (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.
save_to_usd – True to save the gains in USD. Otherwise False.

Raises:

Exception – If both joint_indices and joint_names are specified.

Example

>>> # set the gains (stiffnesses and dampings) for all the articulation joints to the indicated values.
>>> # Since there are 5 envs, the gains are repeated 5 times
>>> stiffnesses = np.tile(
...     np.array([100000, 100000, 100000, 100000, 80000, 80000, 80000, 50000, 50000]),
...     (num_envs, 1),
... )
>>> dampings = np.tile(
...     np.array([8000, 8000, 8000, 8000, 5000, 5000, 5000, 2000, 2000]),
...     (num_envs, 1),
... )
>>> prims.set_gains(kps=stiffnesses, kds=dampings)
>>>
>>> # set the fingers gains (stiffnesses and dampings): panda_finger_joint1 (7) and panda_finger_joint2 (8)
>>> # to 50000 and 2000 respectively for the first, middle and last of the 5 envs
>>> stiffnesses = np.tile(np.array([50000, 50000]), (3, 1))
>>> dampings = np.tile(np.array([2000, 2000]), (3, 1))
>>> prims.set_gains(
...     kps=stiffnesses,
...     kds=dampings,
...     indices=np.array([0, 2, 4]),
...     joint_indices=np.array([7, 8]),
... )

Set the joint efforts of articulations in the view.

Note

This method can be used for effort control. For this purpose, there must be no joint drive or the stiffness and damping must be set to zero.

Parameters:

efforts – Efforts of articulations in the view to be set to in the next frame. Shape is (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Hint

This method belongs to the methods used to set the articulation kinematic states:

set_velocities (set_linear_velocities, set_angular_velocities), set_joint_positions, set_joint_velocities, set_joint_efforts

Set the joint position targets for the implicit Proportional-Derivative (PD) controllers.

Note

This is an independent method for controlling joints. To apply multiple targets (position, velocity, and/or effort) in the same call, consider using the apply_action method

Parameters:

positions – Joint position targets for the implicit PD controller. Shape is (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Hint

High stiffness makes the joints snap faster and harder to the desired target, and higher damping smooths but also slows down the joint’s movement to target

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

Set the joint positions of articulations in the view.

Warning

This method will immediately set (teleport) the affected joints to the indicated value. Use the set_joint_position_targets or the apply_action methods to control the articulation joints.

Parameters:

positions – Joint positions of articulations in the view to be set to in the next frame. Shape is (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Hint

This method belongs to the methods used to set the articulation kinematic states:

set_velocities (set_linear_velocities, set_angular_velocities), set_joint_positions, set_joint_velocities, set_joint_efforts

Set the joint velocities of articulations in the view.

Warning

This method will immediately set the affected joints to the indicated value. Use the set_joint_velocity_targets or the apply_action methods to control the articulation joints.

Parameters:

velocities – Joint velocities of articulations in the view to be set to in the next frame. Shape is (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Hint

This method belongs to the methods used to set the articulation kinematic states:

set_velocities (set_linear_velocities, set_angular_velocities), set_joint_positions, set_joint_velocities, set_joint_efforts

Set the joint velocity targets for the implicit Proportional-Derivative (PD) controllers.

Note

This is an independent method for controlling joints. To apply multiple targets (position, velocity, and/or effort) in the same call, consider using the apply_action method

Parameters:

velocities – Joint velocity targets for the implicit PD controller. Shape is (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Hint

High stiffness makes the joints snap faster and harder to the desired target, and higher damping smooths but also slows down the joint’s movement to target

For velocity control, stiffness must be set to zero with a non-zero damping

Set the joints default state (joint positions, velocities, and efforts) to be applied after each reset.

Note

The default states will be set during post-reset, such as calling .post_reset() or world.reset().

Parameters:

positions – Default joint positions. Shape is (N, num of dofs).
velocities – Default joint velocities. Shape is (N, num of dofs).
efforts – Default joint efforts. Shape is (N, num of dofs).

Set the linear velocities of the prims in the view.

The method does this through the PhysX API only. It has to be called after initialization. Note: This method is not supported for the GPU pipeline. set_velocities method should be used instead.

Warning

This method will immediately set the articulation state.

Parameters:

velocities – Linear velocities to set the rigid prims to. Shape is (M, 3).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Hint

This method belongs to the methods used to set the articulation kinematic state:

set_velocities (set_linear_velocities, set_angular_velocities), set_joint_positions, set_joint_velocities, set_joint_efforts.

Set prim poses in the view with respect to the local frame, which is the prim’s parent frame.

Warning

This method changes the prim poses immediately to the indicated values.

Parameters:

translations – Translations in the local frame of the prims with respect to their parent prim. Shape is (M, 3). If not defined, translations are left unchanged.
orientations – Quaternion orientations in the local frame of the prims. Quaternion is scalar-first (w, x, y, z). Shape is (M, 4). If not defined, orientations are left unchanged.
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Hint

This method belongs to the methods used to set the prim state.

Set prim scales in the view with respect to the local frame (the prim’s parent frame).

Parameters:

scales – scales to be applied to the prim’s dimensions in the view. shape is (M, 3).
indices – indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Raises:

Exception – If the prim view is not valid.

Example:

>>> # set the scale for all prims. Since there are 5 envs, the scale is repeated 5 times
>>> scales = np.tile(np.array([1.0, 0.75, 0.5]), (num_envs, 1))
>>> prims.set_local_scales(scales)
>>>
>>> # set the scale for the first, middle and last of the 5 envs
>>> scales = np.tile(np.array([1.0, 0.75, 0.5]), (3, 1))
>>> prims.set_local_scales(scales, indices=np.array([0, 2, 4]))

Set maximum efforts for articulation in the view.

Parameters:

values – Maximum efforts for articulations in the view. shape (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Example

>>> # set the max efforts for all the articulation joints to the indicated values.
>>> # Since there are 5 envs, the joint efforts are repeated 5 times
>>> max_efforts = np.tile(
...     np.array([10000, 9000, 8000, 7000, 6000, 5000, 4000, 1000, 1000]),
...     (num_envs, 1),
... )
>>> prims.set_max_efforts(max_efforts)
>>>
>>> # set the fingers max efforts: panda_finger_joint1 (7) and panda_finger_joint2 (8) to 1000
>>> # for the first, middle and last of the 5 envs
>>> max_efforts = np.tile(np.array([1000, 1000]), (3, 1))
>>> prims.set_max_efforts(max_efforts, indices=np.array([0, 2, 4]), joint_indices=np.array([7, 8]))

Set maximum velocities for articulation in the view.

Parameters:

values – Maximum velocities for articulations in the view. shape (M, K).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Set the threshold for articulations to enter a sleep state.

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

Parameters:

thresholds – Sleep thresholds to be applied. Shape (M,).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Example:

>>> # set the sleep threshold for all envs
>>> prims.set_sleep_thresholds(np.full((num_envs,), 0.01))
>>>
>>> # set only the sleep threshold for the first, middle and last of the 5 envs
>>> prims.set_sleep_thresholds(np.full((3,), 0.01), indices=np.array([0, 2, 4]))

Set the solver (position) iteration count for the articulations.

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

Setting a higher number of iterations may improve simulation fidelity, although it may affect performance.

Parameters:

counts – Number of iterations for the solver. Shape (M,).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Example:

>>> # set the position iteration count for all envs
>>> prims.set_solver_position_iteration_counts(np.full((num_envs,), 64))
>>>
>>> # set only the position iteration count for the first, middle and last of the 5 envs
>>> prims.set_solver_position_iteration_counts(np.full((3,), 64), indices=np.array([0, 2, 4]))

Set the solver (velocity) iteration count for the articulations.

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

Setting a higher number of iterations may improve simulation fidelity, although it may affect performance.

Parameters:

counts – Number of iterations for the solver. Shape (M,).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Example:

>>> # set the velocity iteration count for all envs
>>> prims.set_solver_velocity_iteration_counts(np.full((num_envs,), 64))
>>>
>>> # set only the velocity iteration count for the first, middle and last of the 5 envs
>>> prims.set_solver_velocity_iteration_counts(np.full((3,), 64), indices=np.array([0, 2, 4]))

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

Search for Stabilization Threshold in PhysX docs for more details.

Parameters:

thresholds – Stabilization thresholds to be applied. Shape (M,).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Example:

>>> # set the stabilization threshold for all envs
>>> prims.set_stabilization_thresholds(np.full((num_envs,), 0.005))
>>>
>>> # set only the stabilization threshold for the first, middle and last of the 5 envs
>>> prims.set_stabilization_thresholds(np.full((3,), 0.0051), indices=np.array([0, 2, 4]))

Set the linear and angular velocities of the prims in the view at once.

The method does this through the PhysX API only. It has to be called after initialization.

Warning

This method will immediately set the articulation state.

Parameters:

velocities – Linear and angular velocities respectively to set the rigid prims to. Shape is (M, 6).
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Hint

This method belongs to the methods used to set the articulation kinematic state:

set_velocities (set_linear_velocities, set_angular_velocities), set_joint_positions, set_joint_velocities, set_joint_efforts.

Set the visibilities of the prims in stage.

Parameters:

visibilities – Flag to set the visibilities of the USD prims in stage. Shape (M,). Where M <= size of the encapsulated prims in the view.
indices – Indices to specify which prims to manipulate. Shape (M,).

Raises:

Exception – If the prim view is not valid.

Example:

>>> # make all prims not visible in the stage
>>> prims.set_visibilities(visibilities=[False] * num_envs)

Set poses of prims in the view with respect to the world’s frame.

Warning

This method changes the prim poses immediately to the indicated values.

Parameters:

positions – Positions in the world frame of the prim. Shape is (M, 3). If not defined, positions are left unchanged.
orientations – Quaternion orientations in the world frame of the prims. Quaternion is scalar-first (w, x, y, z). Shape is (M, 4). If not defined, orientations are left unchanged.
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
usd – Whether to set the pose through USD when the physics view is unavailable.

Hint

This method belongs to the methods used to set the prim state.

Switch control mode between "position", "velocity", or "effort" for all joints.

This method will set the implicit Proportional-Derivative (PD) controller’s Kps (stiffnesses) and Kds (dampings), defined via the set_gains method, of the selected articulations and joints according to the following rule:

Control mode	Stiffnesses	Dampings
`"position"`	Kps	Kds
`"velocity"`	0	Kds
`"effort"`	0	0

Parameters:

mode – Control mode to switch the articulations specified to. It can be "position", "velocity", or "effort".
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (can’t be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

Raises:

Exception – If both joint_indices and joint_names are specified.

Example

>>> # set 'velocity' as control mode for all joints
>>> prims.switch_control_mode("velocity")
>>>
>>> # set 'effort' as control mode only for the fingers: panda_finger_joint1 (7) and panda_finger_joint2 (8)
>>> # for the first, middle and last of the 5 envs
>>> prims.switch_control_mode("effort", indices=np.array([0, 2, 4]), joint_indices=np.array([7, 8]))

switch_dof_control_mode( mode: str, dof_index: int, indices: ndarray | list | Tensor | array | None = None, ) → None#

Switch control mode between "position", "velocity", or "effort" for the specified DOF.

This method will set the implicit Proportional-Derivative (PD) controller’s Kps (stiffnesses) and Kds (dampings), defined via the set_gains method, of the selected DOF according to the following rule:

Control mode	Stiffnesses	Dampings
`"position"`	Kps	Kds
`"velocity"`	0	Kds
`"effort"`	0	0

Parameters:

mode – Control mode to switch the DOF specified to. It can be "position", "velocity" or "effort".
dof_index – DOF index to switch the control mode of.
indices – Indices to specify which prims to manipulate. Shape (M,). Where M <= size of the encapsulated prims in the view.

Example

>>> # set 'velocity' as control mode for the panda_joint1 (0) joint for all envs
>>> prims.switch_dof_control_mode("velocity", dof_index=0)
>>>
>>> # set 'effort' as control mode for the panda_joint1 (0) for the first, middle and last of the 5 envs
>>> prims.switch_dof_control_mode("effort", dof_index=0, indices=np.array([0, 2, 4]))

property body_names: list[str] | None#

List of prim names for each rigid body (link) of the articulations.

Returns:: Ordered names of bodies that correspond to links for the articulations in the view, or None if not initialized.

Example:

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

property count: int#

Number of prims encapsulated in this view.

Returns:: The number of prims encapsulated in this view.

Example:

>>> prims.count
5

property dof_names: list[str] | None#

List of prim names for each DOF of the articulations.

Returns:: Ordered names of joints that correspond to degrees of freedom for the articulations in the view, or None if not initialized.

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 initialized: bool#

Whether a physics simulation view is available for the prim view.

Returns:: True if a physics simulation view is available from SimulationManager. False otherwise.

Example:

>>> # given an active physics simulation view
>>> prims.initialized
True

property is_non_root_articulation_link: bool#

True if the prim corresponds to a non root link in an articulation.

Returns:: True if the prim corresponds to a non root link in an articulation. Otherwise False.

property joint_names: list[str] | None#

List of prim names for each joint of the articulations.

Returns:: Ordered names of joints that correspond to degrees of freedom for the articulations in the view, or None if not initialized.

property name: str#

Name given to the prims view when instantiating it.

Returns:: The name given to the prims view when instantiating it.

property num_bodies: int | None#

Number of rigid bodies (links) of the articulations.

Returns:: Maximum number of rigid bodies for the articulations in the view, or None if the articulation is not initialized.

Example:

>>> prims.num_bodies
12

property num_dof: int | None#

Number of DOF of the articulations.

Returns:: Maximum number of DOFs for the articulations in the view, or None if the articulation is not initialized.

Example:

>>> prims.num_dof
9

property num_fixed_tendons: int | None#

Number of fixed tendons of the articulations.

Returns:: Maximum number of fixed tendons for the articulations in the view, or None if the articulation is not initialized.

Example:

>>> prims.num_fixed_tendons
0

property num_joints: int | None#

Number of joints of the articulations.

Returns:: Number of joints of the articulations in the view, or None if the articulation is not initialized.

property num_shapes: int | None#

Number of rigid shapes of the articulations.

Returns:: Maximum number of rigid shapes for the articulations in the view, or None if the articulation is not initialized.

Example:

>>> prims.num_shapes
17

property prim_paths: list[str]#

Prim paths in the stage encapsulated in this view.

Returns:: The prim paths in the stage encapsulated in this view.

Example:

>>> prims.prim_paths
['/World/envs/env_0', '/World/envs/env_1', '/World/envs/env_2', '/World/envs/env_3',
 '/World/envs/env_4']

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

USD Prim objects encapsulated in this view.

Returns:: The USD Prim objects encapsulated in this view.

Example:

>>> prims.prims
[Usd.Prim(</World/envs/env_0>), Usd.Prim(</World/envs/env_1>), Usd.Prim(</World/envs/env_2>),
 Usd.Prim(</World/envs/env_3>), Usd.Prim(</World/envs/env_4>)]

Scenes#

class Scene#

Bases: object

Provides methods to add objects of interest in the stage, retrieve their information, and reset their default state in an easy way.

Example:

>>> from isaacsim.core.api.scenes import Scene
>>>
>>> scene = Scene()
>>> scene
<isaacsim.core.api.scenes.scene.Scene object at 0x...>

add( obj: SingleXFormPrim, ) → SingleXFormPrim#

Add an object to the scene registry.

Parameters:

obj – Object to be added.

Raises:

Exception – If an object with the same name already exists in the scene registry.
TypeError – If the object type is not supported.

Returns:

Object.

Example:

>>> from isaacsim.core.prims import XFormPrim
>>>
>>> prims = XFormPrim(prim_paths_expr="/World")
>>> scene.add(prims)
<isaacsim.core.prims.XFormPrim object at 0x...>

add_default_ground_plane( z_position: float = 0, name: str = 'default_ground_plane', prim_path: str = '/World/defaultGroundPlane', static_friction: float = 0.5, dynamic_friction: float = 0.5, restitution: float = 0.8, ) → GroundPlane#

Create a ground plane (using the default asset for Isaac Sim environments) and add it to the scene registry.

Parameters:

z_position – Ground plane position in the z-axis.
name – Shortname to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
prim_path – Prim path of the prim to create.
static_friction – Static friction coefficient.
dynamic_friction – Dynamic friction coefficient.
restitution – Restitution coefficient.

Returns:

Ground plane instance.

Example:

>>> scene.add_default_ground_plane()
server...
<isaacsim.core.api.objects.ground_plane.GroundPlane object at 0x...>

add_ground_plane( size: float | None = None, z_position: float = 0, name: str = 'ground_plane', prim_path: str = '/World/groundPlane', static_friction: float = 0.5, dynamic_friction: float = 0.5, restitution: float = 0.8, color: ndarray | None = None, ) → GroundPlane#

Create a ground plane and add it to the scene registry.

Parameters:

size – Length of each edge.
z_position – Ground plane position in the z-axis.
name – Shortname to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
prim_path – Prim path of the prim to create.
static_friction – Static friction coefficient.
dynamic_friction – Dynamic friction coefficient.
restitution – Restitution coefficient.
color – Color of the visual plane. None means 50% gray.

Returns:

Ground plane instance.

Example:

>>> scene.add_ground_plane()
<isaacsim.core.api.objects.ground_plane.GroundPlane object at 0x...>

clear(registry_only: bool = False) → None#

Clear all objects added to the scene registry from the stage.

Parameters:: registry_only – True to remove objects from the scene registry only and not the USD.

Example:

>>> scene.clear()

compute_object_AABB( name: str, ) → tuple[ndarray, ndarray]#

Compute the bounding box points (minimum and maximum) of a registered object given its name.

Warning

The bounding box computations should be enabled, via the enable_bounding_boxes_computations method, before querying the Axis-Aligned Bounding Box (AABB) of an object.

Parameters:

name – Object name.

Raises:

Exception – If the bounding box computation is not enabled.
ValueError – If the registered object is a view class.

Returns:

Bounding box points with the minimum point and maximum point.

Example:

>>> scene.enable_bounding_boxes_computations()
>>>
>>> bbox = scene.compute_object_AABB("ground_plane")
>>> bbox[0]  # minimum
array([-50., -50.,  0.])
>>> bbox[1]  # maximum
array([50., 50.,  0.])

disable_bounding_boxes_computations() → None#

Disable bounding box computations for registered objects.

Example:

>>> scene.disable_bounding_boxes_computations()

enable_bounding_boxes_computations() → None#

Enable bounding box computations for registered objects.

Example:

>>> scene.enable_bounding_boxes_computations()

get_object( name: str, ) → SingleXFormPrim#

Get a registered object by its name if it exists, otherwise None.

Note

Object can be registered via the add method

Parameters:: name – Object name.
Returns:: Object if it exists, otherwise None.

Example:

>>> # given a default ground plane named 'default_ground_plane'
>>> scene.get_object("default_ground_plane")
<isaacsim.core.api.objects.ground_plane.GroundPlane object at 0x...>

object_exists(name: str) → bool#

Check if an object exists in the scene registry.

Parameters:: name – Object name.
Returns:: Whether the object exists in the scene registry.

Example:

>>> # given a default ground plane named 'default_ground_plane'
>>> scene.object_exists("default_ground_plane")
True

post_reset() → None#

Call the post_reset method on all added objects to the scene registry.

Example:

>>> scene.post_reset()

remove_object(name: str, registry_only: bool = False) → None#

Remove an object from the scene registry and the USD stage if specified.

Parameters:

name – Name of the prim to be removed.
registry_only – True to remove the object from the scene registry only and not the USD.

Example:

>>> # given a default ground plane named 'default_ground_plane'
>>> scene.remove_object("default_ground_plane")

property stage: pxr.Usd.Stage#

Current USD stage.

Returns:: Current USD stage.

Example:

>>> scene.stage
Usd.Stage.Open(rootLayer=Sdf.Find('anon:0x...usd'),
               sessionLayer=Sdf.Find('anon:0x...usda'),
               pathResolverContext=<invalid repr>)

class SceneRegistry#

Bases: object

Class to keep track of the different types of objects added to the scene.

Example:

>>> from isaacsim.core.api.scenes import SceneRegistry
>>>
>>> scene_registry = SceneRegistry()
>>> scene_registry
<isaacsim.core.api.scenes.scene_registry.SceneRegistry object at 0x...>

add_articulated_system( name: str, articulated_system: SingleArticulation, ) → None#

Register a SingleArticulation (or subclass) object.

Parameters:

name – Object name.
articulated_system – Object.

Raises:

ValueError – If the object name is not unique.

add_articulated_view( name: str, articulated_view: Articulation, ) → None#

Register a Articulation (or subclass) object.

Parameters:

name – Object name.
articulated_view – Object.

Raises:

ValueError – If the object name is not unique.

add_cloth( name: str, cloth: SingleClothPrim, ) → None#

Register a SingleClothPrim (or subclass) object.

Parameters:

name – Object name.
cloth – Object.

Raises:

ValueError – If the object name is not unique.

add_cloth_view( name: str, cloth_prim_view: ClothPrim, ) → None#

Register a ClothPrim (or subclass) object.

Parameters:

name – Object name.
cloth_prim_view – Object.

Raises:

ValueError – If the object name is not unique.

add_deformable( name: str, deformable: SingleDeformablePrim, ) → None#

Register a SingleDeformablePrim (or subclass) object.

Parameters:

name – Object name.
deformable – Object.

Raises:

ValueError – If the object name is not unique.

add_deformable_material( name: str, deformable_material: DeformableMaterial, ) → None#

Register a DeformableMaterial (or subclass) object.

Parameters:

name – Object name.
deformable_material – Object.

Raises:

ValueError – If the object name is not unique.

add_deformable_material_view( name: str, deformable_material_view: DeformableMaterialView, ) → None#

Register a DeformableMaterialView (or subclass) object.

Parameters:

name – Object name.
deformable_material_view – Object.

Raises:

ValueError – If the object name is not unique.

add_deformable_view( name: str, deformable_prim_view: DeformablePrim, ) → None#

Register a DeformablePrim (or subclass) object.

Parameters:

name – Object name.
deformable_prim_view – Object.

Raises:

ValueError – If the object name is not unique.

add_geometry_object( name: str, geometry_object: SingleGeometryPrim, ) → None#

Register a SingleGeometryPrim (or subclass) object.

Parameters:

name – Object name.
geometry_object – Object.

Raises:

ValueError – If the object name is not unique.

add_geometry_prim_view( name: str, geometry_prim_view: GeometryPrim, ) → None#

Register a GeometryPrim (or subclass) object.

Parameters:

name – Object name.
geometry_prim_view – Object.

Raises:

ValueError – If the object name is not unique.

add_particle_material( name: str, particle_material: ParticleMaterial, ) → None#

Register a ParticleMaterial or subclass object.

Parameters:

name – Object name.
particle_material – Object to register.

Raises:

ValueError – If the object name is not unique.

add_particle_material_view( name: str, particle_material_view: ParticleMaterialView, ) → None#

Register a ParticleMaterialView or subclass object.

Parameters:

name – Object name.
particle_material_view – Object to register.

Raises:

ValueError – If the object name is not unique.

add_particle_system( name: str, particle_system: SingleParticleSystem, ) → None#

Register a SingleParticleSystem (or subclass) object.

Parameters:

name – Object name.
particle_system – Object.

Raises:

ValueError – If the object name is not unique.

add_particle_system_view( name: str, particle_system_view: ParticleSystem, ) → None#

Register a ParticleSystem (or subclass) object.

Parameters:

name – Object name.
particle_system_view – Object.

Raises:

ValueError – If the object name is not unique.

add_rigid_contact_view( name: str, rigid_contact_view: RigidContactView, ) → None#

Register a RigidContactView (or subclass) object.

Parameters:

name – Object name.
rigid_contact_view – Object.

Raises:

ValueError – If the object name is not unique.

add_rigid_object( name: str, rigid_object: SingleRigidPrim, ) → None#

Register a SingleRigidPrim (or subclass) object.

Parameters:

name – Object name.
rigid_object – Object.

Raises:

ValueError – If the object name is not unique.

add_rigid_prim_view( name: str, rigid_prim_view: RigidPrim, ) → None#

Register a RigidPrim (or subclass) object.

Parameters:

name – Object name.
rigid_prim_view – Object.

Raises:

ValueError – If the object name is not unique.

add_robot( name: str, robot: Robot, ) → None#

Register a Robot (or subclass) object.

Parameters:

name – Object name.
robot – Object.

Raises:

ValueError – If the object name is not unique.

add_robot_view( name: str, robot_view: RobotView, ) → None#

Register a RobotView (or subclass) object.

Parameters:

name – Object name.
robot_view – Object.

Raises:

ValueError – If the object name is not unique.

add_sensor( name: str, sensor: BaseSensor, ) → None#

Register a BaseSensor or subclass object.

Parameters:

name – Object name.
sensor – Object to register.

Raises:

ValueError – If the object name is not unique.

add_xform( name: str, xform: SingleXFormPrim, ) → None#

Register a SingleXFormPrim or subclass object.

Parameters:

name – Object name.
xform – Object to register.

Raises:

ValueError – If the object name is not unique.

add_xform_view( name: str, xform_prim_view: XFormPrim, ) → None#

Register an XFormPrim (or subclass) object.

Parameters:

name – Object name.
xform_prim_view – Object.

Raises:

ValueError – If the object name is not unique.

get_object( name: str, ) → SingleXFormPrim#

Get a registered object by its name if it exists, otherwise None.

Parameters:: name – Object name.
Returns:: The object if it exists, otherwise None.

Example:

>>> # given a registered ground plane named 'default_ground_plane'
>>> scene_registry.get_object("default_ground_plane")
<isaacsim.core.api.objects.ground_plane.GroundPlane object at 0x...>

name_exists(name: str) → bool#

Check if an object exists in the registry by its name.

Parameters:: name – Object name.
Returns:: Whether the object is registered.

Example:

>>> # given a registered ground plane named 'default_ground_plane'
>>> scene_registry.name_exists("default_ground_plane")
True

remove_object(name: str) → None#

Remove an object from the registry.

Note

This method will only remove the object from the internal registry. The wrapped object will not be removed from the USD stage.

Parameters:: name – Object name.
Raises:: Exception – If the name does not exist in the registry.

Example:

>>> # given a registered ground plane named 'default_ground_plane'
>>> scene_registry.remove_object("default_ground_plane")

property articulated_systems: dict#

Registered SingleArticulation objects.

Returns:: Dictionary containing the registered articulated systems.

property articulated_views: dict#

Registered Articulation objects.

Returns:: Dictionary containing the registered articulated views.

property cloth_prim_views: dict#

Registered ClothPrim objects.

Returns:: Dictionary of registered ClothPrim objects.

property cloth_prims: dict#

Registered SingleClothPrim objects.

Returns:: Dictionary of registered SingleClothPrim objects.

property deformable_material_views: dict#

Registered DeformableMaterialView objects.

Returns:: Dictionary of registered DeformableMaterialView objects.

property deformable_materials: dict#

Registered DeformableMaterial objects.

Returns:: Dictionary of registered DeformableMaterial objects.

property deformable_prim_views: dict#

Registered DeformablePrim objects.

Returns:: Dictionary of registered DeformablePrim objects.

property deformable_prims: dict#

Registered SingleDeformablePrim objects.

Returns:: Dictionary of registered SingleDeformablePrim objects.

property geometry_prim_views: dict#

Registered GeometryPrim objects.

Returns:: Dictionary containing the registered geometry prim views.

property particle_material_views: dict#

Registered ParticleMaterialView objects.

Returns:: Dictionary mapping names to registered particle material view objects.

property particle_materials: dict#

Registered ParticleMaterial objects.

Returns:: Dictionary of registered ParticleMaterial objects.

property particle_system_views: dict#

Registered ParticleSystem objects.

Returns:: Dictionary of registered ParticleSystem objects.

property particle_systems: dict#

Registered SingleParticleSystem objects.

Returns:: Dictionary of registered SingleParticleSystem objects.

property rigid_contact_views: dict#

Registered RigidContactView objects.

Returns:: Dictionary containing the registered rigid contact views.

property rigid_objects: dict#

Registered SingleRigidPrim objects.

Returns:: Dictionary containing the registered rigid objects.

property rigid_prim_views: dict#

Registered RigidPrim objects.

Returns:: Dictionary containing the registered rigid prim views.

property robot_views: dict#

Registered RobotView objects.

Returns:: Dictionary containing the registered robot views.

property robots: dict#

Registered Robot objects.

Returns:: Dictionary containing the registered robots.

property sensors: dict#

Registered BaseSensor (and derived) objects.

Returns:: Dictionary containing the registered sensors.

property xform_prim_views: dict#

Registered XFormPrim objects.

Returns:: Dictionary of registered XFormPrim objects.

property xforms: dict#

Registered SingleXFormPrim objects.

Returns:: Dictionary containing the registered xforms.

Sensors#

class BaseSensor( prim_path: str, name: str = 'base_sensor', position: Sequence[float] | None = None, translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, scale: Sequence[float] | None = None, visible: bool | None = None, )#

Bases: SingleXFormPrim

Provides common properties and methods to deal with prims as a sensor.

Note

This class, which inherits from SingleXFormPrim, does not currently add any new properties or methods to it. Its definition is intended for future implementations.

Parameters:

prim_path – Prim path of the prim to encapsulate or create.
name – Short name to be used as a key by Scene class. Note: must be unique if the object is added to the Scene.
position – Position in the world frame of the prim. Shape is (3, ).
translation – Translation in the local frame of the prim (with respect to its parent prim). Shape is (3, ).
orientation – Quaternion orientation in the world or local frame of the prim (depends on whether translation or position is specified). Quaternion is scalar-first (w, x, y, z). Shape is (4, ).
scale – Local scale to be applied to the prim’s dimensions. Shape is (3, ).
visible – Set to False for an invisible prim in the stage while rendering.

Raises:

Exception – If translation and position are defined at the same time.

apply_visual_material( visual_material: VisualMaterial, weaker_than_descendants: bool = False, ) → None#

Apply visual material to the held prim and optionally its descendants.

Parameters:

visual_material – Visual material to be applied to the held prim. Currently supports PreviewSurface, OmniPBR and OmniGlass.
weaker_than_descendants – True if the material shouldn’t override the descendants materials, otherwise False.

Example:

>>> from isaacsim.core.api.materials import OmniGlass
>>>
>>> # create a dark-red glass visual material
>>> material = OmniGlass(
...     prim_path="/World/material/glass",  # path to the material prim to create
...     ior=1.25,
...     depth=0.001,
...     thin_walled=False,
...     color=np.array([0.5, 0.0, 0.0])
... )
>>> prim.apply_visual_material(material)

get_applied_visual_material() → VisualMaterial#

Return the current applied visual material if it was applied using apply_visual_material or is one of the following materials that was already applied before: PreviewSurface, OmniPBR and OmniGlass.

Returns:: The current applied visual material if its type is currently supported.

Example:

>>> # given a visual material applied
>>> prim.get_applied_visual_material()
<isaacsim.core.api.materials.omni_glass.OmniGlass object at 0x7f36263106a0>

get_default_state() → XFormPrimState#

Get the default prim states (spatial position and orientation).

Returns:: An object that contains the default state of the prim (position and orientation).

Example:

>>> state = prim.get_default_state()
>>> state
<isaacsim.core.utils.types.XFormPrimState object at 0x7f33addda650>
>>>
>>> state.position
[-4.5299529e-08 -1.8347054e-09 -2.8610229e-08]
>>> state.orientation
[1. 0. 0. 0.]

get_local_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the local frame (the prim’s parent frame).

Returns:: First index is the position in the local frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the local frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_local_pose()
>>> position
[0. 0. 0.]
>>> orientation
[0. 0. 0.]

get_local_scale() → ndarray#

Get prim’s scale with respect to the local frame (the parent’s frame).

Returns:: Scale applied to the prim’s dimensions in the local frame. shape is (3, ).

Example:

>>> prim.get_local_scale()
[1. 1. 1.]

get_visibility() → bool#

Get the visibility of the prim in stage.

Returns:: True if the prim is visible in stage. False otherwise.

Example:

>>> # get the visible state of a visible prim on the stage
>>> prim.get_visibility()
True

get_world_pose() → tuple[ndarray, ndarray]#

Get prim’s pose with respect to the world’s frame.

Returns:: First index is the position in the world frame (with shape (3, )). Second index is quaternion orientation (with shape (4, )) in the world frame.

Example:

>>> # if the prim is in position (1.0, 0.5, 0.0) with respect to the world frame
>>> position, orientation = prim.get_world_pose()
>>> position
[1.  0.5 0. ]
>>> orientation
[1. 0. 0. 0.]

get_world_scale() → ndarray#

Get prim’s scale with respect to the world’s frame.

Returns:: Scale applied to the prim’s dimensions in the world frame. shape is (3, ).

Example:

>>> prim.get_world_scale()
[1. 1. 1.]

initialize(physics_sim_view: object = None) → None#

Creates a physics simulation view if one is not passed when using the PhysX tensor API.

Note

If the prim has been added to the world scene (e.g., world.scene.add(prim)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Parameters:: physics_sim_view – Current physics simulation view.

Example:

>>> prim.initialize()

is_valid() → bool#

Check if the prim path has a valid USD Prim at it.

Returns:: True if the current prim path corresponds to a valid prim in stage. False otherwise.

Example:

>>> # given an existing and valid prim
>>> prims.is_valid()
True

is_visual_material_applied() → bool#

Check if there is a visual material applied.

Returns:: True if there is a visual material applied. False otherwise.

Example:

>>> # given a visual material applied
>>> prim.is_visual_material_applied()
True

post_reset() → None#: Resets the sensor to its initial state after a simulation reset.

set_default_state( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set the default state of the prim (position and orientation), that will be used after each reset.

Parameters:

position – Position in the world frame of the prim. shape is (3, ). If None, the position is left unchanged.
orientation – Quaternion orientation in the world frame of the prim. Quaternion is scalar-first (w, x, y, z). shape is (4, ). If None, the orientation is left unchanged.

Example:

>>> # configure default state
>>> prim.set_default_state(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1, 0, 0, 0]))
>>>
>>> # set default states during post-reset
>>> prim.post_reset()

set_local_pose( translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the local frame (the prim’s parent frame).

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

translation – Translation in the local frame of the prim (with respect to its parent prim). shape is (3, ).
orientation – Quaternion orientation in the local frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_local_pose(translation=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

set_local_scale( scale: Sequence[float] | None, ) → None#

Set prim’s scale with respect to the local frame (the prim’s parent frame).

Parameters:: scale – Scale to be applied to the prim’s dimensions. shape is (3, ).

Example:

>>> # scale prim 10 times smaller
>>> prim.set_local_scale(np.array([0.1, 0.1, 0.1]))

set_visibility(visible: bool) → None#

Set the visibility of the prim in stage.

Parameters:: visible – Flag to set the visibility of the USD prim in stage.

Example:

>>> # make prim not visible in the stage
>>> prim.set_visibility(visible=False)

set_world_pose( position: Sequence[float] | None = None, orientation: Sequence[float] | None = None, ) → None#

Set prim’s pose with respect to the world’s frame.

Warning

This method will change (teleport) the prim pose immediately to the indicated value

Parameters:

position – Position in the world frame of the prim. shape is (3, ).
orientation – Quaternion orientation in the world frame of the prim. quaternion is scalar-first (w, x, y, z). shape is (4, ).

Hint

This method belongs to the methods used to set the prim state

Example:

>>> prim.set_world_pose(position=np.array([1.0, 0.5, 0.0]), orientation=np.array([1., 0., 0., 0.]))

property name: str | None#

Name given to the prim when instantiating it.

Returns:: Name given to the prim when instantiating it. Otherwise None.

property non_root_articulation_link: bool#

Whether the prim is a non-root articulation link.

Returns:: True if the prim itself is a non-root link.

Example:

>>> # for a wrapped articulation (where the root prim has the Physics Articulation Root property applied)
>>> prim.non_root_articulation_link
False

property prim: pxr.Usd.Prim#

USD Prim object that this object holds.

Returns:: USD Prim object that this object holds.

property prim_path: str#

Prim path in the stage.

Returns:: Prim path in the stage.

class RigidContactView( prim_paths_expr: str | list[str], filter_paths_expr: list[str] | list[list[str]], name: str = 'rigid_contact_view', prepare_contact_sensors: bool = True, disable_stablization: bool = True, disable_stabilization: bool | None = None, max_contact_count: int = 0, )#

Bases: object

Provides high-level functions to deal with rigid prims (one or many) that track their contacts through filters, as well as their attributes/properties.

This class wraps all matching rigid prims found by the regex provided in the prim_paths_expr argument.

Warning

The rigid prim view object must be initialized in order to be able to operate on it. See the initialize method for more details.

Parameters:

prim_paths_expr – Prim paths regex to encapsulate all prims that match it. Example: “/World/Env[1-5]/Cube” will match /World/Env1/Cube, /World/Env2/Cube, etc. A non-regex prim path can also be used to encapsulate one rigid prim. Additionally, a list of regexes can be provided. Example: [“/World/Env[1-5]/Cube”, “/World/Env[10-19]/Cube”].
filter_paths_expr – List of prim paths regex to filter the contacts for each corresponding prim_paths_expr. Example: [“/World/envs/env_2/Xform”] will filter the contacts corresponding to the expression passed.
name – Short name to be used as a key by Scene class. Note: needs to be unique if the object is added to the Scene.
prepare_contact_sensors – If rigid prims in the view are not cloned from a prim in a prepared state, this ensures that appropriate physics settings are applied to all prims in the view. This can be slow for large numbers of prims.
disable_stablization – Disables the contact stabilization parameter in the physics context.
disable_stabilization – Overrides disable_stablization when provided; disables contact stabilization in the physics context.
max_contact_count – Maximum number of contact data to report when detailed contact information is needed.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>> from isaacsim.core.cloner import GridCloner
>>> from isaacsim.core.api.sensors import RigidContactView
>>> from pxr import UsdGeom
>>>
>>> env_zero_path = "/World/envs/env_0"
>>> num_envs = 5
>>>
>>> # clone the environment (num_envs)
>>> cloner = GridCloner(spacing=0)
>>> cloner.define_base_env(env_zero_path)
>>> UsdGeom.Xform.Define(stage_utils.get_current_stage(), env_zero_path)
>>> stage_utils.get_current_stage().DefinePrim(f"{env_zero_path}/Xform", "Xform")
>>> stage_utils.get_current_stage().DefinePrim(f"{env_zero_path}/Xform/Cube", "Cube")
>>> # position the cubes on top of each other
>>> position_offsets = np.zeros((num_envs, 3))
>>> position_offsets[:, 2] = np.arange(num_envs) * 1.1
>>> env_pos = cloner.clone(
...     source_prim_path=env_zero_path,
...     prim_paths=cloner.generate_paths("/World/envs/env", num_envs),
...     position_offsets=position_offsets,
...     copy_from_source=True,
... )
>>>
>>> # wrap the prims
>>> prims = RigidContactView(
...     prim_paths_expr="/World/envs/env.*/Xform",
...     name="RigidContactView_view",
...     filter_paths_expr=["/World/envs/env_2/Xform"],
...     max_contact_count=10,
... )
>>> prims
<isaacsim.core.api.sensors.rigid_contact_view.RigidContactView object at 0x7f8d4eb1abf0>

Gets detailed contact information between the prims in the view and the filter prims.

Specifically, this method provides individual contact normals, contact points, contact separations, and contact forces for each pair. The sum of the contact forces equals the force aggregate that get_contact_force_matrix provides for a pair.

Given the dynamic nature of collision between bodies, this method provides buffers of contact data that are arranged sequentially for each pair. The starting index and the number of contact data points for each pair in this stream can be realized from pair_contacts_start_indices, and pair_contacts_count tensors. They both have a dimension of (num_shapes, num_filters) where num_filters is determined according to the filter_paths_expr parameter.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Whether to return a clone of the internal buffer.
dt – Time step multiplier to convert the underlying impulses to forces. Use 1.0 to return contact impulses.

Returns:

A set of buffers for normal forces with shape (max_contact_count, 1), points with shape (max_contact_count, 3), normals with shape (max_contact_count, 3), and distances with shape (max_contact_count, 1), as well as two tensors with shape (M, self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

Example:

>>> # get detailed contact force data between the prims and the filter prims (the cube in the middle)
>>> data = prims.get_contact_force_data()
>>> data[0]  # normal forces
[[-168.53815]
 [ -89.57392]
 [-156.10307]
 [ -75.17234]
 [  98.0681 ]
 [  52.56319]
 [ 108.26558]
 [  67.62025]
 [   0.     ]
 [   0.     ]]
>>> data[1]  # points
[[ 0.4948182  -0.49902824  1.5001888 ]
 [ 0.4950411   0.49933064  1.5001996 ]
 [-0.5024581   0.49930018  1.5001924 ]
 [-0.5024276  -0.49880558  1.5001817 ]
 [-0.5023767   0.497138    2.5001519 ]
 [-0.502735   -0.49877006  2.5001822 ]
 [ 0.4947694  -0.4989927   2.500226  ]
 [ 0.4949917   0.49677914  2.5001955 ]
 [ 0.          0.          0.        ]
 [ 0.          0.          0.        ]]
>>> data[2]  # normals
[[-4.3812128e-05  3.0501858e-05  1.0000000e+00]
 [-4.3812128e-05  3.0501858e-05  1.0000000e+00]
 [-4.3812128e-05  3.0501858e-05  1.0000000e+00]
 [-4.3812128e-05  3.0501858e-05  1.0000000e+00]
 [ 2.1408198e-06 -7.0731985e-05  1.0000000e+00]
 [ 2.1408198e-06 -7.0731985e-05  1.0000000e+00]
 [ 2.1408198e-06 -7.0731985e-05  1.0000000e+00]
 [ 2.1408198e-06 -7.0731985e-05  1.0000000e+00]
 [ 0.0000000e+00  0.0000000e+00  0.0000000e+00]
 [ 0.0000000e+00  0.0000000e+00  0.0000000e+00]]
>>> data[3]  # distances
[[ 3.7143487e-05]
 [-4.0254322e-06]
 [-4.0531158e-05]
 [ 6.0737699e-07]
 [ 1.9307560e-04]
 [ 9.2272363e-05]
 [ 4.6372414e-05]
 [ 1.4718286e-04]
 [ 0.0000000e+00]
 [ 0.0000000e+00]]
>>> data[4]  # pair contacts count
[[0]
 [4]
 [0]
 [4]
 [0]]
>>> data[5]  # start indices of pair contacts
[[0]
 [0]
 [4]
 [4]
 [8]]

Gets the contact forces between the prims in the view and the filter prims.

E.g., a matrix of dimension (num_shapes, num_filters, 3) where num_filters is: determined according to the filter_paths_expr parameter.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Whether to return a clone of the internal buffer.
dt – Time step multiplier to convert the underlying impulses to forces. Use 1.0 to return contact impulses.

Returns:

Net contact forces between the view prims and the filter prims with shape (M, self.num_filters, 3).

Example:

>>> # get the contact forces between the prims and the filter prims (the cube in the middle)
>>> prims.get_contact_force_matrix()
[[[ 0.0000000e+00  0.0000000e+00  0.0000000e+00]]
 [[ 2.2649009e-02 -1.3710857e-02 -4.9047806e+02]]
 [[ 0.0000000e+00  0.0000000e+00  0.0000000e+00]]
 [[-3.3276828e-03 -2.3870371e-02  3.2733777e+02]]
 [[ 0.0000000e+00  0.0000000e+00  0.0000000e+00]]]

Gets friction data between the prims in the view and the filter prims.

Specifically, this method provides frictional contact forces and points. The data is reported for the number of anchor points that includes tangential forces in a single tangent direction to contact normal. Given the dynamic nature of collision between bodies, this method provides buffers of friction data arranged sequentially for each pair. The starting index and the number of contact data points for each pair in this stream can be realized from pair_contacts_start_indices, and pair_contacts_count tensors. They both have a dimension of (self.num_shapes, self.num_filters) where filter_count is determined according to the filter_paths_expr parameter.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Whether to return a clone of the internal buffer.
dt – Time step multiplier to convert the underlying impulses to forces. Use 1.0 to return contact impulses.

Returns:

A set of buffers for tangential forces per patch at the number of anchor points, each in a single direction, with shape (max_contact_count, 3), points with shape (max_contact_count, 3), as well as two tensors with shape (M, self.num_filters) to indicate the starting index and the number of contact data points per pair in the aforementioned buffers.

Gets the overall net contact forces on the prims in the view with respect to the world’s frame.

Parameters:

indices – Indices to specify which prims to query. Shape (M,). Where M <= size of the encapsulated prims in the view.
clone – Whether to return a clone of the internal buffer.
dt – Time step multiplier to convert the underlying impulses to forces. Use 1.0 to return contact impulses.

Returns:

Net contact forces of the prims with shape (M, 3).

Example:

>>> # get the net contact force on all rigid bodies. Returned shape is (5, 3).
>>> prims.get_net_contact_forces()
[[ 1.8731881e-03  5.4876995e-03  1.6408131e+02]
 [ 1.9060407e-02 -2.2513291e-02  1.6358723e+02]
 [-2.1011427e-02  3.5647806e-02  1.6371542e+02]
 [ 9.4006478e-05 -9.3258200e-03  1.6348369e+02]
 [ 9.3709816e-05 -9.2963902e-03  1.6296776e+02]]
>>>
>>> # get the net contact force on the rigid bodies for the first, middle and last of the 5 envs
>>> prims.get_net_contact_forces(indices=np.array([0, 2, 4]))
[[ 1.8731881e-03  5.4876995e-03  1.6408131e+02]
 [-2.1011427e-02  3.5647806e-02  1.6371542e+02]
 [ 9.3709816e-05 -9.2963902e-03  1.6296776e+02]]

initialize( physics_sim_view: omni.physics.tensors.SimulationView = None, ) → None#

Creates the rigid contact view and initializes contact shape and filter counts using the PhysX tensor API.

Note

If the rigid prim view has been added to the world scene (e.g., world.scene.add(prims)), it will be automatically initialized when the world is reset (e.g., world.reset()).

Warning

This method needs to be called after each hard reset (e.g., Stop + Play on the timeline) before interacting with any other class method.

Parameters:: physics_sim_view – Physics simulation view used to create the rigid contact view.

Example:

>>> prims.initialize()

is_physics_handle_valid() → bool#

Checks if the rigid prim view’s physics handle is initialized.

Warning

If the physics handle is not valid, many of the methods that require PhysX will return None.

Returns:: True if the physics handle of the view is valid, otherwise False.

Example:

>>> prims.is_physics_handle_valid()
True

property num_filters: int#

Number of filter bodies that report their contact with the rigid prims.

Returns:: Number of filter bodies that report their contact with the rigid prims.

Example:

>>> prims.num_filters
1

property num_shapes: int#

Number of rigid shapes for the prims in the view.

Returns:: Number of rigid shapes for the prims in the view.

Example:

>>> prims.num_shapes
5

Simulation Context#

class SimulationContext(*args: object, **kwargs: object)#

Bases: object

Provides functions for managing time-related events and simulation control.

Handles physics and render stepping, callback function management for physics steps, timeline events (pause or play), stage operations (open/close), and other simulation events.

Includes a PhysicsContext instance for physics-related settings such as physics dt and solver type.

Parameters:

physics_dt – dt between physics steps.
rendering_dt – dt between rendering steps. Note: rendering means rendering a frame of the current application and not only rendering a frame to the viewports/cameras. UI elements of Isaac Sim will be refreshed with this dt as well if running non-headless.
stage_units_in_meters – The metric units of assets. This affects the gravity value, etc.
physics_prim_path – Specifies the prim path to create a PhysicsScene at, only when no PhysicsScene is already defined.
sim_params – Additional simulation parameters to configure physics.
set_defaults – Set to True to use the default settings [physics_dt = 1.0 / 60.0, stage units in meters = 1.0 (i.e. in meters), rendering_dt = 1.0 / 60.0, gravity = -9.81 m / s, ccd_enabled, stabilization_enabled, GPU dynamics turned off, broadphase type is MBP, solver type is TGS].
backend – Specifies the backend to be used (numpy, torch, or warp).
device – Specifies the device to be used if running on the GPU with the torch or warp backend.
stage – Specifies the USD stage to be used.

Example:

>>> from isaacsim.core.api import SimulationContext
>>>
>>> simulation_context = SimulationContext()
>>> simulation_context
<isaacsim.core.api.simulation_context.simulation_context.SimulationContext object at 0x...>

Make SimulationContext a singleton.

Parameters:

*args – Additional positional arguments accepted by the constructor.
**kwargs – Additional keyword arguments accepted by the constructor.

Returns:

The SimulationContext singleton instance.

add_physics_callback( callback_name: str, callback_fn: Callable[[float], None], ) → None#

Add a callback which will be called before each physics step.

callback_fn should take a float argument (e.g., step_size).

Parameters:

callback_name – Unique name for the callback.
callback_fn – Function to call before each physics step, receives step size as argument.

Example:

>>> def callback_physics(step_size):
...     print("physics callback -> step_size:", step_size)
...
>>> simulation_context.add_physics_callback("callback_physics", callback_physics)

add_render_callback( callback_name: str, callback_fn: Callable, ) → None#

Add a callback which will be called after each rendering event such as .render().

callback_fn should take an event argument (e.g., event).

Parameters:

callback_name – Unique name for the callback.
callback_fn – Function to call after each render, receives event as argument.

Example:

>>> def callback_render(event):
...     print("render callback -> event:", event)
...
>>> simulation_context.add_render_callback("callback_render", callback_render)

add_stage_callback( callback_name: str, callback_fn: Callable, ) → None#

Add a callback which will be called after each stage event such as open/close among others.

callback_fn should take an argument of type omni.usd.StageEvent (e.g., event).

Parameters:

callback_name – Unique name for the callback.
callback_fn – Function to call on stage events, receives stage event as argument.

Example:

>>> def callback_stage(event):
...     print("stage callback -> event:", event)
...
>>> simulation_context.add_stage_callback("callback_stage", callback_stage)

add_timeline_callback( callback_name: str, callback_fn: Callable, ) → None#

Add a callback which will be called after each timeline event such as play/pause.

callback_fn should take an argument of type omni.timeline.TimelineEvent (e.g., event).

Parameters:

callback_name – Unique name for the callback.
callback_fn – Function to call on timeline events, receives timeline event as argument.

Example:

>>> def callback_timeline(event):
...     print("timeline callback -> event:", event)
...
>>> simulation_context.add_timeline_callback("callback_timeline", callback_timeline)

clear() → None#

Clear the current stage leaving the PhysicsScene and /World.

Example:

>>> simulation_context.clear()

clear_all_callbacks() → None#

Clear all callbacks which were added using any add_*_callback method.

Example:

>>> simulation_context.clear_all_callbacks()

classmethod clear_instance() → None#

Delete the simulation context object, if it was instantiated before, and destroy any subscribed callback.

Example:

>>> SimulationContext.clear_instance()

clear_physics_callbacks() → None#

Remove all registered physics callbacks.

Example:

>>> simulation_context.clear_physics_callbacks()

clear_render_callbacks() → None#

Remove all registered render callbacks.

Example:

>>> simulation_context.clear_render_callbacks()

clear_stage_callbacks() → None#

Remove all registered stage callbacks.

Example:

>>> simulation_context.clear_stage_callbacks()

clear_timeline_callbacks() → None#

Remove all registered timeline callbacks.

Example:

>>> simulation_context.clear_timeline_callbacks()

get_block_on_render() → bool#

Get the block on render flag for the simulation thread.

Returns:: True if blocking the step call guarantees a one frame lag between any data captured from render products and the current USD stage.

Example:

>>> simulation_context.get_block_on_render()
False

get_physics_context() → PhysicsContext#

Get the physics context instance, a class to deal with a physics scene and its settings.

Raises:

Exception – If there is no stage currently opened.
RuntimeError – If the physics context is not initialized.

Returns:

Physics context object.

Example:

>>> simulation_context.get_physics_context()
<isaacsim.core.api.physics_context.physics_context.PhysicsContext object at 0x...>

get_physics_dt() → float#

Get the current physics dt of the physics context.

Raises:: Exception – If there is no stage currently opened.
Returns:: Current physics dt of the PhysicsContext.

Example:

>>> simulation_context.get_physics_dt()
0.016666666666666666

get_rendering_dt() → float#

Get the current rendering dt.

Raises:: Exception – If there is no stage currently opened.
Returns:: Current rendering dt.

Example:

>>> simulation_context.get_rendering_dt()
0.016666666666666666

initialize_physics() → None#

Initialize the physics simulation view.

Example:

>>> simulation_context.initialize_physics()

async initialize_simulation_context_async() → None#

Initialize the simulation context.

Hint

This method is intended to be used in the Isaac Sim’s Extensions workflow where the Kit application has the control over timing of physics and rendering steps

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.initialize_simulation_context_async()
...
>>> run_coroutine(task())

classmethod instance() → SimulationContext#

Get the instance of the class, if it was instantiated before.

Returns:: The SimulationContext instance, or None if it has not been instantiated.

Example:

>>> # given that the class has already been instantiated before
>>> simulation_context = SimulationContext.instance()
>>> simulation_context
<isaacsim.core.api.simulation_context.simulation_context.SimulationContext object at 0x...>

is_playing() → bool#

Check whether the simulation is playing.

Returns:: True if the simulator is playing.

Example:

>>> # given a simulation in play
>>> simulation_context.is_playing()
True

is_simulating() → bool#

Check whether the simulation is running.

Warning

With deprecation of Dynamic Control Toolbox, this function is not needed

It can return True if start_simulation is called even if play was pressed/called.

Returns:: True if physics simulation is happening.

Example:

>>> # given a running simulation
>>> simulation_context.is_simulating()
True

is_stopped() → bool#

Check whether the simulation is stopped.

Returns:: True if the simulator is stopped.

Example:

>>> # given a simulation in play
>>> simulation_context.is_stopped()
False

pause() → None#

Pause the physics simulation.

Example:

>>> simulation_context.pause()

async pause_async() → None#

Pause the physics simulation.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.pause_async()
...
>>> run_coroutine(task())

physics_callback_exists(callback_name: str) → bool#

Check if a physics callback exists.

Parameters:: callback_name – Callback name.
Returns:: Whether the callback is registered.

Example:

>>> # given a registered callback named 'callback_physics'
>>> simulation_context.physics_callback_exists("callback_physics")
True

play() → None#

Start playing simulation.

Note

It does one step internally to propagate all physics handles properly.

Example:

>>> simulation_context.play()

async play_async() → None#

Start playing simulation.

Raises:

Exception – If there is no stage currently opened.
RuntimeError – If the physics context is not initialized.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.play_async()
...
>>> run_coroutine(task())

remove_physics_callback(callback_name: str) → None#

Remove a physics callback by its name.

Parameters:: callback_name – Callback name.

Example:

>>> # given a registered callback named 'callback_physics'
>>> simulation_context.remove_physics_callback("callback_physics")

remove_render_callback(callback_name: str) → None#

Remove a render callback by its name.

Parameters:: callback_name – Callback name.

Example:

>>> # given a registered callback named 'callback_render'
>>> simulation_context.remove_render_callback("callback_render")

remove_stage_callback(callback_name: str) → None#

Remove a stage callback by its name.

Parameters:: callback_name – Callback name.

Example:

>>> # given a registered callback named 'callback_stage'
>>> simulation_context.remove_stage_callback("callback_stage")

remove_timeline_callback(callback_name: str) → None#

Remove a timeline callback by its name.

Parameters:: callback_name – Callback name.

Example:

>>> # given a registered callback named 'timeline'
>>> simulation_context.remove_timeline_callback("timeline")

render() → None#

Refresh the Isaac Sim app rendering components, including UI elements, viewports, and others.

Warning

This method is not intended to be used in the Isaac Sim’s Extensions workflow since the Kit application has the control over the rendering steps

Example:

>>> simulation_context.render()

async render_async() → None#

Refresh the Isaac Sim app rendering components, including UI elements, viewports, and others.

Hint

This method is intended to be used in the Isaac Sim’s Extensions workflow where the Kit application has the control over timing of physics and rendering steps

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.render_async()
...
>>> run_coroutine(task())

render_callback_exists(callback_name: str) → bool#

Check if a render callback exists.

Parameters:: callback_name – Callback name.
Returns:: Whether the callback is registered.

Example:

>>> # given a registered callback named 'callback_render'
>>> simulation_context.render_callback_exists("callback_render")
True

reset(soft: bool = False) → None#

Reset the physics simulation view.

Warning

This method is not intended to be used in the Isaac Sim’s Extensions workflow since the Kit application has the control over the rendering steps. For the Extensions workflow use the reset_async method instead

Parameters:: soft – If set to True simulation won’t be stopped and start again. It only calls the reset on the scene objects.

Example:

>>> simulation_context.reset()

async reset_async(soft: bool = False) → None#

Reset the physics simulation view (asynchronous version).

Parameters:

soft – If set to True, simulation will not be stopped and started again. It only calls reset on the scene objects.

Raises:

Exception – If there is no stage currently opened.
RuntimeError – If the physics context is not initialized.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
>>>     await simulation_context.reset_async()
>>>
>>> run_coroutine(task())

set_block_on_render(block: bool) → None#

Set block on render flag for the simulation thread.

Note

This guarantees a one frame lag between any data captured from the render products and the current USD stage if enabled.

Parameters:: block – True to block the thread until the renderer is done.

Example:

>>> simulation_context.set_block_on_render(False)

set_simulation_dt( physics_dt: float | None = None, rendering_dt: float | None = None, ) → None#

Specify the physics step and rendering step size to use when stepping and rendering.

Parameters:

physics_dt – The physics time-step. None means it won’t change the current setting.
rendering_dt – The rendering time-step. None means it won’t change the current setting.

Raises:

Exception – If there is no stage currently opened.
ValueError – If rendering_dt is less than 0.

Hint

It is recommended that the two values be divisible, with the rendering_dt being equal to or greater than the physics_dt

Example:

>>> # set physics dt to 120 Hz and rendering dt to 60 Hz (2 physics steps for each rendering)
>>> simulation_context.set_simulation_dt(physics_dt=1.0 / 120.0, rendering_dt=1.0 / 60.0)

skip_next_stage_open_callback() → None#: Skip the next stage_open_callback_fn trigger.

stage_callback_exists(callback_name: str) → bool#

Check if a stage callback exists.

Parameters:: callback_name – Callback name.
Returns:: Whether the callback is registered.

Example:

>>> # given a registered callback named 'callback_stage'
>>> simulation_context.stage_callback_exists("callback_stage")
True

step( render: bool = True, update_fabric: bool = False, ) → None#

Steps the physics simulation while rendering or without.

Warning

Calling this method with the render parameter set to True is not intended to be used in the Isaac Sim’s Extensions workflow since the Kit application has the control over the rendering steps

Parameters:

render – Set to False to only do a physics simulation without rendering. Note: app UI will be frozen (since it is not rendering) in this case.
update_fabric – Whether to force the update of the physics data to fabric when performing a physics-only step (without rendering). This flag should be enabled when it is desired to read updated data using the fabric interface after performing a physics-only step (e.g., XFormPrim’s world transform).

Raises:

Exception – If there is no stage currently opened.

Example:

>>> simulation_context.step()

stop() → None#

Stop the physics simulation.

Example:

>>> simulation_context.stop()

async stop_async() → None#

Stop the physics simulation.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.stop_async()
...
>>> run_coroutine(task())

timeline_callback_exists(callback_name: str) → bool#

Check if a timeline callback exists.

Parameters:: callback_name – Callback name.
Returns:: Whether the callback is registered.

Example:

>>> # given a registered callback named 'callback_timeline'
>>> simulation_context.timeline_callback_exists("callback_timeline")
True

property app: omni.kit.app.IApp#

Omniverse Kit SDK Application interface.

Returns:: The Omniverse Kit SDK Application interface.

Example:

>>> simulation_context.app
<omni.kit.app._app.IApp object at 0x...>

property backend: str#

Current backend. Supported backends are "numpy", "torch" and "warp".

Returns:: The current backend name.

Example:

>>> simulation_context.backend
numpy

property backend_utils: object#

Current backend utils module.

Backend	Utils module
`"numpy"`	`isaacsim.core.utils.numpy`
`"torch"`	`isaacsim.core.utils.torch`
`"warp"`	`isaacsim.core.utils.warp`

Returns:: The current backend utils module.

Example:

>>> simulation_context.backend_utils
<module 'isaacsim.core.utils.numpy'>

property current_time: float#

Current time (simulated physical time) that has elapsed since the simulation was played.

Returns:: The current simulated physical time.

Example:

>>> # given a running Isaac Sim instance and after 911 physics steps at 60 Hz
>>> simulation_context.current_time
15.183334125205874

property current_time_step_index: int#

Current number of physics steps that has elapsed since the simulation was played.

Returns:: The current physics step count.

Example:

>>> # given a running Isaac Sim instance and after approximately 15 seconds of physics simulation at 60 Hz
>>> simulation_context.current_time_step_index
911

property device: str#

Device used by the physics context. None for numpy backend.

Returns:: The device used by the physics context.

Example:

>>> simulation_context.device
None

property physics_sim_view: object#

Physics simulation view instance.

Note

The physics simulation view instance will be only available after initializing the physics (see initialize_physics) or resetting the simulation context (see reset)

Returns:: Physics simulation view instance.

Example:

>>> simulation_context.physics_sim_view
<omni.physics.tensors.api.SimulationView object at 0x...>

property stage: pxr.Usd.Stage#

Current open USD stage.

Returns:: The current open USD stage.

Example:

>>> simulation_context.stage
Usd.Stage.Open(rootLayer=Sdf.Find('anon:0x...:World....usd'),
               sessionLayer=Sdf.Find('anon:0x...:World...-session.usda'),
               pathResolverContext=<invalid repr>)

World#

class World(*args: object, **kwargs: object)#

Bases: SimulationContext

Provide a comprehensive physics simulation world environment with scene management and task orchestration.

Extends SimulationContext with additional functionality for managing tasks and scenes. SimulationContext handles time-related events such as physics and render steps, callback function management for physics steps and timeline events, and stage operations.

Includes a PhysicsContext instance for physics-related settings such as physics dt and solver type.

Enables easy control of default reset states by adding objects to the Scene. Objects are bound to keywords that facilitate retrieval like a dictionary.

Check out the required tutorials at https://docs.isaacsim.omniverse.nvidia.com/latest/index.html

Parameters:

physics_dt – dt between physics steps.
rendering_dt – dt between rendering steps. Note: rendering means rendering a frame of the current application and not only rendering a frame to the viewports/cameras. So UI elements of Isaac Sim will be refreshed with this dt as well if running non-headless.
stage_units_in_meters – The metric units of assets. This affects the gravity value, etc.
physics_prim_path – Specifies the prim path to create a PhysicsScene at, only when no PhysicsScene is already defined.
sim_params – Simulation parameters.
set_defaults – Set to True to use the default settings [physics_dt = 1.0/ 60.0, stage units in meters = 1.0 (i.e. in meters), rendering_dt = 1.0 / 60.0, gravity = -9.81 m / s ccd_enabled, stabilization_enabled, GPU dynamics turned off, broadphase type is MBP, solver type is TGS].
backend – Specifies the backend to be used (numpy or torch or warp).
device – Specifies the device to be used if running on the GPU with torch or warp backends.

Example:

>>> from isaacsim.core.api import World
>>>
>>> world = World()
>>> world
<isaacsim.core.api.world.world.World object at 0x...>

Make SimulationContext a singleton.

Parameters:

*args – Additional positional arguments accepted by the constructor.
**kwargs – Additional keyword arguments accepted by the constructor.

Returns:

The SimulationContext singleton instance.

add_physics_callback( callback_name: str, callback_fn: Callable[[float], None], ) → None#

Add a callback which will be called before each physics step.

callback_fn should take a float argument (e.g., step_size).

Parameters:

callback_name – Unique name for the callback.
callback_fn – Function to call before each physics step, receives step size as argument.

Example:

>>> def callback_physics(step_size):
...     print("physics callback -> step_size:", step_size)
...
>>> simulation_context.add_physics_callback("callback_physics", callback_physics)

add_render_callback( callback_name: str, callback_fn: Callable, ) → None#

Add a callback which will be called after each rendering event such as .render().

callback_fn should take an event argument (e.g., event).

Parameters:

callback_name – Unique name for the callback.
callback_fn – Function to call after each render, receives event as argument.

Example:

>>> def callback_render(event):
...     print("render callback -> event:", event)
...
>>> simulation_context.add_render_callback("callback_render", callback_render)

add_stage_callback( callback_name: str, callback_fn: Callable, ) → None#

Add a callback which will be called after each stage event such as open/close among others.

callback_fn should take an argument of type omni.usd.StageEvent (e.g., event).

Parameters:

callback_name – Unique name for the callback.
callback_fn – Function to call on stage events, receives stage event as argument.

Example:

>>> def callback_stage(event):
...     print("stage callback -> event:", event)
...
>>> simulation_context.add_stage_callback("callback_stage", callback_stage)

add_task( task: BaseTask, ) → None#

Add a task to the task registry.

Note

Tasks should have a unique name

Parameters:: task – Task object to add.
Raises:: Exception – If a task with the same name already exists in the world.

Example:

>>> from isaacsim.core.api.tasks import BaseTask
>>>
>>> class Task(BaseTask):
...    def get_observations(self):
...        return {'obs': [0]}
...
...    def calculate_metrics(self):
...        return {"reward": 1}
...
...    def is_done(self):
...        return False
...
>>> task = Task(name="custom_task")
>>> world.add_task(task)

add_timeline_callback( callback_name: str, callback_fn: Callable, ) → None#

Add a callback which will be called after each timeline event such as play/pause.

callback_fn should take an argument of type omni.timeline.TimelineEvent (e.g., event).

Parameters:

callback_name – Unique name for the callback.
callback_fn – Function to call on timeline events, receives timeline event as argument.

Example:

>>> def callback_timeline(event):
...     print("timeline callback -> event:", event)
...
>>> simulation_context.add_timeline_callback("callback_timeline", callback_timeline)

calculate_metrics(task_name: str | None = None) → dict#

Get metrics from tasks that were added.

Parameters:: task_name – Task name to ask for. If None, returns metrics from all tasks.
Returns:: Computed metrics for the specified task or all tasks.
Raises:: Exception – If the task name does not exist in the current world tasks.

Example:

>>> world.calculate_metrics("custom_task")
{'reward': 1}

clear() → None#

Clear the current stage, task registry, task scene state, and data logger, leaving the PhysicsScene and /World.

Example:

>>> world.clear()

clear_all_callbacks() → None#

Clear all callbacks which were added using any add_*_callback method.

Example:

>>> simulation_context.clear_all_callbacks()

classmethod clear_instance() → None#

Delete the world object, if it was instantiated before, and destroy any subscribed callback.

Example:

>>> World.clear_instance()

clear_physics_callbacks() → None#

Remove all registered physics callbacks.

Example:

>>> simulation_context.clear_physics_callbacks()

clear_render_callbacks() → None#

Remove all registered render callbacks.

Example:

>>> simulation_context.clear_render_callbacks()

clear_stage_callbacks() → None#

Remove all registered stage callbacks.

Example:

>>> simulation_context.clear_stage_callbacks()

clear_timeline_callbacks() → None#

Remove all registered timeline callbacks.

Example:

>>> simulation_context.clear_timeline_callbacks()

get_block_on_render() → bool#

Get the block on render flag for the simulation thread.

Returns:: True if blocking the step call guarantees a one frame lag between any data captured from render products and the current USD stage.

Example:

>>> simulation_context.get_block_on_render()
False

get_current_tasks() → list[BaseTask]#

Get a dictionary of the registered tasks where keys are task names.

Returns:: Registered tasks keyed by task name.

Example:

>>> world.get_current_tasks()
{'custom_task': <custom.task.scripts.extension.Task object at 0x...>}

get_data_logger() → DataLogger#

Return the data logger of the world.

Returns:: Data logger instance.

Example:

>>> world.get_data_logger()
<isaacsim.core.api.loggers.data_logger.DataLogger object at 0x...>

get_observations(task_name: str | None = None) → dict#

Get observations from tasks that were added.

Parameters:: task_name – Task name to ask for. If None, returns observations from all tasks.
Returns:: Task observations for the specified task or all tasks.
Raises:: Exception – If the task name does not exist in the current world tasks.

Example:

>>> world.get_observations("custom_task")
{'obs': [0]}

get_physics_context() → PhysicsContext#

Get the physics context instance, a class to deal with a physics scene and its settings.

Raises:

Exception – If there is no stage currently opened.
RuntimeError – If the physics context is not initialized.

Returns:

Physics context object.

Example:

>>> simulation_context.get_physics_context()
<isaacsim.core.api.physics_context.physics_context.PhysicsContext object at 0x...>

get_physics_dt() → float#

Get the current physics dt of the physics context.

Raises:: Exception – If there is no stage currently opened.
Returns:: Current physics dt of the PhysicsContext.

Example:

>>> simulation_context.get_physics_dt()
0.016666666666666666

get_rendering_dt() → float#

Get the current rendering dt.

Raises:: Exception – If there is no stage currently opened.
Returns:: Current rendering dt.

Example:

>>> simulation_context.get_rendering_dt()
0.016666666666666666

get_task( name: str, ) → BaseTask#

Get a task by its name.

Parameters:: name – Task name to retrieve.
Returns:: The task with the specified name.
Raises:: Exception – If the task name does not exist in the current world tasks.

Example:

>>> world.get_task("custom_task")
<custom.task.scripts.extension.Task object at 0x...>

initialize_physics() → None#

Initialize the physics simulation view and finalize each object added to the Scene.

Example:

>>> world.initialize_physics()

async initialize_simulation_context_async() → None#

Initialize the simulation context.

Hint

This method is intended to be used in the Isaac Sim’s Extensions workflow where the Kit application has the control over timing of physics and rendering steps

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.initialize_simulation_context_async()
...
>>> run_coroutine(task())

classmethod instance() → SimulationContext#

Get the instance of the class, if it was instantiated before.

Returns:: The SimulationContext instance, or None if it has not been instantiated.

Example:

>>> # given that the class has already been instantiated before
>>> simulation_context = SimulationContext.instance()
>>> simulation_context
<isaacsim.core.api.simulation_context.simulation_context.SimulationContext object at 0x...>

is_done(task_name: str | None = None) → bool#

Get the done state from tasks that were added.

Parameters:: task_name – Task name to ask for. If None, checks if all tasks are done.
Returns:: Whether the specified task or all tasks are done.
Raises:: Exception – If the task name does not exist in the current world tasks.

Example:

>>> world.is_done("custom_task")
False

is_playing() → bool#

Check whether the simulation is playing.

Returns:: True if the simulator is playing.

Example:

>>> # given a simulation in play
>>> simulation_context.is_playing()
True

is_simulating() → bool#

Check whether the simulation is running.

Warning

With deprecation of Dynamic Control Toolbox, this function is not needed

It can return True if start_simulation is called even if play was pressed/called.

Returns:: True if physics simulation is happening.

Example:

>>> # given a running simulation
>>> simulation_context.is_simulating()
True

is_stopped() → bool#

Check whether the simulation is stopped.

Returns:: True if the simulator is stopped.

Example:

>>> # given a simulation in play
>>> simulation_context.is_stopped()
False

is_tasks_scene_built() → bool#

Check if the set_up_scene method was called for each registered task.

Returns:: Whether the set_up_scene method was called for each registered task.

Example:

>>> # given a world instance that was rested at some point
>>> world.is_tasks_scene_built()
True

pause() → None#

Pause the physics simulation.

Example:

>>> simulation_context.pause()

async pause_async() → None#

Pause the physics simulation.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.pause_async()
...
>>> run_coroutine(task())

physics_callback_exists(callback_name: str) → bool#

Check if a physics callback exists.

Parameters:: callback_name – Callback name.
Returns:: Whether the callback is registered.

Example:

>>> # given a registered callback named 'callback_physics'
>>> simulation_context.physics_callback_exists("callback_physics")
True

play() → None#

Start playing simulation.

Note

It does one step internally to propagate all physics handles properly.

Example:

>>> simulation_context.play()

async play_async() → None#

Start playing simulation.

Raises:

Exception – If there is no stage currently opened.
RuntimeError – If the physics context is not initialized.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.play_async()
...
>>> run_coroutine(task())

remove_physics_callback(callback_name: str) → None#

Remove a physics callback by its name.

Parameters:: callback_name – Callback name.

Example:

>>> # given a registered callback named 'callback_physics'
>>> simulation_context.remove_physics_callback("callback_physics")

remove_render_callback(callback_name: str) → None#

Remove a render callback by its name.

Parameters:: callback_name – Callback name.

Example:

>>> # given a registered callback named 'callback_render'
>>> simulation_context.remove_render_callback("callback_render")

remove_stage_callback(callback_name: str) → None#

Remove a stage callback by its name.

Parameters:: callback_name – Callback name.

Example:

>>> # given a registered callback named 'callback_stage'
>>> simulation_context.remove_stage_callback("callback_stage")

remove_timeline_callback(callback_name: str) → None#

Remove a timeline callback by its name.

Parameters:: callback_name – Callback name.

Example:

>>> # given a registered callback named 'timeline'
>>> simulation_context.remove_timeline_callback("timeline")

render() → None#

Refresh the Isaac Sim app rendering components, including UI elements, viewports, and others.

Warning

This method is not intended to be used in the Isaac Sim’s Extensions workflow since the Kit application has the control over the rendering steps

Example:

>>> simulation_context.render()

async render_async() → None#

Refresh the Isaac Sim app rendering components, including UI elements, viewports, and others.

Hint

This method is intended to be used in the Isaac Sim’s Extensions workflow where the Kit application has the control over timing of physics and rendering steps

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.render_async()
...
>>> run_coroutine(task())

render_callback_exists(callback_name: str) → bool#

Check if a render callback exists.

Parameters:: callback_name – Callback name.
Returns:: Whether the callback is registered.

Example:

>>> # given a registered callback named 'callback_render'
>>> simulation_context.render_callback_exists("callback_render")
True

reset(soft: bool = False) → None#

Reset the stage to its initial state and each object included in the Scene to its default state.

The default state is specified by the set_default_state and __init__ methods.

Note

All tasks should be added before the first reset is called unless the clear method was called.
All articulations should be added before the first reset is called unless the clear method was called.
This method takes care of initializing articulation handles with the first reset called.
This will do one step internally regardless.
Call post_reset on each object in the Scene.
Call post_reset on each Task.

Things like setting PD gains should happen at a Task reset or a Robot reset since the defaults are restored after the stop method is called.

Warning

This method is not intended to be used in the Isaac Sim’s Extensions workflow since the Omniverse Kit SDK application has control over the rendering steps. For the Extensions workflow, use the reset_async method instead.

Parameters:: soft – If set to True, simulation will not be stopped and started again. It only calls reset on the Scene objects.

Example:

>>> world.reset()

async reset_async(soft: bool = False) → None#

Reset the stage to its initial state and each object included in the Scene to its default state.

The default state is specified by the set_default_state and __init__ methods.

Note

All tasks should be added before the first reset is called unless the clear method was called.
All articulations should be added before the first reset is called unless the clear method was called.
This method takes care of initializing articulation handles with the first reset called.
This will do one step internally regardless.
Call post_reset on each object in the Scene.
Call post_reset on each Task.

Things like setting PD gains should happen at a Task reset or a Robot reset since the defaults are restored after the stop method is called.

Parameters:: soft – If set to True, simulation will not be stopped and started again. It only calls reset on the Scene objects.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await world.reset_async()
...
>>> run_coroutine(task())

async reset_async_no_set_up_scene(soft: bool = False) → None#

Reset the stage and each object included in the Scene without calling Task set_up_scene.

The default state is specified by the set_default_state and __init__ methods.

Note

All tasks should be added before the first reset is called unless the clear method was called.
All articulations should be added before the first reset is called unless the clear method was called.
This method takes care of initializing articulation handles with the first reset called.
This will do one step internally regardless.
Call post_reset on each object in the Scene.
Call post_reset on each Task.

Things like setting PD gains should happen at a Task reset or a Robot reset since the defaults are restored after the stop method is called.

Parameters:: soft – If set to True, simulation will not be stopped and started again. It only calls reset on the Scene objects.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
>>>     await world.reset_async_no_set_up_scene()
>>>
>>> run_coroutine(task())

async reset_async_set_up_scene(soft: bool = False) → None#

Set up the Scene for each registered task before an async reset.

Calls set_up_scene on each Task with the World Scene.

Parameters:: soft – Unused parameter kept for compatibility with async reset methods.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
>>>     await world.reset_async_set_up_scene()
>>>
>>> run_coroutine(task())

set_block_on_render(block: bool) → None#

Set block on render flag for the simulation thread.

Note

This guarantees a one frame lag between any data captured from the render products and the current USD stage if enabled.

Parameters:: block – True to block the thread until the renderer is done.

Example:

>>> simulation_context.set_block_on_render(False)

set_simulation_dt( physics_dt: float | None = None, rendering_dt: float | None = None, ) → None#

Specify the physics step and rendering step size to use when stepping and rendering.

Parameters:

physics_dt – The physics time-step. None means it won’t change the current setting.
rendering_dt – The rendering time-step. None means it won’t change the current setting.

Raises:

Exception – If there is no stage currently opened.
ValueError – If rendering_dt is less than 0.

Hint

It is recommended that the two values be divisible, with the rendering_dt being equal to or greater than the physics_dt

Example:

>>> # set physics dt to 120 Hz and rendering dt to 60 Hz (2 physics steps for each rendering)
>>> simulation_context.set_simulation_dt(physics_dt=1.0 / 120.0, rendering_dt=1.0 / 60.0)

skip_next_stage_open_callback() → None#: Skip the next stage_open_callback_fn trigger.

stage_callback_exists(callback_name: str) → bool#

Check if a stage callback exists.

Parameters:: callback_name – Callback name.
Returns:: Whether the callback is registered.

Example:

>>> # given a registered callback named 'callback_stage'
>>> simulation_context.stage_callback_exists("callback_stage")
True

step( render: bool = True, step_sim: bool = True, update_fabric: bool = False, ) → None#

Step the physics simulation with or without rendering.

Note

The pre_step for each Task is called before stepping. This method also updates the Bounding Box Cache time for computing bounding boxes if enabled.

Warning

Calling this method with render set to True is not intended to be used in the Isaac Sim’s Extensions workflow since the Omniverse Kit SDK application has control over the rendering steps.

Parameters:

render – Set to False to only do a physics simulation without rendering. The application UI will be frozen because it is not rendering in this case.
step_sim – True to step simulation.
update_fabric – Whether to force the update of the physics data to fabric when performing a physics-only step without rendering. Enable this flag to read updated data using the fabric interface after performing a physics-only step, such as XFormPrim’s world transform.

Raises:

Exception – If data logging is started before adding a data frame logging function.

Example:

>>> world.step()

step_async(step_size: float | None = None) → None#

Run World pre-step updates before an external physics step.

Note

The pre_step for each Task is called before stepping. This method also updates the Bounding Box Cache time for computing bounding boxes if enabled.

Parameters:: step_size – Unused step size parameter.
Raises:: Exception – If data logging is started before adding a data frame logging function.

Example:

>>> world.step_async()

stop() → None#

Stop the physics simulation.

Example:

>>> simulation_context.stop()

async stop_async() → None#

Stop the physics simulation.

Example:

>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await simulation_context.stop_async()
...
>>> run_coroutine(task())

timeline_callback_exists(callback_name: str) → bool#

Check if a timeline callback exists.

Parameters:: callback_name – Callback name.
Returns:: Whether the callback is registered.

Example:

>>> # given a registered callback named 'callback_timeline'
>>> simulation_context.timeline_callback_exists("callback_timeline")
True

property app: omni.kit.app.IApp#

Omniverse Kit SDK Application interface.

Returns:: The Omniverse Kit SDK Application interface.

Example:

>>> simulation_context.app
<omni.kit.app._app.IApp object at 0x...>

property backend: str#

Current backend. Supported backends are "numpy", "torch" and "warp".

Returns:: The current backend name.

Example:

>>> simulation_context.backend
numpy

property backend_utils: object#

Current backend utils module.

Backend	Utils module
`"numpy"`	`isaacsim.core.utils.numpy`
`"torch"`	`isaacsim.core.utils.torch`
`"warp"`	`isaacsim.core.utils.warp`

Returns:: The current backend utils module.

Example:

>>> simulation_context.backend_utils
<module 'isaacsim.core.utils.numpy'>

property current_time: float#

Current time (simulated physical time) that has elapsed since the simulation was played.

Returns:: The current simulated physical time.

Example:

>>> # given a running Isaac Sim instance and after 911 physics steps at 60 Hz
>>> simulation_context.current_time
15.183334125205874

property current_time_step_index: int#

Current number of physics steps that has elapsed since the simulation was played.

Returns:: The current physics step count.

Example:

>>> # given a running Isaac Sim instance and after approximately 15 seconds of physics simulation at 60 Hz
>>> simulation_context.current_time_step_index
911

property device: str#

Device used by the physics context. None for numpy backend.

Returns:: The device used by the physics context.

Example:

>>> simulation_context.device
None

property physics_sim_view: object#

Physics simulation view instance.

Note

The physics simulation view instance will be only available after initializing the physics (see initialize_physics) or resetting the simulation context (see reset)

Returns:: Physics simulation view instance.

Example:

>>> simulation_context.physics_sim_view
<omni.physics.tensors.api.SimulationView object at 0x...>

property scene: Scene#

Scene instance.

Returns:: Scene instance.

Example:

>>> world.scene
<isaacsim.core.api.scenes.scene.Scene object at 0x>

property stage: pxr.Usd.Stage#

Current open USD stage.

Returns:: The current open USD stage.

Example:

>>> simulation_context.stage
Usd.Stage.Open(rootLayer=Sdf.Find('anon:0x...:World....usd'),
               sessionLayer=Sdf.Find('anon:0x...:World...-session.usda'),
               pathResolverContext=<invalid repr>)

Tasks#

class BaseTask(name: str, offset: ndarray | None = None)#

Bases: object

This class provides a way to set up a task in a scene and modularize adding objects to a stage.

It gets observations needed for the behavioral layer, calculates metrics needed about the task, calls certain things pre-stepping, creates multiple tasks at the same time and much more.

Check out the required tutorials at https://docs.isaacsim.omniverse.nvidia.com/latest/index.html

Parameters:

name – Must be unique if added to the World.
offset – Offset applied to all assets of the task.

Raises:

RuntimeError – If the current USD stage or USD stage meters-to-unit conversion factor is not valid.

calculate_metrics() → dict#

Calculate task metrics.

Raises:: NotImplementedError – Must be implemented by subclass.
Returns:: Dictionary containing calculated task metrics.

cleanup() → None#: Called before calling reset() on the world to remove temporary objects added during simulation.

get_description() → str#

Gets a description of the task.

Returns:: The task description.

get_observations() → dict#

Current observations from the objects needed for the behavioral layer.

Raises:: NotImplementedError – Must be implemented by subclass.
Returns:: Dictionary containing task-specific observations.

get_params() → dict#

Gets the parameters of the task.

This is defined differently for each task in order to access the task’s objects and values. Note that this is different from get_observations. Things like the robot name, block name, etc. can be defined here for faster retrieval. Parameters should have the form of params_representation[“param_name”] = {“value”: param_value, “modifiable”: bool}.

Returns:: The parameters of the task.
Raises:: NotImplementedError – Must be implemented by subclass.

get_task_objects() → dict#

All objects registered with the task.

Returns:: Dictionary of task objects keyed by name.

is_done() → bool#

True if the task is done.

Raises:: NotImplementedError – Must be implemented by subclass.
Returns:: True if the task is complete, False otherwise.

post_reset() → None#: Called while doing a .reset() on the world.

pre_step( time_step_index: int, simulation_time: float, ) → None#

Called before stepping the physics simulation.

Parameters:

time_step_index – Current physics step index.
simulation_time – Current simulation time in seconds.

set_params(*args: object, **kwargs: object) → None#

Changes the modifiable parameters of the task.

Parameters:

*args – Variable length argument list.
**kwargs – Additional keyword arguments for task parameters.

Raises:

NotImplementedError – Must be implemented by subclass.

set_up_scene( scene: Scene, ) → None#

Add assets to the stage and register encapsulated objects such as SingleXFormPrim in task_objects.

Parameters:: scene – The scene to set up with task assets.

property device: str#

Device used for simulation computations.

Returns:: The simulation device instance.

property name: str#

Name of the task.

Returns:: The task name.

property scene: Scene#

Scene instance associated with this task.

Returns:: The scene instance associated with this task.

Bases: ABC, BaseTask

Abstract task for following a target with a robot end effector.

Parameters:

name – Task name identifier.
target_prim_path – USD path for the target prim.
target_name – Name for the target object.
target_position – Initial target position.
target_orientation – Initial target orientation.
offset – Offset for all task objects.

add_obstacle(position: ndarray = None) → None#

Add an obstacle cube to the scene and track it for removal.

Parameters:: position – Position for the obstacle.
Returns:: The created obstacle cube object.

calculate_metrics() → dict#

Calculate task metrics.

Returns:: Dictionary containing calculated task metrics.
Raises:: NotImplementedError – Must be implemented by subclass.

cleanup() → None#: Remove all obstacles from the scene.

get_description() → str#

Gets a description of the task.

Returns:: The task description.

get_observations() → dict#

Get current task observations.

Returns:: Dictionary with robot and target observations.

get_obstacle_to_delete() → object#

Get the last obstacle that would be deleted.

Returns:: The obstacle object to be deleted.
Raises:: IndexError – If no obstacles exist.

get_params() → dict#

Get task parameters.

Returns:: Dictionary of task parameters.

get_task_objects() → dict#

All objects registered with the task.

Returns:: Dictionary of task objects keyed by name.

is_done() → bool#

Check if task is complete.

Returns:: Whether the task is complete.
Raises:: NotImplementedError – Must be implemented by subclass.

obstacles_exist() → bool#

Check if any obstacles exist in the scene.

Returns:: True if obstacles exist, False otherwise.

post_reset() → None#: Called after world reset.

pre_step( time_step_index: int, simulation_time: float, ) → None#

Called before each physics step to update target visual.

Parameters:

time_step_index – Current simulation step index.
simulation_time – Current simulation time.

remove_obstacle(name: str | None = None) → None#

Remove an obstacle from the scene.

Parameters:

name – Name of obstacle to remove. If not provided, removes the last added obstacle.

Raises:

IndexError – If no obstacles are available to remove when name is not provided.
KeyError – If name is provided and no tracked obstacle has that name.

set_params( target_prim_path: str | None = None, target_name: str | None = None, target_position: ndarray | None = None, target_orientation: ndarray | None = None, ) → None#

Set task parameters including target pose.

Parameters:

target_prim_path – USD path for target.
target_name – Name for target object.
target_position – Target position.
target_orientation – Target orientation.

Raises:

RuntimeError – If updating the target pose before set_up_scene() has been called.

abstract set_robot() → None#

Create and return the robot for this task.

Raises:: NotImplementedError – Must be implemented by subclass.

set_up_scene( scene: Scene, ) → None#

Set up the scene with target and robot.

Parameters:: scene – The scene to populate.

target_reached() → bool#

Check if the end effector has reached the target.

Returns:: True if target is reached, False otherwise.

property device: str#

Device used for simulation computations.

Returns:: The simulation device instance.

property name: str#

Name of the task.

Returns:: The task name.

property scene: Scene#

Scene instance associated with this task.

Returns:: The scene instance associated with this task.

Bases: ABC, BaseTask

Abstract task for picking and placing a cube with a robot.

Parameters:

name – Task name identifier.
cube_initial_position – Initial cube position.
cube_initial_orientation – Initial cube orientation.
target_position – Target position for placing.
cube_size – Size of the cube.
offset – Offset for all task objects.

calculate_metrics() → dict#

Calculates task metrics.

Returns:: Task metrics.
Raises:: NotImplementedError – If the method is not implemented by a subclass.

cleanup() → None#: Called before calling reset() on the world to remove temporary objects added during simulation.

get_description() → str#

Gets a description of the task.

Returns:: The task description.

get_observations() → dict#

Gets current task observations for the cube and robot.

Returns:: Observations keyed by cube name and robot name, including cube pose, target position, robot joint positions, and end effector position when available.

get_params() → dict#

Gets current task parameters including cube and robot states.

Returns:: Task parameter entries with values and modifiability flags.

get_task_objects() → dict#

All objects registered with the task.

Returns:: Dictionary of task objects keyed by name.

is_done() → bool#

Checks if the task is complete.

Returns:: True if the task is complete.
Raises:: NotImplementedError – If the method is not implemented by a subclass.

post_reset() → None#: Resets the robot ParallelGripper to its opened joint positions after task reset.

pre_step( time_step_index: int, simulation_time: float, ) → None#

Runs before each physics step.

Parameters:

time_step_index – Current simulation step index.
simulation_time – Current simulation time.

set_params( cube_position: ndarray | None = None, cube_orientation: ndarray | None = None, target_position: ndarray | None = None, ) → None#

Sets task parameters for cube position, orientation, and target position.

Parameters:

cube_position – Cube local position to set when provided.
cube_orientation – Cube local orientation to set when provided.
target_position – Target position for placing the cube.

abstract set_robot() → None#

Creates and configures the robot for the task.

Raises:: NotImplementedError – If the method is not implemented by a subclass.

set_up_scene( scene: Scene, ) → None#

Sets up the scene with a ground plane, cube, and robot.

Parameters:: scene – Scene to populate with the ground plane, cube, and robot.

property device: str#

Device used for simulation computations.

Returns:: The simulation device instance.

property name: str#

Name of the task.

Returns:: The task name.

property scene: Scene#

Scene instance associated with this task.

Returns:: The scene instance associated with this task.

class Stacking( name: str, cube_initial_positions: ndarray, cube_initial_orientations: ndarray | None = None, stack_target_position: ndarray | None = None, cube_size: ndarray | None = None, offset: ndarray | None = None, )#

Bases: ABC, BaseTask

Abstract task for stacking multiple cubes with a robot.

Parameters:

name – Task name identifier.
cube_initial_positions – Initial positions for all cubes.
cube_initial_orientations – Initial orientations for cubes.
stack_target_position – Position at which to stack cubes.
cube_size – Size of each cube.
offset – Offset for all task objects.

calculate_metrics() → dict#

Calculates task metrics.

Returns:: The computed task metrics.
Raises:: NotImplementedError – Must be implemented by subclass.

cleanup() → None#: Called before calling reset() on the world to remove temporary objects added during simulation.

get_cube_names() → list[str]#

Gets the names of all cubes in the task.

Returns:: Cube names.

get_description() → str#

Gets a description of the task.

Returns:: The task description.

get_observations() → dict#

Gets current task observations.

Returns:: Dictionary containing robot joint and end effector data plus cube pose and target position data.

get_params() → dict#

Gets task parameters.

Returns:: Dictionary containing stack_target_position and robot_name entries with value and modifiable metadata.

get_task_objects() → dict#

All objects registered with the task.

Returns:: Dictionary of task objects keyed by name.

is_done() → bool#

Checks if task is complete.

Returns:: True if the task is complete, False otherwise.
Raises:: NotImplementedError – Must be implemented by subclass.

post_reset() → None#: Opens the ParallelGripper after a world reset.

pre_step( time_step_index: int, simulation_time: float, ) → None#

Called before each physics step.

Parameters:

time_step_index – Current simulation step index.
simulation_time – Current simulation time.

set_params( cube_name: str | None = None, cube_position: ndarray | None = None, cube_orientation: ndarray | None = None, stack_target_position: ndarray | None = None, ) → None#

Sets task parameters.

Parameters:

cube_name – Name of cube to modify.
cube_position – New position for cube.
cube_orientation – New orientation for cube.
stack_target_position – New stack target position.

abstract set_robot() → None#

Creates and returns the robot for this task.

Raises:: NotImplementedError – Must be implemented by subclass.

set_up_scene( scene: Scene, ) → None#

Sets up the scene with cubes and robot.

Parameters:: scene – Scene to populate with task objects.

property device: str#

Device used for simulation computations.

Returns:: The simulation device instance.

property name: str#

Name of the task.

Returns:: The task name.

property scene: Scene#

Scene instance associated with this task.

Returns:: The scene instance associated with this task.

Python API