dicomwrite (Image Processing Toolbox User's Guide)

Image Processing Toolbox User's Guide

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

'TransferSyntax'

A DICOM UID specifying the Endian and VR mode. Note: If specified, dicomwrite ignores any values specified for the Endian, VR, and CompressionMode options. The TransferSyntax value encodes values for these options.

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

Option Name	Description
'CompressionMode'	String specifying the type of compression to use when storing the image. Possible values: `{'None'}` `'JPEG lossless'` `'JPEG lossy'` `'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.
'TransferSyntax'	A DICOM UID specifying the Endian and VR mode. Note: If specified, `dicomwrite` ignores any values specified for the `Endian`, `VR`, and `CompressionMode` options. The `TransferSyntax` value encodes values for these options.
'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.

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.

Example

This example reads a CT image from the sample DICOM file included with the toolbox. The example then writes the CT image to a file, creating a "secondary capture" image.

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

This example writes the CT image, X, to a DICOM file along with its metadata. You 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.

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

dicomuid dither