pydicom.filewriter.dcmwrite¶

pydicom.filewriter.dcmwrite(filename: str | bytes | PathLike | BinaryIO, dataset: Dataset, write_like_original: bool = True) → None[source]¶

Write dataset to the filename specified.

If write_like_original is True then the Dataset will be written as is (after minimal validation checking) and may or may not contain all or parts of the File Meta Information (and hence may or may not be conformant with the DICOM File Format).

If write_like_original is False, dataset will be stored in the DICOM File Format. To do so requires that the Dataset.file_meta attribute exists and contains a Dataset with the required (Type 1) File Meta Information Group elements. The byte stream of the dataset will be placed into the file after the DICOM File Meta Information.

File Meta Information

The File Meta Information consists of a 128-byte preamble, followed by a 4 byte b'DICM' prefix, followed by the File Meta Information Group elements.

Preamble and Prefix

The dataset.preamble attribute shall be 128-bytes long or None and is available for use as defined by the Application Profile or specific implementations. If the preamble is not used by an Application Profile or specific implementation then all 128 bytes should be set to 0x00. The actual preamble written depends on write_like_original and dataset.preamble (see the table below).

	write_like_original
dataset.preamble	True	False
None	no preamble	128 0x00 bytes
128 bytes	dataset.preamble

The prefix shall be the bytestring b'DICM' and will be written if and only if the preamble is present.

File Meta Information Group Elements

The preamble and prefix are followed by a set of DICOM elements from the (0002,eeee) group. Some of these elements are required (Type 1) while others are optional (Type 3/1C). If write_like_original is True then the File Meta Information Group elements are all optional. See write_file_meta_info() for more information on which elements are required.

The File Meta Information Group elements should be included within their own Dataset in the dataset.file_meta attribute.

If (0002,0010) Transfer Syntax UID is included then the user must ensure its value is compatible with the values for the dataset.is_little_endian and dataset.is_implicit_VR attributes. For example, if is_little_endian and is_implicit_VR are both True then the Transfer Syntax UID must be 1.2.840.10008.1.2 Implicit VR Little Endian. See the DICOM Standard, Part 5, Section 10 for more information on Transfer Syntaxes.

Encoding

The preamble and prefix are encoding independent. The File Meta elements are encoded as Explicit VR Little Endian as required by the DICOM Standard.

Dataset

A DICOM Dataset representing a SOP Instance related to a DICOM Information Object Definition. It is up to the user to ensure the dataset conforms to the DICOM Standard.

Encoding

The dataset is encoded as specified by the dataset.is_little_endian and dataset.is_implicit_VR attributes. It’s up to the user to ensure these attributes are set correctly (as well as setting an appropriate value for dataset.file_meta.TransferSyntaxUID if present).

Parameters:

filename (str or PathLike or file-like) – Name of file or the file-like to write the new DICOM file to.
dataset (pydicom.dataset.FileDataset) – Dataset holding the DICOM information; e.g. an object read with dcmread().
write_like_original (bool, optional) –
If True (default), preserves the following information from the Dataset (and may result in a non-conformant file):
- preamble – if the original file has no preamble then none will be written.
- file_meta – if the original file was missing any required File Meta Information Group elements then they will not be added or written. If (0002,0000) File Meta Information Group Length is present then it may have its value updated.
- seq.is_undefined_length – if original had delimiters, write them now too, instead of the more sensible length characters
- is_undefined_length_sequence_item – for datasets that belong to a sequence, write the undefined length delimiters if that is what the original had.
If False, produces a file conformant with the DICOM File Format, with explicit lengths for all elements.

Raises:

AttributeError – If either dataset.is_implicit_VR or dataset.is_little_endian have not been set.
ValueError – If group 2 elements are in dataset rather than dataset.file_meta, or if a preamble is given but is not 128 bytes long, or if Transfer Syntax is a compressed type and pixel data is not compressed.