skimage2.transform.estimate_transform

skimage2.transform.estimate_transform(ttype, src, dst, *args, **kwargs)

Estimate 2D geometric transformation parameters.

You can determine the over-, well- and under-determined parameters with the total least-squares method.

Number of source and destination coordinates must match.

Parameters:

ttype{‘euclidean’, similarity’, ‘affine’, ‘piecewise-affine’, ‘projective’, ‘polynomial’}

Type of transform.

kwargsarray_like or int

Function parameters (src, dst, n, angle):

NAME / TTYPE        FUNCTION PARAMETERS
'euclidean'         `src, `dst`
'similarity'        `src, `dst`
'affine'            `src, `dst`
'piecewise-affine'  `src, `dst`
'projective'        `src, `dst`
'polynomial'        `src, `dst`, `order` (polynomial order,
                                          default order is 2)

Also see examples below.

Returns:

tf_GeometricTransform or FailedEstimation

An instance of the requested transformation if the estimation 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 = estimate_transform(...)
if not tf:
    raise RuntimeError(f"Failed estimation: {tf}")

Examples

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

>>> # estimate transformation parameters
>>> src = np.array([0, 0, 10, 10]).reshape((2, 2))
>>> dst = np.array([12, 14, 1, -20]).reshape((2, 2))

>>> tform = ski2.transform.estimate_transform('similarity', src, dst)

>>> np.allclose(tform.inverse(tform(src)), src)
True

>>> # warp image using the estimated transformation
>>> image = ski2.data.camera()

>>> ski2.transform.warp(image, inverse_map=tform.inverse)

>>> # create transformation with explicit parameters
>>> tform2 = ski2.transform.SimilarityTransform(scale=1.1, rotation=1,
...     translation=(10, 20))

>>> # unite transformations, applied in order from left to right
>>> tform3 = tform + tform2
>>> np.allclose(tform3(src), tform2(tform(src)))
True

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((2, 2))
>>> bad_tform = ski2.transform.estimate_transform('similarity',
...                                              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 ...