skimage2.transform.EuclideanTransform#

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

Bases: ProjectiveTransform

Euclidean transformation, also known as a rigid transform.

In what follows, x refers to coordinates from the first coordinate axis, and y refers to coordinates from the second coordinate axis.

The transform has the following form:

X = a0 * x - b0 * y + a1 =
  = x * cos(rotation) - y * sin(rotation) + a1

Y = b0 * x + a0 * y + b1 =
  = x * sin(rotation) + y * cos(rotation) + b1

where the homogeneous transformation matrix is:

[[a0 -b0  a1]
 [b0  a0  b1]
 [0   0   1 ]]

The Euclidean transformation is a rigid transformation with rotation and translation parameters. The similarity transformation extends the Euclidean transformation with a single scaling factor.

In 2D and 3D, the transformation parameters may be provided either via matrix, the homogeneous transformation matrix, above, or via the implicit parameters rotation and/or translation (where a1 is the translation along x, b1 along y, etc.). Beyond 3D, if the transformation is only a translation, you may use the implicit parameter translation; otherwise, you must use matrix.

The implicit parameters are applied in the following order:

Rotation
Translation

Parameters:

matrixarray_like of shape (K, K), with K=D+1 (D being the dimensionality), optional: Homogeneous transformation matrix.
rotationfloat or sequence of float, optional: Rotation angle, in radians. See Notes for discussion of clockwise vs anti-clockwise. If given as a vector, it is interpreted as Euler rotation angles [1]. Only 2D (single rotation) and 3D (Euler rotations) values are supported. For higher dimensions, you must provide or estimate the transformation matrix instead, and pass that as matrix above.
translation(x, y[, z, …]) sequence of float, length D, optional: Translation parameters for each axis.
dimensionalityint, optional: Fallback number of dimensions for transform when no other parameter is specified. Otherwise ignored, and we infer dimensionality from the input parameters.

Attributes:

paramsndarray of shape (K, K), with K=D+1 (D being the dimensionality): Homogeneous transformation matrix.

Notes

Our axis convention will change from Scikit-image 1 to 2, and this changes the direction of (positive) rotation. In functions applying transformations, in the skimage2 namespace, we use the NumPy or “ij” convention, where the first and second axis of the image correspond to the first and second axis of the array (row, column). Correspondingly, a positive rotation is counter-clockwise. In scikit-image 1 (the skimage namespace), we used the “xy” convention, where the first axis is columns and the second rows. Correspondingly, positive rotation is clockwise.

Note, therefore, that if you apply a transform using warp, or other functions that apply transforms in skimage2, you will get an opposite direction rotation from the same function in the skimage.transform module.

References

[1]

https://en.wikipedia.org/wiki/Rotation_matrix#In_three_dimensions

Examples

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

Define a transform with an homogeneous transformation matrix:

>>> tform = ski2.transform.EuclideanTransform(np.diag([2., 3., 1.]))
>>> tform.params
array([[2., 0., 0.],
       [0., 3., 0.],
       [0., 0., 1.]])

Define a transform with parameters:

>>> tform = ski2.transform.EuclideanTransform(
...             rotation=0.2, translation=[1, 2])
>>> np.round(tform.params, 2)
array([[ 0.98, -0.2 ,  1.  ],
       [ 0.2 ,  0.98,  2.  ],
       [ 0.  ,  0.  ,  1.  ]])

You can estimate a transformation to map between source and destination points:

>>> src = np.array([[150, 150],
...                 [250, 100],
...                 [150, 200]])
>>> dst = np.array([[200, 200],
...                 [300, 150],
...                 [150, 400]])
>>> tform = ski2.transform.EuclideanTransform.from_estimate(src, dst)
>>> np.allclose(tform.params, [[ 0.99, 0.12,  16.77],
...                            [-0.12, 0.99, 122.91],
...                            [ 0.  , 0.  ,   1.  ]], atol=0.01)
True

Apply the transformation to some image data.

>>> img = ski2.data.astronaut()
>>> warped = ski2.transform.warp(img, inverse_map=tform.inverse)

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((3, 2))
>>> bad_tform = ski2.transform.EuclideanTransform.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, *, rotation=None, translation=None, dimensionality=None)[source]#

property dimensionality#: The dimensionality of the transformation.

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 EuclideanTransform.from_estimate class constructor instead.

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:

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) → Self | FailedEstimation[source]#

Estimate the transformation from a set of corresponding points.

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:

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 = EuclideanTransform.from_estimate(...)
if not tf:
    raise RuntimeError(f"Failed estimation: {tf}")

classmethod identity(dimensionality=None)[source]#

Identity transform

Parameters:

dimensionality{None, int}, optional: Dimensionality of identity transform.

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.

property rotation#

scaling = 'rms'#

property translation#