Crate leaprs

Expand description

§LeapRS

Crates.io

LeapRS is an unofficial safe wrapper for LeapC, the Leap Motion C API. It uses the generated binding provided by leap-sys.

This is an API for accessing Leap Motion/Ultraleap hand tracking device. It works on Linux and Windows.

leaprs

Warning: This library is not complete and not fully tested. Moreover, it includes unsafe code to interact with the C API. It should be treated with caution in its current state.

§Scope

The goal of LeapRS is to cover entirely LeapC in a safe way. It is intended to be as close as possible to the original C library. As such, it’s fairly low level and carries most of the difficulties of using LeapC.

It is not intended to provide any full featured framework such as having a worker thread and provide an async API. It is intended to be usable to create such framework though.

§API Coverage

The current coverage includes most of the necessary functions to interact with a Leap Motion device in a single or a multi device environment. The interpolation and distortion methods are not fully translated and not fully tested.

The allocation API is not exposed.

§Setup

Add leaprs to the current project: cargo add leaprs

You also need to install the LeapMotion Tracking Software.

This library was created for the version named Geminy (5.6.1).

If you install this software in a custom path, you need to define the environment variable LEAPSDK_LIB_PATH (default: C:\Program Files\Ultraleap\LeapSDK\lib\x64 on Windows and /usr/share/doc/ultraleap-hand-tracking-service on Linux).

At runtime, the application requires the LeapC.dll file to be available. The easiest way to do it during development is to add its folder to the PATH environment variable. For distribution, refer to the SDK licensing.

§Quick start

The main entrypoint is Connection::create. For most of the basic usage of hand tracking, you will have to use Connection::poll and retrieve the underlying event with ConnectionMessage::event. The various possible events are described in the EventRef enum, including EventRef::Tracking containing the hand positions.

use leaprs::*;

let mut c = Connection::create(ConnectionConfig::default()).unwrap();
c.open().unwrap();
for _ in 0..10 {
    if let Ok(msg) = c.poll(1000) {
        match msg.event() {
            EventRef::Tracking(e) => println!("{} hand(s)", e.hands().len()),
            _ => {}   
        }
    }
}

Most of the types in leaprs are wrappers with no data around the underlying LeapC structures. These wrappers expose both:

Handy methods for accessing the data, for example TrackingEventRef::hands lists the visible hands
Direct access to the underlying data via the Deref trait, for example HandRef gives direct access to leap_sys::LEAP_HAND::confidence: hand_ref.confidence

When both members are available (.hands and .hands()), the function is the recommended one to get a safe wrapper. The field access can be useful to circumvent a leaprs limitation.

§`glam` and `nalgebra` Integration

leaprs includes opt-in glam and nalgebra integrations.

They are two popular linear algebra library. Both are commonly used, and these features can help integrating with ecosystem using these crates. glam is used by Bevy, and nalgebra is used by Fyrox.

§glam

cargo build --features glam

use leaprs::*;
use glam::{Vec3, Quat};

let mut c = Connection::create(ConnectionConfig::default()).unwrap();
c.open().unwrap();
for _ in 0..10 {
    if let Ok(msg) = c.poll(1000) {
        match msg.event() {
            EventRef::Tracking(e) => {
                for hand in e.hands() {
                    let position: Vec3 = hand.palm().position().into();
                    let orientation: Quat = hand.palm().orientation().into();
                }
            },
            _ => {}
        }
    }
}

§nalgebra

cargo build --features nalgebra

use leaprs::*;
use nalgebra::{Vector3, UnitQuaternion};

let mut c = Connection::create(ConnectionConfig::default()).unwrap();
c.open().unwrap();
for _ in 0..10 {
    if let Ok(msg) = c.poll(1000) {
        match msg.event() {
            EventRef::Tracking(e) => {
                for hand in e.hands() {
                    let position: Vector3<f32> = hand.palm().position().into();
                    let orientation: UnitQuaternion<f32> = hand.palm().orientation().into();
                }
            },
            _ => {}
        }
    }
}

§Using with previous SDK versions

Disabling the geminy feature enables building application for the previous SDK generation (Orion). In Cargo.toml:

[dependencies = { version = "*", default-features = false }]

You also need to point the LEAPSDK_LIB_PATH to a SDK with the Orion version.

§License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

This license only covers the leaprs wrapper, and not the underlying LeapC library.

§Implementation

The enum safety is provided through num_enum.

The bitflags are wrapped using bitflags.

Most struct are simple wrappers around their C counter-part. Most of the time, the C struct is the only member of the wrapper, except when external allocation is needed (when providing a pre-allocated array to LeapC). Accessors are then exposing all the functions and members associated with these structs in a consistent way.

§Tests

The test require to have the Leap software up and running, and to have a device connected.

Structs§

BoneRef: Describes a bone’s position and orientation.
Capabilities: Flags enumerating Leap device capabilities. @since 3.0.0
ClockRebaser: \ingroup Structs \struct LEAP_CLOCK_REBASER An opaque clock rebase state structure. @since 3.1.2
ConfigChangeEventRef: The result of a configuration change request. Contains a status of true for a successful change. Call LeapSaveConfigValue() to request a service config change. The change is performed asynchronously – and may fail. LeapPollConnection() returns this event structure when the request has been processed. Use the requestID value to correlate the response to the originating request. @returns The operation result code, a member of the eLeapRS enumeration. @since 3.0.0
ConfigResponseEventRef: Contains the response to a configuration value request. Call LeapRequestConfigValue() to request a service config value. The value is fetched asynchronously since it requires a service transaction. LeapPollConnection() returns this event structure when the request has been processed. Use the requestID value to correlate the response to the originating request. @since 3.0.0
Connection: A handle to the Leap connection object. Use this handle to specify the connection for an operation. @since 3.0.0
ConnectionConfig: Specifies the configuration for a connection. @since 3.0.0
ConnectionConfigFlags
ConnectionEventRef: \ingroup Structs Received from LeapPollConnection() when a connection to the Ultraleap Tracking Service is established. @since 3.0.0
ConnectionInfo: \ingroup Structs Information about a connection.
ConnectionLostEventRef: Received from LeapPollConnection() when a connection to the Ultraleap Tracking Service is lost.
ConnectionMessage: Defines a basic message from the LeapC message queue. Set by calling LeapPollConnection(). @since 3.0.0
Device: A handle to a Leap device object. Use this handle to specify the device for an operation. @since 3.0.0
DeviceEventRef: Device event information.
DeviceFailureEventRef: Device failure information. LeapPollConnection() produces a message containing this event when a device fails. Only partial information may be available. If hDevice is non-null, then you can use it to identify the failed device with a known, open device. @since 3.0.0
DeviceInfo: Properties of a Leap device. Get a LEAP_DEVICE_INFO by calling LeapGetDeviceInfo() with the handle for device. The device must be open. @since 3.0.0
DeviceRef: A reference to a Leap device.
DeviceStatus: Enumerates the device status codes. @since 3.0.0
DeviceStatusChangeEventRef: A notification that a device’s status has changed. One of these messages is received by the client as soon as the service is connected, or when a new device is attached. @since 3.1.3
DigitRef: Describes the digit of a hand. Digits are members of the LEAP_HAND struct. @since 3.0.0
DistortionMatrixRef: A matrix containing lens distortion correction coordinates.
DroppedFrameEventRef: Fields
EyeEventRef: Fields
FrameHeaderRef: Identifying information for a frame of tracking data. @since 3.0.0
HandRef: Describes a tracked hand. @since 3.0.0
HeadPoseEventRef: Fields
ImageEventRef: Streaming stereo image pairs from the device.
ImagePropertiesRef: Properties of a sensor image.
ImageRef: An image associated with a frame of data. @since 4.0.0
ImuEventRef: Fields
ImuFlag
InterpolationTrackingEvent: Fields
LeapVectorRef: A three element, floating-point vector. @since 3.0.0
LogEventRef: A system log message. @since 3.0.0
LogEventsRef: A notification that a device’s status has changed. One of these messages is received by the client as soon as the service is connected, or when a new device is attached. @since 3.1.3
PalmRef: Fields
Point: A point in the distortion grid. @since 3.0.0
PointMapping: Fields
PointMappingChangeEventRef: Fields
PolicyEventRef: The response from a request to get or set a policy. LeapPollConnection() creates this struct when the response becomes available. @since 3.0.0
PolicyFlags: Enumerates flags for the service policies.
QuaternionRef: A four element, floating point quaternion. @since 3.1.2
ServiceState
TrackingEventRef: A snapshot, or frame of data, containing the tracking data for a single moment in time. The LEAP_FRAME struct is the container for all the tracking data. @since 3.0.0
TrackingModeEventRef: The response from a request to get or set a policy. LeapPollConnection() creates this struct when the response becomes available. @since 3.0.0
Version: Fields

Enums§

ConnectionStatus: The connection status codes. These codes can be read from the LEAP_CONNECTION_INFO struct created by a call to LeapGetConnectionInfo(). @since 3.0.0
DevicePID: Device hardware types. @since 3.0.0
DroppedFrameType
Error: Defines the codes returned by all LeapC functions.
EventRef: The types of event messages resulting from calling LeapPollConnection().
HandType: The Hand chirality types. Used in the LEAP_HAND struct. @since 3.0.0
ImageFormat: Image formats. @since 3.0.0
ImageType: Functional image types (not data formats).
LogSeverity: System message severity types. @since 3.0.0
PerspectiveType: Camera perspective types. @since 3.0.0
TrackingMode: Enumerates values for the tracking mode.
Variant: A variant data type used to get and set service configuration values. @since 3.0.0
VersionPart: Defines the parameters used to access version information. @since 5.2.x

Functions§

leap_get_now

Type Aliases§

LeapVectorFields
QuaternionFields

Crate leaprsCopy item path