Detailed Description

Defines the 2D box tracker API.

Note: SW Release Applicability: These APIs are available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

Data Structures
struct	dwBoxTracker2DParams
	Holds 2D object-tracker parameters. More...

struct	dwTrackedBox2D
	Holds a tracked 2D bounding box. More...

Typedefs
typedef struct dwBoxTracker2DObject *	dwBoxTracker2DHandle_t
	Handle to a 2D object tracker. More...

Functions
DW_API_PUBLIC dwStatus	dwBoxTracker2D_add (const dwBox2D *boxes, size_t num, dwBoxTracker2DHandle_t obj)
	Adds bounding boxes to the tracker. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_addPreClustered (const dwTrackedBox2D *boxes, size_t num, dwBoxTracker2DHandle_t obj)
	Adds pre-clustered bounding boxes to the tracker. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_enablePriorityTracking (bool enable, dwBoxTracker2DHandle_t obj)
	Enables priority tracking of a boundary box. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_get (const dwTrackedBox2D *boxList, size_t num, dwBoxTracker2DHandle_t obj)
	Gets tracked bounding boxes and IDs. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_getTrackingPriority (float32_t *priority, uint32_t idx, dwBoxTracker2DHandle_t obj)
	Returns the priority of a bounding box. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_initialize (dwBoxTracker2DHandle_t obj, const dwBoxTracker2DParams parameters, int32_t imageWidth, int32_t imageHeight, dwContextHandle_t context)
	Initializes 2D bounding box tracker. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_initParams (dwBoxTracker2DParams *parameters)
	Initializes 2D tracker parameters with default values. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_release (dwBoxTracker2DHandle_t obj)
	Releases the 2D bounding box tracker. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_reset (dwBoxTracker2DHandle_t obj)
	Resets the 2D bounding box tracker. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_setTrackingPriority (uint32_t idx, float32_t priority, dwBoxTracker2DHandle_t obj)
	Sets the priority of a bounding box. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_shallowReset (dwBoxTracker2DHandle_t obj)
	Performs a shallow reset on the 2D bounding box tracker. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_track (const float32_t curFeatureLocations, const dwFeature2DStatus curFeatureStatuses, const float32_t *preFeatureLocations, dwBoxTracker2DHandle_t obj)
	Tracks the bounding boxes. More...

DW_API_PUBLIC dwStatus	dwBoxTracker2D_updateFeatures (const float32_t featureLocations, const dwFeature2DStatus statuses, size_t nFeatures, dwBoxTracker2DHandle_t obj)
	Updates the feature locations of the 2D bounding boxes. More...

Data Structure Documentation

◆ dwBoxTracker2DParams

struct dwBoxTracker2DParams

Data Fields
float32_t	confRateDetect	Rate at which to combine confidence values of new boxes to existing tracked boxes when a new box is found to match an existing box, i.e., conf = conf + conf_new * rate. This also applies to the initial confidence value for a new box, i.e., conf = conf_new * rate.
float32_t	confRateTrack	Rate at which confidence values of tracked boxes changes from frame to frame, i.e., conf = conf - rate.
float32_t	confThreshConfirm	Threshold on confidence below which tracker no longer report box location. Box continues to be tracked until confidence falls below discard threshold.
float32_t	confThreshDiscard	Threshold on confidence below which tracker no longer track box location.
uint32_t	groupThreshold	Minimum possible number of boxes minus 1. groupThreshold = 0 means every input box is considered as a valid initialization. Setting a larger value is more robust to outliers. It merges close-by input boxes and uses the average instead.
uint32_t	maxBoxCount	Maximum 2D boxes to track.
float64_t	maxBoxImageScale	Maximum box scale in the image to track. It multiplies with image width and height to get the maximum box size.
uint32_t	maxFeatureCountPerBox	Maximum features to track for each 2D bounding box.
float32_t	maxMatchDistance	Maximum distance around the closest tracked box to search for a candidate matching box. Distance here is defined as delta 1 - IOU. Within this margin, the box with the longest track history is preferred and is selected as the candidate matching box. The candidate still has to pass the minMatchOverlap test to be considered a positive match for the new box.
float64_t	minBoxImageScale	Minimum box scale in the image to track. It multiplies with image width and height to get the minimum box size.
float32_t	minMatchOverlap	Minimum amount of overlap between a tracked box and an added box such that the 2 boxes can be considered the same object. Overlap is defined as the intersection over the union (IOU).
float64_t	similarityThreshold	The threshold to define the location and size similarity of the bounding boxes. It does not perform clustering when similarity = 0. All the boxes are in one cluster when similarity = +inf.

◆ dwTrackedBox2D

struct dwTrackedBox2D

Data Fields
dwBox2D	box	Bounding box location and size.
float32_t	confidence	Confidence in tracking results.
const float32_t *	featureLocations	2d feature coordinates inside the bounding box.
int32_t	id	Bounding box ID.
size_t	nFeatures	Total number of tracked 2D features.
int32_t	trackedFrameCount	Total number of tracked frames.

Typedef Documentation

◆ dwBoxTracker2DHandle_t

typedef struct dwBoxTracker2DObject* dwBoxTracker2DHandle_t

Handle to a 2D object tracker.

Definition at line 66 of file BoxTracker2D.h.

Function Documentation

◆ dwBoxTracker2D_add()

DW_API_PUBLIC dwStatus dwBoxTracker2D_add	(	const dwBox2D *	boxes,
		size_t	num,
		dwBoxTracker2DHandle_t	obj
	)

Adds bounding boxes to the tracker.

The tracker first performs clustering to the group close-by redundant bounding boxes. In each cluster, the average box is computed and added to the tracker.

Parameters

[in]	boxes	The list of 2D bounding boxes to added.
[in]	num	Number of boxes passed in the given list.
[in]	obj	Handle to the 2D bounding box tracker.

Returns: DW_INVALID_ARGUMENT if box tracker2D handle is NULL or num is greater than 0 and boxes is NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_addPreClustered()

DW_API_PUBLIC dwStatus dwBoxTracker2D_addPreClustered	(	const dwTrackedBox2D *	boxes,
		size_t	num,
		dwBoxTracker2DHandle_t	obj
	)

Adds pre-clustered bounding boxes to the tracker.

The tracker assumes input boxes are pre-clustered and all boxes are added to the tracker. If the input box matches an internal tracked box, the ID of the internal tracked box is preferred.

Parameters

[in]	boxes	The list of pre-clustered boxes.
[in]	num	Number of boxes passed in the given list.
[in]	obj	Handle to the 2D bounding box tracker.

Returns: DW_INVALID_ARGUMENT if box tracker2D handle is NULL or num is greater than 0 and boxes is NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_enablePriorityTracking()

DW_API_PUBLIC dwStatus dwBoxTracker2D_enablePriorityTracking	(	bool	enable,
		dwBoxTracker2DHandle_t	obj
	)

Enables priority tracking of a boundary box.

The priority of the bounding boxes can be used to control the association between 2D features and bounding boxes in case of overlap. With priority tracking enabled, the box with the higher priority gets the feature.

Parameters

[in]	enable	Enables (true)/disable(false) priority tracking.
[in]	obj	Handle to the 2D bounding box tracker.

Returns: DW_INVALID_ARGUMENT if box tracker2D handle is NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_get()

DW_API_PUBLIC dwStatus dwBoxTracker2D_get	(	const dwTrackedBox2D **	boxList,
		size_t *	num,
		dwBoxTracker2DHandle_t	obj
	)

Gets tracked bounding boxes and IDs.

Parameters

[out]	boxList	The list of tracked bounding boxes.
[out]	num	Number of bounding box returned in boxList.
[in]	obj	Handle to the 2D bounding box tracker.

Returns: DW_INVALID_ARGUMENT if any parameter is NULL.
DW_SUCCESS otherwise.

Note: boxList is pointing to an internally allocated memory.

◆ dwBoxTracker2D_getTrackingPriority()

DW_API_PUBLIC dwStatus dwBoxTracker2D_getTrackingPriority	(	float32_t *	priority,
		uint32_t	idx,
		dwBoxTracker2DHandle_t	obj
	)

Returns the priority of a bounding box.

Parameters

[out]	priority	Tracking priority (smaller value == higher priority).
[in]	idx	Index of the object.
[in]	obj	Handle to the 2D bounding box tracker.

Returns: DW_INVALID_ARGUMENT if box tracker2D handle or priority is NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_initialize()

DW_API_PUBLIC dwStatus dwBoxTracker2D_initialize	(	dwBoxTracker2DHandle_t *	obj,
		const dwBoxTracker2DParams *	parameters,
		int32_t	imageWidth,
		int32_t	imageHeight,
		dwContextHandle_t	context
	)

Initializes 2D bounding box tracker.

Parameters

[out]	obj	Handle to 2D bounding box tracker.
[in]	parameters	The 2D tracker parameters.
[in]	imageWidth	The width of the image.
[in]	imageHeight	The height of the image.
[in]	context	Handle to the context under which it is created.

Returns: DW_INVALID_ARGUMENT if box tracker2D handle or parameters are NULL or imageWidht or imageHeight are equal or less than zero.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_initParams()

DW_API_PUBLIC dwStatus dwBoxTracker2D_initParams ( dwBoxTracker2DParams * parameters )

Initializes 2D tracker parameters with default values.

Parameters

[out] parameters 2D tracker parameters.

Returns: DW_INVALID_ARGUMENT if parameters are NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_release()

DW_API_PUBLIC dwStatus dwBoxTracker2D_release ( dwBoxTracker2DHandle_t obj )

Releases the 2D bounding box tracker.

Parameters

[in] obj Handle to release.

Returns: DW_INVALID_HANDLE if box tracker2D handle is NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_reset()

DW_API_PUBLIC dwStatus dwBoxTracker2D_reset ( dwBoxTracker2DHandle_t obj )

Resets the 2D bounding box tracker.

Parameters

[in] obj Handle to reset.

Returns: DW_INVALID_ARGUMENT if box tracker2D handle is NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_setTrackingPriority()

DW_API_PUBLIC dwStatus dwBoxTracker2D_setTrackingPriority	(	uint32_t	idx,
		float32_t	priority,
		dwBoxTracker2DHandle_t	obj
	)

Sets the priority of a bounding box.

Parameters

[in]	idx	Index of the object.
[in]	priority	Tracking priority (smaller value == higher priority).
[in]	obj	Handle to the 2D bounding box tracker.

Returns: DW_INVALID_ARGUMENT if box tracker2D handle is NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_shallowReset()

DW_API_PUBLIC dwStatus dwBoxTracker2D_shallowReset ( dwBoxTracker2DHandle_t obj )

Performs a shallow reset on the 2D bounding box tracker.

This function does not initialize all variables. It just sets the count to zero.

Parameters

[in] obj Handle to reset.

Returns: DW_INVALID_ARGUMENT if box tracker2D handle is NULL.
DW_SUCCESS otherwise.

◆ dwBoxTracker2D_track()

DW_API_PUBLIC dwStatus dwBoxTracker2D_track	(	const float32_t *	curFeatureLocations,
		const dwFeature2DStatus *	curFeatureStatuses,
		const float32_t *	preFeatureLocations,
		dwBoxTracker2DHandle_t	obj
	)

Tracks the bounding boxes.

Parameters

[in]	curFeatureLocations	The feature locations computed in the current image frame. It has 2*featureCount number of items.
[in]	curFeatureStatuses	The feature statues of the current image frame. It has featureCount number of items.
[in]	preFeatureLocations	The feature locations computed in the previous image frame. It has 2*featureCount number of items.
[in]	obj	Handle to the 2D bounding box tracker.

Returns: DW_INVALID_ARGUMENT if any parameter is NULL.
DW_SUCCESS otherwise.

Note: Ensure the curFeatureLocations argument has the same size as preFeatureLocations. For guidance on processing feature locations and statuses, see Basic Object Detector and Tracker Sample.

◆ dwBoxTracker2D_updateFeatures()

DW_API_PUBLIC dwStatus dwBoxTracker2D_updateFeatures	(	const float32_t *	featureLocations,
		const dwFeature2DStatus *	statuses,
		size_t	nFeatures,
		dwBoxTracker2DHandle_t	obj
	)

Updates the feature locations of the 2D bounding boxes.

This function call must occur between dwBoxTracker2D_track() and dwBoxTracker2D_get().

Parameters

[in]	featureLocations	The feature locations with 2*nFeatures items.
[in]	statuses	The feature statuses with nFeatures items.
[in]	nFeatures	The number of 2D features, 0 < nFeatures < 8000.
[in]	obj	Handle to the 2D bounding box tracker.

Returns: DW_INVALID_ARGUMENT if box the tracker2D handle, featureLocations, or statuses are NULL; or if nFeatures is greater than 8000.
DW_SUCCESS otherwise.

Detailed Description

Data Structures

Typedefs

Functions

Data Structure Documentation

◆ dwBoxTracker2DParams

◆ dwTrackedBox2D

Typedef Documentation

◆ dwBoxTracker2DHandle_t

Function Documentation

◆ dwBoxTracker2D_add()

◆ dwBoxTracker2D_addPreClustered()

◆ dwBoxTracker2D_enablePriorityTracking()

◆ dwBoxTracker2D_get()

◆ dwBoxTracker2D_getTrackingPriority()

◆ dwBoxTracker2D_initialize()

◆ dwBoxTracker2D_initParams()

◆ dwBoxTracker2D_release()

◆ dwBoxTracker2D_reset()

◆ dwBoxTracker2D_setTrackingPriority()

◆ dwBoxTracker2D_shallowReset()

◆ dwBoxTracker2D_track()

◆ dwBoxTracker2D_updateFeatures()