include/mv_face_detection_internal.h

   1 /*
   2  * Copyright (c) 2023 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_MEDIAVISION_FACE_DETECT_INTERNAL_H__
  18 #define __TIZEN_MEDIAVISION_FACE_DETECT_INTERNAL_H__
  19
  20 #include <mv_common.h>
  21 #include <mv_face_detection_type.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 /**
  28  * @file   mv_face_detection.h
  29  * @internal
  30  * @brief  This file contains the Inference based Media Vision API.
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_MEDIA_VISION_INFERENCE_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @internal
  40  * @brief Creates a inference handle for face detection object.
  41  * @details Use this function to create a inference handle. After the creation
  42  *          the face detection task has to be prepared with
  43  *          mv_face_detection_prepare() function to prepare a network
  44  *          for the inference.
  45  *
  46  * @since_tizen 8.0
  47  *
  48  * @remarks The @a infer should be released using mv_face_detection_destroy().
  49  *
  50  * @param[out] handle    The handle to the inference to be created.
  51  *
  52  * @return @c 0 on success, otherwise a negative error value
  53  * @retval #MEDIA_VISION_ERROR_NONE Successful
  54  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
  55  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
  56  * @retval #MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory
  57  *
  58  * @see mv_face_detection_destroy()
  59  * @see mv_face_detection_prepare()
  60  */
  61 int mv_face_detection_create(mv_face_detection_h *handle);
  62
  63 /**
  64  * @internal
  65  * @brief Destroys inference handle and releases all its resources.
  66  *
  67  * @since_tizen 8.0
  68  *
  69  * @param[in] handle    The handle to the inference to be destroyed.
  70  *
  71  * @return @c 0 on success, otherwise a negative error value
  72  * @retval #MEDIA_VISION_ERROR_NONE Successful
  73  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
  74  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
  75  *
  76  * @pre Create inference handle by using mv_face_detection_create()
  77  *
  78  * @see mv_face_detection_create()
  79  */
  80 int mv_face_detection_destroy(mv_face_detection_h handle);
  81
  82 /**
  83  * @internal
  84  * @brief Sets user-given model information.
  85  * @details Use this function to change the model information instead of default one after calling @ref mv_face_detection_create().
  86  *
  87  * @since_tizen 8.0
  88  *
  89  * @param[in] handle        The handle to the face detection object.
  90  * @param[in] model_name    Model name.
  91  * @param[in] model_file    Model file name.
  92  * @param[in] meta_file     Model meta file name.
  93  * @param[in] label_file    Label file name.
  94  *
  95  * @return @c 0 on success, otherwise a negative error value
  96  * @retval #MEDIA_VISION_ERROR_NONE Successful
  97  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
  98  * @retval #MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation
  99  *
 100  * @pre Create a face detection handle by calling @ref mv_face_detection_create()
 101  */
 102 int mv_face_detection_set_model(mv_face_detection_h handle, const char *model_name, const char *model_file,
 103                                                                 const char *meta_file, const char *label_file);
 104
 105 /**
 106  * @internal
 107  * @brief Configures the backend for the face detection inference.
 108  *
 109  * @since_tizen 8.0
 110  *
 111  * @param [in] handle         The handle to the inference
 112  *
 113  * @return @c 0 on success, otherwise a negative error value
 114  * @retval #MEDIA_VISION_ERROR_NONE Successful
 115  * @retval #MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory
 116  * @retval #MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation
 117  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
 118  */
 119 int mv_face_detection_configure(mv_face_detection_h handle);
 120
 121 /**
 122  * @internal
 123  * @brief Prepares the face detection inference
 124  * @details Use this function to prepare the face detection inference based on
 125  *          the configured network.
 126  *
 127  * @since_tizen 8.0
 128  *
 129  * @param[in] handle         The handle to the inference.
 130  *
 131  * @return @c 0 on success, otherwise a negative error value
 132  * @retval #MEDIA_VISION_ERROR_NONE Successful
 133  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
 134  * @retval #MEDIA_VISION_ERROR_PERMISSION_DENIED Permission denied
 135  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 136  * @retval #MEDIA_VISION_ERROR_INVALID_DATA Invalid model data
 137  * @retval #MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory
 138  * @retval #MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation
 139  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Not supported format
 140  */
 141 int mv_face_detection_prepare(mv_face_detection_h handle);
 142
 143 /**
 144  * @internal
 145  * @brief Performs the face detection inference on the @a source.
 146  *
 147  * @since_tizen 8.0
 148  * @remarks This function is synchronous and may take considerable time to run.
 149  *
 150  * @param[in] handle          The handle to the inference
 151  * @param[in] source         The handle to the source of the media
 152  *
 153  * @return @c 0 on success, otherwise a negative error value
 154  * @retval #MEDIA_VISION_ERROR_NONE Successful
 155  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
 156  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 157  * @retval #MEDIA_VISION_ERROR_INTERNAL          Internal error
 158  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Source colorspace
 159  *                                                  isn't supported
 160  *
 161  * @pre Create a source handle by calling mv_create_source()
 162  * @pre Create an inference handle by calling mv_face_detect_create()
 163  * @pre Prepare an inference by calling mv_face_detect_configure()
 164  * @pre Prepare an inference by calling mv_face_detect_prepare()
 165  */
 166 int mv_face_detection_inference(mv_face_detection_h handle, mv_source_h source);
 167
 168 /**
 169  * @internal
 170  * @brief Performs asynchronously the face detection inference on the @a source.
 171  *
 172  * @since_tizen 7.5
 173  * @remarks This function operates asynchronously, so it returns immediately upon invocation.
 174   *         Therefore, user needs to receive the result though a given callback function.
 175  *
 176  * @param[in] handle         The handle to the inference
 177  * @param[in] source         The handle to the source of the media
 178  * @param[in] completion_cb  A callback which is called internally by the framework
 179  *                           once the given inference request is completed.
 180  * @param[in] user_data      A pointer to user data object.
 181  *
 182  * @return @c 0 on success, otherwise a negative error value
 183  * @retval #MEDIA_VISION_ERROR_NONE Successful
 184  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
 185  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 186  * @retval #MEDIA_VISION_ERROR_INTERNAL          Internal error
 187  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Source colorspace
 188  *                                                  isn't supported
 189  *
 190  * @pre Create a source handle by calling mv_create_source()
 191  * @pre Create an inference handle by calling mv_face_detect_create()
 192  * @pre Prepare an inference by calling mv_face_detect_configure()
 193  * @pre Prepare an inference by calling mv_face_detect_prepare()
 194  */
 195 int mv_face_detection_inference_async(mv_face_detection_h handle, mv_source_h source, mv_completion_cb completion_cb,
 196                                                                           void *user_data);
 197
 198 /**
 199  * @internal
 200  * @brief Gets the face detection inference result on the @a source.
 201  *
 202  * @since_tizen 8.0
 203  *
 204  * @param[in] handle               The handle to the inference
 205  * @param[out] number_of_objects  A number of objects detected.
 206  * @param[out] indices            Label indices to detected objects.
 207  * @param[out] confidences        Probability to detected objects.
 208  * @param[out] left               An left position array to bound boxes.
 209  * @param[out] top                An top position array to bound boxes.
 210  * @param[out] right              An right position array to bound boxes.
 211  * @param[out] bottom             An bottom position array to bound boxes.
 212  *
 213  * @return @c 0 on success, otherwise a negative error value
 214  * @retval #MEDIA_VISION_ERROR_NONE Successful
 215  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
 216  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 217  * @retval #MEDIA_VISION_ERROR_INTERNAL          Internal error
 218  *
 219  * @pre Create a source handle by calling mv_create_source()
 220  * @pre Create an inference handle by calling mv_face_detect_create()
 221  * @pre Prepare an inference by calling mv_face_detect_configure()
 222  * @pre Prepare an inference by calling mv_face_detect_prepare()
 223  * @pre Prepare an inference by calling mv_face_detect_inference()
 224  */
 225 int mv_face_detection_get_result(mv_face_detection_h handle, unsigned int *number_of_objects,
 226                                                                  const unsigned int **indices, const float **confidences, const int **left,
 227                                                                  const int **top, const int **right, const int **bottom);
 228
 229 /**
 230  * @internal
 231  * @brief Gets the label string to a given index.
 232  *
 233  * @since_tizen 8.0
 234  *
 235  * @param[in] handle       The handle to the inference
 236  * @param[in] index       Label index to get the label string.
 237  * @param[out] label  Label string to a given index.
 238  *
 239  * @return @c 0 on success, otherwise a negative error value
 240  * @retval #MEDIA_VISION_ERROR_NONE Successful
 241  * @retval #MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
 242  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 243  * @retval #MEDIA_VISION_ERROR_INTERNAL          Internal error
 244  *
 245  * @pre Create a source handle by calling mv_create_source()
 246  * @pre Create an inference handle by calling mv_face_detect_create()
 247  * @pre Prepare an inference by calling mv_face_detect_configure()
 248  * @pre Prepare an inference by calling mv_face_detect_prepare()
 249  * @pre Prepare an inference by calling mv_face_detect_inference()
 250  */
 251 int mv_face_detection_get_label(mv_face_detection_h handle, const unsigned int index, const char **label);
 252
 253 /**
 254  * @internal
 255  * @brief Sets user-given inference engine and device types for inference.
 256  * @details Use this function to change the inference engine and device types for inference instead of default ones after calling @ref mv_face_detection_create().
 257  *
 258  * @since_tizen 8.0
 259  *
 260  * @param[in] handle        The handle to the face detection object.
 261  * @param[in] engine_type  A string of inference engine type.
 262  * @param[in] device_type   A string of device type.
 263  *
 264  * @return @c 0 on success, otherwise a negative error value
 265  * @retval #MEDIA_VISION_ERROR_NONE Successful
 266  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 267  * @retval #MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation
 268  *
 269  * @pre Create a face detection handle by calling @ref mv_face_detection_create()
 270  */
 271 int mv_face_detection_set_engine(mv_face_detection_h handle, const char *engine_type, const char *device_type);
 272
 273 /**
 274  * @internal
 275  * @brief Gets a number of inference engines available for face detection task API.
 276  * @details Use this function to get how many inference engines are supported for face detection after calling @ref mv_face_detection_create().
 277  *
 278  * @since_tizen 8.0
 279  *
 280  * @param[in] handle         The handle to the face detection object.
 281  * @param[out] engine_count  A number of inference engines available for face detection API.
 282  *
 283  * @return @c 0 on success, otherwise a negative error value
 284  * @retval #MEDIA_VISION_ERROR_NONE Successful
 285  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 286  * @retval #MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation
 287  *
 288  * @pre Create a face detection handle by calling @ref mv_face_detection_create()
 289  */
 290 int mv_face_detection_get_engine_count(mv_face_detection_h handle, unsigned int *engine_count);
 291
 292 /**
 293  * @internal
 294  * @brief Gets engine type to a given inference engine index.
 295  * @details Use this function to get inference engine type with a given engine index after calling @ref mv_face_detection_get_engine_count().
 296  *
 297  * @since_tizen 8.0
 298  *
 299  * @param[in] handle        The handle to the face detection object.
 300  * @param[in] engine_index  A inference engine index for getting the inference engine type.
 301  * @param[out] engine_type  A string to inference engine.
 302  *
 303  * @return @c 0 on success, otherwise a negative error value
 304  * @retval #MEDIA_VISION_ERROR_NONE Successful
 305  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 306  * @retval #MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation
 307  *
 308  * @pre Get a number of inference engines available for face detection task API by calling @ref mv_face_detection_get_engine_count()
 309  */
 310 int mv_face_detection_get_engine_type(mv_face_detection_h handle, const unsigned int engine_index, char **engine_type);
 311
 312 /**
 313  * @internal
 314  * @brief Gets a number of device types available to a given inference engine.
 315  * @details Use this function to get how many device types are supported for a given inference engine after calling @ref mv_face_detection_create().
 316  *
 317  * @since_tizen 8.0
 318  *
 319  * @param[in] handle         The handle to the face detection object.
 320  * @param[in] engine_type    A inference engine string.
 321  * @param[out] device_count  A number of device types available for a given inference engine.
 322  *
 323  * @return @c 0 on success, otherwise a negative error value
 324  * @retval #MEDIA_VISION_ERROR_NONE Successful
 325  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 326  * @retval #MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation
 327  *
 328  * @pre Create a face detection handle by calling @ref mv_face_detection_create()
 329  */
 330 int mv_face_detection_get_device_count(mv_face_detection_h handle, const char *engine_type, unsigned int *device_count);
 331
 332 /**
 333  * @internal
 334  * @brief Gets device type list available.
 335  * @details Use this function to get what device types are supported for current inference engine type after calling @ref mv_face_detection_configure().
 336  *
 337  * @since_tizen 8.0
 338  *
 339  * @param[in] handle         The handle to the face detection object.
 340  * @param[in] engine_type    A inference engine string.
 341  * @param[in] device_index   A device index for getting the device type.
 342  * @param[out] device_type   A string to device type.
 343  *
 344  * @return @c 0 on success, otherwise a negative error value
 345  * @retval #MEDIA_VISION_ERROR_NONE Successful
 346  * @retval #MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter
 347  * @retval #MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation
 348  *
 349  * @pre Create a face detection handle by calling @ref mv_face_detection_create()
 350  * @pre Configure face detection task by calling @ref mv_face_detection_configure()
 351  */
 352 int mv_face_detection_get_device_type(mv_face_detection_h handle, const char *engine_type,
 353                                                                           const unsigned int device_index, char **device_type);
 354 /**
 355  * @}
 356  */
 357 #ifdef __cplusplus
 358 }
 359 #endif /* __cplusplus */
 360
 361 #endif /* __TIZEN_MEDIAVISION_FACE_DETECT_INTERNAL_H__ */