CelanturSDK::Tracker Class Reference

Manages object persistence and state across sequential video frames. The Tracker takes raw detections and associates them over time to create consistent tracks. This tracks can be then used to combat flickering of detections. More...

#include <CelanturSDKInterface.h>

Public Member Functions
	Tracker (std::filesystem::path license_path, float min_iou_threshold=0.3f, float high_score_threshold=0.7f)
	Constructs a new Tracker instance. More...
void	update (const std::vector< celantur::CelanturDetection > &detections)
	Processes a new frame of detections. More...
std::vector< celantur::CelanturDetection >	get_lost_detections () const
	Retrieves detections associated with tracks currently in the 'Lost' state. More...
void	reset ()
	Resets the tracker state. More...
void	init_logging ()
	Initializes the internal logging system for the Tracker module. More...
Rule of Five
Standard memory management
	Tracker (const Tracker &other)=delete
Tracker &	operator= (const Tracker &other)=delete
	Tracker (Tracker &&other) noexcept
Tracker &	operator= (Tracker &&other) noexcept
	~Tracker ()

Detailed Description

Manages object persistence and state across sequential video frames. The Tracker takes raw detections and associates them over time to create consistent tracks. This tracks can be then used to combat flickering of detections.

Constructor & Destructor Documentation

Tracker() [1/3]

Tracker::Tracker	(	std::filesystem::path	license_path,
		float	min_iou_threshold = 0.3f,
		float	high_score_threshold = 0.7f
	)

Constructs a new Tracker instance.

• Parameters

  license_path	Path to the Celantur license file required for operation.
  min_iou_threshold	The minimum Intersection over Union (IoU) required to associate a new detection with an existing track. Range: [0.0, 1.0]. Lower IOU makes it easier for tracker to track detections when they are moving fast in the image, but it also makes it less accurate. Make it higher if you get a lot of false-positives from tracker and lower if the objects that are moving quickly in the frame are lost too often
  high_score_threshold	The confidence value above which a detection is getting initialised into track. The detection needs to be two frames above this confidence to become a frame. Decrease it if you have multiple low-confidence detections that you still want to track. Increase it to decrease the amount of false positives.

  See also

  https://learnopencv.com/wp-content/uploads/2022/06/2-iou-illustration.png

  Current Values for both parameters were selected to get the best results for normal dashcam videos. Feel free to tune them to get better results.

References CelanturSDK::License::_pimpl.

Tracker() [2/3]

CelanturSDK::Tracker::Tracker ( const Tracker &  other )

delete

Tracker() [3/3]

Tracker::Tracker ( Tracker &&  other )

noexcept

~Tracker()

Tracker::~Tracker

(

)

Member Function Documentation

get_lost_detections()

std::vector< celantur::CelanturDetection > Tracker::get_lost_detections

(

)

const

Retrieves detections associated with tracks currently in the 'Lost' state.

Use this to apply predictive anonymization on objects that were recently tracked but temporarily disappeared. These detections often are very good approximations of where the object would be given a couple of conditions:

1. Camera does not shake too much. When camera shakes, e.g. dashcam on the bad road, predicting where the given detection will be the next frame is almost impossible.
2. The object disappearing was a failure of AI. If the object disappeared due to e.g. being covered by another object temporarily it would still count is lost

In summary, tracking can be a very good way to combat intermittent detection flickering but in some usecasees it might become active hindrance for anonymisation quality. Test it for your usecase!

Returns

std::vector<celantur::CelanturDetection> A list of interpolated or last-known detections.

References celantur::CelanturDetection::class_id.

init_logging()

void Tracker::init_logging

(

)

Initializes the internal logging system for the Tracker module.

Internal module is written in Rust and its logging can be controlled by Rust env logger

See also

https://docs.rs/env_logger/latest/env_logger/

operator=() [1/2]

Tracker& CelanturSDK::Tracker::operator= ( const Tracker &  other )

delete

operator=() [2/2]

Tracker & Tracker::operator= ( Tracker &&  other )

noexcept

reset()

void Tracker::reset

(

)

Resets the tracker state.

use when you need to process new video and you need to clear all existing tracks.

update()

void Tracker::update

(

const std::vector< celantur::CelanturDetection > &

detections

)

Processes a new frame of detections.

• Updates the internal state of all tracks. This method will:

1. Attempt to match detections to existing tracks via IoU.
2. Promote Tentative tracks to Confirmed if consistently detected.
3. Mark Confirmed tracks as Lost if they are missing in the current frame.

• Parameters

  detections

  a vector of detections found in the current frame.