isaaclab.sim.views

isaaclab.sim.views#

Views for manipulating USD prims.

Classes

BaseFrameView

Abstract interface for reading and writing world-space transforms of multiple prims.

UsdFrameView

Batched interface for reading and writing transforms of multiple USD prims.

FrameView

FrameView that dispatches to the active physics backend.

Base Frame View#

class isaaclab.sim.views.BaseFrameView[source]#

Bases: ABC

Abstract interface for reading and writing world-space transforms of multiple prims.

Backend-specific implementations (USD/Fabric, Newton GPU state, etc.) subclass this to provide efficient batched pose queries. The factory FrameView selects the correct implementation at runtime based on the active physics backend.

All pose getters return ProxyArray. Setters accept wp.array.

Attributes:

count

Number of prims in this view.

device

Device where arrays are allocated ("cpu" or "cuda:0").

Methods:

get_world_poses([indices])

Get world-space positions and orientations for prims in the view.

set_world_poses([positions, orientations, ...])

Set world-space positions and/or orientations for prims in the view.

get_local_poses([indices])

Get local-space positions and orientations for prims in the view.

set_local_poses([translations, ...])

Set local-space translations and/or orientations for prims in the view.

get_scales([indices])

Get scales for prims in the view.

set_scales(scales[, indices])

Set scales for prims in the view.
abstract property count: int#

Number of prims in this view.

abstract property device: str#

Device where arrays are allocated ("cpu" or "cuda:0").

abstractmethod get_world_poses(indices: wp.array | None = None) → tuple[ProxyArray, ProxyArray][source]#

Get world-space positions and orientations for prims in the view.

Parameters:

indices – Subset of prims to query. None means all prims.

Returns:

A tuple (positions, orientations) of ProxyArray wrappers. Use .warp for the underlying wp.array or .torch for a cached zero-copy torch.Tensor view.

abstractmethod set_world_poses(positions: wp.array | None = None, orientations: wp.array | None = None, indices: wp.array | None = None) → None[source]#

Set world-space positions and/or orientations for prims in the view.

Parameters:

  • positions – World-space positions (M, 3). None leaves positions unchanged.

  • orientations – World-space quaternions (M, 4). None leaves orientations unchanged.

  • indices – Subset of prims to update. None means all prims.

abstractmethod get_local_poses(indices: wp.array | None = None) → tuple[ProxyArray, ProxyArray][source]#

Get local-space positions and orientations for prims in the view.

Parameters:

indices – Subset of prims to query. None means all prims.

Returns:

A tuple (translations, orientations) of ProxyArray wrappers. Use .warp for the underlying wp.array or .torch for a cached zero-copy torch.Tensor view.

abstractmethod set_local_poses(translations: wp.array | None = None, orientations: wp.array | None = None, indices: wp.array | None = None) → None[source]#

Set local-space translations and/or orientations for prims in the view.

Parameters:

  • translations – Local-space translations (M, 3). None leaves translations unchanged.

  • orientations – Local-space quaternions (M, 4). None leaves orientations unchanged.

  • indices – Subset of prims to update. None means all prims.

abstractmethod get_scales(indices: wp.array | None = None) → wp.array[source]#

Get scales for prims in the view.

Parameters:

indices – Subset of prims to query. None means all prims.

Returns:

A wp.array of shape (M, 3).

abstractmethod set_scales(scales: wp.array, indices: wp.array | None = None) → None[source]#

Set scales for prims in the view.

Parameters:

  • scales – Scales (M, 3) as wp.array.

  • indices – Subset of prims to update. None means all prims.

USD Frame View#

class isaaclab.sim.views.UsdFrameView[source]#

Bases: BaseFrameView

Batched interface for reading and writing transforms of multiple USD prims.

Provides batch operations for getting and setting poses (position and orientation) of multiple prims at once via USD’s XformCache.

The class supports both world-space and local-space pose operations:

  • World poses: Positions and orientations in the global world frame

  • Local poses: Positions and orientations relative to each prim’s parent

For GPU-accelerated Fabric operations, use the PhysX backend variant obtained via FrameView.

Pose getters return ProxyArray. Setters accept wp.array.

Note

Transform Requirements:

All prims in the view must be Xformable and have standardized transform operations: [translate, orient, scale]. Non-standard prims will raise a ValueError during initialization if validate_xform_ops is True. Please use the function isaaclab.sim.utils.standardize_xform_ops() to prepare prims before using this view.

Warning

This class operates at the USD default time code. Any animation or time-sampled data will not be affected by write operations. For animated transforms, you need to handle time-sampled keyframes separately.

Methods:

__init__(prim_path[, device, ...])

Initialize the view with matching prims.

set_world_poses([positions, orientations, ...])

Set world-space poses for prims in the view.

set_local_poses([translations, ...])

Set local-space poses for prims in the view.

set_scales(scales[, indices])

Set scales for prims in the view.

set_visibility(visibility[, indices])

Set visibility for prims in the view.

get_world_poses([indices])

Get world-space poses for prims in the view.

get_local_poses([indices])

Get local-space poses for prims in the view.

get_scales([indices])

Get scales for prims in the view.

get_visibility([indices])

Get visibility for prims in the view.

Attributes:

count

Number of prims in this view.

device

Device where arrays are allocated (cpu or cuda).

prims

List of USD prims being managed by this view.

prim_paths

List of prim paths (as strings) for all prims being managed by this view.
__init__(prim_path: str, device: str = 'cpu', validate_xform_ops: bool = True, stage: Usd.Stage | None = None, **kwargs)[source]#

Initialize the view with matching prims.

Parameters:

  • prim_path – USD prim path pattern to match prims. Supports wildcards (*) and regex patterns (e.g., "/World/Env_.*/Robot"). See isaaclab.sim.utils.find_matching_prims() for pattern syntax.

  • device – Device to place arrays on. Can be "cpu" or CUDA devices like "cuda:0". Defaults to "cpu".

  • validate_xform_ops – Whether to validate that the prims have standard xform operations. Defaults to True.

  • stage – USD stage to search for prims. Defaults to None, in which case the current active stage from the simulation context is used.

  • **kwargs – Additional keyword arguments (ignored). Allows forward-compatible construction when callers pass backend-specific options like sync_usd_on_fabric_write.

Raises:

ValueError – If any matched prim is not Xformable or doesn’t have standardized transform operations (translate, orient, scale in that order).

property count: int#

Number of prims in this view.

property device: str#

Device where arrays are allocated (cpu or cuda).

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

List of USD prims being managed by this view.

property prim_paths: list[str]#

List of prim paths (as strings) for all prims being managed by this view.

The conversion is performed lazily on first access and cached.

set_world_poses(positions: wp.array | None = None, orientations: wp.array | None = None, indices: wp.array | None = None)[source]#

Set world-space poses for prims in the view.

Converts the desired world pose to local-space relative to each prim’s parent before writing to USD xform ops.

Parameters:

  • positions – World-space positions of shape (M, 3).

  • orientations – World-space quaternions (w, x, y, z) of shape (M, 4).

  • indices – Indices of prims to set poses for. Defaults to None (all prims).

set_local_poses(translations: wp.array | None = None, orientations: wp.array | None = None, indices: wp.array | None = None)[source]#

Set local-space poses for prims in the view.

Parameters:

  • translations – Local-space translations of shape (M, 3).

  • orientations – Local-space quaternions (w, x, y, z) of shape (M, 4).

  • indices – Indices of prims to set poses for. Defaults to None (all prims).

set_scales(scales: wp.array, indices: wp.array | None = None)[source]#

Set scales for prims in the view.

Parameters:

  • scales – Scales of shape (M, 3).

  • indices – Indices of prims to set scales for. Defaults to None (all prims).

set_visibility(visibility: torch.Tensor, indices: wp.array | None = None)[source]#

Set visibility for prims in the view.

Parameters:

  • visibility – Visibility as a boolean tensor of shape (M,).

  • indices – Indices of prims to set visibility for. Defaults to None (all prims).

get_world_poses(indices: wp.array | None = None) → tuple[ProxyArray, ProxyArray][source]#

Get world-space poses for prims in the view.

Parameters:

indices – Indices of prims to get poses for. Defaults to None (all prims).

Returns:

A tuple (positions, orientations) of ProxyArray wrappers. Use .warp for the underlying wp.array or .torch for a cached zero-copy torch.Tensor view.

get_local_poses(indices: wp.array | None = None) → tuple[ProxyArray, ProxyArray][source]#

Get local-space poses for prims in the view.

Parameters:

indices – Indices of prims to get poses for. Defaults to None (all prims).

Returns:

A tuple (translations, orientations) of ProxyArray wrappers. Use .warp for the underlying wp.array or .torch for a cached zero-copy torch.Tensor view.

get_scales(indices: wp.array | None = None) → wp.array[source]#

Get scales for prims in the view.

Parameters:

indices – Indices of prims to get scales for. Defaults to None (all prims).

Returns:

A wp.array of shape (M, 3).

get_visibility(indices: wp.array | None = None) → torch.Tensor[source]#

Get visibility for prims in the view.

Parameters:

indices – Indices of prims to get visibility for. Defaults to None (all prims).

Returns:

A tensor of shape (M,) containing the visibility of each prim (bool).

Frame View#

class isaaclab.sim.views.FrameView[source]#

Bases: FactoryBase, BaseFrameView

FrameView that dispatches to the active physics backend.

Callers use FrameView(prim_path, device=device) and get the correct implementation automatically:

  • PhysX / no backend: FabricFrameView (Fabric GPU acceleration with USD fallback).

  • Newton: NewtonSiteFrameView (GPU-resident site-based transforms).

Methods:

__new__(cls, *args, **kwargs)

Create a new FrameView for the active physics backend.
static __new__(cls, *args, **kwargs) → BaseFrameView[source]#

Create a new FrameView for the active physics backend.