Setting Up a Project

This article discusses how to import the Python libraries in a Python program.

Libraries

The Leap Motion Python API is provided as a Python extension module containing both Python and native code. The Python API supports Python 2.7.

  Windows Mac Linux
Python module lib/Leap.py lib/Leap.py lib/Leap.py
32-bit native libraries

lib/x86/LeapPython.pyd

lib/x86/Leap.dll

 

lib/x86/LeapPython.so

lib/x86/libLeap.so

64-bit native libraries

lib/x64/LeapPython.pyd

lib/x64/Leap.dll

 

lib/x64/LeapPython.so

lib/x64/libLeap.so

Universal binary native libraries  

lib/LeapPython.so

lib/libLeap.dylib

 

You can find these libraries in the lib folder of the Leap Motion SDK download package. On Windows and Linux, you must use the x86 versions of the native libraries for 32-bit versions of Python and the x64 versions for 64-bit versions of Python.

Leap Motion does not provide these libraries in a standard Python package or install them on end-user computers. Treat the libraries as internal modules of your application. It is your responsibility to distribute the libraries with your application.

Importing the Leap Motion Module

To import the Leap module, the library files must be placed in a location where the Python runtime can find them. The easiest way to do this is to put them in the same directory as your application source code. Python looks in the same directory as the importing file for imported modules.

If you prefer to keep the libraries in a separate directory from your source code, you can add the path to the Leap Motion libraries to the Python sys.path list before importing the Leap module:

import sys
sys.path.insert(0, "path/to/leap/libraries")
import Leap

For example, if your project file structure looked like:

SnakesAndLadders/
    src/
        Snakes.py
        Ladders.py
    lib/

You could copy the Leap Motion libraries to the lib subfolder (making sure to copy the appropriate files for your platform and architecture). For example, on a Mac, your project would look like:

SnakesAndLadders/
    src/
        Snakes.py
        Ladders.py
    lib/
        Leap.py
        LeapPython.so
        libLeap.dylib

From the Snakes.py or Ladders.py source, you could then import the Leap module with the following:

import sys
sys.path.insert(0, "../lib")
import Leap

This import method assumes that your Python file is always run with the current working directory set to the folder containing your main Python file. To allow the import to work when the main application file is invoked from any directory, you can use the Python inspect module to get the directory containing your source file and then set the sys.path relative to that folder:

import os, sys, inspect
src_dir = os.path.dirname(inspect.getfile(inspect.currentframe()))
lib_dir = os.path.abspath(os.path.join(src_dir, '../lib'))
sys.path.insert(0, lib_dir)
import Leap

Note: If you are developing applications solely for your own use, you can put the Leap module and its supporting native libraries in any convenient location: for example, in one of the folders listed in the Python sys.path variable, a folder referenced in your PYTHONPATH environment variable, etc – just remember where you put them when it comes time to update your Leap Motion SDK. However, since the Leap module isn’t currently available through standard Python package managers, copying the Leap Motion libraries to one of the standard Python module search locations isn’t recommended. Doing so could create conflicts if multiple applications try to install their own version of the Leap Motion libraries.

Supporting 32- and 64-bit Python Architectures

To support both 32-bit and 64-bit architectures at the same time on Windows and Linux, you can use a run-time check for the architecture and then set the sys.path to reference the correct files. On Mac, the Leap Motion libraries are universal binaries that support both architectures, so this technique is not needed.

Using the hypothetical SnakesAndLadders project as an example again, you would copy both sets of library files to separate folders within the application, for example:

SnakesAndLadders/
    src/
        Snakes.py
        Ladders.py
    lib/
        x86/
            Leap.py
            LeapPython.so
            libLeap.so
        x64/
            Leap.py
            LeapPython.so
            libLeap.so

And then reference the proper Leap module at run time:

import os, sys, inspect
src_dir = os.path.dirname(inspect.getfile(inspect.currentframe()))
arch_dir = '../lib/x64' if sys.maxsize > 2**32 else '../lib/x86'
sys.path.insert(0, os.path.abspath(os.path.join(src_dir, arch_dir)))

import Leap

The same technique could be extended to support multiple platforms at the same time.

Using a Different Python Distribution

To use the Leap Motion Python libraries with an alternate Python 2.7 distribution on Mac or Linux (i.e HomeBrew or MacPorts, etc.) or with a self-built version of Python, you must update the LeapPython.so loader path to reference the desired instance of Python.

First, run the otool utility to display the current loader paths:

otool -L LeapPython.so

Which will display output similar to:

LeapPython.so:
    @loader_path/LeapPython.so (compatibility version 0.0.0, current version 0.0.0)
    /Library/Frameworks/Python.framework/Versions/2.7/Python (compatibility version 2.7.0, current version 2.7.0)
    @loader_path/libLeap.dylib (compatibility version 0.7.0, current version 2.0.1)
    /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 169.3.0)
    /usr/lib/libstdc++.6.dylib (compatibility version 7.0.0, current version 56.0.0)

The line starting with, /Library/Frameworks/Python.framework/Versions/2.7/Python is the reference to Python, which needs to be changed with the install_name_tool utility.

Second, run the install_name_tool utility to update the Python reference to the desired location. For example:

install_name_tool -change /Library/Frameworks/Python.framework/Versions/2.7/Python \
/usr/local/Cellar/python/2.7.5/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib \
LeapPython.so

Note: otool and install_name_tool are standard Linux and OS X command line utilities.

Recompiling LeapPython for Python 3

The LeapPython library included in the Leap Motion SDK supports only Python 2.7. However, the SDK also includes the SWIG interface file used to generate the LeapPython source code, so advanced users can generate and compile their own version of LeapPython. For instructions, refer to Generating a Python 3.3.0 Wrapper with SWIG 2.0.9 in our support knowledge base.