OpenNI 1.5.2


OpenNI delivers with some samples. All samples are placed under the 'Samples' folder, and their binaries can be found under 'Samples\Bin\Debug' or 'Samples\Bin\Release'. Most samples use an XML file to configure OpenNI. This file can be found at '%OPEN_NI_INSTALL_DIR%\Data\SamplesConfig.xml'. All samples, except for NiCRead, are written using the C++ interface.

Here is a short description of each sample:


NiSimpleRead is very basic. It configures OpenNI using the SamplesConfig XML file, and then takes the depth generator node (it assumes there is one. If not, the sample will exit with an error). It then loops, reading new frames from the depth generator, and prints out the depth value of the middle pixel. The sample exists when the user presses 'ESC'.


NiSimpleCreate is an example of creating a production node programmatically in code, rather than using the SamplesConfig XML file. After creating a depth node, it reads from it like NiSimpleRead does.


NiCRead sample is exactly the same as NiSimpleRead, except for the fact it demonstrates the use of the C interface (instead of the C++ one).


NiSimpleViewer is a small OpenGL application which draws the depth maps and the image maps to the screen. It configures OpenNI using the SamplesConfig XML, but requires both depth and image to be present, both with the same resolution, and image node at RGB24 format. The application creates a histogram of the depth map and draws the frame using it to allow better visibility of the depth map.

The following keys can be used to control the application:

Key Description
1 Converts to OVERLAY mode, drawing depth map on top of the image map. It also sets depth view point to image view point (using the Alternative view point capability).
2 Draws only depth. It also turns off alternative view point.
3 Draws only image. It also turns off alternative view point.
Esc Closes the application


NiSampleModule is a sample for writing a module for OpenNI. It implements a depth node supporting the Mirror capability. Before using it, one should register this module using the niReg utility. It should also be deregistered afterwards, or applications might get it when needing depth nodes.


NiConvertXToONI opens any recording, takes every node in this recording, and records it to a new ONI recording. It receives both input file and output file from the command line.


NiRecordSynthetic shows how to open a recording, perform some sort of transformation on the data in it, and re-record this data.


NiViewer aspires to be able to view any kind of data defined by OpenNI, and be able to configure any kind of configuration OpenNI defines. Currently, is supports a reduced set. It can now display depth, image and IR maps, play audio, and supplies a wide set of configuration (though not complete). NiViewer has two modes: If passed a file name in command-line, it will open this file as a recording. Otherwise, it will configure OpenNI using the SamplesConfig XML file.

NiViewer is automatically associated with the .ONI file extension, for opening OpenNI recordings. The following keys can be used to control the application:

Key Description
1 Showing depth only, in histogram mode
2 Showing depth only, in psychedelic mode (centimeters)
3 Showing depth only, in psychedelic mode (millimeters)
4 Showing depth only, in rainbow mode
5 Showing depth masked image, meaning image pixels that don't have depth values are blacked out.
6 Background removal mode
7 Showing depth and image (or IR), side by side.
8 Showing depth on top of image (or IR)
9 Showing transparent depth on top of image (or IR)
0 Showing rainbow depth on top of image (or IR)
= Showing image (or IR) only
` Showing depth standard deviation
p Toggling pointer mode on/off. When on, additional depth info is displayed regarding currently pointed pixel.
f Toggling Full Screen / Window mode
? Toggling help screen on/off
m Toggling mirror on/off
/ Resets all croppings
s Start recording
d Start recording in 5 seconds
x Stop recording
c Capture current frame to files
z Start/Stop collecting statistics about depth pixels
o Pause/Play
l Seek one frame forward (recordings only)
L Seek 10 frames forward (recordings only)
k Seek one frame backwards (recordings only)
K Seek 10 frames backwards (recordings only)
; Read one single frame and pause
Esc Closes the application

In addition, the mouse can be used. Clicking the right-button of the mouse opens up a menu through which many configurations can be changed. Block selecting using the left button (holding it down in one point, moving and releasing the key) over a frame causes cropping of the node, if the Cropping capability is supported.


niBackRecorder is a command line tool, which stores frames in memory in a cyclic buffer, and when requested (clicking 'd') dumps that cyclic buffer to an oni file. In effect, it saves the last x seconds (configurable).


niBackRecorder time <seconds> [depth [qvga|vga]] [image [qvga|vga]] [verbose] [mirror <on|off>] [registration] [framesync] [outdir <directory>]

The following options are mandatory:

  • time Number of seconds to dump each time.

The following options can be used:

  • depth Sets the resolution of the depth, to either QVGA or VGA. If not mentioned, depth is off. If no resolution is mentioned, QVGA is used.
  • image Sets the resolution of the image, to either QVGA or VGA. If not mentioned, image is off. If no resolution is mentioned, QVGA is used.
  • verbose Turns on the log
  • mirror Set the mirror mode. If not mentioned, uses whatever was configured.
  • registration Change depth to match image.
  • framesync Syncronize between depth and image
  • outdir Where to create the oni files. Default is the execution directory.

Note: Keep in mind the memory used to store the frames.

Configuration Size
1 second, QVGA depth 30*320*240*2B = 4500KB
1 second, QVGA image 30*320*240*3B = 6750KB
1 second, VGA depth 30*640*480*2B = 18000KB
1 second, VGA image 30*640*480*3B = 27000KB