Using the Leap Motion Application

This article describes the Leap application that acts as an intermediary
between the Leap Motion Controller and your Leap-enabled application.

Overview

The Leap application communicates with the Leap Motion Controller hardware and
transmits hand tracking data to Leap-enabled applications. Thus, the Leap
application must be running when you access Leap data in your
application.

When the Leap application is running, it displays an icon in the
notification area of the Windows Taskbar or Mac Finder bar. When the
Leap device is plugged in and working properly, the icon turns green.
The icon will flash yellow while the software is initializing and turn
red if an error has occurred.

  • Unplugged-Icon — the Leap
    device is unplugged (or the Leap application hasn’t detected it
    yet).
  • Normal-Icon — the Leap device
    and application are operating normally.
  • Robust-Icon — the Leap is
    operating in robust mode. See Operating Modes_ for more
    information.
  • Error-Icon — an error has occured
    from which the Leap application is unable to recover. Open the
    application log using the Show Log menu command for more
    information about the error.

When you first run the Leap software, it checks to see if you have
logged in with your Leap developer credentials and whether you have the
calibration file for your Leap device, which is necessary to run the
Leap. The Leap software automatically downloads the calibration file for
your device after you log in.

Menu commands

The Leap application has a number of commands that modify how tracking
data is produced and which give you information about the state of the
device. Access these commands through the menu attached to the
application icon.

The Leap application provides the following menu commands:

  • Settings… — Opens the Leap Software Settings dialog.
  • Check for Updates — checks to see if an update for the Leap software
    and SDK is available
  • Open Log — displays a log of events generated by the Leap
    application; see Application log_
  • Recalibrate Device… — launches the device calibration utility; see
    Device recalibration_
  • Visualizer… — launches the Visualizer application; see Leap
    Visualizer
  • Report a Bug… — opens the bug report dialog; see Reporting bugs_
  • About — provides the Leap application version number as well as
    links to our website and support email address

Note that some of these commands are targeted toward developers. The
consumer version of the Leap application will have a different set of
user commands and options.

Leap Software Settings

You can adjust the behavior of the Leap application using the Leap
Software Settings dialog.

On the Tracking page, you can set the operating mode (see
Operating modes_) and reverse the horizontal orientation with the Flip
Tracking
button.

On the Logging page, you can set log file options, save the current
log to a file, and set automatic bug reporting options.

On the Screen page you can register the relationship between the Leap
device and a selected monitor so that the Leap can accurately calculate
the intersection of the screen with rays projected from fingers and
tools. See Screen location_.

Operating modes

The Leap has several operating modes which determine how the application
analyzes data. The following modes are user-selectable from the Software
Settings dialog of the Leap Application:

  • Precision — prioritizes precision over speed
  • Balanced — balances precision with speed
  • High Speed — prioritizes speed over precision
  • Robust Mode — prioritizes tracking robustness over speed
  • Low Resource — reduces the USB bandwidth used by the Leap

The Leap Robust Mode improves the reliability of the tracking data in
bright lighting conditions. Robust mode allows the Leap to operate in a
wider range of environmental conditions; however, other performance
characteristics may be reduced. The main effects on performance are that
there will be increased processing latency and very fast motions by the
user will cause a loss of tracking data.

The Leap automatically drops into robust mode when lighting conditions
become poor. The Leap switches back into the last user-selected
operating mode when lighting conditions improve, but will remain in
robust mode for at least 30 seconds. The Leap application icon changes
from green to yellow when in this mode.

When the Leap enters robust mode because it detects bad lighting
conditions, it saves a diagnostic file. If the cause of the lighting
problem is not obvious, you can send this diagnostic file to Leap
Motion. This may help us improve the lighting analysis algorithms. See
Reporting bugs_ for information about diagnostic files.

Device recalibration

If the sensors on the Leap device are knocked out of their initial
alignment, the device must be recalibrated. Symptoms that may indicate
the need to recalibrate include:

  • Persistent jumpiness
  • Frequent discontinuities in the tracking data
  • Aberrations in tracking data that occur only in certain areas of
    the field of view
  • Poor tracking range

You can look for these symptoms using the the Leap
Visualizer
.

To recalibrate your Leap device:

  1. Open the Leap Application menu using the icon on the Windows Taskbar
    or Mac Finder bar.
  2. Select the Recalibrate Device command.
  3. Follow the on-screen instructions to perform the calibration
    procedure.

    Calibration

You will need a flat, reflective surface. A mirror is ideal, but many
other reflective surfaces like a flat screen monitor will work accetably
as well. During the procedure, hold the Leap so that the LEDs shine on
the reflective surface and are reflected back into the top of the
device. The calibration window displays a disk that moves as you change
the angle between the surface and the device. Rotate the Leap to move
this disc so that it “paints” the window. Moving the Leap up and down or
side to side does not adversely affect the calibration, but calibration
requires rotation.

Reporting bugs

If you are having problems with the Leap software, please contact us so
we can help you resolve the issue. You can submit reports on the ~!@Leap
Motion
@!~ Developer Portal or by using
the Bug Report form of the Leap Application.

We may ask you to reproduce the issue on your device and record some
diagnostic information which you can send to ~!@Leap
Motion
@!~ to help us assess the problem.
You can start and stop the recording of diagnostic information from the
Leap Bug Report form. The data is compressed and encrypted and is not
useful for your local application debugging. The data recorded can grow
large over time, so we do not recommend recording diagnostics for an
extended period.

To report a bug,

  1. Open the Leap Application menu using the icon on the Windows Taskbar
    or Mac Finder bar.
  2. Select the Report Bug command.
  3. On the Bug Report form, select the reason that best fits your bug
    from the Reason drop-down list.
  4. Add any important details, such as how to reproduce your bug in the
    Details section.
  5. For some types of bugs, you will be asked to record diagnostic
    information.
  6. When finished, click the Send button. Your bug information and
    recorded diagnostics will be sent to Leap Motion.

If you are asked to record diagnostic information,

  1. Press the Record button.
  2. Reproduce the problem (it may help to have the Leap
    Visualizer
    running).
  3. Press the Stop button after a short period of time.
  4. Click Send to upload the diagnostic file to ~!@Leap
    Motion
    @!~ for analysis.

Automatic bug reporting

The Leap application provides the option to automatically send
diagnostic information to Leap Motion when certain types of errors are
encountered by the Leap. This option defaults to off, but we encourage
you to turn it on to help us improve the Leap software.

To turn on automatic bug reporting,

  1. Open the Leap Application menu using the icon on the Windows Taskbar
    or Mac Finder bar.
  2. Select the Settings… command.
  3. On the Leap Settings window, click the Logging tab.
  4. Check the Auto-Send Bug Reports option.
  5. Click OK.

Application log

To view events related to the Leap application, open the application log
using the Leap application menu from the Windows Taskbar or Mac Finder
bar. If you are having problems, we may ask you to save the log and send
it to Leap Motion to help us assess
the problem. You can save the log from the Logging page of the
Settings dialog.

Screen location

Screen Location is only needed to use the Screen class in the Leap
API. All other features of the Leap work without running the Screen
Locator tool.

You can use the Screen Locator tool to register the position and
orientation of a monitor in relation to the Leap device.

Establishing the location of a screen is not required for most features
of the Leap to work correctly. However, when a monitor’s position is
known, a Leap-enabled application can access additional information.
This information includes the coordinates and orientation of the screen
within the Leap coordinate system as well as the intersection points
between the screen and rays projected from fingers and tools.

The Screen Location tool must be run whenever the Leap or the monitor
are moved.

To register the location of a screen:

  1. Place the Leap device in the desired position relative to the
    monitor.
  2. Launch the Leap application and open the Settings window using the
    Leap application menu.
  3. Click the Screen tab on the Settings window.
  4. Select the monitor to locate from the detected screens list (if more
    than one monitor is attached to your computer).
  5. Click the Locate Screen button.
  6. The Leap application opens a full screen window on the selected
    monitor and provides instructions on how to complete the process.

    During the procedure, the Leap displays a sequence of circles. Place
    a tool or finger into the Leap field of view and point at each
    displayed circle in turn. The circle will change color when you are
    pointing close enough to the circle. The more accurately you point,
    the more accurate the results. It may help to sight along the tool
    or finger while pointing.

  7. Click the OK or Apply button when finished.

You can view the location results in the Leap
Visualizer
. (Press the B key while in the
Visualizer to display the computed screen bounds and finger-screen
intersection points.)

See Screen Location for information on using
screen location information in a Leap-enabled application.


Copyright © 2012-2013 Leap Motion, Inc. All rights reserved.

Leap Motion proprietary and confidential. Not for distribution. Use
subject to the terms of the Leap Motion SDK Agreement available at
https://developer.leapmotion.com/sdk_agreement, or another agreement
between Leap Motion and you, your company or other organization.