OpenNI Migration Guide

OPENNI MIGRATION GUIDE

OpenNI/NiTE 2Migration GuideTransitioning from OpenNI/NiTE 1.5 to

OpenNI/NiTE 2Document Version 1.0March 2013

Disclaimer and Proprietary Information Notice

The information contained in this document is subject to change without notice and does not

represent

a commitment by PrimeSense Ltd. PrimeSense Ltd.

and its subsidiaries make no warranty of any kind with regard to this material,

including, but not limited to implied warranties of merchantability

expenses, of any nature or kind, which are incurred in connection with the

furnishing, performance or use of this material.

This document contains proprietary information, which is protected by U.S. and international

copyright laws.

All rights reserved. No part of this document may be reproduced, photocopied or translated into

another language

without the prior written consent of PrimeSense Ltd.

License Notice

OpenNI is written and distributed under the Apache License, which means that its source code is

freely-distributed and available to the general public.

Trademarks

PrimeSense, the PrimeSense logo, Natural Interaction, OpenNI, and NiTE are trademarks and

registered trademarks of PrimeSense Ltd. Other brands and their products are trademarks or

registered trademarks of their respective holders and should be noted as such.

1 Introduction

1.1 Scope

This guide is targeted at developers using OpenNI versions that came before OpenNI 2, with

particular emphasis on those developers using OpenNI1.5.2 who are interested in transitioning

1.2 Audience

The intended audience of this document is the OpenNI 1.5.x developer community interested in

moving to OpenNI 2.

1.3 Related Documentation

[1] NiTE 2 Programmerӳ Guide, PrimeSense.

1.4 Support

The first line of support for OpenNI/NiTE developers is the OpenNI.org web site. There you will

find a wealth of development resources, including ready-made sample solutions and a large and

2 Overview

2.1 New OpenNI Design Philosophy

OpenNI 2 represents a major change in the underlying design philosophy of OpenNI. A careful

analysis of the previous OpenNI API, version 1.5, revealed that it has many features that are

rarely or never used by the developer community. When designing OpenNI 2, PrimeSense has

endeavored to greatly reduce the complexity of the API. Features have been redesigned around

basic functionality that was of most interest to the developer community. Of especial

importance is that OpenNI 2 vastly simplifies the interface for communicating with depth

sensors.

2.2 Simplified Middleware Interface

OpenNI/NiTE1.5 architecture.

[5]

Guide.

PrimeSense is not aware of any third party middleware that actually made use of the provided

OpenNI plug-In interfaces. All known third party middleware simply had been built to run on top

of OpenNI. By simplifying the underlying interfaces that middleware developers are actually

using, it is hoped that third party middleware providers will find it easier to implement their

products on OpenNI.

2.3 Simplified Data Types

OpenNI 1.5 had a wide variety of complex data types. For example, depth maps were wrapped

in metadata. This made it more complicated to work with many types of data that, in their raw

form, are simply arrays. OpenNI 2 achieves the following:

double buffer all data coming in from the sensor. This had implementation issues, complexity

problems and performance problems. The data type simplification in OpenNI 2 allows for the

possibility of not needing to double buffer incoming data. However, if desired it is still possible

to double-buffer. OpenNI 2 allocates one or more user buffers and a work buffer.

2.4 Transition from Data Centric to Device Centric

The overall design of the API can now be described as device centric, rather than data centric.

The concepts of Production Nodes, Production Graphs, Generators, Capabilities, and other such

data centric concepts, have been eliminated in favor of a much simpler model that provides

simple and direct access to the underlying devices and the data they produce. The functionality

provided by OpenNI 2 is generally the same as that provided by OpenNI 1.5.2, but the

understood by learning about just four central classes:

openni::OpenNI

openni::Device

openni::VideoStream

openni::VideoFrameRef

Unfortunately, this redesign has required us to break backward compatibility with OpenNI 1.5.2.

The decision to do this was not made lightly; however, it was deemed necessary in order to

achieve the design goals of the new API.

2.6 Event Driven Depth Access