VPI - Vision Programming Interface

3.2 Release

KLT Feature Tracker

Runs KLT Feature tracking on a sequence of frames. More...

Data Structures

struct  VPIKLTFeatureTrackerCreationParams
 Creation parameters of KLT Feature Tracker. More...
 
struct  VPIKLTFeatureTrackerParams
 Structure that defines the parameters for vpiCreateKLTFeatureTracker. More...
 
struct  VPIKLTTrackedBoundingBox
 Stores a bounding box that is being tracked by KLT Tracker. More...
 

Enumerations

enum  VPIKLTFeatureTrackerType
 KLT Feature Tracker algorithm type. More...
 

Functions

VPIStatus vpiInitKLTFeatureTrackerCreationParams (VPIKLTFeatureTrackerCreationParams *params)
 Initialize VPIKLTFeatureTrackerCreationParams with default values. More...
 
VPIStatus vpiCreateKLTFeatureTracker (uint64_t backends, int32_t imageWidth, int32_t imageHeight, VPIImageFormat imageFormat, const VPIKLTFeatureTrackerCreationParams *params, VPIPayload *payload)
 Creates payload for vpiSubmitKLTFeatureTracker. More...
 
VPIStatus vpiInitKLTFeatureTrackerParams (VPIKLTFeatureTrackerParams *params)
 Initialize VPIKLTFeatureTrackerParams with default values. More...
 
VPIStatus vpiSubmitKLTFeatureTracker (VPIStream stream, uint64_t backend, VPIPayload payload, VPIImage templateImage, VPIArray inputBoxList, VPIArray inputPredictionList, VPIImage referenceImage, VPIArray outputBoxList, VPIArray outputEstimationList, const VPIKLTFeatureTrackerParams *params)
 Runs KLT Feature Tracker on two frames. More...
 

Detailed Description

Runs KLT Feature tracking on a sequence of frames.

Refer to KLT Feature Tracker for more details and usage examples.


Data Structure Documentation

◆ VPIKLTFeatureTrackerCreationParams

struct VPIKLTFeatureTrackerCreationParams

Creation parameters of KLT Feature Tracker.

Definition at line 80 of file KLTFeatureTracker.h.

+ Collaboration diagram for VPIKLTFeatureTrackerCreationParams:
Data Fields
int32_t maxTemplateCount Maximum number of templates to be tracked.
  • Must be >= 1 and <= 128.
int32_t maxTemplateWidth Maximum width of each tracked template.
  • It must be >= 4 and <= 128 (on PVA, <= 64).
int32_t maxTemplateHeight Maximum height of each tracked templates.
  • It must be >= 4 and <= 128 (on PVA, <= 64).

◆ VPIKLTFeatureTrackerParams

struct VPIKLTFeatureTrackerParams

Structure that defines the parameters for vpiCreateKLTFeatureTracker.

Definition at line 173 of file KLTFeatureTracker.h.

+ Collaboration diagram for VPIKLTFeatureTrackerParams:
Data Fields
int32_t numberOfIterationsScaling Number of Inverse compositional iterations of scale estimations.
  • On PVA the maximum allowed is 20.
float nccThresholdUpdate Threshold for requiring template update.
  • Must be a value between 0 and 1.
  • Must be greater than nccThresholdKill.
float nccThresholdKill Threshold to consider template tracking was lost.
  • Must be a value between 0 and 1.
float nccThresholdStop Threshold to early stop iteration.
  • Must be a value between 0 and 1.
  • Must be greater than nccThresholdUpdate.
float maxScaleChange Maximum relative scale change.

Scale changes larger than this will make KLT consider that tracking was lost.

  • Must be >= 0.
  • On PVA, maximum scale change is 0.2.
float maxTranslationChange Maximum relative translation change.
  • Must be less >= 0.
  • Translation changes larger than this will make KLT consider that tracking was lost.
VPIKLTFeatureTrackerType trackingType Type of KLT tracking that will be performed.

◆ VPIKLTTrackedBoundingBox

struct VPIKLTTrackedBoundingBox

Stores a bounding box that is being tracked by KLT Tracker.

Definition at line 487 of file Types.h.

+ Collaboration diagram for VPIKLTTrackedBoundingBox:
Data Fields
VPIBoundingBox bbox Bounding box being tracked.
int8_t trackingStatus Tracking status of this bounding box.

Accepted values:

  • 1 tracking information is invalid and shouldn't be relied upon.
  • 0 tracking information is valid.
int8_t templateStatus Status of the template related to this bounding box.

Accepted values:

  • 1 template needs updating.
  • 0 existing template still can be used for tracking, it doesn't need to be updated.
uint8_t reserved1 Reserved for future use.
uint8_t reserved2 Reserved for future use.

Enumeration Type Documentation

◆ VPIKLTFeatureTrackerType

#include <vpi/algo/KLTFeatureTracker.h>

KLT Feature Tracker algorithm type.

Enumerator
VPI_KLT_INVERSE_COMPOSITIONAL 

Inverse compositional algorithm for KLT tracker.

The inverse compositional algorithm is a reformulation of the classic Lucas-Kanade algorithm to make the steepest-descent images and Hessian constant.

Ref:Simon Baker, Iain Matthew, "Lucas-Kanade 20 Years On: A Unified Framework".
International Journal of Computer Vision, February 2004, Volume 56, issue 3, pp. 228-231.

Definition at line 156 of file KLTFeatureTracker.h.

Function Documentation

◆ vpiInitKLTFeatureTrackerCreationParams()

VPIStatus vpiInitKLTFeatureTrackerCreationParams ( VPIKLTFeatureTrackerCreationParams params)

#include <vpi/algo/KLTFeatureTracker.h>

Initialize VPIKLTFeatureTrackerCreationParams with default values.

Default values:

  • maxTemplateCount: 128
  • maxTemplateWidth: 64
  • maxTemplateHeight: 64
Parameters
[out]paramsStructure to be filled with default values.
Return values
VPI_ERROR_INVALID_ARGUMENTparams is NULL.
VPI_SUCCESSOperation executed successfully.

◆ vpiCreateKLTFeatureTracker()

VPIStatus vpiCreateKLTFeatureTracker ( uint64_t  backends,
int32_t  imageWidth,
int32_t  imageHeight,
VPIImageFormat  imageFormat,
const VPIKLTFeatureTrackerCreationParams params,
VPIPayload payload 
)

#include <vpi/algo/KLTFeatureTracker.h>

Creates payload for vpiSubmitKLTFeatureTracker.

Parameters
[in]backendsVPI backends that are eligible to execute the algorithm.
[in]imageWidth,imageHeightInput image dimensions.
  • On PVA, dimensions must be between 65x65 and 3264x2448.
  • Must be >= 0 (other backends).
[in]imageFormatInput image format.
[in]paramsparams
[out]payloadPointer to the payload variable that receives the created handle.
Return values
VPI_ERROR_INVALID_ARGUMENTpayload is NULL.
VPI_ERROR_INVALID_ARGUMENTimageWidth and imageHeight outside valid range.
VPI_ERROR_INVALID_ARGUMENTmaxTemplateWidth and maxTemplateHeight in params outside valid range.
VPI_ERROR_INVALID_ARGUMENTmaxTemplateCount in params outside valid range.
VPI_ERROR_INVALID_ARGUMENTbackends refers to an invalid backend.
VPI_IMAGE_FORMAT_INVALIDimageFormat is not supported.
VPI_ERROR_INVALID_OPERATIONPVA hardware is not available.
VPI_ERROR_INVALID_OPERATIONBackend isn't enabled in current context.
VPI_ERROR_NOT_IMPLEMENTEDKLT Feature Tracker algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXTCurrent context is destroyed.
VPI_ERROR_OUT_OF_MEMORYCannot allocate required resources.
VPI_SUCCESSOperation executed successfully.

◆ vpiInitKLTFeatureTrackerParams()

VPIStatus vpiInitKLTFeatureTrackerParams ( VPIKLTFeatureTrackerParams params)

#include <vpi/algo/KLTFeatureTracker.h>

Initialize VPIKLTFeatureTrackerParams with default values.

Default values:

  • numberOfIterationsScaling: 20
  • nccThresholdUpdate: 0.8
  • nccThresholdKill: 0.6
  • nccThresholdStop: 1.0
  • maxScaleChange: 0.2
  • maxTranslationChange: 1.5
  • trackingType: VPI_KLT_INVERSE_COMPOSITIONAL
Parameters
[out]paramsStructure to be filled with default values.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiSubmitKLTFeatureTracker()

VPIStatus vpiSubmitKLTFeatureTracker ( VPIStream  stream,
uint64_t  backend,
VPIPayload  payload,
VPIImage  templateImage,
VPIArray  inputBoxList,
VPIArray  inputPredictionList,
VPIImage  referenceImage,
VPIArray  outputBoxList,
VPIArray  outputEstimationList,
const VPIKLTFeatureTrackerParams params 
)

#include <vpi/algo/KLTFeatureTracker.h>

Runs KLT Feature Tracker on two frames.

Outputs tracked bounding boxes and estimated transform array.

Parameters
[in]streamThe stream where the operation will be queued in.
  • Must not be NULL.
  • Stream must have enabled the backends that will execute the algorithm.
[in]backendBackend that will execute the algorithm.
  • Must be the backend specified during payload creation or 0 as a shorthand to use this backend.
[in]payloadPayload created by vpiCreateKLTFeatureTracker.
[in]referenceImageReference image.
  • Must not be NULL.
  • Must have same dimensions and format as template image.
  • Image must have enabled the backends that will execute the algorithm.
[in]inputBoxListInput bounding box array.
[in]inputPredictionListInput predicted transform array.
[in]templateImageTemplate image.
  • Must not be NULL.
  • Must have same dimensions and format as referenceImage.
  • Image must have enabled the backends that will execute the algorithm.
[out]outputBoxListOutput Bounding box array.
[out]outputEstimationListEstimated transform array.
[in]paramsControl parameters of the KLT feature tracker algorithm.
Return values
VPI_ERROR_INVALID_ARGUMENTstream is NULL.
VPI_ERROR_INVALID_ARGUMENTreferenceImage, templateImage, inputBoxList, inputPredictionList, outputBoxList or outputEstimationList are NULL.
VPI_ERROR_INVALID_ARGUMENTparams is NULL.
VPI_ERROR_INVALID_ARGUMENTpayload not created by vpiCreateKLTFeatureTracker.
VPI_ERROR_INVALID_ARGUMENTtemplateImage and referenceImage dimensions and format do not match.
VPI_ERROR_INVALID_ARGUMENTInput and parameter image dimension do not match.
VPI_ERROR_INVALID_ARGUMENTImage format and payload image format do not match.
VPI_ERROR_INVALID_ARGUMENTUnsupported array type for inputBoxList or outputBoxList.
VPI_ERROR_INVALID_ARGUMENTUnsupported array type for inputPredictionList or outputEstimationList.
VPI_ERROR_INVALID_ARGUMENTParameter(s) in params outside valid range.
VPI_ERROR_INVALID_PAYLOAD_TYPEpayload is invalid.
VPI_ERROR_INVALID_OPERATIONThe needed backends aren't enabled in stream, referenceImage, templateImage, inputBoxList, inputPredictionList, outputBoxList or outputEstimationList.
VPI_SUCCESSOperation executed successfully.