 |
OpenNI 1.5.4
|
#include <XnCppWrapper.h>
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:
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:
- 'New User'
- 'User Exit'
- 'Lost User'
B:
- 'New User'
- 'User Exit'
- 'User Reenter'
- 'User Exit'
- 'Lost User'
Member Typedef Documentation
| 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)
- 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
| xn::UserGenerator::UserGenerator | ( | XnNodeHandle | hNode = NULL | ) | [inline] |
Ctor
- Parameters:
-
[in] hNode Node handle
| xn::UserGenerator::UserGenerator | ( | const NodeWrapper & | other | ) | [inline] |
Member Function Documentation
| XnStatus xn::UserGenerator::Create | ( | Context & | context, |
| Query * | pQuery = NULL, |
||
| EnumerationErrors * | pErrors = NULL |
||
| ) | [inline] |
Creates a UserGenerator node from available production node alternatives.
Remarks:
See Understanding the Create() method for a detailed description of this method.
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.
| 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.
| 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().
| 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().
| 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..
| 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..
| 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.
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.
| 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.
| 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.
| 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.
| 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 .
| 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 .
| 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:
Generated on Wed May 16 2012 10:16:07 for OpenNI 1.5.4 by
1.7.5.1