Leap Motion Architecture

The Leap Motion supports most popular desktop operating systems. The Leap Motion software runs as a service (on Windows) or daemon (on Mac and Linux). The software connects to the Leap Motion Controller device over the USB bus. Leap-enabled applications access the Leap Motion service to receive motion tracking data. The Leap Motion SDK provides two varieties of API for getting the Leap Motion data. These APIs enable you to create Leap-enabled applications in several programming languages including JavaScript running in a browser environment.

Note: The Leap Motion service/daemon communicates with applications using the TCP port: 127.0.0.1:5905. This address and port must not be blocked by a firewall or other program.

Topics:

Application Programming Interfaces

The Leap Motion SDK provides two varieties of API to get tracking data from the Leap Motion service: a native interface and a WebSocket interface. The native interface is a dynamic library that you can use to create new, Leap-enabled applications. The WebSocket interface and JavaScript client library allow you to create Leap-enabled web applications.

Leap Motion Application Interface

The application interface is provided through a dynamically loaded library. This library connects to the Leap Motion service and provides tracking data to your application. You can link to the library directly in C++ and Objective-C applications, or through one of the language bindings provided for Java, C#, and Python.

images/Arch-OS-Level-Diagram.png

Leap-enabled applications

  1. The Leap Motion service receives data from the Leap Motion Controller over the USB bus. It processes that information and sends it to running Leap-enabled applications. By default, the service only sends tracking data to the foreground application. However, applications can request that they receive data in the background (a request that can be denied by the user).
  2. The Leap Motion settings dialog runs separately from the service and allows the computer user to configure their Leap Motion installation. The settings application is a Control Panel applet on Windows and a Menu Bar application on Mac OS X.
  3. The foreground Leap-enabled application receives motion tracking data from the service. A Leap-enabled application can connect to the Leap Motion service using the Leap Motion native library. Your application can link against the Leap Motion native library either directly (C++ and Objective-C) or through one of the available language wrapper libraries (Java, C#, and Python).
  4. When a Leap-enabled application loses the operating system focus, the Leap Motion service stops sending data to it. Applications intended to work in the background can request permission to receive data even when in the background. When in the background, the configuration settings are determined by the foreground application.

Leap Motion WebSocket Interface

The Leap Motion service runs a WebSocket server on the localhost domain at port 6437. The WebSocket interface provides tracking data in the form of JSON messages. A JavaScript client library is available that consumes the JSON messages and presents the tracking data as regular JavaScript objects.

images/Arch-WebSocket-Diagram.png

Leap-enabled web applications

  1. The Leap Motion service provides a WebSocket server listening on http://127.0.0.1:6437.
  2. The Leap Motion settings dialog allows end users to enable or disble the WebSocket server.
  3. The server sends tracking data in the form of JSON messages. An application can send configuration messages back to the server.
  4. The leap.js client JavaScript library should be used in web applications. The library establishes the connection to the server and consumes the JSON messages. The API presented by the JavaScript library is similar in philosophy and structure to the native API.

This interface is intended primarily for web applications, but any application that can establish a WebSocket connection can use it. The server conforms to RFC6455.

Programming Language Support

The Leap Motion library is written in C++. Leap Motion also uses SWIG, an open source tool, to generate language bindings for C#, Java, and Python. The SWIG-generated bindings translate calls written in the bound programming language to calls into the base C++ Leap Motion library. Each SWIG binding uses two additional libraries. For JavaScript and web application development, Leap Motion provides a WebSocket server and a client-side JavaScript library.

All the library, code, and header files required to develop Leap-enabled applications and plug-ins are included in the Leap Motion SDK, except the leap.js client JavaScript library. You can download the Leap Motion SDK from the Leap Motion Developer Portal. An SDK package is available for each supported operating system. The JavaScript client library is is distributed separately and can be downloaded from the LeapJS GitHub repository

C++

To develop for the Leap Motion Controller in C++, include the API header files in your program and link with the Leap Motion library, either libLeap.dylib, Leap.dll, or libLeap.so, depending on platform.

Objective-C

Objective-C applications are supported by hand-written wrapper code. To build a Leap-enabled Objective-C application, include the wrapper header and Objective-C++ code file in your application along with the Leap Motion C++ headers. You can then use the classes defined in the wrapper in (otherwise) pure Objective-C applications. Link your application with libLeap.dylib and include the library in your application package.

C#

The C# class definitions are provided for .NET 3.5 and .NET 4.0 in separate libraries. Your code can reference either LeapCSharp.NET3.5.dll or LeapCSharp.NET4.0.dll (the same library names are used for this library on all supported operating systems). These libraries load libCSharp.dylib (Mac), LeapCSharp.dll (Windows), or libLeapCSharp.so (Linux). The intermediate libraries load libLeap.dylib, Leap.dll, or libLeap.so (depending on platform).

Use the .NET 3.5 libraries with the Unity 3D game development system. The Leap Motion SDK provides a Unity plugin for use with the "Pro" version of the Unity editor. See this knowledgebase article for information on developing Leap-enabled applications with versions of the Unity editor that do not support plug-ins.

Java

Leap.jar contains the Leap Motion Java classes. This code loads libLeapJava.dylib (Mac), LeapJava.dll (Windows), or libLeapJava.so (Linux). These libraries contain the native code that translates the Java calls to the base Leap Motion API in libLeap.dylib, Leap.dll, or libLeap.so (depending on platform). The base Leap Motion dynamic library is loaded by the intermediate library.

Python

Leap.py contains the Python module that you reference in your Python application. This module loads LeapPython.so (Mac and Linux) or LeapPython.dll (Windows). These libraries load libLeap.dylib, Leap.dll, or libLeap.so (depending on platform).

JavaScript

Leap Motion JavaScript support has two main components. The first component is the WebSocket server provided by the Leap Motion service. This server allows web applications (or any application that can connect to a WebSocket) to access Leap Motion tracking data as JSON-formatted messages. The second component is the JavaScript client library, Leap.js. Leap.js is an open-source JavaScript API that consumes the WebSocket JSON output and presents it in a form that is consistent in philosophy and structure to the native Leap Motion API.

Other Languages

Many community-created language bindings are available, for a partial list, visit: Links and Libraries.

Operating System Support

The Leap Motion software currently supports OS X 10.6+ and Windows 7+. There is also an experimental, alpha-quality Linux build available only for developers.