237 lines
9.8 KiB
C
237 lines
9.8 KiB
C
/* COPYRIGHT AND CONFIDENTIALITY NOTICE
|
|
* SONY DEPTHSENSING SOLUTIONS CONFIDENTIAL INFORMATION
|
|
*
|
|
* All rights reserved to Sony Depthsensing Solutions SA/NV, a
|
|
* company incorporated and existing under the laws of Belgium, with
|
|
* its principal place of business at Boulevard de la Plainelaan 11,
|
|
* 1050 Brussels (Belgium), registered with the Crossroads bank for
|
|
* enterprises under company number 0811 784 189
|
|
*
|
|
* This file is part of the HumanTracking SDK, which is proprietary
|
|
* and confidential information of Sony Depthsensing Solutions SA/NV.
|
|
*
|
|
* Copyright (c) 2002-2019 Sony Depthsensing Solutions SA/NV
|
|
*/
|
|
|
|
/**
|
|
* \file HumanTrackingCAPI.h
|
|
* \brief Declaration of the Human Tracking Library API
|
|
*/
|
|
|
|
#ifndef HUMAN_TRACKING_CAPI_H
|
|
#define HUMAN_TRACKING_CAPI_H
|
|
|
|
#include "HumanTrackingPlatform.h"
|
|
#include "HumanTrackingCTypes.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif // __cplusplus
|
|
|
|
/**
|
|
* \defgroup HTapi Human Tracking Library API functions
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* \brief Initialize the Human Tracking Library.
|
|
*
|
|
* <p>
|
|
* Initialize the internal state of the HTLib and create a handle used
|
|
* to further compute the scene and skeleton tracking data.
|
|
* </p>
|
|
* \param[in] cparameters the camera parameters.
|
|
* \param[in] htparameters tracking parameters.
|
|
* \param[in] allocator allocator callbacks used to allocate/deallocate CPU/GPU memory.
|
|
* <b>Currently not used: initialize the allocator callbacks to nullptr.</b>
|
|
* \param[in] threadingPolicy the threading policy specifications for the HTLib pipeline.
|
|
* \param[out] handle HTLib handle.
|
|
*
|
|
* \return an error status:
|
|
* + \c HT_NO_ERROR no errors occurred
|
|
* + \c HT_INVALID_CAMERA_PARAM_POINTER null camera parameters pointer
|
|
* + \c HT_INVALID_HT_PARAM_POINTER null ht parameters pointer
|
|
* + \c HT_INVALID_ALLOCATOR_POINTER null allocator pointer
|
|
* + \c HT_NULL_ROOT_DATA_PATH null root data path
|
|
* + \c HT_INVALID_ROOT_DATA_DIRECTORY invalid root data path directory
|
|
* + \c HT_INVALID_MAX_USERS invalid number of max users
|
|
* + \c HT_CLASSIFICATION_DATA_NOT_FOUND classification data was not found
|
|
* + \c HT_INVALID_CAMERA_PARAMS_COLOR_CHANNEL_COUNT invalid color channel count for ARGB image
|
|
* + \c HT_INVALID_CAMERA_PARAMS_COLOR_RESOLUTION invalid color image resolution
|
|
* + \c HT_INVALID_CAMERA_PARAMS_DEPTH_RESOLUTION invalid depth resolution
|
|
* + \c HT_INVALID_CAMERA_PARAMS_FIELD_OF_VIEW invalid field of view
|
|
* + \c HT_INVALID_THREAD_POLICY invalid threading policy
|
|
*
|
|
* \remark The allocator feature is disabled.
|
|
*
|
|
* \remark This function is not thread safe
|
|
*/
|
|
HT_DLL_API HT_ErrorType HT_SDK_CDECL humanTracking_init (HT_CameraParameters* cparameters, HT_Parameters* htparameters,
|
|
HT_Allocator* allocator, HT_ThreadingPolicy* threadingPolicy, HT_Handle* handle);
|
|
|
|
|
|
/**
|
|
* \brief Start computation of the scene and skeleton data.
|
|
* <p>
|
|
* This represent the first stage in the HTLib pipeline and it will trigger the tracking process.
|
|
* The function returns after the first stage of the pipeline has completely finished processing.
|
|
* The function call is non-blocking in respect to the final tracking result for the current frame, meaning
|
|
* that a subsequent call to <code>humanTracking_getSkeletons()</code> will not necessarly return the
|
|
* tracking data for the current frame.
|
|
* </p>
|
|
* \note If the same frame is passed multiple times to this function, it will be ignored and
|
|
* the function will return immediately.
|
|
*
|
|
* \param[in] handle the HTLib handle returned by <code>humanTracking_init()</code>
|
|
* \param[in] frame the current input frame from the camera device
|
|
* \param[in] hints the array of expected poses
|
|
*
|
|
* \return an error status:
|
|
* <ul><li> \c HT_NO_ERROR - no errors occurred </li>
|
|
* <li> \c HT_INVALID_HANDLE - null HTLib handle </li>
|
|
* <li> \c HT_INVALID_FRAME_POINTER - null frame data pointer </li></ul>
|
|
*
|
|
* \remark The last parameter is a pointer to a skeleton pose structure used as a hint for the current
|
|
* frame tracking in order to improve the accuracy of the final skeleton pose for this frame;
|
|
* if provided as a null pointer it will have no impact on the computations. To disable the hint
|
|
* per user basis, put the <code>isActive</code> flag of the <code>HT_Skeleton</code> struct to false.
|
|
* The <code>labelId</code> is not used.
|
|
*
|
|
* \remark This function is not thread safe
|
|
*/
|
|
HT_DLL_API HT_ErrorType HT_SDK_CDECL humanTracking_compute (HT_Handle handle, HT_Frame* frame, HT_Skeleton* hints = NULL);
|
|
|
|
/**
|
|
* \brief Get the skeleton(s) joints data.
|
|
* <p>
|
|
* The function will return the last available skeleton tracking data. Please check the <code>timestamp</code>
|
|
* field in the <code>HT_Skeleton</code> structure in order to match the tracking data with a certain input frame.
|
|
* \see humanTracking_compute() for further details
|
|
* </p>
|
|
*
|
|
* \remark The skeleton data memory is managed internally by the HumanTracking library.
|
|
*
|
|
* \param[in] handle the HTLib handle returned by <code>humanTracking_init()</code>.
|
|
* \param[out] skeletons the array of skeleton joints data.
|
|
* \param[out] countSkeleton the number of skeleton joints results in the array.
|
|
*
|
|
* \return an error status:
|
|
* <ul><li> \c HT_NO_ERROR - no errors occurred </li>
|
|
* <li> \c HT_INVALID_HANDLE - null HTLib handle </li>
|
|
* <li> \c HT_INVALID_SKELETON_POINTER - null skeleton data pointer </li></ul>
|
|
*
|
|
* \remark This function is thread safe
|
|
*/
|
|
HT_DLL_API HT_ErrorType HT_SDK_CDECL humanTracking_getSkeletons (HT_Handle handle, HT_Skeleton** skeletons, int* countSkeleton);
|
|
|
|
/**
|
|
* \brief Get the scene label image.
|
|
* <p>
|
|
* The scene label image is a 2D image having the same resolution as the depth image.
|
|
* Each pixel is assigned a 16-bit value with one of the following meanings:
|
|
*
|
|
* <ul><li> \c 0 represents the invalid pixel label.</li>
|
|
* <li> \c 1 -> \c 10 represent the user labels.</li>
|
|
* <li> \c 11 represents the floor label.</li>
|
|
* <li> \c 12 -> \c 255 represent the scene objects labels (detected as non-human).</li></ul>
|
|
*
|
|
* \note The scene layer of the Human Tracking Library disseminates up to 10 users in
|
|
* the scene but only a maximum of 4 will be tracked by the tracking layer.
|
|
* </p>
|
|
*
|
|
* \param[in] handle the HTLib handle returned by <code>humanTracking_init()</code>.
|
|
* \param[out] labelImage the label image pointer.
|
|
*
|
|
* \return an error status:
|
|
* <ul><li> \c HT_NO_ERROR - no errors occurred </li>
|
|
* <li> \c HT_INVALID_HANDLE - null HTLib handle </li>
|
|
* <li> \c HT_INVALID_LABELIMAGE_POINTER - null label image pointer </li></ul>
|
|
*
|
|
* \remark The label image memory is managed internally by the HumanTracking library.
|
|
*
|
|
* \remark This function is thread safe
|
|
*/
|
|
HT_DLL_API HT_ErrorType HT_SDK_CDECL humanTracking_getLabelImage (HT_Handle handle, HT_Image16* labelImage);
|
|
|
|
/**
|
|
* \brief Release the Human Tracking Library handle.
|
|
*
|
|
* \param[in] handle the HTLib handle returned by <code>humanTracking_init()</code>.
|
|
*
|
|
* \return an error status:
|
|
* <ul><li> \c HT_NO_ERROR - no errors occurred </li>
|
|
* <li> \c HT_INVALID_HANDLE - null HTLib handle </li></ul>
|
|
*
|
|
* \remark This function is not thread safe
|
|
*/
|
|
HT_DLL_API HT_ErrorType HT_SDK_CDECL humanTracking_release (HT_Handle handle);
|
|
|
|
|
|
/**
|
|
* \brief Get scene status.
|
|
* <p>
|
|
* Scene status contains useful information regarding camera positioning, etc.
|
|
* It can be used to request to the user to change the environment in order to have a
|
|
* better skeleton tracking system(e.g. change camera tilt).
|
|
* </p>
|
|
*
|
|
* \param[in] handle the HTLib handle returned by <code>humanTracking_init()</code>.
|
|
* \param[out] sceneStatus the scene status information.
|
|
*
|
|
* \return an error status:
|
|
* <ul><li> \c HT_NO_ERROR - no errors occurred </li>
|
|
* <li> \c HT_INVALID_HANDLE - null HTLib handle </li>
|
|
* <li> \c HT_INVALID_SCENESTATUS_POINTER - null scene status structure pointer </li></ul>
|
|
*
|
|
* \remark The scene status structure memory is managed internally by the HumanTracking library.
|
|
*
|
|
* \remark This function is thread safe
|
|
*/
|
|
HT_DLL_API HT_ErrorType HT_SDK_CDECL humanTracking_getSceneStatus (HT_Handle handle, HT_SceneStatus* sceneStatus);
|
|
|
|
|
|
/**
|
|
* \brief Reset the Human Tracking Library.
|
|
* <p>
|
|
* Allow to reset all or a specific layer of the human tracking library:
|
|
*
|
|
* <ul><li> All : reset all the internal layers (background learning,calibration,scene,users and skeletons) </li>
|
|
* <li> Scene : reset all the scene (background learning,objects and users tracking) </li>
|
|
* <li> Users : reset the users (users,users color signatures and skeletons) </li></ul>
|
|
* </p>
|
|
*
|
|
* \param[in] handle the HTLib handle returned by <code>humanTracking_init()</code>.
|
|
* \param[in] layer enumeration describing the specific layer to reset.
|
|
*
|
|
* \return an error status:
|
|
* <ul><li> \c HT_NO_ERROR - no errors occurred </li>
|
|
* <li> \c HT_INVALID_HANDLE - null HTLib handle </li>
|
|
* <li> \c HT_INVALID_RESET_LAYER - invalid value for reset layer </li></ul>
|
|
*
|
|
* \remark This function is not thread safe.
|
|
*/
|
|
HT_DLL_API HT_ErrorType HT_SDK_CDECL humanTracking_reset (HT_Handle handle, HT_Layer layer);
|
|
|
|
/** @} */ // end group HTapi
|
|
|
|
/*************************************************************************
|
|
* Errors management *
|
|
*************************************************************************/
|
|
|
|
/**
|
|
* \ingroup HTError
|
|
* \brief Get the error message associated to the error type provided as input.
|
|
*
|
|
* \param[in] errorType the error type returned by any of the Human Tracking Library API functions.
|
|
*
|
|
* \return error description message or <code>nullptr</code> if the input error type is invalid.
|
|
*
|
|
* \remark This function is thread safe
|
|
*/
|
|
HT_DLL_API const char * HT_SDK_CDECL humanTracking_getErrorMessage (HT_ErrorType errorType);
|
|
|
|
#ifdef __cplusplus
|
|
} // extern C
|
|
#endif // __cplusplus
|
|
|
|
#endif // HUMAN_TRACKING_CAPI_H
|