hand-tracking-sdk 0.1.0__tar.gz

hand_tracking_sdk-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python cache/artifacts
+__pycache__/
+*.py[oc]
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+
+# IDE/system
+.DS_Store
+.vscode/
+.idea/

hand_tracking_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

hand_tracking_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,129 @@
+# AGENTS.md - Hand Tracking SDK
+
+This file defines how coding agents should work in `hand-tracking-sdk/`.
+
+## Scope
+- Primary working directory: `hand-tracking-sdk/`
+- Goal: build a professional, production-ready Python SDK for Hand Tracking Streamer (HTS), distributed on PyPI.
+- Source protocol reference: `../hand-tracking-streamer/CONNECTIONS.md`
+- Product context: `../hand-tracking-streamer/README.md`
+
+## Environment and Tooling (Required)
+- Package and environment manager: `uv`
+- Local virtual environment path: `hand-tracking-sdk/.venv`
+- Prefer `uv` commands over raw `pip`/`python` invocations.
+- Standard workflow:
+  - `uv sync`
+  - `uv run pytest`
+  - `uv run ruff check .`
+  - `uv run mypy src`
+  - `uv build`
+
+## Non-negotiables
+- Keep changes focused and minimal for each task.
+- Preserve backward compatibility unless explicitly requested.
+- Prefer typed public interfaces and strict validation.
+- Add tests for behavior changes and bug fixes.
+- Avoid speculative abstractions; implement only what current use cases need.
+- Keep runtime dependencies minimal.
+- Follow PEP 8 style and PEP 257 docstring conventions for public modules, classes, and functions.
+
+## PyPI/Release Quality Bar
+- SDK must be installable as a normal package (src layout preferred).
+- Public API surface should be explicit and stable.
+- Maintain semantic versioning discipline.
+- Ensure metadata quality in `pyproject.toml` (license, classifiers, URLs, Python versions).
+- No release without passing lint, type-check, and tests.
+
+## HTS Data Contract (Current)
+HTS emits UTF-8 CSV text lines with a leading label:
+- `Right wrist:` / `Left wrist:` followed by 7 floats:
+  - `x, y, z, qx, qy, qz, qw`
+- `Right landmarks:` / `Left landmarks:` followed by 63 floats:
+  - `21` joints x `3` coords in OpenXR-derived order documented in `CONNECTIONS.md`.
+
+Joint count and order are part of the public parsing contract. Treat them as versioned behavior.
+
+## Coordinate Conventions
+- Incoming HTS data uses Unity left-hand coordinate convention.
+- Most Python robotics stacks assume right-hand coordinates.
+- Make conversion behavior explicit via clear API flags/utilities.
+- Never apply implicit frame conversion without documentation.
+
+## Architecture Guidance
+Preferred module boundaries:
+- `transport/`: UDP/TCP ingestion primitives
+- `parser/`: robust line parsing and schema mapping
+- `models/`: typed data objects
+- `convert/`: coordinate and frame conversion helpers
+- `stream/` or `client/`: user-facing streaming API
+
+Keep boundaries clean even when implementing minimal first versions.
+
+## Reliability and Parsing Rules
+- Be tolerant to whitespace and trailing separators.
+- Reject malformed lines with structured exceptions.
+- Validate exact numeric lengths:
+  - wrist = 7
+  - landmarks = 63
+- No silent truncation or padding.
+- If partial updates are supported, define deterministic frame assembly policy.
+
+## Networking Expectations
+Support HTS modes documented today:
+- UDP (wireless)
+- TCP wired (`adb reverse tcp:8000 tcp:8000`)
+- TCP wireless
+
+Keep defaults aligned with HTS docs unless explicitly overridden.
+
+## API Design Expectations
+- Provide both low-level raw-line access and high-level parsed objects.
+- Favor iterator/callback APIs instead of global mutable state.
+- Include receive timestamps for downstream synchronization.
+- Keep public objects serialization-friendly and deterministic to support downstream middleware bridges.
+
+## Docstring and Documentation Standard
+- Use Sphinx-friendly docstrings (reStructuredText style) for public APIs.
+- Public callables should document:
+  - purpose and behavioral contract
+  - parameter types/meaning/units
+  - return type/shape
+  - raised exceptions
+  - coordinate/frame conventions when relevant
+- Keep docstrings precise and implementation-agnostic; avoid duplicating obvious code details.
+- If API behavior changes, update docstrings in the same change set.
+
+## ROS2 Compatibility Considerations
+- Do not add hard ROS2 runtime dependency in core SDK unless explicitly requested.
+- Design core APIs so ROS2 adapters can be built cleanly on top:
+  - explicit timestamps and stable packet schemas
+  - explicit coordinate/frame conversion entry points
+  - side and packet type enums suitable for message mapping
+  - predictable streaming interfaces that can back publishers/subscribers
+- Keep transport, parsing, and conversion layers decoupled so a future `ros2` integration package can wrap the SDK without forking core logic.
+
+## Testing Requirements
+- Unit tests for:
+  - wrist parsing
+  - landmark parsing
+  - side/type routing
+  - malformed input handling
+  - coordinate conversion behavior
+- Use realistic fixtures aligned with `CONNECTIONS.md`.
+- Keep network tests deterministic (loopback or mocked sockets).
+
+## Documentation Expectations
+- Keep `README.md` focused on SDK usage and behavior, not contributor workflow detail.
+- Document protocol assumptions and version-specific behavior.
+- Update docs whenever parsing contract or API changes.
+
+## Out of Scope (Unless Requested)
+- Unity-side feature work
+- Changing HTS upstream protocol
+- Heavy framework integrations in core package (ROS, MuJoCo, etc.)
+
+## Working Style for Agents
+- State assumptions briefly before major refactors.
+- Implement end-to-end when possible: code + tests + docs.
+- If requirements are unclear, propose concise options and continue with the safest default.

hand_tracking_sdk-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Zhengyang Kris Weng
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

hand_tracking_sdk-0.1.0/MILESTONES.md

@@ -0,0 +1,118 @@
+# Milestones - Hand Tracking SDK
+
+This document tracks delivery for a production-ready Python SDK for Hand Tracking Streamer (HTS).
+
+## Milestone 0 - Foundation (Done)
+- Status: Completed
+- Scope:
+  - project scaffold with `src/` layout
+  - packaging metadata in `pyproject.toml`
+  - typed core models and parser
+  - baseline tests + lint + type-check setup
+  - agent guidelines for `uv`, docstrings, and ROS2-aware design
+- Exit criteria:
+  - package installs locally
+  - parser handles valid and malformed lines
+  - CI-equivalent local checks pass
+
+## Milestone 1 - Transport Ingestion
+- Status: Completed
+- Scope:
+  - UDP receiver
+  - TCP receiver/client paths for HTS wired/wireless usage
+  - deterministic timeout, reconnect, and graceful shutdown behavior
+  - configurable host/port/protocol settings
+- Exit criteria:
+  - integration tests with loopback sockets
+  - documented behavior for disconnects/timeouts
+  - no parser regressions
+
+## Milestone 2 - Frame Assembly + Time Model
+- Status: Completed
+- Scope:
+  - assemble wrist + landmarks into coherent per-hand frames
+  - explicit policy for partial and out-of-order updates
+  - normalized timestamps (`recv_ts_ns` monotonic + optional wall clock)
+  - frame sequencing metadata
+- Exit criteria:
+  - deterministic assembly tests
+  - API guarantees documented
+
+## Milestone 3 - Coordinate Conversion API
+- Status: Completed
+- Scope:
+  - explicit conversion utilities for Unity left-handed data
+  - configurable conversion profile for right-handed robotics stacks
+  - quaternion handling rules documented and tested
+- Exit criteria:
+  - unit tests for axis/sign conventions
+  - examples demonstrating converted output
+
+## Milestone 4 - Public Streaming Client API
+- Status: Completed
+- Scope:
+  - high-level sync iterator client
+  - callback-based streaming option
+  - filtering controls (left/right/bimanual, packet/frame type)
+  - error policy controls (strict vs tolerant)
+- Exit criteria:
+  - stable public API for first prerelease
+  - end-to-end tests with synthetic transport input
+
+## Milestone 5 - Observability + Error Model
+- Status: Planned
+- Scope:
+  - richer exception hierarchy
+  - counters/metrics (dropped packets, parse failures, reconnects)
+  - optional structured logging hooks
+- Exit criteria:
+  - test coverage for error pathways
+  - clear operational troubleshooting docs
+
+## Milestone 6 - ROS2 Readiness (Core SDK, No Hard ROS Dependency)
+- Status: Planned
+- Scope:
+  - ROS-adapter-friendly frame dataclasses
+  - explicit frame identifiers and timestamp fields
+  - serialization helpers for predictable message mapping
+  - docs for mapping SDK types -> ROS messages
+- Exit criteria:
+  - proof-of-mapping examples for `geometry_msgs`/`sensor_msgs` style payloads
+  - no ROS imports in core package
+
+## Milestone 7 - Docs and API Reference
+- Status: Planned
+- Scope:
+  - user-facing README quickstarts (UDP/TCP modes)
+  - Sphinx API reference generation from docstrings
+  - protocol assumptions + coordinate caveats
+- Exit criteria:
+  - docs build successfully
+  - quickstart examples verified
+
+## Milestone 8 - Release Pipeline and PyPI Readiness
+- Status: Planned
+- Scope:
+  - CI pipeline for lint, type-check, tests, build
+  - release checklist and semantic version process
+  - TestPyPI publish + install verification
+  - production PyPI release process
+- Exit criteria:
+  - tagged release candidate published to TestPyPI
+  - reproducible release process documented
+
+## Milestone 9 - First Stable Release (v1.0.0)
+- Status: Planned
+- Scope:
+  - API freeze for core parsing/streaming models
+  - migration notes (if needed)
+  - performance and reliability sign-off
+- Exit criteria:
+  - compatibility statement published
+  - v1.0.0 released to PyPI
+
+## Backlog (Post-v1)
+- optional async-native API
+- optional NumPy acceleration paths
+- separate `hand-tracking-sdk-ros2` adapter package
+- recording/replay tooling for offline debugging and ML datasets

hand_tracking_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: hand-tracking-sdk
+Version: 0.1.0
+Summary: Python SDK for Hand Tracking Streamer telemetry
+Project-URL: Homepage, https://github.com/wengmister/hand-tracking-streamer
+Project-URL: Documentation, https://github.com/wengmister/hand-tracking-streamer/blob/main/CONNECTIONS.md
+Project-URL: Source, https://github.com/wengmister/hand-tracking-streamer
+Project-URL: Issues, https://github.com/wengmister/hand-tracking-streamer/issues
+Author: Hand Tracking SDK Contributors
+License: Apache-2.0
+License-File: LICENSE
+Keywords: hand-tracking,quest,robotics,sdk,teleoperation,vr
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: lark>=1.3.1
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# Hand Tracking SDK
+
+Python SDK for consuming telemetry from [Hand Tracking Streamer (HTS)](https://github.com/wengmister/hand-tracking-streamer).
+
+## Overview
+
+HTS streams UTF-8 CSV lines for wrist pose and hand landmarks.  
+This SDK provides typed parsing and validation for:
+- wrist packets: 7 floats (`x, y, z, qx, qy, qz, qw`)
+- landmark packets: 63 floats (`21 x [x, y, z]`)
+
+Streamed joints are in Mediapipe-style 21 landmark points.
+
+>[!IMPORTANT]
+> Pre-release: This library is actively under development. Expect breaking changes to come.
+
+## Transport API
+
+The SDK includes socket transport primitives for line-based ingestion:
+- `UDPLineReceiver`
+- `TCPServerLineReceiver`
+- `TCPClientLineReceiver`
+
+Network timeout and disconnect behavior is reported through typed exceptions:
+- `TransportTimeoutError`
+- `TransportDisconnectedError`
+- `TransportClosedError`
+
+## Frame Assembly API
+
+Use `HandFrameAssembler` to combine wrist and landmark packets into coherent per-hand frames.
+
+- Emits a frame only after both components are present for a hand.
+- Ignores stale out-of-order updates (older receive timestamps).
+- Increments `sequence_id` per hand side on each newly emitted frame.
+- Supports:
+  - `recv_ts_ns` (monotonic receive time)
+  - `recv_time_unix_ns` (optional wall-clock receive time)
+  - `source_ts_ns` (optional upstream timestamp; currently caller-provided)
+
+## Coordinate Conversion API
+
+The SDK provides explicit Unity-left-handed to right-handed conversion helpers:
+- `unity_left_to_right_position`
+- `unity_left_to_right_quaternion`
+- `convert_wrist_pose_unity_left_to_right`
+- `convert_landmarks_unity_left_to_right`
+- `convert_hand_frame_unity_left_to_right`
+
+Current conversion profile:
+- position: flip Y sign (`x, y, z -> x, -y, z`)
+- orientation: basis transform equivalent to Y-axis reflection
+
+```python
+from hand_tracking_sdk import (
+    HandFrameAssembler,
+    convert_hand_frame_unity_left_to_right,
+)
+
+assembler = HandFrameAssembler()
+frame = assembler.push_line("Right wrist:, 0.1, 0.2, 0.3, 0.0, 0.0, 0.0, 1.0")
+if frame is not None:
+    converted = convert_hand_frame_unity_left_to_right(frame)
+```
+
+## Streaming Client API
+
+`HTSClient` provides a high-level sync stream with filtering and error policy controls.
+
+Key controls:
+- transport mode: `udp`, `tcp_server`, `tcp_client`
+- output mode: `packets`, `frames`, `both`
+- hand filter: `left`, `right`, `both`
+- parse error policy: `strict` (raise) or `tolerant` (skip malformed lines)
+
+```python
+from hand_tracking_sdk import HTSClient, HTSClientConfig, StreamOutput
+
+client = HTSClient(HTSClientConfig(output=StreamOutput.FRAMES))
+for event in client.iter_events():
+    print(event)
+```
+
+## Example
+
+```python
+from hand_tracking_sdk import parse_line
+
+packet = parse_line("Right wrist:, 0.1, 0.2, 0.3, 0.0, 0.0, 0.0, 1.0")
+print(packet.side, packet.kind, packet.data)
+```
+
+The parser validates packet label, side, and value count, and raises `ParseError` on malformed input.
+
+## Protocol Reference
+
+- [`hand-tracking-streamer/README.md`](https://github.com/wengmister/hand-tracking-streamer/blob/main/README.md)
+- [`hand-tracking-streamer/CONNECTIONS.md`](https://github.com/wengmister/hand-tracking-streamer/blob/main/CONNECTIONS.md)
+
+
+## License
+Apache-2.0