Adds option to filter collisions and real-time playback (#253)

This change introduces a new setting in InteractiveSceneCfg to allow
specifying whether collision filtering across environments is desired.
Note that when using the direct workflow, this option will only be
applied automatically when replicate_physics is also enabled in the
config. If replicate_physics is not enabled, a warning will appear in
the logs to prompt users to make a call to scene.filter_collisions().
This is required because collision filtering happens as part of the
physics replication process.

In addition, real-time playback support is extended for all RL library
play.py scripts, allowing real-time replay when possible for
inferencing.

<!-- As you go through the list, delete the ones that are not
applicable. -->

- Bug fix (non-breaking change which fixes an issue)
- New feature (non-breaking change which adds functionality)
- This change requires a documentation update

- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] 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
- [ ] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

<!--
As you go through the checklist above, you can mark something as done by
putting an x character in it

For example,
- [x] I have done this task
- [ ] I have not done this task
-->

scripts/reinforcement_learning/rl_games/play.py

@@ -31,6 +31,7 @@ parser.add_argument(
     action="store_true",
     help="When no checkpoint provided, use the last saved model. Otherwise use the best saved model.",
 )
+parser.add_argument("--real-time", action="store_true", default=False, help="Run in real-time, if possible.")
 # append AppLauncher cli args
 AppLauncher.add_app_launcher_args(parser)
 # parse the arguments
@@ -49,6 +50,7 @@ simulation_app = app_launcher.app
 import gymnasium as gym
 import math
 import os
+import time
 import torch
 
 from isaaclab_rl.rl_games import RlGamesGpuEnv, RlGamesVecEnvWrapper
@@ -147,6 +149,8 @@ def main():
     agent.restore(resume_path)
     agent.reset()
 
+    dt = env.unwrapped.physics_dt
+
     # reset environment
     obs = env.reset()
     if isinstance(obs, dict):
@@ -162,6 +166,7 @@ def main():
     #   attempt to have complete control over environment stepping. However, this removes other
     #   operations such as masking that is used for multi-agent learning by RL-Games.
     while simulation_app.is_running():
+        start_time = time.time()
         # run everything in inference mode
         with torch.inference_mode():
             # convert obs to agent format
@@ -183,6 +188,11 @@ def main():
             if timestep == args_cli.video_length:
                 break
 
+        # time delay for real-time evaluation
+        sleep_time = dt - (time.time() - start_time)
+        if args_cli.real_time and sleep_time > 0:
+            time.sleep(sleep_time)
+
     # close the simulator
     env.close()
 

scripts/reinforcement_learning/rsl_rl/play.py

@@ -28,6 +28,7 @@ parser.add_argument(
     action="store_true",
     help="Use the pre-trained checkpoint from Nucleus.",
 )
+parser.add_argument("--real-time", action="store_true", default=False, help="Run in real-time, if possible.")
 # append RSL-RL cli arguments
 cli_args.add_rsl_rl_args(parser)
 # append AppLauncher cli args
@@ -45,6 +46,7 @@ simulation_app = app_launcher.app
 
 import gymnasium as gym
 import os
+import time
 import torch
 
 from isaaclab_rl.rsl_rl import RslRlOnPolicyRunnerCfg, RslRlVecEnvWrapper, export_policy_as_jit, export_policy_as_onnx
@@ -122,11 +124,14 @@ def main():
         ppo_runner.alg.actor_critic, normalizer=ppo_runner.obs_normalizer, path=export_model_dir, filename="policy.onnx"
     )
 
+    dt = env.unwrapped.physics_dt
+
     # reset environment
     obs, _ = env.get_observations()
     timestep = 0
     # simulate environment
     while simulation_app.is_running():
+        start_time = time.time()
         # run everything in inference mode
         with torch.inference_mode():
             # agent stepping
@@ -139,6 +144,11 @@ def main():
             if timestep == args_cli.video_length:
                 break
 
+        # time delay for real-time evaluation
+        sleep_time = dt - (time.time() - start_time)
+        if args_cli.real_time and sleep_time > 0:
+            time.sleep(sleep_time)
+
     # close the simulator
     env.close()
 

scripts/reinforcement_learning/sb3/play.py

@@ -31,6 +31,7 @@ parser.add_argument(
     action="store_true",
     help="When no checkpoint provided, use the last saved model. Otherwise use the best saved model.",
 )
+parser.add_argument("--real-time", action="store_true", default=False, help="Run in real-time, if possible.")
 # append AppLauncher cli args
 AppLauncher.add_app_launcher_args(parser)
 # parse the arguments
@@ -48,6 +49,7 @@ simulation_app = app_launcher.app
 import gymnasium as gym
 import numpy as np
 import os
+import time
 import torch
 
 from isaaclab_rl.sb3 import Sb3VecEnvWrapper, process_sb3_cfg
@@ -129,11 +131,14 @@ def main():
     print(f"Loading checkpoint from: {checkpoint_path}")
     agent = PPO.load(checkpoint_path, env, print_system_info=True)
 
+    dt = env.unwrapped.physics_dt
+
     # reset environment
     obs = env.reset()
     timestep = 0
     # simulate environment
     while simulation_app.is_running():
+        start_time = time.time()
         # run everything in inference mode
         with torch.inference_mode():
             # agent stepping
@@ -146,6 +151,11 @@ def main():
             if timestep == args_cli.video_length:
                 break
 
+        # time delay for real-time evaluation
+        sleep_time = dt - (time.time() - start_time)
+        if args_cli.real_time and sleep_time > 0:
+            time.sleep(sleep_time)
+
     # close the simulator
     env.close()
 

source/isaaclab/config/extension.toml

 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.33.11"
+version = "0.33.12"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

source/isaaclab/docs/CHANGELOG.rst

 Changelog
 ---------
 
-0.33.11 (2025-01-30)
+0.33.12 (2025-01-30)
 ~~~~~~~~~~~~~~~~~~~~
 
 Fixed
@@ -12,13 +12,27 @@ Fixed
   to the event being triggered at the wrong time after the reset.
 
 
+0.33.11 (2025-01-25)
+~~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added :attr:`isaaclab.scene.InteractiveSceneCfg.filter_collisions` to allow specifying whether collision masking across environments is desired.
+
+Changed
+^^^^^^^
+
+* Automatic collision filtering now happens as part of the replicate_physics call. When replicate_physics is not enabled, we call the previous ``filter_collisions`` API to mask collisions between environments.
+
+
 0.33.10 (2025-01-22)
 ~~~~~~~~~~~~~~~~~~~~
 
 Changed
 ^^^^^^^
 
-* In :meth:`omni.isaac.lab.assets.Articulation.write_joint_limits_to_sim`, we previously added a check for if default joint positions exceed the new limits being set. When this is True, we log a warning message to indicate that the default joint positions will be clipped to be within the range of the new limits. However, the warning message can become overly verbose in a randomization setting where this API is called on every environment reset. We now default to only writing the message to info level logging if called within randomization, and expose a parameter that can be used to choose the logging level desired.
+* In :meth:`isaaclab.assets.Articulation.write_joint_limits_to_sim`, we previously added a check for if default joint positions exceed the new limits being set. When this is True, we log a warning message to indicate that the default joint positions will be clipped to be within the range of the new limits. However, the warning message can become overly verbose in a randomization setting where this API is called on every environment reset. We now default to only writing the message to info level logging if called within randomization, and expose a parameter that can be used to choose the logging level desired.
 
 
 0.33.9 (2025-01-22)
@@ -36,6 +50,7 @@ Fixed
 Fixed
 ^^^^^
 
+<<<<<<< HEAD
 * Removed deprecation of :attr:`omni.isaac.lab.assets.ArticulationData.root_state_w` and
   :attr:`omni.isaac.lab.assets.ArticulationData.body_state_w` derived properties.
 * Removed deprecation of :meth:`omni.isaac.lab.assets.Articulation.write_root_state_to_sim`.
@@ -58,6 +73,29 @@ Fixed
 * Fixed indexing issue in ``write_root_link_velocity_to_sim`` in :class:`omni.isaac.lab.assets.RigidObject`
 * Fixed index broadcasting in ``write_object_link_velocity_to_sim`` and ``write_object_com_pose_to_sim`` in
   the :class:`omni.isaac.lab.assets.RigidObjectCollection` class.
+=======
+* removed deprecation of :attr:`isaaclab.assets.ArticulationData.root_state_w` and
+  :attr:`isaaclab.assets.ArticulationData.body_state_w` derived properties.
+* removed deprecation of :meth:`isaaclab.assets.Articulation.write_root_state_to_sim`.
+* replaced calls to :attr:`isaaclab.assets.ArticulationData.root_com_state_w` and
+  :attr:`isaaclab.assets.ArticulationData.root_link_state_w` with corresponding calls to
+  :attr:`isaaclab.assets.ArticulationData.root_state_w`.
+* replaced calls to :attr:`isaaclab.assets.ArticulationData.body_com_state_w` and
+  :attr:`isaaclab.assets.ArticulationData.body_link_state_w` properties with corresponding calls to
+  :attr:`isaaclab.assets.ArticulationData.body_state_w` properties.
+* removed deprecation of :attr:`isaaclab.assets.RigidObjectData.root_state_w` derived properties  .
+* removed deprecation of :meth:`isaaclab.assets.RigidObject.write_root_state_to_sim`.
+* replaced calls to :attr:`isaaclab.assets.RigidObjectData.root_com_state_w` and
+  :attr:`isaaclab.assets.RigidObjectData.root_link_state_w` properties with corresponding calls to
+  :attr:`isaaclab.assets.RigidObjectData.root_state_w` properties.
+* removed deprecation of :attr:`isaaclab.assets.RigidObjectCollectionData.root_state_w` derived properties.
+* removed deprecation of :meth:`isaaclab.assets.RigidObjectCollection.write_root_state_to_sim`.
+* replaced calls to :attr:`isaaclab.assets.RigidObjectCollectionData.root_com_state_w` and
+  :attr:`isaaclab.assets.RigidObjectData.root_link_state_w` properties with corresponding calls to
+  :attr:`isaaclab.assets.RigidObjectData.root_state_w` properties.
+* fixed indexing issue in ``write_root_link_velocity_to_sim`` in :class:`isaaclab.assets.RigidObject`
+* fixed index broadcasting in ``write_object_link_velocity_to_sim`` and ``write_object_com_pose_to_sim`` in :class:`isaaclab.assets.RigidObjectCollection`
+>>>>>>> e9a3c6c55 (Adds option to filter collisions and real-time playback (#253))
 
 
 0.33.7 (2025-01-14)
@@ -66,7 +104,7 @@ Fixed
 Fixed
 ^^^^^
 
-* Fixed the respawn of only wrong object samples in :func:`repeated_objects_terrain` of :mod:`omni.isaac.lab.terrains.trimesh` module. Previously, the function was respawning all objects in the scene instead of only the wrong object samples, which in worst case could lead to infinite respawn loop.
+* Fixed the respawn of only wrong object samples in :func:`repeated_objects_terrain` of :mod:`isaaclab.terrains.trimesh` module. Previously, the function was respawning all objects in the scene instead of only the wrong object samples, which in worst case could lead to infinite respawn loop.
 
 
 0.33.6 (2025-01-16)
@@ -104,7 +142,7 @@ Changed
 Fixed
 ^^^^^
 
-* Fixed docstring in articulation data :class:`omni.isaac.lab.assets.ArticulationData`.
+* Fixed docstring in articulation data :class:`isaaclab.assets.ArticulationData`.
   In body properties sections, the second dimension should be num_bodies but was documented as 1.
 
 
@@ -114,7 +152,7 @@ Fixed
 Added
 ^^^^^
 
-* Added body tracking as an origin type to :class:`omni.isaac.lab.envs.ViewerCfg` and :class:`omni.isaac.lab.envs.ui.ViewportCameraController`.
+* Added body tracking as an origin type to :class:`isaaclab.envs.ViewerCfg` and :class:`isaaclab.envs.ui.ViewportCameraController`.
 
 
 0.33.1 (2024-12-26)
@@ -133,7 +171,7 @@ Changed
 Fixed
 ^^^^^
 
-* Fixed populating default_joint_stiffness and default_joint_damping values for ImplicitActuator instances in :class:`omni.isaac.lab.assets.Articulation`
+* Fixed populating default_joint_stiffness and default_joint_damping values for ImplicitActuator instances in :class:`isaaclab.assets.Articulation`
 
 
 0.32.2 (2024-12-17)

source/isaaclab/isaaclab/scene/interactive_scene.py

@@ -138,7 +138,7 @@ class InteractiveScene:
                 prim_paths=self.env_prim_paths,
                 replicate_physics=False,
                 copy_from_source=True,
-                enable_env_ids=True,  # this automatically filters collisions between environments
+                enable_env_ids=self.cfg.filter_collisions,  # this won't do anything because we are not replicating physics
             )
             self._default_env_origins = torch.tensor(env_origins, device=self.device, dtype=torch.float32)
         else:
@@ -160,9 +160,14 @@ class InteractiveScene:
                     prim_paths=self.env_prim_paths,
                     base_env_path=self.env_ns,
                     root_path=self.env_regex_ns.replace(".*", ""),
-                    enable_env_ids=True,
+                    enable_env_ids=self.cfg.filter_collisions,
                 )
 
+            # since env_ids is only applicable when replicating physics, we have to fallback to the previous method
+            # to filter collisions if replicate_physics is not enabled
+            if not self.cfg.replicate_physics and self.cfg.filter_collisions:
+                self.filter_collisions(self._global_prim_paths)
+
     def clone_environments(self, copy_from_source: bool = False):
         """Creates clones of the environment ``/World/envs/env_0``.
 
@@ -188,9 +193,17 @@ class InteractiveScene:
             prim_paths=self.env_prim_paths,
             replicate_physics=self.cfg.replicate_physics,
             copy_from_source=copy_from_source,
-            enable_env_ids=True,  # this automatically filters collisions between environments
+            enable_env_ids=self.cfg.filter_collisions,  # this automatically filters collisions between environments
         )
 
+        # since env_ids is only applicable when replicating physics, we have to fallback to the previous method
+        # to filter collisions if replicate_physics is not enabled
+        if not self.cfg.replicate_physics and self.cfg.filter_collisions:
+            omni.log.warn(
+                "Collision filtering can only be automatically enabled when replicate_physics=True."
+                " Please call scene.filter_collisions(global_prim_paths) to filter collisions across environments."
+            )
+
         # in case of heterogeneous cloning, the env origins is specified at init
         if self._default_env_origins is None:
             self._default_env_origins = torch.tensor(env_origins, device=self.device, dtype=torch.float32)

source/isaaclab/isaaclab/scene/interactive_scene_cfg.py

@@ -97,3 +97,15 @@ class InteractiveSceneCfg:
         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 = True
+    """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()``.
+    """

source/isaaclab_tasks/docs/CHANGELOG.rst

@@ -17,7 +17,7 @@ Added
 Fixed
 ^^^^^
 
-* Fixed the reset of the actions in the function overriding of the low level observations of :class:`omni.isaac.lab_tasks.manager_based.navigation.mdp.PreTrainedPolicyAction`.
+* Fixed the reset of the actions in the function overriding of the low level observations of :class:`isaaclab_tasks.manager_based.navigation.mdp.PreTrainedPolicyAction`.
 
 
 0.10.20 (2024-12-17)