`skimage.transform._geometric:estimate_transform`

source: /_skimage2/transform/_geometric.py:2564

Signature

def estimate_transform(ttype, src, dst, *args, **kwargs)

Summary

Estimate 2D geometric transformation parameters.

Extended Summary

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.

kwargs : array_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 : :class:`_GeometricTransform` or :class:`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 skimage as ski

✓

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

✓

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

✓

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

✓

True

image = ski.data.camera()

✓

tform2 = ski.transform.SimilarityTransform(scale=1.1, rotation=1,
    translation=(10, 20))

✓

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``:

if tform:
    print("Estimation succeeded.")
bad_src = np.ones((2, 2))
bad_tform = ski.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  # doctest: +IGNORE_EXCEPTION_DETAIL

✓

Traceback (most recent call last):
  File "<doctest skimage.transform._geometric:estimate_transform[0]>", line 1, in <module>
    bad_tform.params  # doctest: +IGNORE_EXCEPTION_DETAIL
    ^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.14.7/x64/lib/python3.14/site-packages/_skimage2/_shared/utils.py", line 546, in __getattr__
    raise self.error_cls(msg)
_skimage2._shared.utils.FailedEstimationAccessError: FailedEstimation has no attribute 'params'. SimilarityTransform: Poor conditioning for estimation

Hint: You can check for a failed estimation by truth testing the returned object. For failed estimations, `bool(estimation_result)` will be `False`. E.g.

    if not estimation_result:
        raise RuntimeError(f'Failed estimation: {estimation_result}')

Aliases

skimage.transform.estimate_transform