How does Lowe's ratio test with knnMatch(k=2) filter OpenCV feature matches?

## The problem the test solves Descriptor matching has no built-in notion of no answer. `BFMatcher.match(des1, des2)` computes, for every row of `des1`, the closest row of `des2` and emits a `cv2.DMatch` with `queryIdx`, `trainIdx` and `distance`. If a keypoint in image 1 shows a part of the scene that image 2 never captured, its nearest neighbour is still returned — just a bad one. Feed those to `findHomography` and you have contaminated the input with outliers before RANSAC ever runs. An absolute distance threshold is a poor filter, because descriptor distance has no stable scale: it varies with illumination, blur, and the descriptor type. What generalises is a *relative* comparison inside the same query. ## The mechanism `bf.knnMatch(des1, des2, k=2)` returns, for each query descriptor, a Python list of the k best `DMatch` objects sorted by distance. The ratio test asks: how much better is the best candidate than the runner-up? - If the best is much closer than the second best (small ratio), the query descriptor is *distinctive*: only one region in the other image looks like it. Trust it. - If the two are nearly tied (ratio near 1), the query looks like at least two different places. Even if one is correct, you have no way to tell which — so the safe action is to drop it entirely. The threshold that David Lowe proposed with SIFT, and that is still the default in practice, is 0.7 to 0.8. The effect is asymmetric and deliberate: it removes a large share of false matches while costing comparatively few true ones, because a genuine correspondence usually has a clear winner. ## Tuning Think of it as a precision/recall dial: - **0.6 and below** — very strict, few surviving matches, nearly all correct. Appropriate when the scene has heavy repeated texture and you only need a handful of confident correspondences to fit a homography. - **0.75** — the standard starting point. - **0.85 and above** — permissive; you keep more true matches at the cost of admitting outliers, which then has to be absorbed by RANSAC. The right value depends on what runs downstream. A robust estimator can tolerate outliers up to a point, so it is often better to be moderately strict here and let RANSAC handle the residue than to be so strict that you fall below the minimum correspondence count. ## Ratio test versus crossCheck OpenCV offers a second, independent ambiguity filter. `cv2.BFMatcher(normType, crossCheck=True)` returns a match only when descriptor i in image 1 has j as its nearest neighbour in image 2 *and* j has i as its nearest neighbour back in image 1 — a mutual best match. It is symmetric and needs no threshold. The two cannot be combined in one matcher object: `crossCheck=True` conflicts with `knnMatch(k=2)`, because cross-checking is defined for a single best match per query. Trying it produces an error rather than a silently degraded result. In practice: - Use `crossCheck=True` with `match()` when you want a parameter-free filter and are matching two images of similar content. - Use `knnMatch(k=2)` plus the ratio test when repeated texture is the main risk, or when you want an explicit dial to tune. The ratio test is generally the stronger filter for wide-baseline matching, and it is what most stitching pipelines use. Applying both by using two matcher passes and intersecting the results is possible but rarely worth the extra cost. ## Implementation details that bite **Short neighbour lists.** `knnMatch` can return fewer than k matches for a query — for example when a mask restricts candidates, or when the train set has fewer than k descriptors. Unpacking with `for m, n in matches` then raises a ValueError on that entry. A robust loop checks `len(pair) == 2` first. **None descriptors.** If either image produced no keypoints, its descriptor array is `None` in Python and the matcher raises. Guard before matching. **The result is a list of lists.** `knnMatch` does not return a flat list like `match()`; forgetting this and passing it straight to `cv2.drawMatches` fails, since that expects flat `DMatch` objects (`cv2.drawMatchesKnn` takes the nested form). **Counting after filtering.** The number of surviving matches is your first quality signal. Fewer than roughly a dozen after the ratio test on a pair that should overlap usually means a wrong norm, a scale gap too large for the detector, or genuinely non-overlapping images — investigate before blaming the estimator downstream.