imwarp

Apply geometric transformation to image

Syntax

B = imwarp(A,tform)

B = imwarp(A,D)

[B,RB] =
imwarp(A,RA,tform)

[___] = imwarp(___,interp)

[___] =
imwarp(___,Name=Value)

Description

B = imwarp(A,tform) transforms the numeric, logical, or categorical image A according to the geometric transformation tform. The function returns the transformed image in B.

example

B = imwarp(A,D) transforms image A according to the displacement field D.

[B,RB] = imwarp(A,RA,tform) transforms a spatially referenced image specified by the image data A and its associated spatial referencing object RA. The outputs are a spatially referenced image specified by the image data B and its associated spatial referencing object RB.

[___] = imwarp(___,interp) specifies the type of interpolation to use.

[___] = imwarp(___,Name=Value) specifies name-value arguments to control various aspects of the geometric transformation.

Tip

If the input transformation tform does not define a forward transform, then use the OutputView name-value argument to accelerate the transformation.

example

Examples

collapse all

Apply Horizontal Shear to Image

Open Live Script

Read and display a grayscale image.

I = imread('cameraman.tif');
imshow(I)

Figure contains an axes object. The hidden axes object contains an object of type image.

Create a 2-D affine transformation.

A = [1 0.5 0; 0 1 0; 0 0 1];
tform = affinetform2d(A);

Apply the transformation to the image.

J = imwarp(I,tform);
imshow(J)

Figure contains an axes object. The hidden axes object contains an object of type image.

Apply Rotation Transformation to 3-D MRI Data

Open Live Script

Load and display a 3-D MRI volumetric image.

load("mri");
mriVolume = squeeze(D);
volshow(mriVolume);

Create a 3-D rigid transformation object that rotates the image around the y-axis.

theta = [0 22.5 0];
transl = [0 0 0];
tform = rigidtform3d(theta,transl);

Apply the transformation to the image and display the result.

mriVolumeRotated = imwarp(mriVolume,tform);
volshow(mriVolumeRotated);

Warp Image Using Different Output View Styles

Open Live Script

Read and display an image. To see the spatial extents of the image, make the axes visible.

A = imread("kobi.png");
A = imresize(A,0.25);
iptsetpref("ImshowAxesVisible","on")
imshow(A)

Figure contains an axes object. The axes object contains an object of type image.

Create a 2-D affine transformation. This example creates a randomized transformation that consists of scale by a factor in the range [1.2, 2.4], rotation by an angle in the range [-45, 45] degrees, and horizontal translation by a distance in the range [100, 200] pixels.

tform = randomAffine2d("Scale",[1.2,2.4],"XTranslation",[100 200],"Rotation",[-45,45]);

Create three different output views for the image and transformation.

centerOutput = affineOutputView(size(A),tform,"BoundsStyle","CenterOutput");
followOutput = affineOutputView(size(A),tform,"BoundsStyle","FollowOutput");
sameAsInput = affineOutputView(size(A),tform,"BoundsStyle","SameAsInput");

Apply the transformation to the input image using each of the different output view styles.

BCenterOutput = imwarp(A,tform,"OutputView",centerOutput);
BFollowOutput = imwarp(A,tform,"OutputView",followOutput);
BSameAsInput = imwarp(A,tform,"OutputView",sameAsInput);

Display the resulting images.

imshow(BCenterOutput)
title("CenterOutput Bounds Style");

Figure contains an axes object. The axes object with title CenterOutput Bounds Style contains an object of type image.

imshow(BFollowOutput)
title("FollowOutput Bounds Style");

Figure contains an axes object. The axes object with title FollowOutput Bounds Style contains an object of type image.

imshow(BSameAsInput)
title("SameAsInput Bounds Style");

Figure contains an axes object. The axes object with title SameAsInput Bounds Style contains an object of type image.

iptsetpref("ImshowAxesVisible","off")

Input Arguments

collapse all

`A` — Image to be transformed
numeric array | logical array | categorical array

Image to be transformed, specified as a numeric, logical, or categorical array of any dimension.

`tform` — Geometric transformation
geometric transformation object

Geometric transformation, specified as a geometric transformation object listed in the table.

Geometric Transformation Object	Description
2-D Linear Geometric Transformations
`transltform2d`	Translation transformation
`rigidtform2d`	Rigid transformation: translation and rotation
`simtform2d`	Similarity transformation: translation, rotation, and isotropic scaling
`affinetform2d`	Affine transformation: translation, rotation, anisotropic scaling, reflection, and shearing
`projtform2d`	Projective transformation
3-D Linear Geometric Transformations
`transltform3d`	Translation transformation
`rigidtform3d`	Rigid transformation: translation and rotation
`simtform3d`	Similarity transformation: translation, rotation, and isotropic scaling
`affinetform3d`	Affine transformation: translation, rotation, anisotropic scaling, reflection, and shearing
Nonlinear Geometric Transformations
`geometricTransform2d`	2-D geometric transformation
`geometricTransform3d`	3-D geometric transformation
`PolynomialTransformation2D`	Polynomial transformation
`PiecewiseLinearTransformation2D`	Piecewise linear transformation
`LocalWeightedMeanTransformation2D`	Local weighted mean transformation

If tform is 2-D and A has more than two dimensions, such as for an RGB image, then imwarp applies the same 2-D transformation to all 2-D planes along the higher dimensions.
If tform is 3-D, then A must be a 3-D image volume.

Note

You can also specify tform as an object of type rigid2d, rigid3d, affine2d, affine3d, or projective2d. However, these objects are not recommended. For more information, see Version History.

`D` — Displacement field
numeric array

Displacement field, specified as numeric array. The displacement field defines the grid size and location of the output image. Displacement values are in units of pixels. imwarp assumes that D is referenced to the default intrinsic coordinate system. To estimate the displacement field, use imregdemons.

If A is a 2-D grayscale image of size m-by-n, then specify the displacement field as an m-by-n-by-2 array. D(:,:,1) contains displacements along the x-axis. imwarp adds these values to column and row locations in D to produce remapped locations in A. Similarly, D(:,:,2) contains displacements along the y-axis.
If A is a 2-D RGB or multispectral image of size m-by-n-by-c and you specify D as an m-by-n-by-2 array, then imwarp operates on each 2-D color channel independently. D(:,:,1) contains displacements along the x-axis for all of the color channels. Similarly, D(:,:,2) contains displacements along the y-axis.
If A is a 3-D grayscale image of size m-by-n-by-p, then specify the displacement field array as an m-by-n-by-p-by-3 array. D(:,:,:,1) contains displacements along the x-axis. imwarp adds these values to column, row, and depth locations in D to produce remapped locations in A. Similarly, D(:,:,:,2) and D(:,:,:,3) contain displacements along the y- and z-axis.

`RA` — Spatial referencing information of image to be transformed
`imref2d` object | `imref3d` object

Spatial referencing information of the image to be transformed, specified as an imref2d object for a 2-D transformation or an imref3d object for a 3-D transformation.

`interp` — Type of interpolation used
`"nearest"` | `"linear"` | `"cubic"`

Type of interpolation used, specified as one of these values.

Interpolation Method Description

Interpolation Method	Description
`"nearest"`	Nearest-neighbor interpolation. The output pixel is assigned the value of the pixel that the point falls within. No other pixels are considered. Nearest-neighbor interpolation is the only method supported for categorical images and it is the default method for images of this type.
`"linear"`	Linear interpolation. Linear interpolation is the default interpolation method for numeric and logical images.
`"cubic"`	Cubic interpolation

"nearest"

Nearest-neighbor interpolation. The output pixel is assigned the value of the pixel that the point falls within. No other pixels are considered.

Nearest-neighbor interpolation is the only method supported for categorical images and it is the default method for images of this type.

"linear" Linear interpolation. Linear interpolation is the default interpolation method for numeric and logical images.

"cubic" Cubic interpolation

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: B = imwarp(A,tform,FillValues=255) uses a fill value of 255

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: B = imwarp(A,tform,"FillValues",255) uses a fill value of 255

`OutputView` — Size and location of output image
`imref2d` object | `imref3d` object

Size and location of output image in the world coordinate system, specified as an imref2d or imref3d spatial referencing object. The object has properties that define the size of the output image and the location of the output image in the world coordinate system.

You can create an output view by using the affineOutputView function. To replicate the default output view calculated by imwarp, use the default bounds style ("CenterOutput") of affineOutputView.

You cannot specify OutputView when you specify an input displacement field D.

`FillValues` — Fill value
numeric scalar | numeric array | string scalar | character vector | `missing`

Fill values used for output pixels outside the input image, specified as one of the values in the table. imwarp uses fill values for output pixels when the corresponding inverse transformed location in the input image is completely outside the input image boundaries.

The default fill value of numeric and logical images is 0. The default fill value of categorical images is missing, which corresponds to the <undefined> category.

Image Type	Transformation Dimensionality	Format of Fill Values
2-D grayscale or logical image	2-D	Numeric scalar
2-D color image or 2-D multispectral image	2-D	Numeric scalar c-element numeric vector specifying a fill value for each of the c channels. The number of channels, c, is 3 for color images.
Series of p 2-D images	2-D	Numeric scalar c-by-p numeric matrix. The number of channels, c, is 1 for grayscale images and 3 for color images.
N-D image	2-D	Numeric scalar Numeric array whose size matches dimensions 3-to-N of the input image `A`. For example, if `A` is 200-by-200-by-10-by-3, then `FillValues` can be a 10-by-3 array.
3-D grayscale or logical image	3-D	Numeric scalar
Categorical image	2-D or 3-D	Valid category in the image, specified as a string scalar or character vector. `missing`, which corresponds to the `<undefined>` category. For more information, see `missing`.

Example: 255 fills a uint8 image with white pixels

Example: 1 fills a double image with white pixels

Example: [0 1 0] fills a double color image with green pixels

Example: [0 1 0; 0 1 1]', for a series of two double color images, fills the first image with green pixels and the second image with cyan pixels

Example: "vehicle" fills a categorical image with the "vehicle" category

`SmoothEdges` — Pad image to create smooth edges
`false` (default) | `true`

Pad image to create smooth edges, specified as true or false. When set to true, imwarp create a smoother edge in the output image by padding the input image with values specified by FillValues. When set to false, imwarp does not pad the image. Choosing false (not padding) the input image can result in a sharper edge in the output image. This sharper edge can be useful to minimize seam distortions when registering two images side by side.

Output Arguments

collapse all

`B` — Transformed image
numeric array | logical array | categorical array

Transformed image, returned as a numeric, logical, or categorical array of the same data type as the input image A.

`RB` — Spatial referencing information of transformed image
`imref2d` object | `imref3d` object

Spatial referencing information of the transformed image, returned as an imref2d or imref3d spatial referencing object.

Algorithms

imwarp determines the value of pixels in the output image by mapping locations in the output image to the corresponding locations in the input image (an inverse mapping). When the center of a pixel in the output image does not map to the center of a pixel in the input image, imwarp interpolates within the input image to calculate the output pixel value.

The figure illustrates a translation transformation of a checkerboard image, in which each square is 10-by-10 pixels. By convention, the axes in input space are labeled u and v and the axes in output space are labeled x and y. Using the inverse transformation, the pixel with (x,y) coordinates (25,35) in the output coordinate space is mapped to the (u,v) coordinates (5,5) in the input coordinate space.

Checkerboard image in input coordinate space and translated checkerboard image in output coordinate space

imwarp performs the mapping using world coordinates. For more information, see Image Coordinate Systems.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

imwarp supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, imwarp generates code that uses a precompiled, platform-specific shared library. Use of a shared library preserves performance optimizations but limits the target platforms for which code can be generated. For more information, see Types of Code Generation Support in Image Processing Toolbox.
Input images of data type categorical are not supported.
The geometric transformation object input, tform, must represent a 2-D or 3-D linear geometric transformation.
The interpolation method and optional parameter names must be compile-time constants.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

Input images of data type categorical are not supported.
The geometric transformation object input, tform, must represent a 2-D geometric transformation.
The interpolation method and optional parameter names must be constants.
The spatial referencing information output, RB, is not supported.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

Only "nearest" and "linear" interpolation types are supported.
The SmoothEdges argument must be false.
Nonlinear geometric transformations are not supported.

For more information, see Image Processing on a GPU.

Version History

Introduced in R2013a

expand all

R2024a: Generate C code for 3-D linear transformations

You can now generate C code when tform is a 3-D linear geometric transformation.

R2022b: Supports new geometric transformation objects

Starting in R2022b, most Image Processing Toolbox™ functions create and perform geometric transformations using the premultiply convention. Accordingly, you can now specify tform as a geometric transformation object that uses a premultiply convention, such as an affinetform2d object.

Although you can still specify tform as a geometric transformation object that uses a postmultiply convention, such as an affine2d object, these objects are not recommended. You can streamline your geometric transformation workflows by switching to the new premultiply geometric transformation objects. For more information, see Migrate Geometric Transformations to Premultiply Convention.

R2021b: Support for thread-based environments

imwarp now supports thread-based environments.

R2021a: Enhanced support for GPU acceleration

The imwarp function, which already supports GPU acceleration, now extends that support to include the use of displacement fields.

imwarp

Syntax

Description

Examples

Apply Horizontal Shear to Image

Apply Rotation Transformation to 3-D MRI Data

Warp Image Using Different Output View Styles

Input Arguments

`A` — Image to be transformed
numeric array | logical array | categorical array

`tform` — Geometric transformation
geometric transformation object

`D` — Displacement field
numeric array

`RA` — Spatial referencing information of image to be transformed
`imref2d` object | `imref3d` object

`interp` — Type of interpolation used
`"nearest"` | `"linear"` | `"cubic"`

Name-Value Arguments

`OutputView` — Size and location of output image
`imref2d` object | `imref3d` object

`FillValues` — Fill value
numeric scalar | numeric array | string scalar | character vector | `missing`

`SmoothEdges` — Pad image to create smooth edges
`false` (default) | `true`

Output Arguments

`B` — Transformed image
numeric array | logical array | categorical array

`RB` — Spatial referencing information of transformed image
`imref2d` object | `imref3d` object

Algorithms

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

R2024a: Generate C code for 3-D linear transformations

R2022b: Supports new geometric transformation objects

R2021b: Support for thread-based environments

R2021a: Enhanced support for GPU acceleration

See Also

Apps

Functions

Topics

imwarp

Syntax

Description

Examples

Apply Horizontal Shear to Image

Apply Rotation Transformation to 3-D MRI Data

Warp Image Using Different Output View Styles

Input Arguments

A — Image to be transformed numeric array | logical array | categorical array

tform — Geometric transformation geometric transformation object

D — Displacement field numeric array

RA — Spatial referencing information of image to be transformed imref2d object | imref3d object

interp — Type of interpolation used "nearest" | "linear" | "cubic"

Name-Value Arguments

OutputView — Size and location of output image imref2d object | imref3d object

FillValues — Fill value numeric scalar | numeric array | string scalar | character vector | missing

SmoothEdges — Pad image to create smooth edges false (default) | true

Output Arguments

B — Transformed image numeric array | logical array | categorical array

RB — Spatial referencing information of transformed image imref2d object | imref3d object

Algorithms

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

GPU Arrays Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Version History

R2024a: Generate C code for 3-D linear transformations

R2022b: Supports new geometric transformation objects

R2021b: Support for thread-based environments

R2021a: Enhanced support for GPU acceleration

See Also

Apps

Functions

Topics

`A` — Image to be transformed
numeric array | logical array | categorical array

`tform` — Geometric transformation
geometric transformation object

`D` — Displacement field
numeric array

`RA` — Spatial referencing information of image to be transformed
`imref2d` object | `imref3d` object

`interp` — Type of interpolation used
`"nearest"` | `"linear"` | `"cubic"`

`OutputView` — Size and location of output image
`imref2d` object | `imref3d` object

`FillValues` — Fill value
numeric scalar | numeric array | string scalar | character vector | `missing`

`SmoothEdges` — Pad image to create smooth edges
`false` (default) | `true`

`B` — Transformed image
numeric array | logical array | categorical array

`RB` — Spatial referencing information of transformed image
`imref2d` object | `imref3d` object

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

GPU Arrays
Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.