Tracking / Watchlisting

Follow faces in videos. More...

Data Structures
struct	roc_event
	A summary of a person in one or more videos. More...
struct	roc_tracker_algorithm_parameters
	A set of parameters specific to an individual roc_algorithm_id. More...

Macros
#define	ROC_DEFAULT_MIN_TRACKING_SIMILARITY   0.45f
	Default minimum tracking similarity. More...
#define	ROC_SUGGESTED_MIN_DETECTION_OVERLAP   0.0f
	Suggested minimum detection overlap. More...
#define	ROC_DEFAULT_MAX_TIME_SEPARATION   5000
	Default maximum time separation. More...
#define	ROC_DEFAULT_MIN_COUNT   1
	Default minimum template count. More...
#define	ROC_DEFAULT_LICENSE_PLATE_STATE_THRESHOLD   0.9
	Default threshold for license plate state classification. More...

Typedefs
typedef struct roc_event	roc_event
	A summary of a person in one or more videos. More...
typedef struct roc_tracker_type *	roc_tracker
	A tracker takes templates from one or more videos and outputs events. More...
typedef struct roc_tracker_algorithm_parameters	roc_tracker_algorithm_parameters
	A set of parameters specific to an individual roc_algorithm_id. More...
typedef enum roc_tracker_privacy	roc_tracker_privacy
	When to redact faces in a video stream.
typedef enum roc_event_reasons	roc_event_reasons
	Reasons for a roc_event.
typedef uint32_t	roc_event_type
	A combination of roc_event_reasons. More...

Enumerations
enum	roc_tracker_privacy { ROC_REDACT_NONE = 0x0, ROC_REDACT_NONMATCHING = 0x1, ROC_REDACT_MATCHING = 0x2, ROC_REDACT_ALL }
	When to redact faces in a video stream. More...
enum	roc_event_reasons {   ROC_NO_EVENT = 0x0000, ROC_NEW_TRACK = 0x0001, ROC_NEW_PROBE = 0x0002, ROC_BETTER_PROBE = 0x0004,   ROC_BETTER_CANDIDATE = 0x0008, ROC_MERGED_TRACKS = 0x0010, ROC_NEW_START_TIME = 0x0020, ROC_NEW_STOP_TIME = 0x0040,   ROC_NEW_CAMERA = 0x0080, ROC_NEW_WATCHLIST = 0x0100, ROC_MORE_TEMPLATES = 0x0200, ROC_FINALIZED_TRACK = 0x0400,   ROC_ELAPSED_THRESHOLD = 0x0800, ROC_ELAPSED_INTERVAL = 0x1000, ROC_ANY = ROC_NEW_TRACK | ROC_MORE_TEMPLATES }
	Reasons for a roc_event. More...

Functions
roc_error	roc_new_tracker (roc_tracker *tracker)
	Initialize a new tracker. More...
roc_error	roc_tracker_set_tracking_parameters (roc_tracker tracker, roc_event_type reasons, roc_time max_time_separation, float min_detection_overlap, roc_similarity min_tracking_similarity, int min_count)
	Set tracker tracking parameters. More...
roc_error	roc_tracker_set_represent_parameters (roc_tracker tracker, roc_algorithm_id algorithm_id, float relative_min_size, int k, float false_detection_rate, float min_quality)
	Set tracker template representation parameters. More...
roc_error	roc_tracker_set_algorithm_parameters (roc_tracker tracker, const roc_tracker_algorithm_parameters *algorithm_params_list, size_t list_size)
	Set multiple configurations of tracker algorithm parameters. More...
roc_error	roc_tracker_set_enhance_contrast_parameters (roc_tracker tracker, float clip_limit, int num_tiles)
	Enhance the contrast of each frame using roc_enhance_contrast. More...
roc_error	roc_tracker_load_configuration (const char *tracker_info, roc_gallery *galleries, size_t gallery_count, const char *process_id, roc_tracker tracker)
	Configure roc_tracker. More...
roc_error	roc_tracker_set_output_pipe (roc_tracker tracker, const char *template_pipe_file, bool append, bool keep_alive, bool replay_on_failure, int frame_rate, int quality, size_t height)
	Assign an output image pipe to a tracker. More...
roc_error	roc_tracker_set_rendering_options (roc_tracker tracker, bool render_detections, bool render_foreground, bool render_timestamps, bool render_person_ids, bool render_recording, uint8_t r, uint8_t g, uint8_t b)
	Set roc_tracker frame rendering options. More...
roc_error	roc_tracker_set_privacy_parameters (roc_tracker tracker, roc_tracker_privacy face_privacy, bool blur, roc_tracker_privacy image_privacy)
	Set privacy parameters. More...
roc_error	roc_tracker_set_watchlisting_parameters (roc_tracker tracker, roc_similarity min_watchlist_similarity)
	Set tracker watchlisting parameters. More...
roc_error	roc_tracker_add_watchlist (roc_tracker tracker, roc_gallery watchlist)
	Add a watchlist to a tracker. More...
roc_error	roc_tracker_remove_watchlist (roc_tracker tracker, roc_gallery watchlist)
	Remove a watchlist from a tracker. More...
roc_error	roc_tracker_set_rois (roc_tracker tracker, const roc_roi *include, size_t num_include, const roc_roi *exclude, size_t num_exclude, float min_roi_overlap)
	Specify image regions of interest (ROI) for processing. More...
roc_error	roc_tracker_set_foreground_parameters (roc_tracker tracker)
	Automatically crop a region of interest based on foreground change relative to a static background model. More...
roc_error	roc_tracker_set_best_image_parameters (roc_tracker tracker, roc_database database, const char *template_pipe_file, const char *format, int quality, roc_event_type reasons, bool append, bool keep_alive, bool replay_on_failure)
	Set tracker best frame storage. More...
roc_error	roc_tracker_set_time_elapsed (roc_tracker tracker, roc_time threshold_ms, roc_time interval_ms)
	Configure tracker to emit an event for a person a specified amount of time after they were first seen or previously seen. More...
roc_error	roc_tracker_add_template (roc_tracker tracker, const roc_template template_)
	Add a template to a tracker. More...
roc_error	roc_tracker_add_image (roc_tracker tracker, const roc_image image, roc_stream stream)
	Convenience function for generating and tracking all templates in an image. More...
roc_error	roc_tracker_add_encoded_image (roc_tracker tracker, size_t len, const uint8_t *input_byte_array, roc_time timestamp, roc_stream stream)
	Convenience function for generating and tracking all templates in an encoded image. More...
roc_error	roc_tracker_update_time (roc_tracker tracker, roc_time timestamp)
	Update a tracker's current time. More...
roc_error	roc_tracker_get_current_frame (roc_tracker tracker, roc_image *frame, roc_event *events, int *num_events)
	Obtain the most recently processed frame. More...
void *	roc_tracker_cast (roc_tracker tracker)
	Cast and return a roc_tracker as a void*. More...
void	roc_tracker_add_image_callback (roc_stream stream, void *tracker, roc_error error, roc_image image)
	Alternative to roc_tracker_add_image with signature type roc_stream_image_callback. More...
void	roc_tracker_add_encoded_image_callback (roc_stream stream, void *tracker, roc_error error, size_t len, const uint8_t *input_byte_array, roc_time timestamp)
	Alternative to roc_tracker_add_image with signature type roc_stream_encoded_image_callback. More...
bool	roc_tracker_has_events (roc_tracker tracker, roc_time wait)
	Query if the tracker has events. More...
roc_error	roc_tracker_take_event (roc_tracker tracker, roc_event *event)
	Obtain the next event from a tracker. More...
roc_error	roc_tracker_best_image (roc_tracker tracker, roc_person_id person_id, roc_image *image)
	Retrieve the current best image for an active track. More...
roc_error	roc_tracker_set_recorder_parameters (roc_tracker tracker, const char *database_path, bool keep_alive, int max_frames_stored, unsigned int idr_interval, bool persistent_recording_enabled, roc_time persistent_recording_clips_duration)
	Assign and configure an output recorder to a tracker. More...
roc_error	roc_tracker_get_video_clip (const roc_tracker tracker, roc_time *start_time, roc_time *stop_time, roc_buffer *bit_stream, size_t *bit_stream_size)
	Retrieve an MP4 video clip. More...
roc_error	roc_tracker_get_next_video_clip (const roc_tracker tracker, roc_time *start_time, roc_time *stop_time, roc_buffer *bit_stream, size_t *bit_stream_size)
	Retrieve the next persistently-recorded MP4 video clip. More...
roc_error	roc_tracker_flush_remaining_clips (const roc_tracker tracker, roc_camera_id camera_id)
	Retrieve remaining recorded video clips when finished trackering. More...
roc_error	roc_tracker_get_earliest_recorded_time (const roc_tracker tracker, roc_time *timestamp)
	Return the timestamp of the earliest held encoded frame. More...
roc_error	roc_tracker_get_current_recorded_time (const roc_tracker tracker, roc_time *timestamp)
	Return the timestamp of the most recently encoded frame. More...
roc_error	roc_tracker_store_clip (const roc_tracker tracker, roc_media_id media_id, roc_camera_id camera_id, roc_time *start, roc_time *stop)
	Transmit a video. More...
roc_error	roc_tracker_store_next_clip (const roc_tracker tracker, roc_media_id media_id, roc_camera_id camera_id, roc_time *start, roc_time *stop)
	Transmit a persistently recorded video clip. More...
roc_error	roc_free_tracker (roc_tracker tracker)
	Free a tracker. More...
roc_error	roc_event_type_to_string (roc_event_type event_type, const char **str)
	String representation of a roc_event_type. More...
roc_error	roc_event_type_from_string (const char *str, roc_event_type *event_type)
	The opposite of roc_event_type_to_string. More...

Detailed Description

Follow faces in videos.

In the typical case, for tracking and watchlisting one or more live-streams or pre-recorded videos, use roc_tracker and see roc_tracker_add_template for details.

---

Data Structure Documentation

roc_event

struct roc_event

A summary of a person in one or more videos.

Note

For roc_event::start and roc_event::stop, time is measured from the call to roc_new_tracker.

Data Fields
roc_event_type	reasons	Why this event was emitted.
roc_template	probe	Representative template for the event.
float	quality	Face Quality of probe.
roc_person_id	replaced_by	When ROC_MERGED_TRACKS, this value holds the replacing events's probe roc_template::person_id.
roc_time	previous_event	Holds probe roc_template::timestamp for the most recent emitted event for use by ROC_ELAPSED_INTERVAL.
roc_candidate	candidate	Highest roc_similarity match against one of the watchlists.
roc_gallery	watchlist	Watchlist corresponding to candidate.
roc_time	start	Timestamp of the earliest template associated with the event.
roc_time	stop	Timestamp of the latest template associated with the event.
roc_detection	first_detection
roc_detection	latest_detection	Detection of the earliest template associated with the event.
roc_camera_id	camera	Detection of the most recent template associated with the event. Current camera.
uint32_t	count	Number of templates associated with the event.

roc_tracker_algorithm_parameters

struct roc_tracker_algorithm_parameters

A set of parameters specific to an individual roc_algorithm_id.

Data Fields
roc_algorithm_id	algorithm_id	Algorithm to use these parameters for.
float	relative_min_size	Relative minimum size for specified algorithm. see roc_adaptive_minimum_size.
int	k	K value for specified algorithm. See roc_represent.
float	false_detection_rate	False detection rate for specified algorithm. See False Detection Rate.
float	min_quality	Minimum quality for specified algorithm. See roc_represent.
roc_event_type	reasons	Reasons for specified algorithm. See Event Reasons.
roc_time	max_time_separation	Maximum time separation for specified algorithm. See Maximum Time Separation.
float	min_detection_overlap	Minimum detection overlap for specified algorithm. See Minimum Detection Overlap.
roc_similarity	min_tracking_similarity	Minimum tracking similarity for specified algorithm. See Minimum Similarity.
int	min_count	Minimum template count for each event for specified algorithm.
char *	text_filter	Regular expressions describing text to check for in detection areas.
roc_thumbnail_parameters	thumbnail_parameters	Parameters to use for generating template thumbnails. See ROC_THUMBNAIL.
char *	metadata_object	JSON-formatted object to insert in each template's metadata. See roc_set_metadata.

Macro Definition Documentation

ROC_DEFAULT_MIN_TRACKING_SIMILARITY

#define ROC_DEFAULT_MIN_TRACKING_SIMILARITY   0.45f

Default minimum tracking similarity.

See also

Default Versus Suggested Parameters

ROC_SUGGESTED_MIN_DETECTION_OVERLAP

#define ROC_SUGGESTED_MIN_DETECTION_OVERLAP   0.0f

Suggested minimum detection overlap.

Recommendation is to not require detection overlap.

See also

Default Versus Suggested Parameters

ROC_DEFAULT_MAX_TIME_SEPARATION

#define ROC_DEFAULT_MAX_TIME_SEPARATION   5000

Default maximum time separation.

Default is five seconds.

See also

Default Versus Suggested Parameters

ROC_DEFAULT_MIN_COUNT

#define ROC_DEFAULT_MIN_COUNT   1

Default minimum template count.

Default is 1 template.

See also

Default Versus Suggested Parameters

ROC_DEFAULT_LICENSE_PLATE_STATE_THRESHOLD

#define ROC_DEFAULT_LICENSE_PLATE_STATE_THRESHOLD   0.9

Default threshold for license plate state classification.

Default is 0.9

See also

Default Versus Suggested Parameters

Typedef Documentation

roc_event

typedef struct roc_event roc_event

A summary of a person in one or more videos.

Note

For roc_event::start and roc_event::stop, time is measured from the call to roc_new_tracker.

roc_tracker

typedef struct roc_tracker_type* roc_tracker

A tracker takes templates from one or more videos and outputs events.

Initialize with roc_new_tracker and free with roc_free_tracker. Add templates with roc_tracker_add_template and retrieve events with roc_tracker_take_event.

roc_tracker_algorithm_parameters

typedef struct roc_tracker_algorithm_parameters roc_tracker_algorithm_parameters

A set of parameters specific to an individual roc_algorithm_id.

roc_event_type

typedef uint32_t roc_event_type

A combination of roc_event_reasons.

A roc_event_type is a bit field of roc_event_reasons. To combine multiple roc_event_reasons use the C bitwise-or | operator. To test for specific roc_event_reasons use the C bitwise-and & operator.

Enumeration Type Documentation

roc_tracker_privacy

enum roc_tracker_privacy

When to redact faces in a video stream.

Enumerator
ROC_REDACT_NONE	Do not redact any faces.
ROC_REDACT_NONMATCHING	Redact faces that don't match a watchlist.
ROC_REDACT_MATCHING	Redact faces that do match a watchlist.
ROC_REDACT_ALL	Redact all faces.

roc_event_reasons

enum roc_event_reasons

Reasons for a roc_event.

Enumerator
ROC_NO_EVENT	There are no more events in the queue.
ROC_NEW_TRACK	Found a previously unseen person. The roc_template::person_id for roc_event::probe is be one more than the previous maximum roc_person_id.
ROC_NEW_PROBE	The probe template associated with the event has changed. Implies ROC_BETTER_PROBE and/or ROC_BETTER_CANDIDATE.
ROC_BETTER_PROBE	The new roc_event::quality is higher. Implies ROC_NEW_PROBE.
ROC_BETTER_CANDIDATE	The new roc_event::candidate has higher similarity. Implies ROC_NEW_PROBE.
ROC_MERGED_TRACKS	This event is now obsolete and should be considered part of roc_event::replaced_by.
ROC_NEW_START_TIME	The event has an earlier start time. Implies ROC_MERGED_TRACKS.
ROC_NEW_STOP_TIME	The event has a later end time.
ROC_NEW_CAMERA	The most recent camera has changed. Implies ROC_NEW_STOP_TIME.
ROC_NEW_WATCHLIST	The candidate watchlist has changed. Implies ROC_BETTER_CANDIDATE.
ROC_MORE_TEMPLATES	Additional templates associated with an existing track.
ROC_FINALIZED_TRACK	This is the last event reported for a person. It occurs after the person is not observed in the video for Maximum Time Separation milliseconds.
ROC_ELAPSED_THRESHOLD	The specified amount of time has passed since the person was first observed. See roc_tracker_set_time_elapsed.
ROC_ELAPSED_INTERVAL	The specified amount of time has elapsed since a previous event was emitted. See roc_tracker_set_time_elapsed.
ROC_ANY	Emit an event for every new template.

Function Documentation

roc_new_tracker()

roc_error roc_new_tracker

(

roc_tracker *

tracker

)

Initialize a new tracker.

After initializing a tracker, users should first call roc_tracker_set_tracking_parameters. Optionally, if you wish to enable watchlisting, also call roc_tracker_set_watchlisting_parameters. Optionally, if you wish to use roc_tracker_add_image, also call roc_tracker_set_represent_parameters. Optionally, if you wish to store a representative frame per-track, also call roc_tracker_set_best_image_parameters.

Free tracker after last use with roc_free_tracker.

Example

roc_tracker tracker;
roc_new_tracker(&tracker);

Parameters

[out]

tracker

Address of an unitialized tracker to initialize.

Remarks

This function is reentrant.

roc_tracker_set_tracking_parameters()

roc_error roc_tracker_set_tracking_parameters	(	roc_tracker	tracker,
		roc_event_type	reasons,
		roc_time	max_time_separation,
		float	min_detection_overlap,
		roc_similarity	min_tracking_similarity,
		int	min_count
	)

Set tracker tracking parameters.

Two templates are assigned the same roc_template::person_id if all of the following are true:

• Their roc_template::timestamp absolute difference is less than or equal to max_time_separation. The suggested default value for max_time_separation is ROC_DEFAULT_MAX_TIME_SEPARATION.
• Their detection intersection area divided by union area, or overlap, is greater than or equal to min_detection_overlap. The suggested default value for min_detection_overlap is ROC_SUGGESTED_MIN_DETECTION_OVERLAP.
• Their facial similarity is greater than or equal to min_similarity. The suggested default value for min_similarity is ROC_DEFAULT_MIN_TRACKING_SIMILARITY.

Maximum Time Separation

The maximum absolute time difference when greater than zero. A max_time_separation of zero will be treated as std::numeric_limits<roc_time>::max(), effectively disabling the temporal tracking requirement.

Minimum Detection Overlap

The minimum face detection bounding box overlap, between zero and one inclusive.

Minimum Similarity

Minimum template similarity, between zero and one inclusive.

Example

roc_tracker tracker = ...;
roc_tracker_set_tracking_parameters(tracker, ROC_BETTER_PROBE | ROC_BETTER_CANDIDATE | ROC_MERGED_TRACKS, ROC_DEFAULT_MAX_TIME_SEPARATION, ROC_SUGGESTED_MIN_DETECTION_OVERLAP, ROC_DEFAULT_MIN_TRACKING_SIMILARITY, ROC_DEFAULT_MIN_COUNT);

Parameters

[in]	tracker	Tracker to set parameters.
[in]	reasons	See Event Reasons.
[in]	max_time_separation	See Maximum Time Separation.
[in]	min_detection_overlap	See Minimum Detection Overlap.
[in]	min_tracking_similarity	See Minimum Similarity.
[in]	min_count	Minimum template count for event.

Remarks

This function is reentrant.

roc_tracker_set_represent_parameters()

roc_error roc_tracker_set_represent_parameters	(	roc_tracker	tracker,
		roc_algorithm_id	algorithm_id,
		float	relative_min_size,
		int	k,
		float	false_detection_rate,
		float	min_quality
	)

Set tracker template representation parameters.

Example

roc_tracker tracker = ...;
roc_tracker_set_represent_parameters(tracker,
                                     ROC_FRONTAL_DETECTION | ROC_STANDARD_REPRESENTATION,
                                     ROC_SUGGESTED_RELATIVE_MIN_SIZE,
                                     5,
                                     ROC_SUGGESTED_FALSE_DETECTION_RATE,
                                     ROC_STANDARD_SUGGESTED_MIN_QUALITY);

Parameters

[in]	tracker	Tracker to set parameters.
[in]	algorithm_id	See roc_represent.
[in]	relative_min_size	Minimum face size relative to image size, see roc_adaptive_minimum_size.
[in]	k	See roc_represent.
[in]	false_detection_rate	See roc_represent.
[in]	min_quality	See roc_represent.

Remarks

This function is reentrant.

See also

roc_tracker_set_rois

roc_tracker_set_algorithm_parameters()

roc_error roc_tracker_set_algorithm_parameters	(	roc_tracker	tracker,
		const roc_tracker_algorithm_parameters *	algorithm_params_list,
		size_t	list_size
	)

Set multiple configurations of tracker algorithm parameters.

Allows configuring different tracking and representation parameters for different roc_algorithm_id options for a roc_tracker.

Parameters

[in]	tracker	Tracker to set parameters for.
[in]	algorithm_params_list	Array of roc_tracker_algorithm_parameters to configure for the tracker.
[in]	list_size	Size of the array of represent parameters.

Remarks

This function is reentrant. See roc_tracker_set_represent_parameters and roc_tracker_set_tracking_parameters

roc_tracker_set_enhance_contrast_parameters()

roc_error roc_tracker_set_enhance_contrast_parameters	(	roc_tracker	tracker,
		float	clip_limit,
		int	num_tiles
	)

Enhance the contrast of each frame using roc_enhance_contrast.

A num_tiles of 0 (the default) disables contrast enhancement.

Parameters

tracker	Tracker to enable contrast enhancement.
clip_limit	See roc_enhance_contrast.
num_tiles	See roc_enhance_contrast.

Remarks

This function is thread-safe.

roc_tracker_load_configuration()

roc_error roc_tracker_load_configuration	(	const char *	tracker_info,
		roc_gallery *	galleries,
		size_t	gallery_count,
		const char *	process_id,
		roc_tracker	tracker
	)

Configure roc_tracker.

Convenience function which calls roc_tracker_set_watchlisting_parameters, roc_tracker_set_tracking_parameters, roc_tracker_set_time_elapsed, roc_preload, roc_set_model_path, roc_tracker_set_represent_parameters, roc_tracker_add_watchlist, roc_tracker_set_privacy_parameters, roc_open_template_pipe, roc_tracker_set_best_image_parameters, roc_tracker_set_rois and roc_tracker_set_foreground_parameters. Please reference those functions for more information on the full details of this function.

tracker_info can be either the filepath to or the contents of a JSON file.

roc_error roc_tracker_load_configuration(const char* tracker_info, roc_gallery *galleries, size_t gallery_count, const char *process_id, roc_tracker tracker)
{
    if (tracker_info == nullptr || QString(tracker_info).isEmpty())
        return "Failed to load tracker configuration!";

    // Load configuration file from a filepath or from a data pointer
    QByteArray val;
    if (QFile(tracker_info).exists()) {
        QFile file;
        file.setFileName(tracker_info);
        file.open(QIODevice::ReadOnly | QIODevice::Text);
        val = file.readAll();
        file.close();
    } else {
        val = tracker_info;
    }

    roc_video_service_utils::tracker_config config(QJsonDocument::fromJson(val).object());
    if (config.analytics_backends.size() == 0)
        roc_ensure("Failed to load representation parameters!");

    for (int i = 0; i < config.analytics_backends.size(); i++) {
        roc_ensure(roc_preload(config.analytics_backends[i].algorithm_parameters.algorithm_id));

        // All of the parameters sets will use the same threshold and interval for ELAPSED
        if (config.analytics_backends[i].algorithm_parameters.reasons & ROC_ELAPSED_THRESHOLD ||
            config.analytics_backends[i].algorithm_parameters.reasons & ROC_ELAPSED_INTERVAL)
            roc_ensure(roc_tracker_set_time_elapsed(tracker, config.reason_elapsed.threshold_time, config.reason_elapsed.interval_time));
    }
    roc_ensure(roc_tracker_set_watchlisting_parameters(tracker, config.watchlists.min_similarity));

    QVector<roc_tracker_algorithm_parameters> represent_params_list;
    for (int i = 0; i < config.analytics_backends.size(); i++) {
        if (config.analytics_backends[i].enabled) {
            roc_tracker_algorithm_parameters represent_params = config.analytics_backends[i].algorithm_parameters;

            if (config.analytics_backends[i].no_min_quality)
                represent_params.min_quality = ROC_NO_MIN_QUALITY;
            if (config.analytics_backends[i].algorithm_parameters.text_filter) {
                QString filter = config.analytics_backends[i].algorithm_parameters.text_filter;
                char *textFilter = (char*) malloc(filter.length()+1);
                strcpy(textFilter, qPrintable(filter));
                represent_params.text_filter = textFilter;
            }
            if (config.analytics_backends[i].algorithm_parameters.metadata_object) {
                QString set_metadata_object = config.analytics_backends[i].algorithm_parameters.metadata_object;
                char *metadata_object = (char*) malloc (set_metadata_object.length()+1);
                strcpy(metadata_object, qPrintable(set_metadata_object));
                represent_params.metadata_object = metadata_object;
            }

            represent_params_list.push_back(represent_params);
        }
    }

    roc_ensure(roc_tracker_set_algorithm_parameters(tracker, represent_params_list.data(), represent_params_list.size()));

    // Clean up filter-texts and set-metadata-objects
    for (int listIndex = 0; listIndex < represent_params_list.size(); listIndex++) {
        if (represent_params_list[listIndex].text_filter) {
            free(represent_params_list[listIndex].text_filter);
            represent_params_list[listIndex].text_filter = 0;
        }
        if (represent_params_list[listIndex].metadata_object) {
            free(represent_params_list[listIndex].metadata_object);
            represent_params_list[listIndex].metadata_object = 0;
        }
    }

    if (galleries != nullptr) {
        for (size_t i = 0; i < gallery_count; i++) {
            roc_ensure(roc_tracker_add_watchlist(tracker, galleries[i]));
        }
    }

    if (config.redaction.face.enabled || config.redaction.context_image.enabled)
        roc_ensure(roc_tracker_set_privacy_parameters(tracker,
                                                      config.redaction.face.enabled ? config.redaction.face.behavior : ROC_REDACT_NONE,
                                                      config.redaction.face.enabled ? config.redaction.face.blur : config.redaction.context_image.blur,
                                                      config.redaction.context_image.enabled ? config.redaction.context_image.behavior : ROC_REDACT_NONE));

    if (config.context_image.enabled && config.context_image.file.path != "THUMBNAIL" && config.context_image.webhook.url != "THUMBNAIL")
        roc_ensure(roc_tracker_set_best_image_parameters(tracker,
                                                         nullptr,
                                                         qPrintable(config.context_image.file.enabled ?
                                                                        config.context_image.file.path : config.context_image.webhook.url),
                                                         qPrintable(config.context_image.format),
                                                         config.context_image.quality,
                                                         ROC_FINALIZED_TRACK,
                                                         false,
                                                         config.context_image.webhook.keep_alive,
                                                         config.context_image.webhook.keep_alive));

    const QVector<roc_roi> include_rois(roc::parseROIs(config.roi.include_roi.toList()));
    const QVector<roc_roi> exclude_rois(roc::parseROIs(config.roi.exclude_roi.toList()));
    if (config.roi.enabled)
        roc_ensure(roc_tracker_set_rois(tracker,
                                        include_rois.data(),
                                        include_rois.size(),
                                        exclude_rois.data(),
                                        exclude_rois.size(),
                                        config.roi.min_roi_overlap));

    if (config.model_foreground)
        roc_ensure(roc_tracker_set_foreground_parameters(tracker));

    QVector<uint8_t> rgb = roc_video_service_utils::string_to_r_g_b(config.render.color);
    roc_ensure(roc_tracker_set_rendering_options(tracker,
                                                 config.render.detections,
                                                 config.render.foreground,
                                                 config.render.timestamp,
                                                 config.render.person_ids,
                                                 config.render.recordings,
                                                 rgb[0],
                                                 rgb[1],
                                                 rgb[2]));

    if (config.camera_preview.enabled)
        roc_ensure(roc_tracker_set_output_pipe(tracker,
                                               qPrintable(config.camera_preview.file.enabled ?
                                                              config.camera_preview.file.path : config.camera_preview.webhook.url),
                                               false,
                                               config.camera_preview.webhook.keep_alive,
                                               false,
                                               config.camera_preview.fps,
                                               config.camera_preview.quality,
                                               config.camera_preview.height));

    if (config.video_recordings.enabled)
        roc_ensure(roc_tracker_set_recorder_parameters(tracker,
                                                       qPrintable(config.video_recordings.file.enabled ?
                                                                      config.video_recordings.file.path : config.video_recordings.webhook.url),
                                                       config.video_recordings.webhook.keep_alive,
                                                       config.video_recordings.max_frames,
                                                       config.video_recordings.persistent_recording.idr_interval,
                                                       config.video_recordings.persistent_recording.enabled,
                                                       config.video_recordings.persistent_recording.clip_duration));

    if (config.enhance_contrast.enabled)
        roc_ensure(roc_tracker_set_enhance_contrast_parameters(tracker, config.enhance_contrast.clip_limit, config.enhance_contrast.tiles));

    tracker->setProcessId(process_id);

    return nullptr;
}

Parameters

[in]	tracker_info	Filepath to or contents of configuration file.
[in]	galleries	Galleries to watchlist against, or NULL.
[in]	gallery_count	Length of galleries.
[in]	process_id	roc_video_service this tracker belongs to.
[out]	tracker	Tracker to initialize.

Remarks

This function is reentrant.

roc_tracker_set_output_pipe()

roc_error roc_tracker_set_output_pipe	(	roc_tracker	tracker,
		const char *	template_pipe_file,
		bool	append,
		bool	keep_alive,
		bool	replay_on_failure,
		int	frame_rate,
		int	quality,
		size_t	height
	)

Assign an output image pipe to a tracker.

Input frames will be written in JPEG format to roc_template_pipe_transmit_image at the specified frame_rate and quality.

Parameters

[in]	tracker	Tracker to assign an output image pipe to.
[in]	template_pipe_file	Location to write templates to.
[in]	append	For local files, controls opening in write or append mode.
[in]	keep_alive	Ignore transmission errors and re-establish the connection.
[in]	replay_on_failure	Replay transmissions that fail.
[in]	frame_rate	Frames per second to write.
[in]	quality	Encoding quality, see Encoding Quality.
[in]	height	Frame height to resize to, or 0 to not resize. Frame width is chosen automatically to preserve aspect ratio.

Remarks

This function is reentrant.

roc_tracker_set_rendering_options()

roc_error roc_tracker_set_rendering_options	(	roc_tracker	tracker,
		bool	render_detections,
		bool	render_foreground,
		bool	render_timestamps,
		bool	render_person_ids,
		bool	render_recording,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

Set roc_tracker frame rendering options.

Parameters

[in]	tracker	Tracker to set rendering options.
[in]	render_detections	Render bounding boxes, default is false.
[in]	render_foreground	Render foreground on the image, default is false. Requires roc_foreground to be set.
[in]	render_timestamps	Render timestmaps or not, default is false.
[in]	render_person_ids	Render roc_template::person_id, default is false.
[in]	render_recording	Use rendered frames for video recording, default is false.
[in]	r	Rendering color R channel (0-255).
[in]	g	Rendering color G channel (0-255).
[in]	b	Rendering color B channel (0-255).

Remarks

This function is thread-safe.

roc_tracker_set_privacy_parameters()

roc_error roc_tracker_set_privacy_parameters	(	roc_tracker	tracker,
		roc_tracker_privacy	face_privacy,
		bool	blur,
		roc_tracker_privacy	image_privacy
	)

Set privacy parameters.

Parameters

[in]	tracker	Tracker to set parameters.
[in]	face_privacy	Redact faces in frames that match or don't match a watchlist.
[in]	blur	Blur instead of redact faces.
[in]	image_privacy	Don't save frames to the database when they match or don't match a watchlist. ROC_REDACT_NONE means save all frames.

Remarks

This function is reentrant.

roc_tracker_set_watchlisting_parameters()

roc_error roc_tracker_set_watchlisting_parameters	(	roc_tracker	tracker,
		roc_similarity	min_watchlist_similarity
	)

Set tracker watchlisting parameters.

Example

roc_tracker tracker = ...;
roc_tracker_set_watchlisting_parameters(tracker,
                                        ROC_DEFAULT_SEARCH_THRESHOLD);

Parameters

[in]	tracker	Tracker to set parameters.
[in]	min_watchlist_similarity	See Minimum Similarity, or ROC_INVALID_SIMILARITY.

Remarks

This function is reentrant.

roc_tracker_add_watchlist()

roc_error roc_tracker_add_watchlist	(	roc_tracker	tracker,
		roc_gallery	watchlist
	)

Add a watchlist to a tracker.

Note

watchlist is assumed to remain valid until it is removed with roc_tracker_remove_watchlist or tracking is stopped with roc_free_tracker.

Example

roc_tracker tracker = ...;
roc_gallery watchlist = ...;
roc_tracker_add_watchlist(tracker, watchlist);

Parameters

[in]	tracker	Tracker to add watchlist to.
[in]	watchlist	Watchlist to add to the tracker.

Remarks

This function is reentrant.

roc_tracker_remove_watchlist()

roc_error roc_tracker_remove_watchlist	(	roc_tracker	tracker,
		roc_gallery	watchlist
	)

Remove a watchlist from a tracker.

If watchlist is NULL, all watchlists will be removed.

Example

roc_tracker tracker = ...;
roc_gallery watchlist = ...;
roc_tracker_remove_watchlist(tracker, watchlist);

Parameters

[in]	tracker	Tracker to remove watchlist from.
[in]	watchlist	Watchlist to remove from the tracker.

Remarks

This function is reentrant.

roc_tracker_set_rois()

roc_error roc_tracker_set_rois	(	roc_tracker	tracker,
		const roc_roi *	include,
		size_t	num_include,
		const roc_roi *	exclude,
		size_t	num_exclude,
		float	min_roi_overlap
	)

Specify image regions of interest (ROI) for processing.

Example

roc_tracker tracker = ...;
roc_roi roi = roc_roi_get(0.25f, 0.25f, 0.5f, 0.5f);
roc_tracker_set_rois(tracker, &roi, 1, NULL, 0);

Parameters

[in]	tracker	Tracker to set region of interest for.
[in]	include	Regions of interest that detections must lie within, or NULL.
[in]	num_include	Length of include.
[in]	exclude	Regions of interest that detections must not lie within, or NULL.
[in]	num_exclude	Length of exclude.
[in]	min_roi_overlap	Minimum fraction of detection area that must be contained within include or exclude.

Remarks

This function is reentrant.

See also

roc_tracker_set_represent_parameters roc_tracker_set_foreground_parameters

roc_tracker_set_foreground_parameters()

roc_error roc_tracker_set_foreground_parameters

(

roc_tracker

tracker

)

Automatically crop a region of interest based on foreground change relative to a static background model.

Foreground modeling will be applied after roc_tracker_set_rois.

Parameters

[in]

tracker

Tracker to enable backround modeling.

See also

roc_tracker_set_rois

roc_tracker_set_best_image_parameters()

roc_error roc_tracker_set_best_image_parameters	(	roc_tracker	tracker,
		roc_database	database,
		const char *	template_pipe_file,
		const char *	format,
		int	quality,
		roc_event_type	reasons,
		bool	append,
		bool	keep_alive,
		bool	replay_on_failure
	)

Set tracker best frame storage.

If set, the best frame for a track will be written to database and/or template_pipe as a format image when reasons is encountered. The roc_event::probe roc_template::archive_id in the event will be updated to this image file. This is only possible if roc_tracker_add_image is called, roc_tracker_add_template has no knowledge of the origin image.

For frames added to the tracker with roc_tracker_add_encoded_image, format and quality will be ignored, and the frame will be written to the database in its original encoding. Therefore roc_template::archive_id will equal roc_template::media_id.

If database is NULL but format is not an empty string, the frame will be stored in roc_template::tn.

Example

roc_tracker tracker = ...;
roc_database database = ...;
roc_tracker_set_best_image_parameters(tracker, database, NULL, ".jpg", 95, ROC_FINALIZED_TRACK);

Parameters

[in]	tracker	Tracker to assign best frame serialization.
[in]	database	Database to write best frames to, or NULL to unset a previously assigned database.
[in]	template_pipe_file	Filepath of a template pipe to write best frames to, or NULL to unset a previously assigned template pipe.
[in]	format	Image format, see roc_encode_image.
[in]	quality	Image quality, see roc_encode_image.
[in]	reasons	When to save a frame.
[in]	append	For local files, controls opening in write or append mode. Only used when template_pipe_file is set.
[in]	keep_alive	Ignore transmission errors and re-establish the connection. Only used when template_pipe_file is set.
[in]	replay_on_failure	Replay transmissions that fail. Only used when template_pipe_file is set.

Remarks

This function is reentrant.

See also

roc_tracker_best_image

roc_tracker_set_time_elapsed()

roc_error roc_tracker_set_time_elapsed	(	roc_tracker	tracker,
		roc_time	threshold_ms,
		roc_time	interval_ms
	)

Configure tracker to emit an event for a person a specified amount of time after they were first seen or previously seen.

By default milliseconds_threshold is 0 and ROC_ELAPSED_THRESHOLD will not be emitted. By default milliseconds_interval is 0 and ROC_ELAPSED_INTERVAL will not be emitted.

Parameters

[in]	tracker	Tracker to configure ROC_ELAPSED_THRESHOLD and ROC_ELAPSED_INTERVAL for.
[in]	threshold_ms	Milliseconds after which a ROC_ELAPSED_THRESHOLD event is emitted, or 0 to ignore.
[in]	interval_ms	Milliseconds after which a ROC_ELAPSED_INTERVAL event is emitted, or 0 to ignore.

Remarks

This function is reentrant.

roc_tracker_add_template()

roc_error roc_tracker_add_template	(	roc_tracker	tracker,
		const roc_template	template_
	)

Add a template to a tracker.

When a template is added to the tracker it may trigger zero or more roc_event. Events are added to a queue and can be retrieved in-order by calling roc_tracker_take_event.

Events are keyed off of the roc_template::person_id of roc_event::probe, which is the unique identifier for a person in tracker.

The tracker makes a copy of template_, so the caller still owns this value.

Event Reasons

There are different reasons an event might be tiggered. See roc_event_reasons for a list of all possible reasons. The reasons you wish to be notified about should be combined into a roc_event_type and passed to this function as reasons. An event with one or more roc_event::reasons shared in common with reasons will be added to the event queue.

Multiple Cameras

If you are tracking with multiple cameras, indicate which camera template_ came from with roc_template::media_id. To be notified when a person enters a new camera, include ROC_NEW_CAMERA as part of reasons.

Tracking

See roc_tracker_set_tracking_parameters for a description of the tracking algorithm implementation. The roc_template::timestamp stored in template_ is ignored in favor of the current system time so that multiple cameras need not have synced clocks, and templates can be received out-of-order when processed in parallel. Many of roc_event_reasons relate to tracking, but the most noteworthy are ROC_NEW_TRACK, ROC_MERGED_TRACKS and ROC_FINALIZED_TRACK.

Watchlisting

If you have one or more galleries of known identities to search template_ against, specify them with watchlists and num_watchlists. The highest similarity watchlist candidate exceeding min_watchlist_similarity will be reported. To be notified of a watchlist hit, include ROC_BETTER_CANDIDATE as part of reasons.

Retrieve a watchlist hit after this function call using roc_tracker_take_event. The roc_event::probe will be a copy of the template passed to this function and roc_event::candidate and roc_event::watchlist will be set.

If you don't have a watchlist, pass NULL for watchlists, 0 for num_watchlists, and ROC_INVALID_SIMILARITY for min_watchlist_similarity.

Example

roc_tracker tracker = ...;
roc_template template_ = ...;
roc_tracker_add_template(tracker, template, ROC_UNKNOWN_CAMERA);

Parameters

[in]	tracker	Tracker to add a template to.
[in]	template_	Template to add to the tracker.

Remarks

This function is thread-safe.

roc_tracker_add_image()

roc_error roc_tracker_add_image	(	roc_tracker	tracker,
		const roc_image	image,
		roc_stream	stream
	)

Convenience function for generating and tracking all templates in an image.

This function calls roc_represent on image with the parameters set by roc_tracker_set_represent_parameters. For each resulting template it calls roc_tracker_add_template.

Example

roc_tracker tracker = ...;
roc_image image = ...;
roc_tracker_add_image(tracker, image, NULL);

Parameters

[in]	tracker	Tracker to add templates to.
[in]	image	Image to construct templates from.
[in]	stream	Stream the image came from, or NULL.

Remarks

This function is thread-safe.

roc_tracker_add_encoded_image()

roc_error roc_tracker_add_encoded_image	(	roc_tracker	tracker,
		size_t	len,
		const uint8_t *	input_byte_array,
		roc_time	timestamp,
		roc_stream	stream
	)

Convenience function for generating and tracking all templates in an encoded image.

This function calls roc_decode_image then roc_represent with the parameters set by roc_tracker_set_represent_parameters. For each resulting template it calls roc_tracker_add_template.

Parameters

[in]	tracker	Tracker to add templates to.
[in]	len	Length of buffer.
[in]	input_byte_array	Encoded frame buffer.
[in]	timestamp	Timestamp associated with input_byte_array.
[in]	stream	Stream the image came from, or NULL.

Remarks

This function is thread-safe.

roc_tracker_update_time()

roc_error roc_tracker_update_time	(	roc_tracker	tracker,
		roc_time	timestamp
	)

Update a tracker's current time.

The tracker's current time is updated automatically when calling roc_tracker_add_image or roc_tracker_add_template. This function is useful if you have no more images or templates to add, and want to update the tracker's current time for the purpose of checking for newly finalized tracks.

Example

roc_tracker tracker = ...;
roc_time timestamp = ...;
roc_tracker_update_time(tracker, timestamp);

Parameters

[in]	tracker	Tracker to update the current time.
[in]	timestamp	Current time.

Remarks

This function is thread-safe.

roc_tracker_get_current_frame()

roc_error roc_tracker_get_current_frame	(	roc_tracker	tracker,
		roc_image *	frame,
		roc_event *	events,
		int *	num_events
	)

Obtain the most recently processed frame.

Note

events should be length k set by roc_tracker_set_represent_parameters.

If no new frame has been computed since the last call to this function the returned frame roc_image::data will be NULL. This function is generally used to update a graphical user interface, so the null case is an indication that no interface update is needed.

Free frame after use with roc_free_image, and events roc_event::probe after use with roc_free_template.

Parameters

[in]	tracker	Tracker to obtain the most recent frame from.
[out]	frame	Most recent frame processed by tracker, or NULL if you don't need the frame.
[out]	events	Computed events associated with the most recent processed frame.
[out]	num_events	Length of events.

Remarks

This function is thread-safe.

roc_tracker_cast()

void* roc_tracker_cast

(

roc_tracker

tracker

)

Cast and return a roc_tracker as a void*.

Helper function for some of the API language wrappers that don't support this type cast.

Parameters

[in]

tracker

Input tracker.

Remarks

This function is thread-safe.

roc_tracker_add_image_callback()

void roc_tracker_add_image_callback	(	roc_stream	stream,
		void *	tracker,
		roc_error	error,
		roc_image	image
	)

Alternative to roc_tracker_add_image with signature type roc_stream_image_callback.

If error is NULL and image is valid this function calls roc_tracker_add_image, otherwise it does nothing.

Example

roc_tracker tracker = ...;
roc_image image = ...;
roc_tracker_add_image_callback(tracker, NULL, image);

Parameters

[in]	stream	Origin stream.
[in]	tracker	Tracker to add templates to.
[in]	error	Reported error value.
[in]	image	Image to construct templates from.

Remarks

This function is thread-safe.

roc_tracker_add_encoded_image_callback()

void roc_tracker_add_encoded_image_callback	(	roc_stream	stream,
		void *	tracker,
		roc_error	error,
		size_t	len,
		const uint8_t *	input_byte_array,
		roc_time	timestamp
	)

Alternative to roc_tracker_add_image with signature type roc_stream_encoded_image_callback.

If error is NULL and buffer is valid this function calls roc_tracker_add_encoded_image, otherwise it does nothing.

Parameters

[in]	stream	Origin stream.
[in]	tracker	Tracker to add encoded images to.
[in]	error	Reported error value.
[in]	len	Length of buffer.
[in]	input_byte_array	Encoded frame buffer.
[in]	timestamp	Timestamp associated with input_byte_array.

Remarks

This function is thread-safe.

roc_tracker_has_events()

bool roc_tracker_has_events	(	roc_tracker	tracker,
		roc_time	wait
	)

Query if the tracker has events.

If the tracker has events they can be obtained one at a time with roc_tracker_take_event.

This function blocks for up to wait milliseconds for an event if none are available. If wait is 0 this function does not block.

Example

roc_tracker tracker = ...;
if (roc_tracker_has_events(tracker, 0))
    ...;

Parameters

[in]	tracker	Tracker to query for events.
[in]	wait	Maximum milliseconds to wait for an event if one is not immediately available.

Returns

true if tracker has events, false otherwise.

Remarks

This function is thread-safe.

See also

roc_tracker_take_event

roc_tracker_take_event()

roc_error roc_tracker_take_event	(	roc_tracker	tracker,
		roc_event *	event
	)

Obtain the next event from a tracker.

If event roc_event::reasons equals ROC_NO_EVENT then there are no more events, and the rest of the fields in event are unitialized.

Free event roc_event::probe after use with roc_free_template.

Example

roc_tracker tracker = ...;
roc_event;
while (true) {
    roc_tracker_take_event(tracker, &event);
    if (event.reasons == ROC_NO_EVENT)
        break;
    // ...
    roc_free_template(&event.probe);
}

Parameters

[in]	tracker	Tracker to take event from.
[out]	event	Next event in tracker.

Remarks

This function is thread-safe on tracker and reentrant on event.

See also

roc_tracker_has_events

roc_tracker_best_image()

roc_error roc_tracker_best_image	(	roc_tracker	tracker,
		roc_person_id	person_id,
		roc_image *	image
	)

Retrieve the current best image for an active track.

An active track is one for which ROC_NEW_TRACK has occured for person_id but not ROC_MERGED_TRACKS or ROC_FINALIZED_TRACK.

Finalized tracks have their best frames automatically written to disk if roc_tracker_set_best_image_parameters is called.

Free image after use with roc_free_image.

Parameters

[in]	tracker	Tracker to retrieve the best image from.
[in]	person_id	Track to retrieve the best image for.
[out]	image	Current best image for person_id.

Remarks

This function is thread-safe on tracker and reentrant on image.

roc_tracker_set_recorder_parameters()

roc_error roc_tracker_set_recorder_parameters	(	roc_tracker	tracker,
		const char *	database_path,
		bool	keep_alive,
		int	max_frames_stored,
		unsigned int	idr_interval,
		bool	persistent_recording_enabled,
		roc_time	persistent_recording_clips_duration
	)

Assign and configure an output recorder to a tracker.

Set up the recorder, specifying how much space can be used to hold video clips for retrieval. The full initialization process completes on the first call to roc_tracker_add_image.

Retrieve encoded video clips with roc_tracker_get_video_clip or roc_tracker_get_next_video_clip.

Parameters

[in]	tracker	Tracker to assign an output recorder to.
[in]	database_path	Path to the roc_template_pipe to write to.
[in]	keep_alive	Ignore transmission errors and re-establish the connection.
[in]	max_frames_stored	Max number of frames that can be stored at any time. Old frames are evicted when max size is reached. Recommend 5400 (3 minutes at 30 fps).
[in]	idr_interval	Number of milliseconds between IDR frames while recording.
[in]	persistent_recording_enabled	Specify whether to enable persistent recording.
[in]	persistent_recording_clips_duration	Duration of each clip when persistent recording.

Remarks

This function is reentrant.

roc_tracker_get_video_clip()

roc_error roc_tracker_get_video_clip	(	const roc_tracker	tracker,
		roc_time *	start_time,
		roc_time *	stop_time,
		roc_buffer *	bit_stream,
		size_t *	bit_stream_size
	)

Retrieve an MP4 video clip.

Retrieve an MP4 video clip based on the start time and stop time. A best effort attempt is made to bound the start time, though the start time may not be bounded if the earliest stored keyframe is after the start time. The last frame (keyframe or not) before stop time will be the last frame returned. The input start_time and stop_time will be modified by this function to reflect the exact timestamps of the first and last frame in the returned video.

This function will return an error if no part of the specified time range exists in the encoded frames held in memory.

Parameters

[in]	tracker	Tracker to retrive video clip from.
[in,out]	start_time	Start time for the desired video clip.
[in,out]	stop_time	Stop time for the desired video clip.
[out]	bit_stream	Video clip data.
[out]	bit_stream_size	Size of video clip data.

Remarks

This function is thread-safe.

roc_tracker_get_next_video_clip()

roc_error roc_tracker_get_next_video_clip	(	const roc_tracker	tracker,
		roc_time *	start_time,
		roc_time *	stop_time,
		roc_buffer *	bit_stream,
		size_t *	bit_stream_size
	)

Retrieve the next persistently-recorded MP4 video clip.

Retrieve the next consecutive clip of video from the recorder. The recorder internally tracks which clips have been requested from it in order to always return the next consecutive frames of MP4 data The output start_time and stop_time will contain the timestamps of the first and last frame returned.

This function will not return any data if the next logical video clip is still being recorded.

Parameters

[in]	tracker	Tracker to retrive video clip from.
[out]	start_time	Start time for the returned video clip.
[out]	stop_time	Stop time for the returned video clip.
[out]	bit_stream	Video clip data.
[out]	bit_stream_size	Size of video clip data.

Remarks

This function is thread-safe.

roc_tracker_flush_remaining_clips()

roc_error roc_tracker_flush_remaining_clips	(	const roc_tracker	tracker,
		roc_camera_id	camera_id
	)

Retrieve remaining recorded video clips when finished trackering.

Call this function before roc_free_tracker to retrieve the remaining recorded clips from a tracker before tracker deallocation. After calling this function, do not add further frames to the tracker via roc_tracker_add_image or roc_tracker_add_encoded_image. Additionally, do not attempt to retrieve further video clips via roc_tracker_store_next_clip or roc_tracker_get_next_video_clip. This function is only valid when persistently recording video. See roc_tracker_set_recorder_parameters.

Parameters

[in]	tracker	Tracker to retrieve remaining clips from.
[in]	camera_id	ID for the camera generating clips.

Remarks

This function is reentrant.

roc_tracker_get_earliest_recorded_time()

roc_error roc_tracker_get_earliest_recorded_time	(	const roc_tracker	tracker,
		roc_time *	timestamp
	)

Return the timestamp of the earliest held encoded frame.

Parameters

[in]	tracker	Tracker to query.
[out]	timestamp	Earliest timestamp, or ROC_NO_TIMESTAMP if buffer is empty.

Remarks

This function is thread-safe.

roc_tracker_get_current_recorded_time()

roc_error roc_tracker_get_current_recorded_time	(	const roc_tracker	tracker,
		roc_time *	timestamp
	)

Return the timestamp of the most recently encoded frame.

Parameters

[in]	tracker	Tracker to query.
[out]	timestamp	Most recent timestamp, or ROC_NO_TIMESTAMP if buffer is empty.

Remarks

This function is thread-safe.

roc_tracker_store_clip()

roc_error roc_tracker_store_clip	(	const roc_tracker	tracker,
		roc_media_id	media_id,
		roc_camera_id	camera_id,
		roc_time *	start,
		roc_time *	stop
	)

Transmit a video.

Convenience function which called roc_tracker_get_video_clip and roc_template_pipe_transmit_video. Please refer to those functions for more information.

Parameters

[in]	tracker	Tracker to query.
[in]	media_id	roc_hash_calc_sha1 of data.
[in]	camera_id	Camera unique identifier.
[in]	start	Video start time.
[in]	stop	Video stop time.

Remarks

This function is thread-safe.

roc_tracker_store_next_clip()

roc_error roc_tracker_store_next_clip	(	const roc_tracker	tracker,
		roc_media_id	media_id,
		roc_camera_id	camera_id,
		roc_time *	start,
		roc_time *	stop
	)

Transmit a persistently recorded video clip.

Convenience function which calls roc_tracker_get_next_video_clip and roc_template_pipe_transmit_video. Please refer to those functions for more information.

Parameters

[in]	tracker	Tracker to query.
[in]	media_id	roc_hash_calc_sha1 of data.
[in]	camera_id	Camera unique identifier.
[in]	start	Video start time.
[in]	stop	Video stop time.

Remarks

This function is thread-safe.

roc_free_tracker()

roc_error roc_free_tracker

(

roc_tracker

tracker

)

Free a tracker.

Deallocate memory for tracker previously allocated with roc_new_tracker.

Example

roc_tracker tracker = ...;
roc_free_tracker(tracker);

Parameters

[in]

tracker

Tracker to free.

Returns

This function is reentrant.

roc_event_type_to_string()

roc_error roc_event_type_to_string	(	roc_event_type	event_type,
		const char **	str
	)

String representation of a roc_event_type.

The string form uses the same character sequence as the code form. For example, ROC_NEW_PROBE is "ROC_NEW_PROBE". The returned str is statically-allocated data and should not be freed.

Parameters

[in]	event_type	Event type to convert to a string.
[out]	str	String version of event_type.

Remarks

This function is thread-safe.

See also

roc_event_type_from_string.

roc_event_type_from_string()

roc_error roc_event_type_from_string	(	const char *	str,
		roc_event_type *	event_type
	)

The opposite of roc_event_type_to_string.

Parameters

[in]	str	String to convert to a event_type.
[out]	event_type	Code version of str.

Remarks

This function is thread-safe.