/****************************************************************************
	jit.openni
	Copyright (C) 2011 Dale Phurrough

	This file is part of jit.openni.

    jit.openni is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    jit.openni is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with jit.openni.  If not, see <http://www.gnu.org/licenses/>.
****************************************************************************/

jit.openni - a Max Jitter external for OpenNI middleware
Shell of it was imspired by the jit.simple example from the MaxSDK and
the MaxSDK documentation


Initially written and tested using:
- Windows 7 64-bit Service Pack 1
- Microsoft Visual C++ 2010 Express Version 10.0.30319.1 RTMRel
- Hotfix for Microsoft Visual C++ 2010 Express - ENU (KB2455033)   KB2455033
- OpenNI 1.1.0.39 for Win32
- PrimeSense NITE 1.3.1.4 for Win32
- PrimeSense Sensor KinectMod 5.0.1.32 for Win32
- Max/MSP/Jitter 5.1.8 for Windows

Build notes-----------
- You will need to change the build's include and library directories to match
  the locations in the Max SDK and OpenNI SDK.

v0.7.3---------
- Added attribute output_scene_floor which defaults to 0 (false). This controls the /floor data being output for each bang.
- Added attribute scene_floor which contains the same scene floor values as would be output with the /floor message. Remember that
  this attribute can be queried using standard Max messages like "getscene_floor" and its results will be output via dumpout outlet

v0.7.2---------
- Added floor location "/floor" from any configured scene analyzer. This is output from the "OSC" outlet in the configured skeleton_value_type.
  Values are a list of 6 floats: first 3 are the X, Y, Z coordinates for a point on the place, the second 3 are the X, Y, Z of a normal vector
- Through casual observation, PrimeSense's NITE scene generator at first generates all zeros, but later generates reasonably
  good values. The floor point's X value is always 0.0. Z appears to stablize at 349.18811 and the remaining values change based on your physical setup.
- I do support skeleton_value_type and its conversions of these floor values. Warning, anything but skeleton_value_type=0 can generates point x, y, z values
  which are offscreen or beyond the [0...1] normalization. This is by design.
- Added new attribute depth_fov which contains the field of view (horizontal and vertical, in that order) of the depth generator in radians. Remember that
  this attribute can be queried using standard Max messages like "getdepth_fov" and its results will be output via dumpout outlet

v0.7.1---------
- performance improvement: no new OpenNI data -> don't get and transform old data
- minor refactoring and perf changes in main matrix calc loop

v0.7.0---------
- removed the osceleton_legacy_raw and replaced it with the skeleton_value_type attribute
- skeleton_value_type: 0 (default)=OpenNI native values, 1=OpenNI projective coordinates, 2=OSCeleton legacy "normalized" values

v0.6.9---------
- added user center of mass output "/user" on the skeleton outlet; completes OSCeleton emulation + exposes the data to the native output formats
- known issue: OpenNI center of mass values "/user" are unreliable and it is difficult to detect when they are unreliable; /user_exit and /user_reenter can assist but are also unreliable
- added attribute osceleton_legacy_raw to determine output value ranges when attribute skeleton_format=2 (aka legacy OSCeleton output)
- For osceleton_legacy_raw: 0 (default)=OSCeleton legacy "normalized" values, 1=OpenNI (aka Kinect) raw values same as -xr switch on OSCeleton
= fixed output bug introduced in private build v0.6.7 that only appeared if you were tracking 2 or more skeletons

v0.6.7---------
- added skeleton_format attribute to support output in 0=native jit.openni OSC, 1=max route-able message format, or 2=OSCeleton default format (with raw kinect values)

v0.6.6---------
- updated codebase to support OpenNI v1.3.2.3 and its deprecated APIs
- cleanup of some user, pose, calibration event handling
- added support for reloading XML config files on same jit.openni object
- known issue: repeated reloading config file with USER node will eventually cause a crash

v0.6.5---------
- added 5 attributes which enable (default) or not the output for a given outlet; allows for decreasing resource utilization
- corrected ordering of joint orientation output...I think...

v0.6.4---------
- no longer log error if send a bang before XML config was successfully loaded
- fixed crashing bug introduced in v0.6.3 that only occurred if Kinect was unplugged and you tried to load an XML config file

v0.6.3---------
- output success or failure of read message via dumpout

v0.6.2---------
- now limit the possible values of jit.openni's custom attributes to valid values
- minor bug fixes, logic optimizations, performance tweak

v0.6.1---------
- fixed ordering of outlets, dumpout is now on the far right
- updated OSC address pattern format for skeleton joint output to start with "/skel/"
- added functions in jitter object to register for jit.openni events (e.g. calibration start/end, new users)
- now output openni events (e.g. calibration start/end, new users)
- updated jit.openni_test1.maxpat to demonstrate using the OSC output with OSC-route from http://cnmat.berkeley.edu/downloads

v0.6.0---------
- outputs user skeleton data using OSC format (do not yet output user, pose, or calibration events via OSC)
- added attributes to filter by confidence, optional output of joint orientation, smoothing of skeleton

v0.5.0---------
- outputs user pixel maps which show the pixels for recognized users on an output map; value=0 indicated no user, other values are the user's ID
- refactoring to start accommodating generators which have multiple capabilities
- much groundwork to support skeletons
- changed max assist text approach
- switched to Max memory (de)allocation functions

v0.4.2---------
- matrix data copy operations now run in parallel using the Jitter parallel utility module

v0.4.1---------
- fixed several bugs in matrix_calc related to previously not updating the metadata for frames
- fixed the bug regarding alternate viewpoint bad resizing behavior of depthmap
- fixed the crashing bug that previously occurred when changing output matrix attributes
- fixed bug with unseen symptom -> now unlock all jitter matrices correctly

v0.4.0---------
- supports rgb, depth, and ir camera output
- now support more flexible matrix output formats for all generators
- supports up to 3 generators outputting matrices all configured from your XML file
- updated Win32 binary Max Jitter external

v0.3.0---------
- now fully supports output of RGB and depth maps
- added in a compiled Win32 binary Max Jitter external
- depth maps can be output in long, float32, or float64
- imagemap and depthmaps may work in many resolutions and formats, but is seldom tested in anything but 640x480.
- All valid modes (resolutions, fps, etc.) reported from SensorKinect driver do not actually work. For example, only 640x480x30 works for depth.
- when using SensorKinect driver, if you configure an alternate viewpoint in XML, the depthmap exhibits occasionally resizing

v0.2.0---------
Now supports updating generators when the object receives a bang. A good use of
the current functionality is defining an image, depth, and recording generator.
A sample XML config file is included. Sending bangs will then create a .ONI
recording file.

v0.1.0---------
Initial functionality. Able to read in an XML configuration file and initialize
the OpenNI system based on it. Includes debugging output which lists available
resolutions, depths, etc.