dicomreadVolume

Create 4-D volume from set of DICOM images

collapse all in page

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.

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

Create Volumetric Image from DICOM Files

Open Live Script

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

Create Isotropic 4-D DICOM Volume

Open Live Script

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

`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

collapse all

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

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

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

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

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

expand all

R2024b: Support for thread-based environments

dicomreadVolume now supports thread-based environments.

dicomreadVolume

Syntax

Description

Examples

Create Volumetric Image from DICOM Files

Create Isotropic 4-D DICOM Volume

Input Arguments

source — Volume data folder or files string scalar | character vector | string array | cell array of character vectors

sourceTable — Collection of DICOM file metadata table

rowname — Name of table row string scalar | character vector

tf — Create isotropic volume false or 0 (default) | true or 1

Output Arguments

V — 4-D DICOM volume numeric array

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

dim — Dimension with largest offset 1 | 2 | 3

Extended Capabilities

Thread-Based Environment Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Version History

R2024b: Support for thread-based environments

See Also

`source` — Volume data folder or files
string scalar | character vector | string array | cell array of character vectors

`sourceTable` — Collection of DICOM file metadata
table

`rowname` — Name of table row
string scalar | character vector

`tf` — Create isotropic volume
`false` or `0` (default) | `true` or `1`

`V` — 4-D DICOM volume
numeric array

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

`dim` — Dimension with largest offset
`1` | `2` | `3`

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.