Dense Optical Flow

Algorithm used to estimate the motion vectors from previous image to current image. More...

Data Structures
struct	VPIOpticalFlowDenseSGMParams
	Dense optical flow parameters for semi-global matching pass. More...

Functions
VPIStatus	vpiCreateOpticalFlowDense (uint64_t backends, int32_t width, int32_t height, VPIImageFormat inputFmt, const int32_t *gridSize, int32_t numLevels, VPIOpticalFlowQuality quality, VPIPayload *payload)
	Creates payload for vpiSubmitOpticalFlowDense. More...
VPIStatus	vpiSubmitOpticalFlowDense (VPIStream stream, uint64_t backend, VPIPayload payload, VPIImage prevImg, VPIImage curImg, VPIImage mvImg)
	Runs dense Optical Flow on two frames, outputting motion vectors. More...
VPIStatus	vpiSubmitOpticalFlowDensePyramid (VPIStream stream, uint64_t backend, VPIPayload payload, VPIPyramid prevPyr, VPIPyramid curPyr, VPIImage mvImg)
	Runs dense Optical Flow on two frames, outputting motion vectors. More...
VPIStatus	vpiOpticalFlowDenseGetSGMParams (VPIPayload payload, VPIOpticalFlowDenseSGMParams *sgmParams)
	Retrieves the semi-global matching parameters set up in the Dense Optical Flow payload. More...
VPIStatus	vpiOpticalFlowDenseSetSGMParams (VPIPayload payload, const VPIOpticalFlowDenseSGMParams *sgmParams)
	Sets the semi-global matching parameters to be used by the Dense Optical Flow operations with the given payload. More...

Detailed Description

Algorithm used to estimate the motion vectors from previous image to current image.

Refer to Dense Optical Flow for more details and usage examples.

---

Data Structure Documentation

VPIOpticalFlowDenseSGMParams

struct VPIOpticalFlowDenseSGMParams

Dense optical flow parameters for semi-global matching pass.

Each pyramid level can be associated with different parameters. The first value in the arrays corresponds to the bottom (finer) level, the last corresponds to the top (coarse) level.

Definition at line 259 of file OpticalFlowDense.h.

Collaboration diagram for VPIOpticalFlowDenseSGMParams:

Data Fields
int32_t	p1[VPI_MAX_PYRAMID_LEVEL_COUNT]	P1 penalty value of semi-global matching algorithm used. Only used by OFA backend and ignored by others.
int32_t	p2[VPI_MAX_PYRAMID_LEVEL_COUNT]	P2 penalty value of semi-global matching algorithm used. Only used by OFA backend and ignored by others.
int32_t	p2Alpha[VPI_MAX_PYRAMID_LEVEL_COUNT]	Alpha value for adaptative P2 used in semi-global matching. Valid values are 0 (disable adaptative P2), 1, 2, 4 or 8. Only used by OFA backend and ignored by others.
int32_t	numPasses[VPI_MAX_PYRAMID_LEVEL_COUNT]	Number of semi-global matching passes. Valid range is from 1 to 3, inclusive. Only used by OFA backend and ignored by others.
int8_t	includeDiagonals[VPI_MAX_PYRAMID_LEVEL_COUNT]	Enable/disable diagonal directions in semi-global matching. To disable, set it to 0, any other values will enable it. Only used by OFA backend and ignored by others.

Function Documentation

vpiCreateOpticalFlowDense()

VPIStatus vpiCreateOpticalFlowDense	(	uint64_t	backends,
		int32_t	width,
		int32_t	height,
		VPIImageFormat	inputFmt,
		const int32_t *	gridSize,
		int32_t	numLevels,
		VPIOpticalFlowQuality	quality,
		VPIPayload *	payload
	)

#include </opt/nvidia/vpi2/include/vpi/algo/OpticalFlowDense.h>

Creates payload for vpiSubmitOpticalFlowDense.

Parameters

[in]	backends	VPI backends that are eligible to execute the algorithm. Supported backends: VPI_BACKEND_NVENC VPI_BACKEND_OFA Backend must be enabled in current context.
[in]	width,height	Dimensions of current and previous image. The output dimensions depend on the gridSize and the input dimensions. Must be >= 0.
[in]	gridSize	Array with grid sizes for each pyramid level. If working with input images, not pyramids, gridSize points to the single grid size used, as if it were for a pyramid with only one level. The first value in the array corresponds to the bottom (finer) level, the last corresponds to the top (coarse) level. Passing 1 allows for a dense grid. With 2 or more, the grid will be sparse. The output image dimensions depend on the first value in gridSize and the input dimensions. Valid values: Backend Allowed grid sizes per level VPI_BACKEND_NVENC 4 VPI_BACKEND_OFA 1,2,4,8
[in]	numLevels	Number of pyramid levels to be processed. When using pyramids as inputs, this specifies the number of levels to be considered. When using images, numLevels must be 1. On OFA, the number of levels is limited by the dimensions of the smallest pyramid level. It must be >= 32x32. Moreover, after dividing this smallest level by gridSize, the result must be >= 4x4. Valid values: Backend minimum maximum : VPI_BACKEND_NVENC 1 1 VPI_BACKEND_OFA 1 7
[in]	inputFmt	Format of current and previous image/pyramid. The accepted image formats are: Format NVENC OFA VPI_IMAGE_FORMAT_NV12_BL * * VPI_IMAGE_FORMAT_NV12_ER_BL * * VPI_IMAGE_FORMAT_U8_BL * VPI_IMAGE_FORMAT_Y8_BL * VPI_IMAGE_FORMAT_Y8_ER_BL * VPI_IMAGE_FORMAT_Y16_BL * VPI_IMAGE_FORMAT_Y16_ER_BL *
[in]	quality	Quality of the dense optical flow algorithm.
[out]	payload	Pointer to the payload variable that receives the created handle.

Return values

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

vpiSubmitOpticalFlowDense()

VPIStatus vpiSubmitOpticalFlowDense	(	VPIStream	stream,
		uint64_t	backend,
		VPIPayload	payload,
		VPIImage	prevImg,
		VPIImage	curImg,
		VPIImage	mvImg
	)

#include </opt/nvidia/vpi2/include/vpi/algo/OpticalFlowDense.h>

Runs dense Optical Flow on two frames, outputting motion vectors.

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 by vpiCreateOpticalFlowDense. The number of pyramid levels specified in the payload must be 1.
[in]	prevImg	Previous frame. Must not be NULL. Must have same format and dimensions as the one specified during payload creation. Image must have enabled the backends that will execute the algorithm.
[in]	curImg	Current frame. Must not be NULL. Must have same format and dimensions as prevImg. Image must have enabled the backends that will execute the algorithm.
[out]	mvImg	Motion vectors output. Must not be NULL. Image must have enabled the backends that will execute the algorithm. The width and height depend on the input dimensions and grid size specified on the payload. It's calculated by: output_width = (input_width + gridSize-1)/gridSize output_height = (input_height + gridSize-1)/gridSize Supported formats: VPI_IMAGE_FORMAT_2S16_BL is supported. Motion vector is in fixed point S10.5 format.

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	prevImg, curImg or mvImg are NULL.
VPI_ERROR_INVALID_ARGUMENT	payload is not generated using vpiCreateOpticalFlowDense.
VPI_ERROR_INVALID_ARGUMENT	number of pyramid levels specified in payload is not 1.
VPI_ERROR_INVALID_ARGUMENT	prevImg and curImg dimensions does not match the one associated with the payload.
VPI_ERROR_INVALID_IMAGE_FORMAT	prevImg and curImg format does not match the one associated with the payload.
VPI_ERROR_INVALID_PAYLOAD_TYPE	payload is invalid.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream, prevImg, curImg or mvImg.
VPI_SUCCESS	Operation executed successfully.

vpiSubmitOpticalFlowDensePyramid()

VPIStatus vpiSubmitOpticalFlowDensePyramid	(	VPIStream	stream,
		uint64_t	backend,
		VPIPayload	payload,
		VPIPyramid	prevPyr,
		VPIPyramid	curPyr,
		VPIImage	mvImg
	)

#include </opt/nvidia/vpi2/include/vpi/algo/OpticalFlowDense.h>

Runs dense Optical Flow on two frames, outputting motion vectors.

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 by vpiCreateOpticalFlowDense.
[in]	prevPyr	Previous pyramid frame. Must not be NULL. Must have same format and dimensions as the one specified during payload creation. Pyramid height must be >= the number of pyramid levels specified in the payload. Pyramid must have enabled the backends that will execute the algorithm.
[in]	curPyr	Current pyramid frame. Must not be NULL. Must have same format and dimensions as prevImg. Number of pyramid levels must be the same as specified in the payload. Pyramid must have enabled the backends that will execute the algorithm.
[out]	mvImg	Motion vectors output. Must not be NULL. Image must have enabled the backends that will execute the algorithm. The width and height depend on the input dimensions and grid size of the bottom pyramid level specified in the payload. It's calculated by: output_width = (input_width + gridSize-1)/gridSize output_height = (input_height + gridSize-1)/gridSize Supported formats: VPI_IMAGE_FORMAT_2S16_BL is supported. Motion vector is in fixed point S10.5 format.

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	prevPyr, cuurPyr or mvImg are NULL.
VPI_ERROR_INVALID_ARGUMENT	payload is not generated using vpiCreateOpticalFlowDense.
VPI_ERROR_INVALID_ARGUMENT	prevPyr and cuurPyr dimensions does not match the one associated with the payload.
VPI_ERROR_INVALID_ARGUMENT	prevPyr and curPyr number of Levels out of valid range.
VPI_ERROR_INVALID_IMAGE_FORMAT	prevPyr and curPyr format does not match the one associated with the payload.
VPI_ERROR_INVALID_PAYLOAD_TYPE	payload is invalid.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream, prevPyr, cuurPyr or mvImg.
VPI_SUCCESS	Operation executed successfully.

vpiOpticalFlowDenseGetSGMParams()

VPIStatus vpiOpticalFlowDenseGetSGMParams	(	VPIPayload	payload,
		VPIOpticalFlowDenseSGMParams *	sgmParams
	)

#include </opt/nvidia/vpi2/include/vpi/algo/OpticalFlowDense.h>

Retrieves the semi-global matching parameters set up in the Dense Optical Flow payload.

Parameters

[in]	payload	Payload created by vpiCreateOpticalFlowDense. Payload must be using the OFA backend.
[out]	sgmParams	Structure where parameters will be written to. Must not be NULL.

Return values

VPI_ERROR_INVALID_PAYLOAD_TYPE	payload is invalid.
VPI_ERROR_INVALID_ARGUMENT	sgmParams is NULL.
VPI_ERROR_INVALID_OPERATION	payload was not created for OFA dense optical flow.
VPI_SUCCESS	Operation executed successfully.

vpiOpticalFlowDenseSetSGMParams()

VPIStatus vpiOpticalFlowDenseSetSGMParams	(	VPIPayload	payload,
		const VPIOpticalFlowDenseSGMParams *	sgmParams
	)

#include </opt/nvidia/vpi2/include/vpi/algo/OpticalFlowDense.h>

Sets the semi-global matching parameters to be used by the Dense Optical Flow operations with the given payload.

The parameters will be only effective on future dense optical flow operations on the given payload. Already submitted operations won't be affected.

Parameters

[in]	payload	Payload created by vpiCreateOpticalFlowDense. Payload must be using the OFA backend.
[in]	sgmParams	SGM parameters to be used by future dense optical flow submissions with given payload. Must not be NULL.

Return values

VPI_ERROR_INVALID_PAYLOAD_TYPE	payload is invalid.
VPI_ERROR_INVALID_ARGUMENT	sgmParams is NULL.
VPI_ERROR_INVALID_OPERATION	payload was not created for OFA dense optical flow.
VPI_SUCCESS	Operation executed successfully.