ControllerΒΆ

Properties:

Methods:

class Leap::Controller

The Controller class is your main interface to the Leap Motion Controller.

Create an instance of this Controller class to access frames of tracking data and configuration information. Frame data can be polled at any time using the Controller::frame() function. Call frame() or frame(0) to get the most recent frame. Set the history parameter to a positive integer to access previous frames. A controller stores up to 60 frames in its frame history.

Polling is an appropriate strategy for applications which already have an intrinsic update loop, such as a game. You can also subscribe to the FrameReady event to get tracking frames through an event delegate.

If the current thread implements a SynchronizationContext that contains a message loop, events are posted to that threads message loop. Otherwise, events are called on an independent thread and applications must perform any needed synchronization or marshalling of data between threads. Note that Unity3D does not create an appropriate SynchronizationContext object. Typically, event handlers cannot access any Unity objects.

Since
1.0

Public Type

PolicyFlag enum

The supported controller policies.

The supported policy flags are:

POLICY_BACKGROUND_FRAMES requests that your application receives frames when it is not the foreground application for user input.

The background frames policy determines whether an application receives frames of tracking data while in the background. By default, the Leap Motion software only sends tracking data to the foreground application. Only applications that need this ability should request the background frames policy. The “Allow Background Apps” checkbox must be enabled in the Leap Motion Control Panel or this policy will be denied.

POLICY_OPTIMIZE_HMD request that the tracking be optimized for head-mounted tracking.

The optimize HMD policy improves tracking in situations where the Leap Motion hardware is attached to a head-mounted display. This policy is not granted for devices that cannot be mounted to an HMD, such as Leap Motion controllers embedded in a laptop or keyboard.

Some policies can be denied if the user has disabled the feature on their Leap Motion control panel.

Since
1.0

Values:

  • POLICY_DEFAULT = = 0 -

    The default policy.

    Since

    1.0

  • POLICY_BACKGROUND_FRAMES = = (1 << 0) -

    Receive background frames.

    Since

    1.0

  • POLICY_OPTIMIZE_HMD = = (1 << 2) -

    Optimize the tracking for head-mounted device.

    Since

    2.1.2

  • POLICY_ALLOW_PAUSE_RESUME = = (1 << 3) -

    Allow pausing and unpausing of the Leap Motion service.

    Since

    3.0

Public Functions

void ClearPolicy(Controller.PolicyFlag policy)

Requests clearing a policy.

Policy changes are completed asynchronously and, because they are subject to user approval or system compatibility checks, may not complete successfully. Call Controller::isPolicySet() after a suitable interval to test whether the change was accepted.

controller.ClearPolicy (Controller.PolicyFlag.POLICY_OPTIMIZE_HMD);

Since
2.1.6
Parameters
  • flags -

    A PolicyFlag value indicating the policy to request.

Controller()

Constructs a Controller object.

The default constructor uses a connection key of 0.

Since
1.0

Controller(int connectionKey)

Constructs a Controller object using the specified connection key.

All controller instances using the same key will use the same connection to the serivce. In general, an application should not use more than one connection for all its controllers. Each connection keeps its own cache of frames and images.

Since
3.0
Parameters
  • connectionKey -

    An identifier specifying the connection to use. If a connection with the specified key already exists, that connection is used. Otherwise, a new connection is created.

FailedDeviceList FailedDevices()

A list of any Leap Motion hardware devices that are physically connected to the client computer, but are not functioning correctly.

The list contains FailedDevice objects containing the pnpID and the reason for failure. No other device information is available.

FailedDeviceList badDevices = controller.FailedDevices();

Since
3.0

Frame Frame(int history)

Returns a frame of tracking data from the Leap Motion software.

Use the optional history parameter to specify which frame to retrieve. Call frame() or frame(0) to access the most recent frame; call frame(1) to access the previous frame, and so on. If you use a history value greater than the number of stored frames, then the controller returns an empty frame.

if (controller.IsConnected) { //controller is a Controller object
    Frame frame = controller.Frame (); //The latest frame
    Frame previous = controller.Frame (1); //The previous frame
}

Return
The specified frame; or, if no history parameter is specified, the newest frame. If a frame is not available at the specified history position, an invalid Frame is returned.
Since
1.0
Parameters
  • history -

    The age of the frame to return, counting backwards from the most recent frame (0) into the past and up to the maximum age (59).

void Frame(Frame toFill, int history)

Identical to Frame(history) but instead of constructing a new frame and returning it, the user provides a frame object to be filled with data instead.

Parameters
  • toFill -

    The frame object to fill with tracking data.

  • history -

    The age of the frame to return.

Frame Frame()

Returns the most recent frame of tracking data.

Since
1.0

void Frame(Frame toFill)

Fills a frame object with the most recent tracking data.

Parameters
  • toFill -

    The frame object to fill with tracking data.

long FrameTimestamp(int history = 0)

Returns the timestamp of a recent tracking frame.

Use the optional history parameter to specify how many frames in the past to retrieve the timestamp. Leave the history parameter as it’s default value to return the timestamp of the most recent tracked frame.

Parameters
  • history -

    the age of the timestamp to return,

Frame GetInterpolatedFrame(Int64 time)

Returns the Frame at the specified time, interpolating the data between existing frames, if necessary.

void GetInterpolatedLeftRightTransform(Int64 time, Int64 sourceTime, int leftId, int rightId, out LeapTransform leftTransform, out LeapTransform rightTransform)

This is a special variant of GetInterpolatedFrameFromTime, for use with special features that only require the position and orientation of the palm positions, and do not care about pose data or any other data.

You must specify the id of the hand that you wish to get a transform for. If you specify an id that is not present in the interpolated frame, the output transform will be the identity transform.

Frame GetTransformedFrame(LeapTransform trs, int history = 0)

Returns the frame object with all hands transformed by the specified transform matrix.

Parameters
  • trs -

    a LeapTransform containing translation, rotation, and scale.

  • history -

    The age of the frame to return, counting backwards from the most recent frame (0) into the past and up to the maximum age (59).

bool IsPolicySet(Controller.PolicyFlag policy)

Gets the active setting for a specific policy.

Keep in mind that setting a policy flag is asynchronous, so changes are not effective immediately after calling setPolicyFlag(). In addition, a policy request can be declined by the user. You should always set the policy flags required by your application at startup and check that the policy change request was successful after an appropriate interval.

If the controller object is not connected to the Leap Motion software, then the default state for the selected policy is returned.

bool isImagePolicySet = controller.IsPolicySet (Controller.PolicyFlag.POLICY_BACKGROUND_FRAMES);

Return
A boolean indicating whether the specified policy has been set.
Since
2.1.6
Parameters
  • flags -

    A PolicyFlag value indicating the policy to query.

long Now()

Returns a timestamp value as close as possible to the current time.

Values are in microseconds, as with all the other timestamp values.

Since
2.2.7

Image RequestImages(Int64 frameId, Image.ImageType type)

Requests an image pair from the service.

Image data is stacked in a single byte array, with the left camera image first, followed by the right camera image. Two types of image are supported. ImageType.TYPE_DEFAULT is the normal, IR format image. ImageType.RAW is the unmodified, raw sensor pixels. The format of this image type depends on the device. For the publically available Leap Motion devices, the raw image type is also IR and is identical to the default image type except when in robust mode. In robust mode, the default image type is processed to subtract the unilluminated background; the raw image is not.

Images are not sent automatically. You must request each image. This function returns an Image object. However, that object does not contain image data until its IsComplete property becomes true.

Image requests will fail if the request is made after the image has been disposed by the service. The service only keeps images for a few frames, so applications that use images must make the image request as soon as possible after a tracking frame is received.

The controller dispatches an ImageReady event when a requested image is recevied from the service and is ready for use. The controller dispatches an ImageRequestFailed event if the request does not succeed.

Image requests can fail for the following reasons:

In addition, if the returned image is invalid, then the request call itself failed. Typically this will occur when the connection itself is not running. Such errors are reported in a LogEvent event.

Return
An incomplete Image object that will contain the image data when the request is fulfilled. If the request call itself fails, an invalid image is returned.
Since
3.0
Parameters
  • frameId -

    The Id value of the tracking frame.

  • type -

    The type of image desired. A member of the Image.ImageType enumeration.

Image RequestImages(Int64 frameId, Image.ImageType type, byte[] imageBuffer)

Requests an image from the service.

The pixels of the image are written to the specified byte array.

If the specified byte array is too small, an ImageRequestFailed event is dispatched. The arguments of this event include the required buffer size. For the publically available Leap device, the buffer size must be: width * height * bytes-per-pixel * #cameras, i.e: 640 * 240 * 1 * 2 = 307,200 bytes.

The Image object returned by this function contains a reference to the supplied buffer. When the service sets the IsComplete property to true when the buffer is filled in. An ImageReady event is also dispatched.

Return
An incomplete Image object that will contain the image data when the request is fulfilled. If the request call itself fails, an invalid image is returned.
Since
3.0
Parameters
  • frameId -

    The Id value of the tracking frame.

  • type -

    The type of image desired. A member of the Image.ImageType enumeration.

  • imageBuffer -

    A byte array large enough to hold the requested image pair.

void SetPolicy(Controller.PolicyFlag policy)

Requests setting a policy.

A request to change a policy is subject to user approval and a policy can be changed by the user at any time (using the Leap Motion settings dialog). The desired policy flags must be set every time an application runs.

Policy changes are completed asynchronously and, because they are subject to user approval or system compatibility checks, may not complete successfully. Call Controller::isPolicySet() after a suitable interval to test whether the change was accepted.

controller.SetPolicy (Controller.PolicyFlag.POLICY_BACKGROUND_FRAMES);
controller.SetPolicy (Controller.PolicyFlag.POLICY_OPTIMIZE_HMD);

Since
2.1.6
Parameters
  • policy -

    A PolicyFlag value indicating the policy to request.

void StartConnection()

Starts the connection.

A connection starts automatically when created, but you can use this function to restart the connection after stopping it.

Since
3.0

void StopConnection()

Stops the connection.

No more frames or other events are received from a stopped connection. You can restart with StartConnection().

Since
3.0

Property

Config Config

Returns a Config object, which you can use to query the Leap Motion system for configuration information.

Return
The Controller‘s Config object.
Since
1.0

EventHandler< ConfigChangeEventArgs > ConfigChange

Dispatched when a configuration seting changes.

Since
3.0

EventHandler< ConnectionEventArgs > Connect

Dispatched when the connection to the service is established.

Since
3.0

EventHandler< DeviceEventArgs > Device

Dispatched when a Leap Motion device is connected.

Since
3.0

EventHandler< DeviceFailureEventArgs > DeviceFailure

Dispatched when a Leap device fails to initialize.

Since
3.0

EventHandler< DeviceEventArgs > DeviceLost

Dispatched when when a Leap Motion device is disconnected.

Since
3.0

DeviceList Devices

The list of currently attached and recognized Leap Motion controller devices.

The Device objects in the list describe information such as the range and tracking volume.

DeviceList connectedLeaps = controller.Devices;

Currently, the Leap Motion Controller only allows a single active device at a time, however there may be multiple devices physically attached and listed here. Any active device(s) are guaranteed to be listed first, however order is not determined beyond that.

Return
The list of Leap Motion controllers.
Since
1.0

EventHandler< ConnectionLostEventArgs > Disconnect

Dispatched if the connection to the service is lost.

Since
3.0

EventHandler< DistortionEventArgs > DistortionChange

Dispatched when the image distortion map changes.

The distortion map can change when the Leap device switches orientation, or a new device becomes active.

Since
3.0

SynchronizationContext EventContext

The SynchronizationContext used for dispatching events.

By default the synchronization context of the thread creating the controller instance is used. You can change the context if desired.

EventHandler< FrameEventArgs > FrameReady

Dispatched when a tracking frame is ready.

Since
3.0

EventHandler< ImageEventArgs > ImageReady

Dispatched when an image is ready.

Call Controller.RequestImage() to request that an image be sent to your application.

Since
3.0

EventHandler< ImageRequestFailedEventArgs > ImageRequestFailed

Dispatched when a requested image cannot be sent.

Since
3.0

EventHandler< LeapEventArgs > Init

Dispatched when the connection is initialized (but not necessarily connected).

Can be dispatched more than once, if connection is restarted.

Since
3.0

EventHandler< InternalFrameEventArgs > InternalFrameReady

Dispatched when an internal tracking frame is ready.

Since
3.0

bool IsConnected

Reports whether this Controller is connected to the Leap Motion service and the Leap Motion hardware is plugged in.

When you first create a Controller object, isConnected() returns false. After the controller finishes initializing and connects to the Leap Motion software and if the Leap Motion hardware is plugged in, isConnected() returns true.

You can either handle the onConnect event using a Listener instance or poll the isConnected() function if you need to wait for your application to be connected to the Leap Motion software before performing some other operation.

if (controller.IsConnected) {
    //perform action that requires a connected controller
}
Return
True, if connected; false otherwise.
Since
1.0

bool IsServiceConnected

Reports whether your application has a connection to the Leap Motion daemon/service.

Can be true even if the Leap Motion hardware is not available.

Since
1.2

EventHandler< LogEventArgs > LogMessage

Dispatched when the system generates a loggable event.

Since
3.0

EventHandler< PolicyEventArgs > PolicyChange

Dispatched when a policy changes.

Since
3.0