dicomwrite

Write images as DICOM files

Syntax

dicomwrite(X,filename)

dicomwrite(X,cmap,filename)

dicomwrite(___,meta_struct)

dicomwrite(___,info)

dicomwrite(___,"ObjectType",IOD)

dicomwrite(___,"SOPClassUID",UID)

dicomwrite(___,Name,Value)

status = dicomwrite(___)

Description

dicomwrite(X,filename) writes the binary, grayscale, or truecolor image X to the file filename. The dicomwrite function creates a Digital Imaging and Communications in Medicine (DICOM) file or a Digital Imaging and Communication in Security (DICOS) file. This syntax writes a file with the necessary metadata for the Secondary Capture DICOM Information Object (IOD).

dicomwrite(X,cmap,filename) writes the indexed image X with colormap cmap.

dicomwrite(___,meta_struct) specifies optional metadata or file options in the structure meta_struct, in addition to any combination of arguments from previous syntaxes. The names of fields in meta_struct must be the names of DICOM file attributes or options. The value of a field is the value you want to assign to the attribute or option.

dicomwrite(___,info) specifies metadata in the metadata structure info, which is produced by the dicominfo function.

dicomwrite(___,"ObjectType",IOD) writes a file containing the necessary metadata for a particular type of DICOM Information Object (IOD). For the supported IODs, dicomwrite verifies that all required metadata attributes are present for the specified IOD, creates missing attributes if necessary, and specifies default values where possible. Additionally, dicomwrite removes attributes that are not part of the DICOM specification for the specified IOD. For more information, see Tips.

dicomwrite(___,"SOPClassUID",UID) writes a file containing the necessary metadata for a particular type of IOD, specified using a DICOM Unique Identifier (UID).

dicomwrite(___,Name,Value) specifies additional options using name-value arguments. You can also use this syntax to specify individual metadata attributes and their values to write to the DICOM file. To find a list of the DICOM attributes that you can specify, see the data dictionary file, dicom-dict.txt, included with the Image Processing Toolbox™ software. Enclose each attribute name in quotes.

status = dicomwrite(___) returns information about the metadata and the descriptions used to generate the DICOM file. This syntax can be useful when you specify an info structure to the dicomwrite function.

Examples

Write Data to DICOM File

Read a CT image from a DICOM file.

X = dicomread("CT-MONO2-16-ankle.dcm");

Write the CT image to a file, creating a secondary capture image. This operation creates a DICOM file with the necessary metadata attributes for the Secondary Capture DICOM Information Object (IOD).

dicomwrite(X,"sc_file.dcm");

Write the CT image to a DICOM file along with its metadata. Use the dicominfo function to retrieve the metadata from the DICOM file. By default, the dicomwrite function verifies that the metadata attributes in the new file are compliant with the Secondary Capture IOD standard.

metadata = dicominfo("CT-MONO2-16-ankle.dcm");
dicomwrite(X,"ct_file.dcm",metadata);

Write X to another DICOM file with a direct copy of its metadata. When you set the CreateMode parameter to "copy", dicomwrite does not verify the metadata written to the file.

dicomwrite(X,"ct_copy.dcm",metadata,"CreateMode","copy");

Input Arguments

X — DICOM image

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

DICOM image, specified 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.

Note

If X is empty, then the dicomwrite function writes a DICOM file with empty image data. The metadata attributes for the DICOM file are either set to default values or copied from meta_struct, if CreateMode is specified as "Copy".

Data Types: int8 | int16 | uint8 | uint16

cmap — Colormap

c-by-3 matrix

Colormap associated with the indexed image X, specified 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.

Data Types: double

filename — Name of DICOM file to write to

character vector | string scalar

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

Data Types: char | string

meta_struct — Optional metadata or file options

structure

Optional metadata or file options, specified as a structure. The names of the fields in meta_struct must be the names of DICOM file attributes or options. The value of a field is the value you want to assign to the attribute or option.

info — Metadata produced by dicominfo function

structure

Metadata produced by the dicominfo function, specified as a structure.

IOD — DICOM Information Object

"Secondary Capture Image Storage" (default) | "CT Image Storage" | "MR Image Storage"

DICOM Information Object, specified as "Secondary Capture Image Storage", "CT Image Storage", or "MR Image Storage".

Data Types: char | string

UID — DICOM unique identifier

character vector | string scalar

DICOM unique identifier corresponding to an IOD, specified as a character vector or string scalar.

Data Types: char | string

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: dicomwrite(X,"new_file.dcm",CompressionMode="JPEG lossless") writes the image data X to a DICOM file new_file.dcm with JPEG lossless compression.

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

Example: dicomwrite(X,"new_file.dcm","CompressionMode","JPEG lossless") writes the image data X to a DICOM file new_file.dcm with JPEG lossless compression.

CompressionMode — Compression mode

"None" (default) | "JPEG lossless" | "JPEG lossy" | ...

Compression mode to use when storing the image, specified as one of these options:

• "None"

• "JPEG lossless"

• "JPEG lossy"

• "JPEG2000 lossy"

• "JPEG2000 lossless"

• "RLE"

Note

If you specify a compression mode, then dicomwrite ignores any values specified for the Endian or VR arguments.

CreateMode — Method used for creating data

"Create" (default) | "Copy"

Method used for creating data to put in the new file, specified as one of these options:

• "Create" — Verify input values, remove extraneous attributes, and generate missing data values.

• "Copy" — Copy all values from the input, and do not generate missing values.

For help selecting a creation method, see Tips.

Dictionary — Name of DICOM data dictionary

character vector | string scalar

Name of the DICOM data dictionary, specified as a character vector or string scalar. The default file is dicom-dict.mat.

Endian — Byte ordering

"ieee-le" (default) | "ieee-be"

Byte ordering of the file, specified as "ieee-le" or "ieee-be".

Note

If VR is set to "Implicit", then Endian must be "ieee-le". The dicomwrite function ignores this value if you specify CompressionMode or TransferSyntax.

MultiframeSingleFile — Write multiframe image to one file

true or 1 (default) | false or 0

Write a multiframe image to one file, specified as a logical 1 (true) or 0 (false). When true, the function creates one file regardless of how many frames X contains. When false, the function creates one file for each frame in the image.

Data Types: logical

TransferSyntax — Transfer syntax

character vector | string scalar

Transfer syntax, specified as a character vector or string scalar. TransferSyntax is a UID that encodes values for the Endian, VR, and CompressionMode options.

Note

If you specify a transfer syntax, then dicomwrite ignores any values specified for the Endian, VR, and CompressionMode options.

UseMetadataBitDepths — Preserve metadata values

false or 0 (default) | true or 1

Preserve the metadata values, specified as a logical 0 (false) or 1 (true). When true, dicomwrite preserves the existing values of the "BitStored", "BitsAllocated", and"HighBit" fields of the metadata structure. When false, dicomwrite computes these values based on the data type of the pixel data.

Note

When you specify CreateMode as "Create", dicomwrite ignores this value.

Data Types: logical

VR — Write two-letter value representation (VR) code to file

"implicit" (default) | "explicit"

Write two-letter value representation (VR) code to file, specified as one of these options:

• "implicit" — Infer from the data dictionary.

• "explicit" — Write VR to the file.

Note

If you specify the Endian value as "ieee-be", then you must specify VR as "explicit". The dicomwrite function ignores this value if you specify TransferSyntax or CompressionMode.

WritePrivate — Write private data to file

false or 0 (default) | true or 1

Write private data to file, specified as a logical 0 (false) or 1 (true).

Data Types: logical

Output Arguments

status — Status of attributes

structure | []

Status of attributes, returned as a structure. status contains information about the metadata and the descriptions used to generate the DICOM file. If no metadata is specified, dicomwrite returns an empty matrix ([]).

The status structure contains these fields.

Field	Description
BadAttribute	The internal description of the attribute is bad. It might be missing from the data dictionary or have incorrect data in its description.
MissingCondition	The attribute is conditional, but no condition has been provided for when to use it.
MissingData	No data provided for an attribute that must appear in the file.
SuspectAttribute	Data in the attribute does not match a list of enumerated values in the DICOM specification.

Tips

• The DICOM format specification lists several Information Object Definitions (IODs) that can be created. These IODs correspond to images and metadata produced by different real-world modalities (such as MRI, X-ray, and Ultrasound). For each type of IOD, the DICOM specification defines the set of metadata that must be present, as well as possible values for other metadata.

  • dicomwrite fully implements a limited number of IODs (Secondary Capture, Computed Tomography, Magnetic Resonance). For these IODs, dicomwrite verifies that all required metadata attributes are present for the specified IOD, creates missing attributes if necessary, and specifies default values where possible. Additionally, dicomwrite removes attributes that are not part of the DICOM specification for the specified IOD. This behavior corresponds to the default value of the CreateMode name-value argument, "Create". If you are working with DICOM files with one of the supported IODs, setting the CreateMode to "Create" is the best way to ensure that the files you create conform to the DICOM specification.

  • To write DICOM files for IODs that dicomwrite does not fully support, use the "Copy" value for the CreateMode name-value argument. In this mode, dicomwrite writes the image data to a file including the metadata that you specify using the info input argument. This option enables you to take metadata from an existing file of the same modality or IOD and use it to create a new DICOM file with different image pixel data. If the image data is empty, dicomwrite does not write image-related metadata attributes to the new DICOM file.

    Note

    Because dicomwrite copies metadata to the file without verification in "Copy" mode, you can create a DICOM file that does not conform to the DICOM standard. For example, the file may be missing required metadata, contain superfluous metadata, or the metadata may no longer correspond to the modality settings used to generate the original image. When using "Copy" mode, make sure that the metadata you use is from the same modality and IOD. If the copy you make is unrelated to the original image, use dicomuid to create new unique identifiers for series and study metadata. See the IOD descriptions in Part 3 of the DICOM specification for more information on appropriate IOD values.

• The dicomwrite function removes metadata attributes with "Group Length" in their names before writing a new DICOM file, regardless of the value of the CreateMode name-value argument. Including group length attributes is error-prone, and is not currently recommended by the DICOM specification. Other software or devices can read DICOM files without group length attributes.

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

dicomwrite now supports thread-based environments.