skimage2.transform.FundamentalMatrixTransform#

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

Bases: _HMatrixTransform

Fundamental matrix transformation.

The fundamental matrix relates corresponding points between a pair of uncalibrated images. The matrix transforms homogeneous image points in one image to epipolar lines in the other image.

The fundamental matrix is only defined for a pair of moving images. 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 known, the essential matrix describes the metric relation between the two images (EssentialMatrixTransform).

Parameters:

matrix(3, 3) array_like, optional: Fundamental matrix.
dimensionalityint, optional: Fallback number of dimensions when matrix not specified, in which case, must equal 2 (the default).

Attributes:

params(3, 3) array: Fundamental matrix.

Notes

See [1] and [2] for details of the estimation procedure. [2] is a good place to start.

References

[1]

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

[2] (1,2)

Zhang, Zhengyou. “Determining the epipolar geometry and its uncertainty: A review.” International journal of computer vision 27 (1998): 161-195. DOI:10.1023/A:1007941100561 https://www.microsoft.com/en-us/research/wp-content/uploads/2016/11/RR-2927.pdf

Examples

>>> import numpy as np
>>> import _skimage2 as ski2

Define source and destination points:

>>> src = np.array([1.839035, 1.924743,
...                 0.543582, 0.375221,
...                 0.473240, 0.142522,
...                 0.964910, 0.598376,
...                 0.102388, 0.140092,
...                15.994343, 9.622164,
...                 0.285901, 0.430055,
...                 0.091150, 0.254594]).reshape(-1, 2)
>>> dst = np.array([1.002114, 1.129644,
...                 1.521742, 1.846002,
...                 1.084332, 0.275134,
...                 0.293328, 0.588992,
...                 0.839509, 0.087290,
...                 1.779735, 1.116857,
...                 0.878616, 0.602447,
...                 0.642616, 1.028681]).reshape(-1, 2)

Estimate the transformation matrix:

>>> tform = ski2.transform.FundamentalMatrixTransform.from_estimate(
...      src, dst)
>>> tform.params
array([[-0.21785884,  0.41928191, -0.03430748],
       [-0.07179414,  0.04516432,  0.02160726],
       [ 0.24806211, -0.42947814,  0.02210191]])

Compute the Sampson distance:

>>> tform.residuals(src, dst)
array([0.0053886 , 0.00526101, 0.08689701, 0.01850534, 0.09418259,
       0.00185967, 0.06160489, 0.02655136])

Apply inverse transformation:

>>> tform.inverse(dst)
array([[-0.0513591 ,  0.04170974,  0.01213043],
       [-0.21599496,  0.29193419,  0.00978184],
       [-0.0079222 ,  0.03758889, -0.00915389],
       [ 0.14187184, -0.27988959,  0.02476507],
       [ 0.05890075, -0.07354481, -0.00481342],
       [-0.21985267,  0.36717464, -0.01482408],
       [ 0.01339569, -0.03388123,  0.00497605],
       [ 0.03420927, -0.1135812 ,  0.02228236]])

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.FundamentalMatrixTransform.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__(matrix=None, *, dimensionality=None)[source]#

property dimensionality#

estimate(src, dst)[source]#

Estimate fundamental 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 FundamentalMatrixTransform.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 fundamental matrix using 8-point algorithm.

The 8-point algorithm requires at least 8 corresponding point pairs.

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 = FundamentalMatrixTransform.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'#