Max Jitter external for OpenNI middleware, supports Kinect, Windows and Mac OSx
Switch branches/tags
Pull request Compare This branch is 5 commits behind diablodale:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


	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
    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 <>.

jit.openni - a Max Jitter external for OpenNI middleware

Downloads at
Full install and usage documentation at

Windows casually tested using:
- Windows 7 64-bit Service Pack 1 (modern Win32 compatible OSs should also work)
- OpenNI for Win32
- PrimeSense NITE for Win32
- PrimeSense Sensor KinectMod v0.93 for Win32 (based on
- Max 6.0.7 for Windows

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 development install for Win32
- PrimeSense NITE development install for Win32
- Max SDK 6.0.4 for Windows

Mac OSx casually tested using:
- OSx 10.8.2, 10.7.2, and 10.6.8
- Max 6.0.7 for OSx
- libusb-1.0.9
- OpenNI for OSx
- PrimeSense NITE for OSx
- PrimeSense Sensor KinectMod v0.93 for OSx (based on

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

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
  use the package installer method for your specific OSx
- sudo port install libtool
- sudo port install libusb +universal
- Max SDK 6.0.4 for OSx

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,

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

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

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

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

- tweaks for Osx compiling
- added a debug config XML that uses the skeletonrec.oni available
  at downloads

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

- 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

- Osx compatibility changes now merged, it should now compile on Osx

- 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

- 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

- 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

- 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

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

- 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

- 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

- 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)

- 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

- 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...

- 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

- output success or failure of read message via dumpout

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

- 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

- 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

- 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

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

- 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

- 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

- 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

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.

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.