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++.
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/.
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!
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.
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
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)
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/
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
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
See this useful guide on how to resolve merge conflicts.
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.
- 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
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.
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.
- 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
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:
- 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
There is some talk about Semantic Versioning via git tagging but this will need to be discussed for the future.