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 identifies the correct order of the images and creates a 4-D volume.

Note

If the input is a DICOM volume, then the function returns the volume data after checking the order of the image slices in the input volume. When the image slices are not in the appropriate order, the function corrects the order before returning the output.

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 nonisotropic 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(fullfile(matlabroot,"toolbox/images/imdata/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);
alphamap = interp1(intensity,alpha,queryPoints)';
colormap = interp1(intensity,color,queryPoints);

Customize the display panel.

ViewPnl = uipanel(figure,"Title","4-D Dicom Volume");

View the volume with the custom colormap and transparency map.

volshow(V,"Colormap",colormap,"Alphamap",alphamap,"Parent",ViewPnl);

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(fullfile(matlabroot,"toolbox/images/imdata"));

Display the table. The table has multiple rows, with each row containing the metadata for the DICOM image sets present in the specified folder.

sourcetable

sourcetable=6×14 table
               StudyDateTime               SeriesDateTime           PatientName      PatientSex     Modality     Rows    Columns    Channels    Frames    StudyDescription    SeriesDescription                             StudyInstanceUID                                                     SeriesInstanceUID                                                      Filenames                         
          ________________________    ________________________    _______________    __________    __________    ____    _______    ________    ______    ________________    _________________    __________________________________________________________________    __________________________________________________________________    ___________________________________________________________

    s1    {0×0 double            }    {0×0 double            }    ""                    ""         "RTSTRUCT"      0         0         0           1      ""                  ""                   "1.2.826.0.1.3680043.8.274.1.1.2729954696.96242.3632970675.507"       "1.2.826.0.1.3680043.8.274.1.1.7145442384.75872.7982248107.258"       {["B:\matlab\toolbox\images\imdata\rtstruct.dcm"         ]}
    s2    {[30-Apr-1993 11:27:24]}    {[30-Apr-1993 11:27:24]}    "Anonymized"          ""         "CT"          512       512         1           1      "RT ANKLE"          ""                   "1.2.840.113619.2.1.1.322987881.621.736170080.681"                    "1.2.840.113619.2.1.2411.1031152382.365.736169244"                    {["B:\matlab\toolbox\images\imdata\CT-MONO2-16-ankle.dcm"]}
    s3    {[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                                              }
    s4    {[03-Oct-2011 19:18:11]}    {[03-Oct-2011 18:59:02]}    ""                    "M"        "MR"          512       512         1           1      "RIGHT KNEE"        ""                   "1.3.6.1.4.1.9590.100.1.2.320418845013189618318250681693358291211"    "1.3.6.1.4.1.9590.100.1.2.287740981712351622214874344032214809569"    {["B:\matlab\toolbox\images\imdata\knee1.dcm"            ]}
    s5    {[03-Oct-2011 19:18:11]}    {[03-Oct-2011 19:05:04]}    ""                    "M"        "MR"          512       512         1           1      "RIGHT KNEE"        ""                   "1.3.6.1.4.1.9590.100.1.2.320498134711034521212730362051554545799"    "1.3.6.1.4.1.9590.100.1.2.316302984111738034326701385064023497963"    {["B:\matlab\toolbox\images\imdata\knee2.dcm"            ]}
    s6    {[30-Jan-1994 11:25:01]}    {0×0 double            }    "Anonymized"          ""         "US"          430       600         1          10      "Echocardiogram"    "PS LAX MR & AI"     "999.999.3859744"                                                     "999.999.94827453"                                                    {["B:\matlab\toolbox\images\imdata\US-PAL-8-10x-echo.dcm"]}

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

V = dicomreadVolume(sourcetable,"s3","MakeIsotropic",true);
V = squeeze(V);

Display the isotropic 4-D DICOM volume by using the volshow function. Generate a colormap and transparency map for 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);
alphamap = interp1(intensity,alpha,queryPoints)';
colormap = interp1(intensity,color,queryPoints);

Customize the display panel.

ViewPnl = uipanel(figure,"Position",[0 0 1 1],"Title","Isotropic 4-D Dicom Volume");

View the volume with the custom colormap and transparency map.

volshow(V,"Colormap",colormap,"Alphamap",alphamap,"CameraPosition",[3 3 4],"Parent",ViewPnl);

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 nonisotropic 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.

Version History

Introduced in R2017b