isaaclab_ovphysx.sim.views

OVPhysX simulation views.

Classes

OvPhysxView

A string-keyed, generic view over OVPhysX TensorBinding handles for one prim set.

Tensor Binding View

class isaaclab_ovphysx.sim.views.OvPhysxView

Bases: object

A string-keyed, generic view over OVPhysX TensorBinding handles for one prim set.

Parameters:

• physx – The OVPhysX PhysX instance exposing create_tensor_binding.

• pattern – An fnmatch glob selecting the prims this view addresses. Mutually exclusive with prim_paths.

• device – Simulation device (e.g. "cuda:0" or "cpu"). State bindings are read/written on this device; CPU-only property bindings always use "cpu".

• prim_paths – An explicit list of fnmatch globs for the fused multi-prim binding form (create_tensor_binding(prim_paths=[...])). Mutually exclusive with pattern.

• key_aliases – Optional mapping requested_type -> created_type so a binding can be stored under a different TensorType key than the one created (e.g. a RigidObjectCollection stores rigid_body_pose under link_pose). This is an internal IsaacLab adapter for the fused-collection binding path, not a general public API: the requested key and the created binding type deliberately differ, so a caller reasoning from the visible key can get different runtime semantics. A public form would instead carry descriptor metadata (requested key, source tensor type, shape, native device, access mode); that is deferred to wheel-exposed descriptor metadata. Prefer not to rely on it outside the collection adapter.

• tensor_types – Explicit set of TensorType members to instantiate eagerly. Used only when eager is set; defaults to every applicable type.

• eager – If True, create bindings up front and raise if none could be created. Defaults to False (lazy: bindings are created on first access).

Miscellaneous:

OvPhysxViewError	Base class for all errors raised by OvPhysxView.
UnknownAttribute	The attribute name does not resolve to an addressable TensorType.
ReadOnlyAttribute	A write was attempted on a read-only attribute.
AttributeUnavailable	No binding could be created for the attribute on this view's prims.
ShapeMismatch	A supplied buffer does not match the binding's element count.
DtypeMismatch	A supplied buffer does not use the binding-reported DLPack scalar dtype.
DeviceMismatch	A supplied buffer is on a different device than the binding requires.

Methods:

__init__(physx[, pattern, device, ...])
close()	Destroy cached bindings before the OVPhysX runtime is released.
get_attribute(name, *[, out])	Read the full attribute tensor.
read_into(name, dst)	Fill dst in place from the attribute binding (zero-copy).
set_attribute(name, values, *[, indices, mask])	Write a full attribute tensor; indices/mask select which rows apply.
binding_for(name)	Return the underlying TensorBinding for an attribute, creating it on first use.
try_binding_for(name)	Like binding_for(), but return None instead of raising when the attribute is valid yet not available for this view's prims (e.g. tendon types on a tendon-less articulation, or a not-yet-created optional binding).
has_attribute(name)	Return whether name is a valid attribute name (resolves to a TensorType).

Attributes:

attribute_names	Every valid attribute name (the full TensorType vocabulary).
available_attributes	Names with a live binding instantiated for this view's prims.
count	Number of prims matched by this view.
prim_paths	USD paths of the prims matched by this view.
dof_names	Per-articulation DOF names (articulation views only).
body_names	Per-articulation body (link) names (articulation views only).
joint_names	Per-articulation joint names (articulation views only).
dof_count	Number of DOFs per articulation (articulation views only).
body_count	Number of bodies (links) per articulation (articulation views only).
joint_count	Number of joints per articulation (articulation views only).
is_fixed_base	Whether the articulation has a fixed base (articulation views only).
fixed_tendon_count	Number of fixed tendons per articulation (articulation views only).
spatial_tendon_count	Number of spatial tendons per articulation (articulation views only).

exception OvPhysxViewError

Bases: RuntimeError

Base class for all errors raised by OvPhysxView.

exception UnknownAttribute

Bases: OvPhysxViewError

The attribute name does not resolve to an addressable TensorType.

exception ReadOnlyAttribute

Bases: OvPhysxViewError

A write was attempted on a read-only attribute.

exception AttributeUnavailable

Bases: OvPhysxViewError

No binding could be created for the attribute on this view’s prims.

exception ShapeMismatch

Bases: OvPhysxViewError

A supplied buffer does not match the binding’s element count.

exception DtypeMismatch

Bases: OvPhysxViewError

A supplied buffer does not use the binding-reported DLPack scalar dtype.

exception DeviceMismatch

Bases: OvPhysxViewError

A supplied buffer is on a different device than the binding requires.

__init__(physx: _PhysXLike, pattern: str | None = None, device: str = 'cpu', *, prim_paths: list[str] | None = None, key_aliases: dict[Any, Any] | None = None, tensor_types: list[Any] | None = None, eager: bool = False) → None

close() → None

Destroy cached bindings before the OVPhysX runtime is released.

get_attribute(name: str | Any, *, out: wp.array | None = None) → wp.array

Read the full attribute tensor.

Reads are full-array (the wheel exposes no selective read); index into the returned tensor for a subset.

Parameters:

• name – Lowercased TensorType name or the member itself.

• out – Optional destination buffer to fill (must be on the binding’s native device and match its element count). If omitted, a freshly allocated warp.array on the native device is returned.

Returns:

A warp.array holding the attribute values, on the attribute’s native device – cpu for CPU-only property types even on a GPU sim (see is_cpu_only()). When out is omitted this is a fresh, caller-owned array; its dtype is the attribute’s structured Warp dtype when it has one (e.g. wp.transformf for poses, wp.spatial_vectorf for velocities). Otherwise, a flat array matching the binding shape is allocated with the Warp scalar dtype resolved from the binding’s DLPack metadata (see _ATTR_DTYPE).

read_into(name: str | Any, dst: warp.array) → None

Fill dst in place from the attribute binding (zero-copy).

dst may be a structured-dtype buffer (e.g. wp.transformf); it is read through a binding-scalar reinterpret view that matches the binding’s flat shape, so the structured GPU/CPU buffer is filled directly with no extra copy. This is the path the asset data containers use. The reinterpret view for a given dst is built once and reused across calls (see _read_view()) so the wheel’s object-identity read cache stays warm – callers can pass the structured buffer directly each step without maintaining their own reinterpret cache.

Parameters:

• name – Lowercased TensorType name or the member itself.

• dst – Caller-owned buffer on the binding’s native device whose element count matches the binding.

Raises:

• OvPhysxView.DeviceMismatch – If dst is not on the binding’s native device.

• OvPhysxView.DtypeMismatch – If dst’s scalar element type does not match the binding-reported DLPack scalar dtype.

• OvPhysxView.ShapeMismatch – If dst is non-contiguous or its element count does not match.

set_attribute(name: str | Any, values: wp.array, *, indices: wp.array | None = None, mask: wp.array | None = None) → None

Write a full attribute tensor; indices/mask select which rows apply.

values may be a structured-dtype buffer read through a binding-reported scalar dtype reinterpret view. If both indices and mask are given, mask wins and the wheel emits a UserWarning – this view forwards both verbatim to TensorBinding.write and does not implement the precedence itself.

Parameters:

• name – Lowercased TensorType name or the member itself.

• values – Source buffer on the binding’s native device, matching its element count.

• indices – Optional integer row indices to write.

• mask – Optional boolean row mask to write.

Raises:

• OvPhysxView.ReadOnlyAttribute – If the attribute is read-only.

• OvPhysxView.DeviceMismatch – If values is not on the binding’s native device.

• OvPhysxView.DtypeMismatch – If values’ scalar element type does not match the binding-reported DLPack scalar dtype.

• OvPhysxView.ShapeMismatch – If values is non-contiguous or its element count does not match.

binding_for(name: str | Any) → _BindingLike

Return the underlying TensorBinding for an attribute, creating it on first use.

This is a raw escape hatch for asset-internal binding management: the returned binding’s read/write bypass the view’s device, dtype-reinterpret, shape, and read-only guards. Prefer get_attribute() / read_into() / set_attribute() unless you are deliberately managing bindings directly.

try_binding_for(name: str | Any) → _BindingLike | None

Like binding_for(), but return None instead of raising when the attribute is valid yet not available for this view’s prims (e.g. tendon types on a tendon-less articulation, or a not-yet-created optional binding).

An invalid name still raises UnknownAttribute – that is a programming error, not an availability question. Use this for the asset’s binding or None pattern over optional bindings.

property attribute_names: list[str]

Every valid attribute name (the full TensorType vocabulary).

This is name validity, not availability for this view’s prims – a rigid-body view still lists "articulation_*" names. Use available_attributes for what is actually instantiated.

Note

A listed name is not a promise of binding availability or supported DLPack dtype metadata. Those are validated when the view creates and accesses the binding.

property available_attributes: list[str]

Names with a live binding instantiated for this view’s prims.

has_attribute(name: str | Any) → bool

Return whether name is a valid attribute name (resolves to a TensorType).

This checks name validity for any view, not availability for these prims: it can return True for a name whose binding does not apply to this view’s prims (in which case get_attribute() raises AttributeUnavailable). It likewise does not promise binding availability or supported DLPack dtype metadata.

property count: int

Number of prims matched by this view.

property prim_paths: list[str]

USD paths of the prims matched by this view.

property dof_names: list[str]

Per-articulation DOF names (articulation views only).

property body_names: list[str]

Per-articulation body (link) names (articulation views only).

property joint_names: list[str]

Per-articulation joint names (articulation views only).

property dof_count: int

Number of DOFs per articulation (articulation views only).

property body_count: int

Number of bodies (links) per articulation (articulation views only).

property joint_count: int

Number of joints per articulation (articulation views only).

property is_fixed_base: bool

Whether the articulation has a fixed base (articulation views only).

property fixed_tendon_count: int

Number of fixed tendons per articulation (articulation views only).

property spatial_tendon_count: int

Number of spatial tendons per articulation (articulation views only).