warp(image, inverse_map, map_args={}, output_shape=None, order=None, mode='constant', cval=0.0, clip=True, preserve_range=False)

Notes

• The input image is converted to a double image.

• In case of a SimilarityTransform , AffineTransform and ProjectiveTransform and :None:None:`order` in [0, 3] this function uses the underlying transformation matrix to warp the image with a much faster routine.

Parameters

image : ndarray

Input image.

inverse_map : transformation object, callable ``cr = f(cr, **kwargs)``, or ndarray

Inverse coordinate map, which transforms coordinates in the output images into their corresponding coordinates in the input image.

There are a number of different options to define this map, depending on the dimensionality of the input image. A 2-D image can have 2 dimensions for gray-scale images, or 3 dimensions with color information.

• For 2-D images, you can directly pass a transformation object, e.g. skimage.transform.SimilarityTransform , or its inverse.

• For 2-D images, you can pass a (3, 3) homogeneous transformation matrix, e.g. :None:None:`skimage.transform.SimilarityTransform.params`.

• For 2-D images, a function that transforms a (M, 2) array of (col, row) coordinates in the output image to their corresponding coordinates in the input image. Extra parameters to the function can be specified through :None:None:`map_args`.

• For N-D images, you can directly pass an array of coordinates. The first dimension specifies the coordinates in the input image, while the subsequent dimensions determine the position in the output image. E.g. in case of 2-D images, you need to pass an array of shape (2, rows, cols) , where rows and :None:None:`cols` determine the shape of the output image, and the first dimension contains the (row, col) coordinate in the input image. See scipy.ndimage.map_coordinates for further documentation.

Note, that a (3, 3) matrix is interpreted as a homogeneous transformation matrix, so you cannot interpolate values from a 3-D input, if the output is of shape (3,) .

See example section for usage.

map_args : dict, optional

Keyword arguments passed to :None:None:`inverse_map`.

output_shape : tuple (rows, cols), optional

Shape of the output image generated. By default the shape of the input image is preserved. Note that, even for multi-band images, only rows and columns need to be specified.

order : int, optional

The order of interpolation. The order has to be in the range 0-5:

• 0: Nearest-neighbor

• 1: Bi-linear (default)

• 2: Bi-quadratic

• 3: Bi-cubic

• 4: Bi-quartic

• 5: Bi-quintic

Default is 0 if image.dtype is bool and 1 otherwise.

mode : {'constant', 'edge', 'symmetric', 'reflect', 'wrap'}, optional

Points outside the boundaries of the input are filled according to the given mode. Modes match the behaviour of numpy.pad .

cval : float, optional

Used in conjunction with mode 'constant', the value outside the image boundaries.

clip : bool, optional

Whether to clip the output to the range of values of the input image. This is enabled by default, since higher order interpolation may produce values outside the given input range.

preserve_range : bool, optional

Whether to keep the original range of values. Otherwise, the input image is converted according to the conventions of img_as_float . Also see https://scikit-image.org/docs/dev/user_guide/data_types.html

Returns

warped : double ndarray

The warped input image.

Warp an image according to a given coordinate transformation.

Examples

This example is valid syntax, but we were not able to check execution

>>> from skimage.transform import warp
... from skimage import data
... image = data.camera()

The following image warps are all equal but differ substantially in execution time. The image is shifted to the bottom.

Use a geometric transform to warp an image (fast):

This example is valid syntax, but we were not able to check execution

>>> from skimage.transform import SimilarityTransform
... tform = SimilarityTransform(translation=(0, -10))
... warped = warp(image, tform)

Use a callable (slow):

This example is valid syntax, but we were not able to check execution

>>> def shift_down(xy):
...     xy[:, 1] -= 10
...     return xy
... warped = warp(image, shift_down)

Use a transformation matrix to warp an image (fast):

This example is valid syntax, but we were not able to check execution

>>> matrix = np.array([[1, 0, 0], [0, 1, -10], [0, 0, 1]])
... warped = warp(image, matrix)
... from skimage.transform import ProjectiveTransform
... warped = warp(image, ProjectiveTransform(matrix=matrix))

You can also use the inverse of a geometric transformation (fast):

This example is valid syntax, but we were not able to check execution

>>> warped = warp(image, tform.inverse)

For N-D images you can pass a coordinate array, that specifies the coordinates in the input image for every element in the output image. E.g. if you want to rescale a 3-D cube, you can do:

This example is valid syntax, but we were not able to check execution

>>> cube_shape = np.array([30, 30, 30])
... cube = np.random.rand(*cube_shape)

Setup the coordinate array, that defines the scaling:

This example is valid syntax, but we were not able to check execution

>>> scale = 0.1
... output_shape = (scale * cube_shape).astype(int)
... coords0, coords1, coords2 = np.mgrid[:output_shape[0],
...                    :output_shape[1], :output_shape[2]]
... coords = np.array([coords0, coords1, coords2])

Assume that the cube contains spatial data, where the first array element center is at coordinate (0.5, 0.5, 0.5) in real space, i.e. we have to account for this extra offset when scaling the image:

This example is valid syntax, but we were not able to check execution

>>> coords = (coords + 0.5) / scale - 0.5
... warped = warp(cube, coords)

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

skimage.transform._warps.swirl skimage.transform.pyramids.pyramid_gaussian skimage._shared.utils._validate_interpolation_order skimage.transform.pyramids.pyramid_expand skimage.filters._window.window skimage.transform._warps.rotate skimage.transform._warps._clip_warp_output skimage.transform._warps.resize skimage.measure.profile.profile_line skimage.transform._warps.warp skimage.transform.pyramids.pyramid_reduce skimage.transform._warps.warp_coords skimage.transform.pyramids.pyramid_laplacian skimage.transform._warps.rescale

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: /skimage/transform/_warps.py#684
type: <class 'function'>
Commit: