dicomread

Read DICOM image

Syntax

X = dicomread(filename)

X = dicomread(info)

X = dicomread(___,"frames",f)

X = dicomread(___,Name,Value)

[X,cmap] = dicomread(___)

[X,cmap,alpha] = dicomread(___)

[X,cmap,alpha,overlays] = dicomread(___)

Description

X = dicomread(filename) reads the image data from the compliant Digital Imaging and Communications in Medicine (DICOM) file filename. To read a group of DICOM files that contain a series of images that comprise a volume, use dicomreadVolume.

X = dicomread(info) reads DICOM image data from the message referenced in the DICOM metadata structure info.

X = dicomread(___,"frames",f) reads only the specified frames f from the image, using any combination of input arguments from previous syntaxes.

X = dicomread(___,Name,Value) reads DICOM image data using name-value arguments to configure the parser.

[X,cmap] = dicomread(___) also returns the colormap, cmap.

[X,cmap,alpha] = dicomread(___) also returns alpha, an alpha channel matrix for X.

[X,cmap,alpha,overlays] = dicomread(___) also returns any overlays from the DICOM file.

Examples

Read DICOM Files

Read an indexed image from a DICOM file and display it using montage.

[X,map] = dicomread("US-PAL-8-10x-echo.dcm");
montage(X,map,"Size",[2 5]);

Read an image from another DICOM file and display it using imshow.

info = dicominfo("CT-MONO2-16-ankle.dcm");
Y = dicomread(info);
figure
imshow(Y,[]);

Input Arguments

filename — Name of DICOM file

character vector | string scalar

Name of the DICOM file, specified as a character vector or string scalar.

Data Types: char | string

info — DICOM metadata

structure

DICOM metadata, specified as a structure. You can create an info structure by using the dicominfo function.

f — Frames to read

"all" (default) | positive integer scalar | vector of positive integers

Frames to read, specified as a positive integer scalar, a vector of positive integers, or "all". When f is numeric, dicomread reads only the frames of the specified numbers from the image. By default, dicomread reads all frames of the DICOM image.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: dicomread("CT-MONO2-16-ankle.dcm",UseVRHeuristic=false) reads the image data from the DICOM file without using a heuristic.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: dicomread("CT-MONO2-16-ankle.dcm","UseVRHeuristic",false) reads the image data from the DICOM file without using a heuristic.

UseVRHeuristic — Read noncompliant DICOM files that switch VR modes incorrectly

true or 1 (default) | false or 0

Read noncompliant DICOM files that switch value representation (VR) modes incorrectly, specified as a logical 1 (true) or 0 (false).

When set to true, dicomread uses a heuristic to help read certain noncompliant DICOM files that switch VR modes incorrectly. dicomread displays a warning if it uses this heuristic. If this heuristic is enabled, a small number of compliant files are not read correctly. Set UseVRHeuristic to false to read these compliant files.

Data Types: logical

Output Arguments

X — DICOM image

m-by-n matrix | m-by-n-by-3 array | 4-D array

DICOM image, returned as one of these options:

• An m-by-n matrix representing a single-frame grayscale image, or an indexed image.

• An m-by-n-by-3 array representing a single-frame truecolor (RGB) image.

• A 4-D array representing a multiframe image.

Data Types: int8 | int16 | uint8 | uint16

cmap — Colormap

c-by-3 matrix | []

Colormap associated with image X, returned as one of these options:

• If X is an indexed image, then cmap is returned as a c-by-3 numeric matrix with values in the range [0, 1]. Each row is a three-element RGB triplet that specifies the red, green, and blue components of a single color of the colormap.

• If X is a grayscale or truecolor image, then cmap is empty ([]).

Data Types: double

alpha — Alpha channel matrix

m-by-n matrix of nonnegative integers | 4-D array of nonnegative integers

Alpha channel matrix for image X, returned as an m-by-n matrix or 4-D array of nonnegative integers. The values of alpha are 0 if the pixel is opaque. Otherwise, they are row indices into cmap. To use alpha, you should substitute the RGB value in cmap for the value in X. The alpha output has the same height and width as X, and is 4-D for a multiframe image. alpha has the same data type as X.

Data Types: int8 | int16 | uint8 | uint16

overlays — Overlays

binary m-by-n matrix | binary 4-D array | []

Overlays from the DICOM file, returned as an m-by-n matrix or 4-D array of binary values. Each overlay is a 1-bit black and white image with the same height and width as X. If multiple overlays are present in the file, then overlays is a 4-D multiframe image. If no overlays are in the file, then overlays is empty ([]).

Data Types: logical

More About

Supported Transfer Syntax UIDs

The dicomread function reads files with these pixel formats and transfer syntax UIDs:

Pixel Format	Transfer Syntax UID
Implicit VR Little Endian	1.2.840.10008.1.2
Explicit VR Little Endian	1.2.840.10008.1.2.1
Explicit VR Big Endian	1.2.840.10008.1.2.2
JPEG Baseline (Process 1)	1.2.840.10008.1.2.4.50
JPEG Extended (Process 2 & 4)	1.2.840.10008.1.2.4.51
JPEG Spectral Selection, Non-Hierarchical (Process 6 & 8)	1.2.840.10008.1.2.4.53
JPEG Full Progression, Non-Hierarchical (Process 10 & 12)	1.2.840.10008.1.2.4.55
JPEG Lossless, Non-Hierarchical (Process 14)	1.2.840.10008.1.2.4.57
JPEG Extended, Hierarchical (Process 16 & 18)	1.2.840.10008.1.2.4.59
JPEG Spectral Selection, Hierarchical (Process 20 & 22)	1.2.840.10008.1.2.4.61
JPEG Full Progression, Hierarchical (Process 24 & 26)	1.2.840.10008.1.2.4.63
JPEG Lossless, Hierarchical (Process 28)	1.2.840.10008.1.2.4.65
JPEG Lossless, Non-Hierarchical, First-Order Prediction (Process 14 [Selection Value 1])	1.2.840.10008.1.2.4.70
RLE Lossless	1.2.840.10008.1.2.5
GE Implicit VR Little Endian Except Big Endian Pixels	1.2.840.113619.5.2
MPEG2 Main Profile / Main Level	1.2.840.10008.1.2.4.100
MPEG2 Main Profile / High Level	1.2.840.10008.1.2.4.101
MPEG-4 AVC/H.264 High Profile / Level 4.1	1.2.840.10008.1.2.4.102
MPEG-4 AVC/H.264 BD-compatible High Profile / Level 4.1	1.2.840.10008.1.2.4.103
MPEG-4 AVC/H.264 High Profile / Level 4.2 For 2D Video	1.2.840.10008.1.2.4.104
MPEG-4 AVC/H.264 High Profile / Level 4.2 For 3D Video	1.2.840.10008.1.2.4.105
MPEG-4 AVC/H.264 Stereo High Profile / Level 4.2	1.2.840.10008.1.2.4.106
HEVC/H.265 Main Profile / Level 5.1	1.2.840.10008.1.2.4.107
HEVC/H.265 Main 10 Profile / Level 5.1	1.2.840.10008.1.2.4.108

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 before R2006a

R2024b: Support for thread-based environments

dicomread now supports thread-based environments.

R2022b: Support for reading video data

The dicomread function now supports reading DICOM files that contain video data with MPEG-2, MPEG-4/H.264 and HEVC/H.265 encoding. Because MATLAB^® decodes video data using the codecs installed on your computer, some files might not able to be read on all platforms. For more details, see Supported Video and Audio File Formats.