Metadata-Version: 2.5
Name: source-robotics-leap-motion
Version: 0.1.0b1
Summary: Modern Leap Motion tracking and configurable robot-arm teleoperation primitives
Project-URL: Homepage, https://github.com/Source-Robotics/Source-Robotics-Leap-Motion
Project-URL: Documentation, https://github.com/Source-Robotics/Source-Robotics-Leap-Motion#readme
Project-URL: Issues, https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/issues
Project-URL: Releases, https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/releases
Author: Source Robotics
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: typing-extensions>=4.4; python_version < '3.11'
Requires-Dist: websocket-client<2,>=1.8
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.14; extra == 'dev'
Description-Content-Type: text/markdown

**Source Robotics Leap Motion - 0.1.0b1 release candidate**

A Python package for the **Original Leap Motion Controller**, with owned hand data,
recording/replay, and configurable coordinate mapping for custom robot integrations.
It runs on current Python without `LeapPython.pyd` or a Python 3.8 process.

The beta is distributed through this repository's `v0.1.0b1` GitHub release. PyPI
publication is being configured. Install the wheel directly, then start tracking:

```powershell
python -m pip install https://github.com/Source-Robotics/Source-Robotics-Leap-Motion/releases/download/v0.1.0b1/source_robotics_leap_motion-0.1.0b1-py3-none-any.whl
source-leap
```

The Windows engine downloads automatically when needed. First-use driver setup may
require Windows approval. See [release status and validation](docs/BETA_VALIDATION.md)
and [publication steps](docs/RELEASING.md). Linux/macOS currently use an installed
vendor tracking service and remain experimental for hardware use.

**Try it in this project's virtual environment.** Python 3.15.2 and the package are
already installed in `.venv`. No activation is necessary:

```powershell
.\.venv\Scripts\source-leap.exe --demo
.\.venv\Scripts\source-leap.exe setup
.\.venv\Scripts\source-leap.exe doctor --probe
.\.venv\Scripts\source-leap.exe
```

The first command shows synthetic hand motion. The last uses a connected controller.
Stop with Ctrl+C. Add `--frames 60` or `--duration 5` for a bounded run.
`source-leap.cmd --demo` is a convenience wrapper for this checkout.

To install the source in another existing environment:

```powershell
python -m pip install .
source-leap --demo
```

Python **3.10 or newer** is required. The wheel has been installed and tested on
**CPython 3.10.11, 3.11.9, 3.12.10, 3.13.17, 3.14.10, and 3.15.2, Windows x64**.
Each version passed all 86 tests, received live camera frames, and replayed a recorded
real hand. Python 3.10 additionally uses small `tomli` and `typing-extensions`
backports, installed automatically by pip. All versions use `websocket-client`.
Python 3.9 and earlier are not supported by the new package.

The [compatibility and performance report](docs/COMPATIBILITY_PERFORMANCE.md) explains
the test matrix, measured stream rate, comparison with the original Python 3.8 SDK,
and remaining limits. The tracking engine and driver are unchanged; no improvement
in tracking accuracy or camera frame rate is claimed.

**Automatic runtime selection.** `Tracker()` and `source-leap` reuse an installed
compatible service or find the cached private runtime automatically. If neither is
available, the release catalog supplies a pinned Windows download. Its SHA-256 and
file sizes are checked, interrupted transfers resume, and installation is atomic.
The compressed download is removed after installation to keep one extracted copy.
Imports perform no downloads, device access, or background startup.

The service path supports LeapC and the local protocol-v6 WebSocket endpoint.
On this PC, the fallback was verified with service `3.2.1+45911` on
`127.0.0.1:6437` and the actual Original Leap Motion Controller. A 30-second check
captured 3,399 frames, including 53 frames containing a left hand with all five
fingers and four bones per finger. Recording and replay also passed. See
[the hardware validation notes](docs/HARDWARE_VALIDATION.md).

An existing working legacy service can therefore be used without upgrading it.
The native LeapC loader supports Windows x64, Linux x64, and macOS Intel/Apple
Silicon. Linux/macOS hardware integration remains experimental and needs a compatible
vendor service. Windows private-engine operation has been hardware-tested. No vendor
DLLs or model data are included in the Python wheel; the Windows runtime is a separate
GitHub release asset. Clean-PC driver setup still needs a real hardware test.

**First-use setup.** `source-leap setup` reports device status and probes actual frames.
An unplugged device is distinguished from Windows problem code 28 (missing driver).
Only an explicit `--install-driver` action or an accepted interactive prompt requests
Windows approval. A working driver is not replaced. `--open-downloads` opens the
official platform setup page. Linux instructions point to the vendor's core service
package; macOS instructions select the appropriate vendor installation.

An offline Windows installation is also available:

```powershell
.\.venv\Scripts\source-leap.exe setup --archive dist\runtime\source-leap-runtime-windows-x86_64-3.2.1.zip
```

`SOURCE_LEAP_CACHE` selects a development/test cache. Normal users need no environment
variables. `--catalog PATH` is a setup/deployment override for a release catalog.

**Private Windows runtime.** Developers can prepare a local engine copy without the
control panel or visualizer:

```powershell
.\.venv\Scripts\source-leap.exe runtime prepare "C:\Program Files (x86)\Leap Motion\Core Services" --destination .tools\private-runtime-321 --dependencies .
.\.venv\Scripts\source-leap.exe runtime inspect .tools\private-runtime-321
.\.venv\Scripts\source-leap.exe monitor --runtime-dir .tools\private-runtime-321
```

Preparation copies local files and records checksums. Applications acquire leases on
a hidden coordinator that starts the engine and waits for an actual camera frame.
Closing one application keeps the engine alive for other clients. The engine exits
after the last client leaves, including crashed clients. Configuration and logs live
outside the engine directory. The package never stops or installs system services.
`Tracker(runtime_dir="...")` selects a developer bundle explicitly.

The base engine contains seven files, about **248 MB** before compression. The release
archive adds driver files and notices: **251 MB extracted, 244 MB compressed**.
The private engine delivered 1,047 frames in ten
seconds, about 105 FPS, including 50 full hand skeletons. It ran as the normal user
while the installed service was stopped. First-frame startup took about 2.6 seconds.
The project owner confirmed redistribution permission on 5 November 2026. The
installed beta wheel also passed two-client sharing, repeated startup, crash cleanup,
and a live-frame check of the restored installed service. Clean-PC USB setup and
other-platform hardware tests remain pending.
See [the prototype, evidence, and bounded test command](docs/MINIMAL_RUNTIME.md).
The proposed first-use flow and Windows/Linux/macOS targets are documented in
[installation and platforms](docs/INSTALLATION_PLATFORMS.md).

**Read hand data.** The same API accepts live, synthetic, and replay sources:

```python
from source_robotics_leap_motion import Tracker

with Tracker() as tracker:  # use Tracker.demo() to try without a camera
    print("Backend:", tracker.backend_name)
    for frame in tracker:
        if hand := frame.right_hand:
            print(hand.palm.position, hand.grab_strength)
```

Positions, widths, and distances use **metres**; palm velocity uses metres/second.
Camera axes remain Leap's axes: +x right, +y up, +z toward the user. Quaternions have
named `x`, `y`, `z`, `w` components. Frame timestamps are microseconds in the named
`clock_domain`, not Unix time. An empty-hand frame is valid; absence of frames produces
`TrackingTimeoutError`. Service/camera disconnections produce `ConnectionError`.

Frames are immutable Python snapshots and retain no SDK pointers. LeapC includes
finger/arm rotations. The legacy backend exposes finger joint positions when supplied
by protocol v6, derives palm orientation from normal/direction, and reports unavailable
bone rotations and pinch distance as `None`. It never substitutes a made-up rotation.

**Record and replay.** Existing recordings are protected by default:

```powershell
.\.venv\Scripts\source-leap.exe record recordings\session.jsonl --frames 300
.\.venv\Scripts\source-leap.exe replay recordings\session.jsonl --realtime
.\.venv\Scripts\source-leap.exe record recordings\demo.jsonl --demo --frames 60
.\.venv\Scripts\source-leap.exe replay recordings\demo.jsonl --json
```

The destination folder is created automatically. JSON output contains only frames on stdout;
status and errors go to stderr. Each recording has a schema version, timestamp and
coordinate conventions, and one frame per line. Reading streams the file without
loading the whole session. Headerless historical `motion_data.txt` files use a different
format and are not accepted as recordings.

```python
from source_robotics_leap_motion import Recorder, Tracker, read_recording

with Tracker.demo(realtime=False) as tracker, Recorder("demo.jsonl") as recording:
    for _ in range(60):
        recording.write(tracker.read())

for frame in read_recording("demo.jsonl"):
    print(frame.timestamp_us, frame.right_hand.palm.position)
```

**Customize coordinate mapping.** The package provides a pure mapping function, with
no hard-coded robot origin or workspace:

```python
from source_robotics_leap_motion import Mapping, Vector3

mapping = Mapping(axes=("-z", "-x", "y"), gain=Vector3(0.5, 0.5, 0.5))
target = mapping.map_position(
    hand.palm.position,
    hand_origin=calibrated_hand_position,
    robot_origin=current_robot_position,
)
```

Gains apply in output coordinates. Zero locks an axis. Signed axis permutations must
preserve handedness. `Mapping.from_toml("examples/my_arm.toml")` loads the same settings.
Run `python examples/custom_mapping.py` for a complete synthetic example that only
prints targets.

This alpha supplies tracking and mapping primitives. Robot adapters, activation/clutch
states, motion limits, adaptive filtering, and continuous robot control are the next
milestone; a production `Teleoperator` is **not implemented**. There is no automatic
connection to an arm, no motor-driver dependency, and no implicit movement command.

**Diagnostics.** `doctor` inspects fixed runtime locations without loading native
code. `doctor --probe` also opens tracking and waits for a frame. Exit code 0 indicates
the requested check passed, 2 indicates a configuration/tracking error, and Ctrl+C
returns 130. A WebSocket connection can succeed while the camera is unplugged, paused,
or otherwise not streaming; a successful greeting alone is not a live-frame test.

Developers can explicitly select a LeapC library with `--library PATH` or the
`SOURCE_LEAP_LIBRARY` environment variable. An explicit selection never silently
falls back to another backend. Normal users should not need either option.

**Development and validation.**

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check src tests examples
.\.venv\Scripts\python.exe -m ruff format --check src tests examples
.\.venv\Scripts\python.exe -m build --wheel
```

The original scripts and binaries remain historical references. The original README
is preserved in [docs/LEGACY_README.md](docs/LEGACY_README.md). Current scope and design
are in [PACKAGE_DESIGN.md](PACKAGE_DESIGN.md); native-interface verification is described
in [docs/NATIVE_ABI.md](docs/NATIVE_ABI.md).
