medicalImage

2-D medical image pixel data and file metadata

Since R2022b

Description

A medicalImage object stores the pixel data and metadata for a 2-D medical image or image sequence contained in a single DICOM file. An image sequence is a series of 2-D image frames related by time, such as an ultrasound video.

Creation

Syntax

medImage = medicalImage(dirname)

medImage = medicalImage(filename)

medImage = medicalImage(sourceTable)

medImage = medicalImage(sourceTable,rowname)

medImage = medicalImage(imds)

medImage = medicalImage(pixels,info)

Description

medImage = medicalImage(dirname) creates a medicalImage object for the single DICOM file in the directory dirname.

medImage = medicalImage(filename) creates a medicalImage object for the image contained in the single DICOM file filename.

medImage = medicalImage(sourceTable) creates a medicalImage object for the image listed in sourceTable. The table must contain only one row that specifies the metadata for a 2-D DICOM image.

medImage = medicalImage(sourceTable,rowname) creates a medicalImage object for the image listed in the row rowname of sourceTable. Use this syntax to specify one row of a multirow table by name or by its numeric index.

medImage = medicalImage(imds) creates a medicalImage object for the image specified by the image datastore object imds.

medImage = medicalImage(pixels,info) creates a medicalImage object by specifying the image data pixels and info, a metadata structure returned by the dicominfo function. pixels sets value of the Pixels property.

Input Arguments

dirname — Name of directory containing medical image data

string scalar | character vector

Name of the directory containing the medical image data, specified as a string scalar or a character vector. dirname is the name of a directory that contains one DICOM file that specifies one 2-D image or sequence of 2-D images related by time, such as an ultrasound video.

filename — Name of file containing medical image data

string scalar | character vector

Name of the file containing the medical image data, specified as a string scalar or a character vector. filename can specify a single DICOM file that contains a 2-D image or series of 2-D images related by time, such as an ultrasound video.

sourceTable — Collection of DICOM file metadata

table

Collection of DICOM file metadata, specified as a table returned by the dicomCollection function.

rowname — Name or index of table row

string scalar | character vector | positive integer

Name or index of the table row to read from sourceTable, specified as a string scalar, character vector, or positive integer scalar. Specify rowname as a string scalar or character vector to specify the row by name. Specify rowname as a positive integer scalar to specify the row by its numeric index.

imds — Datastore containing one DICOM file

ImageDatastore object

Datastore containing one DICOM file, specified as an imageDatastore object.

info — DICOM file metadata

structure

DICOM file metadata, specified as a structure returned by the dicominfo function.

Properties

Pixels — Image pixel values

m-by-n-by-t-by-c numeric array

Image pixel values, specified as an m-by-n-by-t-by-c numeric array, where m and n are the spatial dimensions of the 2-D image or image frames, t is the number of image frames related by time, and c is the number of color channels in each frame. If the file contains the RescaleIntercept and RescaleSlope metadata attributes, then medicalImage rescales the intensity values based on them.

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

Colormap — Colormap

j-by-3 numeric matrix | []

Colormap, specified as one of these options:

• If the source is an indexed image, then specify Colormap as a j-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 the source is a grayscale or RBG image, then Colormap is empty ([]).

Data Types: double

SpatialUnits — Real-world spatial units

"mm" | "unknown"

This property is read-only.

Real-world spatial units, specified as one of these options:

• If the pixel spacing is specified in the file metadata, then the spatial units value is "mm".

• If the metadata does not specify the pixel spacing information, then SpatialUnits is "unknown".

Data Types: string

FrameTime — Number of milliseconds between frames

numeric scalar | []

This property is read-only.

Number of milliseconds between frames, specified as one of these options:

• If the Frame Time metadata attribute is specified in the file, then the frame time value is specified as a numeric scalar extracted from the metadata.

• If the metadata does not specify the frame time, then FrameTime is empty ([]).

Data Types: double

NumFrames — Number of frames

numeric scalar

This property is read-only.

Number of frames in the image data, specified as a numeric scalar.

Data Types: double

PixelSpacing — Spacing between pixel centers

[1 1] (default) | 2-element row vector

This property is read-only.

Spacing between pixel centers, specified as a 2-element vector of the form [Δx Δy]. The Δx and Δy values are the distances between adjacent pixels in the x- and y-directions, respectively, in the units specified by the SpatialUnits property. If the file metadata does not specify the pixel spacing, the default value is [1 1].

Data Types: double

Modality — Imaging modality used to capture image data

"unknown" (default) | string scalar

This property is read-only.

Imaging modality used to capture image data, specified as a string scalar. The modality is extracted from the file metadata if it is present. Common values include, but are not limited to, "DX" for digital radiography, "US" for ultrasound, "XA" for X-ray angiography, and "MG" for mammography. If the file metadata does not specify the modality, then the default value is "unknown".

Data Types: string

WindowCenter — Center of display range window

numeric scalar | []

This property is read-only.

Center of the display range window, specified as one of these options:

• If the Window Center attribute is specified in the file metadata, then the WindowCenter value is specified as a numeric scalar extracted from the metadata.

• If the metadata does not specify the window center, then WindowCenter is empty ([]).

Data Types: double

WindowWidth — Width of display range window

numeric scalar | []

This property is read-only.

Width of the display range window, specified as one of these options:

• If the Window Width attribute is specified in the file metadata, then the WindowWidth value is specified as a numeric scalar extracted from the metadata.

• If the metadata does not specify the window width, then WindowWidth is empty ([]).

Data Types: double

Object Functions

extractFrame	Extract pixel data for one frame of 2-D medical image series
implay	View 2-D medical image series in Video Viewer app
montage	Display multiple images as rectangular montage

Examples

Create Medical Image Object from Filename

Specify the name of a 2-D X-ray image. The image is attached to this example as a supporting file.

filename = "forearmXrayImage1.dcm";

Create a medicalImage object for the file.

medImage = medicalImage(filename)

medImage = 
  medicalImage with properties:

          Pixels: [1540x1250 uint16]
        Colormap: []
    SpatialUnits: "mm"
       FrameTime: []
       NumFrames: 1
    PixelSpacing: [0.1390 0.1390]
        Modality: 'DX'
    WindowCenter: 2048
     WindowWidth: 4096

The image pixel data is stored in the Pixels property. Display the image stored in medImage.

imshow(medImage.Pixels,[])

Create Medical Image Object from DICOM Collection

Specify the name of the directory containing this example, which includes an echocardiogram image series stored as a DICOM file.

dirname = pwd;

Gather the details about the DICOM files in the directory into a table by using the dicomCollection function.

sourceTable = dicomCollection(dirname);

Create a medicalImage object for the echocardiogram sequence.

medImage = medicalImage(sourceTable)

medImage = 
  medicalImage with properties:

          Pixels: [600x800x3x3 uint8]
        Colormap: []
    SpatialUnits: "unknown"
       FrameTime: []
       NumFrames: 3
    PixelSpacing: [1 1]
        Modality: 'OT'
    WindowCenter: []
     WindowWidth: []

Create Medical Image Object from Specified Row of DICOM Collection

Specify the name of the directory containing this example, which includes three 2-D X-ray images of a forearm.

dataFolder = pwd;

Gather the details about the DICOM files in the directory into a table by using the dicomCollection function. The table contains three rows corresponding to the three DICOM series.

sourceTable = dicomCollection(dataFolder);

Create a medical image object for the second X-ray image by specifying the DICOM collection table and a numeric row index.

medImage = medicalImage(sourceTable,2)

medImage = 
  medicalImage with properties:

          Pixels: [1932x1492 uint16]
        Colormap: []
    SpatialUnits: "mm"
       FrameTime: []
       NumFrames: 1
    PixelSpacing: [0.1390 0.1390]
        Modality: 'DX'
    WindowCenter: 2048
     WindowWidth: 4096

Create Medical Image Object from Image Datastore

Specify the name of the directory containing this example, which includes an echocardiogram image series stored as a single DICOM file.

dataFolder = pwd;

Create an image datastore containing the DICOM file in the dataFolder directory. Specify a custom read function to read the DICOM file.

dicomds = imageDatastore(dataFolder, ... 
    FileExtensions=".dcm",ReadFcn=@(x) dicomread(x));

Create a medical image object for the echocardiogram series.

medImage = medicalImage(dicomds)

medImage = 
  medicalImage with properties:

          Pixels: [600x800x3x3 uint8]
        Colormap: []
    SpatialUnits: "unknown"
       FrameTime: []
       NumFrames: 3
    PixelSpacing: [1 1]
        Modality: 'OT'
    WindowCenter: []
     WindowWidth: []

Create Medical Image Object from Pixels and Metadata

Specify the name of a 2-D X-ray image. The file is attached to this example as a supporting file.

filename = "forearmXrayImage1.dcm";

Read the metadata from the DICOM file by using the dicominfo function.

info = dicominfo(filename);

Create a medicalImage object for the file.

medImage = medicalImage(filename)

medImage = 
  medicalImage with properties:

          Pixels: [1540x1250 uint16]
        Colormap: []
    SpatialUnits: "mm"
       FrameTime: []
       NumFrames: 1
    PixelSpacing: [0.1390 0.1390]
        Modality: 'DX'
    WindowCenter: 2048
     WindowWidth: 4096

The image pixel data is stored in the Pixels property. Apply a smoothing filter to the pixel values and save the smoothed values as a new image array, imSmooth.

sigma = 2;
imSmooth = imgaussfilt(medImage.Pixels,sigma);

Create a new medicalImage object that contains the smoothed pixel values. To maintain the same spatial information as the original image, specify the metadata structure info.

medImageSmoothed = medicalImage(imSmooth,info)

medImageSmoothed = 
  medicalImage with properties:

          Pixels: [1540x1250 uint16]
        Colormap: []
    SpatialUnits: "mm"
       FrameTime: []
       NumFrames: 1
    PixelSpacing: [0.1390 0.1390]
        Modality: 'DX'
    WindowCenter: 2048
     WindowWidth: 4096

Version History

Introduced in R2022b