Bring in Sharpa retargeter from V2D

.github/actions/setup-v2d-src/action.yml

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+name: Setup robotic_grounding source bundle
+description: |
+  Clone jiwenc-nv/v2d:retargeter at the SHA pinned in deps/v2d/version.txt
+  and copy `robotic_grounding/` into deps/v2d/src/robotic_grounding/. The
+  Teleop wheel build (src/core/python/CMakeLists.txt) then bundles that
+  subtree alongside isaacteleop, so `pip install isaacteleop[grounding]`
+  on the resulting wheel works without a separate robotic_grounding install.
+
+  Forks without V2D_RETARGETER_TOKEN no-op cleanly: the action exits
+  without populating deps/v2d/src/, the wheel build skips bundling, and
+  Sharpa retargeter tests skip via the `_HAS_PINOCCHIO` guard.
+
+inputs:
+  github-token:
+    description: PAT with read access to jiwenc-nv/v2d. Empty on forks; action no-ops then.
+    required: false
+    default: ''
+
+outputs:
+  bundled:
+    description: '"true" if deps/v2d/src/robotic_grounding/ was populated, else "false".'
+    value: ${{ steps.locate.outputs.bundled }}
+
+runs:
+  using: composite
+  steps:
+    - name: Skip on forks (no token)
+      if: inputs.github-token == ''
+      shell: bash
+      run: |
+        echo "::warning::V2D_RETARGETER_TOKEN is empty; skipping robotic_grounding source fetch."
+        echo "Sharpa retargeter tests will skip via the _HAS_PINOCCHIO guard."
+
+    - name: Read pinned V2D ref
+      id: pin
+      if: inputs.github-token != ''
+      shell: bash
+      run: |
+        if [ ! -f deps/v2d/version.txt ]; then
+          echo "::error::deps/v2d/version.txt is missing; cannot pin V2D commit."
+          exit 1
+        fi
+        SHA=$(grep -vE '^\s*(#|$)' deps/v2d/version.txt | head -1 | tr -d '[:space:]')
+        if [ -z "$SHA" ]; then
+          echo "::error::deps/v2d/version.txt contains no SHA."
+          exit 1
+        fi
+        echo "sha=${SHA}" >> "$GITHUB_OUTPUT"
+        echo "Pinned V2D ref: ${SHA}"
+
+    - name: Cache robotic_grounding source bundle
+      id: cache
+      if: inputs.github-token != ''
+      uses: actions/cache@v5
+      with:
+        path: deps/v2d/src
+        # Source bundle is pure files; cache key only depends on V2D SHA.
+        key: v2d-src-${{ steps.pin.outputs.sha }}
+
+    - name: Clone robotic_grounding source
+      if: inputs.github-token != '' && steps.cache.outputs.cache-hit != 'true'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+        V2D_REF: ${{ steps.pin.outputs.sha }}
+      run: |
+        set -euo pipefail
+        rm -rf /tmp/v2d deps/v2d/src
+        mkdir -p deps/v2d/src
+
+        # Whole retargeter branch is ~25 MB so a normal clone is fine.
+        gh repo clone jiwenc-nv/v2d /tmp/v2d -- --branch retargeter
+        git -C /tmp/v2d checkout "${V2D_REF}"
+
+        cp -a \
+          /tmp/v2d/robotic_grounding/source/robotic_grounding/robotic_grounding \
+          deps/v2d/src/robotic_grounding
+        find deps/v2d/src/robotic_grounding -type d -name __pycache__ \
+          -exec rm -rf {} + 2>/dev/null || true
+
+        rm -rf /tmp/v2d
+
+    - name: Locate bundle
+      id: locate
+      shell: bash
+      run: |
+        if [ -f deps/v2d/src/robotic_grounding/__init__.py ]; then
+          echo "bundled=true" >> "$GITHUB_OUTPUT"
+          echo "robotic_grounding/ source present at deps/v2d/src/robotic_grounding/"
+        else
+          echo "bundled=false" >> "$GITHUB_OUTPUT"
+          echo "::warning::deps/v2d/src/robotic_grounding/ is missing; wheel build will skip [grounding]."
+        fi

.github/workflows/build-ubuntu.yml

@@ -52,6 +52,22 @@ jobs:
       with:
         ngc-api-key: ${{ secrets.NGC_TELEOP_CORE_GITHUB_SERVICE_KEY }}
 
+    # robotic_grounding source bundle for the [grounding] extra (Sharpa retargeter).
+    # Disabled on release branches (and PRs targeting them) to keep release
+    # artifacts free of V2D source: V2D is private/pre-release and shouldn't
+    # ship with anything stamped as a release. Also no-ops on forks that
+    # lack V2D_RETARGETER_TOKEN. In every disabled case the wheel build skips
+    # bundling robotic_grounding/, and Sharpa tests skip via the
+    # _HAS_PINOCCHIO guard. Must run BEFORE `Configure CMake` so the wheel
+    # staging step in src/core/python/CMakeLists.txt picks up
+    # deps/v2d/src/robotic_grounding/.
+    - name: Setup robotic_grounding source bundle
+      id: setup-v2d-src
+      if: ${{ !startsWith(github.ref_name, 'release/') && !startsWith(github.base_ref, 'release/') }}
+      uses: ./.github/actions/setup-v2d-src
+      with:
+        github-token: ${{ secrets.V2D_RETARGETER_TOKEN }}
+
     # Hunter cache - caches depthai dependencies (OpenSSL, CURL, etc.)
     - name: Cache Hunter packages
       uses: actions/cache@v5
@@ -83,7 +99,8 @@ jobs:
           -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
           -DBUILD_PLUGIN_OAK_CAMERA=ON \
           -DBUILD_VIZ=ON \
-          -DENABLE_CLOUDXR_BUNDLE_CHECK=ON
+          -DENABLE_CLOUDXR_BUNDLE_CHECK=ON \
+          -DBUNDLE_ROBOTIC_GROUNDING=${{ steps.setup-v2d-src.outputs.bundled || 'false' }}
 
     - name: Build
       run: cmake --build build --parallel 4
@@ -151,6 +168,26 @@ jobs:
         mv install/wheels-repaired/*.whl install/wheels/
         rmdir install/wheels-repaired || true
 
+    # Belt-and-suspenders against leaking V2D source via the public CI
+    # artifact. The Teleop wheel build bundles robotic_grounding/ into the
+    # wheel when V2D_RETARGETER_TOKEN was set. Strip those entries here so
+    # the wheel uploaded to a public GitHub Actions artifact never contains
+    # V2D code, regardless of which matrix entry / branch built it.
+    # Internal consumers who need the bundled wheel can rebuild locally
+    # from source via scripts/setup_v2d_src.sh + cmake.
+    - name: Strip robotic_grounding from wheel artifacts (Release only)
+      if: matrix.build_type == 'Release'
+      run: |
+        set -euo pipefail
+        shopt -s nullglob
+        wheels=(install/wheels/*.whl)
+        if (( ${#wheels[@]} == 0 )); then
+          echo "No wheels found; nothing to strip."
+          exit 0
+        fi
+        uv run --python ${{ matrix.python_version }} \
+          python scripts/strip_robotic_grounding_from_wheel.py "${wheels[@]}"
+
     - name: Create tarball to preserve permissions
       if: matrix.build_type == 'Release'
       run: tar -cvf isaacteleop-install.tar -C install .

.gitignore

@@ -50,3 +50,11 @@ dist/
 
 # SPDX report
 project.spdx
+
+# robotic_grounding source bundle (cloned locally / in CI from
+# jiwenc-nv/v2d:retargeter; never committed -- repopulated deterministically
+# from deps/v2d/version.txt). The Teleop wheel build copies this subtree
+# into the wheel staging dir so [grounding] users get robotic_grounding
+# without a separate install. V2D source must NOT be tracked here.
+deps/v2d/src/
+deps/v2d/wheels/

deps/v2d/version.txt

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Pinned commit on jiwenc-nv/v2d:retargeter that the [grounding] extra
+# (Sharpa retargeter) is built against. Edit this single line to upgrade
+# the bundled robotic_grounding; rerun scripts/setup_v2d_src.sh after.
+#
+# See docs/source/references/grounding_extra.rst for the end-to-end flow.
+
+27657fbbc85af946eaf58484aaf0bf6fead215e3

docs/source/index.rst

@@ -59,7 +59,7 @@ Table of Contents
    references/requirements
    references/build
    device/index
-   references/retargeting
+   references/retargeting/index
    references/mcap_record_replay
    references/oob_teleop_control
    references/license

docs/source/references/retargeting.rst → docs/source/references/retargeting/index.rst

@@ -308,4 +308,10 @@ If the built-in retargeters do not cover your use case, you can implement a cust
    ``IDeviceIOSource`` subclass for custom input devices.
 
 See the `retargeters README <https://github.com/NVIDIA/IsaacTeleop/blob/main/src/retargeters/README.md>`_
-and :doc:`Contributing Guide <../getting_started/contributing>` for details.
+and :doc:`Contributing Guide <../../getting_started/contributing>` for details.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Retargeter setup guides
+
+   sharpa