Skip to content

matching

matching #

match — the keypoints two images agree on, verified by a fundamental matrix.

MIN_CANDIDATES = 8 module-attribute #

Fewer candidates than a fundamental matrix needs yield no matches at all.

MIN_INLIERS = 15 module-attribute #

A fundamental matrix explaining fewer correspondences is chance, not a shared scene.

RATIO = 0.8 module-attribute #

Lowe's ratio: a nearest neighbour counts only when this much closer than the second.

match(image_a, image_b) #

The keypoint correspondences between image_a and image_b.

Each image's keypoints are matched by descriptor distance with Lowe's ratio test in both directions, keeping only mutual pairs; a fundamental matrix fitted by MAGSAC then keeps the pairs consistent with one rigid scene, so no intrinsics are needed. Fewer than MIN_CANDIDATES mutual pairs cannot be verified, and fewer than MIN_INLIERS verified ones are chance agreement; both give no matches.

Parameters:

Name Type Description Default
image_a Image

The first image.

required
image_b Image

The second image.

required
Source code in capturegraph-recipes/capturegraph_recipes/sfm/correspondence/matching.py
@cg.pure_function("sfm.match/1")
def match(image_a: cg.Image, image_b: cg.Image) -> Matches:
    """The keypoint correspondences between ``image_a`` and ``image_b``.

    Each image's ``keypoints`` are matched by descriptor distance with Lowe's
    ratio test in both directions, keeping only mutual pairs; a fundamental
    matrix fitted by MAGSAC then keeps the pairs consistent with one rigid
    scene, so no intrinsics are needed. Fewer than ``MIN_CANDIDATES`` mutual
    pairs cannot be verified, and fewer than ``MIN_INLIERS`` verified ones
    are chance agreement; both give no matches.

    Args:
        image_a: The first image.
        image_b: The second image.
    """
    a = keypoints(image_a).arrays()
    b = keypoints(image_b).arrays()
    candidates = mutual_matches(a["descriptors"], b["descriptors"])
    if len(candidates) < MIN_CANDIDATES:
        cg.logging.info("Matched", candidates=int(len(candidates)), inliers=0)
        return Matches.empty()
    _, mask = cv2.findFundamentalMat(
        a["xy"][candidates[:, 0]],
        b["xy"][candidates[:, 1]],
        cv2.USAC_MAGSAC,
        FUNDAMENTAL_THRESHOLD_PX,
        RANSAC_CONFIDENCE,
    )
    inliers = candidates[mask.reshape(-1) > 0] if mask is not None else candidates[:0]
    if len(inliers) < MIN_INLIERS:
        inliers = candidates[:0]
    cg.logging.info("Matched", candidates=int(len(candidates)), inliers=int(len(inliers)))
    return Matches.of(ab=inliers)

mutual_matches(descriptors_a, descriptors_b) #

The M×2 index pairs passing the ratio test from both sides.

Source code in capturegraph-recipes/capturegraph_recipes/sfm/correspondence/matching.py
def mutual_matches(descriptors_a: np.ndarray, descriptors_b: np.ndarray) -> np.ndarray:
    """The M×2 index pairs passing the ratio test from both sides."""
    if len(descriptors_a) < 2 or len(descriptors_b) < 2:
        return np.zeros((0, 2), dtype=np.int64)
    forward = _ratio_test(descriptors_a.astype(np.float32), descriptors_b.astype(np.float32))
    backward = _ratio_test(descriptors_b.astype(np.float32), descriptors_a.astype(np.float32))
    reverse = {(j, i) for i, j in backward}
    return np.array([(i, j) for i, j in forward if (i, j) in reverse], dtype=np.int64).reshape(
        -1, 2
    )