OpenNI 1.5.7
Classes | Public Types | Public Member Functions | List of all members

#include <XnCppWrapper.h>

Inheritance diagram for xn::UserGenerator:
Inheritance graph
[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)
 
NodeWrapperoperator= (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:

Capabilities:

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:

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)
XnUInt32 XnUserID
Definition: XnTypes.h:549
Definition: XnCppWrapper.h:7693
Parameters
[in]generatorUserGenerator node that raised the event.
[in]userID of the user.
[in]pCookieUser's cookie, to be delivered to the callback.

Constructor & Destructor Documentation

◆ UserGenerator() [1/2]

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

Ctor

Parameters
[in]hNodeNode 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]userSpecifies a user ID.
[out]comThe 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]userThe ID of the user the pixel map should be returned for.
[out]smdStruct 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]aUsersPreallocated memory for the method to enter the user IDs.
[in,out]nUsersNumber 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]handlerCallback function to be invoked when the event is raised.
[in]pCookieUser's cookie, to be delivered to the callback.
[out]hCallbackHandle 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]handlerCallback function to be invoked when the event is raised.
[in]pCookieUser's cookie, to be delivered to the callback.
[out]hCallbackHandle 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]NewUserCBCallback function to be invoked when the 'New User' event is raised.
[in]LostUserCBCallback function to be invoked when the 'Lost User' event is raised.
[in]pCookieUser's cookie, to be delivered to the callback.
[out]hCallbackHandle 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]hCallbackHandle 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]hCallbackHandle 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]hCallbackHandle 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: