skimage2.transform.EssentialMatrixTransform#

class skimage2.transform.EssentialMatrixTransform(*, rotation=None, translation=None, matrix=None, dimensionality=None)[source]#

Bases: FundamentalMatrixTransform

Essential matrix transformation.

The essential matrix relates corresponding points between a pair of calibrated images. The matrix transforms normalized, homogeneous image points in one image to epipolar lines in the other image.

The essential matrix is only defined for a pair of moving images capturing a non-planar scene. In the case of pure rotation or planar scenes, the homography describes the geometric relation between two images (ProjectiveTransform). If the intrinsic calibration of the images is unknown, the fundamental matrix describes the projective relation between the two images (FundamentalMatrixTransform).

Parameters:

rotation(3, 3) array_like, optional: Rotation matrix of the relative camera motion.
translation(3, 1) array_like, optional: Translation vector of the relative camera motion. The vector must have unit length.
matrix(3, 3) array_like, optional: Essential matrix.
dimensionalityint, optional: Fallback number of dimensions when matrix not specified, in which case, must equal 2 (the default).

Attributes:

params(3, 3) array: Essential matrix.

References

[1]

Hartley, Richard, and Andrew Zisserman. Multiple view geometry in computer vision. Cambridge university press, 2003.

Examples

>>> import numpy as np
>>> import _skimage2 as ski2
>>>
>>> tform = ski2.transform.EssentialMatrixTransform(
...     rotation=np.eye(3), translation=np.array([0, 0, 1])
... )
>>> tform.params
array([[ 0., -1.,  0.],
       [ 1.,  0.,  0.],
       [ 0.,  0.,  0.]])
>>> src = np.array([[ 1.839035, 1.924743],
...                 [ 0.543582, 0.375221],
...                 [ 0.47324 , 0.142522],
...                 [ 0.96491 , 0.598376],
...                 [ 0.102388, 0.140092],
...                 [15.994343, 9.622164],
...                 [ 0.285901, 0.430055],
...                 [ 0.09115 , 0.254594]])
>>> dst = np.array([[1.002114, 1.129644],
...                 [1.521742, 1.846002],
...                 [1.084332, 0.275134],
...                 [0.293328, 0.588992],
...                 [0.839509, 0.08729 ],
...                 [1.779735, 1.116857],
...                 [0.878616, 0.602447],
...                 [0.642616, 1.028681]])
>>> tform = ski2.transform.EssentialMatrixTransform.from_estimate(src, dst)
>>> tform.residuals(src, dst)
array([0.42455187, 0.01460448, 0.13847034, 0.12140951, 0.27759346,
       0.32453118, 0.00210776, 0.26512283])

The estimation can fail - for example, if all the input or output points are the same. If this happens, you will get a transform that is not “truthy” - meaning that bool(tform) is False:

>>> # A successfully estimated model is truthy (applying ``bool()``
>>> # gives ``True``):
>>> if tform:
...     print("Estimation succeeded.")
Estimation succeeded.
>>> # Not so for a degenerate transform with identical points.
>>> bad_src = np.ones((8, 2))
>>> bad_tform = ski2.transform.EssentialMatrixTransform.from_estimate(
...      bad_src, dst)
>>> if not bad_tform:
...     print("Estimation failed.")
Estimation failed.

Trying to use this failed estimation transform result will give a suitable error:

>>> bad_tform.params
Traceback (most recent call last):
  ...
FailedEstimationAccessError: No attribute "params" for failed estimation ...

__init__(*, rotation=None, translation=None, matrix=None, dimensionality=None)[source]#

property dimensionality#

estimate(src, dst)[source]#

Estimate essential matrix using 8-point algorithm.

Deprecated since version 0.26: estimate is deprecated since version 0.26 and will be removed in version 2.2. Please use EssentialMatrixTransform.from_estimate class constructor instead.

The 8-point algorithm requires at least 8 corresponding point pairs for a well-conditioned solution, otherwise the over-determined solution is estimated.

Parameters:

srcarray_like of shape (N, 2): Source coordinates.
dstarray_like of shape (N, 2): Destination coordinates.

Returns:

successbool: True, if model estimation succeeds.

classmethod from_estimate(src, dst)[source]#

Estimate essential matrix using 8-point algorithm.

The 8-point algorithm requires at least 8 corresponding point pairs for a well-conditioned solution, otherwise the over-determined solution is estimated.

Parameters:

srcarray_like of shape (N, 2): Source coordinates.
dstarray_like of shape (N, 2): Destination coordinates.

Returns:

tfSelf or FailedEstimation

An instance of the transformation if the estimation succeeded. Otherwise, we return a special FailedEstimation object to signal a failed estimation. Testing the truth value of the failed estimation object will return False. E.g.

tf = EssentialMatrixTransform.from_estimate(...)
if not tf:
    raise RuntimeError(f"Failed estimation: {tf}")

Raises:

ValueError: If src has fewer than 8 rows.

classmethod identity(dimensionality=None)[source]#

Identity transform

Parameters:

dimensionality{None, 2}, optional: This transform only allows dimensionality of 2, where None corresponds to 2. The parameter exists for compatibility with other transforms.

Returns:

tformtransform: Transform such that np.all(tform(pts) == pts).

property inverse#

Return a transform object representing the inverse.

See Hartley & Zisserman, Ch. 8: Epipolar Geometry and the Fundamental Matrix, for an explanation of why F.T gives the inverse.

residuals(src, dst)[source]#

Compute the Sampson distance.

The Sampson distance is the first approximation to the geometric error.

Parameters:

srcndarray of shape (N, 2): Source coordinates.
dstndarray of shape (N, 2): Destination coordinates.

Returns:

residualsndarray of shape (N,): Sampson distance.

scaling = 'rms'#