Tizen Native API  5.0
Media Vision Surveillance

Video surveillance module.

Required Header

#include <mv_surveillance.h>

Related Features

This API is related with the following features:

  • http://tizen.org/feature/vision.image_recognition
  • http://tizen.org/feature/vision.face_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 Surveillance provides functionality can be utilized for creation of video surveillance systems. The main idea underlying surveillance is event subscription model. By default, supported event types are described in Media Vision Surveillance Event Types section. mv_surveillance_subscribe_event_trigger() function has to be used to create subscription to the particular event trigger. Triggers are handled by mv_surveillance_event_trigger_h type. Such type handlers can be created with mv_surveillance_event_trigger_create() function and destroyed with mv_surveillance_event_trigger_destroy() function. Once event trigger subscription is created, corresponding mv_surveillance_event_occurred_cb() callback will be invoked each time when event is detected, i.e. trigger is activated. mv_surveillance_result_h event detection result handler will be passed to the callback together with identifier of the video stream where event was detected and mv_source_h handler containing frame in which detection was performed. It is possible to retrieve specific to event type result values using mv_surveillance_result_h handler. In the mv_surveillance_get_result_value() function documentation can be found detailed description of result values retrieving. Following table contains general events and corresponding event detection results can be obtained by this approach:

Event Event result values
MV_SURVEILLANCE_EVENT_TYPE_MOVEMENT_DETECTED MV_SURVEILLANCE_MOVEMENT_NUMBER_OF_REGIONS;
MV_SURVEILLANCE_MOVEMENT_REGIONS
MV_SURVEILLANCE_EVENT_TYPE_PERSON_APPEARED_DISAPPEARED MV_SURVEILLANCE_PERSONS_APPEARED_NUMBER;
MV_SURVEILLANCE_PERSONS_DISAPPEARED_NUMBER;
MV_SURVEILLANCE_PERSONS_TRACKED_NUMBER;
MV_SURVEILLANCE_PERSONS_APPEARED_LOCATIONS;
MV_SURVEILLANCE_PERSONS_DISAPPEARED_LOCATIONS;
MV_SURVEILLANCE_PERSONS_TRACKED_LOCATIONS
MV_SURVEILLANCE_EVENT_TYPE_PERSON_RECOGNIZED MV_SURVEILLANCE_PERSONS_RECOGNIZED_NUMBER;
MV_SURVEILLANCE_PERSONS_RECOGNIZED_LOCATIONS;
MV_SURVEILLANCE_PERSONS_RECOGNIZED_LABELS;
MV_SURVEILLANCE_PERSONS_RECOGNIZED_CONFIDENCES

Before subscription of the event trigger with mv_surveillance_subscribe_event_trigger() call it is possible to create mv_engine_config_h handle and configure following attributes:

Created engine config has to be used as a parameter of mv_surveillance_subscribe_event_trigger() to apply the configuration. If NULL will be passed instead of valid mv_engine_config_h handle, then default attribute values will be used for subscriptions. To make surveillance system work with video sequences mv_surveillance_push_source() function has to be used for each frame in the sequence in the correct order. Multiple video sources can be supported by the system. To distinguish different video sources unique stream identifier has to be assigned to each subscription. Then, particular identifier can be passed as a parameter to the mv_surveillance_push_source() function. After pushing the source to the surveillance system, it will notify all triggers which were subscribed to process frames coming from video stream which source has been pushed. If trigger(s) is(are) activated on the source, then corresponding callback(s) of mv_surveillance_event_occurred_cb() type will be called. Additionally, region where event detection will be performed by the triggers can be set with mv_surveillance_set_event_trigger_roi() function and gotten with mv_surveillance_get_event_trigger_roi(). ROI is specified independently for the each event trigger, so it is possible to detect events of different types in the different parts of the incoming frames. Event trigger subscription can be stopped any time using mv_surveillance_unsubscribe_event_trigger() function. Additionally, mv_surveillance_foreach_supported_event_type() and mv_surveillance_foreach_event_result_name() functions can be found useful if it is required to obtain supported event types list or result value names list dynamically.

Functions

int mv_surveillance_event_trigger_create (const char *event_type, mv_surveillance_event_trigger_h *trigger)
 Creates surveillance event trigger handle.
int mv_surveillance_event_trigger_destroy (mv_surveillance_event_trigger_h trigger)
 Destroys the surveillance event trigger handle and releases all its resources.
int mv_surveillance_get_event_trigger_type (mv_surveillance_event_trigger_h trigger, char **event_type)
 Gets the surveillance event trigger type as character string.
int mv_surveillance_set_event_trigger_roi (mv_surveillance_event_trigger_h trigger, int number_of_points, mv_point_s *roi)
 Sets ROI (Region Of Interest) to the event trigger.
int mv_surveillance_get_event_trigger_roi (mv_surveillance_event_trigger_h trigger, int *number_of_points, mv_point_s **roi)
 Gets ROI (Region Of Interest) from the event trigger.
int mv_surveillance_subscribe_event_trigger (mv_surveillance_event_trigger_h trigger, int video_stream_id, mv_engine_config_h engine_cfg, mv_surveillance_event_occurred_cb callback, void *user_data)
 Subscribes trigger to process sources pushed from video identified by video_stream_id.
int mv_surveillance_unsubscribe_event_trigger (mv_surveillance_event_trigger_h trigger, int video_stream_id)
 Unsubscribes trigger from the event and stop calling callback.
int mv_surveillance_push_source (mv_source_h source, int video_stream_id)
 Pushes source to the surveillance system to detect events.
int mv_surveillance_foreach_supported_event_type (mv_surveillance_event_type_cb callback, void *user_data)
 Starts traversing through list of supported event types.
int mv_surveillance_foreach_event_result_name (const char *event_type, mv_surveillance_event_result_name_cb callback, void *user_data)
 Starts traversing through list of supported event result value names.
int mv_surveillance_get_result_value (mv_surveillance_result_h result, const char *name, void *value)
 Gets result value.

Typedefs

typedef void * mv_surveillance_event_trigger_h
 The handle to event trigger.
typedef void * mv_surveillance_result_h
 The handle to event trigger activation result.
typedef void(* mv_surveillance_event_occurred_cb )(mv_surveillance_event_trigger_h trigger, mv_source_h source, int video_stream_id, mv_surveillance_result_h event_result, void *user_data)
 Called when event trigger activation has been detected.
typedef bool(* mv_surveillance_event_type_cb )(const char *event_type, void *user_data)
 Called to get the information once for each supported event type.
typedef bool(* mv_surveillance_event_result_name_cb )(const char *name, void *user_data)
 Called to get the result name from the triggered event.

Defines

#define MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH   "MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH"
 Defines MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH to set face recognition model file path. It is an attribute of the engine configuration.
#define MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD   "MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD"
 Defines MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD to set movement detection threshold. It is an attribute of the engine configuration.
#define MV_SURVEILLANCE_SKIP_FRAMES_COUNT   "MV_SURVEILLANCE_SKIP_FRAMES_COUNT"
 Defines MV_SURVEILLANCE_SKIP_FRAMES_COUNT to set how many frames will be skipped during push source. It is an attribute of the engine configuration.

Define Documentation

#define MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH   "MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH"

Defines MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH to set face recognition model file path. It is an attribute of the engine configuration.

This value HAS TO BE set in engine configuration before subscription on MV_SURVEILLANCE_EVENT_TYPE_PERSON_RECOGNIZED event trigger

Since :
3.0
See also:
mv_engine_config_set_string_attribute()
mv_engine_config_get_string_attribute()
#define MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD   "MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD"

Defines MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD to set movement detection threshold. It is an attribute of the engine configuration.

This value might be set in engine configuration before subscription on MV_SURVEILLANCE_EVENT_TYPE_MOVEMENT_DETECTED event trigger to specify sensitivity of the movement detector. This value has to be integer in 0..255 range where 255 means that no movements will be detected, and 0 means that all frame changes will be interpreted as movements. Default value is 10.

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

Defines MV_SURVEILLANCE_SKIP_FRAMES_COUNT to set how many frames will be skipped during push source. It is an attribute of the engine configuration.

This integer value might be set in engine configuration to specify number of mv_surveillance_push_source() function calls will be ignored by subscription of the event trigger. Default value is 0. It means that no frames will be skipped and all mv_surveillance_push_source() function calls will be processed.

Since :
3.0
See also:
mv_engine_config_set_int_attribute()
mv_engine_config_get_int_attribute()

Typedef Documentation

typedef void(* mv_surveillance_event_occurred_cb)(mv_surveillance_event_trigger_h trigger, mv_source_h source, int video_stream_id, mv_surveillance_result_h event_result, void *user_data)

Called when event trigger activation has been detected.

Since :
3.0
Remarks:
Handle event_result is valid only inside callback
Parameters:
[in]triggerThe event trigger handle
[in]sourceThe handle to the media source
[in]video_stream_idThe identifier of the video source where event has been detected
[in]event_resultThe event result passed from the mv_surveillance_subscribe_event_trigger()
[in]user_dataThe user data passed from the mv_surveillance_subscribe_event_trigger() function
Precondition:
Callback can be invoked only after mv_surveillance_subscribe_event_trigger() was called for particular event trigger.
See also:
mv_surveillance_subscribe_event_trigger()
mv_surveillance_unsubscribe_event_trigger()
typedef bool(* mv_surveillance_event_result_name_cb)(const char *name, void *user_data)

Called to get the result name from the triggered event.

Since :
3.0
Remarks:
Don't release memory of value_name
Parameters:
[in]nameCharacter string containing the name of value that can be obtained from mv_surveillance_result_h handle by mv_surveillance_get_result_value() function
[in]user_dataThe user data passed from the mv_surveillance_foreach_event_result_name() function
Returns:
true to continue with the next iteration of the loop,
otherwise false to break out of the loop
Precondition:
mv_surveillance_foreach_event_result_name() will invoke this callback
See also:
mv_surveillance_foreach_event_result_name()

The handle to event trigger.

Since :
3.0
Remarks:
See supported event types and their descriptions in Media Vision Surveillance Event Types documentation section. Also the list of supported events can be obtained using mv_surveillance_foreach_supported_event_type() function
typedef bool(* mv_surveillance_event_type_cb)(const char *event_type, void *user_data)

Called to get the information once for each supported event type.

Since :
3.0
Remarks:
Don't release memory of event_type
Parameters:
[in]event_typeCharacter string containing name of the event type
[in]user_dataThe user data passed from the mv_surveillance_foreach_supported_event_type() function
Returns:
true to continue with the next iteration of the loop,
otherwise false to break out of the loop
Precondition:
mv_surveillance_foreach_supported_event_type() will invoke this callback
See also:
mv_surveillance_foreach_supported_event_type()
typedef void* mv_surveillance_result_h

The handle to event trigger activation result.

Result is a handle to the output values which are specific for each event. See the output values names in the event types descriptions located in Media Vision Surveillance Event Types documentation section. Result values can be gotten by mv_surveillance_get_result_value() function one by one in order specified in the event description ( the same order of event value names is supported by mv_surveillance_foreach_event_result_name() function). This pointer will be destroyed when mv_surveillance_event_occurred_cb passed.

Since :
3.0

Function Documentation

int mv_surveillance_event_trigger_create ( const char *  event_type,
mv_surveillance_event_trigger_h trigger 
)

Creates surveillance event trigger handle.

Since :
3.0
Remarks:
List of supported event types can be obtained by mv_surveillance_foreach_supported_event_type function
You must release trigger by using mv_surveillance_event_trigger_destroy()
Parameters:
[in]event_typeName of the event type to be supported by the trigger
[out]triggerA new handle to the event trigger
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
See also:
mv_surveillance_event_trigger_destroy()
mv_surveillance_foreach_supported_event_type()

Destroys the surveillance event trigger handle and releases all its resources.

Since :
3.0
Parameters:
[in]triggerThe handle to the event trigger 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
See also:
mv_surveillance_event_trigger_create
int mv_surveillance_foreach_event_result_name ( const char *  event_type,
mv_surveillance_event_result_name_cb  callback,
void *  user_data 
)

Starts traversing through list of supported event result value names.

Since :
3.0
Remarks:
Supported event types, event result value names and their descriptions can be found in Media Vision Surveillance Event Types documentation section
Parameters:
[in]event_typeThe name of the event type for which result value names will be passed to the callback. Can be set NULL. If set NULL then all supported event result value names will be traversed
[in]callbackThe callback function to be called for each supported event result value name
[in]user_dataThe user data to be passed to the callback function
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
See also:
mv_surveillance_event_result_name_cb
mv_surveillance_foreach_supported_event_type()
mv_surveillance_get_result_value()

Starts traversing through list of supported event types.

Since :
3.0
Remarks:
Supported event types and their descriptions can be found in Media Vision Surveillance Event Types documentation section
Parameters:
[in]callbackThe callback function to be called for each supported event type
[in]user_dataThe user data to be passed to the callback function
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
See also:
mv_surveillance_event_type_cb
mv_surveillance_foreach_event_result_name()
int mv_surveillance_get_event_trigger_roi ( mv_surveillance_event_trigger_h  trigger,
int *  number_of_points,
mv_point_s **  roi 
)

Gets ROI (Region Of Interest) from the event trigger.

Since :
3.0
Remarks:
If mv_surveillance_set_event_trigger_roi() has been never called for trigger, then number_of_points output value will be zero and roi pointer will be not changed.
Parameters:
[in]triggerThe handle to the event trigger
[out]number_of_pointsThe number of ROI points
[out]roiThe output array with ROI points
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:
Event trigger has to be created by mv_surveillance_event_trigger_create() function
Postcondition:
Memory for roi array must be released
See also:
mv_surveillance_event_trigger_h
mv_surveillance_set_event_trigger_roi()

Gets the surveillance event trigger type as character string.

Since :
3.0
Remarks:
The event_type should be freed using free()
Parameters:
[in]triggerThe handle to the event trigger
[out]event_typeThe pointer to the character string which will be filled by textual name of the event type
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:
Event trigger has to be created by mv_surveillance_event_trigger_create() function
int mv_surveillance_get_result_value ( mv_surveillance_result_h  result,
const char *  name,
void *  value 
)

Gets result value.

See the output values names in the event types descriptions located in Media Vision Surveillance Event Types documentation section.

Since :
3.0
Remarks:
The name can be obtained by mv_surveillance_foreach_event_result_name function
Parameters:
[in]resultThe handle to the event result
[in]nameThe name of the value to be gotten
[in,out]valueThe pointer to variable which will be filled by result value. To find the type of value please refer to the Media Vision Surveillance Event Types documentation section
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:
Memory for value has to be allocated
See also:
mv_surveillance_event_trigger_h
mv_surveillance_event_occurred_cb
mv_surveillance_subscribe_event_trigger()
mv_surveillance_unsubscribe_event_trigger()
mv_surveillance_foreach_supported_event_type()
mv_surveillance_foreach_event_result_name()
int mv_surveillance_push_source ( mv_source_h  source,
int  video_stream_id 
)

Pushes source to the surveillance system to detect events.

mv_surveillance_event_occurred_cb() will be called when any subscribing event detected.

Since :
3.0
Remarks:
mv_surveillance_set_event_trigger_roi() function can be used to specify the polygon region where event can be detected only
Parameters:
[in]sourceThe handle to the media source
[in]video_stream_idThe identifier of video stream from which source is coming
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:
To receive surveillance results, some event triggers has to be subscribed by mv_surveillance_subscribe_event_trigger() function before mv_surveillance_push_source() calls
Before calling of this method source has to be correctly filled. mv_source_fill_by_media_packet(), mv_source_fill_by_buffer() functions can be used to fill source
See also:
mv_surveillance_event_trigger_h
mv_surveillance_event_occurred_cb
mv_surveillance_subscribe_event_trigger()
mv_surveillance_unsubscribe_event_trigger()
int mv_surveillance_set_event_trigger_roi ( mv_surveillance_event_trigger_h  trigger,
int  number_of_points,
mv_point_s roi 
)

Sets ROI (Region Of Interest) to the event trigger.

When ROI is set for the event trigger, then event check for this trigger will be performed only inside the polygonal region determined by roi parameter. If this method has been never called for the trigger, then event will be checked for the whole input frame (event check is performed for each mv_surveillance_push_source() function call). It is possible to change the ROI between mv_surveillance_push_source() calls.

Since :
3.0
Parameters:
[in]triggerThe handle to the event trigger
[in]number_of_pointsThe number of ROI points
[in]roiThe input array with ROI points
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:
Event trigger has to be created by mv_surveillance_event_trigger_create() function
See also:
mv_surveillance_event_trigger_h
mv_surveillance_get_event_trigger_roi()
int mv_surveillance_subscribe_event_trigger ( mv_surveillance_event_trigger_h  trigger,
int  video_stream_id,
mv_engine_config_h  engine_cfg,
mv_surveillance_event_occurred_cb  callback,
void *  user_data 
)

Subscribes trigger to process sources pushed from video identified by video_stream_id.

When trigger is subscribed, then each time when function mv_surveillance_push_source() is called for video_stream_id, event occurrence is checked. If this check is successful, callback is invoked. Details on occurred event can be obtained using mv_surveillance_result_h handle from callback.

Since :
3.0
Remarks:
Use mv_surveillance_unsubscribe_event_trigger() function for the same trigger and video_stream_id parameters to stop subscription.
Parameters:
[in]triggerThe handle to the event trigger activating calls of the callback function
[in]video_stream_idThe identifier of the video stream for which event trigger activation will be checked
[in]engine_cfgThe engine configuration of the event
[in]callbackCallback to be called each time when event occurrence is detected
[in]user_dataThe user data to be passed to the callback function
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:
mv_surveillance_event_occurred_cb will be called each time trigger is activated after mv_surveillance_push_source() call
See also:
mv_surveillance_event_trigger_h
mv_surveillance_unsubscribe_event_trigger()
mv_surveillance_push_source()

Unsubscribes trigger from the event and stop calling callback.

Since :
3.0
Remarks:
To start handling trigger activation use mv_surveillance_subscribe_event_trigger().
Parameters:
[in]triggerThe handle to the event trigger for which subscription will be stopped
[in]video_stream_idThe identifier of the video source for which subscription will be stopped
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:
To stop subscription it has to be created earlier with mv_surveillance_subscribe_event_trigger() function
See also:
mv_surveillance_event_trigger_h
mv_surveillance_subscribe_event_trigger()