Homography package for Python

A 2D homography from \(\left(\begin{smallmatrix}x \\ y\end{smallmatrix}\right)\) to \(\left(\begin{smallmatrix}x' \\ y'\end{smallmatrix}\right)\) can be represented by 8 parameters \((a,b,\ldots h)\), organized in a 3x3 matrix. The transformation rule is as follows:

\[\begin{split}\begin{pmatrix} x_0 \\ y_0 \\ z_0 \end{pmatrix} &= \begin{pmatrix} a & b & c \\ d & e & f \\ g & h & 1 \end{pmatrix} \begin{pmatrix} x \\ y \\ 1 \end{pmatrix} \\ \begin{pmatrix} x' \\ y' \end{pmatrix} &= \frac{1}{z_0} \begin{pmatrix} x_0 \\ y_0 \end{pmatrix}\end{split}\]

homography module

library for 2d homographies.

The Homography object represents a 2D homography as a 3x3 matrix. Homographies can be applied directly on numpy arrays or Shapely points using the “call operator” (brackets), composed using * and inverted using ~.

This module supports basic operations, conversion methods and utilities. Sample usage:

>>> h = Homography.translation(5, -1) * Homography.rotation(90)
>>> h.as_ndarray().astype(int)
array([[ 0,  1,  5],
       [-1,  0, -1],
       [ 0,  0,  1]])

>>> print(h([[0, 0],[1, 0],[1 ,1]]))
[[ 5. -1.]
 [ 5. -2.]
 [ 6. -2.]]

>>> print(~h*h)
[[1. 0. 0.]
 [0. 1. 0.]
 [0. 0. 1.]]
>>> print((~h)(h([12, 34])))
[12. 34.]

class homography.Homography(other=None)

The 3x3 homography transformation matrix contains 8 free parameters and represents transfromation from \((x,y)\) to \((x',y')\) as follows:

  | x0 |   | a  b  c | | x |
  | y0 | = | d  e  f | | y |
  | z0 |   | g  h  1 | | 1 |

x' = x0 / z0
y' = y0 / z0

__init__(other=None)

Constructs itself from Homography, Affine or 3x3 mat. The default constuctor returns the identity homography.

classmethod identity()

classmethod translation(x, y)

classmethod scale(x, y=None)

classmethod rotation(angle_deg)

classmethod from_affine(aff)

Parameters

aff (affine.Affine) – the affine to convert from

Return type

Homography

classmethod from_dict(d)

to_affine()

Ignores projective part.

to_dict()

projectivity()

Rough approximation of how non-affine is the homography.

apply(x, y, z=1)

Direct multiplication with H, returns 3-vector. deprecated? consider using __call__()

__eq__(other)

Return self==value.

equal(other, eps=1e-06)

norm(width=1, height=1)

Homography norm in pix, estimated on image with given width, height.

dist_sourcespace(other, width=1, height=1)

Distance between homographies in source space, estimated on output image with given width, height.

dist(other, width=1, height=1)

Distance between homographies in output space, estimated on image with given width, height.

dist_bidirectional(other, width=1, height=1)

Distance between homographies as max between distance in source and image space. Estimated on image with given width, height.

rel_dist(other, width=1, height=1)

Distance between homographies, estimated on image with given size, and normalized by the diagonal length.

get_shift_at_point(point)

Calculates the shift applied to the specified point when the homography is applied. Input point can be a 1D 2 element numpy array or a Shapely point

>>> print(Homography.scale(3).get_shift_at_point([1, -2]))
[ 2. -4.]

as_ndarray()

__getitem__(key)

Returns submatrix, e.g.:

>>> print(Homography.identity()[2, 1:])
[0. 1.]

__invert__()

__module__ = 'homography'

__mul__(other)

__weakref__

list of weak references to the object (if defined)

__call__(point)

Call self as a function.

homography.from_points(src, dst)

Find homography that transforms four source points ‘src’ to destination points ‘dst’. Both specified as 4x2 arrays, or lists of 4 shapely Point objects