VisionWorks Toolkit Reference

December 18, 2015 | 1.2 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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.

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_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_array inliers)
 [Immediate] Computes homography matrix. More...
 

Enumeration Type Documentation

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 1551 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_array  inliers 
)

[Graph] Computes homography matrix.

Parameters
[in]graphSpecifies the graph.
[in]srcPointsSpecifies the coordinates of the points in the original plane (array of vx_keypoint_t or nvx_point2f_t structs, number of the points must be >= 4).
[in]dstPointsSpecifies the coordinates of the points in the target plane (array of vx_keypoint_t or nvx_point2f_t structs; it must have the same number of elements and type as srcPoints). The correspondence is between points with the same indexes in arrays.
[out]homographySpecifies the output homography matrix (VX_TYPE_FLOAT32 3x3 matrix).
[in]methodSpecifies the method used to compute a homography matrix (see nvx_find_homography_method_e).
[in]thresholdSpecifies 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.
[out]inliersSpecifies 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_array  inliers 
)

[Immediate] Computes homography matrix.

Parameters
[in]contextSpecifies the context.
[in]srcPointsSpecifies the coordinates of the points in the original plane (array of vx_keypoint_t or nvx_point2f_t structs, number of the points must be >= 4).
[in]dstPointsSpecifies the coordinates of the points in the target plane (array of vx_keypoint_t or nvx_point2f_t structs; it must have the same number of elements and type as srcPoints). The correspondence is between points with the same indexes in arrays.
[out]homographySpecifies the output homography matrix (VX_TYPE_FLOAT32 3x3 matrix).
[in]methodSpecifies 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]thresholdSpecifies 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.
[out]inliersSpecifies 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