============================================
Geometrical transformations of images
============================================

Cropping, resizing and rescaling images
---------------------------------------

.. currentmodule:: skimage.transform

Images being NumPy arrays (as described in the :ref:`numpy_images` section), cropping
an image can be done with simple slicing operations. Below we crop a 100x100
square corresponding to the top-left corner of the astronaut image. Note that
this operation is done for all color channels (the color dimension is the last,
third dimension)::

   >>> import skimage as ski
   >>> img = ski.data.astronaut()
   >>> top_left = img[:100, :100]

In order to change the shape of the image, :mod:`skimage.color` provides several
functions described in :ref:`sphx_glr_auto_examples_transform_plot_rescale.py`
.

.. literalinclude:: ../../examples/transform/plot_rescale.py
    :language: python
    :start-after: import matplotlib.pyplot as plt
    :end-before: fig, axes


.. image:: ../auto_examples/transform/images/sphx_glr_plot_rescale_001.png
   :target: ../auto_examples/transform/plot_rescale.html
   :align: center
   :width: 80%

Projective transforms (homographies)
------------------------------------

`Homographies <https://en.wikipedia.org/wiki/Homography>`_
are transformations of a Euclidean space that preserve the alignment of points.
Specific cases of homographies correspond to the conservation of more
properties, such as parallelism (affine transformation), shape (similar
transformation) or distances (Euclidean transformation). The different types
of homographies available in scikit-image are presented in
:ref:`sphx_glr_auto_examples_transform_plot_transform_types.py`.

Projective transformations can either be created using the explicit
parameters (e.g. scale, shear, rotation and translation)::

   import numpy as np
   import skimage as ski

   tform = ski.transform.EuclideanTransform(
      rotation=np.pi / 12.,
      translation = (100, -20)
      )

or the full transformation matrix::

   matrix = np.array([[np.cos(np.pi/12), -np.sin(np.pi/12), 100],
                      [np.sin(np.pi/12), np.cos(np.pi/12), -20],
                      [0, 0, 1]])
   tform = ski.transform.EuclideanTransform(matrix)

The transformation matrix of a transform is available as its ``tform.params``
attribute. Transformations can be composed by multiplying matrices with the
``@`` matrix multiplication operator.

Transformation matrices use
`Homogeneous coordinates <https://en.wikipedia.org/wiki/Homogeneous_coordinates>`_,
which are the extension of Cartesian coordinates used in Euclidean geometry to
the more general projective geometry. In particular, points at infinity can be
represented with finite coordinates.

Transformations can be applied to images using :func:`skimage.transform.warp`::

   img = ski.util.img_as_float(ski.data.chelsea())
   tf_img = ski.transform.warp(img, tform.inverse)

.. image:: ../auto_examples/transform/images/sphx_glr_plot_transform_types_001.png
   :target: ../auto_examples/transform/plot_transform_types.html
   :align: center
   :width: 80%

The different transformations in :mod:`skimage.transform` have a
``from_estimate`` class method in order to generate a matching tranform by
estimating the transform parameters from two sets of points (the source and
the destination), as explained in the
:ref:`sphx_glr_auto_examples_transform_plot_geometric.py` tutorial::

   text = ski.data.text()

   src = np.array([[0, 0], [0, 50], [300, 50], [300, 0]])
   dst = np.array([[155, 15], [65, 40], [260, 130], [360, 95]])

   tform3 = ski.transform.ProjectiveTransform.from_estimate(src, dst)
   warped = ski.transform.warp(text, tform3, output_shape=(50, 300))


.. image:: ../auto_examples/transform/images/sphx_glr_plot_geometric_002.png
   :target: ../auto_examples/transform/plot_geometric.html
   :align: center
   :width: 80%


The ``from_estimate`` class method uses least squares optimization to minimize
the distance between source and optimization. Source and destination points
can be determined manually, or using the different methods for feature
detection available in :mod:`skimage.feature`, such as

 * :ref:`sphx_glr_auto_examples_features_detection_plot_corner.py`,
 * :ref:`sphx_glr_auto_examples_features_detection_plot_orb.py`,
 * :ref:`sphx_glr_auto_examples_features_detection_plot_brief.py`,
 * etc.

and matching points using :func:`skimage.feature.match_descriptors` before
estimating transformation parameters. However, spurious matches are often made,
and it is advisable to use the RANSAC algorithm (instead of simple
least-squares optimization) to improve the robustness to outliers, as explained
in :ref:`sphx_glr_auto_examples_transform_plot_matching.py`.

.. image:: ../auto_examples/transform/images/sphx_glr_plot_matching_001.png
   :target: ../auto_examples/transform/plot_matching.html
   :align: center
   :width: 80%

Examples showing applications of transformation estimation are

 * stereo matching
   :ref:`sphx_glr_auto_examples_transform_plot_fundamental_matrix.py` and
 * image rectification :ref:`sphx_glr_auto_examples_transform_plot_geometric.py`

The ``from_estimate`` class method is point-based, that is, it uses only a set
of points from the source and destination images. For estimating translations
(shifts), it is also possible to use a *full-field* method using all pixels,
based on Fourier-space cross-correlation. This method is implemented by
:func:`skimage.registration.phase_cross_correlation` and explained in the
:ref:`sphx_glr_auto_examples_registration_plot_register_translation.py`
tutorial.

.. image:: ../auto_examples/registration/images/sphx_glr_plot_register_translation_001.png
   :target: ../auto_examples/registration/plot_register_translation.html
   :align: center
   :width: 80%

Bear in mind that the estimation can fail, in which case ``from_estimate``
returns a special ``FailedEstimation`` object instead of a valid transform.
See the :ref:`sphx_glr_auto_examples_transform_plot_geometric.py` tutorial for
more detail on testing for such estimation failures.

The
:ref:`sphx_glr_auto_examples_registration_plot_register_rotation.py` tutorial
explains a variant of this full-field method for estimating a rotation, by
using first a log-polar transformation.
