Adds cloner support to Newton Model builder in Physx SDP (isaac-sim#4865)

# Description

<!--
Thank you for your interest in sending a pull request. Please make sure
to check the contribution guidelines.

Link:
https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html

💡 Please try to keep PRs small and focused. Large PRs are harder to
review and merge.
-->

- Adds cloner support to Newton Model builder in Physx SDP
- Adds a new scene data requirements file to improve & centralize newton
model / usd stage req tracking for visualizers & renderers
- Removesvisualizer cfg input from SDP
- Adds newton model cloner unit tests
- Adds docstrings to visualizers and SDP files (and files added in this
change)

<!-- 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)
- New feature (non-breaking change which adds functionality)


## Screenshots

Please attach before and after screenshots of the change if applicable.

<!--
Example:

| Before | After |
| ------ | ----- |
| _gif/png before_ | _gif/png after_ |

To upload images to a PR -- simply drag and drop an image while in edit
mode and it should upload the image directly. You can then paste that
source into the above before/after sections.
-->

## Checklist

- [ ] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [ ] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [ ] I have made corresponding changes to the documentation
- [ ] 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>
Co-authored-by: Antoine RICHARD <antoiner@nvidia.com>
Co-authored-by: Kelly Guo <kellyg@nvidia.com>

Author: 3 people

source/isaaclab/isaaclab/cloner/__init__.pyi

@@ -11,6 +11,7 @@ __all__ = [
     "filter_collisions",
     "grid_transforms",
     "make_clone_plan",
+    "resolve_visualizer_clone_fn",
     "usd_replicate",
 ]
 
@@ -21,5 +22,6 @@ from .cloner_utils import (
     filter_collisions,
     grid_transforms,
     make_clone_plan,
+    resolve_visualizer_clone_fn,
     usd_replicate,
 )

source/isaaclab/isaaclab/cloner/cloner_cfg.py

@@ -73,6 +73,9 @@ class TemplateCloneCfg:
     physics_clone_fn: callable | None = None
     """Function used to perform physics replication."""
 
+    visualizer_clone_fn: callable | None = None
+    """Optional function used to build precomputed visualizer artifacts from the clone plan."""
+
     clone_strategy: callable = random
     """Function used to build prototype-to-environment mapping. Default is :func:`random`."""
 

source/isaaclab/isaaclab/cloner/cloner_utils.py

@@ -6,18 +6,23 @@
 from __future__ import annotations
 
 import itertools
+import logging
 import math
+from collections.abc import Callable
 from typing import TYPE_CHECKING
 
 import torch
 
 from pxr import Gf, Sdf, Usd, UsdGeom, Vt
 
 import isaaclab.sim as sim_utils
+from isaaclab.physics.scene_data_requirements import SceneDataRequirement, VisualizerPrebuiltArtifacts
 
 if TYPE_CHECKING:
     from .cloner_cfg import TemplateCloneCfg
 
+logger = logging.getLogger(__name__)
+
 
 def clone_from_template(stage: Usd.Stage, num_clones: int, template_clone_cfg: TemplateCloneCfg) -> None:
     """Clone assets from a template root into per-environment destinations.
@@ -56,7 +61,7 @@ def clone_from_template(stage: Usd.Stage, num_clones: int, template_clone_cfg: T
         src_paths, dest_paths, clone_masking = make_clone_plan(src, dest, num_clones, cfg.clone_strategy, cfg.device)
 
         # Spawn the first instance of clones from prototypes, then deactivate the prototypes, those first instances
-        # will be served as sources for usd and physx replication.
+        # will be served as sources for usd and physics replication.
         proto_idx = clone_masking.to(torch.int32).argmax(dim=1)
         proto_mask = torch.zeros_like(clone_masking)
         proto_mask.scatter_(1, proto_idx.view(-1, 1).to(torch.long), clone_masking.any(dim=1, keepdim=True))
@@ -70,6 +75,8 @@ def clone_from_template(stage: Usd.Stage, num_clones: int, template_clone_cfg: T
             replicate_args = [clone_path_fmt.format(0)], [clone_path_fmt], world_indices, mapping
             if cfg.clone_physics and cfg.physics_clone_fn is not None:
                 cfg.physics_clone_fn(stage, *replicate_args, positions=positions, device=cfg.device)
+            if cfg.visualizer_clone_fn is not None:
+                cfg.visualizer_clone_fn(stage, *replicate_args, positions=positions, device=cfg.device)
             if cfg.clone_usd:
                 # parse env_origins directly from clone_path
                 usd_replicate(stage, *replicate_args, positions=positions)
@@ -79,6 +86,8 @@ def clone_from_template(stage: Usd.Stage, num_clones: int, template_clone_cfg: T
             replicate_args = selected_src, dest_paths, world_indices, clone_masking
             if cfg.clone_physics and cfg.physics_clone_fn is not None:
                 cfg.physics_clone_fn(stage, *replicate_args, positions=positions, device=cfg.device)
+            if cfg.visualizer_clone_fn is not None:
+                cfg.visualizer_clone_fn(stage, *replicate_args, positions=positions, device=cfg.device)
             if cfg.clone_usd:
                 usd_replicate(stage, *replicate_args)
 
@@ -156,14 +165,13 @@ def usd_replicate(
         positions: Optional positions (``[E, 3]``) -> ``xformOp:translate``.
         quaternions: Optional orientations (``[E, 4]``) in ``xyzw`` -> ``xformOp:orient``.
 
-    Returns:
-        None
     """
     rl = stage.GetRootLayer()
 
     # Group replication by destination path depth so ancestors land before deeper paths.
     # This avoids composition issues for nested or interdependent specs.
     def dp_depth(template: str) -> int:
+        """Return destination prim path depth for stable parent-first replication."""
         dp = template.format(0)
         return Sdf.Path(dp).pathElementCount
 
@@ -240,8 +248,6 @@ def filter_collisions(
         prim_paths: Per-clone prim paths.
         global_paths: Optional global-collider paths.
 
-    Returns:
-        None
     """
 
     scene_prim = stage.GetPrimAtPath(physicsscene_path)
@@ -375,3 +381,37 @@ def grid_transforms(N: int, spacing: float = 1.0, up_axis: str = "z", device="cp
     ori = torch.zeros((N, 4), device=device)
     ori[:, 3] = 1.0  # w=1 for identity quaternion
     return pos, ori
+
+
+def resolve_visualizer_clone_fn(
+    physics_backend: str,
+    requirements: SceneDataRequirement,
+    stage,
+    set_visualizer_artifact: Callable[[VisualizerPrebuiltArtifacts | None], None],
+):
+    """Return an optional visualizer prebuild hook for clone workflows.
+
+    Args:
+        physics_backend: Active physics backend name.
+        requirements: Aggregated scene-data requirements.
+        stage: USD stage used by the clone callback.
+        set_visualizer_artifact: Callback for storing prebuilt visualizer artifacts.
+
+    Returns:
+        Clone callback when the prebuild path is supported; otherwise ``None``.
+    """
+    if "physx" not in physics_backend or not requirements.requires_newton_model:
+        return None
+    try:
+        from isaaclab_newton.cloner.newton_replicate import (
+            create_newton_visualizer_prebuild_clone_fn,
+        )
+    except (ImportError, ModuleNotFoundError) as exc:
+        logger.warning("Visualizer prebuild hook unavailable: failed to import backend helper.")
+        logger.debug("Visualizer prebuild import failure details: %s", exc)
+        return None
+
+    return create_newton_visualizer_prebuild_clone_fn(
+        stage=stage,
+        set_visualizer_artifact=set_visualizer_artifact,
+    )

source/isaaclab/isaaclab/physics/scene_data_provider.py

@@ -23,7 +23,7 @@ class SceneDataProvider(FactoryBase, BaseSceneDataProvider):
     _backend_class_names = {"physx": "PhysxSceneDataProvider", "newton": "NewtonSceneDataProvider"}
 
     @classmethod
-    def _get_backend(cls, visualizer_cfgs, stage, simulation_context: SimulationContext, *args, **kwargs) -> str:
+    def _get_backend(cls, stage, simulation_context: SimulationContext, *args, **kwargs) -> str:
         manager_name = simulation_context.physics_manager.__name__.lower()
         if "newton" in manager_name:
             return "newton"
@@ -35,11 +35,9 @@ def _get_backend(cls, visualizer_cfgs, stage, simulation_context: SimulationCont
     def _get_module_name(cls, backend: str) -> str:
         return f"isaaclab_{backend}.scene_data_providers"
 
-    def __new__(
-        cls, visualizer_cfgs, stage, simulation_context: SimulationContext, *args, **kwargs
-    ) -> BaseSceneDataProvider:
+    def __new__(cls, stage, simulation_context: SimulationContext, *args, **kwargs) -> BaseSceneDataProvider:
         """Create a new scene data provider based on the active physics backend."""
-        result = super().__new__(cls, visualizer_cfgs, stage, simulation_context, *args, **kwargs)
+        result = super().__new__(cls, stage, simulation_context, *args, **kwargs)
         if not isinstance(result, BaseSceneDataProvider):
             name = type(result).__name__
             raise TypeError(f"Backend scene data provider {name!r} must inherit from BaseSceneDataProvider.")

source/isaaclab/isaaclab/physics/scene_data_requirements.py

@@ -0,0 +1,144 @@
+# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
+# All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Central requirement resolution for scene-data consumers.
+
+This module is intentionally type-based (not config-import based) so requirement
+checks stay robust even when optional backend packages are not installed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SceneDataRequirement:
+    """Capabilities required from a scene data provider."""
+
+    requires_newton_model: bool = False
+    requires_usd_stage: bool = False
+
+
+@dataclass(frozen=True)
+class VisualizerPrebuiltArtifacts:
+    """Prebuilt model/state payload shared from scene setup to providers.
+
+    This gets produced during clone-time visualizer prebuild and then read by
+    scene data providers as a fast path (instead of rebuilding from USD).
+    """
+
+    model: Any
+    state: Any
+    rigid_body_paths: list[str]
+    articulation_paths: list[str]
+    num_envs: int
+
+
+_VISUALIZER_REQUIREMENTS: dict[str, SceneDataRequirement] = {
+    "kit": SceneDataRequirement(requires_usd_stage=True),
+    "newton": SceneDataRequirement(requires_newton_model=True),
+    "rerun": SceneDataRequirement(requires_newton_model=True),
+    "viser": SceneDataRequirement(requires_newton_model=True),
+}
+
+_RENDERER_REQUIREMENTS: dict[str, SceneDataRequirement] = {
+    "isaac_rtx": SceneDataRequirement(requires_usd_stage=True),
+    "newton_warp": SceneDataRequirement(requires_newton_model=True),
+    "ovrtx": SceneDataRequirement(requires_newton_model=True, requires_usd_stage=True),
+}
+
+
+def supported_visualizer_types() -> tuple[str, ...]:
+    """Return supported visualizer type names in sorted order.
+
+    Returns:
+        Sorted tuple of supported visualizer type names.
+    """
+    return tuple(sorted(_VISUALIZER_REQUIREMENTS))
+
+
+def supported_renderer_types() -> tuple[str, ...]:
+    """Return supported renderer type names in sorted order.
+
+    Returns:
+        Sorted tuple of supported renderer type names.
+    """
+    return tuple(sorted(_RENDERER_REQUIREMENTS))
+
+
+def requirement_for_visualizer_type(visualizer_type: str) -> SceneDataRequirement:
+    """Resolve scene-data requirements for one visualizer type.
+
+    Args:
+        visualizer_type: Visualizer type name.
+
+    Returns:
+        Requirement object for the given visualizer type.
+
+    Raises:
+        ValueError: If ``visualizer_type`` is unknown.
+    """
+    requirement = _VISUALIZER_REQUIREMENTS.get(visualizer_type)
+    if requirement is None:
+        supported = ", ".join(repr(v) for v in supported_visualizer_types())
+        raise ValueError(f"Unknown visualizer type {visualizer_type!r}. Supported types: {supported}.")
+    return requirement
+
+
+def requirement_for_renderer_type(renderer_type: str) -> SceneDataRequirement:
+    """Resolve scene-data requirements for one renderer type.
+
+    Args:
+        renderer_type: Renderer type name.
+
+    Returns:
+        Requirement object for the given renderer type.
+
+    Raises:
+        ValueError: If ``renderer_type`` is unknown.
+    """
+    requirement = _RENDERER_REQUIREMENTS.get(renderer_type)
+    if requirement is None:
+        supported = ", ".join(repr(v) for v in supported_renderer_types())
+        raise ValueError(f"Unknown renderer type {renderer_type!r}. Supported types: {supported}.")
+    return requirement
+
+
+def aggregate_requirements(requirements: Iterable[SceneDataRequirement]) -> SceneDataRequirement:
+    """Combine a sequence of requirements using logical OR.
+
+    Args:
+        requirements: Requirement objects to combine.
+
+    Returns:
+        Combined requirement object.
+    """
+    requires_newton_model = False
+    requires_usd_stage = False
+    for requirement in requirements:
+        requires_newton_model |= requirement.requires_newton_model
+        requires_usd_stage |= requirement.requires_usd_stage
+    return SceneDataRequirement(requires_newton_model=requires_newton_model, requires_usd_stage=requires_usd_stage)
+
+
+def resolve_scene_data_requirements(
+    visualizer_types: Iterable[str],
+    renderer_types: Iterable[str] = (),
+) -> SceneDataRequirement:
+    """Resolve combined scene-data requirements from visualizer and renderer types.
+
+    Args:
+        visualizer_types: Visualizer type names to resolve.
+        renderer_types: Renderer type names to resolve.
+
+    Returns:
+        Combined requirement object.
+    """
+    requirements = [requirement_for_visualizer_type(viz_type) for viz_type in visualizer_types]
+    requirements.extend(requirement_for_renderer_type(renderer_type) for renderer_type in renderer_types)
+    return aggregate_requirements(requirements)