xn::UserGenerator Class Reference
C++ Reference to Application Programmer Interface (API) » Production Nodes Functionality

`#include <XnCppWrapper.h>`

Inheritance diagram for xn::UserGenerator:
[legend]

## Public Types

typedef void(* | UserHandler) (UserGenerator &generator, XnUserID user, void *pCookie)

## Public Member Functions

| UserGenerator (XnNodeHandle hNode=NULL)
| UserGenerator (const NodeWrapper &other)
XnStatus | Create (Context &context, Query *pQuery=NULL, EnumerationErrors *pErrors=NULL)
XnUInt16 | GetNumberOfUsers () const
XnStatus | GetUsers (XnUserID aUsers[], XnUInt16 &nUsers) const
XnStatus | GetCoM (XnUserID user, XnPoint3D &com) const
XnStatus | GetUserPixels (XnUserID user, SceneMetaData &smd) const
XnStatus | RegisterUserCallbacks (UserHandler NewUserCB, UserHandler LostUserCB, void *pCookie, XnCallbackHandle &hCallback)
void | UnregisterUserCallbacks (XnCallbackHandle hCallback)
const SkeletonCapability | GetSkeletonCap () const
SkeletonCapability | GetSkeletonCap ()
const PoseDetectionCapability | GetPoseDetectionCap () const
PoseDetectionCapability | GetPoseDetectionCap ()
XnStatus | RegisterToUserExit (UserHandler handler, void *pCookie, XnCallbackHandle &hCallback)
void | UnregisterFromUserExit (XnCallbackHandle hCallback)
XnStatus | RegisterToUserReEnter (UserHandler handler, void *pCookie, XnCallbackHandle &hCallback)
void | UnregisterFromUserReEnter (XnCallbackHandle hCallback)
Public Member Functions inherited from xn::Generator
| Generator (XnNodeHandle hNode=NULL)
| Generator (const NodeWrapper &other)
XnStatus | StartGenerating ()
XnBool | IsGenerating () const
XnStatus | StopGenerating ()
XnStatus | RegisterToGenerationRunningChange (StateChangedHandler handler, void *pCookie, XnCallbackHandle &hCallback)
void | UnregisterFromGenerationRunningChange (XnCallbackHandle hCallback)
XnStatus | RegisterToNewDataAvailable (StateChangedHandler handler, void *pCookie, XnCallbackHandle &hCallback)
void | UnregisterFromNewDataAvailable (XnCallbackHandle hCallback)
XnBool | IsNewDataAvailable (XnUInt64 *pnTimestamp=NULL) const
XnStatus | WaitAndUpdateData ()
XnBool | IsDataNew () const
const void * | GetData ()
XnUInt32 | GetDataSize () const
XnUInt64 | GetTimestamp () const
XnUInt32 | GetFrameID () const
const MirrorCapability | GetMirrorCap () const
MirrorCapability | GetMirrorCap ()
const AlternativeViewPointCapability | GetAlternativeViewPointCap () const
AlternativeViewPointCapability | GetAlternativeViewPointCap ()
const FrameSyncCapability | GetFrameSyncCap () const
FrameSyncCapability | GetFrameSyncCap ()
Public Member Functions inherited from xn::ProductionNode
| ProductionNode (XnNodeHandle hNode=NULL)
| ProductionNode (const NodeWrapper &other)
NodeInfo | GetInfo () const
XnStatus | AddNeededNode (ProductionNode &needed)
XnStatus | RemoveNeededNode (ProductionNode &needed)
void | GetContext (Context &context) const
Context | GetContext () const
XnBool | IsCapabilitySupported (const XnChar *strCapabilityName) const
XnStatus | SetIntProperty (const XnChar *strName, XnUInt64 nValue)
XnStatus | SetRealProperty (const XnChar *strName, XnDouble dValue)
XnStatus | SetStringProperty (const XnChar *strName, const XnChar *strValue)
XnStatus | SetGeneralProperty (const XnChar *strName, XnUInt32 nBufferSize, const void *pBuffer)
XnStatus | GetIntProperty (const XnChar *strName, XnUInt64 &nValue) const
XnStatus | GetRealProperty (const XnChar *strName, XnDouble &dValue) const
XnStatus | GetStringProperty (const XnChar *strName, XnChar *csValue, XnUInt32 nBufSize) const
XnStatus | GetGeneralProperty (const XnChar *strName, XnUInt32 nBufferSize, void *pBuffer) const
XnStatus | LockForChanges (XnLockHandle *phLock)
void | UnlockForChanges (XnLockHandle hLock)
XnStatus | LockedNodeStartChanges (XnLockHandle hLock)
void | LockedNodeEndChanges (XnLockHandle hLock)
const ErrorStateCapability | GetErrorStateCap () const
ErrorStateCapability | GetErrorStateCap ()
GeneralIntCapability | GetGeneralIntCap (const XnChar *strCapability)
Public Member Functions inherited from xn::NodeWrapper
| NodeWrapper (XnNodeHandle hNode)
| NodeWrapper (const NodeWrapper &other)
NodeWrapper & | operator= (const NodeWrapper &other)
| ~NodeWrapper ()
| operator XnNodeHandle () const
XnNodeHandle | GetHandle () const
XnBool | operator== (const NodeWrapper &other)
XnBool | operator!= (const NodeWrapper &other)
XnBool | IsValid () const
const XnChar * | GetName () const
XnStatus | AddRef ()
void | Release ()
void | SetHandle (XnNodeHandle hNode)
void | TakeOwnership (XnNodeHandle hNode)

## Detailed Description

Purpose: The UserGenerator node generates data describing users that it recognizes in the scene, identifying each user individually and thus allowing actions to be done on specific users.

Usage: Instantiate the class and call Create() to create a user generator node.

Data output:

- CoM from UserGenerator local data
- User pixels from SceneMetaData

Capabilities:

- SkeletonCapability
- PoseDetectionCapability

Remarks:

The UserGenerator node provides access to the recognized users through user IDs it returns. The user IDs are unique user identification numbers. The application uses these user IDs to pass them to various methods of this node to access the specific data of the specified user. For example:

xn::UserGenerator::GetUserPixels() gets the pixel map of a specific user, and xn::UserGenerator::GetCoM() gets the location of the center of mass of a specific user.

Typically, an application will require only a single UserGenerator node. However, there are cases where more than one UserGenerator node could be required. For example, where there are two sensors it may be convenient to build a production graph with two UserGenerator nodes, one node for each depth output.

Main Features:

- User CoM: Provides the location of the center of mass of a specific user.
- Number of users: Provides the number of users currently detected in the scene.
- Users list: Provides a list of the IDs of currently recognized users in the scene.
- User pixels: Provides the pixels that represent a specific user.
- Events: Provides events about users in the scene:
  - A new user is identified ('New User')
  - An existing user exits temporarily ('User Exit')
  - An exited user returns ('User Reenter')
  - An existing user exits permanently ('Lost User')

Note
  Registering to the 'New User' and 'Lost User' events is done by calling RegisterUserCallbacks(). Registering to the 'User Exit' and 'User Reenter' events is done by calling RegisterToUserExit() and RegisterToUserReEnter().

# Events

New User' event

Signals that a new user has now been recognized in the scene. A new user is a user that was not previously recognized in the scene, and is now recognized in the scene.

'Lost User' event

Signals that a user has been lost from the list of previously recognized users in the scene.

The exact meaning of a lost user is decided by the developer of the user generator. However, a typical implementation would define that a lost user is a previously recognized user that then exits the scene and does not return, even after a 'Lost User' timeout has elapsed. Thus this event is raised only after some delay after the user actually exited the scene.

Using the above approach, the difference then between the 'Lost User' event and the 'User Exit' event (see below) would be that the 'User Exit' event is raised every time a recognized user leaves the scene, but a 'Lost User' event is raised only after the user has remained absent ("exit-ed") for a certain timeout period of time.

If no timeout is used at all, the 'User Exit' and 'User Reenter' events are redundant.

'User Exit' event

Signals that a user now exited from the scene.

The exact meaning of a user that exited is decided by the developer of the user generator. However, a typical implementation would define that a user that exited the scene is a previously recognized user that then leaves the scene. but returns within a specified time, before the 'Lost User' timeout has elapsed. In such a case the UserGenerator object still remembers the user and so when the user comes back, everything known about it is restored. See the 'Lost User' event above for more explanation of the difference between the 'User Exit' event and the 'Lost User' event in a typical implementation.

'User Reenter' event

Signals that a user has now reentered to the scene after exiting. A user that reenters the scene after exiting is a recognized user that exited, but now is returning within a specified permitted time span, before the 'Lost User' timeout has elapsed. In such a case the UserGenerator node still remembers the user and so when the user returns, everything known about it is restored.

Event Sequence

The following event sequences are typical:

A:

1. 'New User'
2. 'User Exit'
3. 'Lost User'

B:

1. 'New User'
2. 'User Exit'
3. 'User Reenter'
4. 'User Exit'
5. 'Lost User'

## Member Typedef Documentation

## UserHandler

typedef void(* xn::UserGenerator::UserHandler) (UserGenerator &generator, XnUserID user, void *pCookie)

Event handler signature for all UserGenerator events.

Example of a handler prototype (for the 'New User' event in this case):

void XN_CALLBACK_TYPE OnNewUser(xn::UserGenerator& generator, XnUserID nId, void* pCookie)
XnUserID
XnUInt32 XnUserID
Definition XnTypes.h:546
xn::UserGenerator
Definition XnCppWrapper.h:7666

Parameters

  [in] | generator | UserGenerator node that raised the event.
  [in] | user | ID of the user.
  [in] | pCookie | User's cookie, to be delivered to the callback.

## Constructor & Destructor Documentation

## UserGenerator() [1/2]

xn::UserGenerator::UserGenerator | ( | XnNodeHandle | hNode = NULL | ) |

inline

Ctor

Parameters

  [in] | hNode | Node handle

## UserGenerator() [2/2]

xn::UserGenerator::UserGenerator | ( | const NodeWrapper & | other | ) |

inline

## Member Function Documentation

## Create()

XnStatus xn::UserGenerator::Create | ( | Context & | context,
|  | Query * | pQuery = NULL,
|  | EnumerationErrors * | pErrors = NULL )

inline

Creates a UserGenerator node from available production node alternatives.

Remarks:

See create_method for a detailed description of this method.

## GetCoM()

XnStatus xn::UserGenerator::GetCoM | ( | XnUserID | user,
|  | XnPoint3D & | com ) const

inline

Gets the position of a user's center of mass. This is the single point for representing the user.

Parameters

  [in] | user | Specifies a user ID.
  [out] | com | The user's center of mass in 3-D coordinates.

The center of mass is a useful point to represent the user. When you don't have any other reference point (e.g., you don't have the position of a specific joint, or of the head, or any other such point), this is an adequate point with which to start to represent the user.

Remarks:

The returned XnPoint3D value is the center of mass of all the shown pixels that belong to that user, but not necessarily the real center of mass of the human user. The application can use this method to request the center of mass for each user.

## GetNumberOfUsers()

XnUInt16 xn::UserGenerator::GetNumberOfUsers | ( |  | ) | const

inline

Gets the number of users currently identified in the scene.

Remarks:

The result of this method is required as input for the GetUsers() method.

## GetPoseDetectionCap() [1/2]

PoseDetectionCapability xn::UserGenerator::GetPoseDetectionCap | ( |  | ) |

inline

Gets a xn::PoseDetectionCapability object for accessing Pose Detection functionality.

Remarks:

It is the application responsibility to check first if XN_CAPABILITY_POSE_DETECTION is supported by calling xn::ProductionNode::IsCapabilitySupported().

## GetPoseDetectionCap() [2/2]

const PoseDetectionCapability xn::UserGenerator::GetPoseDetectionCap | ( |  | ) | const

inline

Gets a xn::PoseDetectionCapability object for accessing Pose Detection functionality.

Remarks:

It is the application responsibility to check first if XN_CAPABILITY_POSE_DETECTION is supported by calling xn::ProductionNode::IsCapabilitySupported().

## GetSkeletonCap() [1/2]

SkeletonCapability xn::UserGenerator::GetSkeletonCap | ( |  | ) |

inline

Gets a SkeletonCapability object for accessing Skeleton functionality.

Remarks:

Once the SkeletonCapability object has been obtained, the application can work with a skeleton.

It is the application's responsibility to check first if Skeleton capability is supported by calling the IsCapabilitySupported() method..

## GetSkeletonCap() [2/2]

const SkeletonCapability xn::UserGenerator::GetSkeletonCap | ( |  | ) | const

inline

Gets a SkeletonCapability object for accessing Skeleton functionality.

Remarks:

Once the SkeletonCapability object has been obtained, the application can work with a skeleton.

It is the application's responsibility to check first if Skeleton capability is supported by calling the IsCapabilitySupported() method..

## GetUserPixels()

XnStatus xn::UserGenerator::GetUserPixels | ( | XnUserID | user,
|  | SceneMetaData & | smd ) const

inline

Gets the pixel map of the specified user in the scene and saves it in the xn::SceneMetaData object. The pixels that form part of the user's body are labeled with user's ID. Other values are irrelevant.

Parameters

  [in] | user | The ID of the user the pixel map should be returned for.
  [out] | smd | Struct to be filled with the pixel map.

Remarks:

A usage example for this method in gaming is for coloring the avatar on the screen.

The special value 0 (zero) can be used in the `user` parameter, telling the generator to return a label map containing all users, where each pixel is either marked as 0 (background pixel) or with the user ID to which it belongs.

## GetUsers()

XnStatus xn::UserGenerator::GetUsers | ( | XnUserID | aUsers[],
|  | XnUInt16 & | nUsers ) const

inline

Gets an array of user IDs of all the recognized users in the scene at the current time.

Parameters

  [out] | aUsers | Preallocated memory for the method to enter the user IDs.
  [in,out] | nUsers | Number of users.

`nUsers` is used both as an in parameter and an out one in this method: [in] Size of the aUsers array (in units of users). To get the value of nUsers (i.e., the size of array that you want - see parameter below), you use the GetNumberOfUsers() method. For example, if you want an array of size 4 - to contain a maximum of 4 users - you pass 4 as the value of this parameter.

[out] On completion, the method returns the number of users that were recognized. E.g., if there is actually only one user, the output will be 1, although the caller passed a value of 4 (as above) for to allocate an array of size 4.

Remarks:

The output user IDs from this method can be used as input to the xn::UserGenerator::GetCoM() method for getting the center of mass of each user.

## RegisterToUserExit()

XnStatus xn::UserGenerator::RegisterToUserExit | ( | UserHandler | handler,
|  | void * | pCookie,
|  | XnCallbackHandle & | hCallback )

inline

Registers an event handler for the 'User Exit' event.

Parameters

  [in] | handler | Callback function to be invoked when the event is raised.
  [in] | pCookie | User's cookie, to be delivered to the callback.
  [out] | hCallback | Handle to the callback to be used for unregistering it.

For full details and usage of the parameters, see Registering to Events.

## RegisterToUserReEnter()

XnStatus xn::UserGenerator::RegisterToUserReEnter | ( | UserHandler | handler,
|  | void * | pCookie,
|  | XnCallbackHandle & | hCallback )

inline

Registers an event handler for the 'User Reenter' event.

Parameters

  [in] | handler | Callback function to be invoked when the event is raised.
  [in] | pCookie | User's cookie, to be delivered to the callback.
  [out] | hCallback | Handle to the callback to be used for unregistering it.

For full details and usage of the parameters, see Registering to Events.

## RegisterUserCallbacks()

XnStatus xn::UserGenerator::RegisterUserCallbacks | ( | UserHandler | NewUserCB,
|  | UserHandler | LostUserCB,
|  | void * | pCookie,
|  | XnCallbackHandle & | hCallback )

inline

Registers event handlers for the 'New User' and 'Lost User' events.

Parameters

  [in] | NewUserCB | Callback function to be invoked when the 'New User' event is raised.
  [in] | LostUserCB | Callback function to be invoked when the 'Lost User' event is raised.
  [in] | pCookie | User's cookie, to be delivered to the callback.
  [out] | hCallback | Handle to the callback to be used for unregistering it.

For full details and usage of the parameters, see Registering to Events.

## UnregisterFromUserExit()

void xn::UserGenerator::UnregisterFromUserExit | ( | XnCallbackHandle | hCallback | ) |

inline

Unregisters an event handler for the 'User Exit' event.

Parameters

  [in] | hCallback | Handle received from registration.

For full details and usage of the parameter, see Unregistering from Events .

## UnregisterFromUserReEnter()

void xn::UserGenerator::UnregisterFromUserReEnter | ( | XnCallbackHandle | hCallback | ) |

inline

Unregisters an event handler for the 'User Reenter' event.

Parameters

  [in] | hCallback | Handle received from registration.

For full details and usage of the parameter, see Unregistering from Events .

## UnregisterUserCallbacks()

void xn::UserGenerator::UnregisterUserCallbacks | ( | XnCallbackHandle | hCallback | ) |

inline

Unregisters event handlers for the 'New User' and 'Lost User' events.

Parameters

  [in] | hCallback | Handle received from registration.

For full details and usage of the parameter, see Unregistering from Events .

The documentation for this class was generated from the following file:

- XnCppWrapper.h