Building the `[grounding]` Extra#

The isaacteleop[grounding] extra enables retargeters that consume the private robotic_grounding package (today: SharpaHandRetargeter, SharpaBiManualRetargeter). Because robotic_grounding ships from a private GitHub repo, you must opt in at build time and provide credentials to fetch the source.

Prerequisites#

gh CLI installed and gh auth login‘d with read access to jiwenc-nv/v2d.
A configured Teleop build tree.

Build#

$ scripts/setup_v2d_src.sh
$ cmake -B build -DBUNDLE_ROBOTIC_GROUNDING=TRUE <other flags...>
$ cmake --build build --target python_wheel
$ uv pip install -e .[grounding]

That’s it. The first command populates deps/v2d/src/robotic_grounding/ from the SHA pinned in deps/v2d/version.txt. The CMake flag tells the wheel build to bundle that subtree alongside isaacteleop.

Without -DBUNDLE_ROBOTIC_GROUNDING=TRUE (the default), the wheel builds without robotic_grounding and Sharpa retargeter imports skip cleanly – useful for forks and OSS contributors who don’t have V2D access.

Use it from Python#

from isaacteleop.retargeters import (
    SharpaHandRetargeter,
    SharpaHandRetargeterConfig,
)

The Sharpa MJCFs and meshes ship inside the bundled robotic_grounding package – resolve them with importlib.resources:

from importlib.resources import files

xml_dir = files("robotic_grounding") / "assets" / "xmls" / "sharpawave"
right_mjcf = str(xml_dir / "right_sharpawave_nomesh.xml")  # mesh-free, fast
# or "right_sharpawave.xml" if you also have the STL meshes

cfg = SharpaHandRetargeterConfig(hand_side="right", robot_asset_path=right_mjcf)
retargeter = SharpaHandRetargeter(cfg)

If the wheel was built without -DBUNDLE_ROBOTIC_GROUNDING=TRUE, the import raises ModuleNotFoundError with a pointer to scripts/setup_v2d_src.sh.

Run the example#

The repo ships a bimanual demo at examples/retargeting/python/sharpa_hand_retargeter_demo.py:

# Synthetic curl animation (no headset, no GUI required):
$ python examples/retargeting/python/sharpa_hand_retargeter_demo.py --synthetic

# Live bimanual from a connected Quest headset:
$ python examples/retargeting/python/sharpa_hand_retargeter_demo.py

# Custom MJCFs (e.g. the mesh-bearing variants):
$ python examples/retargeting/python/sharpa_hand_retargeter_demo.py \
    --left-mjcf  /path/to/left_sharpawave.xml \
    --right-mjcf /path/to/right_sharpawave.xml

The synthetic mode is the smoke test: if it animates a curl trajectory and prints non-zero finger qpos each frame, the install is good.

Validate#

Two checks; either by itself is sufficient.

End-to-end pytest – exercises the full Pinocchio + Pink IK pipeline through the Teleop wrapper (init, warm-start persistence, open vs. curled hand, absent-hand zeros, etc.):

$ ctest --test-dir build -R retargeting_test_sharpa_hand_retargeter --output-on-failure
...
100% tests passed, 0 tests failed out of 1

The Test command line printed by ctest -V should include --extra grounding. If it doesn’t, the wheel build skipped bundling – re-check that cmake -B build was invoked with -DBUNDLE_ROBOTIC_GROUNDING=TRUE after running setup_v2d_src.sh.

Full retargeting suite – regression coverage in case the wrapper introduced a typing or import regression elsewhere:

$ ctest --test-dir build -R '^retargeting_' --output-on-failure
...
100% tests passed, 0 tests failed out of 16

CI#

The workflow at .github/workflows/build-ubuntu.yml runs the same flow via the setup-v2d-src composite action, gated on the V2D_RETARGETER_TOKEN repo secret (a PAT scoped read-only to jiwenc-nv/v2d). The action sets -DBUNDLE_ROBOTIC_GROUNDING from its own bundled output; on forks without the secret the action no-ops and the flag is false.

Public artifact safety: a Release-only step strips robotic_grounding/ out of every wheel before actions/upload-artifact runs, so V2D source never reaches the public artifact channel.

Bumping the bundled `robotic_grounding`#

Edit the SHA in deps/v2d/version.txt and rerun scripts/setup_v2d_src.sh.

Building the [grounding] Extra#