/* 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. * *

* Initialize the internal state of the HTLib and create a handle used * to further compute the scene and skeleton tracking data. *

* \param[in] cparameters the camera parameters. * \param[in] htparameters tracking parameters. * \param[in] allocator allocator callbacks used to allocate/deallocate CPU/GPU memory. * Currently not used: initialize the allocator callbacks to nullptr. * \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. *

* 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 humanTracking_getSkeletons() will not necessarly return the * tracking data for the current frame. *

* \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 humanTracking_init() * \param[in] frame the current input frame from the camera device * \param[in] hints the array of expected poses * * \return an error status: * * * \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 isActive flag of the HT_Skeleton struct to false. * The labelId 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. *

* The function will return the last available skeleton tracking data. Please check the timestamp * field in the HT_Skeleton structure in order to match the tracking data with a certain input frame. * \see humanTracking_compute() for further details *

* * \remark The skeleton data memory is managed internally by the HumanTracking library. * * \param[in] handle the HTLib handle returned by humanTracking_init(). * \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: * * * \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. *

* 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: * *

* * \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. *

* * \param[in] handle the HTLib handle returned by humanTracking_init(). * \param[out] labelImage the label image pointer. * * \return an error status: * * * \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 humanTracking_init(). * * \return an error status: * * * \remark This function is not thread safe */ HT_DLL_API HT_ErrorType HT_SDK_CDECL humanTracking_release (HT_Handle handle); /** * \brief Get scene status. *

* 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). *

* * \param[in] handle the HTLib handle returned by humanTracking_init(). * \param[out] sceneStatus the scene status information. * * \return an error status: * * * \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. *

* Allow to reset all or a specific layer of the human tracking library: * *

*

* * \param[in] handle the HTLib handle returned by humanTracking_init(). * \param[in] layer enumeration describing the specific layer to reset. * * \return an error status: * * * \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 nullptr 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