Skip to content

Home

Jump to bottom
Dale Phurrough edited this page Feb 11, 2016 · 88 revisions

dp.kinect exposes the functionality of the Microsoft Kinect for Windows v1 sensor to the Max patching environment. Below you will find the system requirements, setup guide, and reference documentation.

Strongly recommended sources of additional learning and documentation include

  • Max tutorials. This core knowledge on sending messages and manipulating Jitter matricies is essential. You can find the tutorials under the Help menu in Max.
  • Microsoft Kinect programming guide. This guide teaches you about the coordinate system for the Kinect, depth maps and their range, skeletal tracking, facial recognition, and much more.
  • The demo patch included with dp.kinect. This demo patch demonstrates simple and quick usage of dp.kinect. You can also find advanced usage in the subpatch.

###Setup Guide#

  1. Install Windows 7 or newer. Windows 8.1 or Windows 10 (64-bit) is recommended.
  2. Install Cycling74 Max 6.x (32 or 64-bit) or newer. Max 5.1.9 has only been casually tested
  3. Install the Kinect for Windows v1 Runtime.
    Runtime v1.5.2 is the oldest version supported. Some features of dp.kinect will be unavailable.
    Runtime v1.7 has received the most testing.
    Runtime v1.8 may work better on some Windows 10 computers.
  4. Plug your Kinect for Windows v1 sensor into a USB 2.0 port. Please do not plug any other USB devices into the same USB 2.0 controller because the Microsoft Kinect drivers need a lot of bandwidth.
  5. Download dp.kinect from http://hidale.com/shop/dp-kinect/#download. Open the ZIP archive.
  6. Place all files from this ZIP archive into a common directory.
  7. To use (optional) face tracking...
    Download the face tracking data ZIP file. Open the ZIP archive.
    Place the FaceTrackData.dll from this ZIP archive into the same directory as the dp.kinect external.
    For a 64-bit setup, that means dp.kinect.mxe64 and FaceTrackData.dll will be in the same folder.
  8. Next, you must register dp.kinect.

###Register dp.kinect#

  1. Open the dp.kinect patch from the ZIP archive.
  2. If you want a 14-day trial test period for dp.kinect, you can use the registration name "trial" without the quotes and the trial.dpreg registration key from the ZIP archive. If you purchased a license for dp.kinect, please use the registration name and key you were provided.
  3. Register dp.kinect by entering your registration name in the top text box, clicking the register button, and choosing your registration key file. 3 Steps to Register

###Major Features#

  • Image and depth sensor output in several formats, sizes, extended ranges, etc.
  • User/player identification, location, and occlusion
  • Skeleton joint tracking with orientations
  • Face tracking
  • Speech recognition and sound position location
  • Data available in native Max route format or OSC
  • Multiple Kinects supported simultaneously
  • Near mode, seated mode, IR emitter, and color camera control supported on Kinect for Windows sensors
  • Data filtering, smoothing, rotation to gravity, synchronization
  • Accelerometer readings and tilt motor control
  • Two levels of error messages to aid in debugging
  • Output is compatible with the output of jit.openni to aid in migration

###Terms of Use, Licensing, Conditions, and Warranty# dp.kinect terms of use, licensing, conditions, and warranty are at http://hidale.com/terms/. Separately, Microsoft enforces their Kinect licensing terms by changes in functionality. Part of this topic is discussed at http://msdn.microsoft.com/en-us/library/hh855358.aspx

###Recent Changes# v1.06 added forward compat @face2dpoints=2, added mm output for face translation
v1.05 fixed registration issue that occurred on some active directory computers
v1.04 added some verbose debug output
v1.03 fixed face 2d points output and crash on close bug
v1.02 YUV more compatible with Max's studio swing (previously output full swing)
v1.00 improved YUV alignment

###Compatibility with jit.openni##

  • Output of dp.kinect is compatible with jit.openni yet faster, more stable, and more accurate
  • One exception regarding output is that the optional joint orientation/rotation data is different than in jit.openni. Please see the below documentation for details.
  • The attribute names to control features have changed. This is intentional. You will often find an equivalent attribute.
  • Caution: Installing the official Microsoft Kinect runtime/drivers and the SensorKinect driver for OpenNI v1.x is not supported.

###Known Issues, Limitations, Report Problems#

  • The Kinect v1 hardware does not support simultaneous color and IR streams; the hardware is bandwidth limited
  • The 3D coordinates for facetracking are not rotated by gravity or elevation of the Kinect. This feature will be added in a future release.
  • When you create a dp.kinect object in Max, it is possible you receive an error message saying you are missing the Microsoft Visual C++ 2012 Runtime. If you do receive this error, easily download and install the needed package from http://www.microsoft.com/en-us/download/details.aspx?id=30679
  • If you experience bugs or failures with dp.kinect, please research past issues at https://github.com/diablodale/dp.kinect/issues. If you still do not find a solution to your issue, please open a new issue.

##Reference Documentation# ###Messages Supported# bang Causes the Kinect to be queried for any updated data with optional waiting/blocking. After this, matrices and message-based data are output from the outlets as configured using the attributes.

open Initializes and opens a connection to a specific Kinect. If only one Kinect is attached to the computer and no @idkinect has been set, then dp.kinect defaults to the only attached Kinect. Success/failure is reported at dumpout.

read Is supported primarily for compatibility with jit.openni. No XML file is read. Instead, the message is accepted and a result generated to allow for easier migration. Otherwise, its functionality is the same as open.

close Closes the connection to the currently open Kinect

getusbidlist Returns a list of symbols representing unique USB ID's for all Kinects attached to the computer on dumpout. This ID is not specific to a Kinect. Instead, it is specific to the USB connection to a Kinect. If you move a Kinect to a different USB port, you will get a different ID for that Kinect. If you swap identical Kinects on the same USB port, you will likely get the same ID. Be aware of this when you are planning and testing complex installations with multiple Kinects. Use one of these symbols to set the @idkinect attribute of a given dp.kinect. Below is an example when two Kinects are connected to the computer.

getusbidlist      <-- sent to the inlet
usbidlist USB\VID_0409&PID_005A\5&332C30EE&0&1 USB\VID_0409&PID_005A\6&355ABBF1&0&2      <-- received from the dumpout outlet

pixeltoskel Takes a series of three numbers representing a depth pixel (x column, y row, z depth value) from a depthmap and transforms it into a real world (skeleton space) x, y, z coordinates. The behavior of this message is affected by the values of @distmeter and @flipx. An example:

pixeltoskel 110 85 2.4    <-- sent to the inlet
pixeltoskel -0.42012 0.294084 2.4    <-- received from the outlet

resetcolor Resets all the color camera image settings to their defaults.

This object also supports the normal compliment of Max/Jitter messages to set/query attributes, get a summary via dumpout, etc. Its dumpout output will follow standard conventions through use of standard Max/Jitter APIs.

###Special Dumpout Messages# Some messages are automatically generated and output simultaneously from the dumpout outlets of all dp.kinects created in Max.

newkinect Indicates that a new Kinect was plugged into the computer. It will be followed by two symbols. The first symbol is the USB ID for the new Kinect plugged in. The second symbol is a pseudo-unique identifier for the Kinect hardware and should not be used. This is an example message received after a Kinect was plugged into a computer:

newkinect USB\VID_0409&PID_005A\5&332C30EE&0&1 USB\VID_045E&PID_02AE\A00363A06509053A

lostkinect Indicates that a Kinect was unplugged, lost, or unable to fully initialize. It will be followed by a symbol representing the USB ID for the Kinect in question. You will often have an error message in your Max window providing further details. This is an example message received after a Kinect was unplugged from a computer.

lostkinect USB\VID_0409&PID_005A\5&332C30EE&0&2

###Attributes# Attributes are now documented on their own page.

###Depth, Color, IR, Playermap, Point Cloud# Depthmap, color image, infrared image, playermap, and point cloud data (all matrix-based) are now documented on their own page.

###Skeleton Position, Joints, Face tracking, Sound Info, Speech Recognition, and Other Data# User position, skeleton joints, face tracking, sound information, speech recognition, floor identification, and all other message-based data of this nature are now documented on their own page.

###Standalone Application and Collectives You can create standalone applications and collectives with dp.kinect. In the Build Collective/Application dialog, click "Include file..." and choose the dp.kinectsupport_xx.dll for your 32 or 64-bit application. If you are using face features, you will need to additionally include the matching FaceTrackData.dll. If you create a standalone application, it may be possible to copy these two files into the support subfolder instead of including them with the Build dialog box.

Please remember that your license for dp.kinect is only for one computer. You or your customers will need to purchase additional licenses for each computer on which your standalone or collective runs.

Clone this wiki locally