[OVPHYSX] ContactSensor

[AntoineRichard]

Description

Implements ContactSensor, ContactSensorCfg, and ContactSensorData for the isaaclab_ovphysx backend, mirroring the existing PhysX implementation.

The contact sensor reports normal contact forces in the world frame using the ovphysx 0.3.7 ContactBinding API (PhysX.create_contact_binding / read_net_forces / read_force_matrix). Optional pose tracking is wired through a RIGID_BODY_POSE TensorBinding.

Validation environment: Isaac-Velocity-Flat-Anymal-C-Direct-v0 (Anymal-C foot-contact tracking for locomotion).

v1 scope (this PR):

• Net contact forces + history
• Force matrix (filtered partner forces) + history
• Pose tracking (track_pose)
• Air/contact time tracking + compute_first_contact / compute_first_air
• Reset semantics + native handle teardown on simulation stop

Deferred (raise NotImplementedError if cfg flag enabled):

• track_contact_points
• track_friction_forces

These features are blocked on tensor-friendly per-sensor read APIs in ovphysx (ContactBinding.read_contact_points / read_friction_forces). A maintainer-facing spec listing the missing APIs is attached at docs/superpowers/specs/2026-04-27-ovphysx-contact-api-gaps.md. The data properties still return None per the BaseContactSensorData contract; the implementation only raises if the cfg flag is set.

Fixes #5325
Parent issue: #5315

Stacked on:

• [OVPHYSX] Articulation rewrite (data class + asset class + kernels) #5459 ([OVPHYSX] Articulation rewrite) — this branch is rebased on top of antoiner/feat/ovphysx_articulation. Reviewers can focus on the last 13 commits (everything from Scaffold isaaclab_ovphysx sensors sub-package onward); commits before that are inherited from [OVPHYSX] Articulation rewrite (data class + asset class + kernels) #5459. Will be re-rebased on develop once [OVPHYSX] Articulation rewrite (data class + asset class + kernels) #5459 merges.

Dependencies:

• Requires ovphysx backend integration #4852 (merged into develop 2026-04-20).
• ovphysx RigidObject lands as part of [OVPHYSX] Articulation rewrite (data class + asset class + kernels) #5459 — no separate gate.

Type of change

• New feature (non-breaking change which adds functionality)

Screenshots

N/A — backend feature, no UI surface.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation (changelog fragment at source/isaaclab_ovphysx/changelog.d/antoiner-feat-ovphysx_contactsensor.minor.rst, docstrings, gap spec for the maintainer of ovphysx)
• My changes generate no new warnings
• I have added tests that prove my feature works (9 tests adapted from the PhysX backend; 3 skipped for the deferred features so they're trivially un-skip-able once ovphysx ships the missing APIs)
• I have updated the changelog and the corresponding version in the extension's config/extension.toml file (changelog fragment, minor tier — version bump compiled by the nightly CI workflow per the upstream convention)
• I have added my name to the CONTRIBUTORS.md or my name already exists there

Notes for the reviewer

• The Warp kernels (sensors/contact_sensor/kernels.py and the shared sensors/kernels.py) are physics-engine-agnostic and ported verbatim from the PhysX backend — only module docstrings differ.
• ContactSensorCfg and ContactSensorData are also near-verbatim mirrors; the only edits are the backend-specific class_type pointer and the shared-kernels import path.
• The ovphysx-specific glue lives in _initialize_impl (USD prim discovery + regex→fnmatch glob conversion + create_contact_binding + optional RIGID_BODY_POSE binding), _create_buffers (pre-allocated DLPack read buffers), _update_buffers_impl (per-step reads), and _invalidate_initialize_callback (native handle release).
• Tests not yet executed. They are currently authored in the Isaac-Sim/AppLauncher style (mirroring isaaclab_physx/test/sensors/test_contact_sensor.py); they need to be re-adapted to the kitless ./scripts/run_ovphysx.sh -m pytest flow and the _ovphysx_sim_context helper used by the articulation/rigid-object suites in [OVPHYSX] Articulation rewrite (data class + asset class + kernels) #5459. Will land as a follow-up commit on this branch once that adaptation is reviewed.

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot

Summary

This PR implements ContactSensor, ContactSensorCfg, and ContactSensorData for the ovphysx backend, providing contact force reporting via the ovphysx ContactBinding API. The implementation mirrors the PhysX backend structure, supporting net forces, force matrix filtering, history buffers, air/contact time tracking, and pose tracking. Two features (track_contact_points, track_friction_forces) are explicitly deferred with NotImplementedError. The implementation appears structurally sound but has several bugs in the Warp kernels and test setup that need addressing.

Architecture Impact

• Cross-module: The sensor integrates with isaaclab.sensors.contact_sensor.BaseContactSensor and isaaclab.scene.InteractiveScene. The ContactSensorCfg uses lazy class resolution via "{DIR}.contact_sensor:ContactSensor".
• Data flow: Contact data flows from ovphysx ContactBinding.read_net_forces() → flat Warp buffers → structured ContactSensorData buffers via Warp kernels.
• Dependency: Blocked on #5316 for test execution (tests use RigidObject which requires ovphysx RigidObject support).

Implementation Verdict

Significant concerns — Several Warp kernel bugs will cause incorrect behavior or crashes at runtime. The tests are well-structured but cannot run until #5316 lands.

Test Coverage

The test file is comprehensive, ported from the PhysX backend with appropriate modifications. However:

• Tests are not executable due to dependency on #5316
• 3 tests properly skipped for deferred features
• No unit tests for the Warp kernels in isolation
• @flaky decorator on contact time tests suggests known instability

CI Status

• Check for Broken Links: failure — Likely unrelated to this PR (documentation link issue)
• Most CI jobs are skipped — expected given the test dependency on #5316
• pre-commit: success confirms formatting is correct

Findings

🔴 Critical: contact_sensor.py:309-310 — reset() passes None to optional buffers causing kernel crash

The reset_contact_sensor_kernel is launched with self._data._friction_forces_w and self._data._contact_pos_w as outputs, but these are None when track_friction_forces=False and track_contact_points=False. Warp kernels cannot safely write to None arrays. The kernel guards (if friction_forces_w:) only prevent the write, but the array is still passed as an argument.

outputs=[
    ...
    self._data._friction_forces_w,  # None when track_friction_forces=False
    self._data._contact_pos_w,      # None when track_contact_points=False
],

Fix: Create empty placeholder buffers or restructure the kernel to not require these arguments when disabled.

🔴 Critical: kernels.py:229-230 — force_matrix_w_history accessed without null guard

In update_net_forces_kernel, when net_forces_matrix_flat is not None but force_matrix_w_history could be None (if history tracking is disabled differently than matrix tracking), the kernel will crash:

if net_forces_matrix_flat:
    for f in range(num_filter_shapes):
        force_matrix_w[env, sensor, f] = net_forces_matrix_flat[src_idx, f]
        for i in range(history_length - 1, 0, -1):
            force_matrix_w_history[env, i, sensor, f] = ...  # No null guard!

Looking at _create_buffers(), both are allocated together, so this may be safe in practice, but the asymmetric guarding is fragile.

🔴 Critical: contact_sensor.py:271-278 — Timestamp arrays passed incorrectly to kernel

The kernel expects wp.array(dtype=wp.float32) for timestamp and timestamp_last_update, but self._timestamp and self._timestamp_last_update from the base class are likely per-environment scalars or structured differently. Need to verify these match the expected (num_envs,) shape.

inputs=[
    ...
    self._timestamp,           # What shape/type is this?
    self._timestamp_last_update,
]

🟡 Warning: contact_sensor.py:207-208 — Pose binding pattern may match unintended prims

The pose binding uses a wildcard pattern f"{base_glob}/*" which could match more prims than intended if the scene has siblings under the base path:

single_pose_pattern = f"{base_glob}/*"
self._pose_binding = physx_instance.create_tensor_binding(
    pattern=single_pose_pattern,
    tensor_type=TT.RIGID_BODY_POSE,
)

The count check at line 215-221 catches mismatches, but a more precise pattern construction (using the actual body names) would be safer.

🟡 Warning: contact_sensor_data.py:25-35 — pose_w property launches kernel on every access

Every call to pose_w launches a Warp kernel to concatenate position and quaternion:

@property
def pose_w(self) -> ProxyArray | None:
    if self._pose_w is None:
        return None
    wp.launch(
        concat_pos_and_quat_to_pose_kernel,  # Launched every access!
        ...
    )

This is inefficient if accessed multiple times per step. Consider caching or only recomputing when data is dirty.

🟡 Warning: check_contact_sensor.py:51 — Test imports ovphysx before checking availability

The test file calls pytest.importorskip("ovphysx.types") but then has unconditional imports from isaaclab_ovphysx.sensors at line 53. If ovphysx is not installed, the skip happens but the subsequent import will still execute during collection:

pytest.importorskip("ovphysx.types", reason="ovphysx wheel not installed")
from isaaclab_ovphysx.sensors import ContactSensorCfg  # noqa: E402

This should work due to lazy export, but the order is fragile.

🔵 Improvement: kernels.py:280-292 — Duplicate kernel definition

concat_pos_and_quat_to_pose_kernel is defined both in contact_sensor/kernels.py and sensors/kernels.py. The one in contact_sensor_data.py imports from sensors/kernels.py, while contact_sensor.py also defines it locally via the import. This duplication will cause maintenance issues.

# In sensors/kernels.py
@wp.kernel
def concat_pos_and_quat_to_pose_kernel(...):

# Also in contact_sensor/kernels.py (line 280)
@wp.kernel  
def concat_pos_and_quat_to_pose_kernel(...):

Fix: Remove the duplicate in contact_sensor/kernels.py and import from sensors/kernels.py.

🔵 Improvement: contact_sensor.py:92-94 — Config mutation in __init__

Mutating the config object's attributes in __init__ is a side effect that could surprise callers:

if self.cfg.max_contact_data_count_per_prim is None:
    self.cfg.max_contact_data_count_per_prim = 4
if self.cfg.force_threshold is None:
    self.cfg.force_threshold = 1.0

Fix: Use local variables or @property accessors with defaults instead of mutating the config.