Addresses docs related issues from MultiMeshRayCaster (#4222)

# Description

This MR adds the remaining comments in #3298

## Type of change

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

## Checklist

- [x] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [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
- [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

---------

Signed-off-by: renezurbruegg <zrene@ethz.ch>
Signed-off-by: Mayank Mittal <12863862+Mayankm96@users.noreply.github.com>
Signed-off-by: James Tigue <166445701+jtigue-bdai@users.noreply.github.com>
Signed-off-by: Pascal Roth <57946385+pascal-roth@users.noreply.github.com>
Signed-off-by: Kelly Guo <kellyg@nvidia.com>
Co-authored-by: Pascal Roth <57946385+pascal-roth@users.noreply.github.com>
Co-authored-by: zrene <zrene@ethz.ch>
Co-authored-by: Pascal Roth <roth.pascal@outlook.de>
Co-authored-by: James Tigue <166445701+jtigue-bdai@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Kelly Guo <kellyg@nvidia.com>
Co-authored-by: zrene <rene.zurbruegg@gmail.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

Author: 7 people

docs/source/_static/demos/multi-mesh-raycast.jpg

@@ -31,6 +31,11 @@
     RayCasterCfg
     RayCasterCamera
     RayCasterCameraCfg
+    MultiMeshRayCaster
+    MultiMeshRayCasterData
+    MultiMeshRayCasterCfg
+    MultiMeshRayCasterCamera
+    MultiMeshRayCasterCameraCfg
     Imu
     ImuCfg
 
@@ -151,7 +156,40 @@ Ray-Cast Camera
     :members:
     :inherited-members:
     :show-inheritance:
-    :exclude-members: __init__, class_type
+    :exclude-members: __init__, class_type, OffsetCfg
+
+Multi-Mesh Ray-Cast Sensor
+--------------------------
+
+.. autoclass:: MultiMeshRayCaster
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: MultiMeshRayCasterData
+    :members:
+    :inherited-members:
+    :exclude-members: __init__
+
+.. autoclass:: MultiMeshRayCasterCfg
+    :members:
+    :inherited-members:
+    :show-inheritance:
+    :exclude-members: __init__, class_type, OffsetCfg
+
+Multi-Mesh Ray-Cast Camera
+--------------------------
+
+.. autoclass:: MultiMeshRayCasterCamera
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: MultiMeshRayCasterCameraCfg
+    :members:
+    :inherited-members:
+    :show-inheritance:
+    :exclude-members: __init__, class_type, OffsetCfg, RaycastTargetCfg
 
 Inertia Measurement Unit
 ------------------------

docs/source/api/lab/isaaclab.sensors.rst

@@ -358,3 +358,27 @@ A few quick showroom scripts to run and checkout:
    .. image:: ../_static/demos/quadrupeds.jpg
       :width: 100%
       :alt: Quadrupeds in Isaac Lab
+
+
+-  Spawn a multi-mesh ray caster that uses Warp kernels for raycasting
+
+   .. tab-set::
+      :sync-group: os
+
+      .. tab-item:: :icon:`fa-brands fa-linux` Linux
+         :sync: linux
+
+         .. code:: bash
+
+            ./isaaclab.sh -p scripts/demos/sensors/multi_mesh_raycaster.py --num_envs 16 --asset_type objects
+
+      .. tab-item:: :icon:`fa-brands fa-windows` Windows
+         :sync: windows
+
+         .. code:: batch
+
+            isaaclab.bat -p scripts\demos\sensors\multi_mesh_raycaster.py --num_envs 16 --asset_type objects
+
+   .. image:: ../_static/demos/multi-mesh-raycast.jpg
+      :width: 100%
+      :alt: Multi-mesh raycaster in Isaac Lab

docs/source/overview/showroom.rst

@@ -4,25 +4,34 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 
-"""Example on using the MultiMesh Raycaster sensor.
+"""Example on using the Multi-Mesh Raycaster sensor.
+
+.. code-block:: bash
+
+    # with allegro hand
+    python scripts/demos/sensors/multi_mesh_raycaster.py --num_envs 16 --asset_type allegro_hand
+
+    # with anymal-D bodies
+    python scripts/demos/sensors/multi_mesh_raycaster.py --num_envs 16 --asset_type anymal_d
+
+    # with random multiple objects
+    python scripts/demos/sensors/multi_mesh_raycaster.py --num_envs 16 --asset_type objects
 
-Usage:
-    `python scripts/demos/sensors/multi_mesh_raycaster.py --num_envs 16 --asset_type <allegro_hand|anymal_d|multi>`
 """
 
 import argparse
 
 from isaaclab.app import AppLauncher
 
 # add argparse arguments
-parser = argparse.ArgumentParser(description="Example on using the raycaster sensor.")
+parser = argparse.ArgumentParser(description="Example on using the multi-mesh raycaster sensor.")
 parser.add_argument("--num_envs", type=int, default=16, help="Number of environments to spawn.")
 parser.add_argument(
     "--asset_type",
     type=str,
     default="allegro_hand",
     help="Asset type to use.",
-    choices=["allegro_hand", "anymal_d", "multi"],
+    choices=["allegro_hand", "anymal_d", "objects"],
 )
 # append AppLauncher cli args
 AppLauncher.add_app_launcher_args(parser)
@@ -89,7 +98,7 @@
 elif args_cli.asset_type == "anymal_d":
     asset_cfg = ANYMAL_D_CFG.replace(prim_path="{ENV_REGEX_NS}/Robot")
     ray_caster_cfg = MultiMeshRayCasterCfg(
-        prim_path="{ENV_REGEX_NS}/Robot",
+        prim_path="{ENV_REGEX_NS}/Robot/base",
         update_period=1 / 60,
         offset=MultiMeshRayCasterCfg.OffsetCfg(pos=(0, -0.1, 0.3)),
         mesh_prim_paths=[
@@ -106,7 +115,7 @@
         visualizer_cfg=RAY_CASTER_MARKER_CFG.replace(prim_path="/Visuals/RayCaster"),
     )
 
-elif args_cli.asset_type == "multi":
+elif args_cli.asset_type == "objects":
     asset_cfg = RigidObjectCfg(
         prim_path="{ENV_REGEX_NS}/Object",
         spawn=sim_utils.MultiAssetSpawnerCfg(
@@ -276,7 +285,7 @@ def main():
     scene_cfg = RaycasterSensorSceneCfg(num_envs=args_cli.num_envs, env_spacing=2.0, replicate_physics=False)
     scene = InteractiveScene(scene_cfg)
 
-    if args_cli.asset_type == "multi":
+    if args_cli.asset_type == "objects":
         randomize_shape_color(scene_cfg.asset.prim_path.format(ENV_REGEX_NS="/World/envs/env_.*"))
 
     # Play the simulator

scripts/demos/sensors/multi_mesh_raycaster.py

@@ -4,25 +4,34 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 
-"""Example on using the MultiMesh Raycaster Camera sensor.
+"""Example on using the Multi-Mesh Raycaster Camera sensor.
+
+.. code-block:: bash
+
+    # with allegro hand
+    python scripts/demos/sensors/multi_mesh_raycaster.py --num_envs 16 --asset_type allegro_hand
+
+    # with anymal-D bodies
+    python scripts/demos/sensors/multi_mesh_raycaster.py --num_envs 16 --asset_type anymal_d
+
+    # with random multiple objects
+    python scripts/demos/sensors/multi_mesh_raycaster.py --num_envs 16 --asset_type objects
 
-Usage:
-    `python scripts/demos/sensors/multi_mesh_raycaster_camera.py --num_envs 16 --asset_type <allegro_hand|anymal_d|multi>`
 """
 
 import argparse
 
 from isaaclab.app import AppLauncher
 
 # add argparse arguments
-parser = argparse.ArgumentParser(description="Example on using the raycaster sensor.")
+parser = argparse.ArgumentParser(description="Example on using the multi-mesh raycaster sensor.")
 parser.add_argument("--num_envs", type=int, default=16, help="Number of environments to spawn.")
 parser.add_argument(
     "--asset_type",
     type=str,
     default="allegro_hand",
     help="Asset type to use.",
-    choices=["allegro_hand", "anymal_d", "multi"],
+    choices=["allegro_hand", "anymal_d", "objects"],
 )
 # append AppLauncher cli args
 AppLauncher.add_app_launcher_args(parser)
@@ -94,7 +103,7 @@
 elif args_cli.asset_type == "anymal_d":
     asset_cfg = ANYMAL_D_CFG.replace(prim_path="{ENV_REGEX_NS}/Robot")
     ray_caster_cfg = MultiMeshRayCasterCameraCfg(
-        prim_path="{ENV_REGEX_NS}/Robot",
+        prim_path="{ENV_REGEX_NS}/Robot/base",
         update_period=1 / 60,
         offset=MultiMeshRayCasterCameraCfg.OffsetCfg(pos=(0, -0.1, 1.5), rot=(0.0, 1.0, 0.0, 0.0)),
         mesh_prim_paths=[
@@ -115,7 +124,7 @@
         visualizer_cfg=RAY_CASTER_MARKER_CFG.replace(prim_path="/Visuals/RayCaster"),
     )
 
-elif args_cli.asset_type == "multi":
+elif args_cli.asset_type == "objects":
     asset_cfg = RigidObjectCfg(
         prim_path="{ENV_REGEX_NS}/Object",
         spawn=sim_utils.MultiAssetSpawnerCfg(
@@ -302,7 +311,7 @@ def main():
     scene_cfg = RaycasterSensorSceneCfg(num_envs=args_cli.num_envs, env_spacing=2.0, replicate_physics=False)
     scene = InteractiveScene(scene_cfg)
 
-    if args_cli.asset_type == "multi":
+    if args_cli.asset_type == "objects":
         randomize_shape_color(scene_cfg.asset.prim_path.format(ENV_REGEX_NS="/World/envs/env_.*"))
 
     # Play the simulator

scripts/demos/sensors/multi_mesh_raycaster_camera.py

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

source/isaaclab/config/extension.toml

@@ -1,15 +1,28 @@
 Changelog
 ---------
 
+0.50.5 (2025-12-15)
+~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added :class:`~isaaclab.sensors.MultiMeshRayCaster` sensor to support tracking of dynamic meshes for ray-casting.
+  We keep the previous implementation of :class:`~isaaclab.sensors.RayCaster` for backwards compatibility.
+* Added :mod:`isaaclab.utils.mesh` sub-module to perform various Trimesh and USD Mesh related operations.
+
+
 0.50.4 (2025-12-15)
 ~~~~~~~~~~~~~~~~~~~
 
 Added
 ^^^^^
 
-* Added :attr:`~isaaclab.sim.PhysxCfg.enable_external_forces_every_iteration` to enable external forces every position iteration.
-  This can help improve the accuracy of velocity updates. Consider enabling this flag if the velocities generated by the simulation are noisy.
-* Added warning when :attr:`~isaaclab.sim.PhysxCfg.enable_external_forces_every_iteration` is set to False and the solver type is TGS.
+* Added :attr:`~isaaclab.sim.PhysxCfg.enable_external_forces_every_iteration` to enable external forces every position
+  iteration. This can help improve the accuracy of velocity updates. Consider enabling this flag if the velocities
+  generated by the simulation are noisy.
+* Added warning when :attr:`~isaaclab.sim.PhysxCfg.enable_external_forces_every_iteration` is set to False and
+  the solver type is TGS.
 
 
 0.50.3 (2025-12-11)

source/isaaclab/docs/CHANGELOG.rst

@@ -3,7 +3,17 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-"""Sub-module for Warp-based ray-cast sensor."""
+"""Sub-module for Warp-based ray-cast sensor.
+
+The sub-module contains two implementations of the ray-cast sensor:
+
+- :class:`isaaclab.sensors.ray_caster.RayCaster`: A basic ray-cast sensor that can be used to ray-cast against a single mesh.
+- :class:`isaaclab.sensors.ray_caster.MultiMeshRayCaster`: A multi-mesh ray-cast sensor that can be used to ray-cast against
+  multiple meshes. For these meshes, it tracks their transformations and updates the warp meshes accordingly.
+
+Corresponding camera implementations are also provided for each of the sensor implementations. Internally, they perform
+the same ray-casting operations as the sensor implementations, but return the results as images.
+"""
 
 from . import patterns
 from .multi_mesh_ray_caster import MultiMeshRayCaster

source/isaaclab/isaaclab/sensors/ray_caster/__init__.py

@@ -5,11 +5,6 @@
 
 from __future__ import annotations
 
-"""Multi-mesh ray casting sensor implementation.
-
-This file adds support for ray casting against multiple (possibly regex-selected) mesh targets.
-"""
-
 import logging
 import numpy as np
 import re
@@ -53,27 +48,30 @@ class MultiMeshRayCaster(RayCaster):
     Compared to the default RayCaster, the MultiMeshRayCaster provides additional functionality and flexibility as
     an extension of the default RayCaster with the following enhancements:
 
-    - Raycasting against multiple target types : Supports primitive shapes (spheres, cubes, …) as well as arbitrary
-        meshes.
+    - Raycasting against multiple target types : Supports primitive shapes (spheres, cubes, etc.) as well as arbitrary
+      meshes.
     - Dynamic mesh tracking : Keeps track of specified meshes, enabling raycasting against moving parts
-        (e.g., robot links, articulated bodies, or dynamic obstacles).
+      (e.g., robot links, articulated bodies, or dynamic obstacles).
     - Memory-efficient caching : Avoids redundant memory usage by reusing mesh data across environments.
 
-    Example usage to raycast against the visual meshes of a robot (e.g. anymal):
-        .. code-block:: python
-            ray_caster_cfg = MultiMeshRayCasterCfg(
-                prim_path="{ENV_REGEX_NS}/Robot",
-                mesh_prim_paths=[
-                    "/World/Ground",
-                    MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/LF_.*/visuals"),
-                    MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/RF_.*/visuals"),
-                    MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/LH_.*/visuals"),
-                    MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/RH_.*/visuals"),
-                    MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/base/visuals"),
-                ],
-                ray_alignment="world",
-                pattern_cfg=patterns.GridPatternCfg(resolution=0.02, size=(2.5, 2.5), direction=(0, 0, -1)),
-            )
+    Example usage to raycast against the visual meshes of a robot (e.g. ANYmal):
+
+    .. code-block:: python
+
+        ray_caster_cfg = MultiMeshRayCasterCfg(
+            prim_path="{ENV_REGEX_NS}/Robot",
+            mesh_prim_paths=[
+                "/World/Ground",
+                MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/LF_.*/visuals"),
+                MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/RF_.*/visuals"),
+                MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/LH_.*/visuals"),
+                MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/RH_.*/visuals"),
+                MultiMeshRayCasterCfg.RaycastTargetCfg(prim_expr="{ENV_REGEX_NS}/Robot/base/visuals"),
+            ],
+            ray_alignment="world",
+            pattern_cfg=patterns.GridPatternCfg(resolution=0.02, size=(2.5, 2.5), direction=(0, 0, -1)),
+        )
+
     """
 
     cfg: MultiMeshRayCasterCfg
@@ -84,7 +82,8 @@ class MultiMeshRayCaster(RayCaster):
     mesh_views: ClassVar[dict[str, XFormPrim | physx.ArticulationView | physx.RigidBodyView]] = {}
     """A dictionary to store mesh views for raycasting, shared across all instances.
 
-    The keys correspond to the prim path for the mesh views, and values are the corresponding view objects."""
+    The keys correspond to the prim path for the mesh views, and values are the corresponding view objects.
+    """
 
     def __init__(self, cfg: MultiMeshRayCasterCfg):
         """Initializes the ray-caster object.
@@ -148,17 +147,20 @@ def _initialize_warp_meshes(self):
         """Parse mesh prim expressions, build (or reuse) Warp meshes, and cache per-env mesh IDs.
 
         High-level steps (per target expression):
-            1. Resolve matching prims by regex/path expression.
-            2. Collect supported mesh child prims; merge into a single mesh if configured.
-            3. Deduplicate identical vertex buffers (exact match) to avoid uploading duplicates to Warp.
-            4. Partition mesh IDs per environment or mark as globally shared.
-            5. Optionally create physics views (articulation / rigid body / fallback XForm) and cache local offsets.
+
+        1. Resolve matching prims by regex/path expression.
+        2. Collect supported mesh child prims; merge into a single mesh if configured.
+        3. Deduplicate identical vertex buffers (exact match) to avoid uploading duplicates to Warp.
+        4. Partition mesh IDs per environment or mark as globally shared.
+        5. Optionally create physics views (articulation / rigid body / fallback XForm) and cache local offsets.
 
         Exceptions:
             Raises a RuntimeError if:
-                - No prims match the provided expression.
-                - No supported mesh prims are found under a matched prim.
-                - Multiple mesh prims are found but merging is disabled.
+
+            - No prims match the provided expression.
+            - No supported mesh prims are found under a matched prim.
+            - Multiple mesh prims are found but merging is disabled.
+
         """
         multi_mesh_ids: dict[str, list[list[int]]] = {}
         for target_cfg in self._raycast_targets_cfg:
@@ -292,7 +294,7 @@ def _initialize_warp_meshes(self):
 
             if target_cfg.track_mesh_transforms:
                 MultiMeshRayCaster.mesh_views[target_prim_path], MultiMeshRayCaster.mesh_offsets[target_prim_path] = (
-                    self._get_trackable_prim_view(target_prim_path)
+                    self._obtain_trackable_prim_view(target_prim_path)
                 )
 
         # throw an error if no meshes are found

source/isaaclab/isaaclab/sensors/ray_caster/multi_mesh_ray_caster.py

@@ -18,4 +18,5 @@ class MultiMeshRayCasterCameraData(CameraData, RayCasterData):
     """The mesh ids of the image pixels.
 
     Shape is (N, H, W, 1), where N is the number of sensors, H and W are the height and width of the image,
-    and 1 is the number of mesh ids per pixel."""
+    and 1 is the number of mesh ids per pixel.
+    """