Fixes collision filtering logic on CPU (#2553)

# Description

Previously, the physics engine introduced a new feature to automatically
perform collision filtering across environments when physics replication
is enabled. However, this feature has limitations for CPU simulation, so
we still need to explicitly call collision filtering on CPU simulation.

This change fixes the scene setup process to do explicit collision
filtering when running on the CPU.

Fixes #2548 

<!-- As a practice, it is recommended to open an issue to have
discussions on the proposed pull request.
This makes it easier for the community to keep track of what is being
developed or added, and if a given feature
is demanded by more than one party. -->

## Type of change

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

- Bug fix (non-breaking change which fixes an issue)


## 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
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] 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
-->

---------
Signed-off-by: Kelly Guo <kellyg@nvidia.com>
Signed-off-by: Kelly Guo <kellyguo123@hotmail.com>

source/isaaclab/config/extension.toml

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

source/isaaclab/docs/CHANGELOG.rst

 Changelog
 ---------
 
+0.40.5 (2025-05-22)
+~~~~~~~~~~~~~~~~~~~
+
+Fixed
+^^^^^
+
+* Fixed collision filtering logic for CPU simulation. The automatic collision filtering feature
+  currently has limitations for CPU simulation. Collision filtering needs to be manually enabled when using CPU simulation.
+
+
 0.40.4 (2025-06-03)
 ~~~~~~~~~~~~~~~~~~~
 

source/isaaclab/isaaclab/scene/interactive_scene.py

@@ -171,7 +171,8 @@ class InteractiveScene:
 
             # 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:
+            # additionally, env_ids is only supported in GPU simulation
+            if (not self.cfg.replicate_physics and self.cfg.filter_collisions) or self.device == "cpu":
                 self.filter_collisions(self._global_prim_paths)
 
     def clone_environments(self, copy_from_source: bool = False):
@@ -204,9 +205,10 @@ class InteractiveScene:
 
         # 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:
+        # additionally, env_ids is only supported in GPU simulation
+        if (not self.cfg.replicate_physics and self.cfg.filter_collisions) or self.device == "cpu":
             omni.log.warn(
-                "Collision filtering can only be automatically enabled when replicate_physics=True."
+                "Collision filtering can only be automatically enabled when replicate_physics=True and GPU simulation."
                 " Please call scene.filter_collisions(global_prim_paths) to filter collisions across environments."
             )
 

source/isaaclab_tasks/isaaclab_tasks/direct/anymal_c/anymal_c_env.py

@@ -71,6 +71,9 @@ class AnymalCEnv(DirectRLEnv):
         self._terrain = self.cfg.terrain.class_type(self.cfg.terrain)
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=[self.cfg.terrain.prim_path])
         # add lights
         light_cfg = sim_utils.DomeLightCfg(intensity=2000.0, color=(0.75, 0.75, 0.75))
         light_cfg.func("/World/Light", light_cfg)

source/isaaclab_tasks/isaaclab_tasks/direct/cart_double_pendulum/cart_double_pendulum_env.py

@@ -87,6 +87,9 @@ class CartDoublePendulumEnv(DirectMARLEnv):
         spawn_ground_plane(prim_path="/World/ground", cfg=GroundPlaneCfg())
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=[])
         # add articulation to scene
         self.scene.articulations["robot"] = self.robot
         # add lights

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_camera_env.py

@@ -128,6 +128,9 @@ class CartpoleCameraEnv(DirectRLEnv):
 
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        if self.device == "cpu":
+            # we need to explicitly filter collisions for CPU simulation
+            self.scene.filter_collisions(global_prim_paths=[])
 
         # add articulation and sensors to scene
         self.scene.articulations["cartpole"] = self._cartpole

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_env.py

@@ -78,6 +78,9 @@ class CartpoleEnv(DirectRLEnv):
         spawn_ground_plane(prim_path="/World/ground", cfg=GroundPlaneCfg())
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=[])
         # add articulation to scene
         self.scene.articulations["cartpole"] = self.cartpole
         # add lights

source/isaaclab_tasks/isaaclab_tasks/direct/factory/factory_env.py

@@ -178,6 +178,9 @@ class FactoryEnv(DirectRLEnv):
             self._large_gear_asset = Articulation(self.cfg_task.large_gear_cfg)
 
         self.scene.clone_environments(copy_from_source=False)
+        if self.device == "cpu":
+            # we need to explicitly filter collisions for CPU simulation
+            self.scene.filter_collisions()
 
         self.scene.articulations["robot"] = self._robot
         self.scene.articulations["fixed_asset"] = self._fixed_asset

source/isaaclab_tasks/isaaclab_tasks/direct/franka_cabinet/franka_cabinet_env.py

@@ -277,6 +277,9 @@ class FrankaCabinetEnv(DirectRLEnv):
 
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=[self.cfg.terrain.prim_path])
 
         # add lights
         light_cfg = sim_utils.DomeLightCfg(intensity=2000.0, color=(0.75, 0.75, 0.75))

source/isaaclab_tasks/isaaclab_tasks/direct/humanoid_amp/humanoid_amp_env.py

@@ -69,6 +69,10 @@ class HumanoidAmpEnv(DirectRLEnv):
         )
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=["/World/ground"])
+
         # add articulation to scene
         self.scene.articulations["robot"] = self.robot
         # add lights

source/isaaclab_tasks/isaaclab_tasks/direct/locomotion/locomotion_env.py

@@ -58,6 +58,9 @@ class LocomotionEnv(DirectRLEnv):
         self.terrain = self.cfg.terrain.class_type(self.cfg.terrain)
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=[self.cfg.terrain.prim_path])
         # add articulation to scene
         self.scene.articulations["robot"] = self.robot
         # add lights

source/isaaclab_tasks/isaaclab_tasks/direct/quadcopter/quadcopter_env.py

@@ -143,6 +143,9 @@ class QuadcopterEnv(DirectRLEnv):
         self._terrain = self.cfg.terrain.class_type(self.cfg.terrain)
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=[self.cfg.terrain.prim_path])
         # add lights
         light_cfg = sim_utils.DomeLightCfg(intensity=2000.0, color=(0.75, 0.75, 0.75))
         light_cfg.func("/World/Light", light_cfg)

tools/template/templates/tasks/direct_multi-agent/env

@@ -37,6 +37,9 @@ class {{ task.classname }}Env(DirectMARLEnv):
         spawn_ground_plane(prim_path="/World/ground", cfg=GroundPlaneCfg())
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=[])
         # add articulation to scene
         self.scene.articulations["robot"] = self.robot
         # add lights

tools/template/templates/tasks/direct_single-agent/env

@@ -36,6 +36,9 @@ class {{ task.classname }}Env(DirectRLEnv):
         spawn_ground_plane(prim_path="/World/ground", cfg=GroundPlaneCfg())
         # clone and replicate
         self.scene.clone_environments(copy_from_source=False)
+        # we need to explicitly filter collisions for CPU simulation
+        if self.device == "cpu":
+            self.scene.filter_collisions(global_prim_paths=[])
         # add articulation to scene
         self.scene.articulations["robot"] = self.robot
         # add lights