omni.isaac.lab.scene#

Sub-package containing an interactive scene definition.

A scene is a collection of entities (e.g., terrain, articulations, sensors, lights, etc.) that can be added to the simulation. However, only a subset of these entities are of direct interest for the user to interact with. For example, the user may want to interact with a robot in the scene, but not with the terrain or the lights. For this reason, we integrate the different entities into a single class called InteractiveScene.

The interactive scene performs the following tasks:

  1. It parses the configuration class InteractiveSceneCfg to create the scene. This configuration class is inherited by the user to add entities to the scene.

  2. It clones the entities based on the number of environments specified by the user.

  3. It clubs the entities into different groups based on their type (e.g., articulations, sensors, etc.).

  4. It provides a set of methods to unify the common operations on the entities in the scene (e.g., resetting internal buffers, writing buffers to simulation and updating buffers from simulation).

The interactive scene can be passed around to different modules in the framework to perform different tasks. For instance, computing the observations based on the state of the scene, or randomizing the scene, or applying actions to the scene. All these are handled by different “managers” in the framework. Please refer to the omni.isaac.lab.managers sub-package for more details.

Classes

InteractiveScene

A scene that contains entities added to the simulation.

InteractiveSceneCfg

Configuration for the interactive scene.

interactive Scene#

class omni.isaac.lab.scene.InteractiveScene[source]#

Bases: object

A scene that contains entities added to the simulation.

The interactive scene parses the InteractiveSceneCfg class to create the scene. Based on the specified number of environments, it clones the entities and groups them into different categories (e.g., articulations, sensors, etc.).

Cloning can be performed in two ways:

  • For tasks where all environments contain the same assets, a more performant cloning paradigm can be used to allow for faster environment creation. This is specified by the replicate_physics flag.

    scene = InteractiveScene(cfg=InteractiveSceneCfg(replicate_physics=True))
    
  • For tasks that require having separate assets in the environments, replicate_physics would have to be set to False, which will add some costs to the overall startup time.

    scene = InteractiveScene(cfg=InteractiveSceneCfg(replicate_physics=False))
    

Each entity is registered to scene based on its name in the configuration class. For example, if the user specifies a robot in the configuration class as follows:

from omni.isaac.lab.scene import InteractiveSceneCfg
from omni.isaac.lab.utils import configclass

from omni.isaac.lab_assets.anymal import ANYMAL_C_CFG

@configclass
class MySceneCfg(InteractiveSceneCfg):

    robot = ANYMAL_C_CFG.replace(prim_path="{ENV_REGEX_NS}/Robot")

Then the robot can be accessed from the scene as follows:

from omni.isaac.lab.scene import InteractiveScene

# create 128 environments
scene = InteractiveScene(cfg=MySceneCfg(num_envs=128))

# access the robot from the scene
robot = scene["robot"]
# access the robot based on its type
robot = scene.articulations["robot"]

If the InteractiveSceneCfg class does not include asset entities, the cloning process can still be triggered if assets were added to the stage outside of the InteractiveScene class:

scene = InteractiveScene(cfg=InteractiveSceneCfg(num_envs=128, replicate_physics=True))
scene.clone_environments()

Note

It is important to note that the scene only performs common operations on the entities. For example, resetting the internal buffers, writing the buffers to the simulation and updating the buffers from the simulation. The scene does not perform any task specific to the entity. For example, it does not apply actions to the robot or compute observations from the robot. These tasks are handled by different modules called “managers” in the framework. Please refer to the omni.isaac.lab.managers sub-package for more details.

Methods:

__init__(cfg)

Initializes the scene.

clone_environments([copy_from_source])

Creates clones of the environment /World/envs/env_0.

filter_collisions([global_prim_paths])

Filter environments collisions.

reset([env_ids])

Resets the scene entities.

write_data_to_sim()

Writes the data of the scene entities to the simulation.

update(dt)

Update the scene entities.

keys()

Returns the keys of the scene entities.

Attributes:

physics_scene_path

Search the stage for the physics scene

physics_dt

The physics timestep of the scene.

device

The device on which the scene is created.

env_ns

The namespace /World/envs in which all environments created.

env_regex_ns

The namespace /World/envs/env_.* in which all environments created.

num_envs

The number of environments handled by the scene.

env_origins

The origins of the environments in the scene.

terrain

The terrain in the scene.

articulations

A dictionary of articulations in the scene.

rigid_objects

A dictionary of rigid objects in the scene.

sensors

A dictionary of the sensors in the scene, such as cameras and contact reporters.

extras

A dictionary of miscellaneous simulation objects that neither inherit from assets nor sensors.

__init__(cfg: InteractiveSceneCfg)[source]#

Initializes the scene.

Parameters:

cfg – The configuration class for the scene.

clone_environments(copy_from_source: bool = False)[source]#

Creates clones of the environment /World/envs/env_0.

Parameters:
  • copy_from_source – (bool): If set to False, clones inherit from /World/envs/env_0 and mirror its changes.

  • True (If) –

  • time (clones are independent copies of the source prim and won't reflect its changes (start-up) –

  • False. (may increase). Defaults to) –

filter_collisions(global_prim_paths: list[str] | None = None)[source]#

Filter environments collisions.

Disables collisions between the environments in /World/envs/env_.* and enables collisions with the prims in global prim paths (e.g. ground plane).

Parameters:

global_prim_paths – A list of global prim paths to enable collisions with. Defaults to None, in which case no global prim paths are considered.

property physics_scene_path#

Search the stage for the physics scene

property physics_dt: float#

The physics timestep of the scene.

property device: str#

The device on which the scene is created.

property env_ns: str#

The namespace /World/envs in which all environments created.

The environments are present w.r.t. this namespace under “env_{N}” prim, where N is a natural number.

property env_regex_ns: str#

The namespace /World/envs/env_.* in which all environments created.

property num_envs: int#

The number of environments handled by the scene.

property env_origins: torch.Tensor#

The origins of the environments in the scene. Shape is (num_envs, 3).

property terrain: TerrainImporter | None#

The terrain in the scene. If None, then the scene has no terrain.

Note

We treat terrain separate from extras since terrains define environment origins and are handled differently from other miscellaneous entities.

property articulations: dict[str, omni.isaac.lab.assets.articulation.articulation.Articulation]#

A dictionary of articulations in the scene.

property rigid_objects: dict[str, omni.isaac.lab.assets.rigid_object.rigid_object.RigidObject]#

A dictionary of rigid objects in the scene.

property sensors: dict[str, omni.isaac.lab.sensors.sensor_base.SensorBase]#

A dictionary of the sensors in the scene, such as cameras and contact reporters.

property extras: dict[str, omni.isaac.core.prims.XFormPrimView]#

A dictionary of miscellaneous simulation objects that neither inherit from assets nor sensors.

The keys are the names of the miscellaneous objects, and the values are the XFormPrimView of the corresponding prims.

As an example, lights or other props in the scene that do not have any attributes or properties that you want to alter at runtime can be added to this dictionary.

Note

These are not reset or updated by the scene. They are mainly other prims that are not necessarily handled by the interactive scene, but are useful to be accessed by the user.

reset(env_ids: Sequence[int] | None = None)[source]#

Resets the scene entities.

Parameters:

env_ids – The indices of the environments to reset. Defaults to None (all instances).

write_data_to_sim()[source]#

Writes the data of the scene entities to the simulation.

update(dt: float) None[source]#

Update the scene entities.

Parameters:

dt – The amount of time passed from last update() call.

keys() list[str][source]#

Returns the keys of the scene entities.

Returns:

The keys of the scene entities.

class omni.isaac.lab.scene.InteractiveSceneCfg[source]#

Configuration for the interactive scene.

The users can inherit from this class to add entities to their scene. This is then parsed by the InteractiveScene class to create the scene.

Note

The adding of entities to the scene is sensitive to the order of the attributes in the configuration. Please make sure to add the entities in the order you want them to be added to the scene. The recommended order of specification is terrain, physics-related assets (articulations and rigid bodies), sensors and non-physics-related assets (lights).

For example, to add a robot to the scene, the user can create a configuration class as follows:

import omni.isaac.lab.sim as sim_utils
from omni.isaac.lab.assets import AssetBaseCfg
from omni.isaac.lab.scene import InteractiveSceneCfg
from omni.isaac.lab.sensors.ray_caster import GridPatternCfg, RayCasterCfg
from omni.isaac.lab.utils import configclass

from omni.isaac.lab_assets.anymal import ANYMAL_C_CFG

@configclass
class MySceneCfg(InteractiveSceneCfg):

    # terrain - flat terrain plane
    terrain = TerrainImporterCfg(
        prim_path="/World/ground",
        terrain_type="plane",
    )

    # articulation - robot 1
    robot_1 = ANYMAL_C_CFG.replace(prim_path="{ENV_REGEX_NS}/Robot_1")
    # articulation - robot 2
    robot_2 = ANYMAL_C_CFG.replace(prim_path="{ENV_REGEX_NS}/Robot_2")
    robot_2.init_state.pos = (0.0, 1.0, 0.6)

    # sensor - ray caster attached to the base of robot 1 that scans the ground
    height_scanner = RayCasterCfg(
        prim_path="{ENV_REGEX_NS}/Robot_1/base",
        offset=RayCasterCfg.OffsetCfg(pos=(0.0, 0.0, 20.0)),
        attach_yaw_only=True,
        pattern_cfg=GridPatternCfg(resolution=0.1, size=[1.6, 1.0]),
        debug_vis=True,
        mesh_prim_paths=["/World/ground"],
    )

    # extras - light
    light = AssetBaseCfg(
        prim_path="/World/light",
        spawn=sim_utils.DistantLightCfg(intensity=3000.0, color=(0.75, 0.75, 0.75)),
        init_state=AssetBaseCfg.InitialStateCfg(pos=(0.0, 0.0, 500.0)),
    )

Attributes:

num_envs

Number of environment instances handled by the scene.

env_spacing

Spacing between environments.

lazy_sensor_update

Whether to update sensors only when they are accessed.

replicate_physics

Enable/disable replication of physics schemas when using the Cloner APIs.

num_envs: int#

Number of environment instances handled by the scene.

env_spacing: float#

Spacing between environments.

This is the default distance between environment origins in the scene. Used only when the number of environments is greater than one.

lazy_sensor_update: bool#

Whether to update sensors only when they are accessed. Default is True.

If true, the sensor data is only updated when their attribute data is accessed. Otherwise, the sensor data is updated every time sensors are updated.

replicate_physics: bool#

Enable/disable replication of physics schemas when using the Cloner APIs. Default is True.

If True, the simulation will have the same asset instances (USD prims) in all the cloned environments. Internally, this ensures optimization in setting up the scene and parsing it via the physics stage parser.

If False, the simulation allows having separate asset instances (USD prims) in each environment. This flexibility comes at a cost of slowdowns in setting up and parsing the scene.

Note

Optimized parsing of certain prim types (such as deformable objects) is not currently supported by the physics engine. In these cases, this flag needs to be set to False.