Object detection.

Required Header

#include <mv_object_detection.h>

Overview

Media Vision Object Detection contains mv_object_detection_h handle to perform object detection. Object detection handle should be created with mv_object_detection_create() and destroyed with mv_object_detection_destroy(). mv_object_detection_h should be configured by calling mv_object_detection_configure(). After configuration, mv_object_detection_h should be prepared by calling mv_object_detection_prepare() which loads models and set required parameters. After preparation, mv_object_detection_inference() or mv_object_detection_inference_async() can be called to detect objects in images on mv_source_h. Use mv_object_detection_get_result_count() to get the number of results and mv_object_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_object_detection_create (mv_object_detection_h *infer)
	Creates a inference handle for object detection object.
int	mv_object_detection_destroy (mv_object_detection_h infer)
	Destroys inference handle and releases all its resources.
int	mv_object_detection_configure (mv_object_detection_h infer)
	Configures the backend for the object detection inference.
int	mv_object_detection_prepare (mv_object_detection_h infer)
	Prepares the object detection inference.
int	mv_object_detection_inference (mv_object_detection_h infer, mv_source_h source)
	Performs the object detection inference on the source.
int	mv_object_detection_inference_async (mv_object_detection_h handle, mv_source_h source)
	Performs asynchronously the object detection inference on the source.
int	mv_object_detection_get_result_count (mv_object_detection_h handle, unsigned long frame_number, unsigned int result_cnt)
	Gets the object detection inference result on the handle.
int	mv_object_detection_get_bound_box (mv_object_detection_h handle, unsigned int index, int left, int top, int right, int bottom)
	Gets a bound box to detected object region.
Typedefs
typedef void *	mv_object_detection_h
	The object detection object handle.

Typedef Documentation

typedef void* mv_object_detection_h

The object detection object handle.

Since :: 9.0

Function Documentation

int mv_object_detection_configure ( mv_object_detection_h infer )

Configures the backend for the object detection inference.

Since :: 9.0

Parameters:

[in] infer 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

int mv_object_detection_create ( mv_object_detection_h * infer )

Creates a inference handle for object detection object.

Use this function to create a inference handle. After the creation the object detection 3d task has to be prepared with mv_object_detection_prepare() function to prepare a network for the inference.

Since :: 9.0

Remarks:: The infer should be released using mv_object_detection_destroy().

Parameters:

[out] infer 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_object_detection.h>
 ...
 mv_object_detection_h handle = NULL;
 mv_object_detection_create(&handle);
 ...
 mv_object_detection_destroy(handle);

See also:: mv_object_detection_destroy(); mv_object_detection_prepare()

int mv_object_detection_destroy ( mv_object_detection_h infer )

Destroys inference handle and releases all its resources.

Since :: 9.0

Parameters:

[in] infer 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_object_detection_create()

See also:: mv_object_detection_create()

int mv_object_detection_get_bound_box	(	mv_object_detection_h	handle,
		unsigned int	index,
		int *	left,
		int *	top,
		int *	right,
		int *	bottom
	)

Gets a bound box to detected object region.

Since :: 9.0

Parameters:

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

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_object_detection_create(); Prepare an inference by calling mv_object_detection_configure(); Prepare an inference by calling mv_object_detection_prepare(); Prepare an inference by calling mv_object_detection_inference()

int mv_object_detection_get_result_count	(	mv_object_detection_h	handle,
		unsigned long *	frame_number,
		unsigned int *	result_cnt
	)

Gets the object 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_object_detection_create(); Prepare an inference by calling mv_object_detection_configure(); Prepare an inference by calling mv_object_detection_prepare(); Request an inference by calling mv_object_detection_inference()

int mv_object_detection_inference	(	mv_object_detection_h	infer,
		mv_source_h	source
	)

Performs the object detection inference on the source.

Since :: 9.0

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

Parameters:

[in]	infer	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_object_detection_create(); Prepare an inference by calling mv_object_detection_configure(); Prepare an inference by calling mv_object_detection_prepare()

Inference Example

int main()
{
    int error_code = 0;
    mv_object_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_object_detection_create(&handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

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

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

    error_code = mv_object_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_object_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_object_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_object_detection_destroy(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);
}

int mv_object_detection_inference_async	(	mv_object_detection_h	handle,
		mv_source_h	source
	)

Performs asynchronously the object 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_object_detection_get_result_count() and mv_object_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_object_detection_create(); Prepare an inference by calling mv_object_detection_configure(); Prepare an inference by calling mv_object_detection_prepare()

Async Inference Example

void object_detection_callback(void *user_data)
{
    mv_object_detection_h handle = (mv_object_detection_h) user_data;
    bool is_loop_exit = false;

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

        int error_code = mv_object_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_object_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_object_detection_h handle;

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

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

    error_code = mv_object_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_object_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, object_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_object_detection_destroy(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);
}

int mv_object_detection_prepare ( mv_object_detection_h infer )

Prepares the object detection inference.

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

Since :: 9.0

Parameters:

[in] infer 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

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation