dicomwrite

Write images as DICOM files

collapse all in page

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. dicomwrite creates a Digital Imaging and Communications in Medicine (DICOM) file or a Digital Imaging and Communication in Security (DICOS) file.

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

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.

example

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, 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. For more information, see Tips.

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

dicomwrite(___,Name,Value) writes to a DICOM file using Name,Value pairs to affect how the file is written. You can specify multiple name-value pairs.

You can also use Name,Value pairs to specify optional metadata 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

collapse all

Open Live Script

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.

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

collapse all

DICOM image, specified as one of the following.

  • 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 input 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 'Copy'.

Data Types: int8 | int16 | uint8 | uint16

Color map associated with indexed image X, specified as c-by-3 matrix. There are c colors in the color map, each represented by a red, green, and blue pixel value.

Data Types: double

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

Data Types: char | string

Optional metadata or file options, specified as a 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.

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

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

Data Types: char | string

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

Data Types: char | string

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'CompressionMode','JPEG lossless'

Compression mode to use when storing the image, specified as the comma-separated pair consisting of 'CompressionMode' and one of the following.

  • 'None'

  • 'JPEG lossless'

  • 'JPEG lossy'

  • 'JPEG2000 lossy'

  • 'JPEG2000 lossless'

  • 'RLE'

Method used for creating data to put in the new file, specified as the comma-separated pair consisting of 'CreateMode' and one of the following.

  • 'Create' — Verify input values 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.

Name of DICOM data dictionary, specified as the comma-separated pair consisting of 'Dictionary' and a character vector or string scalar. The default file is dicom-dict.mat.

Byte ordering of the file, specified as the comma-separated pair consisting of 'Endian' and 'ieee-le' or 'ieee-be'.

Note

If VR is set to 'Implicit', then Endian must be 'ieee-le'. dicomwrite ignores this value if CompressionMode or TransferSyntax is set.

Write multiframe image to one file, specified as the comma-separated pair consisting of 'MultiframeSingleFile' and true or false. When true, one file is created regardless of how many frames X contains. When false, one file is written for each frame in the image.

Data Types: logical

Transfer syntax, specified as the comma-separated pair consisting of 'TransferSyntax' and 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.

Preserve the metadata values 'BitStored', 'BitsAllocated', and'HighBit', specified as the comma-separated pair consisting of 'UseMetadataBitDepths' and false or true. 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.

Data Types: logical

Write two-letter value representation (VR) code to file, specified as the comma-separated pair consisting of 'VR' and one of the following.

  • 'implicit' — Infer from data dictionary.

  • 'explicit' — Write VR to file.

Note

If you specify the Endian value as 'ieee-be', then you must specify VR as 'explicit'.

Write private data to file, specified as the comma-separated pair consisting of 'WritePrivate' and false or true.

Data Types: logical

Output Arguments

collapse all

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 was specified, dicomwrite returns an empty matrix ([]).

The status structure 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.

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 (for example, 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 IODs. 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. 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, 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.

See Also

| | | | | |

Topics

Introduced before R2006a

Image Processing Toolbox Documentation

Support