skimage2.transform.PiecewiseAffineTransform#

class skimage2.transform.PiecewiseAffineTransform[source]#

Bases: _GeometricTransform

Piecewise affine transformation.

Control points are used to define the mapping. The transform is based on a Delaunay triangulation of the points to form a mesh. Each triangle is used to find a local affine transform.

Attributes:

affineslist of AffineTransform objects: Affine transformations for each triangle in the mesh.
inverse_affineslist of AffineTransform objects: Inverse affine transformations for each triangle in the mesh.

Examples

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

Define a transformation by estimation:

>>> src = [[-12.3705, -10.5075],
...        [-10.7865, 15.4305],
...        [8.6985, 10.8675],
...        [11.4975, -9.5715],
...        [7.8435, 7.4835],
...        [-5.3325, 6.5025],
...        [6.7905, -6.3765],
...        [-6.1695, -0.8235]]
>>> dst = [[0, 0],
...        [0, 5800],
...        [4900, 5800],
...        [4900, 0],
...        [4479, 4580],
...        [1176, 3660],
...        [3754, 790],
...        [1024, 1931]]
>>> tform = ski2.transform.PiecewiseAffineTransform.from_estimate(src, dst)

Calling the transform applies the transformation to the points:

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

You can apply the inverse transform:

>>> np.allclose(tform.inverse(dst), 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 = [[1, 1]] * 6 + src[6:]
>>> bad_tform = ski2.transform.PiecewiseAffineTransform.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__()[source]#

estimate(src, dst)[source]#

Estimate the transformation from a set of corresponding points.

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

Number of source and destination coordinates must match.

Parameters:

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

Returns:

successbool: True, if all pieces of the model are successfully estimated.

classmethod from_estimate(src, dst)[source]#

Estimate the transformation from a set of corresponding points.

Number of source and destination coordinates must match.

Parameters:

src(N, D) array_like: Source coordinates.
dst(N, D) array_like: 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 = PiecewiseAffineTransform.from_estimate(...)
if not tf:
    raise RuntimeError(f"Failed estimation: {tf}")

classmethod identity(dimensionality=None)[source]#

Identity transform

Parameters:

dimensionalityoptional: This transform does not use the dimensionality parameter, so the value is ignored. 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.

residuals(src, dst)[source]#

Determine residuals of transformed destination coordinates.

For each transformed source coordinate the Euclidean distance to the respective destination coordinate is determined.

Parameters:

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

Returns:

residualsndarray of shape (N,): Residual for coordinate.