Warper

Apply same geometric transformation to many images efficiently

Description

A Warper object applies a linear 2-D geometric transformation to images with a specific size. If the input images are RGB images or 3-D grayscale images, then the Warper object applies the geometric transformation to each color channel or plane independently.

Creation

Syntax

w = images.geotrans.Warper(tform,inputSize)

w = images.geotrans.Warper(tform,inputRef)

w = images.geotrans.Warper(tform,inputRef,outputRef)

w = images.geotrans.Warper(sourceX,sourceY)

w = images.geotrans.Warper(___,Name=Value)

Description

w = images.geotrans.Warper(tform,inputSize) creates a Warper object that applies a 2-D geometric transformation tform to images of size inputSize.

w = images.geotrans.Warper(tform,inputRef) specifies the coordinate system of the input images, inputRef.

w = images.geotrans.Warper(tform,inputRef,outputRef) specifies the coordinate system of the output image, outputRef. This syntax can be used to improve performance by limiting the application of the geometric transformation to a specific output region of interest.

w = images.geotrans.Warper(sourceX,sourceY) specifies the input image coordinates, sourceX and sourceY, required to perform the geometric transformation.

w = images.geotrans.Warper(___,Name=Value) also sets one or more writable properties using name-value arguments.

For example, w = images.geotrans.Warper(tform,size(im),FillValue=1) specifies a fill value of 1 for pixels outside the original image.

Input Arguments

tform — Geometric transformation

geometric transformation object

Geometric transformation, specified as one of these geometric transformation objects.

Geometric Transformation Object	Description
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

inputSize — Size of the input images

2-element vector of positive integers | 3-element vector of positive integers

Size of the input images, specified as a 2- or 3-element vector of positive integers.

This argument sets the InputSize property.

inputRef — Referencing object associated with input image

imref2d object

Referencing object associated with the input image, specified as an imref2d spatial referencing object.

outputRef — Referencing object associated with output image

imref2d object

Referencing object associated with the output image, specified as an imref2d spatial referencing object.

sourceX, sourceY — Input image coordinates

2-D matrix

Input image coordinates, specified as a 2-D matrix the same size as the required output image. Each (x, y) index in sourceX and sourceY specifies the location in the input image for the corresponding output pixel.

Data Types: single

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: w = images.geotrans.Warper(tform,size(im),FillValue=1) specifies a fill value of 1 for pixels outside the original image.

Interpolation — Interpolation method

"linear" (default) | "nearest" | "cubic"

Interpolation method, specified as "linear", "nearest", or "cubic".

This argument sets the Interpolation property.

Data Types: char | string

FillValue — Value used for output pixels outside the input image boundaries

0 (default) | numeric scalar

Value used for output pixels outside the input image boundaries, specified as a numeric scalar. Warper casts the fill value to the data type of the input image.

This argument sets the FillValue property.

Properties

InputSize — Size of the input images

2-element vector of positive integers | 3-element vector of positive integers

Size of the input images, specified as a 2- or 3-element vector of positive integers.

OutputSize — Size of the first two dimensions of the output image

2-element vector of positive integers

Size of the first two dimensions of the output image, specified as a 2-element vector of positive integers.

Interpolation — Interpolation method

"linear" (default) | "nearest" | "cubic"

Interpolation method, specified as "linear", "nearest", or "cubic".

Data Types: char | string

FillValue — Value used for output pixels outside the input image boundaries

0 (default) | numeric scalar

Value used for output pixels outside the input image boundaries, specified as a numeric scalar. Warper casts the fill value to the data type of the input image.

Object Functions

warp	Apply geometric transformation of Warper object

Examples

Apply Shear to Multiple Images

Pick a set of images of the same size. The example uses a set of images that show cells.

imds = imageDatastore(fullfile(matlabroot,"toolbox","images","imdata","AT*"));

Create a similarity geometric transformation that rotates each image by 45 degrees and shrinks each image. The transformation does not translate the images.

scaleFactor = 0.5;
theta = 45;
translation = [0 0];
tform = simtform2d(scaleFactor,theta,translation);

Create a Warper object, specifying the geometric transformation object, tform, and the size of the input images.

im = readimage(imds,1);
warper = images.geotrans.Warper(tform,size(im));

Determine the number of images to be processed and preallocate the output array.

numFiles = numel(imds.Files);
imr = zeros([warper.OutputSize 1 numFiles],"like",im);

Apply the geometric transformation to each of the input images by calling the warp function of the Warper object.

for ind = 1:numFiles
    im = read(imds);
    imr(:,:,1,ind) = warp(warper,im);
end

Visualize the output images in a montage.

montage(imr)

Algorithms

Warper is optimized to apply the same geometric transformation across a batch of same size images. Warper achieves this optimization by splitting the warping process into two steps: computation of the transformed coordinates (done once) and interpolation on the image (done for each image). Compared to imwarp, this approach speeds up the whole process significantly for small to medium-sized images, with diminishing returns for larger images.

Version History

Introduced in R2017b

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 the premultiply convention, such as an affinetform2d object.

Although the Warper object still supports the affine2d and projtform2d objects, these objects are not recommended because they use the postmultiply convention. 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.