README

*-----**-----**-----**-----**-----**-----**-----**-----**-----**-----*
Unity3d + OpenTSPS Example project
Created by James George 
art: http://www.jamesgeorge.org/  | com: http://www.flightphase.com
*-----**-----**-----**-----**-----**-----**-----**-----**-----**-----*

November 24th 2010

This project provides a template and example project for combining the Toolkit for Sensing People In Spaces (http://www.opentsps.com) 
with Unity3d Game Engine (http://www.unity3d.com)

a video example of the project is on my vimeo page
http://vimeo.com/17177478

INSTRUCTIONS
*-----**-----**-----**-----**-----*

	Step 1: 
	Download the Unity example in this repository 
	https://github.com/obviousjim/OpenTSPS_Unity3d_Extension

	Step 2: 
	Download a compiled binary of openTSPS from openTSPS.com

	Step 3:
	Set up your video camera to track some people. This requires some 
	pretty specific and stable lighting. If it's not convenient see below for 
	alternatives for prototyping applications with OpenTSPS/Unity3d

	Step 4:
	Start up OpenTSPS and configure the OSC communication to send to appropriate host/port.
	Most likely you're running these on the same computer, so you can specify IP of
	localhost and use the default OpenTSPS port 12000
	
	Step 5:
	Double click the OpenTSPSExample.unitypackage project. This will import the example scene into
	your current Unity Project if you have one open. Double click the openTSPSReceiver scene to 
	check out the example.
	
	Hit play. If are people in your TSPS scene you should see 
	little cubes moving around tracing their position. Now you can take it from here!
	
	
SCENE SET UP
*-----**-----**-----**-----**-----*
	The example project creates a cube for each person in the scene and moves 
	it along as the person moves across a 3d platform.  OpenTSPSUnityListener.cs script is attached
	to an empty object. This object begins listening for OpenTSPS messages on game start up
	and then instantiates / moves / destroys cubes as they are received.
	

INCLUDED SOURCE FILES
*-----**-----**-----**-----**-----*

	OpenTSPSUnityListener.cs
		An example script that can be added to the an empty game object 
		that will then receive TSPS messages. This is an implementation of 
		the OpenTSPSListener interface class This object also moves the cubes 
		around within the scene.
		
	OpenTSPSListener.cs
		Interface for TSPS listeners. Classes implementing this 
		interface can listen to TPSP messages. 
		
	OpenTSPSReceiver.cs
		Internal code that handles OSC messages and calls back to 
		attached OpenTSPSListeners
		
	OpenTSPSPerson.cs
		Container class for an OpenTSPS Person object which is created for each 
		person in the scene
		
	OSC.NET/
		includes an OSC implementation for Unity3d in C#

WEB CAM ALTERNATIVES:
*-----**-----**-----**-----**-----*

	If access to a good people tracking set up isn't convenient there 
	is a great program called CamTwist for OS X that can play quicktime movie as a 
	WebCam. This lets OpenTSPS use a movie file as input instead of a live camera.
	http://allocinit.com/index.php?title=CamTwist

	You'll need a good video to test it with. Theo Watson has some test videos that work 
	well with people tracking. Any of the overhead ones will do
	http://muonics.net/cvMovies/

	here are some more security-camera movies that work fairly well with TSPS:
	http://homepages.inf.ed.ac.uk/rbf/CAVIARDATA1/


ACKNOWLEDGMENTS
*-----**-----**-----**-----**-----*

	The OSC implementation for Unity+TSPS is taken from the OSCuMote project:
	http://forum.unity3d.com/threads/21273-OSCuMote-Wiimote-support-for-the-free-version

	Which builds upon some code from the Unity/TUIO project

	Big props to the OpenTSPS project for leading the way.
	from the TSPS page:
		"TSPS was started as a collaboration between the LAB at Rockwell Group and the LABS at IDEO. 
		It began as an initiative between Dave  Vondle (IDEO) and Joshua Walton (LAB at Rockwell Group) 
		with many of the key components generated through the hard work of James Tichenor, 
		Brett Renfer, and James George who in turn also used components from the openframeworks 
		community, who in turn built upon many open source projects.

		Special thanks to the teams that develop Openframeworks, OpenCV, 
		and the many individuals who are all working on creating better computer vision systems."


	community contributors include:
		Joshua Walton & James Tichenor (http://lab.rockwellgroup.com)
		Brett Renfer (http://robotconscience.com/)
		myself (http://www.jamesgeorge.org)
		Zack Boka (http://www.zackboka.com)
		Jeff Crouse (http://www.jeffcrouse.info/)
		...and others