Fixes Newton cloner ignoring collision approximation (#6596)

# Description

The Newton cloner throws away whatever `physics:approximation` an asset
authors on its collision meshes: it imports USD with
`skip_mesh_approximation=True`, then convex-hulls everything. So in
cloned envs a concave part always collides as one convex blob, with no
warning. Plain scene loading honors the attribute, so the two paths
didn't even agree with each other.

Two changes:

- Cloner now lets Newton process authored approximations, and only runs
the default convex-hull pass on meshes that don't author one.
- `coacd` is now a core dependency. Without it `convexDecomposition`
just warns and falls back to a single hull. Kit-based installs already
get it via isaacsim (which pins 1.0.7, hence the floor); this covers
kit-less installs.

| Before | After |
|---|---|
| Cloned envs: every authored mode collapses to one convex hull,
silently | `convexDecomposition` -> multiple hulls, `boundingSphere` ->
sphere, `boundingCube` -> box, `meshSimplification`/`none` -> mesh |
| Plain scenes: `convexDecomposition` falls back to one hull (no
`coacd`) | Decomposes out of the box |
| Concave L-prism (volume 3.0) collides as its filled hull (volume 3.5)
| Decomposed hulls preserve the exact shape |

Tests: cloner unit tests, plus an install-CI probe that runs after
`./isaaclab.sh -i core` and fails on either regression (verified failing
before the fix, passing after).

## Reproduction

1. Author a concave collision mesh with `physics:approximation =
"convexDecomposition"` (`UsdPhysics.MeshCollisionAPI`).
2. Load it in a cloned env with the Newton backend, or run `python
source/isaaclab/test/install_ci/misc/convex_decomposition_probe.py` in
an installed environment.
3. Before: one convex hull, concavity filled in. After: multi-hull
decomposition on both import paths.

## 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
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have added a changelog fragment under
`source/<pkg>/changelog.d/` for every touched package (do **not** edit
`CHANGELOG.rst` or bump `extension.toml` — CI handles that)
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

Author: myurasov-nv

pyproject.toml

@@ -84,7 +84,9 @@ dependencies = [
     # ----- newton (default physics engine) -----
     # Loose bound so the wheel co-resolves with isaacsim's newton[sim]==1.2.0 pin; the
     # exact git commit is forced via [tool.uv].override-dependencies (uv sync only).
-    "newton[sim]>=1.2.0",
+    # The importers extra carries the mesh-processing deps (coacd, fast-simplification,
+    # ...) that honoring USD-authored ``physics:approximation`` requires.
+    "newton[sim,importers]>=1.2.0",
     # Loose bound co-resolves with isaacsim's ==0.2.0; the override below forces >=0.3.1.
     "newton-usd-schemas>=0.2.0",
     "PyOpenGL-accelerate>=3.1.0",
@@ -334,7 +336,7 @@ prerelease = "allow"
 # the CUDA indexes via [tool.uv.sources]. Values mirror [tool.isaaclab.versions] above.
 override-dependencies = [
     "numpy>=2",
-    "newton[sim] @ git+https://github.com/newton-physics/newton.git@c7ae7c7648cd0717df39e5c94b95d5a02c997320",
+    "newton[sim,importers] @ git+https://github.com/newton-physics/newton.git@c7ae7c7648cd0717df39e5c94b95d5a02c997320",
     # Force the Newton-matched schemas over isaacsim's ==0.2.0 pin.
     "newton-usd-schemas>=0.3.1",
     "torch==2.11.0",

source/isaaclab/changelog.d/my-newton-collision-approximation.skip

@@ -0,0 +1 @@
+Internal: added an install-CI probe for USD-authored convex decomposition.

source/isaaclab/test/cli/test_install.py

@@ -264,7 +264,7 @@ def fake_run(cmd, *args, **kwargs):
         install_cmds = [cmd for cmd in calls if "install" in cmd]
         assert install_cmds, "expected a pip install call"
         install_args = install_cmds[-1]
-        assert any(arg.startswith("newton[sim]") and arg.endswith(commit) for arg in install_args)
+        assert any(arg.startswith("newton[sim,importers]") and arg.endswith(commit) for arg in install_args)
         assert any(arg.startswith("newton-usd-schemas") for arg in install_args), "schemas must be forced too"
 
     def test_skips_when_commit_already_installed(self):

source/isaaclab/test/cli/test_uv_run_pyproject.py

@@ -133,8 +133,9 @@ def test_uv_run_base_dependencies_cover_newton_rsl_rl_training():
     dependencies = _root_pyproject()["project"]["dependencies"]
 
     # Newton is the default physics engine and RSL-RL the default training library,
-    # so both ship as core third-party requirements (not opt-in extras).
-    assert any(dep.startswith("newton[sim]") for dep in dependencies)
+    # so both ship as core third-party requirements (not opt-in extras). The importers
+    # extra carries the mesh-processing deps that authored collision approximations need.
+    assert any(dep.startswith("newton[sim,importers]") for dep in dependencies)
     assert any(dep.startswith("rsl-rl-lib") for dep in dependencies)
 
 

source/isaaclab/test/install_ci/cli/test_cli_install_core_in_uvenv_correctness.py

@@ -10,6 +10,8 @@
     - ./isaaclab.sh -i core -> verify all core packages importable
     - ./isaaclab.sh -i core -> verify optional submodules (mimic, teleop, ovrtx, ovphysx) NOT installed
     - ./isaaclab.sh -i core -> verify isaaclab_physx test suite passes
+    - ./isaaclab.sh -i core -> verify the Newton importer mesh-processing dependencies
+      (coacd, fast-simplification) are installed
 """
 
 from __future__ import annotations
@@ -95,6 +97,31 @@ def test_install_core_omits_optional_submodules(self, isaaclab_root):
         finally:
             self.destroy_uv_env()
 
+    @pytest.mark.install_path_cli
+    @pytest.mark.uv
+    @pytest.mark.slow
+    @pytest.mark.timeout(1800)
+    def test_install_core_provides_newton_importer_dependencies(self, isaaclab_root):
+        """Newton's mesh-processing deps ship with -i core (via newton[sim,importers]).
+
+        Without them, Newton warns and falls back to a single convex hull instead of
+        honoring an authored ``physics:approximation`` (behavior is unit-tested in
+        isaaclab_newton's test_collision_approximation.py).
+        """
+        try:
+            self.create_uv_env(isaaclab_root)
+
+            result = self.run_in_uv_env([str(self.cli_script), "-i", "core"], cwd=isaaclab_root)
+            assert result.returncode == 0, f"isaaclab -i core failed:\n{result.stdout}\n{result.stderr}"
+
+            result = self.run_in_uv_env(["python", "-c", "import coacd, fast_simplification"])
+            assert result.returncode == 0, (
+                f"Newton importer mesh-processing deps missing:\n{result.stdout}\n{result.stderr}"
+            )
+
+        finally:
+            self.destroy_uv_env()
+
     @pytest.mark.install_path_cli
     @pytest.mark.uv
     @pytest.mark.gpu

source/isaaclab_newton/changelog.d/my-newton-collision-approximation.rst

@@ -0,0 +1,13 @@
+Fixed
+^^^^^
+
+* Fixed the Newton cloner discarding USD-authored ``physics:approximation`` on
+  collision meshes: cloned environments flattened every collision mesh to a single
+  convex hull regardless of the authored mode (``convexDecomposition``,
+  ``boundingSphere``, ``boundingCube``, ``meshSimplification``, or ``none``),
+  without a warning. The cloner now honors authored approximations the same way
+  non-cloned scene loading does, and applies the default convex-hull simplification
+  only to meshes with no authored approximation. Also switched the core install to
+  ``newton[sim,importers]`` so the mesh-processing dependencies (``coacd``,
+  ``fast-simplification``, ...) ship by default and ``convexDecomposition``
+  decomposes instead of silently falling back to a single convex hull.

source/isaaclab_newton/isaaclab_newton/cloner/newton_clone_utils.py

@@ -5,18 +5,68 @@
 
 from __future__ import annotations
 
+import warnings
 from collections.abc import Callable, Sequence
 from typing import Any
 
 import torch
 import warp as wp
-from newton import ModelBuilder, solvers
+from newton import GeoType, ModelBuilder, ShapeFlags, solvers
 
-from pxr import Usd
+from pxr import Usd, UsdPhysics
 
 from isaaclab.cloner.cloner_utils import replace_path_prefix
 from isaaclab.sim.utils.newton_model_utils import replace_newton_builder_shape_colors
 
+# USD ``physics:approximation`` token (lower case) -> Newton remeshing method.
+# Mirrors Newton's own importer mapping; ``none`` keeps the raw trimesh.
+_APPROXIMATION_TO_REMESHING_METHOD = {
+    "convexdecomposition": "coacd",
+    "convexhull": "convex_hull",
+    "boundingsphere": "bounding_sphere",
+    "boundingcube": "bounding_box",
+    "meshsimplification": "quadratic",
+}
+
+
+def _authored_collision_approximations(stage: Usd.Stage) -> dict[str, str]:
+    """Prim path -> authored ``physics:approximation`` token (lower case).
+
+    SDF collision prims are excluded: the attribute has no meaning on a shape with
+    ``NewtonSDFCollisionAPI`` applied (matching Newton's importer semantics).
+    """
+    authored: dict[str, str] = {}
+    for prim in stage.Traverse():
+        attr = UsdPhysics.MeshCollisionAPI(prim).GetApproximationAttr()
+        if attr and attr.HasAuthoredValue() and "NewtonSDFCollisionAPI" not in prim.GetAppliedSchemas():
+            authored[prim.GetPath().pathString] = str(attr.Get()).lower()
+    return authored
+
+
+def _apply_authored_approximations(builder: ModelBuilder, path_shape_map: dict, authored: dict[str, str]) -> set[int]:
+    """Remesh authored collision shapes (visual shapes preserved); return their indices."""
+    authored_shape_indices: set[int] = set()
+    for path, mode in authored.items():
+        index = path_shape_map.get(path)
+        if index is None:
+            continue
+        authored_shape_indices.add(index)
+        method = _APPROXIMATION_TO_REMESHING_METHOD.get(mode)
+        if method is not None:
+            builder.approximate_meshes(method, shape_indices=[index], keep_visual_shapes=True)
+    return authored_shape_indices
+
+
+def _unauthored_collision_mesh_shapes(builder: ModelBuilder, authored_shape_indices: set[int]) -> list[int]:
+    """Colliding mesh shapes not covered by an authored ``physics:approximation``."""
+    return [
+        index
+        for index, shape_type in enumerate(builder.shape_type)
+        if shape_type == GeoType.MESH
+        and (builder.shape_flags[index] & ShapeFlags.COLLIDE_SHAPES)
+        and index not in authored_shape_indices
+    ]
+
 
 def build_source_builders(
     stage: Usd.Stage,
@@ -27,27 +77,76 @@ def build_source_builders(
     ignore_paths: Sequence[str] | None = None,
     simplify_meshes: bool = True,
 ) -> dict[str, ModelBuilder]:
-    """Build one Newton builder for each clone source prim path."""
-    builders: dict[str, ModelBuilder] = {}
-    for source in sources:
-        builder = create_builder()
-        solvers.SolverMuJoCo.register_custom_attributes(builder)
-        solvers.SolverKamino.register_custom_attributes(builder)
-        builder.add_usd(
-            stage,
-            root_path=source,
-            load_visual_shapes=True,
-            skip_mesh_approximation=True,
-            schema_resolvers=schema_resolvers,
-            ignore_paths=ignore_paths,
+    """Build one Newton builder for each clone source prim path.
+
+    USD-authored ``physics:approximation`` modes are honored (applied after import so
+    visual shapes are preserved for visualization/rendering). Exception: when the
+    honored modes leave multiple sources with differing shape-type sequences (e.g.
+    heterogeneous asset variants), every mesh falls back to the uniform convex-hull
+    treatment, because :class:`SolverMuJoCo` requires homogeneous worlds.
+    """
+    authored = _authored_collision_approximations(stage)
+    builders = {
+        source: _build_source_builder(
+            stage, source, create_builder, schema_resolvers, ignore_paths, simplify_meshes, authored
         )
-        if simplify_meshes:
-            builder.approximate_meshes("convex_hull", keep_visual_shapes=True)
-        replace_newton_builder_shape_colors(builder, stage)
-        builders[source] = builder
+        for source in sources
+    }
+
+    if authored and len(builders) > 1:
+        shape_sequences = {tuple(int(t) for t in b.shape_type) for b in builders.values()}
+        if len(shape_sequences) > 1:
+            warnings.warn(
+                "Clone sources have differing collision shape sequences after honoring authored"
+                " physics:approximation modes, which SolverMuJoCo's homogeneous-worlds requirement"
+                " does not support. Falling back to uniform convex-hull approximation for all"
+                " collision meshes.",
+                stacklevel=2,
+            )
+            builders = {
+                source: _build_source_builder(
+                    stage, source, create_builder, schema_resolvers, ignore_paths, simplify_meshes, {}
+                )
+                for source in sources
+            }
     return builders
 
 
+def _build_source_builder(
+    stage: Usd.Stage,
+    source: str,
+    create_builder: Callable[[], ModelBuilder],
+    schema_resolvers: Sequence[Any],
+    ignore_paths: Sequence[str] | None,
+    simplify_meshes: bool,
+    authored: dict[str, str],
+) -> ModelBuilder:
+    """Build one source builder; an empty ``authored`` map restores hull-everything."""
+    builder = create_builder()
+    solvers.SolverMuJoCo.register_custom_attributes(builder)
+    solvers.SolverKamino.register_custom_attributes(builder)
+    import_result = builder.add_usd(
+        stage,
+        root_path=source,
+        load_visual_shapes=True,
+        skip_mesh_approximation=True,
+        schema_resolvers=schema_resolvers,
+        ignore_paths=ignore_paths,
+    )
+    if authored:
+        authored_shape_indices = _apply_authored_approximations(builder, import_result["path_shape_map"], authored)
+        if simplify_meshes:
+            builder.approximate_meshes(
+                "convex_hull",
+                shape_indices=_unauthored_collision_mesh_shapes(builder, authored_shape_indices),
+                keep_visual_shapes=True,
+            )
+    elif simplify_meshes:
+        builder.approximate_meshes("convex_hull", keep_visual_shapes=True)
+    replace_newton_builder_shape_colors(builder, stage)
+    return builder
+
+
 def replicate_builder_mapping(
     builder: ModelBuilder,
     sources: Sequence[str],