isaaclab.sim.views

Views for manipulating USD prims.

Classes

BaseFrameView	Abstract interface for reading and writing 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

Bases: ABC

Abstract interface for reading and writing 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 getters return ProxyArray. All writes go through the writer-scope API – xform_world_space_writer() or xform_local_space_writer():

with view.xform_world_space_writer() as writer:
    writer.set_poses(positions=p, orientations=o)
    writer.set_scales(scales=s)
# Derived-space matrices are recomputed and the writer scope is closed.

Only one writer scope may be active per view at a time. While a writer scope is active, the view-level getters (get_world_poses(), get_local_poses(), get_world_scales(), get_local_scales()) raise RuntimeError – use the writer’s get_poses() or get_scales() inside the scope, or exit the scope first.

Attributes:

count	Number of prims in this view.
device	Device where arrays are allocated ("cpu" or "cuda:0").

Methods:

xform_world_space_writer()	Open a world-space write scope on this view (recommended write API).
xform_local_space_writer()	Open a local-space write scope on this view (recommended write API).
get_world_poses([indices])	Get world-space positions and orientations for prims in the view.
get_local_poses([indices])	Get local-space translations and orientations for prims in the view.
get_local_scales([indices])	Get local-space scales for prims in the view.
get_world_scales([indices])	Get world-space (composed) scales for prims in the view.
set_world_poses([positions, orientations, ...])	Set world-space positions and/or 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").

xform_world_space_writer() → FrameViewWorldSpaceWriter

Open a world-space write scope on this view (recommended write API).

Inside the scope, set_poses() / set_scales() write world-space values.

Returns:

A FrameViewWorldSpaceWriter context manager.

Raises:

RuntimeError – On __enter__, if another writer is already active on this view.

Example

with view.xform_world_space_writer() as w:
    w.set_poses(positions=p, orientations=o)
    w.set_scales(scales=s)

xform_local_space_writer() → FrameViewLocalSpaceWriter

Open a local-space write scope on this view (recommended write API).

Inside the scope, set_poses() / set_scales() write local-space values.

Returns:

A FrameViewLocalSpaceWriter context manager.

Raises:

RuntimeError – On __enter__, if another writer is already active on this view.

Example

with view.xform_local_space_writer() as w:
    w.set_poses(translations=t, orientations=o)
    w.set_scales(scales=s)

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

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.

Raises:

RuntimeError – If a writer scope is active on this view.

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

Get local-space translations 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.

Raises:

RuntimeError – If a writer scope is active on this view.

get_local_scales(indices: wp.array | None = None) → ProxyArray

Get local-space scales for prims in the view.

Parameters:

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

Returns:

A ProxyArray of shape (M, 3).

Raises:

RuntimeError – If a writer scope is active on this view.

get_world_scales(indices: wp.array | None = None) → ProxyArray

Get world-space (composed) scales for prims in the view.

Returns the effective scale in world space (parent_scale * local_scale).

Note

Scale extraction uses TRS (Translation-Rotation-Scale) decomposition, which assumes no shear/skew in the transform matrix. If a prim’s world transform contains shear, the extracted scale values will be approximate.

Parameters:

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

Returns:

A ProxyArray of shape (M, 3).

Raises:

RuntimeError – If a writer scope is active on this view.

set_world_poses(positions: wp.array | None = None, orientations: wp.array | None = None, indices: wp.array | None = None) → None

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

This convenience method opens a single-statement writer scope internally. To update poses and scales together without paying the opposite-space derive/sync twice, prefer with view.xform_world_space_writer() as w: w.set_poses(...); w.set_scales(...).

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.

set_local_poses(translations: wp.array | None = None, orientations: wp.array | None = None, indices: wp.array | None = None) → None

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

This convenience method opens a single-statement writer scope internally. To update poses and scales together without paying the opposite-space derive/sync twice, prefer with view.xform_local_space_writer() as w: w.set_poses(...); w.set_scales(...).

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.

get_scales(indices: wp.array | None = None) → ProxyArray

Get scales for prims in the view.

Note

Prefer the explicit get_local_scales() or get_world_scales() when the space matters. This method delegates to _get_scales_impl(), which preserves each backend’s legacy space (world for Fabric, local for USD).

Parameters:

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

Returns:

A ProxyArray of shape (M, 3).

Raises:

RuntimeError – If a writer scope is active on this view.

set_scales(scales: wp.array, indices: wp.array | None = None) → None

Set scales for prims in the view.

This convenience method delegates to _set_scales_impl(), which opens the backend’s legacy space (world for Fabric, local for USD) and calls writer.set_scales. To update poses and scales together without paying the opposite-space derive/sync twice, prefer with view.xform_world_space_writer() as w: w.set_poses(...); w.set_scales(...) (or xform_local_space_writer()).

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

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.

All writes go through the writer-scope API (xform_world_space_writer() / xform_local_space_writer()). The USD backend’s writers are pass-throughs: each set_poses() / set_scales() call directly modifies the prim’s USD xformOp:* attributes (no batching, no derivation step on exit) – USD has no separate world-matrix storage to keep in sync.

Getters return ProxyArray.

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_visibility(visibility[, indices])	Set visibility 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)

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.

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_visibility(visibility: torch.Tensor, indices: wp.array | None = None)

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_visibility(indices: wp.array | None = None) → torch.Tensor

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

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

• OVPhysX: OvPhysxFrameView (Warp-native, reads body poses via an OVPhysX RIGID_BODY_POSE tensor binding).

• Newton: NewtonSiteFrameView (Warp-native, reads body_q from the Newton state).

Methods:

__new__(cls, *args, **kwargs)

Create a new FrameView for the active physics backend.

static __new__(cls, *args, **kwargs) → BaseFrameView

Create a new FrameView for the active physics backend.