(feat): dVRK PSM retargeters

[chrisvoncsefalvay]

Description

Adds reusable XR retargeters for da Vinci Research Kit (dVRK) Patient Side Manipulators (PSMs).

The retargeters provide a simulator-independent boundary between an XR controller and a PSM integration: they emit a bounded absolute tool-tip pose and paired jaw-joint targets, while robot-specific differential IK, articulation control, collision handling, and emergency-stop behaviour remain with the downstream consumer.

What is included

• DVRKPSMClutchRetargeter emits a float32 ee_pose in [x, y, z, qx, qy, qz, qw] order.
  • Requires an explicit home transform.
  • Supports either controller hand, translation scaling, workspace bounds, orientation calibration, and a configurable clutch threshold.
  • Captures the controller origin on engagement, applies absolute translation and conjugated relative rotation, and re-clutches without a target jump.
• DVRKPSMGripperRetargeter emits float32 jaw_targets for the two native PSM jaw joints.
  • Supports configurable open and closed endpoints, initial closedness, clutch threshold, trigger deadband, and opening-intent dwell.
  • Closing responds immediately; opening requires deliberate trigger release observed for the configured graph-time duration.
• NumPy-only Cartesian-clutch and jaw-intent state machines keep the control semantics reusable without importing a simulator runtime.
• The four public config and retargeter classes are lazy-exported from isaacteleop.retargeters and included in Python package staging.
• The retargeting reference now includes a dVRK overview, controller and frame contracts, configuration guidance, and a runnable right-controller pipeline with explicit source connections.

Control and safety semantics

The squeeze input (deadman) gates target updates. Releasing it holds the last commanded target and re-arms controller-origin capture; it does not disable downstream actuation or latch the measured articulation state. Command disable, measured-state hold, joint and collision limits and emergency-stop behaviour remain the responsibility of the simulator or robot integration.

The output is designed to be fail-safe, i.e. tracking loss, inactive sessions, missing controller data, malformed poses, degenerate quaternions and non-finite samples hold the last safe output and require a fresh engagement. Configuration values that will be narrowed to float32 are validated against the finite float32 range.

The jaw retargeter preserves the last jaw target across clutch release and tracking transitions. Its opening dwell uses observed graph time rather than frame count, including protection against repeated or regressed timestamps.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Testing

• Release CMake configure and build: passed.
• Full CTest suite: 145/145 passed.
• Focused simulator-independent dVRK suite: 58/58 passed.
• Mypy: 42 source files clean, including the new dVRK modules in the repository CTest target.
• Sphinx documentation build with warnings treated as errors: passed.
• Runnable documentation pipeline construction: passed.
• Ruff lint and format checks: passed.
• SKIP=check-copyright-year rtk uvx pre-commit run --all-files: passed.
• REUSE/SPDX and git diff --check: passed.

Coverage includes clutch state transitions, workspace clipping, no-jump re-engagement, an independent non-commuting orientation-conjugation oracle, paired jaw interpolation, deliberate opening dwell, graph-time regressions, malformed and non-finite samples, float32-range configuration rejection and, hopefully, public wrapper/kernel parity.

Scope

This PR contains the reusable dVRK retargeters, public API and configuration, focused tests, packaging, and retargeter documentation only. For the sake of separation of concerns, the Isaac Sim/Lab example, diff IK and articulation validation will be in the downstream dual PSM integration.

Checklist

• I have read and understood the contribution guidelines
• I have run the linter and formatter with SKIP=check-copyright-year pre-commit run --all-files
• I have made corresponding changes to the documentation
• I have added tests that prove my fix/feature works (or explained why not)
• I have signed off all my commits (git commit -s) per the DCO

Summary by CodeRabbit

• New Features

  • Added dVRK Patient Side Manipulator retargeters for clutch-controlled end-effector pose and trigger-controlled paired-jaw targets.
  • Added configurable workspace limits, clutch thresholds, jaw endpoints, initial jaw positions, and orientation offsets.
  • Added robust handling for tracking loss, invalid input, clutch transitions, and reset behavior.
  • Exposed the new retargeters through the public package interface.

• Documentation

  • Added setup guidance, input/output contracts, frame conventions, usage examples, and test instructions for dVRK retargeting.

• Tests

  • Added comprehensive coverage for pose, jaw, clutch, reset, validation, timing, and invalid-input behavior.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 4bccd692-330a-466c-8b44-a23c9bbff662

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds dVRK PSM clutch and gripper retargeters with NumPy state machines for absolute tool poses and paired jaw targets. The change exposes public configurations and retargeter classes, integrates the package into builds, adds extensive simulator-free tests, and documents behavior, reference frames, Python wiring, and validation commands.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ControllersSource
  participant DVRKPSMClutchRetargeter
  participant DVRKPSMGripperRetargeter
  participant OutputCombiner
  participant SimulatorIK
  ControllersSource->>DVRKPSMClutchRetargeter: grip pose and squeeze
  ControllersSource->>DVRKPSMGripperRetargeter: trigger and squeeze
  DVRKPSMClutchRetargeter-->>OutputCombiner: ee_pose
  DVRKPSMGripperRetargeter-->>OutputCombiner: jaw_targets
  OutputCombiner->>SimulatorIK: combined pose and jaw targets

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding dVRK PSM retargeters.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📝 Docs preview is not auto-deployed for fork PRs.

A maintainer with write access to NVIDIA/IsaacTeleop can deploy a preview by
commenting /preview-docs on this PR. Once deployed, the preview
will live at:

https://nvidia.github.io/IsaacTeleop/preview/pr-769/

[Copilot]

Pull request overview

Adds simulator-independent XR retargeters for the dVRK Patient Side Manipulator (PSM), providing a clean boundary that outputs a bounded absolute tool pose plus paired jaw targets for downstream IK / articulation control.

Changes:

• Introduces DVRKPSMClutchRetargeter (7D ee_pose) and DVRKPSMGripperRetargeter (2D jaw_targets) with NumPy-only control kernels.
• Wires the new dVRK retargeters into the Python package surface and build/test tooling (mypy path, package staging).
• Adds extensive simulator-free unit tests and new retargeter documentation/reference material.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/retargeters/DVRK/psm_retargeter.py	New engine-facing retargeter wrappers for pose clutch and jaw targets.
src/retargeters/DVRK/control.py	New NumPy-only clutch + jaw-intent state machines and math helpers.
src/retargeters/DVRK/init.py	Lazy-export surface for the DVRK retargeter subpackage.
src/retargeters/CMakeLists.txt	Ensures DVRK __pycache__ is removed during Python package staging.
src/retargeters/init.py	Exposes new dVRK retargeters/configs from isaacteleop.retargeters.
src/core/retargeting_engine_tests/python/test_dvrk_psm_retargeters.py	New simulator-free test suite for dVRK PSM retargeters and kernels.
src/core/retargeting_engine_tests/python/CMakeLists.txt	Adds mypy coverage for the new src/retargeters/DVRK modules.
src/core/python/pyproject.toml.in	Includes isaacteleop.retargeters.DVRK in the packaged modules list.
docs/source/references/retargeting/index.rst	Adds dVRK entry to the retargeter reference index.
docs/source/references/retargeting/dvrk.rst	New documentation page describing dVRK PSM retargeter usage and contracts.