Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds configuration classes for spawning different assets at prim paths #1164

Merged
merged 31 commits into from
Oct 9, 2024
Merged
Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
b540a5f
adds demo on multi-object
Mayankm96 Oct 4, 2024
106b267
moves randomization to its own function
Mayankm96 Oct 4, 2024
86e0946
adds wrapper for multi asset spawn
Mayankm96 Oct 4, 2024
ad15267
adds multi asset py
Mayankm96 Oct 4, 2024
f19cb63
removes version addded notice
Mayankm96 Oct 5, 2024
ab9f892
allows overriding global settings in cfg
Mayankm96 Oct 5, 2024
d919efe
adds spawning of multi usd files
Mayankm96 Oct 5, 2024
2ec63fb
combines multi usd file into multi-asset
Mayankm96 Oct 6, 2024
18ef1fd
reduces solver count
Mayankm96 Oct 6, 2024
ea64b87
renames function
Mayankm96 Oct 6, 2024
93daf30
fixes documentation
Mayankm96 Oct 6, 2024
1c2f234
adds version log
Mayankm96 Oct 6, 2024
0c9b63c
runs formatter
Mayankm96 Oct 6, 2024
33247a5
Added docs
Dhoeller19 Oct 8, 2024
07710f8
Merge branch 'main' into feature/multi-object
Dhoeller19 Oct 8, 2024
d7a8551
Update docs
Dhoeller19 Oct 8, 2024
7be898d
adds more points to note to how-to
Mayankm96 Oct 9, 2024
f8050e2
runs formatter
Mayankm96 Oct 9, 2024
0dc3691
fixes tab ordering
Mayankm96 Oct 9, 2024
798b5cd
fix tab
Mayankm96 Oct 9, 2024
9f6f0c1
fixes doc
Mayankm96 Oct 9, 2024
845ac59
Apply suggestions from code review
Mayankm96 Oct 9, 2024
6375eb8
Apply suggestions from code review
Mayankm96 Oct 9, 2024
144f15d
Apply suggestions from code review
Mayankm96 Oct 9, 2024
df63363
make function safer
Mayankm96 Oct 9, 2024
2e6c299
adds test
Mayankm96 Oct 9, 2024
df51fb2
adds test for files as well
Mayankm96 Oct 9, 2024
1378991
adds check for multi-asset spawning
Mayankm96 Oct 9, 2024
49353c3
moves the check up
Mayankm96 Oct 9, 2024
fefda69
checks
Mayankm96 Oct 9, 2024
90300a7
Merge branch 'main' into feature/multi-object
Mayankm96 Oct 9, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/source/_static/demos/multi_asset.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
25 changes: 25 additions & 0 deletions docs/source/api/lab/omni.isaac.lab.sim.spawners.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
sensors
from_files
materials
wrappers

.. rubric:: Classes

Expand Down Expand Up @@ -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
11 changes: 11 additions & 0 deletions docs/source/how-to/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------------

Expand Down
101 changes: 101 additions & 0 deletions docs/source/how-to/multi_asset_spawning.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
Spawning Multiple Assets
========================

.. currentmodule:: omni.isaac.lab

Typical, spawning configurations (introduced in :ref:`tutorial-spawn-prims`) 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_utils.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.
45 changes: 34 additions & 11 deletions docs/source/overview/showroom.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion source/extensions/omni.isaac.lab/config/extension.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[package]

# Note: Semantic Versioning is used: https://semver.org/
version = "0.24.19"
version = "0.24.20"

# Description
title = "Isaac Lab framework for Robot Learning"
Expand Down
10 changes: 10 additions & 0 deletions source/extensions/omni.isaac.lab/docs/CHANGELOG.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,16 @@
Changelog
---------

0.24.20 (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.19 (2024-10-05)
~~~~~~~~~~~~~~~~~~~~

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""


Expand Down
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading