Adds a rigid body collection class (#1288)

# Description

Adds a rigid body collection class, which allows to spawn multiple
objects in each environment and access/modify the quantities with a
unified (env_ids, object_ids) API.

## Type of change

- New feature (non-breaking change which adds functionality)

## Checklist

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

Author: David Hoeller

docs/source/_static/demos/multi_asset.jpg

@@ -12,6 +12,9 @@
     RigidObject
     RigidObjectData
     RigidObjectCfg
+    RigidObjectCollection
+    RigidObjectCollectionData
+    RigidObjectCollectionCfg
     Articulation
     ArticulationData
     ArticulationCfg
@@ -51,6 +54,26 @@ Rigid Object
     :show-inheritance:
     :exclude-members: __init__, class_type
 
+Rigid Object Collection
+-----------------------
+
+.. autoclass:: RigidObjectCollection
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: RigidObjectCollectionData
+    :members:
+    :inherited-members:
+    :show-inheritance:
+    :exclude-members: __init__
+
+.. autoclass:: RigidObjectCollectionCfg
+    :members:
+    :inherited-members:
+    :show-inheritance:
+    :exclude-members: __init__, class_type
+
 Articulation
 ------------
 

docs/source/api/lab/omni.isaac.lab.assets.rst

@@ -1,16 +1,23 @@
+
 Spawning Multiple Assets
 ========================
 
 .. currentmodule:: omni.isaac.lab
 
-Typical, spawning configurations (introduced in the :ref:`tutorial-spawn-prims` tutorial) copy the same
+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.
+However, we also support multi-asset spawning with two mechanisms:
+
+1. Rigid object collections. This allows the user to spawn multiple rigid objects in each environment and access/modify
+   them with a unified API, improving performance.
+
+2. Spawning different assets under the same prim path. This allows the user to create diverse simulations, where each
+   environment has a different asset.
+
+This guide describes how to use these two mechanisms.
 
 The sample script ``multi_asset.py`` is used as a reference, located in the
 ``IsaacLab/source/standalone/demos`` directory.
@@ -20,28 +27,49 @@ The sample script ``multi_asset.py`` is used as a reference, located in the
 
    .. literalinclude:: ../../../source/standalone/demos/multi_asset.py
       :language: python
-      :emphasize-lines: 101-123, 130-149
+      :emphasize-lines: 109-131, 135-179, 184-203
       :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.
+This script creates multiple environments, where each environment has:
+
+* a rigid object collection containing a cone, a cube, and a sphere
+* a rigid object that is either a cone, a cube, or a sphere, chosen at random
+* an articulation that is either the ANYmal-C or ANYmal-D robot, chosen at random
 
 .. 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
+Rigid Object Collections
+------------------------
+
+Multiple rigid objects can be spawned in each environment and accessed/modified with a unified ``(env_ids, obj_ids)`` API.
+While the user could also create multiple rigid objects by spawning them individually, the API is more user-friendly and
+more efficient since it uses a single physics view under the hood to handle all the objects.
+
+.. literalinclude:: ../../../source/standalone/demos/multi_asset.py
+   :language: python
+   :lines: 135-179
+   :dedent:
+
+The configuration :class:`~assets.RigidObjectCollectionCfg` is used to create the collection. It's attribute :attr:`~assets.RigidObjectCollectionCfg.rigid_objects`
+is a dictionary containing :class:`~assets.RigidObjectCfg` objects. The keys serve as unique identifiers for each
+rigid object in the collection.
+
+
+Spawning different assets under the same prim path
+--------------------------------------------------
+
+It is possible to spawn different assets and USDs under the same prim path 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
+     :lines: 107-133
      :dedent:
 
   This function allows you to define a list of different assets that can be spawned as rigid objects.
@@ -53,14 +81,14 @@ It is possible to spawn different assets and USDs in each environment using the
 
   .. literalinclude:: ../../../source/standalone/demos/multi_asset.py
      :language: python
-     :lines: 128-161
+     :lines: 182-215
      :dedent:
 
   Similar to before, this configuration allows the selection of different USD files representing articulated assets.
 
 
 Things to Note
---------------
+~~~~~~~~~~~~~~
 
 Similar asset structuring
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -85,7 +113,7 @@ anymore. Hence the flag :attr:`scene.InteractiveScene.replicate_physics` must be
 
 .. literalinclude:: ../../../source/standalone/demos/multi_asset.py
    :language: python
-   :lines: 221-224
+   :lines: 280-283
    :dedent:
 
 The Code Execution

docs/source/how-to/multi_asset_spawning.rst

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

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

@@ -1,6 +1,16 @@
 Changelog
 ---------
 
+0.27.14 (2024-10-23)
+~~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added the class :class:`~omni.isaac.lab.assets.RigidObjectCollection` which allows to spawn
+  multiple objects in each environment and access/modify the quantities with a unified (env_ids, object_ids) API.
+
+
 0.27.13 (2024-10-30)
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -13,7 +23,7 @@ Added
 
 
 0.27.12 (2024-01-04)
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
 
 Removed
 ^^^^^^^

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

@@ -43,3 +43,4 @@
 from .asset_base_cfg import AssetBaseCfg
 from .deformable_object import DeformableObject, DeformableObjectCfg, DeformableObjectData
 from .rigid_object import RigidObject, RigidObjectCfg, RigidObjectData
+from .rigid_object_collection import RigidObjectCollection, RigidObjectCollectionCfg, RigidObjectCollectionData

source/extensions/omni.isaac.lab/omni/isaac/lab/assets/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) 2022-2024, The Isaac Lab Project Developers.
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Sub-module for rigid object collection."""
+
+from .rigid_object_collection import RigidObjectCollection
+from .rigid_object_collection_cfg import RigidObjectCollectionCfg
+from .rigid_object_collection_data import RigidObjectCollectionData