refactor(retargeting): rename HeadPose tensor type to HeadInput

examples/deviceio_live_view/python/deviceio_viser.py

@@ -26,7 +26,7 @@
     BodyJointIndex,
     ControllerInputIndex,
     FullBodyInputIndex,
-    HeadPoseIndex,
+    HeadInputIndex,
 )
 
 HANDS_CHANNEL = "hands"
@@ -425,12 +425,12 @@ def __init__(
         )
 
     def update_if_active(self, head) -> bool:
-        if head.is_none or not bool(head[HeadPoseIndex.IS_VALID]):
+        if head.is_none or not bool(head[HeadInputIndex.IS_VALID]):
             self.frame.visible = False
             return False
 
-        position = np.asarray(head[HeadPoseIndex.POSITION], dtype=np.float32)
-        orientation = np.asarray(head[HeadPoseIndex.ORIENTATION], dtype=np.float32)
+        position = np.asarray(head[HeadInputIndex.POSITION], dtype=np.float32)
+        orientation = np.asarray(head[HeadInputIndex.ORIENTATION], dtype=np.float32)
         self.frame.position = (
             float(position[0]),
             float(position[1]),

examples/retargeting/python/sources_example.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
 
 """
@@ -34,7 +34,7 @@
 from isaacteleop.retargeting_engine.interface import OutputCombiner, TensorGroup
 from isaacteleop.retargeting_engine.tensor_types import (
     HandInputIndex,
-    HeadPoseIndex,
+    HeadInputIndex,
     ControllerInputIndex,
 )
 
@@ -226,10 +226,10 @@ def main():
                         if head.is_none:
                             print("    Status: ABSENT (no tracker)")
                         else:
-                            head_valid = head[HeadPoseIndex.IS_VALID]
+                            head_valid = head[HeadInputIndex.IS_VALID]
                             print(f"    Status: {'VALID' if head_valid else 'INVALID'}")
                             if head_valid:
-                                head_position = head[HeadPoseIndex.POSITION]
+                                head_position = head[HeadInputIndex.POSITION]
                                 print(
                                     f"    Position: [{head_position[0]:6.3f}, {head_position[1]:6.3f}, {head_position[2]:6.3f}]"
                                 )

examples/teleop_ros2/python/messages.py

@@ -22,7 +22,7 @@
     FullBodyInputIndex,
     HandInputIndex,
     HandJointIndex,
-    HeadPoseIndex,
+    HeadInputIndex,
 )
 
 from constants import BODY_JOINT_NAMES, HAND_POSE_JOINT_INDICES, HAND_POSE_NAMES
@@ -403,8 +403,8 @@ def build_head_output(
     if not head_is_valid(head):
         return None
 
-    position = [float(x) for x in head[HeadPoseIndex.POSITION]]
-    orientation = [float(x) for x in head[HeadPoseIndex.ORIENTATION]]
+    position = [float(x) for x in head[HeadInputIndex.POSITION]]
+    orientation = [float(x) for x in head[HeadInputIndex.ORIENTATION]]
     pose = to_pose(position, orientation)
     if transform_rot is not None or transform_trans is not None:
         pose = apply_transform_to_pose(pose, transform_rot, transform_trans)

examples/teleop_ros2/python/tensor_group_helpers.py

@@ -9,7 +9,7 @@
     ControllerInputIndex,
     HandInputIndex,
     HandJointIndex,
-    HeadPoseIndex,
+    HeadInputIndex,
 )
 
 
@@ -31,7 +31,7 @@ def hand_wrist_is_valid(hand: OptionalTensorGroup) -> bool:
 
 
 def head_is_valid(head: OptionalTensorGroup) -> bool:
-    return _flag_is_valid(head, HeadPoseIndex.IS_VALID)
+    return _flag_is_valid(head, HeadInputIndex.IS_VALID)
 
 
 def joint_names_from_group_type(group_type) -> list[str]:

examples/teleop_ros2/python/tests/test_messages.py

@@ -26,8 +26,8 @@
     HandInput,
     HandInputIndex,
     HandJointIndex,
-    HeadPose,
-    HeadPoseIndex,
+    HeadInput,
+    HeadInputIndex,
     RobotHandJoints,
 )
 
@@ -102,10 +102,10 @@ def _active_hand() -> TensorGroup:
 
 
 def _active_head() -> TensorGroup:
-    head = TensorGroup(HeadPose())
-    head[HeadPoseIndex.POSITION] = np.array([1.0, 2.0, 3.0], dtype=np.float32)
-    head[HeadPoseIndex.ORIENTATION] = np.array([0.0, 0.0, 0.0, 1.0], dtype=np.float32)
-    head[HeadPoseIndex.IS_VALID] = True
+    head = TensorGroup(HeadInput())
+    head[HeadInputIndex.POSITION] = np.array([1.0, 2.0, 3.0], dtype=np.float32)
+    head[HeadInputIndex.ORIENTATION] = np.array([0.0, 0.0, 0.0, 1.0], dtype=np.float32)
+    head[HeadInputIndex.IS_VALID] = True
     return head
 
 
@@ -342,7 +342,7 @@ def test_build_head_output_keeps_pose_and_tf_consistent() -> None:
 def test_build_head_output_returns_none_when_head_is_absent() -> None:
     assert (
         build_head_output(
-            OptionalTensorGroup(HeadPose()),
+            OptionalTensorGroup(HeadInput()),
             Time(),
             "world",
             "head",

examples/teleop_session_manager/python/teleop_controls_simple_helper.py

@@ -26,8 +26,8 @@
     ControllerInput,
     HandInput,
     HandInputIndex,
-    HeadPose,
-    HeadPoseIndex,
+    HeadInput,
+    HeadInputIndex,
 )
 
 
@@ -41,7 +41,7 @@ def __init__(self, name: str, print_every_n_frames: int = 30) -> None:
 
     def input_spec(self) -> RetargeterIOType:
         return {
-            "head": OptionalType(HeadPose()),
+            "head": OptionalType(HeadInput()),
             "hand_left": OptionalType(HandInput()),
             "hand_right": OptionalType(HandInput()),
             "controller_left": OptionalType(ControllerInput()),
@@ -115,7 +115,7 @@ def print_frame(outputs, elapsed: float) -> None:
 
     head_pos_str = "absent"
     if head_present:
-        p = outputs["head"][HeadPoseIndex.POSITION]
+        p = outputs["head"][HeadInputIndex.POSITION]
         head_pos_str = f"[{p[0]:+.3f}, {p[1]:+.3f}, {p[2]:+.3f}]"
 
     left_wrist_str = "absent"

src/core/retargeting_engine_tests/python/test_sources.py

@@ -23,7 +23,7 @@
 from isaacteleop.retargeting_engine.interface.base_retargeter import _make_output_group
 from isaacteleop.retargeting_engine.tensor_types import (
     ControllerInputIndex,
-    HeadPoseIndex,
+    HeadInputIndex,
 )
 from isaacteleop.schema import (
     Point,
@@ -260,12 +260,12 @@ def test_head_source_compute_active(self):
         head = outputs["head"]
         assert not head.is_none
         np.testing.assert_array_almost_equal(
-            head[HeadPoseIndex.POSITION], [1.0, 2.0, 3.0]
+            head[HeadInputIndex.POSITION], [1.0, 2.0, 3.0]
         )
         np.testing.assert_array_almost_equal(
-            head[HeadPoseIndex.ORIENTATION], [0.0, 0.0, 0.0, 1.0]
+            head[HeadInputIndex.ORIENTATION], [0.0, 0.0, 0.0, 1.0]
         )
-        assert head[HeadPoseIndex.IS_VALID] is True
+        assert head[HeadInputIndex.IS_VALID] is True
 
     def test_head_source_compute_inactive(self):
         """Test that inactive head (TrackedT.data is None) produces absent output."""
@@ -447,7 +447,7 @@ def test_active_head_produces_data(self):
 
         assert not outputs["head"].is_none
         np.testing.assert_array_almost_equal(
-            outputs["head"][HeadPoseIndex.POSITION], [0.5, 1.5, 0.0]
+            outputs["head"][HeadInputIndex.POSITION], [0.5, 1.5, 0.0]
         )
 
     def test_inactive_head_sets_none(self):
@@ -473,4 +473,4 @@ def test_absent_head_raises_on_access(self):
         source.compute(inputs, outputs)
 
         with pytest.raises(ValueError, match="absent"):
-            _ = outputs["head"][HeadPoseIndex.POSITION]
+            _ = outputs["head"][HeadInputIndex.POSITION]

src/core/retargeting_engine_tests/python/test_tensor_group.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
 
 """
@@ -642,5 +642,29 @@ def test_copy_returns_optional_tensor_group_type(self):
         assert type(cp) is OptionalTensorGroup
 
 
+class TestDeprecatedHeadAliases:
+    """``HeadPose``/``HeadPoseIndex`` still resolve to the renamed ``HeadInput``
+    names and emit a DeprecationWarning on access."""
+
+    def test_package_level_aliases_resolve_and_warn(self):
+        from isaacteleop.retargeting_engine import tensor_types
+
+        for old, new in (
+            ("HeadPose", "HeadInput"),
+            ("HeadPoseIndex", "HeadInputIndex"),
+        ):
+            with pytest.warns(DeprecationWarning, match=old):
+                deprecated = getattr(tensor_types, old)
+            assert deprecated is getattr(tensor_types, new)
+
+    def test_submodule_aliases_resolve_and_warn(self):
+        from isaacteleop.retargeting_engine.tensor_types import indices, standard_types
+
+        with pytest.warns(DeprecationWarning, match="HeadPose"):
+            assert standard_types.HeadPose is standard_types.HeadInput
+        with pytest.warns(DeprecationWarning, match="HeadPoseIndex"):
+            assert indices.HeadPoseIndex is indices.HeadInputIndex
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])