findHomography

geometryfunctionOpenCV 5.0.0

import { findHomography } from '@banou/opencv-wasm'

Use after await initOpenCV(). See the initialization and named imports guide.

Explore visually: Homography and RANSAC →

Estimate a projective mapping between two views of a plane, rejecting inconsistent point matches.

VISUAL WALKTHROUGHGeometry

REFERENCE INPUTTentative correspondences

Eight tentative matches include two inconsistent pairs, shown in orange.

→

RESULTRecover the projective plane

The accepted mapping bends a rectangular grid into perspective. Every grid intersection uses the same projective transform as the inlier points.

Illustrative example. The stages explain the method; they are not a live OpenCV execution.

example: samples/cpp/tutorial_code/features/Homography/pose_from_homography.cpp An example program about pose estimation from coplanar points

Check tutorial_homography "the corresponding tutorial" for more details Finds a perspective transformation between two planes.

Note: Whenever an H matrix cannot be estimated, an empty one will be returned.

See: getAffineTransform, estimateAffine2D, estimateAffinePartial2D, getPerspectiveTransform, warpPerspective, perspectiveTransform

findHomography(srcPoints: Mat, dstPoints: Mat, method: number, ransacReprojThreshold: number, mask: Mat, maxIters: number, confidence: number): Mat;

6 available overloads

findHomography(srcPoints: Mat, dstPoints: Mat): Mat;

findHomography(srcPoints: Mat, dstPoints: Mat, method: number): Mat;

findHomography(srcPoints: Mat, dstPoints: Mat, method: number, ransacReprojThreshold: number): Mat;

findHomography(srcPoints: Mat, dstPoints: Mat, method: number, ransacReprojThreshold: number, mask: Mat): Mat;

findHomography(srcPoints: Mat, dstPoints: Mat, method: number, ransacReprojThreshold: number, mask: Mat, maxIters: number): Mat;

findHomography(srcPoints: Mat, dstPoints: Mat, method: number, ransacReprojThreshold: number, mask: Mat, maxIters: number, confidence: number): Mat;

srcPoints

Coordinates of the points in the original plane, a matrix of the type CV_32FC2 or vector<Point2f> .

dstPoints

Coordinates of the points in the target plane, a matrix of the type CV_32FC2 or a vector<Point2f> .

method

Method used to compute a homography matrix. The following methods are possible:

• 0 - a regular method using all the points, i.e., the least squares method
• RANSAC - RANSAC-based robust method
• LMEDS - Least-Median robust method
• RHO - PROSAC-based robust method

ransacReprojThreshold

Maximum allowed reprojection error to treat a point pair as an inlier (used in the RANSAC and RHO methods only). That is, if

\| \texttt{dstPoints} _i -  \texttt{convertPointsHomogeneous} ( \texttt{H} \cdot \texttt{srcPoints} _i) \|_2  >  \texttt{ransacReprojThreshold}

then the point i is considered as an outlier. If srcPoints and dstPoints are measured in pixels, it usually makes sense to set this parameter somewhere in the range of 1 to 10.

mask

Output destination, filled by the native operation. Optional output mask set by a robust method ( RANSAC or LMeDS ). Note that the input mask values are ignored.

maxIters

The maximum number of RANSAC iterations.

confidence

Confidence level, between 0 and 1.

The function finds and returns the perspective transformation H between the source and the destination planes:

s_i  \vecthree{x'_i}{y'_i}{1} \sim H  \vecthree{x_i}{y_i}{1}

so that the back-projection error

\sum _i \left ( x'_i- \frac{h_{11} x_i + h_{12} y_i + h_{13}}{h_{31} x_i + h_{32} y_i + h_{33}} \right )^2+ \left ( y'_i- \frac{h_{21} x_i + h_{22} y_i + h_{23}}{h_{31} x_i + h_{32} y_i + h_{33}} \right )^2

is minimized. If the parameter method is set to the default value 0, 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_i, dstPoints_i ) fit the rigid perspective transformation (that is, there are some outliers), this initial estimate will be poor. In this case, you can use one of the three robust methods. The methods RANSAC, LMeDS and RHO try many different random subsets of the corresponding point pairs (of four pairs each, collinear pairs are discarded), estimate the homography matrix using this subset and a simple least-squares algorithm, and then compute the quality/goodness of the computed homography (which is the number of inliers for RANSAC or the least 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 methods RANSAC and RHO can handle practically any ratio of outliers but need a threshold to distinguish inliers from outliers. The method 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 (method=0).

The function is used to find initial intrinsic and extrinsic matrices. Homography matrix is determined up to a scale. If h_{33} is non-zero, the matrix is normalized so that h_{33}=1.

Returns

The Mat result. Release returned native handles with using or delete(), including handles nested in results.

Upstream declaration ↗

These signatures describe this package. Upstream documentation can mention optional backends that are absent from this build. Check runtime compatibility before choosing a backend or file format.