Add shared kinematic rigid-object renderer contract (#6308)

# Description

Revives #6308 on current `develop` and supersedes #3728 with a single
backend-neutral contract for kinematic rigid-object rendering.

## Architecture

`source/isaaclab/test/renderers/rigid_object_rendering_contract.py` is
the composition root. It owns the cloned scene, kinematic pose sequence,
depth measurements, and assertions. Package-local adapters own only
availability checks, simulation/renderer selection, and backend cleanup:

- Isaac RTX + PhysX on CPU and CUDA, with and without a coexisting
articulation;
- Newton Warp + PhysX on CUDA;
- OVRTX + OVPhysX on CUDA through both legacy and OVStage scene
ownership (OVStage runs when installed).

The dependency direction is adapter -> shared test contract -> public
Isaac Lab APIs. An AST architecture gate rejects backend imports in the
shared contract and rejects scene, asset, sensor, or class ownership in
adapters.

The contract creates two cloned instanceable DexCubes with root-level
nonuniform scale, verifies their depth silhouettes, moves both kinematic
bodies through the public rigid-object tensor API, verifies the physics
poses, and requires opposite rendered centroid displacement.

## Current-develop audit

Most production changes in the old PR have since landed through newer
ownership boundaries: Isaac RTX render-product lifetime in #6729, Newton
shadow-state copying in #6773, OVRTX scale-aware transform writes in
#7010, and Newton Fabric scale preservation in #7481. This revival
removes those stale patches rather than carrying duplicate
implementations.

The revived contract exposed one remaining OVRTX bug: composed scale was
captured only for clone-plan source paths, while OVRTX creates
non-source destinations after exporting the host USD stage. Those
destinations therefore defaulted to unit scale. As a deliberately
temporary bridge, this PR projects only captured non-unit scales through
the existing `isaaclab.cloner.query.path_env_ids` and `path_to_clone`
boundary using the already-validated `ClonePlan`; real destination
scales take precedence. It adds no plan fields, query APIs, renderer
configuration, or per-body fallback, and the bridge can be deleted as
one unit when SDP supplies composed scale aligned with canonical
rigid-body paths.

Historical context: [Isaac Sim forum
report](https://forums.developer.nvidia.com/t/rigidbody-prim-is-not-updated-in-rendering-pipeline-if-set-to-kinematic/346608).

## Type of change

- Bug fix
- Shared regression coverage

## Testing

- Isaac RTX contract: 4 passed (CUDA/CPU x articulation absent/present).
- Newton Warp contract: 1 passed.
- OVRTX contract: 2 passed (legacy and OVStage).
- OVRTX renderer unit surface: 167 passed.
- Core architecture and Newton visualization suites: 25 passed.
- OVRTX clone-plan suite: 17 passed.
- Cloner query and rendering-contract architecture suites: 87 passed.
- Controlled OVRTX regression: failed before the production fix with
clone silhouettes of 264 vs. 36 pixels; passed after the fix.
- Incoming #7462 NumPy-backed `ClonePlan` query-boundary smoke check:
passed unchanged, including non-dense environment ids.
- `uv run isaaclab -f`: all hooks passed against the exact upstream
`develop` base, including changelog validation.

## Checklist

- [x] I have read and understood the contribution guidelines
- [x] I have run the pre-commit checks
- [x] Documentation changes are not applicable
- [x] I have added unit and integration regression coverage
- [x] I have added changelog fragments for every touched package
- [x] My name is already present in `CONTRIBUTORS.md`

Author: ooctipus

source/isaaclab/changelog.d/ooctipus-kinematic-rigid-object-rendering.skip

@@ -0,0 +1 @@
+Tests only: no user-visible core package change.

source/isaaclab/test/renderers/rigid_object_rendering_contract.py

@@ -0,0 +1,222 @@
+# 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
+
+"""Backend-neutral kinematic rigid-object rendering contract.
+
+Backend test modules provide only a simulation context and renderer configuration.
+This module owns the scene, motion sequence, measurements, and assertions.
+"""
+
+from __future__ import annotations
+
+import gc
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+
+import torch
+
+import isaaclab.sim as sim_utils
+from isaaclab.actuators import ImplicitActuatorCfg
+from isaaclab.assets import ArticulationCfg, RigidObject, RigidObjectCfg
+from isaaclab.renderers import RendererCfg
+from isaaclab.scene import InteractiveScene, InteractiveSceneCfg
+from isaaclab.sensors.camera import Camera, CameraCfg
+from isaaclab.sim import SimulationContext
+from isaaclab.sim.schemas import UsdPhysicsRigidBodyCfg
+from isaaclab.utils.assets import ISAAC_NUCLEUS_DIR
+from isaaclab.utils.configclass import configclass
+
+__all__ = ["RigidObjectRenderingBackend", "run_rigid_object_scale_and_pose_rendering_contract"]
+
+_NUM_ENVS = 2
+_ENV_SPACING = 4.0
+_CAMERA_DISTANCE = 2.0
+_CAMERA_HEIGHT = 120
+_CAMERA_WIDTH = 160
+_OBJECT_SCALE = (1.0, 1.0, 8.0)
+_OBJECT_SHIFT = 0.45
+_MIN_OBJECT_DEPTH = 0.05
+_MAX_OBJECT_DEPTH = 10.0
+_MIN_OBJECT_PIXELS = 50
+_MIN_CENTROID_SHIFT = 10.0
+
+
+@dataclass(frozen=True)
+class RigidObjectRenderingBackend:
+    """Backend-owned inputs to the shared rendering contract."""
+
+    name: str
+    simulation_context_factory: Callable[[], AbstractContextManager[SimulationContext]]
+    renderer_cfg: RendererCfg
+    with_articulation: bool = False
+    cleanup: Callable[[], None] | None = None
+
+
+def _make_scene_cfg(backend: RigidObjectRenderingBackend) -> InteractiveSceneCfg:
+    """Create the scene whose rendered behavior is shared by every backend."""
+
+    @configclass
+    class _SceneCfg(InteractiveSceneCfg):
+        rigid_object: RigidObjectCfg = RigidObjectCfg(
+            prim_path="{ENV_REGEX_NS}/Object",
+            spawn=sim_utils.UsdFileCfg(
+                usd_path=f"{ISAAC_NUCLEUS_DIR}/Props/Blocks/DexCube/dex_cube_instanceable.usd",
+                rigid_props=[UsdPhysicsRigidBodyCfg(rigid_body_enabled=True, kinematic_enabled=True)],
+                scale=_OBJECT_SCALE,
+            ),
+        )
+        camera: CameraCfg = CameraCfg(
+            prim_path="{ENV_REGEX_NS}/Camera",
+            height=_CAMERA_HEIGHT,
+            width=_CAMERA_WIDTH,
+            update_period=0.0,
+            update_latest_camera_pose=True,
+            data_types=["depth"],
+            renderer_cfg=backend.renderer_cfg,
+            spawn=sim_utils.PinholeCameraCfg(
+                focal_length=24.0,
+                focus_distance=400.0,
+                horizontal_aperture=20.955,
+                clipping_range=(_MIN_OBJECT_DEPTH, 100.0),
+            ),
+        )
+        if backend.with_articulation:
+            articulation: ArticulationCfg = ArticulationCfg(
+                prim_path="{ENV_REGEX_NS}/Articulation",
+                spawn=sim_utils.UsdFileCfg(
+                    usd_path=f"{ISAAC_NUCLEUS_DIR}/Robots/IsaacSim/SimpleArticulation/revolute_articulation.usd"
+                ),
+                init_state=ArticulationCfg.InitialStateCfg(pos=(0.0, -20.0, 0.0)),
+                actuators={
+                    "joint": ImplicitActuatorCfg(joint_names_expr=[".*"], stiffness=100.0, damping=1.0),
+                },
+            )
+
+    return _SceneCfg(num_envs=_NUM_ENVS, env_spacing=_ENV_SPACING, lazy_sensor_update=False)
+
+
+def _require(condition: torch.Tensor | bool, message: str) -> None:
+    """Raise a diagnostic assertion instead of relying on pytest rewriting this helper."""
+    if not bool(condition):
+        raise AssertionError(message)
+
+
+def _measure_depth_mask(
+    depth: torch.Tensor, backend_name: str, camera: Camera
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Return silhouette height, width, and horizontal centroid for every camera."""
+    depth_image = depth[..., 0]
+    valid = torch.isfinite(depth_image) & (depth_image > _MIN_OBJECT_DEPTH) & (depth_image < _MAX_OBJECT_DEPTH)
+    pixel_counts = valid.sum(dim=(1, 2))
+    finite = torch.where(torch.isfinite(depth_image), depth_image, torch.zeros_like(depth_image))
+    diagnostics = (
+        f"depth min={finite.amin(dim=(1, 2)).tolist()} max={finite.amax(dim=(1, 2)).tolist()} "
+        f"finite%={(torch.isfinite(depth_image).float().mean(dim=(1, 2)) * 100).tolist()} "
+        f"camera pos_w={camera.data.pos_w.torch.tolist()}"
+    )
+    _require(
+        torch.all(pixel_counts >= _MIN_OBJECT_PIXELS),
+        f"[{backend_name}] Expected at least {_MIN_OBJECT_PIXELS} object pixels per camera, "
+        f"got {pixel_counts.tolist()}; {diagnostics}.",
+    )
+
+    silhouette_heights = valid.any(dim=2).sum(dim=1)
+    silhouette_widths = valid.any(dim=1).sum(dim=1)
+    image_x = torch.arange(depth.shape[2], device=depth.device, dtype=torch.float32)
+    centroids_x = (valid * image_x.view(1, 1, -1)).sum(dim=(1, 2)) / pixel_counts
+    return silhouette_heights, silhouette_widths, centroids_x
+
+
+def _write_pose_and_render(
+    sim: SimulationContext,
+    scene: InteractiveScene,
+    rigid_object: RigidObject,
+    camera: Camera,
+    root_poses: torch.Tensor,
+) -> torch.Tensor:
+    """Write a kinematic pose, settle renderer state, and return depth."""
+    rigid_object.write_root_pose_to_sim_index(root_pose=root_poses)
+    for _ in range(3):
+        sim.step()
+        scene.update(sim.cfg.dt)
+    torch.testing.assert_close(rigid_object.data.root_link_pose_w.torch, root_poses, rtol=0.0, atol=1.0e-4)
+    return camera.data.output["depth"].torch.clone()
+
+
+def run_rigid_object_scale_and_pose_rendering_contract(backend: RigidObjectRenderingBackend) -> None:
+    """Assert root-scale preservation and pose-to-pixel synchronization."""
+    with backend.simulation_context_factory() as sim:
+        sim._app_control_on_stop_handle = None
+        scene = InteractiveScene(_make_scene_cfg(backend))
+        sim.register_interactive_scene(scene)
+        rigid_object = scene["rigid_object"]
+        camera = scene["camera"]
+
+        try:
+            sim.reset()
+            scene.reset()
+            _require(rigid_object.is_initialized, f"[{backend.name}] Rigid object did not initialize.")
+            if backend.with_articulation:
+                _require(scene["articulation"].is_initialized, f"[{backend.name}] Articulation did not initialize.")
+
+            camera_eyes = scene.env_origins.clone()
+            camera_eyes[:, 1] -= _CAMERA_DISTANCE
+            camera.set_world_poses_from_view(camera_eyes, scene.env_origins)
+
+            center_poses = torch.zeros((_NUM_ENVS, 7), device=rigid_object.device)
+            center_poses[:, :3] = scene.env_origins
+            center_poses[:, 6] = 1.0
+
+            center_depth = _write_pose_and_render(sim, scene, rigid_object, camera, center_poses)
+            center_heights, center_widths, center_centroids = _measure_depth_mask(center_depth, backend.name, camera)
+            _require(
+                torch.all(center_heights > 3 * center_widths),
+                f"[{backend.name}] Expected root-scaled cubes to render as tall silhouettes, got "
+                f"heights={center_heights.tolist()} and widths={center_widths.tolist()}.",
+            )
+            _require(
+                torch.all(center_heights > _CAMERA_HEIGHT // 4),
+                f"[{backend.name}] Expected root-scaled silhouettes to span more than one quarter of the image, "
+                f"got heights={center_heights.tolist()}.",
+            )
+            _require(
+                torch.all(torch.abs(center_centroids - (_CAMERA_WIDTH - 1) / 2) < 8.0),
+                f"[{backend.name}] Expected centered silhouettes, got centroids={center_centroids.tolist()}.",
+            )
+
+            negative_poses = center_poses.clone()
+            negative_poses[:, 0] -= _OBJECT_SHIFT
+            negative_depth = _write_pose_and_render(sim, scene, rigid_object, camera, negative_poses)
+            _, _, negative_centroids = _measure_depth_mask(negative_depth, backend.name, camera)
+
+            positive_poses = center_poses.clone()
+            positive_poses[:, 0] += _OBJECT_SHIFT
+            positive_depth = _write_pose_and_render(sim, scene, rigid_object, camera, positive_poses)
+            _, _, positive_centroids = _measure_depth_mask(positive_depth, backend.name, camera)
+
+            negative_delta = negative_centroids - center_centroids
+            positive_delta = positive_centroids - center_centroids
+            _require(
+                torch.all(negative_delta.abs() > _MIN_CENTROID_SHIFT),
+                f"[{backend.name}] Negative-shift centroids moved too little: {negative_delta.tolist()}.",
+            )
+            _require(
+                torch.all(positive_delta.abs() > _MIN_CENTROID_SHIFT),
+                f"[{backend.name}] Positive-shift centroids moved too little: {positive_delta.tolist()}.",
+            )
+            _require(
+                torch.all(negative_delta * positive_delta < 0.0),
+                f"[{backend.name}] Opposite translations must move silhouettes in opposite directions, got "
+                f"deltas {negative_delta.tolist()} and {positive_delta.tolist()}.",
+            )
+        finally:
+            sim.register_interactive_scene(None)
+            # Release camera-owned render products before another parametrized case creates a stage.
+            camera._invalidate_initialize_callback(None)  # noqa: SLF001
+            del camera, rigid_object, scene
+            gc.collect()
+            if backend.cleanup is not None:
+                backend.cleanup()

source/isaaclab/test/renderers/test_rigid_object_rendering_contract_architecture.py

@@ -0,0 +1,66 @@
+# 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
+
+"""Architecture gates for the shared rigid-object rendering contract."""
+
+import ast
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[4]
+_CONTRACT = Path(__file__).with_name("rigid_object_rendering_contract.py")
+_ADAPTERS = (
+    _REPO_ROOT / "source/isaaclab_physx/test/renderers/test_isaac_rtx_renderer_rigid_object_rendering.py",
+    _REPO_ROOT / "source/isaaclab_newton/test/renderers/test_newton_warp_renderer_rigid_object_rendering.py",
+    _REPO_ROOT / "source/isaaclab_ov/test/test_ovrtx_renderer_rigid_object_rendering.py",
+)
+
+
+def _imported_modules(tree: ast.AST) -> set[str]:
+    modules = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            modules.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module is not None:
+            modules.add(node.module)
+    return modules
+
+
+def test_shared_contract_does_not_depend_on_backend_packages() -> None:
+    """Optional backends depend on the contract; the core contract never points back."""
+    tree = ast.parse(_CONTRACT.read_text(encoding="utf-8"))
+    forbidden_roots = {"isaaclab_newton", "isaaclab_ov", "isaaclab_ovphysx", "isaaclab_physx", "newton", "ovrtx"}
+    imported_roots = {module.split(".", 1)[0] for module in _imported_modules(tree)}
+
+    assert imported_roots.isdisjoint(forbidden_roots), imported_roots & forbidden_roots
+
+
+def test_backend_adapters_do_not_duplicate_scene_ownership() -> None:
+    """Adapters may select backends, but scene construction and assertions stay shared."""
+    for adapter in _ADAPTERS:
+        tree = ast.parse(adapter.read_text(encoding="utf-8"))
+        modules = _imported_modules(tree)
+        forbidden = {
+            module
+            for module in modules
+            if module == "isaaclab.assets"
+            or module.startswith("isaaclab.assets.")
+            or module == "isaaclab.scene"
+            or module.startswith("isaaclab.scene.")
+            or module == "isaaclab.sensors"
+            or module.startswith("isaaclab.sensors.")
+        }
+        contract_calls = [
+            node
+            for node in ast.walk(tree)
+            if isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Name)
+            and node.func.id == "run_rigid_object_scale_and_pose_rendering_contract"
+        ]
+
+        assert not forbidden, f"{adapter.relative_to(_REPO_ROOT)} duplicates contract ownership: {forbidden}"
+        assert len(contract_calls) == 1, f"{adapter.relative_to(_REPO_ROOT)} must compose the shared contract once"
+        assert not any(isinstance(node, ast.ClassDef) for node in ast.walk(tree)), (
+            f"{adapter.relative_to(_REPO_ROOT)} must not define backend-local scene classes"
+        )

source/isaaclab/test/sim/test_newton_manager_visualization_state.py

@@ -561,6 +561,49 @@ def test_resolve_scene_data_body_paths_uses_joint_body_targets():
     assert resolved_paths == ["/World/envs/env_0/Robot/robot0_forearm"]
 
 
+def test_update_visualization_state_copies_identity_mapped_transforms(monkeypatch):
+    """Identity-mapped transforms update the persistent Newton shadow buffer."""
+    import numpy as np
+    import warp as wp
+    from isaaclab_newton.physics import NewtonManager
+
+    from isaaclab.scene_data import SceneDataFormat, SceneDataProvider
+
+    _reset_newton_manager_state()
+    monkeypatch.setattr(NewtonManager, "_backend_is_newton", classmethod(lambda cls, provider=None: False))
+
+    body_paths = ["/World/envs/env_0/Object", "/World/envs/env_1/Object"]
+    source_transforms = wp.array(
+        [
+            [1.0, 2.0, 3.0, 0.0, 0.0, 0.0, 1.0],
+            [4.0, 5.0, 6.0, 0.0, 0.0, 0.0, 1.0],
+        ],
+        dtype=wp.transformf,
+        device="cpu",
+    )
+    source_data = SceneDataFormat.Transform()
+    source_data.transforms = source_transforms
+    provider_impl = SceneDataProvider(
+        SimpleNamespace(transforms=source_data, transform_paths=body_paths, transform_count=len(body_paths))
+    )
+    provider = SimpleNamespace(
+        usd_stage=None,
+        create_mapping=provider_impl.create_mapping,
+        get_transforms=provider_impl.get_transforms,
+        point_count=0,
+    )
+
+    destination = wp.zeros(len(body_paths), dtype=wp.transformf, device="cpu")
+    NewtonManager._model = SimpleNamespace(body_label=body_paths, body_count=len(body_paths))
+    NewtonManager._state_0 = SimpleNamespace(body_q=destination, particle_q=None)
+
+    NewtonManager.update_visualization_state(provider)
+
+    assert NewtonManager._state_0.body_q is destination
+    assert NewtonManager._scene_data.transforms is destination
+    np.testing.assert_allclose(destination.numpy(), source_transforms.numpy())
+
+
 def test_update_visualization_state_syncs_shadow_particle_q(monkeypatch):
     """PhysX/OVPhysX shadow sync copies backend points into ``state.particle_q``.
 

source/isaaclab_newton/changelog.d/ooctipus-kinematic-rigid-object-rendering.skip

@@ -0,0 +1 @@
+Tests only: no user-visible Newton package change.

source/isaaclab_newton/test/renderers/test_newton_warp_renderer_rigid_object_rendering.py

@@ -0,0 +1,44 @@
+# 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
+
+"""Newton Warp adapter for the shared rigid-object rendering contract."""
+
+import sys
+from pathlib import Path
+
+from isaaclab.app import AppLauncher
+
+simulation_app = AppLauncher(headless=True, enable_cameras=True).app
+
+"""Rest everything follows."""
+
+import pytest
+from isaaclab_newton.physics import NewtonManager
+from isaaclab_newton.renderers import NewtonWarpRendererCfg
+
+from isaaclab.sim import build_simulation_context
+
+_CONTRACT_DIR = Path(__file__).resolve().parents[3] / "isaaclab" / "test" / "renderers"
+if str(_CONTRACT_DIR) not in sys.path:
+    sys.path.insert(0, str(_CONTRACT_DIR))
+
+from rigid_object_rendering_contract import (  # noqa: E402
+    RigidObjectRenderingBackend,
+    run_rigid_object_scale_and_pose_rendering_contract,
+)
+
+pytestmark = [pytest.mark.integration, pytest.mark.rendering, pytest.mark.isaacsim_ci]
+
+
+def test_kinematic_rigid_object_scale_and_pose_are_rendered() -> None:
+    """Kinematic PhysX transforms and root scale must reach Newton Warp."""
+    run_rigid_object_scale_and_pose_rendering_contract(
+        RigidObjectRenderingBackend(
+            name="newton_warp (PhysX)",
+            simulation_context_factory=lambda: build_simulation_context(device="cuda:0", gravity_enabled=False),
+            renderer_cfg=NewtonWarpRendererCfg(),
+            cleanup=NewtonManager.clear,
+        )
+    )

source/isaaclab_ov/changelog.d/ooctipus-kinematic-rigid-object-rendering.rst

@@ -0,0 +1,4 @@
+Fixed
+^^^^^
+
+* Fixed OVRTX transform synchronization dropping authored scale from clone-plan destinations.