From 8a57c702e557639ba87b003efbea27b36bca6ae0 Mon Sep 17 00:00:00 2001 From: Jiwen Cai Date: Fri, 28 Aug 2026 04:33:44 +0000 Subject: [PATCH] examples(teleop_session_manager): package under isaacteleop_examples teleop_controls_simple_example.py imported its helper as a top-level module, which resolved only because the invoked script's own directory landed on sys.path -- so it broke under `python -m`, broke when copied into another project, and claimed the bare name `teleop_controls_simple_helper`. Move the tree to the layout in examples/README.md. The four demos here are co-equal, so there is no __main__.py to pick: each is its own submodule and the README lists them. Inventing a default would have made one of the four look privileged. The README moves up beside the pyproject and now documents all four, rather than only teleop_session_example. Part of NVIDIA/IsaacTeleop#985. Signed-off-by: Jiwen Cai --- .../teleop_control_state_machine.rst | 2 +- .../teleop_session_manager/CMakeLists.txt | 4 +- examples/teleop_session_manager/README.md | 26 ++++++++++++ .../teleop_session_manager/pyproject.toml | 26 ++++++++++++ .../teleop_session_manager/python/README.md | 40 ------------------- .../teleop_session_manager/__init__.py | 2 + .../external_inputs_example.py | 6 ++- .../message_channel_example.py | 0 .../teleop_controls_simple_example.py | 2 +- .../teleop_controls_simple_helper.py | 0 .../teleop_session_example.py | 6 ++- .../python/pyproject.toml | 12 ------ 12 files changed, 66 insertions(+), 60 deletions(-) create mode 100644 examples/teleop_session_manager/README.md create mode 100644 examples/teleop_session_manager/pyproject.toml delete mode 100644 examples/teleop_session_manager/python/README.md create mode 100644 examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/__init__.py rename examples/teleop_session_manager/python/{ => isaacteleop_examples/teleop_session_manager}/external_inputs_example.py (98%) rename examples/teleop_session_manager/python/{ => isaacteleop_examples/teleop_session_manager}/message_channel_example.py (100%) rename examples/teleop_session_manager/python/{ => isaacteleop_examples/teleop_session_manager}/teleop_controls_simple_example.py (99%) rename examples/teleop_session_manager/python/{ => isaacteleop_examples/teleop_session_manager}/teleop_controls_simple_helper.py (100%) rename examples/teleop_session_manager/python/{ => isaacteleop_examples/teleop_session_manager}/teleop_session_example.py (96%) delete mode 100644 examples/teleop_session_manager/python/pyproject.toml diff --git a/docs/source/getting_started/teleop_control_state_machine.rst b/docs/source/getting_started/teleop_control_state_machine.rst index 1b2d3b606d..0a9b7ba3c6 100644 --- a/docs/source/getting_started/teleop_control_state_machine.rst +++ b/docs/source/getting_started/teleop_control_state_machine.rst @@ -69,7 +69,7 @@ Connecting Inputs ----------------- Use one debounced selector per signal (simple wiring, no multi-input lambdas): -see :code-file:`teleop_controls_simple_example.py ` +see :code-file:`teleop_controls_simple_example.py ` for the full runnable setup. .. code-block:: python diff --git a/examples/teleop_session_manager/CMakeLists.txt b/examples/teleop_session_manager/CMakeLists.txt index 687c4deed6..3a39adaed4 100644 --- a/examples/teleop_session_manager/CMakeLists.txt +++ b/examples/teleop_session_manager/CMakeLists.txt @@ -1,7 +1,7 @@ -# 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) include(${CMAKE_SOURCE_DIR}/cmake/InstallPythonExample.cmake) -install_python_example(DESTINATION examples/teleop_session_manager/python) +install_python_example(DESTINATION examples/teleop_session_manager) diff --git a/examples/teleop_session_manager/README.md b/examples/teleop_session_manager/README.md new file mode 100644 index 0000000000..862d8fe937 --- /dev/null +++ b/examples/teleop_session_manager/README.md @@ -0,0 +1,26 @@ + + +# TeleopSessionManager examples + +Four standalone demos of the `TeleopSession` API. Install once, then run +whichever one you want: + +```bash +uv pip install -e ./examples/teleop_session_manager +python -m isaacteleop_examples.teleop_session_manager.teleop_session_example +``` + +| Module | What it shows | +| --- | --- | +| `teleop_session_example` | Velocity from hand-wrist and controller motion, driven by `session.step()` with the synthetic hands plugin | +| `teleop_controls_simple_example` | The simplified controls helper, with the state machine in `teleop_controls_simple_helper` | +| `external_inputs_example` | Feeding a session from an input source outside DeviceIO | +| `message_channel_example` | Sending and receiving on a session message channel | + +## See also + +- Module docs: `docs/source/references/teleop_session.rst` +- Retargeting engine: `src/core/retargeting_engine/` diff --git a/examples/teleop_session_manager/pyproject.toml b/examples/teleop_session_manager/pyproject.toml new file mode 100644 index 0000000000..e83fba56d6 --- /dev/null +++ b/examples/teleop_session_manager/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-teleop-session-manager" +version = "0.0.0" # Internal examples - not versioned +description = "TeleopUtils Python Examples" +requires-python = ">=3.11,<3.14" +dependencies = [ + "isaacteleop[ui]", + "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 `teleop_session_manager/`. +[tool.hatch.build.targets.wheel] +only-include = ["python/isaacteleop_examples/teleop_session_manager"] +sources = ["python"] diff --git a/examples/teleop_session_manager/python/README.md b/examples/teleop_session_manager/python/README.md deleted file mode 100644 index 1962af801d..0000000000 --- a/examples/teleop_session_manager/python/README.md +++ /dev/null @@ -1,40 +0,0 @@ - - -# TeleopSessionManager Examples - -Example demonstrating the TeleopSession API with velocity tracking. - -## Example - -### Velocity Tracker (`teleop_session_example.py`) - -Demonstrates computing velocity from hand and controller movements: -- Tracks hand wrist positions and controller positions -- Computes velocity from position changes -- Uses synthetic hands plugin -- Shows TeleopSession usage with `session.step()` - -**Usage:** -```bash -python teleop_session_example.py -``` - -## Quick Start - -```bash -# Build & Install -cd IsaacTeleop -cmake -B build && cmake --build build --target install -j16 - -# Run example -cd install/examples/teleop_session_manager/python -uv run teleop_session_example.py -``` - -## See Also - -- **Module docs:** `docs/source/references/teleop_session.rst` -- **Retargeting engine:** `src/core/retargeting_engine/` diff --git a/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/__init__.py b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/__init__.py new file mode 100644 index 0000000000..52a7a9daf0 --- /dev/null +++ b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/__init__.py @@ -0,0 +1,2 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 diff --git a/examples/teleop_session_manager/python/external_inputs_example.py b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/external_inputs_example.py similarity index 98% rename from examples/teleop_session_manager/python/external_inputs_example.py rename to examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/external_inputs_example.py index eeecdece44..ce19fa9d6c 100644 --- a/examples/teleop_session_manager/python/external_inputs_example.py +++ b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/external_inputs_example.py @@ -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 """ @@ -78,7 +78,9 @@ ) -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" # ============================================================================== diff --git a/examples/teleop_session_manager/python/message_channel_example.py b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/message_channel_example.py similarity index 100% rename from examples/teleop_session_manager/python/message_channel_example.py rename to examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/message_channel_example.py diff --git a/examples/teleop_session_manager/python/teleop_controls_simple_example.py b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_controls_simple_example.py similarity index 99% rename from examples/teleop_session_manager/python/teleop_controls_simple_example.py rename to examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_controls_simple_example.py index 6e6e24e82d..9a0279eb33 100644 --- a/examples/teleop_session_manager/python/teleop_controls_simple_example.py +++ b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_controls_simple_example.py @@ -38,7 +38,7 @@ DefaultTeleopStateManager, ) -from teleop_controls_simple_helper import ( +from .teleop_controls_simple_helper import ( build_observation_pipeline, print_frame, print_header, diff --git a/examples/teleop_session_manager/python/teleop_controls_simple_helper.py b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_controls_simple_helper.py similarity index 100% rename from examples/teleop_session_manager/python/teleop_controls_simple_helper.py rename to examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_controls_simple_helper.py diff --git a/examples/teleop_session_manager/python/teleop_session_example.py b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_session_example.py similarity index 96% rename from examples/teleop_session_manager/python/teleop_session_example.py rename to examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_session_example.py index c7e12ff3ca..a1b135fce8 100644 --- a/examples/teleop_session_manager/python/teleop_session_example.py +++ b/examples/teleop_session_manager/python/isaacteleop_examples/teleop_session_manager/teleop_session_example.py @@ -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 """ @@ -47,7 +47,9 @@ from isaacteleop.retargeting_engine.tensor_types import FloatType -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" # ============================================================================== diff --git a/examples/teleop_session_manager/python/pyproject.toml b/examples/teleop_session_manager/python/pyproject.toml deleted file mode 100644 index 2152e1b474..0000000000 --- a/examples/teleop_session_manager/python/pyproject.toml +++ /dev/null @@ -1,12 +0,0 @@ -# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -# SPDX-License-Identifier: Apache-2.0 - -[project] -name = "teleop-utils-examples" -version = "0.0.0" # Internal examples - not versioned -description = "TeleopUtils Python Examples" -requires-python = ">=3.11,<3.14" -dependencies = [ - "isaacteleop[ui]", - "numpy>=1.23.0", -]