imwarp
Apply geometric transformation to image
Syntax
Description
[___] = imwarp(___,
specifies the type of interpolation to use.interp
)
[___] =
imwarp(___,
specifies name-value arguments to control various aspects of the geometric
transformation. Name=Value
)
Tip
If the input transformation tform
does not define a
forward transform, then use the OutputView
name-value
argument to accelerate the transformation.
Examples
Apply Horizontal Shear to Image
Read and display a grayscale image.
I = imread('cameraman.tif');
imshow(I)
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)
Apply Rotation Transformation to 3-D MRI Data
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
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)
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");
imshow(BFollowOutput)
title("FollowOutput Bounds Style");
imshow(BSameAsInput)
title("SameAsInput Bounds Style");
iptsetpref("ImshowAxesVisible","off")
Input Arguments
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.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
| categorical
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 andA
has more than two dimensions, such as for an RGB image, thenimwarp
applies the same 2-D transformation to all 2-D planes along the higher dimensions.If
tform
is 3-D, thenA
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 inD
to produce remapped locations inA
. 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 specifyD
as an m-by-n-by-2 array, thenimwarp
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 inD
to produce remapped locations inA
. Similarly,D(:,:,:,2)
andD(:,:,:,3)
contain displacements along the y- and z-axis.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
interp
— Type of interpolation used
"nearest"
| "linear"
| "cubic"
Type of interpolation used, specified as one of these values.
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 |
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 |
|
2-D color image or 2-D multispectral image | 2-D |
|
Series of p 2-D images | 2-D |
|
N-D image | 2-D |
|
3-D grayscale or logical image | 3-D |
|
Categorical image | 2-D or 3-D |
|
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
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
.
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.
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 genericMATLAB 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 befalse
.Nonlinear geometric transformations are not supported.
For more information, see Image Processing on a GPU.
Version History
Introduced in R2013aR2024a: 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.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)