Tizen Native API  9.0
Functions | Typedefs
Media Vision Image Classification
Media Vision

Image classification.

Required Header

#include <mv_image_classification.h>

Overview

Media Vision Image Classification contains mv_image_classification_h handle to perform image classification. Image classification handle should be created with mv_image_classification_create() and destroyed with mv_image_classification_destroy(). mv_image_classification_h should be configured by calling mv_image_classification_configure(). After configuration, mv_image_classification_h should be prepared by calling mv_image_classification_prepare() which loads models and set required parameters. After preparation, mv_image_classification_inference() or mv_image_classification_inference_async() can be called to classify images on mv_source_h. Use mv_image_classification_get_result_count() to get the number of results and mv_image_classification_get_label() to get the label of each result.

Related Features

This API is related with the following features:

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

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_image_classification_create (mv_image_classification_h *handle)
 Creates image classification object handle.
int mv_image_classification_destroy (mv_image_classification_h handle)
 Destroys image classification handle and releases all its resources.
int mv_image_classification_configure (mv_image_classification_h handle)
 Configures the backend to the inference handle.
int mv_image_classification_prepare (mv_image_classification_h handle)
 Prepares inference.
int mv_image_classification_inference (mv_image_classification_h handle, mv_source_h source)
 Performs inference with a given face on the source.
int mv_image_classification_inference_async (mv_image_classification_h handle, mv_source_h source)
 Performs asynchronously the image classification inference on the source.
int mv_image_classification_get_result_count (mv_image_classification_h handle, unsigned long *frame_number, unsigned int *result_cnt)
 Gets the image classification inference result count on the handle.
int mv_image_classification_get_label (mv_image_classification_h handle, unsigned int index, const char **label)
 Gets the image classification inference result to a given index.

Typedefs

typedef void * mv_image_classification_h
 The image classification object handle.

Typedef Documentation

typedef void* mv_image_classification_h

The image classification object handle.

Since :
9.0

Function Documentation

int mv_image_classification_configure ( mv_image_classification_h  handle)

Configures the backend to the inference handle.

Since :
9.0
Parameters:
[in]handleThe handle to the inference
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_OUT_OF_MEMORYOut of memory
int mv_image_classification_create ( mv_image_classification_h *  handle)

Creates image classification object handle.

Use this function to create an image classification object handle. After creation the handle has to be prepared with mv_image_classification_prepare() function to prepare an image classification object.

Since :
9.0
Parameters:
[out]handleThe handle to the image classification object 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_INTERNALInternal Error
Postcondition:
Release handle by using mv_image_classification_destroy() function when it is not needed anymore.
 #include <mv_image_classification.h>
 ...
 mv_image_classification_h handle = NULL;
 mv_image_classification_create(&handle);
 ...
 mv_image_classification_destroy(handle);
See also:
mv_image_classification_destroy()
int mv_image_classification_destroy ( mv_image_classification_h  handle)

Destroys image classification handle and releases all its resources.

Since :
9.0
Parameters:
[in]handleThe handle to the image classification 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 an image classification handle by using mv_image_classification_create()
See also:
mv_image_classification_create()
int mv_image_classification_get_label ( mv_image_classification_h  handle,
unsigned int  index,
const char **  label 
)

Gets the image classification inference result to a given index.

Since :
9.0
Remarks:
The label should not be released.
The label is available until new inference is performed or handle is released.
Parameters:
[in]handleThe handle to the inference
[in]indexA result index.
[out]labelA label name to a detected 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
Precondition:
Create a source handle by calling mv_create_source()
Create an inference handle by calling mv_image_classification_create()
Prepare an inference by calling mv_image_classification_configure()
Prepare an inference by calling mv_image_classification_prepare()
Request an inference by calling mv_image_classification_inference()
Get result count by calling mv_image_classification_get_result_count()
 #include <mv_image_classification.h>
 #include <stdio.h>
 ...
 mv_image_classification_h handle = NULL;
 mv_image_classification_create(&handle);
 ...
 // perform inference
 ...
 unsigned long frame_number;
 unsigned int cnt;
 mv_image_classification_get_result_count(handle, &frame_number, &cnt);
 for (unsigned long idx = 0; idx < cnt; ++idx) {
      const char *label = NULL;
      mv_image_classification_get_label(handle, idx, &label);
      printf("frame number = %ld, label = %s\n", frame_number, label);
 }
 mv_image_classification_destroy(handle);
int mv_image_classification_get_result_count ( mv_image_classification_h  handle,
unsigned long *  frame_number,
unsigned int *  result_cnt 
)

Gets the image classification inference result count on the handle.

Since :
9.0
Parameters:
[in]handleThe handle to the inference
[out]frame_numberA frame number inferenced.
[out]result_cntA number of results.
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
Precondition:
Create a source handle by calling mv_create_source()
Create an inference handle by calling mv_image_classification_create()
Prepare an inference by calling mv_image_classification_configure()
Prepare an inference by calling mv_image_classification_prepare()
Request an inference by calling mv_image_classification_inference()
int mv_image_classification_inference ( mv_image_classification_h  handle,
mv_source_h  source 
)

Performs inference with a given face on the source.

Use this function to inference with a given source.

Since :
9.0
Parameters:
[in]handleThe handle to the image classification 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_NOT_SUPPORTED_FORMATSource colorspace isn't supported
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
Create a source handle by calling mv_create_source()
Create an image classification handle by calling mv_image_classification_create()
Prepare an image classification by calling mv_image_classification_prepare()
Inference Example
int main()
{
    int error_code = 0;
    mv_image_classification_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_image_classification_create(&handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);

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

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

    error_code = mv_image_classification_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_image_classification_get_result_count(handle, &frame_number, &cnt);
    if (error_code == MEDIA_VISION_ERROR_INVALID_OPERATION)
        break;

    for (unsigned int idx = 0; idx < cnt; ++idx) {
        const char *label = NULL;

        error_code = mv_image_classification_get_label(handle, idx, &label);
        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, label = %s", frame_number, idx, label);
    }

    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_image_classification_destroy(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);
}
int mv_image_classification_inference_async ( mv_image_classification_h  handle,
mv_source_h  source 
)

Performs asynchronously the image classification 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_image_classification_get_label().
Parameters:
[in]handleThe handle to the inference
[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_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMATSource colorspace isn't supported
Precondition:
Create a source handle by calling mv_create_source()
Create an inference handle by calling mv_image_classification_create()
Prepare an inference by calling mv_image_classification_configure()
Prepare an inference by calling mv_image_classification_prepare()
Async Inference Example
void image_classification_callback(void *user_data)
{
    mv_image_classification_h handle = (mv_image_classification_h) user_data;
    bool is_loop_exit = false;

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

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

        for (unsigned int idx = 0; idx < cnt; ++idx) {
            const char *label = NULL;

            error_code = mv_image_classification_get_label(handle, idx, &label);
            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, label = %s", frame_number, idx, label);

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

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

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

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

    error_code = mv_image_classification_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_image_classification_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, image_classification_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_image_classification_destroy(handle);
    if (error_code != MEDIA_VISION_ERROR_NONE)
        dlog_print(DLOG_ERROR, LOG_TAG, "error code = %d", error_code);
}
int mv_image_classification_prepare ( mv_image_classification_h  handle)

Prepares inference.

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

Since :
9.0
Parameters:
[in]handleThe handle to the inference
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_DATAInvalid model data
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory