kornia.geometry.homography#

Functions to estimate homographies from point or line correspondences and to score them.

kornia.geometry.homography.find_homography_dlt(points1, points2, weights=None, solver='lu')[source]#

Compute the homography matrix using the DLT formulation.

The weighted DLT system of four or more correspondences is solved with solver.

Convention:

H maps points1 to points2, points2 ~ H @ points1, and is scaled so that H[2, 2] = 1 by normalize_transformation(), which leaves it at its unnormalised scale when |H[2, 2]| is at most 1e-8; Two-view geometry compares this with OpenCV.
weights multiply each correspondence’s squared algebraic residual: a weight of 0 removes the correspondence from the equations, and only relative weights matter.
solver="lu" and "svd" give the same homography on exact data, to roundoff scaled by the conditioning of the system; on noisy data they solve different least-squares problems and differ.

Parameters:

points1 (Tensor) – A set of points in the first image with a tensor shape \((B, N, 2)\).
points2 (Tensor) – A set of points in the second image with a tensor shape \((B, N, 2)\).
weights (Optional[Tensor], optional) – Tensor containing the weights per point correspondence with a shape of \((B, N)\). Zero-weight points are excluded from the DLT equations and Hartley normalization. Default: None
solver (str, optional) – variants: svd, lu. Default: "lu"

Return type:

Tensor

Returns:

the computed homography matrix with shape \((B, 3, 3)\).

kornia.geometry.homography.find_homography_dlt_iterated(points1, points2, weights, soft_inl_th=3.0, n_iter=5)[source]#

Compute the homography matrix using the iteratively-reweighted least squares (IRWLS).

Convention:

Direction and H[2, 2] = 1 as find_homography_dlt(). Each solve after the first re-weights with the Gaussian kernel exp(-e**2 / (2 * soft_inl_th**2)) of the symmetric transfer error e (the root of the summed squared forward and backward transfer errors), so soft_inl_th is a standard deviation in pixels: a correspondence with e = soft_inl_th keeps weight exp(-1/2).

Parameters:

points1 (Tensor) – A set of points in the first image with a tensor shape \((B, N, 2)\).
points2 (Tensor) – A set of points in the second image with a tensor shape \((B, N, 2)\).
weights (Tensor) – Tensor containing the weights per point correspondence with a shape of \((B, N)\). Used for the first iteration of the IRWLS.
soft_inl_th (float, optional) – standard deviation, in pixels, of the Gaussian re-weighting kernel given above. Default: 3.0
n_iter (int, optional) – number of solves, including the initial one. Default: 5

Return type:

Tensor

Returns:

the computed homography matrix with shape \((B, 3, 3)\).

kornia.geometry.homography.find_homography_lines_dlt(ls1, ls2, weights=None)[source]#

Compute the homography matrix from line segment correspondences with a DLT formulation.

See [JJC01] for details.

Convention:

H maps image-1 points to image-2 points, as in find_homography_dlt(). Each segment is a [start, end] pair of (x, y) points, and weights has one entry per segment.
Both endpoints of image-1 segment i are constrained to lie, after mapping by H, on the line through image-2 segment i, so the endpoints need not be point correspondences.

Parameters:

ls1 (Tensor) – A set of line segments in the first image with a tensor shape \((B, N, 2, 2)\), or \((N, 2, 2)\), which is treated as \(B = 1\).
ls2 (Tensor) – A set of line segments in the second image with a tensor shape \((B, N, 2, 2)\), or \((N, 2, 2)\), which is treated as \(B = 1\).
weights (Optional[Tensor], optional) – Tensor containing the weights per segment with a shape of \((B, N)\). Zero-weight segments are excluded from Hartley normalization. Default: None

Return type:

Tensor

Returns:

the computed homography matrix with shape \((B, 3, 3)\).

kornia.geometry.homography.find_homography_lines_dlt_iterated(ls1, ls2, weights, soft_inl_th=4.0, n_iter=5)[source]#

Compute the homography matrix using the iteratively-reweighted least squares (IRWLS) from line segments.

Convention:

As find_homography_dlt_iterated(), with find_homography_lines_dlt() as the solver and, as e in the Gaussian kernel, the perpendicular distance in pixels of the mapped image-1 endpoints from the image-2 line. A zero-length image-2 segment gets weight zero.

Parameters:

ls1 (Tensor) – A set of line segments in the first image with a tensor shape \((B, N, 2, 2)\).
ls2 (Tensor) – A set of line segments in the second image with a tensor shape \((B, N, 2, 2)\).
weights (Tensor) – Tensor containing the weights per segment with a shape of \((B, N)\). Used for the first iteration of the IRWLS.
soft_inl_th (float, optional) – standard deviation, in pixels, of the Gaussian re-weighting kernel of find_homography_dlt_iterated(). Default: 4.0
n_iter (int, optional) – number of solves, including the initial one. Default: 5

Return type:

Tensor

Returns:

the computed homography matrix with shape \((B, 3, 3)\).

kornia.geometry.homography.line_segment_transfer_error_one_way(ls1, ls2, H, squared=False)[source]#

Return the mean perpendicular transfer distance in image 2 for line segment correspondences.

Both endpoints of each image-1 segment are mapped into image 2 by H and scored against the line through the matching image-2 segment. See [JJC01] for details.

Convention:

Argument order and direction as oneway_transfer_error().
The image-2 line is scaled to unit \((a, b)\), so the error is the mean perpendicular distance of the two mapped endpoints, in pixels.

Parameters:

ls1 (Tensor) – line segment correspondences from the left images with shape (B, N, 2, 2).
ls2 (Tensor) – line segment correspondences from the right images with shape (B, N, 2, 2).
H (Tensor) – Homographies with shape \((B, 3, 3)\).
squared (bool, optional) – if True (default is False), the squared error is returned. Default: False

Return type:

Tensor

Returns:

the computed error with shape \((B, N)\).

kornia.geometry.homography.oneway_transfer_error(pts1, pts2, H, squared=True, eps=1e-8)[source]#

Return transfer error in image 2 for correspondences given the homography matrix.

Convention:

oneway_transfer_error(pts1, pts2, H) measures in image 2, between H applied to pts1 and pts2.
One set of correspondences scored against several homographies (points with leading dimensions of size 1) is computed from one matrix product for all of them, in at least float32; the result matches the per-homography computation to roundoff.
squared=True, the default here and in symmetric_transfer_error(), returns the squared distance; line_segment_transfer_error_one_way() defaults to squared=False.
The error does not depend on the scale of H, and an exact match scores exactly 0, with a zero gradient, with squared=False. A point that H maps to infinity (\(w' = 0\)) has error inf.

Parameters:

pts1 (Tensor) – correspondences from the left images with shape (B, N, 2 or 3). If they are homogeneous, converted automatically.
pts2 (Tensor) – correspondences from the right images with shape (B, N, 2 or 3). If they are homogeneous, converted automatically.
H (Tensor) – Homographies with shape \((B, 3, 3)\).
squared (bool, optional) – if True (default), the squared distance is returned. Default: True
eps (float, optional) – unused; it was added to the projective denominator and inside the square root, which made the error depend on the scale of H and an exact match score sqrt(eps) (#4881). The singular case is guarded exactly instead. Accepted so that existing calls keep working. Default: 1e-8

Return type:

Tensor

Returns:

the computed distance with shape \((B, N)\).

kornia.geometry.homography.sample_is_valid_for_homography(points1, points2)[source]#

Implement oriented constraint check from [MarquezNLopezABB16].

Analogous to opencv/opencv

Convention:

RANSAC uses it to discard minimal samples for "homography". It checks only that the four triples of the first four points keep their orientation across the two views, so a mirror-image sample is rejected. A triple that is collinear in both views, for instance through a repeated point, counts as kept, so collinearity alone does not reject a sample.

Parameters:

points1 (Tensor) – A set of points in the first image with a tensor shape \((B, N, 2)\); only the first four points are used.
points2 (Tensor) – A set of points in the second image with a tensor shape \((B, N, 2)\); only the first four points are used.

Return type:

Tensor

Returns:

Mask with the minimal sample is good for homography estimation \((B)\).

kornia.geometry.homography.sampson_homography_distance(pts1, pts2, H, squared=True)[source]#

Return the Sampson distance of correspondences to homographies.

The first-order approximation of the geometric error: the squared distance by which pts1 and pts2 together must move for \(x_2 \sim H x_1\) to hold (Hartley and Zisserman, Multiple View Geometry, 2nd ed., section 4.2.6). With \(x_1 = (x, y, 1)\), \(x_2 = (u, v, 1)\) and \(H x_1 = (p, q, w)\), the algebraic residuals \(\epsilon = (v w - q, p - u w)\) and their Jacobian \(J\) with respect to \((x, y, u, v)\) give \(d^2 = \epsilon^\top (J J^\top)^{-1} \epsilon\).

Convention:

Argument order and direction as oneway_transfer_error(): H maps pts1 to pts2. Unlike the one-way transfer error, the distance accounts for noise in both images and does not depend on the scale of H.
For an affine H the constraint is linear in the coordinates, and the distance is the exact geometric error.
An exact correspondence scores 0; a correspondence whose \(J J^\top\) is singular scores inf; a non-finite correspondence or homography gives NaN.
Computed in at least float32 and returned in the promoted dtype of the inputs, or in float32 when they are all integers.

Parameters:

pts1 (Tensor) – points in the first image with shape \((B, N, 2)\), or homogeneous \((B, N, 3)\).
pts2 (Tensor) – points in the second image with shape \((B, N, 2)\), or homogeneous \((B, N, 3)\).
H (Tensor) – homographies with shape \((B, 3, 3)\). Points with a leading dimension of 1 are scored against every homography.
squared (bool, optional) – if True (default), the squared distance is returned, else the distance. Default: True

Return type:

Tensor

Returns:

the computed distance with shape \((B, N)\).

kornia.geometry.homography.symmetric_transfer_error(pts1, pts2, H, squared=True, eps=1e-8)[source]#

Return Symmetric transfer error for correspondences given the homography matrix.

Convention:

Argument order as oneway_transfer_error(). The squared value is the image-2 error of H plus the image-1 error of H^-1, and squared=False returns the square root of that sum.
As oneway_transfer_error(), the error does not depend on the scale of H and an exact match scores exactly 0 with squared=False.

Parameters:

pts1 (Tensor) – correspondences from the left images with shape (B, N, 2 or 3). If they are homogeneous, converted automatically.
pts2 (Tensor) – correspondences from the right images with shape (B, N, 2 or 3). If they are homogeneous, converted automatically.
H (Tensor) – Homographies with shape \((B, 3, 3)\).
squared (bool, optional) – if True (default), the squared distance is returned. Default: True
eps (float, optional) – unused, as in oneway_transfer_error() (#4881). Default: 1e-8

Return type:

Tensor

Returns:

the computed distance with shape \((B, N)\). Rows whose homography is not invertible score max_num, i.e. torch.finfo(pts1.dtype).max, for both values of squared.