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]	source	The handle to the source image on which the recognition was carried out
[in]	engine_cfg	The handle to the configuration of engine that was used for image recognition, or NULL if default settings were applied
[in]	image_objects	The set of handles to the image objects which have been processed as targets of recognition
[in]	locations	The 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_objects	The number of image objects and corresponding locations
[in]	user_data	The 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]	source	The handle to the source image on which the tracking was carried out
[in]	image_tracking_model	The handle to the image tracking model which processed as target of tracking
[in]	engine_cfg	The handle to the configuration of engine that was used to image tracking, or NULL if default settings were applied
[in]	location	The image object location on the source image or NULL if objects is not tracked
[in]	user_data	The 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; mv_image_tracking_model_h; mv_engine_config_h; mv_quadrangle_s

typedef void* mv_image_tracking_model_h

The image tracking model's type handle.

Since :: 3.0

Function Documentation

int mv_image_object_clone	(	mv_image_object_h	src,
		mv_image_object_h *	dst
	)

Clones the image object.

Since :: 3.0

Remarks:: dst must be released using mv_image_object_destroy().

Parameters:

[in]	src	The handle to the source image object
[out]	dst	The handle to the destination image object

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_OUT_OF_MEMORY	Out 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_object A new handle to the image object

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

Return values:

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

Postcondition:: Release image object by using mv_image_object_destroy()

See also:: mv_image_object_destroy(); mv_image_object_h

int mv_image_object_destroy ( mv_image_object_h image_object )

Destroys the image object.

Since :: 3.0

Parameters:

[in] image_object The handle to the image object to be destroyed

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_object	The handle to the image object which will be filled and can be recognized in future
[in]	engine_cfg	The 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]	source	The source image where image object is depicted
[in]	location	The 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_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT	Source colorspace isn't supported
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_object	The handle to the image object from which a label will be received
[out]	label	The label of image object

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NO_DATA	Image object hasn't label
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_object	The handle to the image object which will be evaluated by this function
[out]	recognition_rate	A 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_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_name	Name of path/file to load the image object
[out]	image_object	The handle to the image object which will be filled

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_INVALID_PATH	Invalid path
MEDIA_VISION_ERROR_OUT_OF_MEMORY	Out of memory
MEDIA_VISION_ERROR_PERMISSION_DENIED	Not permitted
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_name	Name of the file to path/save the image object
[in]	image_object	The handle to the image object which will be saved

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_INVALID_PATH	Invalid path
MEDIA_VISION_ERROR_PERMISSION_DENIED	Not permitted
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_object	The handle to the image object for which the label will be assigned
[in]	label	The label which will be assigned to the image object

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_cfg configuration.

Since :: 3.0

Parameters:

[in]	source	The handle to the source image on which image objects will be recognized
[in]	image_objects	The set of handles to the image objects which will be processed as targets of recognition
[in]	number_of_objects	The number of image objects
[in]	engine_cfg	The handle to the configuration of engine which will be used for recognition. If NULL, then default settings will be used.
[in]	recognized_cb	The callback which will be called in order to process recognition result
[in]	user_data	The user data to be passed to the recognized_cb

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT	Source colorspace isn't supported
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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]	source	The handle to the current image of sequence where image tracking model will be tracked
[in,out]	image_tracking_model	The handle to the image tracking model which processed as target of tracking
[in]	engine_cfg	The handle to the configuration of engine which will be used for tracking. If NULL, then default settings will be used.
[in]	tracked_cb	The callback which will receive tracking results
[in]	user_data	The user data to be passed to the tracked_cb

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED_FORMAT	Source colorspace isn't supported
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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; mv_image_tracking_model_h; mv_image_tracking_model_create(); mv_image_tracking_model_set_target(); mv_image_tracking_model_destroy()

int mv_image_tracking_model_clone	(	mv_image_tracking_model_h	src,
		mv_image_tracking_model_h *	dst
	)

Clones the image tracking model.

Since :: 3.0

Remarks:: dst must be released using mv_image_tracking_model_destroy().

Parameters:

[in]	src	The handle to the source image tracking model
[out]	dst	The handle to the destination image tracking model

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_OUT_OF_MEMORY	Out 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()

int mv_image_tracking_model_create ( mv_image_tracking_model_h * image_tracking_model )

Creates an image tracking model.

Since :: 3.0

Parameters:

[out] image_tracking_model A new handle to the image tracking model

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported

Postcondition:: Release image tracking model by using mv_image_tracking_model_destroy()

See also:: mv_image_tracking_model_destroy()

int mv_image_tracking_model_destroy ( mv_image_tracking_model_h image_tracking_model )

Destroys the image tracking model.

Since :: 3.0

Parameters:

[in] image_tracking_model The handle to the image tracking model to be destroyed

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_name	Name of path/file to load model
[out]	image_tracking_model	The handle to the image tracking model to be filled

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_INVALID_PATH	Invalid path
MEDIA_VISION_ERROR_OUT_OF_MEMORY	Out of memory
MEDIA_VISION_ERROR_PERMISSION_DENIED	Not permitted
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_model	The handle to the image tracking model which will be refreshed
[in]	engine_cfg	The 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_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_name	Name of path/file to save the model
[in]	image_tracking_model	The handle to the image tracking model to be saved

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

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_INVALID_PATH	Invalid path
MEDIA_VISION_ERROR_PERMISSION_DENIED	Not permitted
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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_object	Image object which will be set as target for tracking
[in]	image_tracking_model	Handle 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_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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()

Required Header

Related Features

Overview

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Function Documentation