Adds configuration classes for spawning different assets at prim paths

docs/source/api/lab/omni.isaac.lab.sim.spawners.rst

@@ -13,6 +13,7 @@
     sensors
     from_files
     materials
+    wrappers
 
   .. rubric:: Classes
 
@@ -302,3 +303,27 @@ Physical Materials
 .. autoclass:: DeformableBodyMaterialCfg
     :members:
     :exclude-members: __init__, func
+
+Wrappers
+--------
+
+.. automodule:: omni.isaac.lab.sim.spawners.wrappers
+
+  .. rubric:: Classes
+
+  .. autosummary::
+
+    MultiAssetSpawnerCfg
+    MultiUsdFileCfg
+
+.. autofunction:: spawn_multi_asset
+
+.. autoclass:: MultiAssetSpawnerCfg
+    :members:
+    :exclude-members: __init__, func
+
+.. autofunction:: spawn_multi_usd_file
+
+.. autoclass:: MultiUsdFileCfg
+    :members:
+    :exclude-members: __init__, func

docs/source/how-to/index.rst

@@ -36,6 +36,17 @@ a fixed base robot. This guide goes over the various considerations and steps to
 
     make_fixed_prim
 
+Spawning Multiple Assets
+------------------------
+
+This guide explains how to import and configure different assets in each environment. This is
+useful when you want to create diverse environments with different objects.
+
+.. toctree::
+    :maxdepth: 1
+
+    multi_asset_spawning
+
 Saving Camera Output
 --------------------
 

docs/source/how-to/multi_asset_spawning.rst

@@ -0,0 +1,101 @@
+Spawning Multiple Assets
+========================
+
+.. currentmodule:: omni.isaac.lab
+
+Typical, spawning configurations (introduced in the :ref:`tutorial-spawn-prims` tutorial) copy the same
+asset (or USD primitive) across the different resolved prim paths from the expressions.
+For instance, if the user specifies to spawn the asset at "/World/Table\_.*/Object", the same
+asset is created at the paths "/World/Table_0/Object", "/World/Table_1/Object" and so on.
+
+However, at times, it might be desirable to spawn different assets under the prim paths to
+ensure a diversity in the simulation. This guide describes how to create different assets under
+each prim path using the spawning functionality.
+
+The sample script ``multi_asset.py`` is used as a reference, located in the
+``IsaacLab/source/standalone/demos`` directory.
+
+.. dropdown:: Code for multi_asset.py
+   :icon: code
+
+   .. literalinclude:: ../../../source/standalone/demos/multi_asset.py
+      :language: python
+      :emphasize-lines: 101-123, 130-149
+      :linenos:
+
+This script creates multiple environments, where each environment has a rigid object that is either a cone,
+a cube, or a sphere, and an articulation that is either the ANYmal-C or ANYmal-D robot.
+
+.. image:: ../_static/demos/multi_asset.jpg
+  :width: 100%
+  :alt: result of multi_asset.py
+
+Using Multi-Asset Spawning Functions
+------------------------------------
+
+It is possible to spawn different assets and USDs in each environment using the spawners
+:class:`~sim.spawners.wrappers.MultiAssetSpawnerCfg` and :class:`~sim.spawners.wrappers.MultiUsdFileCfg`:
+
+* We set the spawn configuration in :class:`~assets.RigidObjectCfg` to be
+  :class:`~sim.spawners.wrappers.MultiAssetSpawnerCfg`:
+
+  .. literalinclude:: ../../../source/standalone/demos/multi_asset.py
+     :language: python
+     :lines: 99-125
+     :dedent:
+
+  This function allows you to define a list of different assets that can be spawned as rigid objects.
+  When :attr:`~sim.spawners.wrappers.MultiAssetSpawnerCfg.random_choice` is set to True, one asset from the list
+  is randomly selected and spawned at the specified prim path.
+
+* Similarly, we set the spawn configuration in :class:`~assets.ArticulationCfg` to be
+  :class:`~sim.spawners.wrappers.MultiUsdFileCfg`:
+
+  .. literalinclude:: ../../../source/standalone/demos/multi_asset.py
+     :language: python
+     :lines: 128-161
+     :dedent:
+
+  Similar to before, this configuration allows the selection of different USD files representing articulated assets.
+
+
+Things to Note
+--------------
+
+Similar asset structuring
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While spawning and handling multiple assets using the same physics interface (the rigid object or articulation classes),
+it is essential to have the assets at all the prim locations follow a similar structure. In case of an articulation,
+this means that they all must have the same number of links and joints, the same number of collision bodies and
+the same names for them. If that is not the case, the physics parsing of the prims can get affected and fail.
+
+The main purpose of this functionality is to enable the user to create randomized versions of the same asset,
+for example robots with different link lengths, or rigid objects with different collider shapes.
+
+Disabling physics replication in interactive scene
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, the flag :attr:`scene.InteractiveScene.replicate_physics` is set to True. This flag informs the physics
+engine that the simulation environments are copies of one another so it just needs to parse the first environment
+to understand the entire simulation scene. This helps speed up the simulation scene parsing.
+
+However, in the case of spawning different assets in different environments, this assumption does not hold
+anymore. Hence the flag :attr:`scene.InteractiveScene.replicate_physics` must be disabled.
+
+.. literalinclude:: ../../../source/standalone/demos/multi_asset.py
+   :language: python
+   :lines: 221-224
+   :dedent:
+
+The Code Execution
+------------------
+
+To execute the script with multiple environments and randomized assets, use the following command:
+
+.. code-block:: bash
+
+  ./isaaclab.sh -p source/standalone/demos/multi_asset.py --num_envs 2048
+
+This command runs the simulation with 2048 environments, each with randomly selected assets.
+To stop the simulation, you can close the window, or press ``Ctrl+C`` in the terminal.

docs/source/overview/showroom.rst

@@ -77,7 +77,7 @@ A few quick showroom scripts to run and checkout:
       :width: 100%
       :alt: Dexterous hands in Isaac Lab
 
--  Spawn procedurally generated terrains with different configurations:
+-  Spawn different deformable (soft) bodies and let them fall from a height:
 
    .. tab-set::
       :sync-group: os
@@ -87,20 +87,20 @@ A few quick showroom scripts to run and checkout:
 
          .. code:: bash
 
-            ./isaaclab.sh -p source/standalone/demos/procedural_terrain.py
+            ./isaaclab.sh -p source/standalone/demos/deformables.py
 
       .. tab-item:: :icon:`fa-brands fa-windows` Windows
          :sync: windows
 
          .. code:: batch
 
-            isaaclab.bat -p source\standalone\demos\procedural_terrain.py
+            isaaclab.bat -p source\standalone\demos\deformables.py
 
-   .. image:: ../_static/demos/procedural_terrain.jpg
+   .. image:: ../_static/demos/deformables.jpg
       :width: 100%
-      :alt: Procedural Terrains in Isaac Lab
+      :alt: Deformable primitive-shaped objects in Isaac Lab
 
--  Spawn different deformable (soft) bodies and let them fall from a height:
+-  Use the interactive scene and spawn varying assets in individual environments:
 
    .. tab-set::
       :sync-group: os
@@ -110,20 +110,43 @@ A few quick showroom scripts to run and checkout:
 
          .. code:: bash
 
-            ./isaaclab.sh -p source/standalone/demos/deformables.py
+            ./isaaclab.sh -p source/standalone/demos/multi_asset.py
 
       .. tab-item:: :icon:`fa-brands fa-windows` Windows
          :sync: windows
 
          .. code:: batch
 
-            isaaclab.bat -p source\standalone\demos\deformables.py
+            isaaclab.bat -p source\standalone\demos\multi_asset.py
 
-   .. image:: ../_static/demos/deformables.jpg
+   .. image:: ../_static/demos/multi_asset.jpg
       :width: 100%
-      :alt: Deformable primitive-shaped objects in Isaac Lab
+      :alt: Multiple assets managed through the same simulation handles
+
+-  Create and spawn procedurally generated terrains with different configurations:
+
+   .. tab-set::
+      :sync-group: os
+
+      .. tab-item:: :icon:`fa-brands fa-linux` Linux
+         :sync: linux
+
+         .. code:: bash
+
+            ./isaaclab.sh -p source/standalone/demos/procedural_terrain.py
+
+      .. tab-item:: :icon:`fa-brands fa-windows` Windows
+         :sync: windows
+
+         .. code:: batch
+
+            isaaclab.bat -p source\standalone\demos\procedural_terrain.py
+
+   .. image:: ../_static/demos/procedural_terrain.jpg
+      :width: 100%
+      :alt: Procedural Terrains in Isaac Lab
 
--  Spawn multiple markers that are useful for visualizations:
+-  Define multiple markers that are useful for visualizations:
 
    .. tab-set::
       :sync-group: os

source/extensions/omni.isaac.lab/config/extension.toml

@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.24.20"
+version = "0.25.0"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

source/extensions/omni.isaac.lab/docs/CHANGELOG.rst

@@ -1,6 +1,16 @@
 Changelog
 ---------
 
+0.25.0 (2024-10-06)
+~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added configuration classes for spawning assets from a list of individual asset configurations randomly
+  at the specified prim paths.
+
+
 0.24.20 (2024-10-07)
 ~~~~~~~~~~~~~~~~~~~~
 

source/extensions/omni.isaac.lab/omni/isaac/lab/scene/interactive_scene.py

@@ -166,6 +166,18 @@ def clone_environments(self, copy_from_source: bool = False):
             If True, clones are independent copies of the source prim and won't reflect its changes (start-up time
             may increase). Defaults to False.
         """
+        # check if user spawned different assets in individual environments
+        # this flag will be None if no multi asset is spawned
+        carb_settings_iface = carb.settings.get_settings()
+        has_multi_assets = carb_settings_iface.get("/isaaclab/spawn/multi_assets")
+        if has_multi_assets and self.cfg.replicate_physics:
+            carb.log_warn(
+                "Varying assets might have been spawned under different environments."
+                " However, the replicate physics flag is enabled in the 'InteractiveScene' configuration."
+                " This may adversely affect PhysX parsing. We recommend disabling this property."
+            )
+
+        # clone the environment
         env_origins = self.cloner.clone(
             source_prim_path=self.env_prim_paths[0],
             prim_paths=self.env_prim_paths,
@@ -187,9 +199,6 @@ def filter_collisions(self, global_prim_paths: list[str] | None = None):
             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.
         """
-        # obtain the current physics scene
-        physics_scene_prim_path = self.physics_scene_path
-
         # validate paths in global prim paths
         if global_prim_paths is None:
             global_prim_paths = []
@@ -203,7 +212,7 @@ def filter_collisions(self, global_prim_paths: list[str] | None = None):
 
         # filter collisions within each environment instance
         self.cloner.filter_collisions(
-            physics_scene_prim_path,
+            self.physics_scene_path,
             "/World/collisions",
             self.env_prim_paths,
             global_paths=self._global_prim_paths,
@@ -224,14 +233,16 @@ def __str__(self) -> str:
     """
 
     @property
-    def physics_scene_path(self):
-        """Search the stage for the physics scene"""
+    def physics_scene_path(self) -> str:
+        """The path to the USD Physics Scene."""
         if self._physics_scene_path is None:
             for prim in self.stage.Traverse():
                 if prim.HasAPI(PhysxSchema.PhysxSceneAPI):
-                    self._physics_scene_path = prim.GetPrimPath()
+                    self._physics_scene_path = prim.GetPrimPath().pathString
                     carb.log_info(f"Physics scene prim path: {self._physics_scene_path}")
                     break
+            if self._physics_scene_path is None:
+                raise RuntimeError("No physics scene found! Please make sure one exists.")
         return self._physics_scene_path
 
     @property

source/extensions/omni.isaac.lab/omni/isaac/lab/sim/spawners/__init__.py

@@ -61,3 +61,4 @@ class and the function call in a single line of code.
 from .sensors import *  # noqa: F401, F403
 from .shapes import *  # noqa: F401, F403
 from .spawner_cfg import *  # noqa: F401, F403
+from .wrappers import *  # noqa: F401, F403

source/extensions/omni.isaac.lab/omni/isaac/lab/sim/spawners/spawner_cfg.py

@@ -64,11 +64,6 @@ class SpawnerCfg:
 
     This parameter is only used when cloning prims. If False, then the asset will be inherited from
     the source prim, i.e. all USD changes to the source prim will be reflected in the cloned prims.
-
-    .. versionadded:: 2023.1
-
-        This parameter is only supported from Isaac Sim 2023.1 onwards. If you are using an older
-        version of Isaac Sim, this parameter will be ignored.
     """
 
 

source/extensions/omni.isaac.lab/omni/isaac/lab/sim/spawners/wrappers/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2022-2024, The Isaac Lab Project Developers.
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Sub-module for wrapping spawner configurations.
+
+Unlike the other spawner modules, this module provides a way to wrap multiple spawner configurations
+into a single configuration. This is useful when the user wants to spawn multiple assets based on
+different configurations.
+"""
+
+from .wrappers import spawn_multi_asset, spawn_multi_usd_file
+from .wrappers_cfg import MultiAssetSpawnerCfg, MultiUsdFileCfg