imtranslate

Translate image

Syntax

B = imtranslate(A,translation)

[B,RB] = imtranslate(A,RA,translation)

___ = imtranslate(___,method)

___ = imtranslate(___,Name=Value)

Description

B = imtranslate(A,translation) translates image A by the 2-D or 3-D translation vector specified in translation.

If A has more than two dimensions and translation is a 2-element vector, then imtranslate applies the 2-D translation to each plane of A.

[B,RB] = imtranslate(A,RA,translation) translates the spatially referenced image A with its associated spatial referencing object RA. The translation vector, translation, is in the world coordinate system. The function returns the translated spatially referenced image B, with its associated spatial referencing object, RB.

___ = imtranslate(___,method) translates image A, using the interpolation method specified by method.

___ = imtranslate(___,Name=Value) translates the input image using name-value arguments to control various aspects of the translation.

Examples

Translate 2-D Image

Read image into the workspace.

I = imread('pout.tif');

Translate the image.

J = imtranslate(I,[25.3, -10.1],'FillValues',255);

Display the original image and the translated image.

figure
imshow(I);
title('Original Image');
set(gca,'Visible','on');

figure
imshow(J);
title('Translated Image');
set(gca,'Visible','on');

Translate 2-D Image and View Entire Translated Image

Read image into the workspace.

I = imread('pout.tif');

Translate the image. Use the OutputView parameter to specify that you want the entire translated image to be visible.

J = imtranslate(I,[25.3, -10.1],'FillValues',255,'OutputView','full');

Display the original image and the translated image.

figure
imshow(I);
title('Original Image');
set(gca,'Visible','on');

figure
imshow(J);
title('Full Translated Image');
set(gca,'Visible','on');

Translate 3-D MRI Dataset

Load MRI data into the workspace and display it.

s = load('mri');
mriVolume = squeeze(s.D);
sizeIn = size(mriVolume);
hFigOriginal = figure;
hAxOriginal  = axes;
slice(double(mriVolume),sizeIn(2)/2,sizeIn(1)/2,sizeIn(3)/2);
grid on, shading interp, colormap gray

Apply a translation in the X,Y direction.

mriVolumeTranslated = imtranslate(mriVolume,[40,30,0],'OutputView','full');

Visualize the translation by viewing an axial slice plane taken through center of the volume. Note the shift in the X and Y directions.

sliceIndex = round(sizeIn(3)/2);
axialSliceOriginal   = mriVolume(:,:,sliceIndex);
axialSliceTranslated = mriVolumeTranslated(:,:,sliceIndex);

imshow(axialSliceOriginal);

imshow(axialSliceTranslated);

Input Arguments

A — Image to be translated

numeric array | logical array | categorical array

Image to be translated, specified as a numeric array, logical array, or categorical array.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 | logical | categorical

RA — Spatial referencing information associated with the input image A

imref2d or imref3d spatial referencing object

Spatial referencing information associated with the input image A, specified as an imref2d or imref3d spatial referencing object.

translation — Translation vector

2-element numeric vector | 3-element numeric vector

Translation vector, specified as a 2-element numeric vector [Tx Ty] or a 3-element numeric vector [Tx Ty Tz]. Values can be fractional.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32

method — Interpolation method

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

Interpolation method, specified as one of these values.

Value	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.
"bilinear"	Linear interpolation. Linear interpolation is the default method for numeric and logical images.
"bicubic"	Cubic interpolation. Note Cubic interpolation can produce pixel values outside the original range.

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: mriVolumeTranslated = imtranslate(mriVolume,[40,30,0],OutputView="full") specifies the output world limits as "full".

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

Example: mriVolumeTranslated = imtranslate(mriVolume,[40,30,0],"OutputView","full");

OutputView — Output world limits

"same" (default) | "full"

Output world limits, specified as one of these values.

Value	Description
"same"	Output world limits are the same as the input image.
"full"	Output world limits are the bounding rectangle that includes both the input image and the translated output image.

Data Types: char | string

FillValues — Fill values

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. imtranslate 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	Translation Dimension	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

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | string | char

Output Arguments

B — Translated image

numeric array | logical array | categorical array

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

RB — Spatial referencing information associated with the output image

imref2d object | imref3d object

Spatial referencing information associated with the output image, returned as an imref2d or imref3d spatial referencing object.

Tips

• imtranslate is optimized for integer valued translation vectors.

• When OutputView is "full" and translation is a fractional number of pixels, then imtranslate expands the world limits of the output spatial referencing object to the nearest full pixel increment. imtranslate does this so that it contains both the original and translated images at the same resolution as the input image. The additional image extent in each is added on one side of the image, in the direction that the translation vector points. For example, when translation is fractional and positive in both X and Y, then imtranslate expands the maximum of XWorldLimits and YWorldLimits to enclose the "full" bounding rectangle at the resolution of the input image.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• imtranslate supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, imtranslate 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 function supports only 2-D translation vectors, translation. 3-D translations are 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.

Version History

Introduced in R2014a

R2021b: Support for thread-based environments

imtranslate now supports thread-based environments.