ofxKinect

ofxKinect is an Open Frameworks addon for the Xbox Kinect that runs on Linux and OS X. OpenFrameworks is a cross platform open source toolkit for creative coding in C++.

http://www.openframeworks.cc/

Installation

To use ofxKinect, first you need to download and install Open Frameworks. ofxKinect-beta.xcodeproj is developed against the latest version of Open Frameworks on github, while ofxKinect.xcodeproj will work with the 0062 release.

To get a copy of the repository you can download the source from http://github.com/ofTheo/ofxKinect/zipball/master or, alternatively, you can use git clone:

git clone git://github.com/ofTheo/ofxKinect.git

The addon should sit in openFrameworks/addons/ofxKinect/.

Using the latest OpenFrameworks

If you want to work with the latest unstable (still in development) Open Frameworks, download the ofxKinect source from the experimental branch https://github.com/ofTheo/ofxKinect/archives/experimental or via git clone:

git clone git://github.com/ofTheo/ofxKinect.git -b experimental

Warning: The experimental branch will be in flux, so don't be suprised if things do not always work as expected!

Running the Example Project

If you're using OS X, open the XCode project in ofxKinect/example/ and hit "Build and Run". You might want to chosoe "Release" instead of "Debug" for faster performance.

If you're using Linux, you should open the Code::Blocks .cbp and hit F9 to build and run.

You should create some udev rules in order to run the app without root privileges. As root write this to /etc/udev/rules.d/51-kinect.rules (this works on Ubuntu 10.10):

SUBSYSTEM=="usb", SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02ae", MODE="0660", GROUP="plugdev"
SUBSYSTEM=="usb", SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02ad", MODE="0660", GROUP="plugdev"
SUBSYSTEM=="usb", SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02b0", MODE="0660", GROUP="plugdev"

Windows support is currently in testing in the develop branch. The libfreenect Kinect drivers and an example Visual Studio 2010 solution are included.

Make sure to install or update the libfreenect Kinect camera, motor, and audio drivers through Windows Device Manager by pointing it to the driver folder:

libs/libusb/win/inf

You may need to manually update each driver individually if you've plugged it in before. ofxKinect will not work if the drivers are not installed.

How to Create a New ofxKinect Project

To develop your own project based on ofxKinect, simply copy the example project and rename it. You probably want to put it in your apps folder, for example, after copying:

openFrameworks/addons/ofxKinect/example/ => openFrameworks/apps/myApps/example/

Then after renaming:

openFrameworks/apps/myApps/myKinectProject/

On Mac, rename the project in XCode (do not rename the .xcodeproj file in Finder!): XCode Menu->Project->Rename

Adding ofxKinect to an Existing Project

If you want to add ofxKinect to another project, you need to make sure you include the src and libs folders:

openFrameworks/addons/ofxKinect/src
openFrameworks/addons/ofxKinect/libs

For XCode:

• create a new group "ofxKinect"
• drag these directories from ofxKinect into this new group: ofxKinect/src & ofxKinect/libs
• add a search path to: ../../../addons/ofxKinect/libs/libusb/osx/libs under Targets->YourApp->Build->Library Search Paths (make sure All Configurations and All Settings are selected)

Developing ofxKinect

Branch Layout

master is the latest stable version for 0062

develop is the unstable development branch for the current stable OF, ie 0062

experimental is the unstable development branch for the unstable OF, ie 007

This layout is designed so that a clone and the github page point to the stable version by default.

When adding new features or fixing bugs, you may need to create commits that should be merged across branches. Do this by creating a branch to do your work in, then merge this branch with other branches. Do NOT work directly on master.

Development for master is done in the develop branch and then merged. The experimental branch is for bleeding edge work with the latest unstable OF so that any new api changes do not break master or develop.

When a new stable version of OF is released, the current master is tagged with a version number (system to be determined) and experimental is merged into master.

This development model follows: http://nvie.com/posts/a-successful-git-branching-model/

Git Help

Colored Output

Use the following commands to setup colored output form git which makes it easier to see changes:

git config --global color.diff auto
git config --global color.status auto
git config --global color.branch auto

Git Cheatsheet

Print the git help:

git --help

Print the help on a specific git tool:

git help checkout

Switching to a branch:

git checkout branchname

Show which branch you are currently working in:

git branch -v

Creating a new branch:

git branch branchname

Deleting a branch:

git branch -d branchname

Show the log of the last 10 commits:

git log -10

Resolving Merge Conflicts

See this useful guide on how to resolve merge conflicts.

Developing

Checkout the develop branch:

git git://github.com/ofTheo/ofxKinect.git -b develop

Switch to the develop branch:

git checkout develop

Changes done in develop may need to be brought into master. This should not be taken lightly as master must always be stable and working with the latest stable version of OF.

The work flow is as follows:

• do your commits in develop
• switch to the master branch:

  git checkout master
  

• merge from branch to master:

  git merge develop
  

• if you have any conflicts, follow this guide on how to resolve merge commits
• push your changes to github:

  git push origin develop
  

Experimental Development

The experimental branch is considered unstable and is for an upcoming release of OF. It will only be merged into master once the new version of OF becomes stable.

Adding New Features Across Branches

If you want to add a feature to both develop and experimental, create a branch of develop, do your work, and merge the branch with both develop and experimetal. This avoid having to merge experimental with develop as any api changes between the 2 could break experimental.

The workflow is as follows:

• create a new branch for the feature from develop:

  git checkout -b newfeature develop`
  

• do your work, make commits, etc
• merge these changes to develop:

  git checkout develop
  git merge --no-ff newfeature
  

• merge these changes to experimental:

  git checkout experimetal
  git merge --no-ff newfeature
  git push origin experimental
  

• close the feature branch:

  git checkout develop 
  git branch -d newfeature
  git push origin develop
  

Making Bugfixes Across Branches:

If you want to fix a bug found in master, do not do it directly, but through a branch which can then be merged across the main branches:

The workflow is as follows:

• create a new branch for the bugfix:

  git checkout -b newbugfix master
  

• do your work, make commits, etc
• merge these changes to master:

  git checkout master
  git merge --no-ff newbugfix
  

• merge these changes to develop:

  git checkout develop
  git merge --no-ff newbugfix
  git push origin develop
  

• merge these changes to experimental:

  git checkout experimental
  git merge --no-ff newbugfix
  git push origin experimental
  

• close the bugfix branch:

  git checkout master 
  git branch -d newbugfix
  git push origin master
  

Versioning

There is some talk about Semantic Versioning via git tagging but this will need to be discussed for the future.