tracking::MultiTracker Class Reference

Class for tracking multiple bounding boxes in images using OpenCV. This class supports all OpenCV tracking algorithms and can be used to track multiple objects in a single image or video stream. More...

#include <BoundingBoxTracking.h>

Public Member Functions
	MultiTracker (const double dTrackingLostTimeout=1.0, const double dMaxTrackingTime=3.0, const double dIOUThreshold=0.3)
	Construct a new Multi Tracker object.
	~MultiTracker ()
	Destroy the Multi Tracker object.
bool	InitTracker (const cv::Mat &cvFrame, const std::shared_ptr< cv::Rect2d > cvBoundingBox, const TrackerType eTrackerType=TrackerType::eKCF)
	Add a new tracker for a given frame and bounding box.
void	Update (const cv::Mat &cvFrame)
	Initialize the MultiTracker with a new frame and a vector of bounding boxes.
void	ClearTrackers ()
	Clear all trackers and bounding boxes from the MultiTracker.
void	SetTrackerLostTimeout (const double dTimeout)
	Set the timeout for when a tracker is considered lost.
void	SetMaxTrackingTime (const double dMaxTime)
	Set the maximum tracking time for a tracker.
double	GetTrackerLostTimeout () const
	Get the timeout for when a tracker is considered lost.
double	GetMaxTrackingTime () const
	Get the maximum tracking time for a tracker.

Private Member Functions
double	CalculateIOU (const cv::Rect2d &cvBoxA, const cv::Rect2d &cvBoxB)
	Calculate the Intersection over Union (IoU) of two bounding boxes.
cv::Ptr< cv::Tracker >	CreateTracker (const TrackerType eType)
	Create a tracker based on the specified type.

Private Attributes
std::map< int, cv::Ptr< cv::Tracker > >	m_mTrackers
std::map< int, std::shared_ptr< cv::Rect2d > >	m_mBoundingBoxes
std::map< int, std::chrono::system_clock::time_point >	m_mLastUpdateTime
std::map< int, std::chrono::system_clock::time_point >	m_mTimeSinceLastGroundTruthDetection
double	m_dTrackingLostThreshold
double	m_dMaxTrackingTime
double	m_dIOUThreshold
int	m_nNextId

Detailed Description

Class for tracking multiple bounding boxes in images using OpenCV. This class supports all OpenCV tracking algorithms and can be used to track multiple objects in a single image or video stream.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-14

Constructor & Destructor Documentation

MultiTracker()

tracking::MultiTracker::MultiTracker	(	const double	dTrackingLostThreshold = 1.0,
		const double	dMaxTrackingTime = 3.0,
		const double	dIOUThreshold = 0.3
	)

Construct a new Multi Tracker object.

Parameters

dTrackingLostThreshold	- The time in seconds after which a tracker is considered lost (default is 1.0).
dMaxTrackingTime	- The maximum time in seconds a tracker can be lost before being removed (default is 3.0).
dIOUThreshold	- The minimum Intersection over Union (IoU) required to associate a new detection with an existing tracker (default is 0.3).

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-15

    {
        // Initialize member variables.
        m_dTrackingLostThreshold = dTrackingLostThreshold;
        m_dMaxTrackingTime       = dMaxTrackingTime;
        m_dIOUThreshold          = dIOUThreshold;
        m_nNextId                = 0;
    }

~MultiTracker()

tracking::MultiTracker::~MultiTracker

(

)

Destroy the Multi Tracker object.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-15

    {
        // Nothing to do yet.
    }

Member Function Documentation

InitTracker()

bool tracking::MultiTracker::InitTracker	(	const cv::Mat &	cvFrame,
		const std::shared_ptr< cv::Rect2d >	cvBoundingBox,
		const TrackerType	eTrackerType = TrackerType::eKCF
	)

Add a new tracker for a given frame and bounding box.

Parameters

cvFrame	- The frame to initialize the tracker with.
cvBoundingBox	- The bounding box (cv::Rect2d) for the object to track.
eTrackerType	- The type of tracker to use (default is KCF).

Returns

true - The given bounding box was matched to an existing tracker and the tracker was updated.

false - The given bounding box was not matched to an existing tracker and a new tracker was created.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-15

    {
        // Create instance variables.
        double dBestIOU         = 0.0;
        int nBestTrackerID      = -1;
        bool bMatchedOldTracker = false;
 
        // Loop through the existing trackers to find the best match for the given bounding box.
        for (const std::pair<int, std::shared_ptr<cv::Rect2d>>& stdEntry : m_mBoundingBoxes)
        {
            int nID     = stdEntry.first;
            double dIOU = this->CalculateIOU(*stdEntry.second, *cvBoundingBox);
            if (dIOU > dBestIOU)
            {
                dBestIOU       = dIOU;
                nBestTrackerID = nID;
            }
        }
 
        // Catch OpenCV exceptions.
        try
        {
            // If the best IoU is above the threshold and a tracker was found, update the tracker.
            if (dBestIOU > m_dIOUThreshold && nBestTrackerID != -1)
            {
                // Reinitialize the tracker with the new bounding box.
                m_mBoundingBoxes[nBestTrackerID]->x      = cvBoundingBox->x;
                m_mBoundingBoxes[nBestTrackerID]->y      = cvBoundingBox->y;
                m_mBoundingBoxes[nBestTrackerID]->width  = cvBoundingBox->width;
                m_mBoundingBoxes[nBestTrackerID]->height = cvBoundingBox->height;
                cv::Ptr<cv::Tracker> cvTracker           = this->CreateTracker(eTrackerType);
                cvTracker->init(cvFrame, *m_mBoundingBoxes[nBestTrackerID]);
                // Update the last update time for the tracker.
                m_mLastUpdateTime[nBestTrackerID] = std::chrono::system_clock::now();
                // Update the time since the last ground truth detection.
                m_mTimeSinceLastGroundTruthDetection[nBestTrackerID] = std::chrono::system_clock::now();
                // Set the matched tracker flag.
                bMatchedOldTracker = true;
            }
            else
            {
                // Create a new tracker and initialize it with the given frame and bounding box.
                cv::Ptr<cv::Tracker> cvTracker = this->CreateTracker(eTrackerType);
                cvTracker->init(cvFrame, *cvBoundingBox);
                // Add the new tracker to the maps.
                m_mTrackers[m_nNextId]                          = cvTracker;
                m_mBoundingBoxes[m_nNextId]                     = cvBoundingBox;
                m_mLastUpdateTime[m_nNextId]                    = std::chrono::system_clock::now();
                m_mTimeSinceLastGroundTruthDetection[m_nNextId] = std::chrono::system_clock::now();
                m_nNextId++;
            }
        }
        catch (const std::exception& stdException)
        {
            // Submit logger message if an exception occurs.
            LOG_ERROR(logging::g_qSharedLogger, "Exception in tracker initialization: {}", stdException.what());
            // Set the bounding box to 0,0,0,0.
            cvBoundingBox->x      = 0;
            cvBoundingBox->y      = 0;
            cvBoundingBox->width  = 0;
            cvBoundingBox->height = 0;
        }
 
        return bMatchedOldTracker;
    }

Here is the call graph for this function:

Update()

void tracking::MultiTracker::Update

(

const cv::Mat &

cvFrame

)

Initialize the MultiTracker with a new frame and a vector of bounding boxes.

Parameters

cvFrame

- The initial frame to track objects in.

Note

If the tracking for a bounding box is lost, it will be set to 0,0,0,0 and removed from the tracker.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-15

    {
        // Create instance variables.
        std::vector<int> vToRemove;
        std::chrono::system_clock::time_point tmCurrentTime = std::chrono::system_clock::now();
 
        // Loop through the existing trackers.
        for (const std::pair<const int, cv::Ptr<cv::Tracker>>& stdEntry : m_mTrackers)
        {
            // Create instance variables.
            int nID = stdEntry.first;
            cv::Rect cvBoundingBox;
 
            // Check if the tracker is valid
            if (!stdEntry.second)
            {
                LOG_WARNING(logging::g_qSharedLogger, "Tracker is null for ID: {}", std::to_string(nID));
                continue;
            }
 
            // OpenCV loves to throw exceptions, so we need to catch them.
            try
            {
                // Try to update the tracker with the current frame.
                if (stdEntry.second->update(cvFrame, cvBoundingBox))
                {
                    // Update the bounding box
                    m_mBoundingBoxes[nID]->x      = cvBoundingBox.x;
                    m_mBoundingBoxes[nID]->y      = cvBoundingBox.y;
                    m_mBoundingBoxes[nID]->width  = cvBoundingBox.width;
                    m_mBoundingBoxes[nID]->height = cvBoundingBox.height;
                    m_mLastUpdateTime[nID]        = tmCurrentTime;
                }
 
                // If the tracker fails to update, we need to check if it has been lost for too long.
                double dTimeElapsedSinceGoodTrack = std::chrono::duration_cast<std::chrono::milliseconds>(tmCurrentTime - m_mLastUpdateTime[nID]).count() / 1000.0;
                double dTimeElapsedSinceLastDetection =
                    std::chrono::duration_cast<std::chrono::milliseconds>(tmCurrentTime - m_mTimeSinceLastGroundTruthDetection[nID]).count() / 1000.0;
                if (dTimeElapsedSinceGoodTrack > m_dTrackingLostThreshold || dTimeElapsedSinceLastDetection > m_dMaxTrackingTime)
                {
                    vToRemove.push_back(nID);
                }
            }
            catch (const std::exception& stdException)
            {
                // Submit logger message if an exception occurs.
                LOG_ERROR(logging::g_qSharedLogger, "Exception in tracker update for ID: {} Error {}", nID, stdException.what());
                // Remove the problematic tracker.
                vToRemove.push_back(nID);
            }
        }
 
        // Remove trackers that have been lost for too long.
        for (int nID : vToRemove)
        {
            // Remove the tracker and last update time from the maps.
            m_mTrackers.erase(nID);
            m_mLastUpdateTime.erase(nID);
            m_mTimeSinceLastGroundTruthDetection.erase(nID);
 
            // Set the bounding box to 0,0,0,0.
            m_mBoundingBoxes[nID]->x      = 0;
            m_mBoundingBoxes[nID]->y      = 0;
            m_mBoundingBoxes[nID]->width  = 0;
            m_mBoundingBoxes[nID]->height = 0;
            // Remove the bounding box from the map.
            m_mBoundingBoxes.erase(nID);
        }
    }

ClearTrackers()

void tracking::MultiTracker::ClearTrackers

(

)

Clear all trackers and bounding boxes from the MultiTracker.

Note

This function will set all bounding boxes to 0,0,0,0 and remove all trackers.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-27

    {
        m_mTrackers.clear();
        m_mLastUpdateTime.clear();
        m_mTimeSinceLastGroundTruthDetection.clear();
 
        // Set the bounding boxes to 0,0,0,0.
        for (const std::pair<int, std::shared_ptr<cv::Rect2d>>& stdEntry : m_mBoundingBoxes)
        {
            stdEntry.second->x      = 0;
            stdEntry.second->y      = 0;
            stdEntry.second->width  = 0;
            stdEntry.second->height = 0;
        }
        // Clear the bounding boxes.
        m_mBoundingBoxes.clear();
    }

SetTrackerLostTimeout()

void tracking::MultiTracker::SetTrackerLostTimeout

(

const double

dTimeout

)

Set the timeout for when a tracker is considered lost.

Parameters

dTimeout

- The time in seconds after which a tracker is considered lost.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-29

    {
        m_dTrackingLostThreshold = dTimeout;
    }

SetMaxTrackingTime()

void tracking::MultiTracker::SetMaxTrackingTime

(

const double

dMaxTime

)

Set the maximum tracking time for a tracker.

Parameters

dMaxTime

- The maximum time in seconds a tracker can be lost before being removed.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-04-15

    {
        m_dMaxTrackingTime = dMaxTime;
    }

GetTrackerLostTimeout()

double tracking::MultiTracker::GetTrackerLostTimeout

(

)

const

Get the timeout for when a tracker is considered lost.

Returns

double - The time in seconds after which a tracker is considered lost.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-29

    {
        return m_dTrackingLostThreshold;
    }

GetMaxTrackingTime()

double tracking::MultiTracker::GetMaxTrackingTime

(

)

const

Get the maximum tracking time for a tracker.

Returns

double - The maximum time in seconds a tracker can be lost before being removed.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-04-15

    {
        return m_dMaxTrackingTime;
    }

CalculateIOU()

double tracking::MultiTracker::CalculateIOU ( const cv::Rect2d &  cvBoxA, const cv::Rect2d &  cvBoxB  )

private

Calculate the Intersection over Union (IoU) of two bounding boxes.

Parameters

cvBoxA	- The first bounding box (cv::Rect2d).
cvBoxB	- The second bounding box (cv::Rect2d).

Returns

double - The IoU value between the two bounding boxes, ranging from 0.0 to 1.0.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-15

    {
        // Calculate the intersection area.
        double dIntersectionArea = (cvBoxA & cvBoxB).area();
        // Calculate the union area.
        double dUnionArea = cvBoxA.area() + cvBoxB.area() - dIntersectionArea;
        // Return the Intersection over Union (IoU).
        return (dUnionArea > 0) ? (dIntersectionArea / dUnionArea) : 0.0;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

CreateTracker()

cv::Ptr< cv::Tracker > tracking::MultiTracker::CreateTracker ( const TrackerType  eType )

private

Create a tracker based on the specified type.

Parameters

eType

- The type of tracker to create (eMIL, eKCF, eGOTURN, eCSRT).

Returns

cv::Ptr<cv::Tracker> - A pointer to the created tracker.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-03-29

    {
        // Catch OpenCV exceptions.
        try
        {
            // Create a tracker based on the specified type.
            switch (eType)
            {
                case TrackerType::eMIL: return cv::TrackerMIL::create(); break;
                case TrackerType::eKCF: return cv::TrackerKCF::create(); break;
                case TrackerType::eCSRT: return cv::TrackerCSRT::create(); break;
                default:
                    // Submit a warning message if the tracker type is unknown.
                    LOG_WARNING(logging::g_qSharedLogger, "Unknown tracker type specified. Defaulting to KCF.");
                    // Return a default tracker (KCF) if the type is unknown.
                    return cv::TrackerKCF::create();
                    break;
            }
        }
        catch (const std::exception& stdException)
        {
            // Submit a warning message if an exception occurs.
            LOG_ERROR(logging::g_qSharedLogger, "Exception in tracker creation: {}", stdException.what());
            // Return a default tracker (KCF) if an exception occurs.
            return cv::TrackerKCF::create();
        }
    }

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• src/util/vision/BoundingBoxTracking.h
• src/util/vision/BoundingBoxTracking.cpp