Expand description
§LeapRS
LeapRS is a 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.
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.
§Installation
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).
§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.
§Runtime
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
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()),
_ => {}
}
}
}§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();
}
},
_ => {}
}
}
}§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§
- Describes a bone’s position and orientation.
- Flags enumerating Leap device capabilities. @since 3.0.0
- \ingroup Structs \struct LEAP_CLOCK_REBASER An opaque clock rebase state structure. @since 3.1.2
- 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
- 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
- A handle to the Leap connection object. Use this handle to specify the connection for an operation. @since 3.0.0
- Specifies the configuration for a connection. @since 3.0.0
- \ingroup Structs Received from LeapPollConnection() when a connection to the Ultraleap Tracking Service is established. @since 3.0.0
- \ingroup Structs Information about a connection.
- Received from LeapPollConnection() when a connection to the Ultraleap Tracking Service is lost.
- Defines a basic message from the LeapC message queue. Set by calling LeapPollConnection(). @since 3.0.0
- A handle to a Leap device object. Use this handle to specify the device for an operation. @since 3.0.0
- Device event information.
- 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
- 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
- A reference to a Leap device.
- Enumerates the device status codes. @since 3.0.0
- 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
- Describes the digit of a hand. Digits are members of the LEAP_HAND struct. @since 3.0.0
- A matrix containing lens distortion correction coordinates.
- Identifying information for a frame of tracking data. @since 3.0.0
- Describes a tracked hand. @since 3.0.0
- Streaming stereo image pairs from the device.
- Properties of a sensor image.
- An image associated with a frame of data. @since 4.0.0
- A three element, floating-point vector. @since 3.0.0
- A system log message. @since 3.0.0
- 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
- A point in the distortion grid. @since 3.0.0
- The response from a request to get or set a policy. LeapPollConnection() creates this struct when the response becomes available. @since 3.0.0
- Enumerates flags for the service policies.
- A four element, floating point quaternion. @since 3.1.2
- 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
- The response from a request to get or set a policy. LeapPollConnection() creates this struct when the response becomes available. @since 3.0.0
Enums§
- 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
- Device hardware types. @since 3.0.0
- Defines the codes returned by all LeapC functions.
- The types of event messages resulting from calling LeapPollConnection().
- The Hand chirality types. Used in the LEAP_HAND struct. @since 3.0.0
- Image formats. @since 3.0.0
- Functional image types (not data formats).
- System message severity types. @since 3.0.0
- Camera perspective types. @since 3.0.0
- Enumerates values for the tracking mode.
- A variant data type used to get and set service configuration values. @since 3.0.0
- Defines the parameters used to access version information. @since 5.2.x