imrotate3

Rotate 3-D volumetric grayscale image

Syntax

B = imrotate3(V,angle,W)

B = imrotate3(V,angle,W,method)

B = imrotate3(V,angle,W,method,bbox)

B = imrotate3(___,"FillValues",fillValues)

Description

B = imrotate3(V,angle,W) rotates the 3-D volume V by angle degrees counterclockwise around an axis passing through the origin [0 0 0]. W is a 1-by-3 vector which specifies the direction of the axis of rotation in 3-D space. By default, imrotate3 sets the values of voxels in B that are outside the boundaries of the rotated volume to 0.

B = imrotate3(V,angle,W,method) also specifies the interpolation method.

B = imrotate3(V,angle,W,method,bbox) also specifies the size of the output volume, bbox. If you specify "crop", then imrotate3 makes the output volume the same size as the input volume. If you specify "loose", then imrotate3 makes the output volume large enough to include the entirety of the rotated volume.

B = imrotate3(___,"FillValues",fillValues) sets the fill values used for output pixels without a corresponding pixel in the input image.

Examples

Rotate 3-D Volume

Load and display 3-D volumetric grayscale image.

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

Rotate the volume 90 degrees around the Z axis.

volRot = imrotate3(vol,90,[0 0 1],"nearest","loose");

Display the rotated output volume. You can also explore the volume in the Volume Viewer app.

volshow(volRot);

Input Arguments

V — Volume to be rotated

3-D numeric array | 3-D logical array | 3-D categorical array

Volume to be rotated, specified as a 3-D numeric array, 3-D logical array, or 3-D categorical array.

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

angle — Rotation angle in degrees

numeric scalar

Rotation angle in degrees, specified as numeric scalar. To rotate the volume clockwise, specify a negative value for angle. imrotate3 makes the output volume B large enough to contain the entire rotated 3-D volume.

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

W — Direction of the axis of rotation

1-by-3 numeric vector

Direction of the axis of rotation in 3-D space in Cartesian coordinates, specified as a 1-by-3 numeric vector.

If you want to specify the direction of the axis of rotation in spherical coordinates, use sph2cart to convert values to Cartesian coordinates before passing it to imrotate3.

Example: [0 0 1] rotates the volume around the Z axis

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

method — Interpolation method

"nearest" | "linear" | "cubic"

Interpolation method, specified as one of the following values.

Method	Description
"nearest"	Nearest neighbor interpolation. The output voxel is assigned the value of the voxel that the point falls within. No other voxels 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"	Trilinear interpolation. Trilinear interpolation is the default method for numeric and logical images.
"cubic"	Tricubic interpolation Note Tricubic interpolation can produce pixel values outside the original range.

Data Types: char | string

bbox — Size of the output volume

"loose" (default) | "crop"

Size of the output volume, specified as either of the following values.

Method	Description
"crop"	Make the output volume the same size as the input volume, cropping the rotated volume to fit.
"loose"	Make the output volume large enough to contain the entire rotated volume. Usually, the rotated volume is larger than the input volume.

Data Types: char | string

fillValues — Fill values

numeric scalar | string scalar | character vector | missing

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

Image Type	Format of Fill Values
Numeric image or logical image	Numeric scalar. The default fill value of numeric and logical images is 0.
Categorical image	Valid category in the image, specified as a string scalar or character vector. missing, which corresponds to the <undefined> category. missing is the default fill value for categorical images. For more information, see missing.

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

Output Arguments

B — Rotated volume

numeric array | logical array | categorical array

Rotated volume, returned as a numeric, logical, or categorical array of the same data type as the input volume, V.

Tips

• imrotate3 assumes that the input volume V is centered on the origin [0 0 0]. If your volume is not centered on the origin, then use imtranslate to translate the volume to [0 0 0] before using imrotate3. You can translate the output volume B back to the original position with the opposite translation vector.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• imrotate3 supports the generation of C code (requires MATLAB^® Coder™). Note that if you choose the generic MATLAB Host Computer target platform, imrotate3 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.

• The method and bbox arguments must be compile-time constants.

• Input images of data type categorical are not supported.

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 method and bbox arguments must be compile-time constants.

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 R2017a

R2024b: Generate optimized CUDA code using GPU Coder

imrotate3 now supports the generation of optimized CUDA^® code (requires GPU Coder™).

R2024a: Generate C code using MATLAB Coder

imrotate3 now supports the generation of C code (requires MATLAB Coder).

R2021b: Support for thread-based environments

imrotate3 now supports thread-based environments.