Video surveillance module.

Required Header

#include <mv_surveillance.h>

Related Features

This API is related with the following features:

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:

MV_SURVEILLANCE_SKIP_FRAMES_COUNT to setup number of frames will be ignored by event trigger;
MV_SURVEILLANCE_MOVEMENT_DETECTION_THRESHOLD to specify sensitivity of the MV_SURVEILLANCE_EVENT_TYPE_MOVEMENT_DETECTED event detection;
MV_SURVEILLANCE_FACE_RECOGNITION_MODEL_FILE_PATH to specify the file where face recognition model to be used for recognition is stored.

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_THRESOLD 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_THRESOLD 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]	trigger	The event trigger handle
[in]	source	The handle to the media source
[in]	video_stream_id	The identifier of the video source where event has been detected
[in]	event_result	The event result passed from the mv_surveillance_subscribe_event_trigger()
[in]	user_data	The 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]	name	Character 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_data	The 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()

typedef void* mv_surveillance_event_trigger_h

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_type	Character string containing name of the event type
[in]	user_data	The 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_type	Name of the event type to be supported by the trigger
[out]	trigger	A new handle to the event trigger

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_OUT_OF_MEMORY	Out of memory
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported

See also:: mv_surveillance_event_trigger_destroy(); mv_surveillance_foreach_supported_event_type()

int mv_surveillance_event_trigger_destroy ( mv_surveillance_event_trigger_h trigger )

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

Since :: 3.0

Parameters:

[in] trigger The handle to the event trigger 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

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_type	The 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]	callback	The callback function to be called for each supported event result value name
[in]	user_data	The user data to be passed to the callback function

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

See also:: mv_surveillance_event_result_name_cb; mv_surveillance_foreach_supported_event_type(); mv_surveillance_get_result_value()

int mv_surveillance_foreach_supported_event_type	(	mv_surveillance_event_type_cb	callback,
		void *	user_data
	)

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]	callback	The callback function to be called for each supported event type
[in]	user_data	The user data to be passed to the callback function

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

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]	trigger	The handle to the event trigger
[out]	number_of_points	The number of ROI points
[out]	roi	The output array with ROI points

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:: 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()

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.

Since :: 3.0

Remarks:: The event_type should be freed using free()

Parameters:

[in]	trigger	The handle to the event trigger
[out]	event_type	The 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_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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]	result	The handle to the event result
[in]	name	The name of the value to be gotten
[in,out]	value	The 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_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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]	source	The handle to the media source
[in]	video_stream_id	The identifier of video stream from which source is coming

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:: 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 triger 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]	trigger	The handle to the event trigger
[in]	number_of_points	The number of ROI points
[in]	roi	The input array with ROI points

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:: 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]	trigger	The handle to the event trigger activating calls of the callback function
[in]	video_stream_id	The identifier of the video stream for which event trigger activation will be checked
[in]	engine_cfg	The engine configuration of the event
[in]	callback	Callback to be called each time when event occurrence is detected
[in]	user_data	The user data to be passed to the callback function

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:: 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()

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.

Since :: 3.0

Remarks:: To start handling trigger activation use mv_surveillance_subscribe_event_trigger().

Parameters:

[in]	trigger	The handle to the event trigger for which subscription will be stopped
[in]	video_stream_id	The 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_NONE	Successful
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not 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()

Required Header

Related Features

Overview

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Function Documentation