source-robotics-leap-motion 0.1.0b1

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:

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 and publication steps. 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:

.\.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:

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 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.

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:

.\.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:

.\.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. The proposed first-use flow and Windows/Linux/macOS targets are documented in installation and platforms.

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

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:

.\.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.

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:

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.

.\.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. Current scope and design are in PACKAGE_DESIGN.md; native-interface verification is described in docs/NATIVE_ABI.md.