Main Content

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

Description

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

example

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

example

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.

example

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.

example

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

example

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

expand all

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.

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.

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

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.

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

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

Properties

expand all

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, 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

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

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

This property is read-only.

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

Data Types: double

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

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

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

This property is read-only.

Width of the of 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

extractFrameExtract pixel data for one frame of 2-D medical image series
implayView 2-D medical image series in Video Viewer app
montageDisplay multiple image frames as rectangular montage

Examples

collapse all

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,[])

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: []

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

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: []

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