kornia.geometry.homography

Module with useful functionalities for homographies manipulation.

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

Compute the homography matrix using the DLT formulation.

The linear system is solved by using the Weighted Least Squares Solution for the 4 Points algorithm.

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)\). 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)

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

The linear system is solved by using the Reweighted Least Squares Solution for the 4 Points algorithm.

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) – Soft inlier threshold used for weight calculation. Default: 3.0

  • n_iter (int, optional) – number of iterations. 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)

Compute the homography matrix using the DLT formulation for line correspondences.

See [JJC01] for details.

The linear system is solved by using the Weighted Least Squares Solution for the 4 Line correspondences algorithm.

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 (Optional[Tensor], optional) – Tensor containing the weights per point correspondence with a shape of \((B, N)\). 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)

Compute the homography matrix using the iteratively-reweighted least squares (IRWLS) from line segments. The linear system is solved by using the Reweighted Least Squares Solution for the 4 line segments algorithm.

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 point correspondence with a shape of \((B, N)\). Used for the first iteration of the IRWLS.

  • soft_inl_th (float, optional) – Soft inlier threshold used for weight calculation. Default: 4.0

  • n_iter (int, optional) – number of iterations. 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)

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

Line segment end points are reprojected into image 2, and point-to-line error is calculated w.r.t. line, induced by line segment in image 2. See [JJC01] for details.

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 distance is returned. Default: False

Return type:

Tensor

Returns:

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

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

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

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) – Small constant for safe sqrt. Default: 1e-8

Return type:

Tensor

Returns:

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

kornia.geometry.homography.sample_is_valid_for_homography(points1, points2)

Function, which implements oriented constraint check from [MarquezNLopezABB16].

Analogous to https://github.com/opencv/opencv/blob/4.x/modules/calib3d/src/usac/degeneracy.cpp#L88

Parameters:
  • points1 (Tensor) – A set of points in the first image with a tensor shape \((B, 4, 2)\).

  • points2 (Tensor) – A set of points in the second image with a tensor shape \((B, 4, 2)\).

Return type:

Tensor

Returns:

Mask with the minimal sample is good for homography estimation:math:(B, 3, 3).

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

Return Symmetric transfer error for correspondences given the homography matrix.

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) – Small constant for safe sqrt. Default: 1e-8

Return type:

Tensor

Returns:

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

Interactive Demo