/****************************************************************************
	jit.openni
	Copyright (C) 2011, 2012 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; Max is a Cycling74 product

Downloads at http://hidale.com/jit-openni/#download
Full install and usage documentation at https://github.com/diablodale/jit.openni/wiki

Windows casually tested using:
- Windows 7 64-bit Service Pack 1 (modern Win32 compatible OSs should also work)
- OpenNI 1.5.4.0 for Win32
- PrimeSense NITE 1.5.2.21 for Win32
- PrimeSense Sensor KinectMod v0.93 for Win32 (based on 5.1.2.1)
- Cycling 74 Max 6.0.7 for Windows http://cycling74.com

Windows additional requirements for compiling jit.openni:
- Microsoft Visual C++ 2010 Express Version 10.0.40219.1 SP1Rel
- Hotfix for Microsoft Visual C++ 2010 Express - KB2635973, KB2542054
- OpenNI 1.5.4.0 development install for Win32
- PrimeSense NITE 1.5.2.21 development install for Win32
- Cycling 74 Max SDK 6.0.4 for Windows http://cycling74.com

Mac OSx casually tested using:
- OSx 10.8.2, 10.7.2, and 10.6.8
- Cycling 74 Max 6.0.7 for OSx http://cycling74.com
- libusb-1.0.9
- OpenNI 1.5.4.0 for OSx
- PrimeSense NITE 1.5.2.21 for OSx
- PrimeSense Sensor KinectMod v0.93 for OSx (based on 5.1.2.1)

Mac OSx install notes:
- run and install the libusb-1.0.9 package
- download and expand OpenNI
- sudo ./install.sh
- download and expand NITE
- sudo ./install.sh
- download and expand SensorKinect
- sudo ./install.sh

Mac OSx additional requirements for compiling jit.openni:
- XCode (4.5.2 on OSx 10.8.2) or (3.2.6 on OSx 10.6.8)
  the compiler command line tools must also be installed
- http://www.macports.org/install.php
  use the package installer method for your specific OSx
- sudo port install libtool
- sudo port install libusb +universal
- Cycling 74 Max SDK 6.0.4 for OSx http://cycling74.com


Build notes-----------
- You will need to change the build's include and library directories to match
  the locations of your Max SDK and OpenNI SDK.
- With Microsoft Visual Studio, set a system environment variable C74SUPPORT to
  your Max SDK support directory. With XCode on Mac OSx, update the custom build
  setting called C74SUPPORT. Edit these settings so their value is the directory
  that is the c74support directory that is within in the Max SDK. As a check,
  the 3 children of this needed directory are the three: jit-includes, max-includes,
  msp-includes.

v0.8.8 removed use of an undocumented Max API
- minor change to remove use of an undocumented Max API
- removed some extraneous debug messages

v0.8.7 fix for issue# 10: orientation data not useful
- no longer output joints if a generator doesn't support them
- added call to stop all generators before releasing production nodes

v0.8.6 yet another fix for XML config file loading
- split method Win/OSx to resolve locaton of XML file
- unifed API call to OpenNI for XML config file loading

v0.8.5 split XML file loading methods Win/OSx
- split the XML file loading methods Win <-> Mac OSx
- removed some unneed nodes in the config XML file
- changed dllmain.c to dllmain.cpp while attempting to capture OpenNI log
- removed some unneeded compiler/linker options

v0.8.4 fixed null-terminated string missing on XML path
- fixed bug where pathname of XML file was missing
  terminating null
- re-indented the XML config file

v0.8.3 fixed corrupt XML file issue due to <licenses> tag
- removed <licenses> tag from both XML config files, added warning
- updated some debug output
- updated install steps

v0.8.2
- first working OSx port, needs testing to verify all features work
- reformatted the current directory call for OSx compatibility

v0.8.1
- switched method for loading XML configuration file to aid in OSx compatibility
- minor debug macro usage/output changes

v0.8.0
- can now cross-compile Win and OSx
- included Visual Studio and XCode project files
- cleaned up/unified debug output statements

v0.7.9-------
- tweaks for Osx compiling
- added a debug config XML that uses the skeletonrec.oni available
  at http://openni.org downloads

v0.7.8-------
- small changes for Osx cross-compiling
- added some debugging output
- issing warnings if being compiled under C++
- unifying use of booleans

v0.7.7-------
- increased warning level of VS compiler, excluded some warnings
- minor changes to reduce harmless VS compiler warnings
- renamed dllmain.cpp -> dllmain.c
- fixed version retrieval

v0.7.6-------
- Osx compatibility changes now merged, it should now compile on Osx

v0.7.5-------
- added distmeter attribute and code to support
- refactoring to support new attribute
- OpenNI and NITE versions used for compile/test show in Max window
- removed error forcing specific OpenNI version
- condensed and commented out many debug outputs
- changed most debug output to be to console rather than max window
- removed Scene generator from XML file due to OpenNI dup creation issue
- updated demo patch for new attribute

v0.7.4---------
- Added attribute to expose the version number of OpenNI and of the jit.openni object itself
- Added functionality so that jit.openni checks the installed version of OpenNI for the minimum required version
- Removed Scene node from the XML config file due to the errant behavior of newer
  versions of OpenNI/NITE automatically creating a Scene node
- minor refactoring in preparation to later support other skeleton profiles than today's XN_SKEL_PROFILE_ALL

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.