isaaclab.scene_data

isaaclab.scene_data#

Sub-package containing the scene data provider and backend interface.

The SceneDataProvider bridges physics simulation backends and the consumers that read scene transforms (renderers and visualizers). Physics backends implement SceneDataBackend to expose their current transforms in one of the SceneDataFormat Warp struct variants; the provider converts and remaps them on demand for each consumer.

This package is deliberately separate from isaaclab.scene so that physics backends (isaaclab_physx, isaaclab_newton) can subclass SceneDataBackend without pulling isaaclab.scene into the AppLauncher pre-launch import chain.

Classes

`SceneDataProvider`
`SceneDataBackend`
`SceneDataFormat`	Warp struct variants describing the transform layouts that a `SceneDataBackend` may publish to consumers.

Scene Data Provider#

class isaaclab.scene_data.SceneDataProvider[source]#

Bases: object

Methods:

`__init__`(backend)	Initialize the scene data provider.
`set_interactive_scene`(scene)	Attach the active interactive scene for scene-owned sensor discovery.
`get_interactive_scene`()	Return the registered interactive scene, if available.
`get_camera_sensors`()	Return Isaac Lab camera sensors keyed by scene sensor name.
`get_contact_sensors`()	Return Isaac Lab contact sensors keyed by scene sensor name.
`get_usd_stage`()	Return the USD stage for callers using the older method-style API.
`get_camera_transforms`()	Per-camera, per-environment world transforms discovered from USD.
`get_transforms`(output[, mapping, ...])	Convert sim backend transforms into the requested output format.
`init_output`(output)	Allocate any uninitialized fields in `output` with empty Warp arrays.
`create_mapping`(paths)	Create an index mapping from sim backend transforms to desired output ordering.
`create_geometry_mapping`(paths, particle_offsets)	Create a mapping from backend geometry entities to consumer particle offsets.
`get_points`(output[, mapping, allow_passthrough])	Copy sim backend geometry points into `output`.

Attributes:

`transform_count`	Number of transforms available from the sim backend.
`usd_stage`	Pixar `Usd.Stage` for visualizers and renderers that walk USD.
`num_envs`	Number of environments discovered from `/World/envs/env_<id>` prims.
`point_count`	Number of geometry points available from the sim backend.

__init__(backend: SceneDataBackend)[source]#

Initialize the scene data provider.

Parameters:: backend¶ – The simulation backend that supplies raw transform data.

set_interactive_scene(scene: Any) → None[source]#: Attach the active interactive scene for scene-owned sensor discovery.

get_interactive_scene() → Any | None[source]#: Return the registered interactive scene, if available.

get_camera_sensors() → dict[str, Any][source]#: Return Isaac Lab camera sensors keyed by scene sensor name.

get_contact_sensors() → dict[str, Any][source]#: Return Isaac Lab contact sensors keyed by scene sensor name.

property transform_count: int#: Number of transforms available from the sim backend.

property usd_stage: Usd.Stage | None#

Pixar Usd.Stage for visualizers and renderers that walk USD.

Resolves to isaaclab.sim.SimulationContext.stage, falling back to omni.usd.get_context().get_stage() when the simulation context has no cached stage. Returns None on Newton-only headless runs without a USD stage.

get_usd_stage() → Usd.Stage | None[source]#: Return the USD stage for callers using the older method-style API.

property num_envs: int#

Number of environments discovered from /World/envs/env_<id> prims.

Cached on first call. Returns 0 when no USD stage is available or when no /World/envs/env_<id> prims exist.

get_camera_transforms() → dict[str, Any] | None[source]#

Per-camera, per-environment world transforms discovered from USD.

Returns:: Dictionary with keys order (list of template prim paths using env_%d), positions and orientations (per-camera, per-env lists, with None for absent envs), and num_envs. Returns None when no USD stage is available.

get_transforms(output: SceneDataFormat.Vec3_Quat | SceneDataFormat.Transform | SceneDataFormat.Matrix44 | SceneDataFormat.Vec3_Matrix33, mapping: wp.array(dtype=wp.int32) | None = None, allow_passthrough: bool = True) → bool[source]#

Convert sim backend transforms into the requested output format.

When the backend’s native format matches output, data is either passed through by reference (allow_passthrough=True) or deep-copied. Otherwise a Warp conversion kernel is launched to transform the data, applying mapping to reorder the output if provided.

Parameters:

output¶ – A pre-allocated SceneDataFormat struct that determines the target format. Uninitialized (None) fields are allocated automatically when a conversion kernel is needed.
mapping¶ – Optional index remapping array produced by create_mapping(). When None, input and output indices are identical.
allow_passthrough¶ – If True and the formats already match, the output struct’s fields are set to reference the input arrays directly (zero-copy). If False, the data is always copied.

Returns:

True if the conversion succeeded, False if no suitable conversion kernel exists for the input/output format pair.

init_output(output: Vec3_Quat | Transform | Matrix44 | Vec3_Matrix33)[source]#

Allocate any uninitialized fields in output with empty Warp arrays.

Only fields that are currently None are allocated; already-initialized fields are left untouched.

Parameters:: output¶ – A SceneDataFormat struct whose None-valued fields will be replaced with empty arrays of length transform_count.

create_mapping(paths: list[str | None]) → wp.array(dtype=wp.int32) | None[source]#

Create an index mapping from sim backend transforms to desired output ordering.

For each transform in the sim backend, the resulting array stores the index into paths where that transform should be written. Transforms whose path does not appear in paths (or maps to None) receive an index of -1 and are skipped during conversion.

Parameters:: paths¶ – Desired output ordering expressed as prim paths. Use None for slots that should not receive any transform.
Returns:: A Warp int32 array of length transform_count containing the remapped indices, or None if the sim backend provides no transform paths or if no mapping is needed.

create_geometry_mapping(paths: list[str | None], particle_offsets: list[int]) → wp.array(dtype=wp.int32) | None[source]#

Create a mapping from backend geometry entities to consumer particle offsets.

For each geometry entity in the sim backend, the resulting array stores the destination particle offset in the consumer buffer. Entities whose path does not appear in paths receive -1 and are skipped during copy.

Parameters:

paths¶ – Desired consumer entity paths in particle-offset order.
particle_offsets¶ – Particle offset in the consumer buffer for each paths entry.

Returns:

A Warp int32 array of length len(geometry_paths) containing destination particle offsets, or None when no geometry is available or every entity maps identically in order.

get_points(output: SceneDataFormat.Points, mapping: wp.array(dtype=wp.int32) | None = None, allow_passthrough: bool = True) → bool[source]#

Copy sim backend geometry points into output.

Parameters:

output¶ – Pre-allocated SceneDataFormat.Points buffer (typically aliased to shadow particle_q).
mapping¶ – Optional destination particle-offset array from create_geometry_mapping().
allow_passthrough¶ – When True and no mapping is needed, alias output.points directly to the backend buffer.

Returns:

True when points were copied or passed through, False when the backend exposes no geometry.

property point_count: int#: Number of geometry points available from the sim backend.

Scene Data Backend#

class isaaclab.scene_data.SceneDataBackend[source]#

Bases: object

Attributes:

`transforms`	Return the sim backends transforms as one of the SceneDataFormat structs.
`transform_count`	Return the number of transforms in the sim backend.
`transform_paths`	Return the paths for each transform.
`points`	Return deformable or particle geometry as flat world-space positions.
`point_count`	Return the number of points in `points`.
`geometry_paths`	Return one USD prim path per geometry entity (deformable body instance).
`geometry_counts`	Return the unpadded point count for each geometry entity.

property transforms: Vec3_Quat | Transform | Matrix44 | Vec3_Matrix33#: Return the sim backends transforms as one of the SceneDataFormat structs.

property transform_count: int#: Return the number of transforms in the sim backend.

property transform_paths: list[str]#: Return the paths for each transform.

property points: Points#: Return deformable or particle geometry as flat world-space positions.

property point_count: int#: Return the number of points in points.

property geometry_paths: list[str]#: Return one USD prim path per geometry entity (deformable body instance).

property geometry_counts: list[int]#: Return the unpadded point count for each geometry entity.

class isaaclab.scene_data.SceneDataFormat[source]#

Bases: object

Warp struct variants describing the transform layouts that a SceneDataBackend may publish to consumers.

Classes:

`Vec3_Quat`	Separate position and quaternion arrays.
`Vec3_Matrix33`	Separate position and rotation-matrix arrays.
`Transform`	Packed warp transforms (position + quaternion).
`Matrix44`	Packed 4x4 homogeneous transform matrices.
`Points`	Flat world-space nodal or particle positions.