- pydicom.filewriter.dcmwrite(filename: str | bytes | PathLike | BinaryIO | DicomFileLike, dataset: Dataset, write_like_original: bool = True) None ¶
Write dataset to the filename specified.
If write_like_original is
Datasetwill 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_metaattribute exists and contains a
Datasetwith 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
dataset.preambleattribute shall be 128-bytes long or
Noneand 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).
128 0x00 bytes
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
Truethen 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
If (0002,0010) Transfer Syntax UID is included then the user must ensure its value is compatible with the values for the
dataset.is_implicit_VRattributes. For example, if
Truethen 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.
The preamble and prefix are encoding independent. The File Meta elements are encoded as Explicit VR Little Endian as required by the DICOM Standard.
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.
The dataset is encoded as specified by the
dataset.is_implicit_VRattributes. It’s up to the user to ensure these attributes are set correctly (as well as setting an appropriate value for
filename (str or PathLike or file-like) – Name of file or the file-like to write the new DICOM file to.
write_like_original (bool, optional) –
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.
False, produces a file conformant with the DICOM File Format, with explicit lengths for all elements.
AttributeError – If either
dataset.is_little_endianhave not been set.
ValueError – If group 2 elements are in
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.