Controller

Attributes:

Methods:

Constants:

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 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 add an instance of a subclass of Listener to the controller to handle events as they occur. The Controller dispatches events to the listener upon initialization and exiting, on connection changes, when the application gains and loses the OS input focus, and when a new frame of tracking data is available. When these events occur, the controller object invokes the appropriate callback function defined in your subclass of Listener.

To access frames of tracking data as they become available:

  1. Implement a subclass of the Listener class and override the Listener.on_frame() function.
  2. In your Listener on_frame() function, call the frame() function to access the newest frame of tracking data.
  3. To start receiving frames, create a Controller object and add an instance of the Listener subclass to the add_listener() function.

When an instance of a Listener subclass is added to a Controller object, it calls the Listener.on_init() function when the listener is ready for use. When a connection is established between the controller and the Leap Motion software, the controller calls the Listener.on_connect() function. At this point, your application will start receiving frames of data. The controller calls the Listener.on_frame() function each time a new frame is available. If the controller loses its connection with the Leap Motion software or device for any reason, it calls the Listener.on_disconnect() function. If the listener is removed from the controller or the controller is destroyed, it calls the Listener.on_exit() function. At that point, unless the listener is added to another controller, it will no longer receive frames of tracking data.

The Controller object is multithreaded and calls the Listener functions on its own thread, not on an application thread.

New in version 1.0.

classmethod Controller([listener])

Constructs a Controller object.

controller = Leap.Controller()

When creating a Controller object, you may optionally pass in a reference to an instance of a subclass of Listener. Alternatively, you may add a listener later using the add_listener() function.

listener = FrameListener()
controller = Leap.Controller(listener)
Parameters:listener (Listener) – An optional instance of Listener implementing the callback functions for the Leap Motion events you want to handle in your application.

New in version 1.0.

config
Type:Config

Set configuration values for the Leap Motion service/daemon. Currently, all available config parameters apply to the gesture recognition feature.

config = controller.config
radius = config.get("Gesture.Circle.MinRadius")
config.set("Gesture.Circle.MinRadius", radius * 2)

New in version 1.0.

devices
Type:DeviceList

The list of all plugged in Leap Motion controller devices.

device_list = controller.devices

Currently, only one device can be connected at a time.

New in version 1.0.

failed_devices
Type:FailedDeviceList

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.

New in version 2.3.2.

has_focus
Type:boolean

Reports whether this application is the focused, foreground application.

if controller.has_focus:
    print "Focused"

By default, your application only receives tracking information from the Leap Motion controller when it has the operating system input focus. To receive tracking data when your application is in the background, the background frames policy flag must be set.

New in version 1.0.

images
Type:

ImageList

The most recent set of images.

Images direct from the controller will be more recent than images retrieved from the Frame object. However, they do not match the tracking data reported for the current frame. Use images from the controller for the lowest latency image display. Use images from the frame when you are combining graphics generated from the tracking data with the visuals.

image_list = controller.images
left_image = image_list[0]
right_image = image_list[1]

New in version 2.2.1.

is_connected
Type:boolean

Reports whether this Controller is connected to the Leap Motion service and device.

When you first create a Controller object, is_connected is False. After the controller finishes initializing and connects to the Leap Motion software and hardware, is_connected becomes True.

if controller.is_connected:
    print "Leap Motion connected."

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

New in version 1.0.

is_paused
Type:boolean

Reports whether the Leap Motion service is currently paused.

New in version 2.3.2.

is_policy_set
Type:boolean

Reports whether a policy is in effect policies.

Use set_policy() to change policies.

if controller.is_policy_set(Leap.Controller.POLICY_BACKGROUND_FRAMES):
    print "Background frames policy in effect"
if controller.is_policy_set(Leap.Controller.POLICY_IMAGES):
    print "Image policy in effect"
if controller.is_policy_set(Leap.Controller.POLICY_OPTIMIZE_HMD):
    print "Optimize for HMD policy in effect"

New in version 2.1.6.

is_service_connected
Type:boolean

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.

New in version 1.2.

frame([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 invalid frame.

if(controller.is_connected): #controller is a Leap.Controller object
    frame = controller.frame() #The latest frame
    previous = controller.frame(1) #The previous frame
Parameters:history (integer) – 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).
Returns:Frame – 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.

New in version 1.0.

add_listener(listener)

Adds a listener to this Controller.

listener = FrameListener()
controller.add_listener(listener)

The Controller dispatches Leap Motion events to each associated listener. The order in which listener callback functions are invoked is arbitrary. If you pass a listener to the Controller’s constructor function, it is automatically added to the list and can be removed with the remove_listener() function.

Parameters:listener (Listener) – A subclass of Listener implementing the callback functions for the Leap Motion events you want to handle in your application.
Returns:bool indicating whether or not the listener was successfully added to the list of listeners.

New in version 1.0.

enable_gesture(type, enable)

Enables or disables reporting of a specified gesture type.

By default, all gesture types are disabled. When disabled, gestures of the disabled type are never reported and will not appear in the frame gesture list.

As a performance optimization, only enable recognition for the types of movements that you use in your application.

Parameters:
  • type
  • enable – True, to enable the specified gesture type; false, to disable.

New in version 1.0.

is_gesture_enabled(type)

Reports whether the specified gesture type is enabled.

Parameters:type (int) –

A Gesture type, one of:

Returns:boolean True if the gesture type is enabled; false, otherwise.

New in version 1.0.

now()

The current timestamp in microseconds.

You can use this value to establish a relative baseline for calculating the duration between now and a future timestamp.

Returns:long the timestamp of the moment.

New in version 2.2.7.

remove_listener(listener)

Remove a listener from the list of listeners that will receive Leap Motion events. A listener must be removed if its lifetime is shorter than the controller to which it is listening.

controller.remove_listener(listener)
Parameters:listener (Listener) – The listener to remove.
Returns:boolean indicating whether or not the listener was successfully removed from the list of listeners.

New in version 1.0.

request_diagnostic()

Requests that the service run a diagnostic check on all active devices.

The controller provides the results of the diagnostic check asynchronously by calling the Listener.on_diagnostic_event() callback. You must implement a Listener subclass with this callback to receive the diagnostic results. A diagnostic check can take several seconds to complete.

The diagnostic checks test the device (firmware, USB interfaces, bandwidth, and noise), environment (IR lighting conditions and sensor window cleanliness), and calibration. These checks are the same tests that can be run from the Leap Motion Control Panel application.

New in version 2.3.2.

set_paused(pause)

Pauses or resumes the Leap Motion service.

When the service is paused no applications receive tracking data and the service itself uses minimal CPU time.

Before changing the state of the service, you must set the POLICY_ALLOW_PAUSE_RESUME using the set_policy() function. Policies must be set every time the application is run.

Parameters:pause (True, to pause the service; false, to resume.) –

New in version 2.3.2.

set_policy(flag)

Requests a change in policy.

A request to enable 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, may not complete successfully. Examine the policy_flags attribute after a suitable interval to test whether the change was accepted.

  • POLICY_ALLOW_PAUSE_RESUME – requests that your application be allowed to pause and unpause the Leap Motion service.

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

    Note that your application does not receive frames if another Leap-enabled application is in the foreground, even when the background frames policy is in effect. The policy only matters when a non-Leap-enabled app has the operating system input focus.

  • POLICY_IMAGES – request that your application receives images from the device cameras. The “Allow Images” checkbox must be enabled in the Leap Motion Control Panel or this policy will be denied.

    The images policy determines whether an application recieves image data from the Leap Motion sensors which each frame of data. By default, this data is not sent. Only applications that use the image data should request this policy.

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

controller.set_policy(Leap.Controller.POLICY_BACKGROUND_FRAMES)
controller.set_policy(Leap.Controller.POLICY_IMAGES)
controller.set_policy(Leap.Controller.POLICY_OPTIMIZE_HMD)
Parameters:flags (integer) –

A policy flag value indicating the policies to request:

New in version 2.1.6.

clear_policy(flag)

Clears a policy.

Policy changes are completed asynchronously. Examine the policy_flags attribute after a suitable interval to test whether the change has completed.

controller.clear_policy(Leap.Controller.POLICY_BACKGROUND_FRAMES)
controller.clear_policy(Leap.Controller.POLICY_IMAGES)
controller.clear_policy(Leap.Controller.POLICY_OPTIMIZE_HMD)
Parameters:flags (integer) –

A policy flag value indicating the policies to request:

New in version 2.1.6.

POLICY_ALLOW_PAUSE_RESUME

Request that the application be allowed to pause and unpause the Leap Motion service.

New in version 2.3.2.

POLICY_BACKGROUND_FRAMES

Your application will receive tracking data when no other Leap-enabled applications have the operating system focus.

controller.set_policy(Leap.Controller.POLICY_BACKGROUND_FRAMES)

New in version 1.0.

POLICY_IMAGES

Your application will receive image data from the Leap Motion sensors with each frame.

New in version 2.1.0.

POLICY_OPTIMIZE_HMD

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.

New in version 2.1.2.