Face detection.

Required Header

#include <mv_face_detection.h>

Overview

Media Vision Face Detection contains mv_face_detection_h handle to perform face detection. Face detection handle should be created with mv_face_detection_create() and destroyed with mv_face_detection_destroy(). mv_face_detection_h should be configured by calling mv_face_detection_configure(). After configuration, mv_face_detection_h should be prepared by calling mv_face_detection_prepare() which loads models and set required parameters. After preparation, mv_face_detection_inference() or mv_face_detection_inference_async() can be called to detect faces in images on mv_source_h. Use mv_face_detection_get_result_count() to get the number of results and mv_face_detection_get_bound_box() to get the bounding box of each result.

Related Features

This API is related with the following features:

http://tizen.org/feature/vision.inference.image
http://tizen.org/feature/vision.inference.face

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.

Functions
int	mv_face_detection_create (mv_face_detection_h *handle)
	Creates a inference handle for face detection object.
int	mv_face_detection_destroy (mv_face_detection_h handle)
	Destroys inference handle and releases all its resources.
int	mv_face_detection_configure (mv_face_detection_h handle)
	Configures the backend for the face detection inference.
int	mv_face_detection_prepare (mv_face_detection_h handle)
	Prepares the face detection inference.
int	mv_face_detection_inference (mv_face_detection_h handle, mv_source_h source)
	Performs the face detection inference on the source.
int	mv_face_detection_inference_async (mv_face_detection_h handle, mv_source_h source)
	Performs asynchronously the face detection inference on the source.
int	mv_face_detection_get_result_count (mv_face_detection_h handle, unsigned long frame_number, unsigned int result_cnt)
	Gets the face detection inference result on the handle.
int	mv_face_detection_get_bound_box (mv_face_detection_h handle, unsigned int index, int left, int top, int right, int bottom)
	Gets a bound box to detected face region.
Typedefs
typedef void *	mv_face_detection_h
	The face detection object handle.

Typedef Documentation

typedef void* mv_face_detection_h

The face detection object handle.

Since :: 9.0

Function Documentation

int mv_face_detection_configure ( mv_face_detection_h handle )

Configures the backend for the face detection inference.

Since :: 9.0

Parameters:

[in] handle The handle to the inference

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_INVALID_OPERATION	Invalid operation
MEDIA_VISION_ERROR_OUT_OF_MEMORY	Out of memory

Precondition:: Create an inference handle by calling mv_face_detection_create()

int mv_face_detection_create ( mv_face_detection_h * handle )

Creates a inference handle for face detection object.

Use this function to create a inference handle. After the creation the face detection task has to be prepared with mv_face_detection_prepare() function to prepare a network for the inference.

Since :: 9.0

Remarks:: The handle should be released using mv_face_detection_destroy().

Parameters:

[out] handle The handle to the inference to be created.

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_INTERNAL	Internal Error

 #include <mv_face_detection.h>
 ...
 mv_face_detection_h handle = NULL;
 mv_face_detection_create(&handle);
 ...
 mv_face_detection_destroy(handle);

See also:: mv_face_detection_destroy(); mv_face_detection_prepare()

int mv_face_detection_destroy ( mv_face_detection_h handle )

Destroys inference handle and releases all its resources.

Since :: 9.0

Parameters:

[in] handle The handle to the inference to be destroyed.

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Create inference handle by using mv_face_detection_create()

See also:: mv_face_detection_create()

int mv_face_detection_get_bound_box	(	mv_face_detection_h	handle,
		unsigned int	index,
		int *	left,
		int *	top,
		int *	right,
		int *	bottom
	)

Gets a bound box to detected face region.

Since :: 9.0

Parameters:

[in]	handle	The handle to the inference
[in]	index	A result index.
[out]	left	An left position of bound box.
[out]	top	An top position of bound box.
[out]	right	An right position of bound box.
[out]	bottom	An bottom position of bound box.

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Create a source handle by calling mv_create_source(); Create an inference handle by calling mv_face_detection_create(); Prepare an inference by calling mv_face_detection_configure(); Prepare an inference by calling mv_face_detection_prepare(); Request an inference by calling mv_face_detection_inference(); Get result count by calling mv_face_detection_get_result_count()

int mv_face_detection_get_result_count	(	mv_face_detection_h	handle,
		unsigned long *	frame_number,
		unsigned int *	result_cnt
	)

Gets the face detection inference result on the handle.

Since :: 9.0

Parameters:

[in]	handle	The handle to the inference
[out]	frame_number	A frame number inferenced.
[out]	result_cnt	A number of results.

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: Create a source handle by calling mv_create_source(); Create an inference handle by calling mv_face_detection_create(); Prepare an inference by calling mv_face_detection_configure(); Prepare an inference by calling mv_face_detection_prepare(); Request an inference by calling mv_face_detection_inference()

int mv_face_detection_inference	(	mv_face_detection_h	handle,
		mv_source_h	source
	)

Performs the face detection inference on the source.

Since :: 9.0

Remarks:: This function is synchronous and may take considerable time to run.

Parameters:

[in]	handle	The handle to the inference
[in]	source	The handle to the source of the media

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT	Source colorspace isn't supported

Precondition:: Create a source handle by calling mv_create_source(); Create an inference handle by calling mv_face_detection_create(); Prepare an inference by calling mv_face_detection_configure(); Prepare an inference by calling mv_face_detection_prepare()

Inference Example

int main()
{
    int error_code = 0;
    mv_face_detection_h handle;
    mv_source_h mv_source = NULL;

    error_code = mv_create_source(&mv_source);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    load_image_to_source("/path/to/image", mv_source);

    error_code = mv_face_detection_create(&handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    error_code = mv_face_detection_configure(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    error_code = mv_face_detection_prepare(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    error_code = mv_face_detection_inference(handle, mv_source);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    unsigned long frame_number;
    unsigned int cnt;

    int error_code = mv_face_detection_get_result_count(handle, &frame_number, &cnt);
    if (error_code == MEDIA_VISION_ERROR_INVALID_OPERATION)
        break;

    for (unsigned int idx = 0; idx < cnt; ++idx) {
        int left, top, right, bottom;

        int ret = mv_face_detection_get_bound_box(handle, idx, &left, &top, &right, &bottom);
        if (error_code != MEDIA_VISION_ERROR_NONE)
            dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

        dlog_print(DLOG_INFO, LOG_TAG,
                   "frame = %lu, idx = %u, left = %d, top = %d, "
                   "right = %d, bottom = %d",
                   frame_number, idx, left, top, right, bottom);
    }

    error_code = mv_destroy_source(mv_source);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    error_code = mv_face_detection_destroy(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);
}

int mv_face_detection_inference_async	(	mv_face_detection_h	handle,
		mv_source_h	source
	)

Performs asynchronously the face detection inference on the source.

Since :: 9.0

Remarks:: This function operates asynchronously, so it returns immediately upon invocation. The inference results are inserted into the outgoing queue within the framework in the order of processing, and the results can be obtained through mv_face_detection_get_result_count() and mv_face_detection_get_bound_box().

Parameters:

[in]	handle	The handle to the inference
[in]	source	The handle to the source of the media

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT	Source colorspace isn't supported

Precondition:: Create a source handle by calling mv_create_source(); Create an inference handle by calling mv_face_detection_create(); Prepare an inference by calling mv_face_detection_configure(); Prepare an inference by calling mv_face_detection_prepare()

Async Inference Example

void face_detection_callback(void *user_data)
{
    mv_face_detection_h handle = (mv_face_detection_h) user_data;
    bool is_loop_exit = false;

    while (!is_loop_exit) {
        unsigned long frame_number;
        unsigned int cnt;

        int error_code = mv_face_detection_get_result_count(handle, &frame_number, &cnt);
        if (error_code == MEDIA_VISION_ERROR_INVALID_OPERATION)
            break;

        for (unsigned int idx = 0; idx < cnt; ++idx) {
            int left, top, right, bottom;

            int ret = mv_face_detection_get_bound_box(handle, idx, &left, &top, &right, &bottom);
            if (error_code != MEDIA_VISION_ERROR_NONE)
                dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

            dlog_print(DLOG_INFO, LOG_TAG,
                       "frame = %lu, idx = %u, left = %d, top = %d, "
                       "right = %d, bottom = %d",
                       frame_number, idx, left, top, right, bottom);

            if (frame_number > MAX_INFERENCE_ITERATION - 10)
                is_loop_exit = true;
        }
    }
}

int main()
{
    int error_code = 0;
    mv_face_detection_h handle;

    error_code = mv_face_detection_create(&handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    error_code = mv_face_detection_configure(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    error_code = mv_face_detection_prepare(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

    pthread_t thread_id;

    for (unsigned int iter = 0; iter < MAX_INFERENCE_ITERATION; ++iter) {
        mv_source_h mv_source = NULL;

        error_code = mv_create_source(&mv_source);
        if (error_code != MEDIA_VISION_ERROR_NONE)
            dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

        load_image_to_source("/path/to/image", mv_source);

        error_code = mv_face_detection_inference_async(handle, mv_source);
        if (error_code != MEDIA_VISION_ERROR_NONE)
            dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

        if (iter == 0)
            pthread_create(&thread_id, NULL, face_detection_callback, handle);

        error_code = mv_destroy_source(mv_source);
        if (error_code != MEDIA_VISION_ERROR_NONE)
            dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);
    }

    /* This thread will be exited after inference is performed MAX_INFERENCE_ITERATION times. */
    pthread_join(thread_id, NULL);

    error_code = mv_face_detection_destroy(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);
}

int mv_face_detection_prepare ( mv_face_detection_h handle )

Prepares the face detection inference.

Use this function to prepare the face detection inference based on the configured network.

Since :: 9.0

Parameters:

[in] handle The handle to the inference.

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_INVALID_DATA	Invalid model data
MEDIA_VISION_ERROR_OUT_OF_MEMORY	Out of memory
MEDIA_VISION_ERROR_INVALID_OPERATION	Invalid operation
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT	Not supported format

Precondition:: Prepare an inference by calling mv_face_detection_configure()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation