Getting Started

Language:	English • français • italiano • português do Brasil

Please read this before you start

This page documents how to get started using OpenKinect. The libraries are very much in flux and this won't be the final process. This also means these instructions might be out of date with the latest commits. You may also want to take a look at the following for more information:

the github project top README (don't forget other readme files in the project tree for specific components)
the Wrappers section
the OpenKinect mailing list
the FAQ

Support

For support requests in the OpenKinect irc channel or in the mailing list, please specify the platform you are using, the version of the software you are trying to build or install, and information about the context etc. as explained here.

The adapter

The Kinect needs its own power source which is independent from the USB connection to work on a computer. The latest Xbox360 can power the Kinect directly but the older Xbox requires an adapter for that purpose. Therefore, the Kinect which is bundled with the Xbox360 doesn't include an adapter whereas the Kinect which is sold separately does. The adapter is sold here. This adapter is required to use the Kinect hardware on your computer with libfreenect.

Fakenect

It is also possible to use the Fakenect utility which is a libfreenect simulator/mock interface to run the Kinect demos without having a Kinect.

Thank you!

Linux

Ubuntu

An Ubuntu launchpad ppa for Lucid(10.04), Maverick (10.10), Natty (11.04), and Oneiric (11.10) is available at:

https://launchpad.net/~floe/+archive/libtisch

to use it, open a console and execute:

$ sudo add-apt-repository ppa:floe/libtisch

Resynchronize the list of packages from the repository:

$ sudo apt-get update

After that, you can use:

$ sudo apt-get install libfreenect libfreenect-dev libfreenect-demos

This will install libfreenect, the development headers, and the demo applications.

After that, you need to add yourself to the 'video' group and log back in. The package already includes the necessary rules for the udev daemon so that accessing the device will be possible for users in the group video.

$ sudo adduser $USER video

be sure to log out and back in. You don't need to reboot, just plug in the kinect device right now (if it was already connected, unplug and plug back in).

To start the demo applications use:

$ freenect-glview

You find all demo applications starting with the freenect- prefix.

Ubuntu Manual Install

Quick copy-paste instructions to get up-and-running instantly:

sudo apt-get install git-core cmake libglut3-dev pkg-config build-essential libxmu-dev libxi-dev libusb-1.0-0-dev
git clone git://github.com/OpenKinect/libfreenect.git
cd libfreenect
mkdir build
cd build
cmake ..
make
sudo make install
sudo ldconfig /usr/local/lib64/
sudo glview

Note: If you getting an error saying apt-get cannot find libglut3, you might be on a newer version of Ubuntu that has freeglut3-* instead of libglut3-*, so your initial apt-get install would look like:

sudo apt-get install git-core cmake freeglut3-dev pkg-config build-essential libxmu-dev libxi-dev libusb-1.0-0-dev

To use Kinect as a non-root user do the following:

sudo adduser $USER video

Also make a file with rules for the Linux device manager:

sudo nano /etc/udev/rules.d/51-kinect.rules

Copy and paste:

# ATTR{product}=="Xbox NUI Motor"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02b0", MODE="0666"
# ATTR{product}=="Xbox NUI Audio"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ad", MODE="0666"
# ATTR{product}=="Xbox NUI Camera"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ae", MODE="0666"

Be sure to log out and back in.

Manual Build on Linux

these instruction need more work, mostly taken from README.asciidoc
Works on CentOS 5.6 x86_64

Install dependencies

For compiling, you need to have the following libs/programs installed. Note these package names seem to be geared toward Ubuntu/Debian.

* cmake
* libusb-1.0-0
* libusb-1.0-0-dev
* pkg-config
* libglut3
* libglut3-dev

APT users: (Works on Ubuntu 10.10)

$ sudo apt-get install cmake libglut3-dev pkg-config build-essential libxmu-dev libxi-dev libusb-1.0-0-dev

For a non-developer install of RedHat/Fedora/CentOS using yum/rpms, the following command should install most of the packages needed to retrieve, compile, & run the glview demo:

$ yum install git cmake gcc gcc-c++ libXi libXi-devel libXmu libXmu-devel freeglut freeglut-devel

If you don't see these packages, you will need to add RPMforge as a repository

RPMforge
RPMforge for CentOS

Clone libusb-1.0 Repo and Configure Makefile

If you can not find a pre-built distribution of libusb-1.0, you will need to build it yourself.

$ git clone git://git.libusb.org/libusb.git
$ cd libusb
$ ./autogen.sh

If you get the error:

$ configure: error: cannot find macro directory `m4'

Then you need to create the m4 directory and rerun ./autogen.sh

$ mkdir m4
$ ./autogen.sh

Build libusb-1.0

$ make
$ sudo make install

Clone libfreenect Repo

$ git clone git://github.com/OpenKinect/libfreenect.git

If you get the error:

$ error: SSL certificate problem, verify that the CA cert is OK. Details:
$ error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed while accessing https://github.com/OpenKinect/libfreenect.git/info/refs

Your SSL Certificate Authority (CA) root certificates are out of date. The following will install the latest version of Mozilla's CA certificate bundle. More info at:
http://curl.haxx.se/docs/caextract.html
http://curl.haxx.se/docs/sslcerts.html

$ su root
$ curl http://curl.haxx.se/ca/cacert.pem -o /etc/pki/tls/certs/ca-bundle.crt

Build libfreenect

$ cd libfreenect
$ mkdir build
$ cd build
$ ccmake ..

Inside the ccmake editor, press c to configure
Using the arrow keys, move to line with LIBUSB_1_INCLUDE_DIR
Press enter to edit the line, then change it to /usr/local/include/libusb-1.0
Press enter when finished editing
Press c to continue configuring
If everything is correct, you will now get an option to press g to generate and exit

Now continue building:

$ cmake ..
$ make
$ sudo make install

If you get the error:

$ CMake Error at src/cmake_install.cmake:64 (FILE):
$   file INSTALL cannot find file
$   "/usr/local/libfreenect/build/src/libfreenect.pc" to install.
$ Call Stack (most recent call first):
Bold text$   cmake_install.cmake:37 (INCLUDE)

Then copy libfreenect.pc file into src directory and reinstall:

$ cp libfreenect.pc src/
$ sudo make install

Errors

If you run into into the following cmake error:

$ CMake Error: The following variables are used in this project, but they are set to NOTFOUND.
$ Please set them or make sure they are set and tested correctly in the CMake files:
$ GLUT_Xi_LIBRARY (ADVANCED)
$    linked by target "glview" in directory /home/user/libfreenect/examples
$ GLUT_Xmu_LIBRARY (ADVANCED)
$    linked by target "glview" in directory /home/user/libfreenect/examples

Then you need to install libxi-dev and libxmu-dev/libxmu-headers If you are using Ubuntu 10.04 or 11.04, type the command: sudo apt-get install libusb-1.0-0-dev libxmu-dev libxi-dev

If you are using Ubuntu 11.04, GLUT_Xi_LIBRARY might still not be found, although it's installed. A workaround for this is to create a symlink:

sudo ln -s /usr/lib/i386-linux-gnu/libXi.so /usr/lib/libXi.so

If glview gives a shared library error:

$ glview 
glview: error while loading shared libraries: libfreenect.so.0.0: cannot open shared object file: No such file or directory
glview: error while loading shared libraries: libusb-1.0.so.0: cannot open shared object file: No such file or directory

You need to refresh your ldconfig cache. The easiest way to do this is to create a file usr-local-libs.conf (or whatever name you wish) with the following lines:

/usr/local/lib64
/usr/local/lib

Switch to root account and move it to /etc/ld.so.conf.d/usr-local-libs.conf. Then update the ldconfig cache:

$ su root
$ mv ~/usr-local-libs.conf /etc/ld.so.conf.d/usr-local-libs.conf
$ /sbin/ldconfig -v

Python

To compile the Python wrappers you'll need the package "python-dev" and cython. The cython package included in Ubuntu 10.10 seems to be broken (see this), get it here or try

 $ sudo easy_install cython

For more information about the Python wrappers see this page.

Use as normal user

To be able to access the Kinect you need to add yourself to the video group and change the permission on the created device.

create a file: /etc/udev/rules.d/66-kinect.rules

#Rules for Kinect ####################################################
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02ae", MODE="0660",GROUP="video"
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02ad", MODE="0660",GROUP="video"
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02b0", MODE="0660",GROUP="video"
### END #############################################################

and add yourself to the video group:

$ sudo usermod -a -G video YOURUSERNAME

Testing the Kinect

You need to do this as root (or use sudo) if you did not follow the "Use as normal user" steps.

$ bin/glview

or

$ sudo bin/glview

OS X

It is best to install (at least the prerequisites) via a package manager. If you're not already using macports or fink, try Homebrew as we actually have a full package created for this.

MacPorts

Current versions of MacPorts need to support several different versions of libusb. We have added a special libusb-devel port that builds the patched libusb library required by the Kinect.

After installing MacPorts, issue the commands:

 sudo port install git-core
 sudo port install libtool
 sudo port install libusb-devel

Then change to a working directory, and you're ready to:

git clone git://github.com/OpenKinect/libfreenect.git

and continue as per the Manual Build under OSX section. The libusb found by cmake will be correct and already-patched, greatly simplifying the build process!

Fink

After installing Fink, issue the following command:

 fink install cmake git libusb1 libfreenect

Or you can skip installing 'libfreenect' if you want to build from source:

git clone git://github.com/OpenKinect/libfreenect.git

and continue as per the Manual Build under OSX section.

Homebrew

If you dont have Homebrew already, it is quite simple to install.

Note: Even if you already have homebrew, make sure to update your formulas (run `brew update`), before trying to install libfreenect as there has been a lot of bugfixing to cmake lately.

Get the formulas

Since the project is still so much in flux the packages are not yet in the official homebrew directory, so you will need to manually fetch them:

cd /usr/local/Library/Formula
curl --insecure -O "https://raw.github.com/OpenKinect/libfreenect/master/platform/osx/homebrew/libfreenect.rb"
curl --insecure -O "https://raw.github.com/OpenKinect/libfreenect/master/platform/osx/homebrew/libusb-freenect.rb"

Install

brew install libfreenect

And thats it, you are done! A copy of glview demo should now be in your PATH so you can simply run:

glview

to confirm everything worked out ok.

Manual Build under OSX

Prerequisites:

git
cmake (Can be obtained via MacPorts or from http://www.cmake.org/cmake/resources/software.html)

Next create fetch the OpenKinect repository and libusb:

git clone git://github.com/OpenKinect/libfreenect.git
git clone git://git.libusb.org/libusb.git or git clone http://git.libusb.org/libusb.git

You don't need to fetch and patch libusb if you already installed libusb-devel via MacPorts (see above)! If you cloned libusb via github you will need to patch it for OpenKinect like so:

cd libusb
./autogen.sh
patch -p1 < ../libfreenect/platform/osx/libusb-osx-kinect.diff
./configure LDFLAGS='-framework IOKit -framework CoreFoundation'
make
sudo make install

and configure OpenKinect:

cd ../libfreenect/
mkdir build
cd build
ccmake ..

Don't worry if it shows you an 'Empty Cache' at startup. Now press 'c' in ccmake to configure it. If you already installed libusb via MacPorts or Homebrew, it will work fine. Otherwise it will likely fail, because it cannot find libusb. Press 'e' to exit help and manually edit the path to libusb in the following screen to point to /usr/local/include/libusb-1.0/ and continue.

When you're done, build OpenKinect:

cmake ..
make

If you want to build OpenKinect as an Xcode project, instead do:

cmake -G Xcode ..
make

And you're done! There now should be a program called 'glview' in libfreenect/build/bin. Connect your Kinect and start it! If you run into 'ld: warning: in /usr/local/lib/libusb-1.0.dylib, missing required architecture x86_64' when using make, you have to correct the paths with cmake: They have to point to /opt ... when libusb was installed via MacPorts.

To have the files globally available on your Mac and to use them with your own projects, you may install them:

sudo make install

Parallel usage with pyusb

If you also want to use pyusb to play with the Kinect, you will need libusb-1.0.8 (it seems). Install it via homebrew and then define the _lib variable before finding the usb device:

from ctypes import *
import usb.core
import usb.utils

_lib = CDLL('/usr/local/Cellar/libusb/1.0.8/lib/libusb-1.0.dylib') # That's the location homebrew puts the libusb libraries
dev = usb.core.find(idVendor=0x045e, idProduct=0x02B0)

Windows

If you are looking for a showcase of the project's features before compiling, you could take a look at this precompiled demo (source is available as well) which uses libfreenect and opencv.

Manual build from source

Introduction

Building from source shouldn't require any specific expertise but may yet be challenging for some. This introduction will serve to give those who need it a bit of background as to what we're trying to do here. To summarize, you will be downloading the latest libfreenect source and separate dependencies. The dependencies will be used twofold. First, you will copy .dll files to your system where they can be accessed. Secondly, you will link .lib and header files to the source code using the cmake-gui program in order to configure the project and generate the makefiles required for compiling. Finally, you will bring the configured project to your integrated development environment (ex. Visual Studio 2010) for compiling proper or to start your own development. So you should understand from this that your system needs some libraries to run the project demos just like any other piece of software usually does (and .dll files are used for this) and that before this can happen the project itself needs links to libraries and headers to build properly. Note that the resulting compiled libfreenect is itself a dll library which your computer will need to access in order to run the glview.exe demo for example. All of this should become quite clear as you go through the steps.

Getting the source files

There are 2 ways to get the latest source:

Go to the OpenKinect project github, select the branch you want (master or unstable for instance - see below) and click the "Download" button (then extract the files to a convenient location) or
Use Git to create and keep an up to date project folder and access any branch locally:

Using Git

Download and install Git with these settings:
- Accept the license etc.
- Choose the level of shell integration you want
- Choose "Run git from the Windows Command prompt"
- Choose "Check out WIndows style, commit Unix-style line endings"

Open a Command Prompt, cd to the directory where you want the source folder (/libfreenect) created and type:

$ git clone git://github.com/OpenKinect/libfreenect.git //downloads the project, creates local master
$ cd libfreenect                                            //cd to source directory
$ git branch --track unstable origin/unstable        //creates a local unstable branch for remote unstable
$ git checkout master                                //check out the master or unstable branch
$ or
$ git checkout unstable
$ git pull                                           //updates the contents of the selected branch

The contents of the libfreenect folder will interactively change as you checkout a specific branch (magic!) so you don't need to search for a specific "branch" folder inside the libfreenect directory. Just checkout the branch you want to configure and proceed using the libfreenect folder as source in cmake. This setup allows you to easily switch between the master and unstable branch, update the source files and then configure the branch you want to build.

The "git branch" command will show you the different branches (here master and unstable) and which one is currently selected. You can also view the development logs for the branch you're checking out with the "git log" command (use shift-Q to exit the log).

Master vs. unstable branch

If you plan on changing libfreenect, writing wrappers, or trying the latest developments you might want to check out the unstable branch. Unstable has the latest commits that have not been fully tested yet. Otherwise just try the 'master' branch.

Take note that the master and unstable branches were synced on Jan. 6, 2011; see this update for more information.
On February the 15th, support for multiple resolutions was added to the unstable branch and the 1280x1024 RGB and IR mode was enabled as explained here.

After you have the source files, you should download the dependencies required to configure and build the library and then install the hardware driver...

Dependencies

For each required dependency, first download and install the libraries (.dll) on your system and then identify the paths to the libraries (.lib or .a) and header (.h) files which you will need later on to configure the source project using cmake:

Dependency	Install	Library/includes to be used with cmake (see this printscreen)
libusb-win32 - download and extract the latest libusb-win32-bin-x.x.x.x.zip NOTE: Currently there is a breaking change in libusb 1.2.5.0. Until we fix libfreenect to accept this change and remove this message, please use libusb 1.2.4.0	This will be taken care of when we install the driver in the next section	The /lib and /include folders contain the libraries and header files required to configure the project; depending on the compiler you choose, you may have to specify a different library file: For instance, to configure for MS Visual Studio 2010, use /lib/msvc/libusb.lib or if you plan to use mingw, use /lib/gcc/libusb.a as the libusb library path in cmake (LIBUSB_1_LIBRARY) Select the path to the libusb header folder /include as libusb include path in cmake (LIBUSB_1_INCLUDE_DIR) For more info see the libusb-win32 readme and their wiki
pthreads-win32 - download and extract the latest pthreads-w32-x-x-x-release.exe	Find the /lib folder and copy the appropriate .dll library to /windows or /windows/system32 (see Library/includes to the right to figure out which one to use)	The /lib and /include contain the libraries and header files required to configure the project; depending on the compiler you choose, you may have to specify a different library file: For instance, to configure for MS Visual Studio 2010, use /lib/pthreadVC2.lib or if you plan to use mingw, use /lib/pthreadGC2.a as the pthread library path in cmake (THREADS_PTHREADS_WIN32_LIBRARY) In both cases you will need to install the corresponding library .dll file to /windows/system32 i.e. phtreadVC2.dll or pthreadGC2.dll Select the path to the pthread header folder /include as pthread include path in cmake (THREADS_PTHREADS_INCLUDE_DIR) For more info see the pthreads-win32 readme and their FAQ
Glut - download and extract the latest glut-x.x.x-bin.zip	Find the glut32.dll file and copy it to /windows/system or any directory included in your PATH system variable (see this explanation)	With MSVC, you should copy the glut.h header file to the /include/GL folder and the glut32.lib library to the /lib folder of your VC tree(for instance /Program Files/Microsoft Visual Studio 10.0/VC/) - if the GL folder is not there, create it and put the glut.h file there. If you built glut from source, the files should already be there. In cmake-gui, supply the path to the header up to the /include folder (NOT ../include/GL) and the path to the library itself (../lib/glut32.lib) in cmake (GLUT_INCLUDE_DIR and GLUT_glut_LIBRARY respectively) For more info see the glut readme

Driver installation

There are two parts to libfreenect -- the low-level libusb-based device driver and libfreenect itself, the library that talks to the driver. You only need to install the driver once.

Windows 7: step-by-step walkthrough (should also work with Windows XP!)

Plug in your Kinect. Windows will warn that no device driver was found for the plugged device (the LED of Kinect will not turn on). If Windows presents a dialog asking to search for drivers, simply cancel it.

Open the Device Manager: Start >> Control Panel >> System and Security >> System >> Device Manager

A device called "Xbox NUI Motor" should be somewhere there (most probably be under "Other devices") with a small yellow warning symbol "!" on top of its icon. Right click on it, and select "Update Driver Software...", then click on "Browse my computer for driver software".

"Browse" and select the folder where the "XBox_NUI_Motor.inf" is located (/platform/windows/inf inside your libfreenect source folder). Click "Next" and if warned by Windows that a non-certified driver is about to be installed, just order it to install it anyway.

After that, the Kinect LED should start blinking green. Now there will be two additional devices in the Device Manager list: "Xbox NUI Camera" and "Xbox NUI Audio". Repeat the above instructions for them as well.

You are now ready to configure libfreenect before building...

Configuring with cmake-gui

Follow these steps to configure libfreenect for compiling:

Download Cmake (Cross-Platform Make) and make sure you have a working C compiler (Visual Studio 2010 or MinGW)
Launch Cmake-GUI and select your /libfreenect folder as source, select an output folder, check the "advanced" and "grouped" checkboxes to display more variables and categorize them and then click on the "Configure" button
Select the C compiler you want to use
Select the BUILD options you want, taking into consideration the following:
1. For now only select the EXAMPLES and C_SYNC options in BUILD. The other build options such as FAKENECT have not been updated for Visual Studio yet
2. But take a look at the following notes if you're interested in compiling the PYTHON wrapper
Unresolved dependencies will show up as red in the CMake GUI. Supply the missing paths to the dependencies by following these guidelines, and click the "Configure" button again:
1. The *_LIBRARY variables need to point to actual .lib files not a folder
2. INCLUDE variables need to point to the appropriate include directories
When all errors have been resolved, click on the "Generate" button to create the makefiles for your compiler.

Compiling

Now that the project is configured, open libfreenect.sln from your output folder and build it with Visual Studio. Then look for your compiled files in /bin and /lib

The freenect libraries in /lib are compiled but not installed at this point. To use them you should:
- Add the path to the /lib folder to your system PATH environment variable or
- Copy the libraries to a folder already in the system PATH like /windows/system32 or
- Copy libraries to the folder of the program you want to run
If some items fail to compile the first time, simply right-click on the solution again and select "Build" or "Rebuild" to see if the missing items compile
If you're having issues compiling check out the readme in the /libfreenect/platform/windows folder for more information.

Testing

To do a quick test run /bin/glview.exe

It's also a good idea to check the wrappers section and the mailing list for more ideas and solutions...

User contributions

Installation/Compilation Guides

Getting Started

Please read this before you start

Linux

Ubuntu

Ubuntu Manual Install

Manual Build on Linux

Install dependencies

Clone libusb-1.0 Repo and Configure Makefile

Build libusb-1.0

Clone libfreenect Repo

Build libfreenect

Errors

Python

Use as normal user

Testing the Kinect

OS X

MacPorts

Fink

Homebrew

Get the formulas

Install

Manual Build under OSX

Parallel usage with pyusb

Windows

Manual build from source

Introduction

Getting the source files

Dependencies

Driver installation

Configuring with cmake-gui

Compiling

Testing

User contributions

Navigation menu

Search