Tizen Native API  5.0
Media Vision Image

Flat Image recognition and tracking;
Flat image feature extraction.

Required Header

#include <mv_image.h>

Related Features

This API is related with the following features:

  • http://tizen.org/feature/vision.image_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 Image contains mv_image_recognize() function to recognize images on mv_source_h, and mv_image_recognized_cb() callback to process recognition result. Module also contains mv_image_track() which performs tracking of image on sequence of mv_source_h handles (by using method for each mv_source_h) and callback mv_image_tracked_cb to process tracking result. In order to perform general functionality, module contains mv_image_object_h and mv_image_tracking_model_h handles. Image object should be created with mv_image_object_create() and destroyed with mv_image_object_destroy(). mv_image_object_h can be constructed by calling mv_image_object_fill() using image wrapped with mv_source_h. Object can be cloned with mv_image_object_clone(), saved to the file with mv_image_object_save() and loaded from file with mv_image_object_load(). Image object can be evaluated with mv_image_object_get_recognition_rate(). Tracking model should be created with mv_image_tracking_model_create() and destroyed with mv_image_tracking_model_destroy(). Tracking model should be based on image object which will be tracked. Use mv_image_tracking_model_set_target() to assign mv_image_object_h to the corresponding mv_image_tracking_model_h. It can be cloned with mv_image_tracking_model_clone(), saved to the file with mv_image_tracking_model_save() and loaded from file with mv_image_tracking_model_load().

Functions

int mv_image_recognize (mv_source_h source, const mv_image_object_h *image_objects, int number_of_objects, mv_engine_config_h engine_cfg, mv_image_recognized_cb recognized_cb, void *user_data)
 Recognizes the given image objects on the source image.
int mv_image_track (mv_source_h source, mv_image_tracking_model_h image_tracking_model, mv_engine_config_h engine_cfg, mv_image_tracked_cb tracked_cb, void *user_data)
 Tracks the given image tracking model on the current frame.
int mv_image_object_create (mv_image_object_h *image_object)
 Creates an image object.
int mv_image_object_destroy (mv_image_object_h image_object)
 Destroys the image object.
int mv_image_object_fill (mv_image_object_h image_object, mv_engine_config_h engine_cfg, mv_source_h source, mv_rectangle_s *location)
 Fills the image object.
int mv_image_object_get_recognition_rate (mv_image_object_h image_object, double *recognition_rate)
 Gets a value that determines how well an image object can be recognized.
int mv_image_object_set_label (mv_image_object_h image_object, int label)
 Sets a label for the image object.
int mv_image_object_get_label (mv_image_object_h image_object, int *label)
 Gets a label of image object.
int mv_image_object_clone (mv_image_object_h src, mv_image_object_h *dst)
 Clones the image object.
int mv_image_object_save (const char *file_name, mv_image_object_h image_object)
 Saves the image object.
int mv_image_object_load (const char *file_name, mv_image_object_h *image_object)
 Loads an image object from the file.
int mv_image_tracking_model_create (mv_image_tracking_model_h *image_tracking_model)
 Creates an image tracking model.
int mv_image_tracking_model_set_target (mv_image_object_h image_object, mv_image_tracking_model_h image_tracking_model)
 Sets target of image tracking model.
int mv_image_tracking_model_destroy (mv_image_tracking_model_h image_tracking_model)
 Destroys the image tracking model.
int mv_image_tracking_model_refresh (mv_image_tracking_model_h image_tracking_model, mv_engine_config_h engine_cfg)
 Refreshes the state of image tracking model.
int mv_image_tracking_model_clone (mv_image_tracking_model_h src, mv_image_tracking_model_h *dst)
 Clones the image tracking model.
int mv_image_tracking_model_save (const char *file_name, mv_image_tracking_model_h image_tracking_model)
 Saves the image tracking model.
int mv_image_tracking_model_load (const char *file_name, mv_image_tracking_model_h *image_tracking_model)
 Loads an image tracking model from the file.

Typedefs

typedef void(* mv_image_recognized_cb )(mv_source_h source, mv_engine_config_h engine_cfg, const mv_image_object_h *image_objects, mv_quadrangle_s **locations, unsigned int number_of_objects, void *user_data)
 Called when image recognition results are received from mv_image_recognize()
typedef void(* mv_image_tracked_cb )(mv_source_h source, mv_image_tracking_model_h image_tracking_model, mv_engine_config_h engine_cfg, mv_quadrangle_s *location, void *user_data)
 Called when image tracking result received from mv_image_track()
typedef void * mv_image_object_h
 The image object's type handle.
typedef void * mv_image_tracking_model_h
 The image tracking model's type handle.

Defines

#define MV_IMAGE_RECOGNITION_OBJECT_SCALE_FACTOR   "MV_IMAGE_RECOGNITION_OBJECT_SCALE_FACTOR"
 Defines MV_IMAGE_RECOGNITION_OBJECT_SCALE_FACTOR to set the image to be recognized scale factor attribute of the engine configuration.
#define MV_IMAGE_RECOGNITION_OBJECT_MAX_KEYPOINTS_NUM   "MV_IMAGE_RECOGNITION_OBJECT_MAX_KEYPOINTS_NUM"
 Defines MV_IMAGE_RECOGNITION_OBJECT_MAX_KEYPOINTS_NUM to set the maximum keypoints should be detected on the image attribute of the engine configuration.
#define MV_IMAGE_RECOGNITION_SCENE_SCALE_FACTOR   "MV_IMAGE_RECOGNITION_SCENE_SCALE_FACTOR"
 Defines MV_IMAGE_RECOGNITION_SCENE_SCALE_FACTOR to set the scene scale factor attribute of the engine configuration.
#define MV_IMAGE_RECOGNITION_SCENE_MAX_KEYPOINTS_NUM   "MV_IMAGE_RECOGNITION_SCENE_MAX_KEYPOINTS_NUM"
 Defines MV_IMAGE_RECOGNITION_SCENE_MAX_KEYPOINTS_NUM to set the maximum keypoints should be detected on the scene attribute of the engine configuration.
#define MV_IMAGE_RECOGNITION_MIN_MATCH_NUM   "MV_IMAGE_RECOGNITION_MIN_MATCH_NUM"
 Defines MV_IMAGE_RECOGNITION_MIN_MATCH_NUM to set the minimum number of keypoints matches required for recognition attribute of the engine configuration.
#define MV_IMAGE_RECOGNITION_REQ_MATCH_PART   "MV_IMAGE_RECOGNITION_REQ_MATCH_PART"
 Defines MV_IMAGE_RECOGNITION_REQ_MATCH_PART to set the required matching part for the image recognition attribute of the engine configuration.
#define MV_IMAGE_RECOGNITION_TOLERANT_MATCH_PART_ERR   "MV_IMAGE_RECOGNITION_TOLERANT_MATCH_PART_ERR"
 Defines MV_IMAGE_RECOGNITION_TOLERANT_MATCH_PART_ERR to set the part matching error for the image recognition attribute of the engine configuration.
#define MV_IMAGE_TRACKING_HISTORY_AMOUNT   "MV_IMAGE_TRACKING_HISTORY_AMOUNT"
 Defines MV_IMAGE_TRACKING_HISTORY_AMOUNT to set the number of recognition results in the tracking history attribute of the engine configuration.
#define MV_IMAGE_TRACKING_EXPECTED_OFFSET   "MV_IMAGE_TRACKING_EXPECTED_OFFSET"
 Defines MV_IMAGE_TRACKING_EXPECTED_OFFSET to set the expected tracking offset attribute of the engine configuration.
#define MV_IMAGE_TRACKING_USE_STABLIZATION   "MV_IMAGE_TRACKING_USE_STABLIZATION"
 Defines MV_IMAGE_TRACKING_USE_STABLIZATION to enable the contour stabilization during tracking process. Default value is true.
#define MV_IMAGE_TRACKING_STABLIZATION_TOLERANT_SHIFT   "MV_IMAGE_TRACKING_STABLIZATION_TOLERANT_SHIFT"
 Defines MV_IMAGE_TRACKING_STABLIZATION_TOLERANT_SHIFT to set the relative tolerant shift for the tracking stabilization attribute of the engine configuration.
#define MV_IMAGE_TRACKING_STABLIZATION_SPEED   "MV_IMAGE_TRACKING_STABLIZATION_SPEED"
 Defines MV_IMAGE_TRACKING_STABLIZATION_SPEED to set the speed of the tracking stabilization attribute of the engine configuration.
#define MV_IMAGE_TRACKING_STABLIZATION_ACCELERATION   "MV_IMAGE_TRACKING_STABLIZATION_ACCELERATION"
 Defines MV_IMAGE_TRACKING_STABLIZATION_ACCELERATION to set the acceleration of the tracking stabilization attribute of the engine configuration.

Define Documentation

#define MV_IMAGE_RECOGNITION_MIN_MATCH_NUM   "MV_IMAGE_RECOGNITION_MIN_MATCH_NUM"

Defines MV_IMAGE_RECOGNITION_MIN_MATCH_NUM to set the minimum number of keypoints matches required for recognition attribute of the engine configuration.

The minimal number of keypoints should be matched between an image and a scene. It will be taken into account for image objects recognition. Value is unsigned integer and the default is 30

Since :
3.0
See also:
mv_engine_config_set_int_attribute()
mv_engine_config_get_int_attribute()
#define MV_IMAGE_RECOGNITION_OBJECT_MAX_KEYPOINTS_NUM   "MV_IMAGE_RECOGNITION_OBJECT_MAX_KEYPOINTS_NUM"

Defines MV_IMAGE_RECOGNITION_OBJECT_MAX_KEYPOINTS_NUM to set the maximum keypoints should be detected on the image attribute of the engine configuration.

The maximal number of keypoints can be selected on the image object to calculate descriptors. This keypoints will be used for image (object) recognition and has to be specified as integer number and the default is 1000

Since :
3.0
See also:
mv_engine_config_set_int_attribute()
mv_engine_config_get_int_attribute()
#define MV_IMAGE_RECOGNITION_OBJECT_SCALE_FACTOR   "MV_IMAGE_RECOGNITION_OBJECT_SCALE_FACTOR"

Defines MV_IMAGE_RECOGNITION_OBJECT_SCALE_FACTOR to set the image to be recognized scale factor attribute of the engine configuration.

The value of the factor will be used for resizing of the images (objects) for recognition. Scale factor is the double value and the default is 1.2

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_RECOGNITION_REQ_MATCH_PART   "MV_IMAGE_RECOGNITION_REQ_MATCH_PART"

Defines MV_IMAGE_RECOGNITION_REQ_MATCH_PART to set the required matching part for the image recognition attribute of the engine configuration.

To recognize occluded or hidden an image by other images, required relative part of the matches in respect to the total amount of matching keypoints required for image recognition. Too low value will result in unsustainable behavior, but effect of object overlapping will be reduced. Value can be from 0 to 1 and the default is 0.05

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_RECOGNITION_SCENE_MAX_KEYPOINTS_NUM   "MV_IMAGE_RECOGNITION_SCENE_MAX_KEYPOINTS_NUM"

Defines MV_IMAGE_RECOGNITION_SCENE_MAX_KEYPOINTS_NUM to set the maximum keypoints should be detected on the scene attribute of the engine configuration.

The maximal number of keypoints can be selected on the scene including the images (objects) to calculate descriptors. This keypoints will be used for image recognition and has to be specified as unsigned integer and the default is 5000

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_RECOGNITION_SCENE_SCALE_FACTOR   "MV_IMAGE_RECOGNITION_SCENE_SCALE_FACTOR"

Defines MV_IMAGE_RECOGNITION_SCENE_SCALE_FACTOR to set the scene scale factor attribute of the engine configuration.

The value of the factor will be used for resizing of the scene including the images (objects) for recognition. Scale factor is the double value and the default is 1.2

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_RECOGNITION_TOLERANT_MATCH_PART_ERR   "MV_IMAGE_RECOGNITION_TOLERANT_MATCH_PART_ERR"

Defines MV_IMAGE_RECOGNITION_TOLERANT_MATCH_PART_ERR to set the part matching error for the image recognition attribute of the engine configuration.

Allowable error of matches number. Value can be from 0 to 1 and the default is 0.1

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_TRACKING_EXPECTED_OFFSET   "MV_IMAGE_TRACKING_EXPECTED_OFFSET"

Defines MV_IMAGE_TRACKING_EXPECTED_OFFSET to set the expected tracking offset attribute of the engine configuration.

Relative offset value, for which the object offset is expected (relative to the object size in the current frame). Value is a double and the default is 0

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_TRACKING_HISTORY_AMOUNT   "MV_IMAGE_TRACKING_HISTORY_AMOUNT"

Defines MV_IMAGE_TRACKING_HISTORY_AMOUNT to set the number of recognition results in the tracking history attribute of the engine configuration.

Number of previous recognition results, which will influence the stabilization. Value is unsigned integer and the default is 3

Since :
3.0
See also:
mv_engine_config_set_int_attribute()
mv_engine_config_get_int_attribute()
#define MV_IMAGE_TRACKING_STABLIZATION_ACCELERATION   "MV_IMAGE_TRACKING_STABLIZATION_ACCELERATION"

Defines MV_IMAGE_TRACKING_STABLIZATION_ACCELERATION to set the acceleration of the tracking stabilization attribute of the engine configuration.

Acceleration will be used for image stabilization (relative to the distance from current location to stabilized location). Value is double from 0 to 1 and the default is 0.1

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_TRACKING_STABLIZATION_SPEED   "MV_IMAGE_TRACKING_STABLIZATION_SPEED"

Defines MV_IMAGE_TRACKING_STABLIZATION_SPEED to set the speed of the tracking stabilization attribute of the engine configuration.

Start speed will be used for image stabilization. Value is a double and the default is 0.3

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_TRACKING_STABLIZATION_TOLERANT_SHIFT   "MV_IMAGE_TRACKING_STABLIZATION_TOLERANT_SHIFT"

Defines MV_IMAGE_TRACKING_STABLIZATION_TOLERANT_SHIFT to set the relative tolerant shift for the tracking stabilization attribute of the engine configuration.

It is component of tolerant shift which will be ignored by stabilization process. (this value is relative to the object size in the current frame). Tolerant shift will be computed like R * S + C, where R - value set to MV_IMAGE_TRACKING_STABLIZATION_TOLERANT_SHIFT, S - area of object location on frame, C - constant value equal 1.3. Value is a double

Since :
3.0
See also:
mv_engine_config_set_double_attribute()
mv_engine_config_get_double_attribute()
#define MV_IMAGE_TRACKING_USE_STABLIZATION   "MV_IMAGE_TRACKING_USE_STABLIZATION"

Defines MV_IMAGE_TRACKING_USE_STABLIZATION to enable the contour stabilization during tracking process. Default value is true.

Since :
3.0
See also:
mv_engine_config_set_bool_attribute()
mv_engine_config_get_bool_attribute()

Typedef Documentation

typedef void* mv_image_object_h

The image object's type handle.

Since :
3.0
typedef void(* mv_image_recognized_cb)(mv_source_h source, mv_engine_config_h engine_cfg, const mv_image_object_h *image_objects, mv_quadrangle_s **locations, unsigned int number_of_objects, void *user_data)

Called when image recognition results are received from mv_image_recognize()

This type of callback will be called after mv_image_recognize() in order to process recognition result.

Since :
3.0
Remarks:
Values source, engine_cfg, image_objects, and number_of_objects are the same as values of input parameters of mv_image_recognize().
locations are valid only inside callback.
Parameters:
[in]sourceThe handle to the source image on which the recognition was carried out
[in]engine_cfgThe handle to the configuration of engine that was used for image recognition, or NULL if default settings were applied
[in]image_objectsThe set of handles to the image objects which have been processed as targets of recognition
[in]locationsThe locations of image objects on the source image. This array corresponding to an array of image objects and each element contains a location of corresponding object on the source image or NULL if object is not recognized
[in]number_of_objectsThe number of image objects and corresponding locations
[in]user_dataThe user data passed from the mv_image_recognize() function
Precondition:
Call mv_image_recognize() function to perform recognition of the image objects on the source image and invoke this callback as a result
See also:
mv_image_recognize()
mv_source_h
mv_image_object_h
mv_engine_config_h
mv_quadrangle_s
typedef void(* mv_image_tracked_cb)(mv_source_h source, mv_image_tracking_model_h image_tracking_model, mv_engine_config_h engine_cfg, mv_quadrangle_s *location, void *user_data)

Called when image tracking result received from mv_image_track()

Image tracking on a sequence of frames assumes calling mv_image_track() function for each frame in the correct order. This type of callback will be called after each mv_image_track() call for processing result data.

Since :
3.0
Remarks:
If image object is not tracked then the callback will be invoked, but location will be NULL.
Handles image_tracking_model, source and engine_cfg the same as input parameters of mv_image_track().
location pointer is valid only inside callback
Parameters:
[in]sourceThe handle to the source image on which the tracking was carried out
[in]image_tracking_modelThe handle to the image tracking model which processed as target of tracking
[in]engine_cfgThe handle to the configuration of engine that was used to image tracking, or NULL if default settings were applied
[in]locationThe image object location on the source image or NULL if objects is not tracked
[in]user_dataThe user data passed from the mv_image_track() function
Precondition:
Call mv_image_track() function to perform tracking of the image object on the current image from the sequence and invoke this callback as a result
See also:
mv_image_track()
mv_source_h
image_tracking_model_h
mv_engine_config_h
mv_quadrangle_s

The image tracking model's type handle.

Since :
3.0

Function Documentation

Clones the image object.

Since :
3.0
Remarks:
dst must be released using mv_image_object_destroy().
Parameters:
[in]srcThe handle to the source image object
[out]dstThe handle to the destination image object
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_SUPPORTEDNot supported
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
Create image object handles by calling mv_image_object_create()
See also:
mv_image_object_create()
mv_image_object_destroy()
int mv_image_object_create ( mv_image_object_h image_object)

Creates an image object.

Since :
3.0
Parameters:
[out]image_objectA new handle to the image object
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_SUPPORTEDNot supported
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
Postcondition:
Release image object by using mv_image_object_destroy()
See also:
mv_image_object_destroy()
mv_image_object_h

Destroys the image object.

Since :
3.0
Parameters:
[in]image_objectThe handle to the image 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
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
Precondition:
Create image object by using mv_image_object_create()
See also:
mv_image_object_create()
mv_image_object_h
int mv_image_object_fill ( mv_image_object_h  image_object,
mv_engine_config_h  engine_cfg,
mv_source_h  source,
mv_rectangle_s location 
)

Fills the image object.

Extracts data from source image which will be needed for recognition of depicted object in location.

Since :
3.0
Remarks:
After filling the image object it can be evaluated by mv_image_object_get_recognition_rate(). If recognition rate is too low, try to use another image of object or change configuration parameters (see mv_engine_config_h) and construct the image object again.
Parameters:
[in,out]image_objectThe handle to the image object which will be filled and can be recognized in future
[in]engine_cfgThe handle to the configuration of engine which will be used for extract recognition data from source. If NULL, then default settings will be used.
[in]sourceThe source image where image object is depicted
[in]locationThe pointer to location of the image object on the source image, or NULL if the object is shown in full
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_NOT_SUPPORTEDNot supported
Precondition:
Create image object by using mv_image_object_create()
Postcondition:
Release image object by using mv_image_object_destroy()
See also:
mv_image_object_h
mv_image_object_create()
mv_image_object_get_recognition_rate()
mv_image_recognize()
mv_image_object_destroy()
mv_engine_config_h
int mv_image_object_get_label ( mv_image_object_h  image_object,
int *  label 
)

Gets a label of image object.

Since :
3.0
Remarks:
If image_object have not a label, this function return MEDIA_VISION_ERROR_NO_DATA value.
Parameters:
[in]image_objectThe handle to the image object from which a label will be received
[out]labelThe label of image object
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_NO_DATAImage object hasn't label
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
Precondition:
Create image object by using mv_image_object_create()
Set label for the image object by using mv_image_object_set_label()
Postcondition:
Release image object by using mv_image_object_destroy()
See also:
mv_image_object_set_label()
mv_image_object_h
mv_image_object_create()
mv_image_object_destroy()
int mv_image_object_get_recognition_rate ( mv_image_object_h  image_object,
double *  recognition_rate 
)

Gets a value that determines how well an image object can be recognized.

Recognition rate determines how well an image object can be recognized. This value can be from 0 to 1. If the recognition rate is 0 object can not be recognized and the bigger it is the more likely to recognize the object.

Since :
3.0
Remarks:
If recognition rate is too low, try to use another image of object or change some configuration parameters (see mv_engine_config_h) and fill the image object again (see mv_image_object_fill()).
Parameters:
[in]image_objectThe handle to the image object which will be evaluated by this function
[out]recognition_rateA value that determines how well an image object can be recognized, if 0 then object can not be recognized
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_SUPPORTEDNot supported
Precondition:
Create image object by using mv_image_object_create()
Postcondition:
Release image object by using mv_image_object_destroy()
See also:
mv_image_object_h
mv_image_object_create()
mv_image_object_fill()
mv_image_object_destroy()
mv_engine_config_h
int mv_image_object_load ( const char *  file_name,
mv_image_object_h image_object 
)

Loads an image object from the file.

Since :
3.0
Remarks:
image_object is loaded from the absolute path directory. Use app_get_data_path for the private app storage path. image_object must be destroyed using mv_image_object_destroy().
Parameters:
[in]file_nameName of path/file to load the image object
[out]image_objectThe handle to the image object which will be filled
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_PATHInvalid path
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_VISION_ERROR_PERMISSION_DENIEDNot permitted
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
Precondition:
Image object can be preliminary saved with mv_image_object_save() function
See also:
mv_image_object_save()
mv_image_object_destroy()
int mv_image_object_save ( const char *  file_name,
mv_image_object_h  image_object 
)

Saves the image object.

Since :
3.0
Remarks:
image_object is saved to the absolute path directory. Use app_get_data_path for the private app storage path.
Parameters:
[in]file_nameName of the file to path/save the image object
[in]image_objectThe handle to the image object which will be saved
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_PATHInvalid path
MEDIA_VISION_ERROR_PERMISSION_DENIEDNot permitted
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
Precondition:
Create image object handle by calling mv_image_object_create()
Postcondition:
Saved model can be loaded later by calling mv_image_object_load() function
See also:
mv_image_object_create()
mv_image_object_load()
mv_image_object_destroy()
int mv_image_object_set_label ( mv_image_object_h  image_object,
int  label 
)

Sets a label for the image object.

Since :
3.0
Parameters:
[in]image_objectThe handle to the image object for which the label will be assigned
[in]labelThe label which will be assigned to the image object
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_SUPPORTEDNot supported
Precondition:
Create image object by using mv_image_object_create()
Postcondition:
Label could be received by using mv_image_object_get_label()
Release image object by using mv_image_object_destroy()
See also:
mv_image_object_get_label()
mv_image_object_h
mv_image_object_create()
mv_image_object_destroy()
int mv_image_recognize ( mv_source_h  source,
const mv_image_object_h image_objects,
int  number_of_objects,
mv_engine_config_h  engine_cfg,
mv_image_recognized_cb  recognized_cb,
void *  user_data 
)

Recognizes the given image objects on the source image.

Use this function to launch image recognition algorithm configured by engine_conf configuration.

Since :
3.0
Parameters:
[in]sourceThe handle to the source image on which image objects will be recognized
[in]image_objectsThe set of handles to the image objects which will be processed as targets of recognition
[in]number_of_objectsThe number of image objects
[in]engine_cfgThe handle to the configuration of engine which will be used for recognition. If NULL, then default settings will be used.
[in]recognized_cbThe callback which will be called in order to process recognition result
[in]user_dataThe user data to be passed to the recognized_cb
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_NOT_SUPPORTEDNot supported
Precondition:
Create a set of image objects using mv_image_object_create() for each of them and construct (fill / load / clone) them on images that will be recognized
Create a source handle by calling mv_create_source() and fill by the image for which recognition will be performed
Postcondition:
mv_image_recognized_cb will be called to process recognition result
Release source image by using mv_destroy_source()
Release image objects by using mv_image_object_destroy() for each handle from image_objects set
See also:
mv_image_recognized_cb
mv_source_h
mv_create_source()
mv_destroy_source()
mv_image_object_h
mv_image_object_create()
mv_image_object_destroy()
mv_engine_config_h
int mv_image_track ( mv_source_h  source,
mv_image_tracking_model_h  image_tracking_model,
mv_engine_config_h  engine_cfg,
mv_image_tracked_cb  tracked_cb,
void *  user_data 
)

Tracks the given image tracking model on the current frame.

Image tracking on a sequence of frames assumes calling this function for each frame in the correct order. tracked_cb will be called for result processing.

Since :
3.0
Remarks:
Tracking algorithm is usually using for recognition of image object on the sequence of images that are organized by time. For example, it may be the sequence of frames from a video stream.
If object is lost during the tracking, system tries to find it further for the following frames. Therefore, tracking will be recovered when object appears again.
Previous calls of mv_image_track() for this image_tracking_model will affect on current call
Parameters:
[in]sourceThe handle to the current image of sequence where image tracking model will be tracked
[in,out]image_tracking_modelThe handle to the image tracking model which processed as target of tracking
[in]engine_cfgThe handle to the configuration of engine which will be used for tracking. If NULL, then default settings will be used.
[in]tracked_cbThe callback which will receive tracking results
[in]user_dataThe user data to be passed to the tracked_cb
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_NOT_SUPPORTEDNot supported
Precondition:
Create image tracking model by calling mv_image_tracking_model_create() and set target by calling mv_image_tracking_model_set_target()
Create a source images by calling mv_create_source() for each of them and construct them based on sequence of images for which will be held image tracking
Postcondition:
tracked_cb will be called to process tracking result
Release image tracking model by using mv_image_tracking_model_destroy()
See also:
mv_image_tracked_cb
mv_source_h
image_tracking_model_h
mv_image_tracking_model_create()
mv_image_tracking_model_set_target()
mv_image_tracking_model_destroy()

Clones the image tracking model.

Since :
3.0
Remarks:
dst must be released using mv_image_tracking_model_destroy().
Parameters:
[in]srcThe handle to the source image tracking model
[out]dstThe handle to the destination image tracking model
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_SUPPORTEDNot supported
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
Create image tracking model handles by calling mv_image_tracking_model_create()
See also:
mv_image_tracking_model_create()
mv_image_tracking_model_destroy()

Creates an image tracking model.

Since :
3.0
Parameters:
[out]image_tracking_modelA new handle to the image tracking model
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_SUPPORTEDNot supported
Postcondition:
Release image tracking model by using mv_image_tracking_model_destroy()
See also:
mv_image_tracking_model_destroy()

Destroys the image tracking model.

Since :
3.0
Parameters:
[in]image_tracking_modelThe handle to the image tracking model to be destroyed
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_SUPPORTEDNot supported
Precondition:
Create image tracking model by using mv_image_tracking_model_create()
See also:
mv_image_tracking_model_create()
int mv_image_tracking_model_load ( const char *  file_name,
mv_image_tracking_model_h image_tracking_model 
)

Loads an image tracking model from the file.

Since :
3.0
Remarks:
image_tracking_model is loaded from the absolute path directory. Use app_get_data_path for the private app storage path. image_tracking_model must be destroyed using mv_image_tracking_model_destroy.
Parameters:
[in]file_nameName of path/file to load model
[out]image_tracking_modelThe handle to the image tracking model to be filled
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_PATHInvalid path
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_VISION_ERROR_PERMISSION_DENIEDNot permitted
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
Precondition:
Image tracking model handle can be preliminary saved with mv_image_tracking_model_save() function
See also:
mv_image_tracking_model_save()
mv_image_tracking_model_destroy()
int mv_image_tracking_model_refresh ( mv_image_tracking_model_h  image_tracking_model,
mv_engine_config_h  engine_cfg 
)

Refreshes the state of image tracking model.

Clears moving history and change state to undetected. This function is usually called 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. Tracking algorithm will try to find image by itself.

Since :
3.0
Parameters:
[in]image_tracking_modelThe handle to the image tracking model which will be refreshed
[in]engine_cfgThe handle to the configuration of engine which will be used. If NULL, then default settings will be used.
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_SUPPORTEDNot supported
Precondition:
Create image tracking model by calling mv_image_tracking_model_create()
Postcondition:
Release image tracking model by using mv_image_tracking_model_destroy()
See also:
mv_image_tracking_model_h
mv_image_tracking_model_create()
mv_image_track()
mv_image_tracking_model_destroy()
int mv_image_tracking_model_save ( const char *  file_name,
mv_image_tracking_model_h  image_tracking_model 
)

Saves the image tracking model.

Since :
3.0
Remarks:
image_tracking_model is saved to the absolute path directory. Use app_get_data_path for the private app storage path.
Parameters:
[in]file_nameName of path/file to save the model
[in]image_tracking_modelThe handle to the image tracking model to be saved
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_PATHInvalid path
MEDIA_VISION_ERROR_PERMISSION_DENIEDNot permitted
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
Precondition:
Create image tracking model handle by calling mv_image_tracking_model_create()
Postcondition:
Saved model can be loaded later by calling mv_image_tracking_model_load() function
See also:
mv_image_tracking_model_create()
mv_image_tracking_model_load()
mv_image_tracking_model_destroy()
int mv_image_tracking_model_set_target ( mv_image_object_h  image_object,
mv_image_tracking_model_h  image_tracking_model 
)

Sets target of image tracking model.

Sets image object which will be tracked by using tracking functionality with image_tracking_model.

Since :
3.0
Parameters:
[in]image_objectImage object which will be set as target for tracking
[in]image_tracking_modelHandle to the image tracking model for which will be set a new target
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_SUPPORTEDNot supported
Precondition:
Create image tracking model by calling mv_image_tracking_model_create()
Create an image object using mv_image_object_create() and construct (fill / load / clone) it on image that will be tracking
Postcondition:
Release image object by using mv_image_object_destroy()
Release image tracking model by using mv_image_tracking_model_destroy()
See also:
mv_image_object_h
mv_image_tracking_model_h
mv_image_object_create()
mv_image_object_destroy()
mv_image_tracking_model_create()
mv_image_track()
mv_image_tracking_model_destroy()