examples(oxr): package under isaacteleop_examples

docs/source/device/body_tracking.rst

@@ -203,7 +203,7 @@ joint ``is_valid`` flags to determine which joints have valid poses.
 For a minimal C++ reader see ``examples/schemaio/full_body_printer.cpp``, which
 creates the tracker, queries the required OpenXR extensions, and prints the
 joint data each frame through ``DeviceIOSession``. The Python equivalent is
-``examples/oxr/python/test_full_body_tracker.py``. Running
+``examples/oxr/python/isaacteleop_examples/oxr/test_full_body_tracker.py``. Running
 ``python -m isaacteleop.rig rigs/full_body.yaml`` runs this printer and the C++
 MCAP recorder together in one tmux window, against the CloudXR runtime it makes
 sure is serving first (see :ref:`rig-launcher`).

docs/source/device/oak.rst

@@ -169,7 +169,7 @@ controllers, etc.):
        while True:
            session.step()  # metadata is recorded each update
 
-See also :code-file:`examples/oxr/python/test_oak_camera.py` (``--mode
+See also :code-file:`examples/oxr/python/isaacteleop_examples/oxr/test_oak_camera.py` (``--mode
 schema-pusher``) for a standalone PluginManager + DeviceIOSession example of
 the same SchemaPusher flow.
 

docs/source/device/trackers.rst

@@ -190,7 +190,7 @@ Tracks the HMD head pose via the OpenXR view space.
 - Examples:
 
   - :code-file:`examples/oxr/cpp/oxr_simple_api_demo.cpp`
-  - :code-file:`examples/oxr/python/modular_example.py`
+  - :code-file:`examples/oxr/python/isaacteleop_examples/oxr/modular_example.py`
 
 HandTracker
 ~~~~~~~~~~~
@@ -206,12 +206,12 @@ Tracks articulated hand joints (26 joints per hand, following the OpenXR
 
   - :code-file:`tests/cpp/core/schema/test_hand.cpp`
   - :code-file:`tests/python/core/schema/test_hand.py`
-  - :code-file:`examples/oxr/python/test_synthetic_hands.py`
+  - :code-file:`examples/oxr/python/isaacteleop_examples/oxr/test_synthetic_hands.py`
 
 - Examples:
 
   - :code-file:`examples/oxr/cpp/oxr_simple_api_demo.cpp`
-  - :code-file:`examples/oxr/python/modular_example.py`
+  - :code-file:`examples/oxr/python/isaacteleop_examples/oxr/modular_example.py`
   - :code-file:`examples/retargeting/python/isaacteleop_examples/retargeting/sources_example.py`
 
 ControllerTracker
@@ -228,7 +228,7 @@ axis inputs. Uses standard OpenXR action bindings.
 
   - :code-file:`tests/cpp/core/schema/test_controller.cpp`
   - :code-file:`tests/python/core/schema/test_controller.py`
-  - :code-file:`examples/oxr/python/test_controller_tracker.py`
+  - :code-file:`examples/oxr/python/isaacteleop_examples/oxr/test_controller_tracker.py`
 
 - Examples:
 
@@ -254,7 +254,7 @@ reads the PICO ``XR_BD_body_tracking`` extension directly.
 
   - :code-file:`tests/cpp/core/schema/test_full_body.cpp`
   - :code-file:`tests/python/core/schema/test_full_body.py`
-  - :code-file:`examples/oxr/python/test_full_body_tracker.py`
+  - :code-file:`examples/oxr/python/isaacteleop_examples/oxr/test_full_body_tracker.py`
 
 - Examples:
 
@@ -287,7 +287,7 @@ utility internally.
 
   - :code-file:`tests/cpp/core/schema/test_oak.cpp`
   - :code-file:`tests/python/core/schema/test_camera.py`
-  - :code-file:`examples/oxr/python/test_oak_camera.py`
+  - :code-file:`examples/oxr/python/isaacteleop_examples/oxr/test_oak_camera.py`
 
 - Examples:
 
@@ -378,7 +378,7 @@ Usage Examples
 For end-to-end usage patterns combining trackers with a ``DeviceIOSession``, see:
 
 - **C++**: :code-file:`examples/oxr/cpp/oxr_simple_api_demo.cpp`
-- **Python**: :code-file:`examples/oxr/python/modular_example.py`
+- **Python**: :code-file:`examples/oxr/python/isaacteleop_examples/oxr/modular_example.py`
 
 For higher-level usage with the teleop session manager and retargeting, see:
 

examples/oxr/CMakeLists.txt

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.20)
@@ -7,4 +7,4 @@ cmake_minimum_required(VERSION 3.20)
 add_subdirectory(cpp)
 
 include(${CMAKE_SOURCE_DIR}/cmake/InstallPythonExample.cmake)
-install_python_example(DESTINATION examples/oxr/python)
+install_python_example(DESTINATION examples/oxr)

examples/oxr/README.md

@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 SPDX-License-Identifier: Apache-2.0
 -->
 
@@ -31,8 +31,8 @@ examples/oxr/
 │   ├── CMakeLists.txt
 │   ├── oxr_session_sharing.cpp
 │   └── oxr_simple_api_demo.cpp
-└── python/                 # Python examples
-    ├── pyproject.toml      # uv configuration
+├── pyproject.toml          # the distribution
+└── python/isaacteleop_examples/oxr/
     ├── modular_example.py
     ├── test_modular.py
     ├── test_extensions.py
@@ -41,34 +41,25 @@ examples/oxr/
 
 ## Python Examples
 
-Python examples use `uv` for dependency management and execution.
-
 ### Running Python Examples
 
-After building and installing, navigate to the installed examples:
+Install the example once, then run any module from anywhere:
 
 ```bash
-# From install directory (recommended)
-cd install/examples/oxr/python
+uv pip install -e ./examples/oxr
 export XR_RUNTIME_JSON=/path/to/cloudxr/openxr_cloudxr-dev.json
-uv run test_modular.py
+python -m isaacteleop_examples.oxr.test_modular
 ```
 
-Or run from source directory:
-
-```bash
-# From source directory (requires build to be complete)
-cd examples/oxr/python
-export XR_RUNTIME_JSON=/path/to/cloudxr/openxr_cloudxr-dev.json
-uv run test_modular.py
-```
+The installed tree works the same way — `uv pip install -e
+install/examples/oxr` resolves against the wheel that build produced.
 
 ### Available Python Examples
 
-- **modular_example.py** - Basic hand + head tracking
-- **test_modular.py** - Complete API test
-- **test_extensions.py** - Extension query demonstration
-- **test_session_sharing.py** - Session sharing between DeviceIOSession instances
+- **modular_example** - Basic hand + head tracking
+- **test_modular** - Complete API test
+- **test_extensions** - Extension query demonstration
+- **test_session_sharing** - Session sharing between DeviceIOSession instances
 
 ## C++ Examples
 
@@ -110,9 +101,9 @@ cmake --build build
 cmake --install build
 
 # Run Python example
-cd install/examples/oxr/python
+uv pip install -e install/examples/oxr
 export XR_RUNTIME_JSON=/path/to/cloudxr/openxr_cloudxr-dev.json
-uv run test_modular.py
+python -m isaacteleop_examples.oxr.test_modular
 ```
 
 ### C++ Example

examples/oxr/pyproject.toml

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# The dist name mirrors the import path, so an installed example claims no bare
+# top-level name in site-packages.
+name = "isaacteleop-examples-oxr"
+version = "0.0.0"  # Internal examples - not versioned
+description = "OpenXR Tracking Python Examples"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "isaacteleop",
+    "numpy>=1.23.0",
+]
+
+# `isaacteleop_examples` is a PEP 420 namespace shared by every example dist and
+# must stay without an __init__.py. `only-include` + `sources`, not `packages`:
+# the latter keeps only the last path component and would root the wheel at a
+# bare top-level `oxr/`.
+[tool.hatch.build.targets.wheel]
+only-include = ["python/isaacteleop_examples/oxr"]
+sources = ["python"]

examples/oxr/python/isaacteleop_examples/oxr/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0

examples/oxr/python/test_hand_inactive_on_plugin_stop.py → examples/oxr/python/isaacteleop_examples/oxr/test_hand_inactive_on_plugin_stop.py

@@ -20,7 +20,9 @@
 import isaacteleop.oxr as oxr
 import isaacteleop.plugin_manager as pm
 
-PLUGIN_ROOT_DIR = Path(__file__).resolve().parent.parent.parent.parent / "plugins"
+# Six levels up is the tree root -- the checkout, or the install prefix
+# when running from install/examples/.
+PLUGIN_ROOT_DIR = Path(__file__).resolve().parents[5] / "plugins"
 
 ACTIVE_WAIT_S = 15.0  # max time to wait for hands to become active
 INACTIVE_WAIT_S = 5.0  # max time to wait for hands to become inactive after stop

examples/oxr/python/test_oak_camera.py → examples/oxr/python/isaacteleop_examples/oxr/test_oak_camera.py

@@ -26,7 +26,9 @@
 import isaacteleop.deviceio as deviceio
 import isaacteleop.oxr as oxr
 
-PLUGIN_ROOT_DIR = Path(__file__).resolve().parent.parent.parent.parent / "plugins"
+# Six levels up is the tree root -- the checkout, or the install prefix
+# when running from install/examples/.
+PLUGIN_ROOT_DIR = Path(__file__).resolve().parents[5] / "plugins"
 
 MODE_NO_METADATA = "no-metadata"
 MODE_SCHEMA_PUSHER = "schema-pusher"

examples/oxr/python/test_package_version.py → examples/oxr/python/isaacteleop_examples/oxr/test_package_version.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
 """Validate isaacteleop module version reporting against CI-provided expected version."""

examples/oxr/python/test_synthetic_hands.py → examples/oxr/python/isaacteleop_examples/oxr/test_synthetic_hands.py

@@ -25,7 +25,9 @@
 # The test will look for plugins in the install directory relative to this script
 # This script is in install/examples/oxr/python
 # Plugins are in install/plugins
-PLUGIN_ROOT_DIR = Path(__file__).resolve().parent.parent.parent.parent / "plugins"
+# Six levels up is the tree root -- the checkout, or the install prefix
+# when running from install/examples/.
+PLUGIN_ROOT_DIR = Path(__file__).resolve().parents[5] / "plugins"
 
 
 def run_test():

scripts/run_tests_with_cloudxr.sh

@@ -24,10 +24,12 @@ set -euo pipefail
 # the ctest configuration in `build-ubuntu.yml` instead, so that they can be
 # run on a runner without GPU support immediately after the build.
 #==============================================================================
+# Paths are relative to /app/tests in the test image, which is a copy of
+# examples/oxr/python/ -- so they carry the namespace prefix.
 CXR_PYTHON_GPU_TESTS=(
-    "test_package_version.py"
-    "test_extensions.py"
-    "test_modular.py"
+    "isaacteleop_examples/oxr/test_package_version.py"
+    "isaacteleop_examples/oxr/test_extensions.py"
+    "isaacteleop_examples/oxr/test_modular.py"
 )
 
 CXR_NATIVE_GPU_TESTS=(

src/plugins/oak/README.md

@@ -144,7 +144,7 @@ with TeleopSession(config) as session:
         session.step()  # metadata is recorded each update
 ```
 
-See also `examples/oxr/python/test_oak_camera.py --mode schema-pusher` for a
+See also `examples/oxr/python/isaacteleop_examples/oxr/test_oak_camera.py --mode schema-pusher` for a
 standalone PluginManager + DeviceIOSession example of the same SchemaPusher
 flow.
 

tests/AGENTS.md

@@ -61,5 +61,5 @@ Shared C++ fixtures (not executables) live under `tests/cpp/viz/support/`
 ## Out of scope here
 
 - `src/core/codegen/test_*.py` — unittest, co-located with the generator.
-- `examples/oxr/python/test_*.py` — standalone scripts for CloudXR GPU CI.
+- `examples/oxr/python/isaacteleop_examples/oxr/test_*.py` — standalone scripts for CloudXR GPU CI.
 - ROS2 Docker integration helpers under `examples/teleop_ros2/.../integration_tests/`.