medicalVolume

3-D medical image voxel data and spatial referencing information

Since R2022b

Description

A medicalVolume object stores the voxel data and spatial referencing information for the medical image volume contained in a single DICOM, NIfTI, or NRRD file, or in a directory of DICOM files. The medicalVolume object specifies the mapping between the intrinsic image coordinate system, the patient coordinate system, and the anatomical planes. The medicalVolume object and its object functions provide a standardized interface for accessing voxel data, spatial referencing, and intensity scaling information.

Creation

Syntax

medVol = medicalVolume(dirname)

medVol = medicalVolume(filenames)

medVol = medicalVolume(sourceTable)

medVol = medicalVolume(sourceTable,rowname)

medVol = medicalVolume(imds)

medVol = medicalVolume(voxels,VolumeGeometry)

Description

medVol = medicalVolume(dirname) creates a medicalVolume object for the image volume contained in a multifile DICOM series in the directory dirname.

medVol = medicalVolume(filenames) creates a medicalVolume object for the image volume stored in the single DICOM, NIfTI, or NRRD file or list of DICOM files specified by filenames.

medVol = medicalVolume(sourceTable) creates a medicalVolume object for the image volume listed in sourceTable. The table must contain only one row that specifies the metadata for a DICOM volume.

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

medVol = medicalVolume(imds) creates a medicalVolume object for the image volume specified by the image datastore object imds.

medVol = medicalVolume(voxels,VolumeGeometry) creates a medicalVolume by directly specifying the Voxels and VolumeGeometry properties.

Input Arguments

dirname — Name of directory containing medical image volume data

string scalar | character vector

Name of the directory containing the medical image volume data, specified as a string scalar or a character vector. Specify dirname as the name of a directory containing multiple DICOM files corresponding to one image volume.

filenames — Name of file or files containing medical image volume data

string scalar | character vector | string array

Name of the file or files containing the medical image volume data, specified as a string scalar, character vector, or string array. Specify filenames as a single DICOM, NIfTI, or NRRD file or as a list of DICOM files corresponding to one image volume.

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 table row, specified as a string scalar, character vector, or positive integer. Specify rowname as a string scalar or character vector to specify a row of sourceTable by name. Specify rowname as a positive integer to specify a row by its numeric index.

imds — Datastore specifying list of DICOM files containing medical image volume data

ImageDatastore object

Datastore specifying a list of DICOM files containing medical image volume data, specified as an ImageDataStore object. The list of files must correspond to one medical image volume.

Properties

Voxels — Image voxel values

m-by-n-by-p numeric array | N-D numeric array

Image voxel values, specified as an m-by-n-by-p numeric array or an N-D numeric array. The first three dimensions of Voxels correspond to the spatial dimensions of the patient coordinate system.

For DICOM files, medicalVolume rescales the intensity values using the RescaleIntercept and RescaleSlope metadata attributes, if they are present in the file. Additionally, medicalVolume converts DICOM intensities of data type uint16 to data type int16 or single.

• If the RescaleSlope attribute value is unspecified or an integer, then medicalVolume converts the intensity values from uint16 to int16.

• If the RescaleSlope attribute value is fractional, then medicalVolume converts the intensity values from uint16 to single.

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

VolumeGeometry — Spatial referencing information

medicalref3d object

Spatial referencing information, specified as a medicalref3d object. The coordinates and distances specified by VolumeGeometry are in the units specified by the SpatialUnits property, if available in the file metadata.

SpatialUnits — Real-world spatial units

"unknown" (default) | string scalar

Real-world spatial units, specified as a string scalar or a character vector. If the data source is a DICOM file, then the SpatialUnits value is "mm" (millimeters). If the data source is a NIfTI or NRRD file, the object extracts the spatial units from the SpaceUnits or spaceunits metadata attribute, respectively, if present in the file.

Data Types: string

VoxelSpacing — Distances between voxel centers in each dimension

1-by-3 numeric vector

This property is read-only.

Distances between voxel centers in each dimension, specified as a 1-by-3 numeric vector. The values of VoxelSpacing are in the units specified by the SpatialUnits property. If VolumeGeometry.IsAffine is false, then the object calculates the spacing for each dimension as the average spacing across all slices.

Data Types: double

Orientation — Slice plane with greatest spatial resolution

"coronal" | "mixed" | "oblique" | "sagittal" | "tranverse" | "unknown"

This property is read-only.

Slice plane with the greatest spatial resolution, specified as one of these values:

• "coronal" — Coronal plane.

• "sagittal" — Sagittal plane.

• "transverse" — Transverse plane.

• "mixed" — Image volume slices are not parallel. This value occurs when the IsMixed property of the VolumeGeometry object is true.

• "oblique" — Image slices are not aligned with the anatomical axes.

• "unknown" — Mapping between image coordinate system and anatomical axes is unknown. This value occurs when the PatientCoordinateSystem property of the VolumeGeometry object is "unknown".

Data Types: string

NumCoronalSlices — Number of slices in coronal direction

numeric scalar | []

This property is read-only.

Number of slices in the coronal direction, specified as a numeric scalar or empty array. NumCoronalSlices is empty in these cases:

• PatientCoordinateSystem property of the VolumeGeometry object is "unknown".

• Image volume is oblique.

• Image volume contains a temporal dimension with multiple slices at each spatial location.

Data Types: double

NumSagittalSlices — Number of slices in sagittal direction

numeric scalar | []

This property is read-only.

Number of slices in the sagittal direction, specified as a numeric scalar or empty array. NumSagittalSlices is empty in these cases:

• PatientCoordinateSystem property of the VolumeGeometry object is "unknown".

• Image volume is oblique.

• Image volume contains a temporal dimension with multiple slices at each spatial location.

Data Types: double

NumTransverseSlices — Number of slices in transverse direction

numeric scalar | []

This property is read-only.

Number of slices in the transverse direction, specified as a numeric scalar or empty array. NumTransverseSlices is empty in these cases:

• PatientCoordinateSystem property of the VolumeGeometry object is "unknown".

• Image volume is oblique.

• Image volume contains a temporal dimension with multiple slices at each spatial location.

Data Types: double

PlaneMapping — Mapping between image data dimensions and anatomical planes

1-by-3 string array

This property is read-only.

Mapping between image data dimensions and anatomical planes, specified as a 1-by-3 string array. If the spatial referencing information is available in the source file, PlaneMapping contains the strings "transverse", "coronal", and "sagittal". For example, if the first element of PlaneMapping is "coronal", then moving along the first dimension of Voxels corresponds to moving between slices in the coronal plane.

If the PatientCoordinateSystem property of the VolumeGeometry object is "unknown", or if the volume is oblique, the values of PlaneMapping are "unknown" or "oblique", respectively.

Example: ["transverse","coronal","sagittal"]

Data Types: string

NormalVector — Unit vector normal to first slice of image volume

1-by-3 numeric vector

This property is read-only.

Unit vector normal to the first slice of the image volume, specified as a 1-by-3 numeric vector. The first slice of the volume corresponds to the points stored in Voxels(:,:,1).

Data Types: double

Modality — Imaging modality used to capture image volume data

"unknown" (default) | string scalar

This property is read-only.

Imaging modality used to capture the image volume data, specified as a string scalar. The modality is extracted from the file metadata, if present. Common values include, but are not limited to, "CT" for computed tomography, "MR" for magnetic resonance, "NM" for nuclear medicine, and "US" for ultrasound. If the modality is not specified in the file metadata, the default value is "unknown".

Data Types: string

WindowCenters — Center of display range window of each slice

[] (default) | p-by-1 numeric vector

This property is read-only.

Center of the display range window for each slice, specified as a p-by-1 numeric vector, where p is the number of slices in the image volume along the third dimension. The object extracts the WindowCenters property value from the file metadata, if available. If the display window metadata is not available, then WindowCenters is empty.

Data Types: double

WindowWidths — Width of display window of each slice

[] (default) | p-by-1 numeric vector

This property is read-only.

Width of display window of each slice, specified as a p-by-1 numeric vector, where p is the number of slices in the image volume along the third dimension. The object extracts the WindowWidths property value from the file metadata, if available. If the display window metadata is not available, then WindowWidths is empty.

Data Types: double

Object Functions

extractSlice	Extract voxels and spatial details for one slice of medical volume
replaceSlice	Replace voxel values for one slice of medical volume
resample	Resample medical image volume in different patient coordinate system
sliceCorners	Extract coordinates of corner voxels for one slice of medical volume
sliceLimits	Extract X-, Y-, Z-limits for one slice of medical volume
volshow	Display medical volume in patient coordinates
montage	Display medical image slices or frames as montage in patient coordinates
write	Write affine medical volume data to NIfTI file

Examples

Create Medical Volume Object for Multifile DICOM File

Create a medical volume object using 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. Download the data set from the MathWorks® website, then unzip the folder.

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

Specify the directory of DICOM files for the first CT volume in the data set.

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

Create a medical volume object 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]

Create Medical Volume Object from Filename

Create a medical volume object using a CT chest volume from the Medical Segmentation Decathlon data set [1]. Download the MedicalVolumNIfTIData.zip file from the MathWorks website, then unzip the file. The file contains two CT chest volumes and corresponding label images, stored in the NIfTI file format. The size of the data file is approximately 76 MB.

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

Specify the file name of the first CT volume.

filePath = fullfile(dataFolder,"lung_027.nii.gz");

Create a medical volume object for the CT volume.

medVol = medicalVolume(filePath)

medVol = 
  medicalVolume with properties:

                 Voxels: [512×512×264 single]
         VolumeGeometry: [1×1 medicalref3d]
           SpatialUnits: "mm"
            Orientation: "transverse"
           VoxelSpacing: [0.8594 0.8594 1.2453]
           NormalVector: [0 0 -1]
       NumCoronalSlices: 512
      NumSagittalSlices: 512
    NumTransverseSlices: 264
           PlaneMapping: ["sagittal"    "coronal"    "transverse"]
               Modality: "unknown"
          WindowCenters: 0
           WindowWidths: 0

[1] Medical Segmentation Decathlon. "Lung." Tasks. Accessed May 10, 2018. http://medicaldecathlon.com/.

The Medical Segmentation Decathlon data set is provided under the CC-BY-SA 4.0 license. All warranties and representations are disclaimed. See the license for details.

Create Medical Volume Object from DICOM Collection

Create a medical volume object using 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. Download the data set from the MathWorks website, then unzip the folder.

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

Specify the directory of DICOM files for the first CT volume in the data set.

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

Gather the details about the DICOM files in the dataFolder directory into a table by using the dicomCollection function. The files belong to one CT volume series, so the table has one row.

sourceTable = dicomCollection(dataFolder);

Create a medical volume object for the CT volume by specifying the single-row DICOM collection table.

medVol = medicalVolume(sourceTable)

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]

Create Medical Volume Object from Specified Row of DICOM Collection

Create a medical volume object using a data set containing three chest CT scans. Each CT scan is saved as a directory of DICOM files. The size of the data set is approximately 81 MB. Download the data set from the MathWorks website, then unzip the folder.

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

Gather the details about the DICOM files in the dataFolder directory into a table by using the dicomCollection function. The table contains three rows, each corresponding to one of three CT DICOM series.

sourceTable = dicomCollection(dataFolder);

Create a medical volume object for the second CT volume by specifying the DICOM collection table and a numeric row index.

medVol = medicalVolume(sourceTable,2)

medVol = 
  medicalVolume with properties:

                 Voxels: [512×512×88 int16]
         VolumeGeometry: [1×1 medicalref3d]
           SpatialUnits: "mm"
            Orientation: "transverse"
           VoxelSpacing: [0.7617 0.7617 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]

Create Medical Volume Object from Image Datastore

Create a medical volume object using 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. Download the data set from the MathWorks website, then unzip the folder.

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

Specify the directory of DICOM files for the first CT volume in the data set.

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

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

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

Create a medical volume object for the CT volume.

medVol = medicalVolume(dicomds)

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]

Create Medical Volume Object from Voxels and Spatial Details

Create a medical volume object using 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. Download the data set from the MathWorks website, then unzip the folder.

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

Specify the directory of DICOM files for the first CT volume in the data set.

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

Create a medical volume object for the CT volume.

medVol = medicalVolume(dataFolder);

The Voxels property contains the intensity values of each voxel. The VolumeGeometry property contains a medicalref3d object defining the spatial referencing for the image volume.

V = medVol.Voxels;
R = medVol.VolumeGeometry;

Modify the voxel data by applying a 3-D Gaussian filter.

sigma = 2;
filterV = imgaussfilt3(V,sigma);

Create a new medicalVolume object that contains the smoothed voxel values. To maintain the same spatial referencing as the original volume, specify the original medicalref3d object R.

medVolFiltered = medicalVolume(filterV,R);

Display Medical Image Volume in Slice Viewer

Run this code to download a data set from the MathWorks® website and unzip the downloaded folder. The data set contains three CT volumes that are each saved as a directory of DICOM files. The size of the entire data set is approximately 81 MB.

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

The folder dataFolder contains the downloaded scan used by this example, LungCT01.

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

Create a medical image volume object that contains the image data and spatial referencing information for the CT volume. The Orientation property indicates that the primary slice direction is "transverse".

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]

View the transverse slices of the volume in the slice viewer. By default, the viewer uses the properties of medVol to scale anisotropic voxels, set the intensity display range, and orient slices. The viewer opens on the center slice. Use the scroll bar to navigate to other slices.

sv = sliceViewer(medVol,Parent=figure)

sv = 
  sliceViewer with properties:

             SliceDirection: [0 0 1]
                SliceNumber: 45
                     Parent: [1×1 Panel]
                   Colormap: [256×3 double]
               DisplayRange: [-160 240]
               ScaleFactors: [1 1 1]
    DisplayRangeInteraction: 'on'

Create Medical Volume Object from Voxels

Since R2024a

Read the voxels of an MRI volume from a TIFF file using the tiffreadVolume function.

voxels = tiffreadVolume("mri.tif");

Create a medicalref3d object containing the volume geometry using only the volume size of the MRI volume.

volGeometry = medicalref3d(size(voxels))

volGeometry = 
  medicalref3d with properties:

                 VolumeSize: [128 128 27]
                   Position: [27x3 double]
             VoxelDistances: {[1 0 0]  [0 1 0]  [0 0 1]}
    PatientCoordinateSystem: ["Unknown"]
               PixelSpacing: [1 1]
                   IsAffine: [1]
              IsAxesAligned: [1]
                    IsMixed: [0]

Specify a patient coordinate system for visualization.

volGeometry.PatientCoordinateSystem = "LPS+";

Create a medicalVolume object using the voxel data and the volume geometry.

medVol = medicalVolume(voxels,volGeometry)

medVol = 
  medicalVolume with properties:

                 Voxels: [128x128x27 uint8]
         VolumeGeometry: [1x1 medicalref3d]
           SpatialUnits: "unknown"
            Orientation: "transverse"
           VoxelSpacing: [1 1 1]
           NormalVector: [0 0 1]
       NumCoronalSlices: 128
      NumSagittalSlices: 128
    NumTransverseSlices: 27
           PlaneMapping: ["sagittal"    "coronal"    "transverse"]
               Modality: "unknown"
          WindowCenters: []
           WindowWidths: []

Visualize a slice of the medical volume.

slice = extractSlice(medVol,15,"transverse");
figure
imshow(slice)

Version History

Introduced in R2022b

R2023a: The medicalVolume object converts DICOM intensities from unsigned to signed values

When reading DICOM files, the medicalVolume object converts intensity values of data type uint16 to data type int16 or single. If the DICOM file specifies the RescaleIntercept and RescaleSlope metadata attributes, medicalVolume converts the values before rescaling them. By converting unsigned uint16 values to signed values before rescaling, the new behavior preserves the full data range of the rescaled intensities, including negative values.

• If the RescaleSlope attribute value is unspecified or an integer, then medicalVolume converts the intensities from uint16 to int16.

• If the RescaleSlope attribute value is fractional, then medicalVolume converts the intensities from uint16 to single.

In R2022b, medicalVolume stored intensity values as the same data type as in the DICOM file. For DICOM files that stored intensities as data type uint16, medicalVolume limited rescaled values to the range [0, 2¹⁶-1], and set all negative intensities to 0 before storing them in the Voxels property.