Tizen Native API  7.0
Media Vision Face Recognition

Face recognition.

Required Header

#include <mv_face_recognition.h>

Related Features

This API is related with the following features:

  • http://tizen.org/feature/vision.inference
  • http://tizen.org/feature/vision.training
  • http://tizen.org/feature/vision.inference.face_recognition
  • http://tizen.org/feature/vision.training.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 Recognition 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

Functions

int mv_face_recognition_create (mv_face_recognition_h *handle)
 Creates face recognition handle.
int mv_face_recognition_destroy (mv_face_recognition_h handle)
 Destroys face recognition handle and release all its resources.
int mv_face_recognition_prepare (mv_face_recognition_h handle)
 Prepares the resources for face recognition.
int mv_face_recognition_register (mv_face_recognition_h handle, mv_source_h source, const char *label)
 Registers a new face on the source.
int mv_face_recognition_unregister (mv_face_recognition_h handle, const char *label)
 Unregisters face data on the label.
int mv_face_recognition_inference (mv_face_recognition_h handle, mv_source_h source)
 Inferences with a given face on the source.
int mv_face_recognition_get_label (mv_face_recognition_h handle, const char **out_label)
 Gets the recognized face label name.

Typedefs

typedef void * mv_face_recognition_h
 The face recognition object handle.

Typedef Documentation

typedef void* mv_face_recognition_h

The face recognition object handle.

Since :
7.0

Function Documentation

Creates face recognition handle.

Use this function to create a face recognition handle. After the creation the handle has to be prepared with mv_face_recognition_prepare() function to prepare face recognition resources.

Since :
7.0
Remarks:
The handle should be released using mv_face_recognition_destroy().
Parameters:
[out]handleThe handle to the face recognition to be created
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
See also:
mv_face_recognition_destroy()

Destroys face recognition handle and release all its resources.

Since :
7.0
Parameters:
[in]handleThe handle to the face recognition object to be destroyed
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Create face recognition handle by using mv_face_recognition_create()
See also:
mv_face_recognition_create()
int mv_face_recognition_get_label ( mv_face_recognition_h  handle,
const char **  out_label 
)

Gets the recognized face label name.

Use this function to get the recognized label name after calling mv_face_recognition_inference().

Since :
7.0
Remarks:
The out_label must NOT be released using free()
Parameters:
[in]handleThe handle to the face recognition object.
[out]out_labelThe array pointer for the label name to be stored. This function returns memory pointer containing actual label string to out_label. So do not free out_label. And please note that out_label is valid only while handle is alive.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_INVALID_OPERATIONInvalid operation
Precondition:
Request an inference by calling mv_face_recognition_inference()

Inferences with a given face on the source.

Use this function to inference with a given source. This function returns n proper label string to a give source.

Since :
7.0
Parameters:
[in]handleThe handle to the face recognition object.
[in]sourceThe handle to the source of the media.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_VISION_ERROR_INVALID_PATHInvalid path
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_VISION_ERROR_INTERNALInternal error
MEDIA_VISION_ERROR_NO_DATANo data
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMATSource colorspace isn't supported
Precondition:
Prepare an face recognition by calling mv_face_recognition_prepare()
Register a new face by calling mv_face_recognition_register()

Prepares the resources for face recognition.

Use this function to prepare the resources for face recognition.

Since :
7.0
Parameters:
[in]handleThe handle to the face recognition object.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_VISION_ERROR_KEY_NOT_AVAILABLEAttribute key isn't available
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
Create face recognition handle by using mv_face_recognition_create()
int mv_face_recognition_register ( mv_face_recognition_h  handle,
mv_source_h  source,
const char *  label 
)

Registers a new face on the source.

Use this function to register a new face. Each time when this function is called, a new face on the media source will be registered to internal database.

Since :
7.0
Parameters:
[in]handleThe handle to the face recognition object.
[in]sourceThe handle to the source of the media.
[in]labelThe label to be registered.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMATSource colorspace isn't supported
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_VISION_ERROR_INTERNALInternal error
Precondition:
Prepare an face recognition by calling mv_face_recognition_prepare()
int mv_face_recognition_unregister ( mv_face_recognition_h  handle,
const char *  label 
)

Unregisters face data on the label.

Use this function to unregister a given label. Each time when this function is called, all data related to the label will be removed from internal database.

Since :
7.0
Parameters:
[in]handleThe handle to the face recognition object.
[in]labelThe label to be unregistered.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
Register an new face by calling mv_face_recognition_register()