Tizen Native API
7.0
|
Face detection, recognition, and tracking.
Required Header
#include <mv_face.h>
Related Features
This API is related with the following features:
- http://tizen.org/feature/vision.face_recognition
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
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.
More details on featuring your application can be found from Feature Element.
Overview
Media Vision Face contains mv_face_detect() function to detect faces on mv_source_h, and mv_face_detected_cb() callback to process detected faces. Also it contains mv_face_recognize() function which performs face recognition on mv_source_h for recognition model mv_face_recognition_model_h handle. Results of the recognition will be passed to the mv_face_recognized_cb(). Results of the recognition consist of unique face label and confidence of the recognition model that face was recognized correctly. Unique face label is the integer identifier should be introduced to the model before starting recognition, when learning examples are added (see mv_face_recognition_model_add() function documentation for details about unique face labels).
Recognition model should be created with mv_face_recognition_model_create() and destroyed with mv_face_recognition_model_destroy(). Model can be cloned with mv_face_recognition_model_clone(), saved to the file with mv_face_recognition_model_save(), loaded with mv_face_recognition_model_load(). Model learning can be provided with mv_face_recognition_model_add(), and mv_face_recognition_model_learn() functions. These two methods has to be called in the direct order: first, labeled face examples should be added to the model using mv_face_recognition_model_add(). It is expected that images of the same face will be added specifying the same face label. When examples were added, model has to be learned based on the collected set of labeled face images. mv_face_recognition_model_learn() function will perform learning. If it is required to get the list of unique face labels learned by the model, mv_face_recognition_model_query_labels() function can be used.
Module contains function mv_face_track() which performs tracking on mv_source_h for mv_face_tracking_model_h and mv_face_tracked_cb() which process tracked face. Tracking model should be created with mv_face_tracking_model_create() and destroyed with mv_face_tracking_model_destroy(). Tracking model should be prepared with mv_face_tracking_model_prepare() before each session of tracking. Model can be cloned with mv_face_tracking_model_clone(), saved to the file with mv_face_tracking_model_save(), loaded with mv_face_tracking_model_load().
Module provides function for detecting eye-blink status - mv_face_eye_condition_recognize(), which provides detection on mv_source_h and face location - mv_rectangle_s. Callback mv_face_eye_condition_recognized_cb() handles result.
Also module contains mv_face_facial_expression_recognize() function which detects face expression on mv_source_h, face location is determined by mv_rectangle_s. Result is handled with mv_face_facial_expression_recognized_cb().
Functions | |
int | mv_face_detect (mv_source_h source, mv_engine_config_h engine_cfg, mv_face_detected_cb detected_cb, void *user_data) |
Performs face detection on the source for the engine_cfg. | |
int | mv_face_recognize (mv_source_h source, mv_face_recognition_model_h recognition_model, mv_engine_config_h engine_cfg, mv_rectangle_s *face_location, mv_face_recognized_cb recognized_cb, void *user_data) |
Performs face recognition on the source image. | |
int | mv_face_track (mv_source_h source, mv_face_tracking_model_h tracking_model, mv_engine_config_h engine_cfg, mv_face_tracked_cb tracked_cb, bool do_learn, void *user_data) |
Performs face tracking on the source for the tracking_model. | |
int | mv_face_eye_condition_recognize (mv_source_h source, mv_engine_config_h engine_cfg, mv_rectangle_s face_location, mv_face_eye_condition_recognized_cb eye_condition_recognized_cb, void *user_data) |
Determines eye-blink condition for face_location on media source. | |
int | mv_face_facial_expression_recognize (mv_source_h source, mv_engine_config_h engine_cfg, mv_rectangle_s face_location, mv_face_facial_expression_recognized_cb expression_recognized_cb, void *user_data) |
Determines facial expression for face_location on media source. | |
int | mv_face_recognition_model_create (mv_face_recognition_model_h *recognition_model) |
Creates a face recognition model handle. | |
int | mv_face_recognition_model_destroy (mv_face_recognition_model_h recognition_model) |
Destroys the face recognition model handle and releases all its resources. | |
int | mv_face_recognition_model_clone (mv_face_recognition_model_h src, mv_face_recognition_model_h *dst) |
Creates a copy of existed recognition model handle and clones all its resources. | |
int | mv_face_recognition_model_save (const char *file_name, mv_face_recognition_model_h recognition_model) |
Saves recognition model to the file. | |
int | mv_face_recognition_model_load (const char *file_name, mv_face_recognition_model_h *recognition_model) |
Loads recognition model from file. | |
int | mv_face_recognition_model_add (const mv_source_h source, mv_face_recognition_model_h recognition_model, const mv_rectangle_s *example_location, int face_label) |
Adds face image example to be used for face recognition model learning with mv_face_recognition_model_learn(). | |
int | mv_face_recognition_model_reset (mv_face_recognition_model_h recognition_model, int *face_label) |
Removes from recognition_model all collected with mv_face_recognition_model_add() function face examples labeled with face_label. | |
int | mv_face_recognition_model_learn (mv_engine_config_h engine_cfg, mv_face_recognition_model_h recognition_model) |
Learns face recognition model. | |
int | mv_face_recognition_model_query_labels (mv_face_recognition_model_h recognition_model, int **labels, unsigned int *number_of_labels) |
Queries labels list and number of labels had been learned by the model. | |
int | mv_face_tracking_model_create (mv_face_tracking_model_h *tracking_model) |
Calls this function to create a face tracking model handle. | |
int | mv_face_tracking_model_destroy (mv_face_tracking_model_h tracking_model) |
Calls this function to destroy the face tracking model handle and release all its resources. | |
int | mv_face_tracking_model_prepare (mv_face_tracking_model_h tracking_model, mv_engine_config_h engine_cfg, mv_source_h source, mv_quadrangle_s *location) |
Calls this function to initialize tracking model by the location of the face to be tracked. | |
int | mv_face_tracking_model_clone (mv_face_tracking_model_h src, mv_face_tracking_model_h *dst) |
Calls this function to make a copy of existed tracking model handle and clone all its resources to the copy. | |
int | mv_face_tracking_model_save (const char *file_name, mv_face_tracking_model_h tracking_model) |
Calls this method to save tracking model to the file. | |
int | mv_face_tracking_model_load (const char *file_name, mv_face_tracking_model_h *tracking_model) |
Calls this method to load a tracking model from file. | |
Typedefs | |
typedef void(* | mv_face_detected_cb )(mv_source_h source, mv_engine_config_h engine_cfg, mv_rectangle_s *faces_locations, int number_of_faces, void *user_data) |
Called when faces are detected for the source. | |
typedef void(* | mv_face_recognized_cb )(mv_source_h source, mv_face_recognition_model_h recognition_model, mv_engine_config_h engine_cfg, mv_rectangle_s *face_location, const int *face_label, double confidence, void *user_data) |
Called each time when face is recognized by mv_face_recognize() function. | |
typedef void(* | mv_face_tracked_cb )(mv_source_h source, mv_face_tracking_model_h tracking_model, mv_engine_config_h engine_cfg, mv_quadrangle_s *location, double confidence, void *user_data) |
Called when face determined by tracking_model is tracked. | |
typedef void(* | mv_face_eye_condition_recognized_cb )(mv_source_h source, mv_engine_config_h engine_cfg, mv_rectangle_s face_location, mv_face_eye_condition_e eye_condition, void *user_data) |
Called when eye blink condition is recognized. | |
typedef void(* | mv_face_facial_expression_recognized_cb )(mv_source_h source, mv_engine_config_h engine_cfg, mv_rectangle_s face_location, mv_face_facial_expression_e facial_expression, void *user_data) |
Called when facial expression is recognized. | |
typedef void * | mv_face_recognition_model_h |
The handle to the model aggregating recognition face features. | |
typedef void * | mv_face_tracking_model_h |
The handle to the model aggregating tracking face features. | |
Defines | |
#define | MV_FACE_DETECTION_MODEL_FILE_PATH "MV_FACE_DETECTION_MODEL_FILE_PATH" |
Defines MV_FACE_DETECTION_MODEL_FILE_PATH to set face detection haarcascade xml file attribute of the engine configuration. | |
#define | MV_FACE_RECOGNITION_MODEL_TYPE "MV_FACE_RECOGNITION_MODEL_TYPE" |
Defines MV_FACE_RECOGNITION_MODEL_TYPE to set the method used for face recognition model learning attribute of the engine configuration. | |
#define | MV_FACE_DETECTION_ROI_X "MV_FACE_DETECTION_ROI_X" |
Define MV_FACE_DETECTION_ROI_X to set X coordinate of face detection roi (Region of Interest) as attribute of the engine configuration. | |
#define | MV_FACE_DETECTION_ROI_Y "MV_FACE_DETECTION_ROI_Y" |
Define MV_FACE_DETECTION_ROI_Y to set Y coordinate of face detection roi (Region of Interest) as attribute of the engine configuration. | |
#define | MV_FACE_DETECTION_ROI_WIDTH "MV_FACE_DETECTION_ROI_WIDTH" |
Define MV_FACE_DETECTION_ROI_WIDTH to set width of face detection roi (Region of Interest) as attribute of the engine configuration. | |
#define | MV_FACE_DETECTION_ROI_HEIGHT "MV_FACE_DETECTION_ROI_HEIGHT" |
Define MV_FACE_DETECTION_ROI_HEIGHT to set height of face detection roi (Region of Interest) as attribute of the engine configuration. | |
#define | MV_FACE_DETECTION_MIN_SIZE_WIDTH "MV_FACE_DETECTION_MIN_SIZE_WIDTH" |
Define MV_FACE_DETECTION_MIN_SIZE_WIDTH to set minimum width of face which will be detected as attribute of the engine configuration. | |
#define | MV_FACE_DETECTION_MIN_SIZE_HEIGHT "MV_FACE_DETECTION_MIN_SIZE_HEIGHT" |
Define MV_FACE_DETECTION_MIN_SIZE_HEIGHT to set minimum height of face which will be detected as attribute of the engine configuration. |
Define Documentation
#define MV_FACE_DETECTION_MIN_SIZE_HEIGHT "MV_FACE_DETECTION_MIN_SIZE_HEIGHT" |
Define MV_FACE_DETECTION_MIN_SIZE_HEIGHT to set minimum height of face which will be detected as attribute of the engine configuration.
Default value is -1 (all detected faces will be applied) can be changed to specify the minimum face height
- Since :
- 3.0
#define MV_FACE_DETECTION_MIN_SIZE_WIDTH "MV_FACE_DETECTION_MIN_SIZE_WIDTH" |
Define MV_FACE_DETECTION_MIN_SIZE_WIDTH to set minimum width of face which will be detected as attribute of the engine configuration.
Default value is -1 (all detected faces will be applied) can be changed to specify the minimum face width
- Since :
- 3.0
#define MV_FACE_DETECTION_MODEL_FILE_PATH "MV_FACE_DETECTION_MODEL_FILE_PATH" |
Defines MV_FACE_DETECTION_MODEL_FILE_PATH to set face detection haarcascade xml file attribute of the engine configuration.
Face detection haarcascade model can be changed to specify the path to the file
- Since :
- 3.0
#define MV_FACE_DETECTION_ROI_HEIGHT "MV_FACE_DETECTION_ROI_HEIGHT" |
Define MV_FACE_DETECTION_ROI_HEIGHT to set height of face detection roi (Region of Interest) as attribute of the engine configuration.
Default value is -1 (the roi will be a full image) can be changed to specify the roi for face detection
- Since :
- 3.0
#define MV_FACE_DETECTION_ROI_WIDTH "MV_FACE_DETECTION_ROI_WIDTH" |
Define MV_FACE_DETECTION_ROI_WIDTH to set width of face detection roi (Region of Interest) as attribute of the engine configuration.
Default value is -1 (the roi will be a full image) can be changed to specify the roi for face detection
- Since :
- 3.0
#define MV_FACE_DETECTION_ROI_X "MV_FACE_DETECTION_ROI_X" |
Define MV_FACE_DETECTION_ROI_X to set X coordinate of face detection roi (Region of Interest) as attribute of the engine configuration.
Default value is -1 (the roi will be a full image) can be changed to specify the roi for face detection
- Since :
- 3.0
#define MV_FACE_DETECTION_ROI_Y "MV_FACE_DETECTION_ROI_Y" |
Define MV_FACE_DETECTION_ROI_Y to set Y coordinate of face detection roi (Region of Interest) as attribute of the engine configuration.
Default value is -1 (the roi will be a full image) can be changed to specify the roi for face detection
- Since :
- 3.0
#define MV_FACE_RECOGNITION_MODEL_TYPE "MV_FACE_RECOGNITION_MODEL_TYPE" |
Defines MV_FACE_RECOGNITION_MODEL_TYPE to set the method used for face recognition model learning attribute of the engine configuration.
Switches between three types of methods used for face recognition model learning. Possible values of the attribute are: 1 - Eigenfaces, 2 - Fisherfaces, 3 - Local Binary Patterns Histograms (LBPH) Default type is LBPH
- Since :
- 3.0
Typedef Documentation
typedef void(* mv_face_detected_cb)(mv_source_h source, mv_engine_config_h engine_cfg, mv_rectangle_s *faces_locations, int number_of_faces, void *user_data) |
Called when faces are detected for the source.
This type callback can be invoked each time when mv_face_detect() is called to process the results of face detecting.
- Since :
- 3.0
- Remarks:
- If no face is detected then the callback will be invoked, but faces_locations array will be NULL, and number_of_faces will be equal to 0.
- Parameters:
-
[in] source The handle to the source of the media where faces were detected [in] engine_cfg The handle to the configuration of engine was used for face detecting, or NULL if default settings were applied [in] faces_locations Rectangular locations of detected faces [in] number_of_faces Number of detected faces [in] user_data The user data passed from callback invoking code
- Precondition:
- Call mv_face_detect() function to perform detection of the face for the face image and invoke this callback as a result
- See also:
- mv_face_detect()
typedef void(* mv_face_eye_condition_recognized_cb)(mv_source_h source, mv_engine_config_h engine_cfg, mv_rectangle_s face_location, mv_face_eye_condition_e eye_condition, void *user_data) |
Called when eye blink condition is recognized.
This type callback can be invoked each time when mv_face_eye_condition_recognize() is called for face_location to recognize eye-blink condition for the face at the source.
Usage example for this callback can be found in mv_face_eye_condition_recognize() documentation.
- Since :
- 3.0
- Parameters:
-
[in] source The handle to the source of the media for which eye-blink condition was recognized [in] engine_cfg The handle to the configuration of engine was used for eye-blink condition recognition, or NULL if default settings were applied. [in] face_location The location bounding the face at the source [in] eye_condition The type of eye-blink condition recognized for face bounded by face_location [in] user_data The user data passed from callback invoking code
- Precondition:
- Call mv_face_eye_condition_recognize() function to perform eye-blink condition recognition and invoke this callback as a result
- See also:
- mv_face_eye_condition_recognize()
typedef void(* mv_face_facial_expression_recognized_cb)(mv_source_h source, mv_engine_config_h engine_cfg, mv_rectangle_s face_location, mv_face_facial_expression_e facial_expression, void *user_data) |
Called when facial expression is recognized.
This type callback can be invoked each time when mv_face_facial_expression_recognize() is called for face_location to recognize facial expression for the face at the source.
Usage example for this callback can be found in mv_face_facial_expression_recognize() documentation.
- Since :
- 3.0
- Parameters:
-
[in] source The handle to the source of the media for which facial expression was recognized [in] engine_cfg The handle to the configuration of engine was used for expression recognition [in] face_location The location bounding the face at the source [in] facial_expression The type of facial expression recognized for face bounded by face_location [in] user_data The user data passed from callback invoking code
- Precondition:
- Create a source handle by calling mv_create_source()
- Create a face engine configuration handle by calling mv_create_engine_config()
typedef void* mv_face_recognition_model_h |
The handle to the model aggregating recognition face features.
This handle can be used for faces recognizing with mv_face_recognize() function. Handle has to be created by mv_face_recognition_model_create() and destroyed by mv_face_recognition_model_destroy() functions. To use recognition models effectively learning process has to be performed before recognition. In other words, appropriate set of the face image examples has to be collected with mv_face_recognition_model_add() function before mv_face_recognition_model_learn() function call, then recognition can be performed with mv_face_recognize().
- Since :
- 3.0
typedef void(* mv_face_recognized_cb)(mv_source_h source, mv_face_recognition_model_h recognition_model, mv_engine_config_h engine_cfg, mv_rectangle_s *face_location, const int *face_label, double confidence, void *user_data) |
Called each time when face is recognized by mv_face_recognize() function.
- Since :
- 3.0
- Parameters:
-
[in] source The handle to the image source for which face has been recognized/not recognized [in] recognition_model The handle to the recognition model has been used for recognition [in] engine_cfg The handle to the configuration of engine was used for recognition, or NULL if default settings were applied [in] face_location The pointer to the location of the face recognized on source. If face wasn't recognized, then pointer is NULL [in] face_label The label that identifies face which was recognized in the source. NULL if recognition was performed, but no faces were recognized in the source [in] confidence The confidence of the recognition_model that face has been recognized correctly (value from 0.0 to 1.0). No faces were recognized if confidence was 0.0. When model has been learned on large amount of examples, threshold for this value can be high (0.85-0.95). If model was learned for small amount of examples, then threshold can be reduced (0.5-0.85) [in] user_data The user data passed from callback invoking code
- Precondition:
- Call mv_face_recognize() function to perform recognition of the face for the face image and invoke this callback as a result
- See also:
- mv_face_recognize()
typedef void(* mv_face_tracked_cb)(mv_source_h source, mv_face_tracking_model_h tracking_model, mv_engine_config_h engine_cfg, mv_quadrangle_s *location, double confidence, void *user_data) |
Called when face determined by tracking_model is tracked.
This type callback can be invoked each time when mv_face_track() is called to process the results of face tracking.
- Since :
- 3.0
- Parameters:
-
[in] source The handle to the video frame or image from sequence for which face was tracked [in] tracking_model The handle to the model that was used for tracking [in] engine_cfg The handle to the configuration of engine was used for tracking, or NULL if default settings were applied. [in] location The pointer to the quadrangle-shaped location which determines new position of the tracked face on the source. If NULL, then face was lost by tracking algorithm during last iteration [in] confidence The confidence of the tracking_model that new location of the face was determined correctly (value from 0.0 to 1.0). If no location was determined during last track iteration, then value is 0.0 [in] user_data The user data passed from callback invoking code
- Precondition:
- Call mv_face_track() function to perform track iteration for the video frame or the image from sequence and invoke this callback as a result
- See also:
- mv_face_track()
typedef void* mv_face_tracking_model_h |
The handle to the model aggregating tracking face features.
This model can be used for face tracking with mv_face_track() function. Handle has to be created by mv_face_tracking_model_create() and destroyed by mv_face_tracking_model_destroy() function. Tracking model can be improved during tracking task and allows to track face more accurately. So, you can create several tracking models independently by default, then apply tracking task for each of them. After some tracking these models will be different and each of them will be more efficient for tracking of face for which was created.
- Since :
- 3.0
- Remarks:
- Create each tracking model for single face.
Enumeration Type Documentation
Enumeration for expression types can be determined for faces.
- Since :
- 3.0
- Enumerator:
Function Documentation
int mv_face_detect | ( | mv_source_h | source, |
mv_engine_config_h | engine_cfg, | ||
mv_face_detected_cb | detected_cb, | ||
void * | user_data | ||
) |
Performs face detection on the source for the engine_cfg.
Use this function to launch face detection algorithm configured by engine_cfg configuration. Each time when mv_face_detect() is called, detected_cb will receive a set of the detected faces at the media source.
- Since :
- 3.0
- Parameters:
-
[in] source The handle to the source of the media where faces will be detected [in] engine_cfg The handle to the configuration of engine will be used for detecting. If NULL, then default settings will be used. [in] detected_cb The callback which will be called for all face locations detected on media source. This callback will receive detecting results [in] user_data The user data passed from the code where mv_face_detect() is invoked. This data will be accessible from detected_cb callback.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Source colorspace isn't supported MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a source handle by calling mv_create_source()
- Postcondition:
- detected_cb will be called to process detection results
- See also:
- mv_face_detected_cb()
int mv_face_eye_condition_recognize | ( | mv_source_h | source, |
mv_engine_config_h | engine_cfg, | ||
mv_rectangle_s | face_location, | ||
mv_face_eye_condition_recognized_cb | eye_condition_recognized_cb, | ||
void * | user_data | ||
) |
Determines eye-blink condition for face_location on media source.
Use this function to recognize eye-blink condition for the face bounded by face_location at source.
- Since :
- 3.0
- Parameters:
-
[in] source The handle to the source of the media to recognize eye-blink condition for [in] engine_cfg The handle to the configuration of engine will be used for eye-blink condition recognition. If NULL, the default configuration will be used. [in] face_location The location bounding the face at the source [in] eye_condition_recognized_cb The callback for processing result of eye-blink condition recognition [in] user_data The user data passed from the code where mv_face_eye_condition_recognize() is invoked. This data will be accessible from eye_condition_recognized_cb callback.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Source colorspace isn't supported MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a source handle by calling mv_create_source()
int mv_face_facial_expression_recognize | ( | mv_source_h | source, |
mv_engine_config_h | engine_cfg, | ||
mv_rectangle_s | face_location, | ||
mv_face_facial_expression_recognized_cb | expression_recognized_cb, | ||
void * | user_data | ||
) |
Determines facial expression for face_location on media source.
Use this function to determine facial expression for the face bounded by face_location at source.
- Since :
- 3.0
- Parameters:
-
[in] source The handle to the source of the media to recognize facial expression for [in] engine_cfg The handle to the configuration of engine will be used for expression recognition [in] face_location The location bounding the face at the source [in] expression_recognized_cb The callback for processing result of facial expression determining [in] user_data The user data passed from the code where mv_face_facial_expression_recognize() is invoked. This data will be accessible from expression_recognized_cb callback.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Source colorspace isn't supported MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a source handle by calling mv_create_source()
- Create a face engine configuration handle by calling mv_create_engine_config()
int mv_face_recognition_model_add | ( | const mv_source_h | source, |
mv_face_recognition_model_h | recognition_model, | ||
const mv_rectangle_s * | example_location, | ||
int | face_label | ||
) |
Adds face image example to be used for face recognition model learning with mv_face_recognition_model_learn().
- Since :
- 3.0
- Remarks:
- It is possible to destroy source after calling this method. Source isn't used for learning directly.
- Face image example_location location can be determined using mv_face_detect() function.
- Parameters:
-
[in] source The handle to source that contains face image [in] recognition_model The handle to the recognition model which could be learned based on example [in] example_location The pointer to the rectangular location of the face image at the source image. If NULL, then full image will be analyzed as the face image [in] face_label The label that identifies face for which example is adding. Specify the same labels for the face images of a single person when calling this method. Has to be unique for each face
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Source colorspace isn't supported MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a face recognition handle by calling mv_face_recognition_model_create() function
- Postcondition:
- When appropriate amount of face image examples is added to the recognition_model, this model has to be learned by mv_face_recognition_model_learn() function call. Only after learning of the model it can be used for face recognition with mv_face_recognize() function
int mv_face_recognition_model_clone | ( | mv_face_recognition_model_h | src, |
mv_face_recognition_model_h * | dst | ||
) |
Creates a copy of existed recognition model handle and clones all its resources.
- Since :
- 3.0
- Remarks:
- Cloning perform not only handle copy, but also copies all internal resources of the model. dst must be released using mv_face_recognition_model_destroy().
- Parameters:
-
[in] src The handle to the recognition model to be copied [out] dst The handle to the copy of existed recognition model specified as src
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create face recognition handles by calling mv_face_recognition_model_create()
- See also:
- mv_face_recognition_model_create()
int mv_face_recognition_model_create | ( | mv_face_recognition_model_h * | recognition_model | ) |
Creates a face recognition model handle.
Use this function to create default face recognition model. Creating process is defined by concrete face engine library. After creation recognition model has to be learned with mv_face_recognition_model_learn() function to provide appropriate results of face recognition functionality. Or learned earlier model can be loaded by mv_face_recognition_model_load() function.
- Since :
- 3.0
- Remarks:
- It can cause incompatibility issues when saved models (see mv_face_recognition_model_save(), mv_face_recognition_model_load() functions documentation) are used in applications for different platforms which use different computer vision libraries underlying this API.
- You must release recognition_model by using mv_face_recognition_model_destroy() function.
- Parameters:
-
[out] recognition_model The handle to the recognition model to be created
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- Model can be loaded from the file after creation. Use mv_face_recognition_model_load() function to load it from file
- Release recognition_model by using mv_face_recognition_model_destroy() function when it is not needed anymore
- See also:
- mv_face_recognition_model_destroy()
int mv_face_recognition_model_destroy | ( | mv_face_recognition_model_h | recognition_model | ) |
Destroys the face recognition model handle and releases all its resources.
- Since :
- 3.0
- Parameters:
-
[in] recognition_model The handle to the face recognition model to be destroyed
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create recognition model by using mv_face_recognition_model_create()
- See also:
- mv_face_recognition_model_create()
int mv_face_recognition_model_learn | ( | mv_engine_config_h | engine_cfg, |
mv_face_recognition_model_h | recognition_model | ||
) |
Learns face recognition model.
Before you start learning process, face recognition models has to be filled with training data - face image examples. These examples has to be provided by mv_face_recognition_model_add() function. Usually, recognition accuracy is increased when number of not identical examples is large. But it depends on the used learning algorithm.
- Since :
- 3.0
- Remarks:
- Common flow is to collect face examples as much as possible, add them to the recognition model with mv_face_recognition_model_add(), then call mv_face_recognition_model_learn() for this recognition model to learn it (or update the model if updating is supported by the used algorithm).
- Selection of the learning algorithm can be performed by setting corresponding attributes for the engine_cfg. You can check supported by engine_cfg attributes using mv_engine_config_foreach_supported_attribute() function call. By default, Local Binary Patterns Histograms (LBPH) based recognition algorithm will be used.
- Parameters:
-
[in] engine_cfg The handle to the configuration of engine will be used for learning of the recognition models. If NULL, then default settings will be used [in,out] recognition_model The model which will be learned. After learning process these model may be changed, so mv_face_recognize() results may differ before and after method call respectively to the face examples collected for the recognition_model
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_NO_DATA No data MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a face engine configuration handle by calling mv_create_engine_config() and set supported parameters if needed. Or just set engine_cfg as NULL to learn with default settings
- Create a face recognition model handles by calling mv_face_recognition_model_create() function
- Add face image examples to the recognition_model by calling mv_face_recognition_model_add() function
- Postcondition:
- If it is not planned to learn the model again, clear memory by mv_face_recognition_model_reset() function
- When model has been learned, it can be used for face recognition with mv_face_recognize() function
int mv_face_recognition_model_load | ( | const char * | file_name, |
mv_face_recognition_model_h * | recognition_model | ||
) |
Loads recognition model from file.
- Since :
- 3.0
- Remarks:
- This function doesn't modify the set of face image examples added with mv_face_recognition_model_add() function. Model will be loaded from file without loss of collected examples. If you want to free memory from examples, use mv_face_recognition_model_reset() function. It is recommended to clear the memory if learning algorithm doesn't support reinforcement learning.
- recognition_model is loaded from the absolute path directory. Use app_get_data_path for the private app storage path. recognition_model must be destroyed using mv_face_recognition_model_destroy().
- Parameters:
-
[in] file_name Name of path/file to load the model [out] recognition_model The handle to the recognition model to be loaded from the file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_INVALID_PATH Invalid path MEDIA_VISION_ERROR_PERMISSION_DENIED Not permitted MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Not supported model format MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Recognition model can be preliminary saved with mv_face_recognition_model_save() function
int mv_face_recognition_model_query_labels | ( | mv_face_recognition_model_h | recognition_model, |
int ** | labels, | ||
unsigned int * | number_of_labels | ||
) |
Queries labels list and number of labels had been learned by the model.
- Since :
- 3.0
- Remarks:
- labels array has to be released using free().
- Parameters:
-
[in] recognition_model The handle to the recognition model for which set of the learned labels will be queried [out] labels The array which will be filled with labels had been learned by the model [out] number_of_labels The number of labels in labels array
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Add face image examples with labels to the recognition_model by calling the mv_face_recognition_model_add() function
- Learn the recognition_model by labeled examples using mv_face_recognition_model_learn() function
- Postcondition:
- labels array has to be freed in the function invoking code
int mv_face_recognition_model_reset | ( | mv_face_recognition_model_h | recognition_model, |
int * | face_label | ||
) |
Removes from recognition_model all collected with mv_face_recognition_model_add() function face examples labeled with face_label.
- Since :
- 3.0
- Remarks:
- Be aware that if this function is called before mv_face_recognition_model_learn() function call, all or part of the required for learning data will be lost. It means that face image examples determined by the face_label label will be removed from the model and not taken into account when mv_face_recognition_model_learn() will be called next time.
- Call of this function will free all the memory has been allocated during previous mv_face_recognition_model_add() calls for the corresponding face_label label.
- Parameters:
-
[in] recognition_model The handle to the recognition model for which face image examples will be reset. [in] face_label The label that identifies face for which examples will be removed from the recognition_model. If NULL, then all known by recognition_model face image examples will be removed
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_KEY_NOT_AVAILABLE Key not available MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
int mv_face_recognition_model_save | ( | const char * | file_name, |
mv_face_recognition_model_h | recognition_model | ||
) |
Saves recognition model to the file.
- Since :
- 3.0
- Remarks:
- This function doesn't save face image examples (image itself) added by mv_face_recognition_model_add() function. This examples can be removed by mv_face_recognition_model_reset() function if it is needed to clear the memory.
- recognition_model is saved to the absolute path directory. Use app_get_data_path for the private app storage path. After model is saved to the file, it can be loaded from this file by mv_face_recognition_model_load() function.
- Parameters:
-
[in] file_name Name of the path/file to save the model [in] recognition_model The handle to the recognition model to be saved to the file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation MEDIA_VISION_ERROR_INVALID_PATH Invalid path MEDIA_VISION_ERROR_PERMISSION_DENIED Not permitted MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Not supported model format MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a face recognition handle by calling mv_face_recognition_model_create() function
- Postcondition:
- Saved model can be loaded later by calling mv_face_recognition_model_load() function
int mv_face_recognize | ( | mv_source_h | source, |
mv_face_recognition_model_h | recognition_model, | ||
mv_engine_config_h | engine_cfg, | ||
mv_rectangle_s * | face_location, | ||
mv_face_recognized_cb | recognized_cb, | ||
void * | user_data | ||
) |
Performs face recognition on the source image.
Use this function to launch face recognition algorithm configured by engine_cfg configuration using recognition_model recognition model. Each time when mv_face_recognize() is called, recognized_cb will receive recognition results:
- Location in the source of the face has been recognized;
- Label of the face has been recognized;
- Confidence of the recognition_model that face has been recognized correctly (value from 0.0 to 1.0).
- Since :
- 3.0
- Remarks:
- Using of untrained or weakly trained recognition models will cause not accurate results even if resulting confidence will be high. Use mv_face_recognition_model_learn() function before mv_face_recognize() call. Best results can be achieved when big set of face image examples were added by mv_face_recognition_model_add() before mv_face_recognition_model_learn() call.
- Parameters:
-
[in] source The handle to the source of the media to recognize face(s) for [in] recognition_model The handle to the model will be used for recognition [in] engine_cfg The handle to the configuration of engine will be used for recognition. If NULL, then default settings will be used [in] face_location Rectangular box bounding face image on the source. If NULL, then full source will be analyzed [in] recognized_cb The callback which will be called for the face recognition results on the source. [in] user_data The user data passed from the code where mv_face_recognize() is invoked. This data will be accessible from recognized_cb callback
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Source colorspace isn't supported MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a source handle by calling mv_create_source()
- Create a face recognition model handle by calling mv_face_recognition_model_create()
- Postcondition:
- recognized_cb will be called to process recognition results
- See also:
- mv_face_recognized_cb()
int mv_face_track | ( | mv_source_h | source, |
mv_face_tracking_model_h | tracking_model, | ||
mv_engine_config_h | engine_cfg, | ||
mv_face_tracked_cb | tracked_cb, | ||
bool | do_learn, | ||
void * | user_data | ||
) |
Performs face tracking on the source for the tracking_model.
Use this function to launch face tracking algorithm configured by engine_cfg configuration using tracking_model tracking model. Each time when this function is called, tracked_cb will receive updated tracking_model, new location determined for the tracked face and model confidence that location is determined correctly.
- Since :
- 3.0
- Remarks:
- To allow correct tracking tracking_model has to be already used in previous tracking process(es) or prepared with mv_face_tracking_model_prepare(). Preparation requires specifying the face location for the source on which tracking was started. I.e. mv_face_tracking_model_prepare() function has to be called at least once before this method call.
- Parameters:
-
[in] source The handle to the source of the media to recognize face for [in] tracking_model The handle to the model will be used for tracking [in] engine_cfg The handle to the configuration of engine will be used for tracking. If NULL, the default configuration will be used. [in] tracked_cb The callback which will be called for tracking event on the source where face would be tracked. This callback will receive tracking results [in] do_learn The model learning flag. If it is set true
then model will try to learn (if it supports learning feature), otherwise model will be not learned during the invoking tracking iteration. Learning process improves tracking correctness, but can decrease tracking performance[in] user_data The user data passed from the code where mv_face_track() is invoked. This data will be accessible from tracked_cb callback
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Source colorspace isn't supported MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a source handle by calling mv_create_source()
- Create a face tracking model handle by calling mv_face_tracking_model_create()
- Postcondition:
- tracked_cb will be called to process tracking results
- See also:
- mv_face_tracked_cb()
int mv_face_tracking_model_clone | ( | mv_face_tracking_model_h | src, |
mv_face_tracking_model_h * | dst | ||
) |
Calls this function to make a copy of existed tracking model handle and clone all its resources to the copy.
- Since :
- 3.0
- Remarks:
- Cloning performs not only handle copy, but also copies all internal resources of the model. dst must be released using mv_face_tracking_model_destroy().
- Parameters:
-
[in] src The handle to the tracking model to be copied [out] dst The handle to the copy of existed tracking model specified as src
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create face tracking src handle by calling mv_face_tracking_model_create()
- See also:
- mv_face_tracking_model_create()
int mv_face_tracking_model_create | ( | mv_face_tracking_model_h * | tracking_model | ) |
Calls this function to create a face tracking model handle.
Use this function to create default face tracking model handle. After creation this handle has to be initialized with mv_face_tracking_model_prepare() function to provide appropriate results of face tracking functionality. When handle is prepared, it is possible to use it for tracking on continuous sequence of the sources. Call mv_face_tracking_model_prepare() function each time before starting tracking on the new sequence. The exception is situation when the new sequence is continuation of the previous sequence for which model has been tracked.
- Since :
- 3.0
- Parameters:
-
[out] tracking_model The pointer to the handle to the tracking model that will be created
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- Model can be loaded from the file after creation. Use mv_face_tracking_model_load() function to load it from file
- Use mv_face_tracking_model_prepare() function before tracking on the new video or continuous images sequence
- Release tracking_model by using mv_face_tracking_model_destroy() function when it is not needed anymore
int mv_face_tracking_model_destroy | ( | mv_face_tracking_model_h | tracking_model | ) |
Calls this function to destroy the face tracking model handle and release all its resources.
- Since :
- 3.0
- Parameters:
-
[in] tracking_model The handle to the face tracking model that will be destroyed
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create tracking model by using mv_face_tracking_model_create()
- See also:
- mv_face_tracking_model_create()
int mv_face_tracking_model_load | ( | const char * | file_name, |
mv_face_tracking_model_h * | tracking_model | ||
) |
Calls this method to load a tracking model from file.
- Since :
- 3.0
- Remarks:
- tracking_model is loaded from the absolute path directory. Use app_get_data_path() for the private app storage path. tracking_model must be destroyed using mv_face_tracking_model_destroy().
- Parameters:
-
[in] file_name Name of path/file to load the model [out] tracking_model The handle to the tracking model to be loaded from file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation MEDIA_VISION_ERROR_INVALID_PATH Invalid path MEDIA_VISION_ERROR_PERMISSION_DENIED Not permitted MEDIA_VISION_ERROR_OUT_OF_MEMORY Out of memory MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Not supported model format MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Models has been saved by mv_face_tracking_model_save() function can be loaded with this function
- Postcondition:
- After model has been loaded and if further tracking will be performed on the video which is not continuation of the last tracking performed for the model, it is recommended to call mv_face_tracking_model_prepare() function
int mv_face_tracking_model_prepare | ( | mv_face_tracking_model_h | tracking_model, |
mv_engine_config_h | engine_cfg, | ||
mv_source_h | source, | ||
mv_quadrangle_s * | location | ||
) |
Calls this function to initialize tracking model by the location of the face to be tracked.
This function is usually called once after tracking model is created and each time before tracking is started for the new sequence of sources which is not the direct continuation of the sequence for which tracking has been performed before. But it is allowed to call it between tracking sessions to allow Media Vision start to track more accurately.
- Since :
- 3.0
- Parameters:
-
[in] tracking_model The handle to the tracking model that will be prepared for tracking on new video or image sequence [in] engine_cfg The handle to the configuration of engine will be used for model preparing. If NULL, then default settings will be used. [in] source The handle to the source where face location is specified. Usually it is the first frame of the video or the first image in the continuous image sequence planned to be used for tracking [in] location The quadrangle-shaped location (actually, rectangle can be used) determining position of the face to be tracked on the source. If NULL
, then tracking model will try to find previously tracked face by itself. Don't set NULL when called first time for the tracking model.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a face tracking model handle by calling mv_face_tracking_model_create() function
- Create a source handle by calling mv_create_source() function
- Postcondition:
- When model is prepared, mv_face_track() function can be used to track on the video or continuous image sequence
int mv_face_tracking_model_save | ( | const char * | file_name, |
mv_face_tracking_model_h | tracking_model | ||
) |
Calls this method to save tracking model to the file.
- Since :
- 3.0
- Remarks:
- tracking_model is saved to the absolute path directory. Use app_get_data_path() for the private app storage path. After model is saved to the file, it can be loaded from this file with mv_face_tracking_model_load() function.
- Parameters:
-
[in] file_name Name of the path/file to save the model [in] tracking_model The handle to the tracking model to be saved to the file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_VISION_ERROR_NONE Successful MEDIA_VISION_ERROR_INVALID_PARAMETER Invalid parameter MEDIA_VISION_ERROR_INVALID_OPERATION Invalid operation MEDIA_VISION_ERROR_INVALID_PATH Invalid path MEDIA_VISION_ERROR_PERMISSION_DENIED Not permitted MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT Not supported model format MEDIA_VISION_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- Create a face tracking handle by calling mv_face_tracking_model_create()
- Postcondition:
- Saved model can be loaded from file using mv_face_tracking_model_load() function