compute_homography_transform#

movement.transforms.compute_homography_transform(src_points, dst_points)[source]#

Compute a homography transformation matrix.

Parameters:

  • src_points (np.ndarray) – An array of shape (N, 2) representing N source points in 2-dimensional space. N >= 4.

  • dst_points (np.ndarray) – An array of shape (N, 2) representing N destination points in 2-dimensional space. N >= 4.

Returns:

A (3, 3) transformation matrix that aligns the source points to the destination points.

Return type:

np.ndarray

Raises:

ValueError – If the number of source points does not match the number of destination points, or if there are insufficient points to compute the transformation, or if the points are not 2-dimensional, or if the points are degenerate or collinear, making it impossible to compute a valid homography.

Notes

This function estimates a 3x3 homography matrix using corresponding 2D point pairs from two images or planes. A homography describes a projective transformation suitable for planar scenes where perspective effects are present — e.g., when the camera is tilted, moved closer, or rotated relative to the plane.

The transformation preserves straight lines but not necessarily parallelism or distances, making it ideal for:

  • Image rectification

  • Perspective warping

  • Planar object tracking

Important considerations:

  • At least 4 non-collinear, non-degenerate points are required to compute a valid homography transformation.

  • The function internally filters invalid point pairs.

  • The computed homography is most accurate for planar scenes with perspective distortion, where the transformation can be modeled as a projective mapping.

Examples

>>> src = np.array([[0, 0], [1, 0], [1, 1], [0, 1]], dtype=np.float32)
>>> dst = np.array([[0, 0], [2, 0], [2, 2], [0, 2]], dtype=np.float32)
>>> H = compute_homography_transform(src, dst)
>>> print(H.shape)
(3, 3)