Merge pull request #50 from nickswalker/fix-axis-convention

Add ergonomic way to fix axis convention

Author: peter-mitrano-ar

README.md

@@ -112,6 +112,29 @@ with pyspacemouse.open() as device:
     print(state.t)
 ```
 
+### Axis Conventions
+
+For new code, opt into an axis convention by passing an enum value on device open:
+
+```python
+import pyspacemouse
+from pyspacemouse import AxisConvention
+
+with pyspacemouse.open(axis_convention=AxisConvention.HID_Z_UP) as device:
+    state = device.read()
+```
+
+<p align="center">
+  <img src="./docs/assets/hid_z_up_axes.svg" alt="HID Z-up axis convention" width="220">
+  <img src="./docs/assets/hid_axes.svg" alt="Raw HID axis convention" width="220">
+  <img src="./docs/assets/legacy_axis.svg" alt="Legacy PySpaceMouse axis convention" width="220">
+</p>
+
+See [Axis Conventions](./docs/mouseApi/index.md#axis-conventions) for the full
+mapping table. Custom
+`device_spec` mappings are used exactly as provided and cannot be combined with
+`axis_convention`.
+
 ### Callbacks
 
 ```python

docs/README.md

@@ -112,6 +112,29 @@ with pyspacemouse.open() as device:
     print(state.t)
 ```
 
+### Axis Conventions
+
+For new code, opt into an axis convention by passing an enum value on device open:
+
+```python
+import pyspacemouse
+from pyspacemouse import AxisConvention
+
+with pyspacemouse.open(axis_convention=AxisConvention.HID_Z_UP) as device:
+    state = device.read()
+```
+
+<p align="center">
+  <img src="./assets/hid_axes.svg" alt="Raw HID axis convention" width="220">
+  <img src="./assets/hid_z_up_axes.svg" alt="HID Z-up axis convention" width="220">
+  <img src="./assets/legacy_axis.svg" alt="Legacy PySpaceMouse axis convention" width="220">
+</p>
+
+See [Axis Conventions](./mouseApi/index.md#axis-conventions) for the full
+mapping table. Custom
+`device_spec` mappings are used exactly as provided and cannot be combined with
+`axis_convention`.
+
 ### Callbacks
 
 ```python

docs/assets/hid_axes.svg

@@ -42,7 +42,7 @@ There are also attributes:
     dev.connected       True if the device is connected, False otherwise
     dev.state           Convenience property which returns the same value as read()
 
-## State objects
+## State Objects
 
 State objects returned from `read()` have 7 attributes: [t,x,y,z,roll,pitch,yaw,button].
 
@@ -51,6 +51,40 @@ State objects returned from `read()` have 7 attributes: [t,x,y,z,roll,pitch,yaw,
 * roll, pitch, yaw: rotations in the range [-1.0, 1.0].
 * buttons: list of button states (0 or 1), in order specified in the device specifier
 
+## Axis Conventions
+
+Built-in device specs can be opened with an explicit axis convention:
+
+```python
+import pyspacemouse
+from pyspacemouse import AxisConvention
+
+with pyspacemouse.open(axis_convention=AxisConvention.HID_Z_UP) as device:
+    state = device.read()
+```
+
+<p align="center">
+  <img src="../assets/hid_axes.svg" alt="Raw HID axis convention" width="220">
+  <img src="../assets/hid_z_up_axes.svg" alt="HID Z-up axis convention" width="220">
+  <img src="../assets/legacy_axis.svg" alt="Legacy PySpaceMouse axis convention" width="220">
+</p>
+
+The same `axis_convention` argument is available on `open_by_path()` and
+`open_with_config()`.
+
+| Convention | Translation axes | Rotation axes                                  | Notes                                                                                                              |
+|------------|------------------|------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| `AxisConvention.HID` | `+x` right, `+y` toward the user, `+z` down | right-handed                                   | USB HID convention; see [HID Usage Tables, 4.2 Axis Usages](https://usb.org/document-library/hid-usage-tables-17). |
+| `AxisConvention.HID_Z_UP` | `+x` right, `+y` away from the user, `+z` up | right-handed                                   | HID frame, rotated -180 degrees about +X so Z points up                                                            |
+| `AxisConvention.LEGACY` | `x=+HID_x`, `y=-HID_y`, `z=-HID_z` | `roll=-HID_Ry`, `pitch=-HID_Rx`, `yaw=+HID_Rz` | Deprecated. Default for backward compatibility.                                                                    |
+
+For new code, select a convention that matches your need. Use `AxisConvention.LEGACY` only for existing code that
+depends on the old PySpaceMouse signs or labels.
+
+Custom `device_spec` mappings are used exactly as provided. If you pass a
+custom `device_spec`, do not also pass `axis_convention`; adjust the mapping
+with `create_device_info()` or `modify_device_info()` instead.
+
 ## Custom Device Configuration
 
 You can customize axis mappings without modifying the TOML configuration by using the helper functions:

docs/assets/hid_z_up_axes.svg

@@ -52,7 +52,7 @@
 )
 
 # Config helpers (for custom device configurations)
-from .config_helpers import create_device_info, modify_device_info
+from .config_helpers import apply_axis_convention, create_device_info, modify_device_info
 
 # Device class
 from .device import SpaceMouseDevice
@@ -62,6 +62,7 @@
 from .types import (
     AXIS_NAMES,
     Axis,
+    AxisConvention,
     AxisSpec,
     ButtonSpec,
     ButtonState,
@@ -82,6 +83,7 @@
     # Types
     "Axis",
     "AXIS_NAMES",
+    "AxisConvention",
     "AxisSpec",
     "ButtonSpec",
     "ButtonState",
@@ -108,6 +110,7 @@
     "get_device_specs",
     "load_device_specs",
     # Config helpers
+    "apply_axis_convention",
     "create_device_info",
     "modify_device_info",
 ]

docs/assets/legacy_axis.svg

@@ -16,15 +16,17 @@
 
 from __future__ import annotations
 
+import warnings
 from pathlib import Path
 from typing import Callable, List, Optional, Sequence, Tuple
 
 from easyhid import Enumeration
 
 from .callbacks import ButtonCallback, Config, DofCallback
+from .config_helpers import apply_axis_convention
 from .device import SpaceMouseDevice
 from .loader import get_device_specs
-from .types import DeviceInfo, SpaceMouseState
+from .types import AxisConvention, DeviceInfo, SpaceMouseState
 
 
 def get_connected_devices() -> List[str]:
@@ -100,11 +102,33 @@ def _create_and_open_device(
     button_callback: Optional[Callable[[SpaceMouseState, List[int]], None]] = None,
     button_callbacks: Optional[Sequence[ButtonCallback]] = None,
     nonblocking: bool = True,
+    axis_convention: Optional[AxisConvention] = None,
+    is_custom_spec: bool = False,
 ) -> SpaceMouseDevice:
     """Create, configure and open a SpaceMouseDevice.
 
     This is a shared helper to avoid duplication between open() and open_by_path().
     """
+    if is_custom_spec and axis_convention is not None:
+        raise ValueError(
+            "axis_convention and device_spec are mutually exclusive. "
+            "Manually change the axis mapping in the spec if you need to."
+        )
+    if not is_custom_spec:
+        axis_convention = (
+            AxisConvention.LEGACY if axis_convention is None else AxisConvention(axis_convention)
+        )
+        if axis_convention == AxisConvention.LEGACY:
+            warnings.warn(
+                "AxisConvention.LEGACY is deprecated for built-in device specs "
+                "and will be removed in a future release. Pass "
+                "axis_convention=AxisConvention.HID_Z_UP for the recommended "
+                "right-handed Z-up frame, or AxisConvention.HID for raw HID axes.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+        spec = apply_axis_convention(spec, axis_convention)
+
     mouse = SpaceMouseDevice(info=spec, device=hid_device)
     mouse.configure(
         callback=callback,
@@ -127,6 +151,7 @@ def open_by_path(
     button_callbacks: Optional[Sequence[ButtonCallback]] = None,
     nonblocking: bool = True,
     device_spec: Optional[DeviceInfo] = None,
+    axis_convention: Optional[AxisConvention] = None,
 ) -> SpaceMouseDevice:
     """Open a SpaceMouse device by its filesystem path.
 
@@ -143,7 +168,13 @@ def open_by_path(
         nonblocking: If True, use non-blocking reads (required for callbacks)
         device_spec: Optional custom DeviceInfo. If provided, uses this
                      instead of looking up by VID/PID. Useful for custom
-                     axis mappings or unsupported devices.
+                     axis mappings or unsupported devices. Custom specs are
+                     used exactly as provided.
+        axis_convention: Coordinate convention for axis values. If None,
+                         uses the deprecated legacy convention for backward
+                         compatibility. Use AxisConvention.HID_Z_UP for a
+                         right-handed Z-up frame. Mutually exclusive with
+                         device_spec.
 
     Returns:
         SpaceMouseDevice instance (use as context manager for auto-cleanup)
@@ -175,7 +206,8 @@ def open_by_path(
         raise FileNotFoundError(f"No HID device found at path '{path}'.")
 
     # Use provided spec or find matching device specification
-    if device_spec is not None:
+    is_custom_spec = device_spec is not None
+    if is_custom_spec:
         spec = device_spec
     else:
         all_specs = get_device_specs()
@@ -207,6 +239,8 @@ def open_by_path(
         button_callback=button_callback,
         button_callbacks=button_callbacks,
         nonblocking=nonblocking,
+        axis_convention=axis_convention,
+        is_custom_spec=is_custom_spec,
     )
 
 
@@ -220,6 +254,7 @@ def open(
     device: Optional[str] = None,
     device_index: int = 0,
     device_spec: Optional[DeviceInfo] = None,
+    axis_convention: Optional[AxisConvention] = None,
 ) -> SpaceMouseDevice:
     """Open a SpaceMouse device by name or auto-detection.
 
@@ -240,7 +275,14 @@ def open(
         device_spec: Optional custom DeviceInfo. If provided, uses this
                      instead of looking up from TOML. Useful for custom
                      axis mappings. The device/device_index are still used
-                     to find the HID device.
+                     to find the HID device. Custom specs are used exactly
+                     as provided.
+        axis_convention: Coordinate convention for axis values. If None,
+                         uses the deprecated legacy convention for backward
+                         compatibility. Use AxisConvention.HID_Z_UP for a
+                         geometrically consistent right-handed Z-up frame, or
+                         AxisConvention.HID for raw HID values (Z down).
+                         Mutually exclusive with device_spec.
 
     Returns:
         SpaceMouseDevice instance (use as context manager for auto-cleanup)
@@ -261,8 +303,9 @@ def open(
     if device not in device_specs:
         raise ValueError(f"Unknown device: '{device}'. Available: {list(device_specs.keys())}")
 
-    # Use provided spec or get from TOML
-    spec = device_spec if device_spec is not None else device_specs[device]
+    # Use provided spec exactly as-is, or get from TOML and apply convention.
+    is_custom_spec = device_spec is not None
+    spec = device_spec if is_custom_spec else device_specs[device]
 
     # Find matching HID devices
     hid = Enumeration()
@@ -291,6 +334,8 @@ def open(
         button_callback=button_callback,
         button_callbacks=button_callbacks,
         nonblocking=nonblocking,
+        axis_convention=axis_convention,
+        is_custom_spec=is_custom_spec,
     )
 
 
@@ -299,6 +344,7 @@ def open_with_config(
     nonblocking: bool = True,
     device: Optional[str] = None,
     device_index: int = 0,
+    axis_convention: Optional[AxisConvention] = None,
 ) -> SpaceMouseDevice:
     """Open a SpaceMouse device using a Config object.
 
@@ -307,6 +353,7 @@ def open_with_config(
         nonblocking: If True, use non-blocking reads
         device: Device name to open
         device_index: Which instance to open if multiple connected
+        axis_convention: Coordinate convention for axis values (see open()).
 
     Returns:
         SpaceMouseDevice instance (use as context manager for auto-cleanup)
@@ -320,4 +367,5 @@ def open_with_config(
         nonblocking=nonblocking,
         device=device,
         device_index=device_index,
+        axis_convention=axis_convention,
     )