Skip to content

pairs

pairs #

Which images to compare: every pair, a sliding window, or the neighbours of known poses.

Matching costs a pair at a time, so the choice of pairs is the choice of how long a reconstruction takes. exhaustive_pairs compares everything; sequential_pairs compares each image with the next few, as a video walks; nearby_pairs uses prior poses to compare only cameras that stand close and look the same way — the optional-positions guidance, which also takes sparse priors and falls back to the sequential walk where there is none.

dense_pairs(poses, neighbors=32, max_distance_meters=50.0, max_angle_degrees=90.0) #

nearby_pairs over a prior pose for every image; see there.

Parameters:

Name Type Description Default
poses Array[Pose]

The prior pose of every image, in image order.

required
neighbors int

How many neighbours each pose keeps at most.

32
max_distance_meters float

The furthest a neighbour's centre may be.

50.0
max_angle_degrees float

The widest angle between two optical axes.

90.0
Source code in capturegraph-recipes/capturegraph_recipes/sfm/correspondence/pairs.py
@cg.pure_function("sfm.dense_pairs/1")
def dense_pairs(
    poses: cg.Array[cg.Pose],
    neighbors: int = 32,
    max_distance_meters: float = 50.0,
    max_angle_degrees: float = 90.0,
) -> Pairs:
    """``nearby_pairs`` over a prior pose for every image; see there.

    Args:
        poses: The prior pose of every image, in image order.
        neighbors: How many neighbours each pose keeps at most.
        max_distance_meters: The furthest a neighbour's centre may be.
        max_angle_degrees: The widest angle between two optical axes.
    """
    rows, kept = _nearby(list(poses), neighbors, max_distance_meters, max_angle_degrees)
    return _pairs(
        np.array(rows, dtype=np.int64).reshape(-1, 2),
        mean_neighbors=float(np.mean(kept)) if kept else 0.0,
    )

exhaustive_pairs(count) #

Every pair of count images.

Parameters:

Name Type Description Default
count int

How many images there are.

required
Source code in capturegraph-recipes/capturegraph_recipes/sfm/correspondence/pairs.py
@cg.pure_function("sfm.exhaustive_pairs/1")
def exhaustive_pairs(count: int) -> Pairs:
    """Every pair of ``count`` images.

    Args:
        count: How many images there are.
    """
    a, b = np.triu_indices(count, k=1)
    return _pairs(np.stack([a, b], axis=1))

nearby_pairs(poses, count=None, neighbors=32, max_distance_meters=50.0, max_angle_degrees=90.0) #

Each pose paired with its nearest neighbours that look roughly the same way.

Neighbours are ranked by the distance between camera centres; one further than max_distance_meters, or whose optical axis turns more than max_angle_degrees from the pose's own, is passed over. Priors may be sparse — a Map keyed by image index, as exif_priors gives — in which case the images with a prior pair among themselves by distance and every image without one pairs with the neighbors images on either side of it in index order, as a burst walks. The two cases are the memoized dense_pairs and sparse_pairs; this is their one door.

Parameters:

Name Type Description Default
poses Array[Pose] | Map[String, Pose]

The prior pose of every image in image order, or of some images keyed by array position, as exif_priors gives.

required
count int | None

How many images there are; required with a Map, and the array's length otherwise.

None
neighbors int

How many neighbours each pose keeps at most, and the index window of an image without a prior.

32
max_distance_meters float

The furthest a neighbour's centre may be.

50.0
max_angle_degrees float

The widest angle between two optical axes.

90.0

Raises:

Type Description
ValueError

If poses is a Map and count is not given.

Source code in capturegraph-recipes/capturegraph_recipes/sfm/correspondence/pairs.py
def nearby_pairs(
    poses: cg.Array[cg.Pose] | cg.Map[cg.String, cg.Pose],
    count: int | None = None,
    neighbors: int = 32,
    max_distance_meters: float = 50.0,
    max_angle_degrees: float = 90.0,
) -> Pairs:
    """Each pose paired with its nearest neighbours that look roughly the same way.

    Neighbours are ranked by the distance between camera centres; one further
    than ``max_distance_meters``, or whose optical axis turns more than
    ``max_angle_degrees`` from the pose's own, is passed over. Priors may be
    sparse — a ``Map`` keyed by image index, as ``exif_priors`` gives — in
    which case the images with a prior pair among themselves by distance and
    every image without one pairs with the ``neighbors`` images on either
    side of it in index order, as a burst walks. The two cases are the
    memoized ``dense_pairs`` and ``sparse_pairs``; this is their one door.

    Args:
        poses: The prior pose of every image in image order, or of some
            images keyed by array position, as ``exif_priors`` gives.
        count: How many images there are; required with a ``Map``, and the
            array's length otherwise.
        neighbors: How many neighbours each pose keeps at most, and the
            index window of an image without a prior.
        max_distance_meters: The furthest a neighbour's centre may be.
        max_angle_degrees: The widest angle between two optical axes.

    Raises:
        ValueError: If ``poses`` is a ``Map`` and ``count`` is not given.
    """
    if isinstance(poses, cg.Map):
        if count is None:
            raise ValueError("nearby_pairs needs the image count with sparse priors")
        return sparse_pairs(poses, count, neighbors, max_distance_meters, max_angle_degrees)
    return dense_pairs(poses, neighbors, max_distance_meters, max_angle_degrees)

sequential_pairs(count, window=10) #

Each of count images paired with the window that follow it.

Parameters:

Name Type Description Default
count int

How many images there are.

required
window int

How many later images each image is compared with.

10
Source code in capturegraph-recipes/capturegraph_recipes/sfm/correspondence/pairs.py
@cg.pure_function("sfm.sequential_pairs/1")
def sequential_pairs(count: int, window: int = 10) -> Pairs:
    """Each of ``count`` images paired with the ``window`` that follow it.

    Args:
        count: How many images there are.
        window: How many later images each image is compared with.
    """
    a, b = np.triu_indices(count, k=1)
    keep = b - a <= window
    return _pairs(np.stack([a[keep], b[keep]], axis=1))

sparse_pairs(poses, count, neighbors=32, max_distance_meters=50.0, max_angle_degrees=90.0) #

nearby_pairs over priors some images have; see there.

Parameters:

Name Type Description Default
poses Map[String, Pose]

A prior pose per image, keyed by array position.

required
count int

How many images there are.

required
neighbors int

How many neighbours a posed image keeps at most, and the index window of an image without a prior.

32
max_distance_meters float

The furthest a neighbour's centre may be.

50.0
max_angle_degrees float

The widest angle between two optical axes.

90.0
Source code in capturegraph-recipes/capturegraph_recipes/sfm/correspondence/pairs.py
@cg.pure_function("sfm.sparse_pairs/1")
def sparse_pairs(
    poses: cg.Map[cg.String, cg.Pose],
    count: int,
    neighbors: int = 32,
    max_distance_meters: float = 50.0,
    max_angle_degrees: float = 90.0,
) -> Pairs:
    """``nearby_pairs`` over priors some images have; see there.

    Args:
        poses: A prior pose per image, keyed by array position.
        count: How many images there are.
        neighbors: How many neighbours a posed image keeps at most, and the
            index window of an image without a prior.
        max_distance_meters: The furthest a neighbour's centre may be.
        max_angle_degrees: The widest angle between two optical axes.
    """
    indices = sorted(camera_index(key) for key in poses.keys())
    known = [poses[camera_key(index)] for index in indices]
    rows, kept = _nearby(known, neighbors, max_distance_meters, max_angle_degrees)
    rows = [(indices[a], indices[b]) for a, b in rows]
    for image in set(range(count)) - set(indices):
        rows.extend(
            (min(image, other), max(image, other))
            for other in range(max(0, image - neighbors), min(count, image + neighbors + 1))
            if other != image
        )
    return _pairs(
        np.array(rows, dtype=np.int64).reshape(-1, 2),
        mean_neighbors=float(np.mean(kept)) if kept else 0.0,
    )