mv_machine_learning: update description

[Issue type] cleanup

Updated header and doc file description for face recognition CAPI,
which just reflects the feedback from API REVIEW step.

Change-Id: Id17eef55aafbd6a4c077b712fa5e8fe2a279f729
Signed-off-by: Inki Dae <inki.dae@samsung.com>

diff --git a/doc/mediavision_doc.h b/doc/mediavision_doc.h
index 7691efd251a30159c44f96ab5a8e23e3d4977f67..4678ceb0a053e915d9cb138e9f24b1620b2d0767 100644 (file)
--- a/doc/mediavision_doc.h
+++ b/doc/mediavision_doc.h
@@ -28,7 +28,8 @@
  * * Surveillance: movement detection, person appearance/disappearance,
  *   person recognition.
  * * Inference: Image classification, object detection,
- *   face detection and facial landmark detection;\n
+ *   face detection, facial landmark detection and face recognition;\n
+ * * Training: Face recognition;\n
  *
  *
  * @defgroup    CAPI_MEDIA_VISION_COMMON_MODULE Media Vision Common
@@ -411,6 +412,61 @@
  * mv_inference_facial_landmark_detect() functionalities to detect faces and their landmark
  * on #mv_source_h, and callbacks mv_inference_face_detected_cb() and
  * mv_inference_facial_landmark_detected_cb() to process detection results.
+ *
+ * @defgroup    CAPI_MEDIA_VISION_FACE_RECOGNITION_MODULE Media Vision Face Recognition
+ * @ingroup     CAPI_MEDIA_VISION_MODULE
+ * @brief Face recognition.
+ * @section CAPI_MEDIA_VISION_FACE_RECOGNITION_MODULE_HEADER Required Header
+ *      \#include <mv_face_recognition.h>
+ *
+ * @section CAPI_MEDIA_VISION_FACE_RECOGNITION_MODULE_FEATURE Related Features
+ * This API is related with the following features:\n
+ *  - %http://tizen.org/feature/vision.face_recognition\n
+ *
+ * It is recommended to design feature related codes in your application for
+ * reliability.\n
+ * You can check if a device supports the related features for this API by using
+ * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of
+ * your application.\n
+ * To ensure your application is only running on the device with specific
+ * features, please define the features in your manifest file using the manifest
+ * editor in the SDK.\n
+ * More details on featuring your application can be found from
+ * <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element">
+ *   <b>Feature Element</b>.
+ * </a>
+ *
+ * @section CAPI_MEDIA_VISION_FACE_RECOGNITION_MODULE_OVERVIEW Overview
+ * @ref CAPI_MEDIA_VISION_FACE_RECOGNITION_MODULE contains mv_face_recognition_register() function
+ * to train a face on #mv_source_h, and mv_face_recognition_unregister() function to remote
+ * all face data related to a given label. Also it contains mv_face_recognition_inference() function
+ * which performs face recognition a face on #mv_source_h. User can get a proper label string through
+ * mv_face_recognition_get_label() function after calling mv_face_recognition_inference() function
+ * as a recognized result.
+ *
+ * A training example
+ * First of all, a face recognition handle should be created by mv_face_recognition_create() function
+ * and destroyed with mv_face_recognition_destroy() function, and some resources - such as backbone model to extract
+ * feature vector and loading the label/feature vector database files - should be prepared with
+ * mv_face_recognition_prepare() function, and then a given face image and its label string should be registered
+ * with mv_face_recognition_register() function.
+ *
+ * A inference example
+ * First of all, a face recognition handle should be created by mv_face_recognition_create() function
+ * and destroyed with mv_face_recognition_destroy() function, and some resources - such as backbone model to extract
+ * feature vector and loading the label/feature vector database files - should be prepared with
+ * mv_face_recognition_prepare() function, and mv_face_recognition_inference() function should be called
+ * to request the training to face recognition framework of Mediavision, and then mv_face_recognition_get_label()
+ * function should be called to get a label as a recognized result.
+ *
+ * A label removing example
+ * First of all, a face recognition handle should be created by mv_face_recognition_create() function
+ * and destroyed with mv_face_recognition_destroy() function, and some resources - such as backbone model to extract
+ * feature vector and loading the label/feature vector database files - should be prepared with
+ * mv_face_recognition_prepare() function, and mv_face_recognition_unregister() function should be called
+ * to delete face data to a given label string.
+ *
+ * For more details, please refer to test/testsuites/machine_learning/face_recognition/test_face_recognition.cpp
  */
 
 #endif  /* __TIZEN_MEDIAVISION_DOC_H__ */

diff --git a/include/mv_face_recognition.h b/include/mv_face_recognition.h
index 9cece8953b1d7337a7d4c3fadb6c0dc70ec3b6e7..233c9ac626efbce70ae521dd31215bdec787b665 100644 (file)
--- a/include/mv_face_recognition.h
+++ b/include/mv_face_recognition.h
@@ -170,6 +170,8 @@ int mv_face_recognition_inference(mv_face_recognition_h handle, mv_source_h sour
  *
  * @since_tizen 7.0
  *
+ * @remarks The @a out_label must NOT be released using free()
+ *
  * @param[in] handle         The handle to the face recognition object.
  * @param[out] out_label     The array pointer for the label name to be stored.
  *                           This function returns memory pointer containing actual label string to @a out_label.