ScalingFeatureTracker

Detailed Description

Defines scaling-extend KLT module for object tracking.

• Template
  It's a subimage defined by ROI (regions of interest) that is going to be tracked in the new frame.
  
• Tracker workflow
  
  1. Mark existing features as valid/invalid features based on its size (see applySizeFilter) or other user-defined validation function. ScalingFeatureTracker works better for feature size less than DW_MAX_TEMPLATE_SIZE x DW_MAX_TEMPLATE_SIZE, but this is an optional step. The tracker DOES work with larger feature size.
  2. Compact list (see selectValid and compactList)
  3. Add new features to the list. This module does not provide a feature detector. The user decides what new features to add.
  4. Update feature templates (see updateTemplateAsync)
  5. Do tracking (see trackAsync)
• Template updating strategy
  The template is not updated every frame. When KLT iteration is finished and the tracker gets the new predicted feature in the new frame, it will calculate the ZNCC (zero normalized cross-correlation) between the warped templated feature and the predicted one, only when ZNCC is less than a predifined updateThreshold, the template feature and its location/size will be updated, elsewise the tracker will use the old template feature and its size as an estimation and moves its location to the new one. There is another killing threshold (smaller than updateThreshold), if ZNCC is even less than killing threshold, it will be considered that the tracked result differs so much to the template that the tracking is failed and the current feature entry will be killed. In order to prevent track drifting, there're 2 more parameter to control the feature template updating. One is maxPixelTolerance, feature template location will be updated only when the center position of old and new feature is greater than this value. The other is maxSizeDifference, once the ratio of old and new feature size is greater than it, tracker will trigger a force template updating.

  
  Psudo code:
  if (ZNCC < killThreshold)
      tracking is lost, kill the current feature
      return

if (ZNCC < updateThreshold)
    feature template image <– new image
    feature template location <– new location
    feature template size <– new size
else
    if (templateSize/newSize is not within [1/maxSizeDifference, maxSizeDifference])
        feature template image <– new image
        feature template location <– new location
        feature template size <– new size

    else if ((templateCenter - newCenter) > maxPixelTolerance)
        feature template location <– new location
}

Functions
DW_API_PUBLIC dwStatus	dwScalingFeatureTracker_getCUDAStream (cudaStream_t *cudaStream, dwScalingFeatureTrackerHandle_t obj)
	Gets the CUDA stream used. More...
DW_API_PUBLIC dwStatus	dwScalingFeatureTracker_initDefaultParams (dwScalingFeatureTrackerParameters *params)
	Initializes ScalingFeatureTracker parameters with default values. More...
DW_API_PUBLIC dwStatus	dwScalingFeatureTracker_initialize (dwScalingFeatureTrackerHandle_t *obj, const dwScalingFeatureTrackerParameters *params, cudaStream_t stream, dwContextHandle_t context)
	Initialize the ScalingFeatureTracker module. More...
DW_API_PUBLIC dwStatus	dwScalingFeatureTracker_release (dwScalingFeatureTrackerHandle_t *obj)
	Releases the ScalingFeatureTracker module. More...
DW_API_PUBLIC dwStatus	dwScalingFeatureTracker_reset (dwScalingFeatureTrackerHandle_t obj)
	Resets the ScalingFeatureTracker. More...
DW_API_PUBLIC dwStatus	dwScalingFeatureTracker_setCUDAStream (cudaStream_t cudaStream, dwScalingFeatureTrackerHandle_t obj)
	Sets the CUDA stream used. More...
DW_API_PUBLIC dwStatus	dwScalingFeatureTracker_trackAsync (dwScalingFeatureListHandle_t list, const dwImageCUDA *currentImage, dwScalingFeatureTrackerHandle_t obj)
	Track the features in currentImage . More...
DW_API_PUBLIC dwStatus	dwScalingFeatureTracker_updateTemplateAsync (dwScalingFeatureListHandle_t list, const dwImageCUDA *templateImage, dwScalingFeatureTrackerHandle_t obj)
	Update the tracking template for each valid feature in the tracker The computation takes place asynchronously on the device (GPU). More...

Function Documentation

dwScalingFeatureTracker_getCUDAStream()

DW_API_PUBLIC dwStatus dwScalingFeatureTracker_getCUDAStream	(	cudaStream_t *	cudaStream,
		dwScalingFeatureTrackerHandle_t	obj
	)

Gets the CUDA stream used.

Parameters

[out]	cudaStream	The CUDA stream used.
[in]	obj	obj A pointer to the ScalingFeatureTracker handle that is updated.

Returns

DW_INVALID_ARGUMENT if ScalingFeatureTracker handle or cudaStream are NULL.
DW_SUCCESS otherwise.

dwScalingFeatureTracker_initDefaultParams()

DW_API_PUBLIC dwStatus dwScalingFeatureTracker_initDefaultParams

(

dwScalingFeatureTrackerParameters *

params

)

Initializes ScalingFeatureTracker parameters with default values.

Parameters

[out]

params

ScalingFeatureTracker parameters.

Returns

DW_INVALID_ARGUMENT if params is NULL.
DW_SUCCESS otherwise.

dwScalingFeatureTracker_initialize()

DW_API_PUBLIC dwStatus dwScalingFeatureTracker_initialize	(	dwScalingFeatureTrackerHandle_t *	obj,
		const dwScalingFeatureTrackerParameters *	params,
		cudaStream_t	stream,
		dwContextHandle_t	context
	)

Initialize the ScalingFeatureTracker module.

Parameters

[out]	obj	A pointer to ScalingFeatureTracker handle that is initialized from parameters.
[in]	params	ScalingFeatureTracker parameters.
[in]	stream	Specifies the cuda stream to use
[in]	context	Specifies the handle to the context.

Returns

DW_INVALID_ARGUMENT if ScalingFeatureTracker handle, params or context are NULL, or the params has invalid values.
DW_SUCCESS otherwise.

dwScalingFeatureTracker_release()

DW_API_PUBLIC dwStatus dwScalingFeatureTracker_release

(

dwScalingFeatureTrackerHandle_t *

obj

)

Releases the ScalingFeatureTracker module.

Parameters

[in]

obj

A pointer to the object handle to release.

Returns

DW_INVALID_ARGUMENT if ScalingFeatureTracker handle is NULL.
DW_SUCCESS otherwise.

Note

This method renders the handle unusable.

dwScalingFeatureTracker_reset()

DW_API_PUBLIC dwStatus dwScalingFeatureTracker_reset

(

dwScalingFeatureTrackerHandle_t

obj

)

Resets the ScalingFeatureTracker.

Parameters

[in]

obj

Handle to reset.

Returns

DW_INVALID_ARGUMENT if ScalingFeatureTracker handle is NULL.
DW_SUCCESS otherwise.

dwScalingFeatureTracker_setCUDAStream()

DW_API_PUBLIC dwStatus dwScalingFeatureTracker_setCUDAStream	(	cudaStream_t	cudaStream,
		dwScalingFeatureTrackerHandle_t	obj
	)

Sets the CUDA stream used.

Parameters

[in]	cudaStream	The CUDA stream used.
[in]	obj	A pointer to the ScalingFeatureTracker handle that is updated.

Returns

DW_INVALID_ARGUMENT if ScalingFeatureTracker handle is NULL.
DW_SUCCESS otherwise.

dwScalingFeatureTracker_trackAsync()

DW_API_PUBLIC dwStatus dwScalingFeatureTracker_trackAsync	(	dwScalingFeatureListHandle_t	list,
		const dwImageCUDA *	currentImage,
		dwScalingFeatureTrackerHandle_t	obj
	)

Track the features in currentImage
.

The computation takes place asynchronously on the device (GPU).

Parameters

[in,out]	list	Specifies the scaling feature list which stores the features to be tracked and the tracking results (in place)
[in]	currentImage	Current image data to track to.
[in]	obj	Specifies the ScalingFeatureTracker handle.

Returns

DW_INVALID_ARGUMENT if ScalingFeatureTracker handle, list, d_rowCount, d_memoryIndices or currentImage are NULL.
DW_SUCCESS otherwise.

dwScalingFeatureTracker_updateTemplateAsync()

DW_API_PUBLIC dwStatus dwScalingFeatureTracker_updateTemplateAsync	(	dwScalingFeatureListHandle_t	list,
		const dwImageCUDA *	templateImage,
		dwScalingFeatureTrackerHandle_t	obj
	)

Update the tracking template for each valid feature in the tracker The computation takes place asynchronously on the device (GPU).

Parameters

[in,out]	list	Specifies the scaling feature list where the updated template data will be stored
[in]	templateImage	Template image to the features to be tracked from
[in]	obj	Specifies the ScalingFeatureTracker handle.

Returns

DW_INVALID_ARGUMENT if ScalingFeatureTracker handle, list, d_rowCount, d_memoryIndices or templateImage are NULL.
DW_SUCCESS otherwise.