Skip to content

leveling

leveling #

leveled — a free reconstruction given gravity: its dominant plane becomes the ground.

  1. Ground. RANSAC over three-point samples of points finds the plane with the most points within INLIER_FRACTION of the cloud's extent; a least-squares fit to those inliers refines it.
  2. Up. The plane's normal is signed so the mean camera centre lies on its positive side: cameras stand above the ground, never below it.
  3. Move. The whole model turns so that normal becomes +y and slides so the ground is y = 0 — a rigid motion, so scale and shape survive.

INLIER_FRACTION = 0.02 module-attribute #

How far from the plane a point may lie and still count, as a fraction of the cloud's extent.

dominant_plane(points) #

The plane through the most of points: (unit normal, a point on it, inlier mask).

Source code in capturegraph-recipes/capturegraph_recipes/sfm/alignment/leveling.py
def dominant_plane(points: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
    """The plane through the most of ``points``: ``(unit normal, a point on it, inlier mask)``."""
    rng = np.random.default_rng(0)
    threshold = INLIER_FRACTION * float(np.linalg.norm(points.max(axis=0) - points.min(axis=0)))
    best = np.zeros(len(points), dtype=bool)
    for _ in range(RANSAC_ITERATIONS):
        a, b, c = points[rng.choice(len(points), 3, replace=False)]
        normal = np.cross(b - a, c - a)
        length = np.linalg.norm(normal)
        if length == 0.0:
            continue
        inliers = np.abs((points - a) @ (normal / length)) <= threshold
        if inliers.sum() > best.sum():
            best = inliers
    origin = points[best].mean(axis=0)
    _, _, vt = np.linalg.svd(points[best] - origin)
    return vt[-1], origin, best

leveled(model) #

model turned and lifted so its dominant plane is the ground at y = 0.

Parameters:

Name Type Description Default
model Reconstruction

The reconstruction, typically one built from nothing and so without a notion of up.

required

Raises:

Type Description
ValueError

If the model holds fewer than three points or no camera.

Source code in capturegraph-recipes/capturegraph_recipes/sfm/alignment/leveling.py
@cg.pure_function("sfm.leveled/1")
def leveled(model: Reconstruction) -> Reconstruction:
    """``model`` turned and lifted so its dominant plane is the ground at ``y = 0``.

    Args:
        model: The reconstruction, typically one built from nothing and so
            without a notion of up.

    Raises:
        ValueError: If the model holds fewer than three points or no camera.
    """
    points, _ = model.points.points()
    points = points.astype(np.float64)
    if len(points) < 3 or not len(model.cameras):
        raise ValueError("levelling needs at least three points and one camera")
    normal, origin, inliers = dominant_plane(points)
    centres = np.array([position(pose) for pose in model.cameras.values()])
    if (centres.mean(axis=0) - origin) @ normal < 0.0:
        normal = -normal
    rotation = _rotation_onto_y(normal)
    translation = np.array([0.0, -(rotation @ origin)[1], 0.0])
    cg.logging.info(
        "Leveled",
        inlier_fraction=float(inliers.mean()),
        tilt_degrees=math.degrees(math.acos(min(1.0, max(-1.0, float(normal[1]))))),
    )
    return transformed(model, 1.0, rotation, translation)