<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

<a id="retargeter-joint-space-device"></a>

# Retargeter: Joint-Space Device

`JointStateRetargeter` maps a name-keyed joint-state input (from
[Generic Joint-Space Device](../../device/joint_space/index.md)’s `JointStateSource`) onto an Isaac Lab action, in one of two modes.
It is the generic retargeter for leader arms, exoskeletons, and other joint-encoder devices; the
SO-101 leader arm is the reference instance.

<a id="at-a-glance"></a>

## At a glance

| Mode      | Output                                                  | Use                                                                                                                                      |
|-----------|---------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| `joint`   | one float per target joint (`joint_targets`)            | Lossless leader -> follower mirror for same-kinematics teleoperation. Name remap + optional<br/>per-joint affine. No extra dependencies. |
| `ee_pose` | 7-D `ee_pose` `[x,y,z,qx,qy,qz,qw]` + `gripper_command` | Task-space / cross-embodiment teleoperation via URDF forward kinematics. Requires<br/>`pinocchio` (the `[retargeters]` extra).           |

<a id="joint-mode"></a>

## `joint` mode

Each target joint is filled from a device joint (by name) with an optional affine
`offset + sign * scale * value`. Defaults are an identity mirror. `JointStateRetargeterConfig`:

* `device_joints` – ordered device DOF names (must match the source’s `joint_names` order).
* `target_joints` – robot joint names to emit (defaults to `device_joints`).
* `joint_map` – `{device_name: target_name}` overrides; `scale` / `offset` / `sign` –
  per-target affine.

<a id="ee-pose-mode"></a>

## `ee_pose` mode

Forward-kinematics the device joints through a URDF and emit the end-effector pose plus a gripper
command. Config: `urdf_path`, `ee_link`, `gripper_joint` (and optional `gripper_open` /
`gripper_close` to emit normalized closedness in `[0, 1]` instead of the raw value).

* FK uses `pinocchio` (imported lazily; `joint` mode never needs it). Install via
  `pip install 'isaaccapture[retargeters]'`.
* Assumes a fixed-base model of single-DOF joints (the common leader-arm / exoskeleton case).
* The schema’s device `ee_pose` field is **not** consumed yet – FK is always computed from the
  joint positions.
* `clutch=True` rebases the EE around an origin captured on the first `RUNNING` frame so
  engaging teleop does not jump the robot; when the optional `robot_ee_pos` input (the live
  `world_T_ee`) is connected, the latched home is the robot’s current end-effector.

#### NOTE
The `joints` input is read positionally in `device_joints` order, so the upstream source’s
`joint_names` must list the same names in the same order. A name mismatch is rejected by the
graph’s type check at `connect` time.

<a id="use-it-from-python"></a>

## Use it from Python

A pipeline builder returns an `OutputCombiner` with a single `"action"` key (the layout your
environment’s action space expects):

```python
from isaaccapture.retargeting_engine.deviceio_source_nodes import JointStateSource
from isaaccapture.retargeting_engine.interface import OutputCombiner
from isaaccapture.retargeters import (
    JointStateRetargeter,
    JointStateRetargeterConfig,
    TensorReorderer,
)

SO101_JOINTS = ["shoulder_pan", "shoulder_lift", "elbow_flex", "wrist_flex", "wrist_roll", "gripper"]

def build_so101_joint_pipeline():
    source = JointStateSource(name="leader", collection_id="so101_leader", joint_names=SO101_JOINTS)
    retargeter = JointStateRetargeter(
        name="leader",
        mode="joint",
        config=JointStateRetargeterConfig(device_joints=SO101_JOINTS, target_joints=SO101_JOINTS),
    )
    head = retargeter.connect({JointStateRetargeter.JOINTS: source.output(JointStateSource.JOINTS)})
    reorderer = TensorReorderer(
        input_config={"joint_targets": SO101_JOINTS},
        output_order=SO101_JOINTS,
        name="action_reorderer",
        input_types={"joint_targets": "scalar"},
    )
    connected = reorderer.connect({"joint_targets": head.output("joint_targets")})
    return OutputCombiner({"action": connected.output("output")})
```

For `ee_pose` mode, build the retargeter with `mode="ee_pose"` + a `urdf_path` / `ee_link`
and flatten `ee_pose` + `gripper_command` into the env’s task-space action layout.

<a id="run-the-example"></a>

## Run the example

The repo ships `examples/teleop/python/isaaccapture_examples/teleop/joint_space_device_example.py`:

```console
$ uv pip install -e ./examples/teleop

# Consumes the so101_leader plugin over OpenXR (source cloudxr.env first):
$ python -m isaaccapture_examples.teleop.joint_space_device_example --launch-plugin --mode joint --frames 8
$ python -m isaaccapture_examples.teleop.joint_space_device_example --launch-plugin --mode ee --urdf /path/to/so101_new_calib.urdf
```

`so101_new_calib.urdf` is not shipped in this repo. It is `Simulation/SO101/so101_new_calib.urdf`
in [TheRobotStudio/SO-ARM100](https://github.com/TheRobotStudio/SO-ARM100); pass its path to
`--urdf`. Run the commands from the repository root.

<a id="validate"></a>

## Validate

Sim-free unit tests cover both modes (joint affine/remap/hold/reset, EE forward kinematics, clutch
rebasing, and the flattened action width/order):

```console
$ ctest --test-dir build -R 'retargeting_test_joint_state' --output-on-failure
```

#### SEE ALSO
[Generic Joint-Space Device](../../device/joint_space/index.md) – the schema, `JointStateTracker`, `JointStateSource`, the
SO-101 plugin, and MCAP record/replay.

[Retargeting Interface](index.md) – the broader retargeting interface and pipeline-builder pattern.
