Expose SO-101 clutch position scale as a constructor parameter

[jiwenc-nv]

Summary

SO101ClutchRetargeter integrated controller position deltas 1:1 (the module
constant _CLUTCH_POSITION_SCALE = 1.0). Because an operator's comfortable arm
travel (~0.7 m) is roughly twice the SO-101's reach (~0.35 m), 1:1 motion plus
clutch release/re-engage cycles ratchet the commanded end-effector target out of
the reachable workspace.

This exposes the clutch position scale as a validated constructor parameter so a
full operator sweep can be mapped inside the arm's reach.

Changes

• Add position_scale: float to SO101ClutchRetargeter.__init__ (slotted after
  home_base_T_ee, before orientation_offset), defaulting to
  _CLUTCH_POSITION_SCALE (1.0). It scales the clutch position delta only —
  orientation is always tracked 1:1.
• Validate at construction: coerce to float, then reject non-positive and
  non-finite values with ValueError. A zero scale freezes the EE, a negative
  one inverts the hand→EE mapping, and the finite check closes the inf * 0 = nan
  path before it can reach the SE3 IK. No upper clamp.
• The single call site now uses self._position_scale; the 7D ee_pose output
  contract and the no-teleport-on-engage invariant are unchanged (the latter holds
  at any finite scale).

Testing

Adds sim-free unit tests to test_so101_retargeters.py:

• test_position_scale_scales_delta — scaled compute path, incl. no-teleport on engage.
• test_invalid_position_scale_rejected — parametrized over 0.0, -1.0, nan, inf.
• test_reengage_ratchets_scaled_delta_per_cycle — the motivating N-cycle ratchet
  property (home + N·scale·δ, vs home + N·δ at unit scale).

All 32 tests in the module pass; the new cases were confirmed to fail against the
unmodified retargeter. ruff format/check clean.

Scope / follow-up

The default 1.0 preserves current behavior — this PR enables the fix without
changing runtime behavior on its own. Landing the operator-facing correction
requires the SO-101 task config to pass a sub-unity position_scale (that wiring
lives outside this repo and is a separate follow-up).

Runtime motion-scale control (HUD v2) is intentionally out of scope; this is a
construction-time parameter.

Part of #733.

Summary by CodeRabbit

• New Features

  • Added configurable position scaling for SO-101 clutch retargeting.
  • Added validation to reject zero, negative, or non-finite scale values.
  • Re-engagement cycles now apply the configured scaling consistently.

• Tests

  • Added coverage for scaled position changes, invalid configuration values, and repeated clutch cycles.

[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-821/

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8dd34523-9ba2-4e31-8354-1a13d5749839

📥 Commits

Reviewing files that changed from the base of the PR and between 6258095 and 901974d.

📒 Files selected for processing (2)

• src/core/retargeting_engine_tests/python/test_so101_retargeters.py
• src/retargeters/SO101/clutch_retargeter.py

---

📝 Walkthrough

Walkthrough

SO101ClutchRetargeter now accepts a configurable position_scale, rejects non-positive or non-finite values, and applies the scale to translation rebasing while preserving engage-at-home behavior. New tests cover scaled motion, invalid constructor inputs, and accumulated translation across repeated clutch cycles.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 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 summarizes the main change: exposing the SO-101 clutch position scale as a constructor parameter.
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.}