Notice: MediaWiki has been updated. Report any rough edges to marcan@marcan.st

Difference between revisions of "Getting Started Windows"

From OpenKinect
Jump to: navigation, search
(Dependencies: clarification, printscreen link more obvious, reference to little PATH info from the compiling section in case glut32.dll in /windows/system (as per their readme) is wrong.)
m (Compiling: system PATH doesn't include /windows/system... /windows/system32 given instead. Had missed that one.)
Line 109: Line 109:
 
*The freenect libraries in /lib are compiled but not installed at this point. To use them you should:
 
*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
 
**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/system 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
 
**Copy libraries to the folder of the program you want to run
 
If you're having issues compiling check out the [https://github.com/OpenKinect/libfreenect/tree/master/platform/windows readme] in the /libfreenect/platform/windows folder for more information.
 
If you're having issues compiling check out the [https://github.com/OpenKinect/libfreenect/tree/master/platform/windows readme] in the /libfreenect/platform/windows folder for more information.

Revision as of 09:06, 11 February 2011

Building libfreenect 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.

It may also be that you are looking for a showcase of the project's features before compiling. In that case you could take a look at this precompiled demo (source is available as well) which uses libfreenect and opencv.

Getting the source files

There are 2 ways to get the latest source:

  1. 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
  2. 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, commits Unix-style line endings"
  • Open a Command Prompt, cd to the directory where you want the source folder (/libfreenect) created and type:
$ git clone https://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.
  • You may also look into some further performance updates that have not yet been integrated to the project; see this post for further information.

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 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:

  1. Download Cmake (Cross-Platform Make) and make sure you have a working C compiler (Visual Studio 2010 or MinGW)
  2. 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
  3. Select the C compiler you want to use
  4. 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
  5. 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
  6. When all errors have been resolved, click on the "Generate" button to create the makefiles for your compiler.
  • See this sceenshot of a sample cmake configuration for MS Visual Studio 2010: 1

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