Browse files

Cleaned up the README finally.

Signed-off-by: Kyle Machulis <>
  • Loading branch information...
qdot committed Nov 23, 2010
1 parent 8635326 commit 12a39e384b625ebcaf5c7066cacb773356008b85
Showing with 86 additions and 73 deletions.
  1. +86 −73 README.asciidoc
@@ -1,38 +1,63 @@
-== qDot's Readme
+== libfreenect
-=== So you want to play with the kinect right now
+Ongoing Development and Maintenance by the OpenKinect Community
-First off, the kinect code here is in such a massive amount of flux as
-to like, totally not even be funny. You are so amazingly on your own
-right now, but feel free to hit the #openkinect IRC channel on
-Freenode for questions.
-What you'll get when compiling this branch:
+- Original Code and Engineering: Hector Martin (marcan)
+- Community Lead: Josh Blake (JoshB)
+- Integration: Kyle Machulis (qDot)
-- the libfreenect library, not the it does a whole lot right now.
-- an executable called glview. glview will render depth data next to
- rgb data in a glut window.
+=== Description
-==== Building with CMake
+libfreenect is the core library for accessing the Microsoft Kinect USB
+camera. Currently, the library supports access to:
+- RGB and Depth Images
+- Motors
+- Accelerometer
+- LED
+Audio is currently being worked on.
+=== Information Resources
+Information about the OpenKinect project can be found at
+For questions, support, and discussion, check out the google groups
+mailing list at
+Or the IRC channel at
+#openkinect on Freenode
+=== Requirements
+You'll need
+- libusb-1.0 >= 1.0.3
+- Cmake >= 2.6
+Outside of that, you may also want opengl and other things. See the
+platform specifics section for anything needed by your platform to run
+=== Basic Compiling Instructions
To use CMake:
-- Make a directory somewhere. Like, say, c/build in your repo directory.
+- Make a directory somewhere. Like, say, 'build' in your repo directory.
- Go into that directory
- Type cmake ..
- Watch the magic happen
- After this, just run make and you'll be fine.
- If you want to use an IDE or whatever, well, you'll figure it out.
-==== Linux
-Should "just work" if you have the following packages installed:
-- libusb-1.0-dev
-- freeglut3-dev (or whatever freeglut dev package your distro has)
-Since there's no udev rules yet, you'll need to run glview as
-root. Deal with it.
+=== Platform Specifics
==== OS X
@@ -58,73 +83,61 @@ Recompile libusb and put it wherever CMake will look (/usr/local/lib,
macports, or homebrew, I'm going to expect you know what your doing
and can deal with this. If not, see IRC channel.
-==== Windows
-We're still working on that. This branch still does not work on
-windows. If you're jonesin' for windows, check out the win32-merge
-branch, though we'll be moving toward the new-api branch ASAP.
-=== And everyone else...
+OpenGL and GLUT come as prebuilt frameworks with OS X, so that should
+do it for requirements.
-Below is the readmes of the other repos I'm organizing this from. This
-currently consists of:
-- Marcan's original libfreenect repo (in the c directory here) -
- GPL'd.
-- ofTheo's OS X libfreenect patched (integrated by me, with libusb-1.0
- patches in platform directory) - GPL'd
-- JoshBlake's C# OpenKinect (in the csharp directory, with inf files
- in platform directory) - Apache'd
-- Brandyn's Python bindings (Ctypes/Cython + Sync/Async)
- in libfreenect/python. (see README there)
-The aggregated READMEs are below.
-== Marcan's Readme
+==== Linux
-Horribly hacky first take at a Kinect Camera driver. Does RGB and Depth.
+Should "just work" if you have the following packages installed:
-main.c implements a simple OpenGL visualization. Hopefully it should be mostly
-self-explanatory... You pretty much just open the USB device, call
-cams_init(dev, depthimg, rgbimg), and your depthimg and rgbimg callbacks get
-called as libusb processes events.
+- libusb-1.0-dev
+If you want to see the glview example:
-- TONS of cleanup. I mean LOTS.
-- Determine exactly what the inits do
-- Bayer to RGB conversion that doesn't suck
-- Integrate support for the servo and accelerometer (which have already been reverse engineered)
+- freeglut3-dev (or whatever freeglut dev package your distro has)
+- libxmu-dev
+- libxi-dev
-BIG TODO: audio. The audio chip (the Marvell) requires firmware and more init
-and does a TON of stuff including the crypto authentication to prove that it is
-an original Kinect and not a clone. Who knows what this thing does to the
-incoming audio. This should be interesting to look at.
+udev rules are available in the platform/linux directory so that you
+are not required to run as root.
-Libfreenect is Copyright (C) 2010 Hector Martin "marcan" <>
+==== Windows
-This code is licensed to you under the terms of the GNU GPL, version 2 or
-version 3; see:
+This library does not work on windows currently. We're trying to get
+something going ASAP though. Watch the mailing list for updates.
+=== Licensing
-Adafruit, for providing the USB logs that I used to work out the initialization
-sequence and data format.
+The libfreenect project is covered under a dual Apache v2/GPL v2
+license. The licensing criteria are listed below, as well as at the
+top of each source file in the repo.
-bushing, for trying to provide USB logs, although he got preempted by Adafruit ;)
-A few other people who provided hints and encouragement along the way, you know
-who you are!
+This file is part of the OpenKinect Project.
-== Josh Blake's Readme
+Copyright (c) 2010 individual OpenKinect contributors. See the CONTRIB
+file for details.
-OpenKinect project
+This code is licensed to you under the terms of the Apache License,
+version 2.0, or, at your option, the terms of the GNU General Public
+License, version 2.0. See the APACHE20 and GPL2 files for the text of
+the licenses, or the following URLs:
-Copyright (c) 2010 Joshua Blake and other contributors
+If you redistribute this file in source form, modified or unmodified,
+you may:
-The folder INF contains Windows drivers. Plug in Kinect and during the driver installation browse to the proper folder. The drivers were generated via libusbdotnet tools and are distributed under their own licenses.
+- Leave this header intact and distribute it under the same terms,
+ accompanying it with the APACHE20 and GPL2 files, or
+- Delete the Apache 2.0 clause and accompany it with the GPL2 file, or
+- Delete the GPL v2 clause and accompany it with the APACHE20 file
-The rest of the project is distributed under the Apache 2 license.
+In all cases you must keep the copyright notice intact and include a
+copy of the CONTRIB file.
+Binary distributions must follow the binary distribution requirements
+of either License.

0 comments on commit 12a39e3

Please sign in to comment.