dicomwrite
Write images as DICOM files
Syntax
Description
dicomwrite(
writes the binary, grayscale, or truecolor image X
,filename
)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(___,
specifies optional metadata or file options in the structure
meta_struct
)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(___,"ObjectType",
writes a file containing the necessary metadata for a particular type of DICOM
Information Object (IOD). For the supported IODs, IOD
)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",
writes a file containing the necessary metadata for a particular type of IOD,
specified using a DICOM Unique Identifier (UID).UID
)
dicomwrite(___,
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, Name,Value
)dicom-dict.txt
, included with the
Image Processing Toolbox™ software. Enclose each attribute name in quotes.
Examples
Input Arguments
Output Arguments
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 ofIOD
s (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 theCreateMode
name-value argument,"Create"
. If you are working with DICOM files with one of the supported IODs, setting theCreateMode
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 theCreateMode
name-value argument. In this mode,dicomwrite
writes the image data to a file including the metadata that you specify using theinfo
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, usedicomuid
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 theCreateMode
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.
Version History
Introduced before R2006a