Find Homography

Detailed Description

The Find Homography Algorithm.

The function finds and returns the perspective transformation between the source and the destination planes so that back-projection error is minimized.

Method

If the parameter method is set to USE_ALL_POINTS, the function uses all the point pairs to compute an initial homography estimate with a simple least-squares scheme. However, if not all of the point pairs (srcPoints, dstPoints) fit the rigid perspective transformation (that is, there are some outliers), this initial estimate will be poor.

When initial estimates are poor, you can use one of the two robust methods. Both methods, RANSAC and LMeDS:

1. Try many different random subsets of the corresponding point pairs (of four pairs each),
2. Estimate the homography matrix using this subset and a simple least-square algorithm, and then
3. Compute the quality/goodness of the computed homography (which is the number of inliers for RANSAC or the median re-projection error for LMeDs).

The best subset is then used to produce the initial estimate of the homography matrix and the mask of inliers/outliers. Regardless of the method, robust or not, the computed homography matrix is refined further (using inliers only in case of a robust method) with the Levenberg-Marquardt method to reduce the re-projection error even more.

• RANSAC handles practically any ratio of outliers but it needs a threshold to distinguish inliers from outliers.
• LMeDS does not need any threshold but it works correctly only when there are more than 50% of inliers.
• Finally, if there are no outliers and the noise is rather small, use the default method (USE_ALL_POINTS).

The function is used to find initial intrinsic and extrinsic matrices. Homography matrix is determined up to a scale. Thus, it is normalized so that H(3,3)=1.

Enumerations
enum	nvx_find_homography_method_e {   NVX_FIND_HOMOGRAPHY_METHOD_USE_ALL_POINTS = 0x0,   NVX_FIND_HOMOGRAPHY_METHOD_RANSAC = 0x1,   NVX_FIND_HOMOGRAPHY_METHOD_LMEDS = 0x2 }
	Method used to compute a homography matrix. More...

Functions
vx_node	nvxFindHomographyNode (vx_graph graph, vx_array srcPoints, vx_array dstPoints, vx_matrix homography, vx_enum method, vx_float32 threshold, vx_int32 maxEstimateIters, vx_int32 maxRefineIters, vx_float32 confidence, vx_float32 outlierRatio, vx_array inliers)
	[Graph] Computes homography matrix. More...
vx_status	nvxuFindHomography (vx_context context, vx_array srcPoints, vx_array dstPoints, vx_matrix homography, vx_enum method, vx_float32 threshold, vx_int32 maxEstimateIters, vx_int32 maxRefineIters, vx_float32 confidence, vx_float32 outlierRatio, vx_array inliers)
	[Immediate] Computes homography matrix. More...

Enumeration Type Documentation

enum nvx_find_homography_method_e

Method used to compute a homography matrix.

Enumerator
NVX_FIND_HOMOGRAPHY_METHOD_USE_ALL_POINTS	A regular method using all the points.
NVX_FIND_HOMOGRAPHY_METHOD_RANSAC	RANSAC-based robust method.
NVX_FIND_HOMOGRAPHY_METHOD_LMEDS	Least-Median robust method.

Definition at line 1555 of file nvx.h.

Function Documentation

vx_node nvxFindHomographyNode	(	vx_graph	graph,
		vx_array	srcPoints,
		vx_array	dstPoints,
		vx_matrix	homography,
		vx_enum	method,
		vx_float32	threshold,
		vx_int32	maxEstimateIters,
		vx_int32	maxRefineIters,
		vx_float32	confidence,
		vx_float32	outlierRatio,
		vx_array	inliers
	)

[Graph] Computes homography matrix.

Parameters

[in]	graph	Specifies the graph.
[in]	srcPoints	Specifies the coordinates of the points in the original plane (array of vx_keypoint_t, nvx_keypointf_t or nvx_point2f_t structs, number of the points must be >= 4). For vx_keypoint_t and nvx_keypointf_t types, the method uses points only with non-zero tracking_status.
[in]	dstPoints	Specifies the coordinates of the points in the target plane (it must have the same number of elements and type as srcPoints). For vx_keypoint_t and nvx_keypointf_t types, the method uses points only with non-zero tracking_status. The correspondence is between points with the same indexes in arrays.
[out]	homography	Specifies the output homography matrix (VX_TYPE_FLOAT32 3x3 matrix).
[in]	method	Specifies the method used to compute a homography matrix (see nvx_find_homography_method_e).
[in]	threshold	Specifies the maximum allowed reprojection error to treat a point pair as an inlier, if RANSAC method is chosen. If srcPoints and dstPoints are measured in pixels, it usually makes sense to set this parameter somewhere in the range of 1 to 10. Default value is 3.
[in]	maxEstimateIters	Specifies the maximum allowed number of estimation iterations for robust methods (RANSAC and LMeDS). Default value is 2000.
[in]	maxRefineIters	Specifies the maximum allowed number of refinement iterations for robust methods (RANSAC and LMeDS). Default value is 10.
[in]	confidence	Specifies the confidence level for robust methods (RANSAC and LMeDS). It must be a value between 0 and 1. Default value is 0.995.
[in]	outlierRatio	Specifies the outlier ratio if LMeDS method is chosen. Default value is 0.45.
[out]	inliers	Specifies the optional inliers/outliers output mask. The inliers[i] value is set to 0 if corresponding points pair srcPoints[i] and dstPoints[i] is marked as outlier by the method. It must be a VX_TYPE_UINT8 array with capacity greater than or equal to the capacity of srcPoints.

Returns

vx_node

vx_status nvxuFindHomography	(	vx_context	context,
		vx_array	srcPoints,
		vx_array	dstPoints,
		vx_matrix	homography,
		vx_enum	method,
		vx_float32	threshold,
		vx_int32	maxEstimateIters,
		vx_int32	maxRefineIters,
		vx_float32	confidence,
		vx_float32	outlierRatio,
		vx_array	inliers
	)

[Immediate] Computes homography matrix.

Parameters

[in]	context	Specifies the context.
[in]	srcPoints	Specifies the coordinates of the points in the original plane (array of vx_keypoint_t, nvx_keypointf_t or nvx_point2f_t structs, number of the points must be >= 4). For vx_keypoint_t and nvx_keypointf_t types, the method uses points only with non-zero tracking_status.
[in]	dstPoints	Specifies the coordinates of the points in the target plane (it must have the same number of elements and type as srcPoints). For vx_keypoint_t and nvx_keypointf_t types, the method uses points only with non-zero tracking_status. The correspondence is between points with the same indexes in arrays.
[out]	homography	Specifies the output homography matrix (VX_TYPE_FLOAT32 3x3 matrix).
[in]	method	Specifies the method used to compute a homography matrix (see nvx_find_homography_method_e) (optional, NVX_FIND_HOMOGRAPHY_METHOD_USE_ALL_POINTS by default).
[in]	threshold	Specifies the maximum allowed reprojection error to treat a point pair as an inlier, if RANSAC method is chosen. If srcPoints and dstPoints are measured in pixels, it usually makes sense to set this parameter somewhere in the range of 1 to 10. Default value is 3.
[in]	maxEstimateIters	Specifies the maximum allowed number of estimation iterations for robust methods (RANSAC and LMeDS). Default value is 2000.
[in]	maxRefineIters	Specifies the maximum allowed number of refinement iterations for robust methods (RANSAC and LMeDS). Default value is 10.
[in]	confidence	Specifies the confidence level for robust methods (RANSAC and LMeDS). It should be a value between 0 and 1. Default value is 0.995.
[in]	outlierRatio	Specifies the outlier ratio if LMeDS method is chosen. Default value is 0.45.
[out]	inliers	Specifies the optional inliers/outliers output mask. The inliers[i] value is set to 0 if corresponding points pair srcPoints[i] and dstPoints[i] is marked as outlier by the method. It must be a VX_TYPE_UINT8 array with capacity greater than or equal to the capacity of srcPoints.

Returns

vx_status