Match prim path expressions as whole-path regular expressions

find_matching_prims matched each '/'-separated token against prim names
at that depth, while find_first_matching_prim compiled the same argument
as one regex over the full path. Both take a parameter named
prim_path_regex and document the same contract, so an expression such as
'/World/Robot/.*link2' returned nothing from the first and a depth-2 prim
from the second.

Match the whole path in both, and have find_first_matching_prim delegate.
Whole-path matching does not imply traversing the whole stage: the
expression's longest literal prefix gives the traversal root, and when no
wildcard can span a '/', the separator count bounds the descent. On a
93k-prim stage a per-environment query visits about 1k prims.

Two changes follow, because '.*' had been carrying structure rather than
meaning what regex says it means.

make_clone_plan derived an asset's destination template by substituting
'.*' for '{}' in the configured prim path. str.replace is positionally
blind, so a second wildcard below the environment slot produced a
template with two slots that raised IndexError when formatted; the
environment root was hardcoded besides, so a non-default namespace
excluded every asset from the plan. Take the slot from the environment
template instead, which CloneCfg now carries directly: a template always
yields a regex, whereas recovering a template from a regex requires
guessing which part of the text is the wildcard.

With '.*' free to mean what regex says, the environment namespace spells
its slot '[^/]+' so it cannot match across a '/' and select a prim nested
deeper under an environment. path.match accepts a character class in the
clone slot for that, since the text '[^/]+' contains a '/' and so cannot
match the one-segment alternative.

Author: ooctipus

source/isaaclab/changelog.d/octi-prim-path-real-regex-matcher.minor.rst

@@ -0,0 +1,45 @@
+Added
+^^^^^
+
+* Added :attr:`~isaaclab.cloner.CloneCfg.clone_template` for the replicated environment prim path,
+  with ``{}`` marking the environment index. It replaces ``CloneCfg.clone_regex``, whose value is
+  now ``clone_template.format(".*")``.
+* Added an ``env_template`` argument to :func:`~isaaclab.cloner.make_clone_plan` and
+  :class:`~isaaclab.cloner.ReplicateSession`.
+* Added :func:`~isaaclab.sim.utils.path_expr_to_glob` and
+  :func:`~isaaclab.sim.utils.split_path_expr`, for converting a prim path expression to the glob
+  the physics engines accept and for splitting one without cutting a character class in half.
+
+Changed
+^^^^^^^
+
+* **Breaking:** Changed :func:`~isaaclab.sim.utils.find_matching_prims` to match the whole prim
+  path as a plain regular expression instead of one token per path segment. ``.`` now matches
+  ``/``, so ``/World/Robot/.*`` selects descendants at any depth; use ``[^/]+`` for a single
+  segment.
+* Changed :func:`~isaaclab.sim.utils.find_first_matching_prim` to delegate to
+  :func:`~isaaclab.sim.utils.find_matching_prims`, so both read an expression the same way.
+* Changed the environment namespace to spell its slot ``[^/]+`` rather than ``.*``, so
+  ``{ENV_REGEX_NS}/Robot`` no longer also selects a ``Robot`` nested deeper under an environment.
+* Changed :func:`~isaaclab.cloner.path.match` to accept a character class in the clone slot, so a
+  segment-safe namespace resolves against a destination template.
+
+* Changed prim path expressions throughout the repository to spell a single path segment
+  ``[^/]`` rather than ``.``, so each pattern selects what it selected before now that ``.``
+  matches ``/``.
+
+Removed
+^^^^^^^
+
+* Removed the legacy glob-wildcard rewrite from prim path expressions. A bare ``*`` is a regular
+  expression quantifier and is no longer rewritten to ``.*``; the rewrite could not tell a glob
+  star from a quantifier and corrupted ``[^/]*`` into ``[^/].*``. Patterns relying on ``*`` as a
+  standalone wildcard should spell it ``.*`` (any depth) or ``[^/]*`` (one path segment).
+
+Fixed
+^^^^^
+
+* Fixed :func:`~isaaclab.cloner.make_clone_plan` raising ``IndexError`` for a prim path holding
+  more than one wildcard, and ignoring a non-default environment namespace.
+* Fixed :class:`~isaaclab.sensors.MultiMeshRayCaster` expanding ``{ENV_REGEX_NS}`` with a
+  hardcoded namespace instead of the shared default.

source/isaaclab/isaaclab/cloner/clone_plan.py

@@ -22,6 +22,7 @@
 
 import itertools
 import math
+import re
 from collections.abc import Callable, Iterable, Sequence
 from dataclasses import dataclass, field
 from typing import Any
@@ -30,7 +31,7 @@
 
 import isaaclab.sim as sim_utils
 
-from .cloner_cfg import InclusionSet
+from .cloner_cfg import DEFAULT_ENV_TEMPLATE, InclusionSet
 from .cloner_strategies import sequential
 from .path import split
 
@@ -224,6 +225,7 @@ def make_clone_plan(
     *,
     clone_strategy: Callable = sequential,
     valid_set: torch.Tensor | None = None,
+    env_template: str = DEFAULT_ENV_TEMPLATE,
 ) -> ClonePlan:
     """Build a :class:`ClonePlan` from asset cfgs.
 
@@ -266,21 +268,35 @@ def set_spawn_paths(spawn_cfg: Any, paths: list[str | None]) -> None:
                 raise ValueError("Single spawner expects exactly one planned source path.")
             spawn_cfg.spawn_path = active[0]
 
-    env_root_marker = "/World/envs/"
-    env_template = "/World/envs/env_{}"
+    # the env root sits at a known depth, so the destination is the env template plus whatever the
+    # cfg authored below it -- no need to find the clone slot by substituting in the cfg's own path
+    env_prefix, _ = split(env_template)
+
+    def env_destination(prim_path: str) -> str | None:
+        """Rebase an env-scoped cfg path onto the env template, or None when it is global.
+
+        The cfg may name one environment (``env_0``) or all of them (``env_.*``, ``env_[^/]+``);
+        only the text before the slot is fixed, so that is what identifies an env-scoped path.
+        """
+        if not prim_path.startswith(env_prefix):
+            return None
+        # blank out character classes so a '/' inside one does not read as a separator; the
+        # replacement is the same length, so the index carries back to the original string
+        masked = re.sub(r"\[\^?[^]]*\]", lambda match: "\x00" * len(match.group()), prim_path)
+        cut = masked.find("/", len(env_prefix))
+        return env_template if cut == -1 else env_template + prim_path[cut:]
 
     # 1) Build per-group records: (cfg, spawn_cfg, destination_template, num_variants).
     groups: list[tuple[Any, Any, str, int]] = []
     for cfg in cfgs:
         if not hasattr(cfg, "prim_path") or not hasattr(cfg, "spawn") or cfg.spawn is None:
             continue
         prim_path = cfg.prim_path
-        if env_root_marker not in prim_path:
+        if (destination := env_destination(prim_path)) is None:
             continue
         count = num_spawn_variants(cfg.spawn)
         if count <= 0:
             raise ValueError(f"Spawner at '{prim_path}' must have at least one variant.")
-        destination = prim_path.replace(".*", "{}")
         groups.append((cfg, cfg.spawn, destination, count))
 
     env_ids = torch.arange(num_clones, dtype=torch.long, device=device)

source/isaaclab/isaaclab/cloner/cloner_cfg.py

@@ -12,6 +12,9 @@
 
 from .cloner_strategies import sequential
 
+DEFAULT_ENV_TEMPLATE = "/World/envs/env_{}"
+"""Default path template for a replicated env prim; ``{}`` marks the environment index."""
+
 
 @configclass
 class InclusionSet:
@@ -46,8 +49,12 @@ class CloneCfg:
     device: str = "cpu"
     """Torch device on which mapping buffers are allocated."""
 
-    clone_regex: str = "/World/envs/env_.*"
-    """Regex matching every replicated env prim. Used to expand ``{ENV_REGEX_NS}`` cfg macros."""
+    clone_template: str = DEFAULT_ENV_TEMPLATE
+    """Path template for every replicated env prim, where ``{}`` is the environment index.
+
+    The regex form used to expand ``{ENV_REGEX_NS}`` cfg macros is
+    ``clone_template.format("[^/]+")``, which confines the slot to one path segment.
+    """
 
     replicate_physics: bool = True
     """Whether physics replication clones each environment. Default is True.

source/isaaclab/isaaclab/cloner/path.py

@@ -56,8 +56,8 @@ def split(template: str) -> tuple[str, str]:
 def match(path_expr: str, template: str) -> TemplateMatch | None:
     """Match ``path_expr`` against a destination template, capturing the instance slot.
 
-    The ``"{}"`` slot matches one path segment's worth of text, whether a concrete id (``3``)
-    or a wildcard (``.*``). Recovering that text is the only way to tell which instance a
+    The ``"{}"`` slot matches one path segment's worth of text: a concrete id (``3``) or a
+    wildcard standing for one segment (``.*``, ``[^/]+``). Recovering that text is the only way to tell which instance a
     concrete clone path belongs to without slicing the string by hand.
 
     Args:
@@ -73,7 +73,10 @@ def match(path_expr: str, template: str) -> TemplateMatch | None:
         TemplateMatch(instance='3', suffix='/base')
     """
     prefix, template_suffix = split(template)
-    pattern = re.compile(re.escape(prefix) + r"([^/]+)" + re.escape(template_suffix))
+    # the slot holds one segment's worth of text: a concrete id, or a wildcard standing for one.
+    # A segment-safe wildcard is written as a character class, whose text contains a '/' that is
+    # not a separator, so it is matched as a class rather than by the one-segment alternative.
+    pattern = re.compile(re.escape(prefix) + r"(\[\^?[^]]*\][*+?]?|[^/]+)" + re.escape(template_suffix))
     matched = pattern.match(path_expr)
     if matched is None:
         return None

source/isaaclab/isaaclab/cloner/query.py

@@ -214,7 +214,7 @@ def iter_sources(plan: ClonePlan, path_expr: str) -> Iterator[tuple[str, str, st
     Example:
         For a row with prototype root ``"/World/source/Robot"``, destination template
         ``"/World/scenes/{}/Robot"`` and env ids ``(0, 2)``, querying
-        ``"/World/scenes/.*/Robot/base"`` yields ``("/World/source/Robot",
+        ``"/World/scenes/[^/]*/Robot/base"`` yields ``("/World/source/Robot",
         "/World/scenes/{}/Robot", "/World/source/Robot/base", (0, 2))``.
 
     Args:

source/isaaclab/isaaclab/cloner/replicate_session.py

@@ -16,6 +16,7 @@
 from isaaclab.utils.version import has_kit
 
 from .clone_plan import make_clone_plan
+from .cloner_cfg import DEFAULT_ENV_TEMPLATE
 from .cloner_strategies import sequential
 from .usd import UsdReplicateContext
 
@@ -140,6 +141,7 @@ def __init__(
         clone_strategy: Callable = sequential,
         valid_set: torch.Tensor | None = None,
         replicate_physics: bool = True,
+        env_template: str = DEFAULT_ENV_TEMPLATE,
     ):
         """Capture arguments for :func:`make_clone_plan` and :func:`replicate`.
 
@@ -154,6 +156,7 @@ def __init__(
                 prototype combinations; ``None`` uses the full cartesian product.
             replicate_physics: Whether physics replication clones each environment;
                 forwarded to :func:`replicate`.
+            env_template: Path template for a replicated env prim, ``{}`` marking the env index.
         """
         self._cfgs = cfgs
         self._stage = stage
@@ -164,6 +167,7 @@ def __init__(
             device=device,
             clone_strategy=clone_strategy,
             valid_set=valid_set,
+            env_template=env_template,
         )
         self._plan: ClonePlan | None = None
 

source/isaaclab/isaaclab/envs/mdp/actions/task_space_actions.py

@@ -355,7 +355,7 @@ def has_rigid_body_api(prim) -> bool:
             if not rigid_matches:
                 raise ValueError(f"No descendant rigid body found under the expression: '{self._asset.cfg.prim_path}'.")
             _, root_rigidbody_path = rigid_matches[0]
-            task_frame_transformer_path = "/World/envs/env_.*/" + self.cfg.task_frame_rel_path
+            task_frame_transformer_path = "/World/envs/env_[^/]*/" + self.cfg.task_frame_rel_path
             task_frame_transformer_cfg = FrameTransformerCfg(
                 prim_path=root_rigidbody_path,
                 target_frames=[

source/isaaclab/isaaclab/envs/utils/camera_view.py

@@ -63,8 +63,8 @@ def env_path_from_template(path_template: str, env_id: int) -> str:
     if "{}" in path:
         return path.format(env_id)
     path = path.replace("/World/envs/*", f"/World/envs/env_{env_id}")
-    path = path.replace("/World/envs/env_.*", f"/World/envs/env_{env_id}")
-    path = path.replace("/World/envs/env_.*/", f"/World/envs/env_{env_id}/")
+    path = path.replace("/World/envs/env_[^/]*", f"/World/envs/env_{env_id}")
+    path = path.replace("/World/envs/env_[^/]*/", f"/World/envs/env_{env_id}/")
     return path
 
 
@@ -142,7 +142,7 @@ def create_visualizer_camera(
             attr = cam_prim.CreateAttribute("omni:scenePartition", Sdf.ValueTypeNames.Token)
         attr.Set(path.split("/")[-2])
     cfg = CameraCfg(
-        prim_path=f"/World/envs/env_.*/{camera_name}",
+        prim_path=f"/World/envs/env_[^/]*/{camera_name}",
         update_period=0.0,
         height=int(height),
         width=int(width),

source/isaaclab/isaaclab/scene/interactive_scene.py

@@ -159,9 +159,10 @@ def __init__(self, cfg: InteractiveSceneCfg):
         self.cloner_cfg = copy.deepcopy(self.cfg.clone_cfg)
         self.cloner_cfg.device = self.device
         self.cloner_cfg.replicate_physics = self.cfg.replicate_physics
-        self._env_regex_ns = self.cloner_cfg.clone_regex
-        self._env_fmt = self._env_regex_ns.replace(".*", "{}")
-        self._env_ns = self._env_regex_ns.rsplit("/", 1)[0]
+        # the template is authoritative; the regex form is the same namespace spelled for matching
+        self._env_fmt = self.cloner_cfg.clone_template
+        self._env_regex_ns = self._env_fmt.format("[^/]+")
+        self._env_ns = self._env_fmt.rsplit("/", 1)[0]
         self.env_prim_paths = [self._env_fmt.format(i) for i in range(self.cfg.num_envs)]
         self._scene_asset_names: list[str] = []
         self._clone_valid_set: torch.Tensor | None = None
@@ -189,6 +190,7 @@ def __init__(self, cfg: InteractiveSceneCfg):
             num_clones=self.num_envs,
             env_spacing=self.cfg.env_spacing,
             device=self.device,
+            env_template=self._env_fmt,
             stage=self.stage,
             clone_strategy=self.cloner_cfg.clone_strategy,
             valid_set=self._clone_valid_set,
@@ -225,7 +227,7 @@ def _collect_asset_cfgs(self) -> list[Any]:
             )
             for child in children:
                 if hasattr(child, "prim_path"):
-                    child.prim_path = child.prim_path.format(ENV_REGEX_NS=self.cloner_cfg.clone_regex)
+                    child.prim_path = child.prim_path.format(ENV_REGEX_NS=self._env_regex_ns)
                     if hasattr(child, "spawn") and child.spawn is not None and self.env_ns in child.prim_path:
                         clone_asset_names.append(asset_name)
                         variant_counts.append(cloner.num_spawn_variants(child.spawn))

source/isaaclab/isaaclab/scene_data/deformable_discovery.py

@@ -327,7 +327,7 @@ def path_to_env_wildcard(path: str) -> str:
 
 def path_to_env_regex(path: str) -> str:
     """Rewrite ``env_<id>`` segments to ``env_.*`` for Isaac Lab asset regex paths."""
-    return re.sub(r"/World/envs/env_\d+", "/World/envs/env_.*", path)
+    return re.sub(r"/World/envs/env_\d+", "/World/envs/env_[^/]*", path)
 
 
 def build_deformable_vertex_count_lookup(entries: list[DeformableStageEntry]) -> dict[str, int]: