montage

Display medical image slices or frames as montage in patient coordinates

Since R2023a

Syntax

montage(medImage)

montage(medVolume)

montage(I)

montage(imagelist)

montage(filenames)

montage(imds)

montage(___,map)

montage(___,Name=Value)

img = montage(___)

Description

Medical Imaging Toolbox™ extends the functionality of the montage (Image Processing Toolbox™) function to display data in a medicalImage or medicalVolume object. If you do not have Medical Imaging Toolbox installed, see montage (Image Processing Toolbox).

Medical Objects

montage(medImage) displays all of the frames in a medicalImage object as a rectangular montage. The function automatically adjusts display settings using medicalImage properties.

montage(medVolume) displays all of the slices in a medicalVolume object as a rectangular montage. The function automatically adjusts display settings using medicalVolume properties.

Nonmedical Image Formats

montage(I) displays all of the frames of the numeric array I.

montage(imagelist) displays a montage of images specified in the cell array imagelist. The images can be of different types and sizes.

montage(filenames) displays a montage of the images with the specified filenames filenames. Files must be in standard image formats supported by imread.

montage(imds) displays a montage of the images specified in the image datastore imds.

Additional Options

montage(___,map) treats grayscale and binary images as indexed images and displays them with the specified colormap map, in addition to any input argument from a previous syntax. If you specify images using a medicalImage object, medicalVolume object, filenames, or an image datastore, then map overrides any internal colormap present in the object or image files. montage does not modify the colormap of RGB images.

montage(___,Name=Value) uses name-value pair arguments to customize the display of the image montage.

img = montage(___) returns a handle to the single image object that contains all of the displayed images.

Examples

Display Medical Image Series as Montage

Specify the name of a DICOM file containing an echocardiogram ultrasound series. The DICOM file is attached to this example as a supporting file.

filename = "heartUltrasoundSequenceVideo.dcm";

Read the metadata and image data from the file by creating a medicalImage object. The FrameTime property indicates that each frame has a duration of 33.333 milliseconds. The NumFrames property indicates that the series has a total of 116 image frames.

medImg = medicalImage(filename)

medImg = 
  medicalImage with properties:

          Pixels: [600×800×116×3 uint8]
        Colormap: []
    SpatialUnits: "unknown"
       FrameTime: 33.3330
       NumFrames: 116
    PixelSpacing: [1 1]
        Modality: 'US'
    WindowCenter: []
     WindowWidth: []

Display the frames of the image series stored in the Pixels property of medImg as a montage.

montage(medImg)

Display Medical Image Volume Slices as Montage

Display a montage of slices from a chest CT volume saved as a directory of DICOM files. The volume is part of a data set containing three CT volumes. The size of the entire data set is approximately 81 MB.

Run this code to download the data set from the MathWorks® website and unzip the folder.

zipFile = matlab.internal.examples.downloadSupportFile("medical","MedicalVolumeDICOMData.zip");
filepath = fileparts(zipFile);
unzip(zipFile,filepath)

The dataFolder folder contains the downloaded CT volume.

dataFolder = fullfile(filepath,"MedicalVolumeDICOMData","LungCT01");

Create a medical image volume object that contains the image data and spatial referencing information for the CT volume.

medVol = medicalVolume(dataFolder)

medVol = 
  medicalVolume with properties:

                 Voxels: [512×512×88 int16]
         VolumeGeometry: [1×1 medicalref3d]
           SpatialUnits: "mm"
            Orientation: "transverse"
           VoxelSpacing: [0.7285 0.7285 2.5000]
           NormalVector: [0 0 1]
       NumCoronalSlices: 512
      NumSagittalSlices: 512
    NumTransverseSlices: 88
           PlaneMapping: ["sagittal"    "coronal"    "transverse"]
               Modality: "CT"
          WindowCenters: [88×1 double]
           WindowWidths: [88×1 double]

Display the slices of the images stored in medVol as a montage. The Orientation property of medVol determines the slice plane, which is transverse in this example. The montage object function automatically sets the intensity display range and orients slices in the patient coordinate system using the property values of medVol.

montage(medVol)

Input Arguments

medImage — Medical image

medicalImage object

Medical image, specified as a medicalImage object. The montage object function displays frames stored in the Pixels property of medImage and uses these properties of medImage to set display settings:

• WindowCenter and WindowWidth — If specified, these properties set the DisplayRange name-value argument.

• Colormap — If specified, this property sets the map input argument.

medVolume — Medical volume

medicalVolume object

Medical volume, specified as a medicalVolume object. The montage object function displays slices stored in the Voxels property of medVolume, and uses these properties of medVolume to set display settings:

• WindowCenters and WindowWidths — If specified, these properties set the DisplayRange name-value argument.

• Orientation — Specifies the plane in which the function displays slices:

  • If the Orientation property value is "transverse", then montage displays transverse slices with the anterior side of the patient on the top of the image and the right side of the patient on the left side of the image. To display the right side of the patient on the right side of the image, set the AnatomicalConvention name-value argument to "neurological".

  • If the Orientation property value is "coronal", then montage displays coronal slices with the superior end of the patient on the top of the image and the right side of the patient on the left side of the image. To display the right side of the patient on the right side of the image, set the AnatomicalConvention name-value argument to "neurological".

  • If the Orientation property value is "sagittal", then montage displays sagittal slices with the superior end of the patient on the top of the image and the anterior side of the patient on the left side of the image.

If the patient coordinate system is undefined, then montage displays the data in the Voxels property of the medicalVolume object as a numeric array with default display settings. The patient coordinate system is undefined if the PatientCoordinateSystem property of the medicalref3d object in the VolumeGeometry property of the medicalVolume object is "unknown".

I — Multiframe image array

numeric array

Multiframe image array, specified as one of these options:

• m-by-n-by-k numeric array representing a sequence of k binary or grayscale images

• m-by-n-by-1-by-k numeric array representing a sequence of k binary or grayscale images

• m-by-n-by-3-by-k numeric array representing a sequence of k truecolor (RGB) images

Data Types: single | double | int16 | uint8 | uint16 | logical

imagelist — Set of images

cell array of numeric matrices

Set of images, specified as a cell array of numeric matrices. Each matrix is of size m-by-n for binary or grayscale images or m-by-n-by-3 for truecolor (RGB) images.

Data Types: single | double | int16 | uint8 | uint16 | logical | cell

filenames — Names of files containing images

cell array of character vectors | vector of strings

Names of files containing image, specified as a cell array of character vectors or a vector of strings. If the files are not in the current folder or in a folder on the MATLAB^® path, then specify the full path name. For more information, see imread.

Data Types: char | string | cell

imds — Image datastore

ImageDatastore object

Image datastore, specified as an ImageDatastore object.

map — Colormap

c-by-3 numeric matrix

Colormap, specified as a c-by-3 numeric matrix with values in the range [0, 1]. Each row is a three-element RGB triplet that specifies the red, green, and blue components of a single color of the colormap.

If you specify a medicalImage object with a defined Colormap property as input, montage, by default, applies the colormap from this property to the image frames. Specify map to override the default behavior.

Data Types: double

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: montage(medVol,AnatomicalConvention="radiological") displays the left side of the patient on the right side of the image.

AnatomicalConvention — Anatomical display orientation convention

"radiological" (default) | "neurological"

Anatomical display orientation convention, specified as one of these values:

• "radiological" — Displays the left side of the patient on the right side of the image.

• "neurological" — Displays the left side of the patient on the left side of the image.

Note

To use the AnatomicalConvention name-value argument, you must specify a medicalVolume object as the input.

Data Types: char | string

BackgroundColor — Background color

"black" (default) | RGB triplet | color name | short color name

Background color, specified as an RGB triplet, a color name, or a short color name. The montage object function fills all blank spaces with the background color, including the space specified by BorderSize. If you specify a background color, then the montage function renders the output as an RGB image.

You can specify any color using an RGB triplet. An RGB triplet is a 3-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0, 1].

You can specify some common colors by name as a string scalar or character vector. This table lists the named color options and the equivalent RGB triplets.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

Here are the RGB triplets for the default colors that MATLAB uses in many types of plots.

RGB Triplet	Appearance
[0 0.4470 0.7410]
[0.8500 0.3250 0.0980]
[0.9290 0.6940 0.1250]
[0.4940 0.1840 0.5560]
[0.4660 0.6740 0.1880]
[0.3010 0.7450 0.9330]
[0.6350 0.0780 0.1840]

Example: "BackgroundColor","r"

Example: "BackgroundColor","green"

Example: "BackgroundColor",[0 0.4470 0.7410]

BorderSize — Padding around each thumbnail image

[0 0] (default) | nonnegative integer | 1-by-2 vector of nonnegative integers

Padding around each thumbnail image, in pixels, specified as a nonnegative integer or a 1-by-2 vector of nonnegative integers. The montage function pads the image borders with the background color BackgroundColor.

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

DisplayRange — Intensity display range

1-by-2 vector

Intensity display range, specified as a two-element vector of the form [low high]. Intensity values less than or equal to low appear black. Intensity values greater than or equal to high appear white. If you specify an empty matrix ([]), then montage uses the minimum and maximum values in the image. The default display range depends on the input image:

• medicalImage object — montage uses the WindowCenter and WindowWidth properties to set the display range. If WindowCenter and WindowWidth are empty, then montage uses the minimum and maximum values in the image.

• medicalVolume object — montage uses the WindowCenters and WindowWidths properties to set the display range. If WindowCenters and WindowWidths are empty, then montage uses the minimum and maximum values in the image.

• Numeric array — The default is the range of the datatype of the array.

DisplayRange has no effect when displaying indexed images with colormaps or RGB images.

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

Indices — Frames or slices to display

array of positive integers

Frames or slices to display in the montage, specified as an array of positive integers. If you specify a medicalImage object as input, then montage displays the corresponding frames of the image series. If you specify a medicalVolume object, montage displays the corresponding slices in the displayed plane. For nonmedical inputs, the montage function interprets the values as indices into the array I or into the cell array filenames or imagelist.

By default, the montage function displays all frames or image files.

Example: Indices=1:4 creates a montage of the first four frames.

Example: Indices=1:2:20 displays every other frame.

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

Interpolation — Interpolation technique

"nearest" (default) | "bilinear"

Interpolation technique used when scaling an image, specified as one of these values.

Value	Description
"nearest"	Nearest neighbor interpolation (default)
"bilinear"	Bilinear interpolation

Parent — Parent of image object

Axes object

Parent of the image object created by montage, specified as an Axes object. The montage function resizes the image to fit the extents available in the parent axes.

Size — Number of rows and columns of images

2-element vector

Number of rows and columns of images, specified as a 2-element vector of the form [nrows ncols]. By default, montage arranges the images in the number of rows and columns that roughly form a square.

If you specify NaN or Inf for a particular dimension, then the montage function calculates the value of that dimension required to display all images in the montage, while preserving the specified dimension. For example, if Size is [2 NaN], then the montage has two rows and the minimum number of columns required to display all images. When there is a mismatch between Size and the number of images (frames) specified, then the montage function displays as many of the images as possible while preserving the specified Size.

Data Types: single | double

ThumbnailSize — Size of each thumbnail

2-element vector of positive integers | []

Size of each thumbnail, in pixels, specified as a 2-element vector of positive integers. The function preserves the aspect ratio of each image, and fills any blank space with the background color BackgroundColor. By default, montage sets the thumbnail size based on your screen size and the number of frames to display.

If you specify an empty array ([]), then the thumbnail size is the full size of the first image. If you specify either element as NaN or Inf, then the montage function calculates the corresponding value so as to preserve the aspect ratio of the first image, given the specified size of the other dimension.

Data Types: single | double

Output Arguments

img — Montage image

Image object

Montage image, returned as an Image object. For more information on Image objects, see Image Properties.

Tips

• If you specify an indexed image, then montage converts it to RGB using the colormap present in the file.

• If there is a data type mismatch between images, then the montage function converts all images to data type double using the im2double function.

• When calculating the number of images to display horizontally and vertically, montage considers the aspect ratio of the images, so that the displayed montage is nearly square.

• Figure titles can appear cut off in the Live Editor. To ensure the whole title is visible, set the PositionContraint property of the parent Axes object to "outerposition". Update the property value after you call the montage function and before you call the title function.

  I = imread("peppers.png");
  montage({I,I})
  ax = gca;
  ax.PositionConstraint = "outerposition";
  title("Peppers");

  If you specify the parent axes using the Parent name-value argument, set the PositionConstraint property of the specified parent Axes object. For more details about axes position properties, see Control Axes Layout.

Version History

Introduced in R2023a