isaaclab.scene — Isaac Lab Documentation (original) (raw)

isaaclab.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 theisaaclab.managers sub-package for more details.

Classes

interactive Scene#

class isaaclab.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 isaaclab.scene import InteractiveSceneCfg from isaaclab.utils import configclass

from isaaclab_assets.robots.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 isaaclab.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 isaaclab.managers sub-package for more details.

Methods:

Attributes:

__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_: str_#

The path to the USD 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, isaaclab.assets.articulation.articulation.Articulation]_#

A dictionary of articulations in the scene.

property deformable_objects_: dict[str, isaaclab.assets.deformable_object.deformable_object.DeformableObject]_#

A dictionary of deformable objects in the scene.

property rigid_objects_: dict[str, isaaclab.assets.rigid_object.rigid_object.RigidObject]_#

A dictionary of rigid objects in the scene.

property rigid_object_collections_: dict[str, isaaclab.assets.rigid_object_collection.rigid_object_collection.RigidObjectCollection]_#

A dictionary of rigid object collections in the scene.

property sensors_: dict[str, isaaclab.sensors.sensor_base.SensorBase]_#

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

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

property state_: dict[str, dict[str, dict[str, torch.Tensor]]]_#

A dictionary of the state of the scene entities in the simulation world frame.

Please refer to get_state() for the format.

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.

reset_to(state: dict[str, dict[str, dict[str, torch.Tensor]]], env_ids: Sequence[int] | None = None, is_relative: bool = False)[source]#

Resets the entities in the scene to the provided state.

Parameters:

• state – The state to reset the scene entities to. Please refer to get_state() for the format.
• env_ids – The indices of the environments to reset. Defaults to None, in which case all environment instances are reset.
• is_relative – If set to True, the state is considered relative to the environment origins. Defaults to False.

get_state(is_relative: bool = False) → dict[str, dict[str, dict[str, torch.Tensor]]][source]#

Returns the state of the scene entities.

Based on the type of the entity, the state comprises of different components.

• For an articulation, the state comprises of the root pose, root velocity, and joint position and velocity.
• For a deformable object, the state comprises of the nodal position and velocity.
• For a rigid object, the state comprises of the root pose and root velocity.

The returned state is a dictionary with the following format:

{ "articulation": { "entity_1_name": { "root_pose": torch.Tensor, "root_velocity": torch.Tensor, "joint_position": torch.Tensor, "joint_velocity": torch.Tensor, }, "entity_2_name": { "root_pose": torch.Tensor, "root_velocity": torch.Tensor, "joint_position": torch.Tensor, "joint_velocity": torch.Tensor, }, }, "deformable_object": { "entity_3_name": { "nodal_position": torch.Tensor, "nodal_velocity": torch.Tensor, } }, "rigid_object": { "entity_4_name": { "root_pose": torch.Tensor, "root_velocity": torch.Tensor, } }, }

where entity_N_name is the name of the entity registered in the scene.

Parameters:

is_relative – If set to True, the state is considered relative to the environment origins. Defaults to False.

Returns:

A dictionary of the state of the scene entities.

keys() → list[str][source]#

Returns the keys of the scene entities.

Returns:

The keys of the scene entities.

class isaaclab.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 theInteractiveScene 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 isaaclab.sim as sim_utils from isaaclab.assets import AssetBaseCfg from isaaclab.scene import InteractiveSceneCfg from isaaclab.sensors.ray_caster import GridPatternCfg, RayCasterCfg from isaaclab.utils import configclass

from isaaclab_assets.robots.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_: 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.

filter_collisions_: bool_#

Enable/disable collision filtering between cloned environments. Default is True.

If True, collisions will not occur between cloned environments.

If False, the simulation will generate collisions between environments.

Note

Collisions can only be filtered automatically in direct workflows when physics replication is enabled. If replicated_physics=False and collision filtering is desired, make sure to call scene.filter_collisions().