Main Content

dicomreadVolume

Create 4-D volume from set of DICOM images

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.

example

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.

example

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.

example

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

example

Examples

collapse all

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);

Figure contains an object of type images.ui.graphics3d.viewer3d.

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

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);

Figure contains an object of type images.ui.graphics3d.viewer3d.

Input Arguments

collapse all

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

Data Types: char | string

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

Data Types: table

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

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

collapse all

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.

4-D array depicted as groups of 3-D grayscale volumes of size rows-by-colums-by-samples.

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

FieldDescription
PatientPositions(x, y, z) coordinate of the first pixel in each slice, measured in millimeters from the origin of the scanner coordinate system.
PixelSpacingsDistance between neighboring rows and columns within each slice, in millimeters.
PatientOrientationsPair 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.

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.

3-D representation of DICOM image slices

  • 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

Version History

Introduced in R2017b

expand all