Transform Estimator

Estimate the transform between source and target keypoints. More...

Data Structures
struct	VPIConstrainedHomography2DConfig
	Holds the configuration of a constrained 2d homography transform. More...
union	VPITransformConfig
	Transformation parameters. More...
struct	VPITransformEstimatorParams
	Parameters used to tune Transform Estimator algorithm. More...

Enumerations
enum	VPITransformType
	Types of transformation supported. More...
enum	VPITransfomEstimationMethod
	Transform estimation method. More...

Functions
VPIStatus	vpiCreateTransformEstimator (uint64_t backends, int32_t maxKeypoints, VPIPayload *payload)
	Creates payload for vpiSubmitTransformEstimator. More...
VPIStatus	vpiInitTransformEstimatorParams (VPITransformType type, VPITransformEstimatorParams *params)
	Initializes the VPITransformEstimatorParams with default values for a given transform type. More...
VPIStatus	vpiSubmitTransformEstimator (VPIStream stream, uint64_t backend, VPIPayload payload, VPIArray srcKeypoints, VPIArray tgtKeypoints, VPIArray matches, VPIArray outTransform, VPIArray outInliers, const VPITransformEstimatorParams *params)
	Submits a Transform Estimator operation to the stream. More...

Detailed Description

Estimate the transform between source and target keypoints.

Refer to Transform Estimator for more details and usage examples.

---

Data Structure Documentation

VPIConstrainedHomography2DConfig

struct VPIConstrainedHomography2DConfig

Holds the configuration of a constrained 2d homography transform.

Definition at line 104 of file TransformEstimator.h.

Collaboration diagram for VPIConstrainedHomography2DConfig:

Data Fields
float	minRotation	Valid rotation range, in radians. If min==-FLT_MAX, do not impose restriction on minimum rotation. If max==FLT_MAX, do not impose restriction on maximum rotation. If min==max, no rotation will be estimated, it'll be considered to be min.
float	maxRotation	Valid rotation range, in radians. If min==-FLT_MAX, do not impose restriction on minimum rotation. If max==FLT_MAX, do not impose restriction on maximum rotation. If min==max, no rotation will be estimated, it'll be considered to be min.
float	minXScale	Valid horizontal scale range. If isIsotropicScale is != 0 (true), this range is for the isotropic scale. If 0, don't restrict. If min==max, no horizontal scaling will be estimated, it'll be considered to be min. If max != 0, min must be <= max.
float	maxXScale	Valid rotation range, in radians. If min==-FLT_MAX, do not impose restriction on minimum rotation. If max==FLT_MAX, do not impose restriction on maximum rotation. If min==max, no rotation will be estimated, it'll be considered to be min.
float	minYScale	Valid vertical scale range. Only used if isIsotropicScale is 0 (false). If 0, don't restrict. If min==max, no vertical scaling will be estimated, it'll be considered to be min. If max != 0, min must be <= max.
float	maxYScale	Valid vertical scale range. Only used if isIsotropicScale is 0 (false). If 0, don't restrict. If min==max, no vertical scaling will be estimated, it'll be considered to be min. If max != 0, min must be <= max.
float	minXTranslation	Valid horizontal translation range. If min==-FLT_MAX, do not impose restriction on minimum horizontal translation. If max==FLT_MAX, do not impose restriction on maximum horizontal translation. If min==max, no horizontal translation will be estimated, it'll be considered to be min. min must be <= max.
float	maxXTranslation	Valid horizontal translation range. If min==-FLT_MAX, do not impose restriction on minimum horizontal translation. If max==FLT_MAX, do not impose restriction on maximum horizontal translation. If min==max, no horizontal translation will be estimated, it'll be considered to be min. min must be <= max.
float	minYTranslation	Valid vertical translation range. If min==-FLT_MAX, do not impose restriction on minimum vertical translation. If max==FLT_MAX, do not impose restriction on maximum vertical translation. If min==max, no vertical translation will be estimated, it'll be considered to be min. min must be <= max.
float	maxYTranslation	Valid vertical translation range. If min==-FLT_MAX, do not impose restriction on minimum vertical translation. If max==FLT_MAX, do not impose restriction on maximum vertical translation. If min==max, no vertical translation will be estimated, it'll be considered to be min. min must be <= max.
float	minShear	Valid shearing range. If min==-FLT_MAX, do not impose restriction on minimum shear. If max==FLT_MAX, do not impose restriction on maximum shear. If min==max, no shear will be estimated, it'll be considered to be min. min must be <= max.
float	maxShear	Valid shearing range. If min==-FLT_MAX, do not impose restriction on minimum shear. If max==FLT_MAX, do not impose restriction on maximum shear. If min==max, no shear will be estimated, it'll be considered to be min. min must be <= max.
int8_t	isAffine	Whether to restrict to affine transforms. If != 0, restrict transform to affine. If 0, allow perspective transform.
int8_t	isIsotropicScale	Whether scaling is uniform in all directions (isotropic) or not. If != 0, assume scale is isotropic. If 0, allow different horizontal and vertical scaling.

VPITransformConfig

union VPITransformConfig

Transformation parameters.

Definition at line 178 of file TransformEstimator.h.

Collaboration diagram for VPITransformConfig:

Data Fields
VPIConstrainedHomography2DConfig	constrainedHomography2D

VPITransformEstimatorParams

struct VPITransformEstimatorParams

Parameters used to tune Transform Estimator algorithm.

Definition at line 193 of file TransformEstimator.h.

Collaboration diagram for VPITransformEstimatorParams:

Data Fields
VPITransfomEstimationMethod	method	Method to use for transform estimation.
int32_t	solverMaxIterations	Maximum number of iterations the non-linear solver should take.
int32_t	ransacMaxIterations	Maximum number of RANSAC iterations.
float	ransacReprojErrorTolerance	Maximum allowed reprojection error for a point to be treated as an inlier.
float	ransacConfidenceLevel	Maximum allowed reprojection error for a point to be treated as an inlier.
int32_t	ransacSeed	Random number seed to be used.
int32_t	maxRefinementIterations	Maximum number of iterations for model refinement step. Pass 0 to skip refinement. It's usually needed when transform isn't affine.
VPITransformType	xftype	Type of transform to estimate.
VPITransformConfig	xfcfg	Transform configuration, such as trusted boundaries, etc.

Enumeration Type Documentation

VPITransformType

enum VPITransformType

#include <vpi/algo/TransformEstimator.h>

Types of transformation supported.

Enumerator
VPI_XFORM_CONSTRAINED_HOMOGRAPHY_2D	Represents a constrained 2D homography transform.

Definition at line 171 of file TransformEstimator.h.

VPITransfomEstimationMethod

enum VPITransfomEstimationMethod

#include <vpi/algo/TransformEstimator.h>

Transform estimation method.

Enumerator
VPI_XFORM_ESTIM_METHOD_REGULAR	Use least squares minimization method.
VPI_XFORM_ESTIM_METHOD_RANSAC	Use robust estimation with RANSAC and least squares.

Definition at line 184 of file TransformEstimator.h.

Function Documentation

vpiCreateTransformEstimator()

VPIStatus vpiCreateTransformEstimator	(	uint64_t	backends,
		int32_t	maxKeypoints,
		VPIPayload *	payload
	)

#include <vpi/algo/TransformEstimator.h>

Creates payload for vpiSubmitTransformEstimator.

Parameters

[in]	backends	VPI backend that will execute the algorithm. Valid values: VPI_BACKEND_CPU Backend must be enabled in current context.
[in]	maxKeypoints	Maximum number of keypoints processed. Must be > 0.
[out]	payload	Pointer to the payload variable that receives the created handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	payload is NULL.
VPI_ERROR_INVALID_ARGUMENT	maxKeypints outside valid range.
VPI_ERROR_INVALID_ARGUMENT	backend refers to an invalid backend.
VPI_ERROR_NOT_IMPLEMENTED	Transform Estimator algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXT	Current context was destroyed.
VPI_ERROR_INVALID_OPERATION	Backend isn't enabled in current context.
VPI_ERROR_OUT_OF_MEMORY	Cannot allocate required resources.
VPI_SUCCESS	Operation executed successfully.

vpiInitTransformEstimatorParams()

VPIStatus vpiInitTransformEstimatorParams	(	VPITransformType	type,
		VPITransformEstimatorParams *	params
	)

#include <vpi/algo/TransformEstimator.h>

Initializes the VPITransformEstimatorParams with default values for a given transform type.

The default values remove all parameter constraints. It sets the following parameters:

• method: VPI_XFORM_ESTIM_METHOD_RANSAC
• ransacMaxIterations: 2000
• ransacReprojErrorTolerance: 3
• ransacConfidenceLevel: 0.95
• ransacSeed: 0
• solverMaxIterations: 50
• solverReprojErrorTolerance: 1e-6
• solverParameterTolerance: 1e-8
• maxRefinementIterations: 10
• xftype: (type passed) If xftype == VPI_XFORM_CONSTRAINED_HOMOGRAPHY_2D:
• xfcfg.constrainedHomography2D.minRotation: -FLT_MAX
• xfcfg.constrainedHomography2D.maxRotation: +FLT_MAX
• xfcfg.constrainedHomography2D.minXScale: 0
• xfcfg.constrainedHomography2D.maxXScale: 0
• xfcfg.constrainedHomography2D.minYScale: 0
• xfcfg.constrainedHomography2D.maxYScale: 0
• xfcfg.constrainedHomography2D.minXTranslation: -FLT_MAX
• xfcfg.constrainedHomography2D.maxXTranslation: FLT_MAX
• xfcfg.constrainedHomography2D.minYTranslation: -FLT_MAX
• xfcfg.constrainedHomography2D.maxYTranslation: FLT_MAX
• xfcfg.constrainedHomography2D.isAffine: 0
• xfcfg.constrainedHomography2D.isIsotropicScale: 0

Parameters

[in]	type	Type of transform to initialize the structure to. Accepted types: VPI_XFORM_CONSTRAINED_HOMOGRAPHY_2D
[in,out]	params	Pointer to structure to be initialized. Must not be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	params is NULL.
VPI_ERROR_INVALID_ARGUMENT	Transform type not accepted.
VPI_SUCCESS	Operation executed successfully.

vpiSubmitTransformEstimator()

VPIStatus vpiSubmitTransformEstimator	(	VPIStream	stream,
		uint64_t	backend,
		VPIPayload	payload,
		VPIArray	srcKeypoints,
		VPIArray	tgtKeypoints,
		VPIArray	matches,
		VPIArray	outTransform,
		VPIArray	outInliers,
		const VPITransformEstimatorParams *	params
	)

#include <vpi/algo/TransformEstimator.h>

Submits a Transform Estimator operation to the stream.

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 vpiCreateTransformEstimator. Must not be NULL.
[in]	srcKeypoints	Source keypoints. It defines a set of keypoints to which the estimated transform is to be applied to. Must not be NULL. Valid array types: VPI_ARRAY_TYPE_KEYPOINT_F32 VPI_ARRAY_TYPE_PYRAMIDAL_KEYPOINT_F32 If matches is not NULL, srcKeypoints and matches must have the same size.
[in]	tgtKeypoints	Target keypoints. It defines a set of keypoints that are to be the result of applying the transform to the source keypoints. Must not be NULL. Valid array types: VPI_ARRAY_TYPE_KEYPOINT_F32 VPI_ARRAY_TYPE_PYRAMIDAL_KEYPOINT_F32 If matches is NULL, srcKeypoints and tgtKeypoints must have the same size. If matches is not NULL, it must be guaranteed that the first element of VPIMatches::refIndex exists in tgtKeypoints.
[in]	matches	Correspondence between source and target keypoints. If not NULL, for each i-th element in matches, the correspondence is given by: src = srcKeypoints[i] tgt = tgtKeypoints[matches[i].refIndex[0]] If it's NULL, for each i-th element in srcKeypoints, the correspondence is given by: src = srcKeypoints[i] tgt = tgtKeypoints[i] If not NULL, it must have type VPI_ARRAY_TYPE_MATCHES.
[out]	outTransform	Where the estimated transformation will be written to. Array's type specify what transform is to be estimated. Must not be NULL. Capacity must be >= 1. Array type must be VPI_ARRAY_TYPE_HOMOGRAPHY_TRANSFORM_2D.
[out]	outInliers	Indices of the inlier matches. Optional, if not needed pass NULL. Capacity must be >= number of keypoints in srcKeypoints. The array type must be VPI_ARRAY_TYPE_U32
[in]	params	Parameters specifying the parameters of the transform to be estimated. If NULL, will perform an unconstrained estimation for the transform given by the output transform array type. If not NULL, the following restrictions apply: Transform type must be consistent with output transform array type: Transform Type Output transform array type VPI_XFORM_CONSTRAINED_HOMOGRAPHY_2D VPI_ARRAY_TYPE_HOMOGRAPHY_TRANSFORM_2D

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	payload is NULL.
VPI_ERROR_INVALID_ARGUMENT	srcKeypoints or tgtKeypoints are NULL.
VPI_ERROR_INVALID_ARGUMENT	outTransform is NULL.
VPI_ERROR_INVALID_ARGUMENT	backend is invalid or unknown.
VPI_ERROR_INVALID_ARGUMENT	srcKeypoints, tgtKeypoints aren't consistent.
VPI_ERROR_INVALID_ARGUMENT	Transform type not consistent with output transform array type.
VPI_ERROR_INVALID_ARRAY_TYPE	Array type of srcKeypoints, tgtKeypoints, matches or outInliers is not correct.
VPI_ERROR_NOT_IMPLEMENTED	Transform Estimator algorithm is not supported by given backend.
VPI_ERROR_INVALID_OPERATION	Backend hardware not available.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream, srcKeypoints, tgtKeypoints or matches.
VPI_SUCCESS	Operation executed successfully.