Write images as DICOM files
dicomwrite(X, map, filename)
dicomwrite(..., param1, value1, param2, value2, ...)
dicomwrite(..., 'ObjectType', IOD,...)
dicomwrite(..., 'SOPClassUID', UID,...)
status = dicomwrite(...)
dicomwrite(X, filename) writes the binary, grayscale,
or truecolor image
X to the file
filename is a string or character vector specifying the name of
the Digital Imaging and Communications in Medicine (DICOM) file to create.
dicomwrite(X, map, filename) writes
the indexed image
X with colormap
dicomwrite(..., param1, value1, param2,
specifies optional metadata to write to the DICOM file or parameters that affect how the
file is written.
param1 is a string or character vector containing
the metadata attribute name or a
value1 is the corresponding value for the attribute or
To find a list of the DICOM attributes that you can specify,
see the data dictionary file,
with the Image Processing
Toolbox™ software. The following table
lists the options that you can specify, in alphabetical order. Default
values are enclosed in braces (
Type of compression to use when storing the image. Possible values:
Specifies the method used for creating the data to put in the new file. Possible values:
Name of a DICOM data dictionary, specified as a string or character vector.
Byte ordering of the file. Possible values:
Logical value indicating whether multiframe imagery should
be written to one file. When
A DICOM UID specifying the
|Logical value that indicates whether to preserve the metadata
Write two-letter value representation (VR) code to file. Possible values:
If you specify the
Logical value indicating whether private data should
be written to the file. Possible values:
dicomwrite(..., 'ObjectType', IOD,...) writes
a file containing the necessary metadata for a particular type of
DICOM Information Object (IOD). Supported IODs are
'Secondary Capture Image Storage' (default)
'CT Image Storage'
'MR Image Storage'
dicomwrite(..., 'SOPClassUID', UID,...) provides
an alternate method for specifying the IOD to create. UID is the DICOM
unique identifier corresponding to one of the IODs listed above.
dicomwrite(..., meta_struct,...) specifies
optional metadata or file options in structure
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
is produced by the
dicominfo function. For more
information about this structure, see
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
that was created by
dicominfo to the
info structure can contain many fields. If no
metadata was specified,
dicomwrite returns an empty
The structure returned by
The attribute's internal description is bad. It might be missing from the data dictionary or have incorrect data in its description.
The attribute is conditional but no condition has been provided for when to use it.
No data was provided for an attribute that must appear in the file.
Data in the attribute does not match a list of enumerated values in the DICOM specification.
Read a CT image from the sample DICOM file included with the toolbox.
X = dicomread('CT-MONO2-16-ankle.dcm');
Write the CT image to a file, creating a secondary capture image.
Write the CT image, X, to a DICOM file along with its metadata. Use the
dicominfo function to retrieve metadata from a DICOM file.
metadata = dicominfo('CT-MONO2-16-ankle.dcm'); dicomwrite(X, 'ct_file.dcm', metadata);
Copy all metadata from one file to another. 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');
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 (e.g., MR, X-ray, Ultrasound, etc.). For each type of IOD, the DICOM specification defines the set of metadata that must be present and possible values for other metadata.
dicomwrite fully implements a limited number
of these IODs, listed above in the
For these IODs,
dicomwrite verifies that all required
metadata attributes are present, creates missing attributes if necessary,
and specifies default values where possible. Using these supported
IODs is the best way to ensure that the files you create conform to
the DICOM specification. This is
behavior and corresponds to the
To write DICOM files for IODs that
implement, use the
'Copy' value for the
In this mode,
dicomwrite writes the image data
to a file including the metadata that you specify as a parameter,
shown above in the
info syntax. The purpose of
this option is 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.
dicomwrite copies metadata to the
file without verification in
'copy' mode, it is
possible to 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
'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
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.