How do you use cv2.findHomography with RANSAC to reject outlier matches?

## What a homography is and when it applies A homography is a 3x3 matrix mapping points from one image plane to another in homogeneous coordinates, up to scale — eight degrees of freedom, which is why four point correspondences (two equations each) are the minimum. It exactly describes the relationship between two views in only two situations: the scene points all lie on a **plane**, or the camera **rotates about its optical centre without translating**. Panorama stitching relies on the second; document scanning, marker tracking and aerial-to-map registration rely on the first. If neither holds — a camera that translates through a scene with depth — no homography fits, and forcing one produces a matrix that satisfies the dominant plane and mangles everything else. Two-view geometry with depth needs the fundamental or essential matrix instead (`cv2.findFundamentalMat`), not this function. ## Preparing the inputs OpenCV wants both point sets as float32 arrays of shape `(N, 1, 2)`, in corresponding order: row i of `src` maps to row i of `dst`. The standard construction from matches is: src = np.float32([kp1[m.queryIdx].pt for m in good]).reshape(-1, 1, 2) dst = np.float32([kp2[m.trainIdx].pt for m in good]).reshape(-1, 1, 2) Getting `queryIdx` and `trainIdx` the wrong way round produces the inverse mapping — the warp goes the wrong direction and the result looks confidently broken. ## What RANSAC does here With `method=cv2.RANSAC`, the estimator does not fit all the points. It: 1. Samples a random minimal subset of 4 correspondences. 2. Fits the exact homography through them. 3. Maps every `src` point with that candidate and counts how many land within `ransacReprojThreshold` pixels of their `dst` partner. Those are the inliers. 4. Repeats up to `maxIters` times (default 2000), keeping the model with the largest inlier set, stopping early once `confidence` (default 0.995) is reached. 5. Re-estimates the final homography using **all** inliers, so the answer is not merely the best random quadruple. This is why the estimator survives a match list that is half wrong: outliers never form a consistent large inlier set, so they cannot win the vote. ## The parameters that matter - **ransacReprojThreshold** is in **pixels of reprojection error**, defaulting to 3. It should reflect your keypoint localisation noise and image resolution: 1 to 3 for clean, high-resolution, well-localised features; 5 to 10 for noisy detections or heavily downscaled images. Too small and every model looks bad, so the inlier count collapses; too large and outliers get counted as inliers, dragging the refined fit off. - **maxIters** caps the sampling. If the true inlier ratio is low, the probability of drawing four clean points at random falls steeply, and 2000 iterations may not be enough. - **confidence** is the desired probability of finding a good model and governs early termination. ## Alternatives to the method argument Passing `0` fits least squares over all points, which any single outlier ruins — only use it when the correspondences are already known-clean. `cv2.LMEDS` needs no threshold but assumes more than half the matches are inliers. `cv2.RHO` is a faster variant that does well at low inlier ratios. OpenCV 4.5 and later, including OpenCV 5, also expose the USAC family such as `cv2.USAC_MAGSAC`, which is generally more accurate and less threshold-sensitive than plain RANSAC and is worth benchmarking on your data. ## Reading the mask, and validating the result The second return value is an `(N, 1)` uint8 mask. It is the diagnostic that separates a real fit from a lucky one: - `H is None` — estimation failed outright, usually too few points or a degenerate configuration. - Low absolute inlier count (single digits) — the model was fit on almost nothing. Do not trust it, whatever it looks like. - Low inlier *ratio* — matching is producing noise; look upstream at the descriptor norm, the ratio test, or whether the images overlap at all. Even a healthy inlier count can hide a degenerate case: if all inliers are collinear or clustered in a small image region, the homography is unconstrained elsewhere and extrapolates absurdly. A cheap, effective sanity check is to push the source image corners through with `cv2.perspectiveTransform(corners, H)` and verify the result is still a convex, sensibly sized quadrilateral rather than a self-intersecting bowtie or something a thousand pixels off-frame. Checking that the determinant of the top-left 2x2 block is positive catches mirror flips. Once `H` is trusted, `cv2.warpPerspective` applies it, and `cv2.drawMatches` with `matchesMask=mask.ravel().tolist()` visualises exactly which correspondences the estimator kept — the single most useful debugging image in this whole pipeline.