dicomwrite

Write images as DICOM files

Syntax

dicomwrite(X, filename)
dicomwrite(X, map, filename)
dicomwrite(..., param1, value1, param2, value2, ...)
dicomwrite(..., 'ObjectType', IOD,...)
dicomwrite(..., 'SOPClassUID', UID,...)
dicomwrite(..., meta_struct,...)
dicomwrite(..., info,...)
status = dicomwrite(...)

Description

dicomwrite(X, filename) writes the binary, grayscale, or truecolor image X to the file filename, where filename is a string 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 map.

dicomwrite(..., param1, value1, param2, value2, ...) specifies optional metadata to write to the DICOM file or parameters that affect how the file is written. param1 is a string containing the metadata attribute name or a dicomwrite-specific option. value1 is the corresponding value for the attribute or option.

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. The following table lists the options that you can specify, in alphabetical order. Default values are enclosed in braces ({}).

Option Name

Description

'CompressionMode'

String specifying the type of compression to use when storing the image. Possible values:

{'None'}

'JPEG lossless'

'JPEG lossy'

'JPEG2000 lossy'

'JPEG2000 lossless'

'RLE'

'CreateMode'

Specifies the method used for creating the data to put in the new file. Possible values:

{'Create'} — Verify input values and generate missing data values.

'Copy' — Copy all values from the input and do not generate missing values.

'Dictionary'

String specifying the name of a DICOM data dictionary.

'Endian'

String specifying the byte ordering of the file.

'Big'

{'Little'}

    Note:   If VR is set to 'Explicit', 'Endian' must be 'Big'. dicomwrite ignores this value if 'CompressionMode' or 'TransferSyntax' is set.

'MultiframeSingleFile'

Logical value indicating whether multiframe imagery should be written to one file. When true (default), one file is created regardless of how many frames X contains. When false, one file is written for each frame in the image.

'TransferSyntax'

A DICOM UID specifying the 'Endian', 'VR', and 'CompressionMode' options.

    Note:   If specified, dicomwrite ignores any values specified for the 'Endian', 'VR', and 'CompressionMode' options. The TransferSyntax value encodes values for these options.

‘UseMetadataBitDepths'Logical value that indicates whether to preserve the metadata values 'BitStored', 'BitsAllocated', and'HighBit'. When true, dicomwrite preserves existing values. When false (default), dicomwrite computes these values based on the datatype of the pixel data. When 'CreateMode' is 'Create', dicomwrite ignores this field.

'VR'

String specifying whether the two-letter value representation (VR) code should be written to the file.

'explicit' — Write VR to file.

{'implicit'} — Infer from data dictionary.

    Note:   If you specify the 'Endian' value 'Big', you must specify 'Explicit'.

'WritePrivate'

Logical value indicating whether private data should be written to the file. Possible values: true — Write private data to file.

{false} — Do not write private data.

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 meta_struct. 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. For more information about this structure, see dicominfo.

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 that was created by dicominfo to the dicomwrite function. An info structure can contain many fields. If no metadata was specified, dicomwrite returns an empty matrix ([]).

The structure returned by dicomwrite contains these fields:

Field

Description

'BadAttribute'

The attribute's internal description 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 was 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.

Examples

Read a CT image from the sample DICOM file included with the toolbox and then write the CT image to a file, creating a secondary capture image.

X = dicomread('CT-MONO2-16-ankle.dcm');
dicomwrite(X, 'sc_file.dcm');

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. In this mode, dicomwrite does not verify the metadata written to the file.

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

More About

expand all

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 (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 ObjectType syntax. 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 dicomwrite default behavior and corresponds to the CreateMode option value of 'Create'.

To write DICOM files for IODs that dicomwrite doesn't implement, use the 'Copy' value for the CreateMode option. 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.

    Note   Because 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 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.

Was this topic helpful?