Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix broken headings in Markdown files #23

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
34 changes: 17 additions & 17 deletions README.md
@@ -1,16 +1,16 @@
#Kinect Projector Toolkit
# Kinect Projector Toolkit

Processing library for calibrating a kinect and a projector together, such that projected image is automatically aligned to the physical space it is projecting onto, facilitating the projection of images onto moving bodies and surfaces.

To see some applications of the software, see this [highlight video](http://vimeo.com/81914893) of a workshop applying the software to live dance.

The calibration methodology comes from this writeup by [Jan Hrdlička at 3dsense blog](http://blog.3dsense.org/programming/kinect-projector-calibration-human-mapping-2/). For other work on Projector/Kinect calibration, see works and code by [Elliot Woods, Kyle McDonald](https://github.com/elliotwoods/artandcode.Camera-and-projector-calibration), and [Daito Manabe](http://thecreatorsproject.vice.com/blog/projection-mapped-dance-performance-daito-manabe), as well as the OpenFrameworks addon [ofxCamaraLucida](http://chparsons.com.ar/#camara_lucida).

##V2 version
## V2 version

A very nice-looking fork of this for Kinect V2 is available [here](https://github.com/bradenneufeld/K2P3Toolkit).

##Installation
## Installation

The library requires [Processing 2.0+](http://www.processing.org), [SimpleOpenNI](https://code.google.com/p/simple-openni/), [ControlP5](http://www.sojamo.de/libraries/controlP5/), and [OpenCV](https://github.com/atduskgreg/opencv-processing).

Expand All @@ -19,18 +19,18 @@ To install the library, copy the entire contents of this repository into a folde
The library comes with a number of demos in the "examples" folder, as well as a program called **CALIBRATION.pde** which is the application used for determining the fit between the projector and Kinect. Instructions for calibration follow below.


##Instructions for calibration
## Instructions for calibration

###*[Video tutorial for calibration](http://vimeo.com/84658886)*
### *[Video tutorial for calibration](http://vimeo.com/84658886)*

###1) Room setup
### 1) Room setup

After setting the projector, fix the Kinect to face the space onto which you are projecting. Ideally, the Kinect is tracking roughly the full space of the projection; if it is too close it may not see everything the projector sees, and if it is too far, it will be less precise. Unless you have a short-throw projector, the Kinect will probably be closer to the stage than the projector.

The Kinect and projector must be *totally immobilized* during calibration and after, because a calibration only works for that positioning of the two devices together.


###2) Software setup
### 2) Software setup

Set your computer's display to extended/dual screen and project the secondary screen. Open up **CALIBRATION.pde** and make sure to set the `pWidth` and `pHeight` variables at the top to exactly match the resolution of the secondary display, e.g. 1024x768.

Expand All @@ -39,7 +39,7 @@ Finally, set the `calibFilename` variable to the exact path to which you want to
![Setting up display](http://www.genekogan.com/images/kinect-projector-toolkit/kpt_screen_1.jpg)


###3) Getting point pairs
### 3) Getting point pairs

The interface allows you to position a 5x4 chessboard which is being projected onto your stage/room. You can move its position using the XY grid on the right side of the interface, and resize it using the "size" slider. The "searching" button toggles whether the app is actively searching for a chessboard pattern.

Expand All @@ -52,7 +52,7 @@ You need some sort of a flat, mobile panel (best if white) to project onto. Plac
Repeat this process for a series of panel positions throughout your stage space. To get the best possible fit, you should sample the space as widely as possible. Move the board to at least two or three different depths (distance from the Kinect), and position the board at high and low positions as well. The more dispersed your board points are across all three spatial dimensions, the better your fit will be. If the points are mostly coplanar, the model may not generalize well to undersampled regions.


###4) Calibration
### 4) Calibration

Depending on the demands of your application, you may need only a few board positions, or several dozen. Generally, 10-15 board positions gives a good fit, with each position contributing 12 point pairs. When you have a good amount of point pairs, click the "calibrate" button. This will generate a calibration.

Expand All @@ -61,7 +61,7 @@ Once you have generated a calibration, you can toggle into "Testing mode" which
If the calibration is satisfactory, click "Save." It will generate a text file containing the calibration parameters, which will be located in the path you specified in the `calibFilename` variable.


##Using the calibration
## Using the calibration

The core function of the library is the ability to map any 3d point in physical space to the corresponding pixel which falls on that point. The process goes as follows.

Expand Down Expand Up @@ -93,7 +93,7 @@ An optional second parameter "dilates" the projected contour, i.e. stretches or
The test applications in the library demonstrate some of these tasks.


##Test applications
## Test applications

The library contains a number of examples, prefixed "Test" which demonstrate various uses of the toolkit for creative projection. Demos include projecting an image onto a human body, projecting images onto specific tracked parts of a body, graphics projected onto background surfaces interacting with tracked bodies, etc.

Expand All @@ -103,20 +103,20 @@ You must first make sure to go through the calibration process and generate the

Descriptions for test applications follow below:

###TestSkeleton, TestKrang, TestFireball
### TestSkeleton, TestKrang, TestFireball
These demos are the simplest applications of the calibration. The Kinect tracks users and returns real world coordinates for their joints and limbs, and we project objects onto them. Skeleton projects the entire skeleton onto each person, Krang projects an image of [Krang](http://en.wikipedia.org/wiki/Krang) onto users' torsos.

###TestBodyGraphics, TestBodyImage, TestBodyMovie, TestBodyShader
### TestBodyGraphics, TestBodyImage, TestBodyMovie, TestBodyShader
Show the process of projecting graphics onto a tracked human body, via the Kinect's userImage. They are identical, except for the content of the graphics, showing how to project a PGraphics object, a PImage, a Movie, and a shader, respectively.

###TestRibbons
### TestRibbons
Similar to the body projection examples, but instead projects ribbon-like lines around the contour of a body, tracing them onto the background behind the user.

###TestBackgroundFX
### TestBackgroundFX
This example shows how a tracked user can manipulate background graphics projected behind them onto a screen or floor.

###TestFallingPolygons
### TestFallingPolygons
Similar to TestBackgroundFX as it involves a user manipulating a background screen. A game in which polygons fall from the sky and a user can physically interact with them on a wall.

###RENDER
### RENDER
This is a high-level application combining the previous examples with a user interface for applying the effects. It is currently still under development.