Pyramidal LK Optical Flow

Algorithm used to track points from one frame to the next. More...

Data Structures
struct	VPIOpticalFlowPyrLKParams
	Structure that defines the parameters for vpiSubmitOpticalFlowPyrLK. More...

Enumerations
enum	VPIEpsilonType
	Defines the error measurement types. More...

Functions
VPIStatus	vpiInitOpticalFlowPyrLKParams (VPIOpticalFlowPyrLKParams *params)
	Initializes VPIOpticalFlowPyrLKParams with default values. More...
VPIStatus	vpiCreateOpticalFlowPyrLK (uint64_t backends, int32_t width, int32_t height, VPIImageFormat fmt, int32_t levels, float scale, VPIPayload *payload)
	Creates payload for vpiSubmitOpticalFlowPyrLK. More...
VPIStatus	vpiSubmitOpticalFlowPyrLK (VPIStream stream, uint64_t backend, VPIPayload payload, VPIPyramid prevPyr, VPIPyramid curPyr, VPIArray prevPts, VPIArray curPts, VPIArray trackingStatus, const VPIOpticalFlowPyrLKParams *params)
	Runs Pyramidal LK Optical Flow on two frames. More...

Detailed Description

Algorithm used to track points from one frame to the next.

Refer to Pyramidal LK Optical Flow for more details and usage examples.

---

Data Structure Documentation

VPIOpticalFlowPyrLKParams

struct VPIOpticalFlowPyrLKParams

Structure that defines the parameters for vpiSubmitOpticalFlowPyrLK.

Definition at line 92 of file OpticalFlowPyrLK.h.

Collaboration diagram for VPIOpticalFlowPyrLKParams:

Data Fields
uint32_t	useInitialFlow	Uses initial estimations stored in current frame keypoints array when this flag is not 0, otherwise previous frame keypoints are copied to current frame keypoints array and is considered the initial estimate.
uint32_t	termination	Specifies the termination criteria. It must be bitwise combination of one or more of the following values: VPI_TERMINATION_CRITERIA_ITERATIONS VPI_TERMINATION_CRITERIA_EPSILON
VPIEpsilonType	epsilonType	Specifies the tracking error type.
float	epsilon	Specifies minimum error threshold for terminating the algorithm. Only applicable if termination flags includes VPI_TERMINATION_CRITERIA_ITERATIONS.
int32_t	numIterations	Specifies the maximum number of iterations. Only applicable if termination flags includes VPI_TERMINATION_CRITERIA_ITERATIONS. Must be >= 1 and <= 32.
int32_t	windowDimension	Specifies the size of the window on which to perform the algorithm. Must be >= 6 and <= 32.

Enumeration Type Documentation

VPIEpsilonType

enum VPIEpsilonType

#include </opt/nvidia/vpi3/include/vpi/algo/OpticalFlowPyrLK.h>

Defines the error measurement types.

Enumerator
VPI_LK_ERROR_L1	L1 distance between previous feature and a next feature.

Definition at line 83 of file OpticalFlowPyrLK.h.

Function Documentation

vpiInitOpticalFlowPyrLKParams()

VPIStatus vpiInitOpticalFlowPyrLKParams

(

VPIOpticalFlowPyrLKParams *

params

)

#include </opt/nvidia/vpi3/include/vpi/algo/OpticalFlowPyrLK.h>

Initializes VPIOpticalFlowPyrLKParams with default values.

Defaults:

• useInitialFlow = 0
• termination = VPI_TERMINATION_CRITERIA_ITERATIONS | VPI_TERMINATION_CRITERIA_EPSILON
• epsilonType = VPI_LK_ERROR_L1
• epsilon = 0
• windowDimension = 15
• numIterations = 6

Parameters

[in]

params

Structure to be filled with default values.

Return values

VPI_ERROR_INVALID_ARGUMENT	params is NULL.
VPI_SUCCESS	Operation executed successfully.

vpiCreateOpticalFlowPyrLK()

VPIStatus vpiCreateOpticalFlowPyrLK	(	uint64_t	backends,
		int32_t	width,
		int32_t	height,
		VPIImageFormat	fmt,
		int32_t	levels,
		float	scale,
		VPIPayload *	payload
	)

#include </opt/nvidia/vpi3/include/vpi/algo/OpticalFlowPyrLK.h>

Creates payload for vpiSubmitOpticalFlowPyrLK.

Parameters

[in]	backends	VPI backends that are eligible to execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA Backend must be enabled in current context.
[in]	fmt	Specifies the format for the pyramid. The accepted image formats are: VPI_IMAGE_FORMAT_U8 VPI_IMAGE_FORMAT_U16
[in]	width,height	Specifies the dimensions of the pyramid on the finest resolution. Must be >= 0.
[in]	levels	Number of levels of the pyramid to be used.
[in]	scale	Scale of the pyramid to be used.
[out]	payload	Pointer to the payload variable that receives the created handle.

Return values

VPI_IMAGE_FORMAT_INVALID	fmt is not supported.
VPI_ERROR_INVALID_ARGUMENT	payload is NULL.
VPI_ERROR_INVALID_ARGUMENT	width or height outside valid range.
VPI_ERROR_INVALID_ARGUMENT	fmt is not supported.
VPI_ERROR_INVALID_ARGUMENT	backends refers to an invalid backend.
VPI_ERROR_NOT_IMPLEMENTED	Pyramidal LK Optical Flow algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_ERROR_OUT_OF_MEMORY	Cannot allocate required resources.
VPI_ERROR_INVALID_OPERATION	Backend isn't enabled in current context.
VPI_SUCCESS	Operation executed successfully.

vpiSubmitOpticalFlowPyrLK()

VPIStatus vpiSubmitOpticalFlowPyrLK	(	VPIStream	stream,
		uint64_t	backend,
		VPIPayload	payload,
		VPIPyramid	prevPyr,
		VPIPyramid	curPyr,
		VPIArray	prevPts,
		VPIArray	curPts,
		VPIArray	trackingStatus,
		const VPIOpticalFlowPyrLKParams *	params
	)

#include </opt/nvidia/vpi3/include/vpi/algo/OpticalFlowPyrLK.h>

Runs Pyramidal LK Optical Flow on two frames.

Outputs estimated feature points and tracking status.

Parameters

[in]	stream	The stream where the operation will be queued in. Must not be NULL. Stream must have enabled the backends that will execute the algorithm.
[in]	backend	Backend that will execute the algorithm. Must be the backend specified during payload creation or 0 as a shorthand to use this backend.
[in]	payload	Payload created with vpiCreateOpticalFlowPyrLK.
[in]	prevPyr	Previous frame, represented as a gaussian pyramid. Must not be NULL. Must have same format, scale and number of levels as the ones specified during payload creation. Pyramid must have enabled the backends that will execute the algorithm.
[in]	curPyr	Current frame, represented as a gaussian pyramid. Must not be NULL. Must have same number of levels, size, scale and format as prevPyr. Pyramid must have enabled the backends that will execute the algorithm.
[in]	prevPts	Array of keypoints in the prevPyr high resolution pyramid. Must not be NULL. The type of array must be VPI_ARRAY_TYPE_KEYPOINT_F32. If useInitialFlow in params is not zero, prevPts must have same size as curPts. Array must have enabled the backends that will execute the algorithm.
[in,out]	curPts	Array of keypoints in first level of curPyr. It is used as starting search point in curPyr if useInitialFlow in params is not 0. Must not be NULL. The type of array must be VPI_ARRAY_TYPE_KEYPOINT_F32. If useInitialFlow in params is not zero, curPts must have same size as prevPts. Array capacity must be greater or equal than prevPts array size. Array must have enabled the backends that will execute the algorithm.
[in,out]	trackingStatus	Status array for tracking status for each input in prevPts. If element is 0, the corresponding keypoint is being tracked, otherwide, tracking is lost. Must not be NULL. The type of the array must be VPI_ARRAY_TYPE_U8. Array capacity must be greater or equal than prevPts array size. Array must have enabled the backends that will execute the algorithm.
[in]	params	Parameters for the LK tracker. If NULL, it uses default parameters are returned by vpiInitOpticalFlowPyrLKParams.

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	prevPyr, curPyr, prevPts, curPts or trackingStatus are NULL.
VPI_ERROR_INVALID_ARGUMENT	payload is not generated using vpiCreateKLTFeatureTracker.
VPI_ERROR_INVALID_ARGUMENT	prevPyr and curPyr should have same number of levels, size, scale and format.
VPI_ERROR_INVALID_ARGUMENT	prevPyr and curPyr format should match with format specified in the payload creation.
VPI_ERROR_INVALID_ARGUMENT	Invalid termination criteria provided in params.
VPI_ERROR_INVALID_ARGUMENT	Number of iterations in params outside valid range.
VPI_ERROR_INVALID_ARGUMENT	Tracking window dimension in params is invalid.
VPI_ERROR_INVALID_ARGUMENT	prevPts or curPts have unsupported array type.
VPI_ERROR_INVALID_ARGUMENT	prevPts or curPts's size outside valid range.
VPI_ERROR_INVALID_ARGUMENT	prevPts or trackingStatus's capacity outside valid range.
VPI_ERROR_INVALID_ARGUMENT	trackingStatus has unsupported array type.
VPI_ERROR_INVALID_PAYLOAD_TYPE	payload is invalid.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream, prevPyr, curPyr, prevPts, curPts or trackingStatus.
VPI_SUCCESS	Operation executed successfully.