dicomreadVolume

Create 4-D volume from set of DICOM images

Syntax

V = dicomreadVolume(source)

V = dicomreadVolume(sourceTable)

V = dicomreadVolume(sourceTable,rowname)

V = dicomreadVolume(___,"MakeIsotropic",tf)

[V,spatial] = dicomreadVolume(___)

[V,spatial,dim] = dicomreadVolume(___)

Description

V = dicomreadVolume(source) creates a 4-D volume, V, from a set of Digital Imaging and Communications in Medicine (DICOM) files specified by source. The dicomreadVolume function automatically orders the image slices of the 4-D volume in the correct order.

V = dicomreadVolume(sourceTable) creates a 4-D DICOM volume from the input file listed in sourceTable. The table must contain only one row that specifies the metadata for a DICOM volume.

V = dicomreadVolume(sourceTable,rowname) creates a 4-D DICOM volume from the input file listed in rowname of the multirow table. Use this syntax when sourceTable contains multiple rows.

V = dicomreadVolume(___,"MakeIsotropic",tf) creates an isotropic 4-D DICOM volume from the input DICOM image data using any combination of the input arguments from previous syntaxes. Use this syntax to create an isotropic DICOM volume from a set of anisotropic DICOM image data.

[V,spatial] = dicomreadVolume(___) also returns a structure, spatial, that describes the location, resolution, and orientation of the input DICOM data.

[V,spatial,dim] = dicomreadVolume(___) also returns the dimension that has the largest amount of offset between two adjacent slices in the input DICOM data.

Examples

Create Volumetric Image from DICOM Files

Load volume data from a folder containing DICOM image files. Use the squeeze function to remove any singleton dimensions.

[V,spatial,dim] = dicomreadVolume("dog");
V = squeeze(V);

Display the 4-D DICOM volume. Generate a colormap and transparency map for magnetic resonance (MR) images.

intensity = [0 20 40 120 220 1024];
alpha = [0 0 0.15 0.3 0.38 0.5];
color = ([0 0 0; 43 0 0; 103 37 20; 199 155 97; 216 213 201; 255 255 255])/ 255;
queryPoints = linspace(min(intensity),max(intensity),256);
amap = interp1(intensity,alpha,queryPoints)';
cmap = interp1(intensity,color,queryPoints);

View the volume with the custom colormap and transparency map.

volshow(V,Colormap=cmap,Alphamap=amap);

Display the returned spatial structure from dicomreadVolume. The structure contains spatial information about the input DICOM image files.

spatial

spatial = struct with fields:
       PatientPositions: [22×3 double]
          PixelSpacings: [22×2 double]
    PatientOrientations: [2×3×22 double]
              ImageSize: [512 512 22]

Display the dimension information from dicomreadVolume. The value specifies that the slice offset is largest along the z-dimension.

dim

dim = 3

Create Isotropic 4-D DICOM Volume

Gather details about the DICOM files contained in a folder by using the dicomCollection function. The function returns the details of the available DICOM metadata in the form of a table.

sourceTable = dicomCollection("dog");

Display the table. Each row contains the metadata for the a DICOM image set present in the specified folder.

sourceTable

sourceTable=1×14 table
             StudyDateTime           SeriesDateTime         PatientName      PatientSex    Modality    Rows    Columns    Channels    Frames    StudyDescription    SeriesDescription                        StudyInstanceUID                                             SeriesInstanceUID                          Filenames  
          ____________________    ____________________    _______________    __________    ________    ____    _______    ________    ______    ________________    _________________    _________________________________________________________    _________________________________________________________    _____________

    s1    14-Dec-2013 15:47:31    14-Dec-2013 15:54:33    "GORBERG MITZI"       "F"          "MR"      512       512         1          22           "CSP"               "AX T2"         "1.2.840.113619.2.244.3596.11880862.13689.1386517653.214"    "1.2.840.113619.2.244.3596.11880862.13689.1386517653.217"    {22×1 string}

Create a 4-D DICOM volume from a DICOM image set in the table. Specify the row name that contains the desired DICOM image set. To create an isotropic volume, specify the MakeIsotropic name-value argument as true. Use the squeeze function to remove any singleton dimensions.

V = dicomreadVolume(sourceTable,"s1",MakeIsotropic=true);
V = squeeze(V);

Generate a colormap and transparency map for MRI images.

intensity = [0 20 40 120 220 1024];
alpha = [0 0 0.15 0.3 0.38 0.5];
color = ([0 0 0; 43 0 0; 103 37 20; 199 155 97; 216 213 201; 255 255 255])/255;
queryPoints = linspace(min(intensity),max(intensity),256);
amap = interp1(intensity,alpha,queryPoints)';
cmap = interp1(intensity,color,queryPoints);

Display the isotropic 4-D DICOM volume with the custom colormap and transparency map by using the volshow function.

vol = volshow(V,Colormap=cmap,Alphamap=amap);

Input Arguments

source — Volume data folder or files

string scalar | character vector | string array | cell array of character vectors

Volume data folder or files, specified as a string scalar, character vector, string array, or cell array of character vectors.

Data Types: char | string

sourceTable — Collection of DICOM file metadata

table

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

Data Types: table

rowname — Name of table row

string scalar | character vector

Name of the table row, specified as a string scalar or character vector. The name identifies one of the rows in the multirow table specified in sourceTable.

Data Types: char | string

tf — Create isotropic volume

false or 0 (default) | true or 1

Create an isotropic volume, specified as a logical 0 (false) or 1 (true).

• false or 0 — Create a 4-D DICOM volume from the input data.

• true or 1 — Create an isotropic 4-D DICOM volume.

The input data specified by source can be either isotropic or anisotropic DICOM data.

Output Arguments

V — 4-D DICOM volume

numeric array

4-D DICOM volume, returned as a numeric array.

The dimensions of V are [rows, columns, samples, slices], where samples is the number of color channels per voxel. For example, grayscale volumes have one sample, and RGB volumes have three samples. Use the squeeze function to remove any singleton dimensions, such as when the sample is 1.

spatial — Location, resolution, and orientation of input DICOM images

structure

Location, resolution, and orientation of slices collected from the metadata of the input DICOM images, returned as a structure with these fields.

Field	Description
PatientPositions	(x, y, z) coordinate of the first pixel in each slice, measured in millimeters from the origin of the scanner coordinate system.
PixelSpacings	Distance between neighboring rows and columns within each slice, in millimeters.
PatientOrientations	Pair of direction-cosine triplets that designate the direction of the rows and columns in each slice relative to the patient position.

For more information about DICOM attributes, see part 3 of the DICOM standard, section C.7.6.2.

dim — Dimension with largest offset

1 | 2 | 3

Dimension with the largest offset, returned as 1, 2, or 3. The value denotes the dimension in a 3-D coordinate system that has the largest amount of offset between adjacent slices in the input DICOM data.

• If the largest offset is along the x dimension, then dim is 1.

• If the largest offset is along the y dimension, then dim is 2.

• If the largest offset is along the z dimension, then dim is 3.

Extended Capabilities

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 R2017b

R2024b: Support for thread-based environments

dicomreadVolume now supports thread-based environments.