pydicom.filewriter.dcmwrite¶

pydicom.filewriter.dcmwrite(filename: str | bytes | PathLike | BinaryIO | WriteableBuffer, dataset: Dataset, /, __write_like_original: bool | None = None, *, implicit_vr: bool | None = None, little_endian: bool | None = None, enforce_file_format: bool = False, force_encoding: bool = False, overwrite: bool = True, **kwargs: Any) → None[source]¶

Write dataset to filename, which can be a path, a file-like or a writeable buffer.

Changed in version 3.0: Added the enforce_file_format and overwrite keyword arguments.

Deprecated since version 3.0: write_like_original is deprecated and will be removed in v4.0, use enforce_file_format instead.

If enforce_file_format is True then an attempt will be made to write dataset using the DICOM File Format, or raise an exception if unable to do so.

If enforce_file_format is False (default) then 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.

DICOM File Format

The DICOM File Format consists of a 128-byte preamble, a 4 byte b'DICM' prefix, the File Meta Information Group elements and finally the encoded dataset.

Preamble and Prefix

The dataset.preamble attribute shall be 128-bytes long or None. The actual preamble written depends on enforce_file_format and dataset.preamble (see the table below).

	enforce_file_format
dataset.preamble	False	True
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 enforce_file_format is False then the File Meta Information Group elements are all optional, otherwise an attempt will be made to add the required elements using dataset. See write_file_meta_info() for more information on which elements are required.

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

Encoding

The preamble and prefix are encoding independent. The File Meta Information Group 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 (IOD). It’s up to the user to ensure dataset conforms to the requirements of the IOD.

Encoding

Changed in version 3.0: Added the implicit_vr and little_endian arguments.

The dataset is encoded as specified by (in order of priority):

The encoding corresponding to the set Transfer Syntax UID in file_meta.
The implicit_vr and little_endian arguments
is_implicit_VR and is_little_endian
original_encoding

Warning

This function does not automatically convert dataset from little to big endian encoding (or vice versa). The endianness of values for elements with a VR of OD, OF, OL, OW, OV and UN must be converted manually prior to calling dcmwrite().

Parameters:

filename (str, PathLike, file-like or writeable buffer) – File path, file-like or writeable buffer to write the encoded dataset to. If using a writeable buffer it must have write(), seek() and tell() methods.
dataset (pydicom.dataset.FileDataset) – The dataset to be encoded.
write_like_original (bool, optional) – If True (default) then write dataset as-is, otherwise ensure that dataset is written in the DICOM File Format or raise an exception if that isn’t possible. This parameter is deprecated, please use enforce_file_format instead.
implicit_vr (bool, optional) – Required if dataset has no valid public Transfer Syntax UID set in the file meta and dataset has been created from scratch. If True then encode dataset using implicit VR, otherwise use explicit VR.
little_endian (bool, optional) – Required if dataset has no valid public Transfer Syntax UID set in the file meta and dataset has been created from scratch. If True (default) then use little endian byte order when encoding dataset, otherwise use big endian.
enforce_file_format (bool, optional) –
If True then ensure dataset is written in the DICOM File Format or raise an exception if that isn’t possible.

If False (default) then write dataset as-is, preserving the following - which may result in a non-conformant file:
- dataset.preamble: if dataset has no preamble then none will be written
- dataset.file_meta: if dataset is missing any required File Meta Information Group elements then they will not be written.
force_encoding (bool, optional) – If True then force the encoding to follow implicit_vr and little_endian. Cannot be used with enforce_file_format. Default False.
overwrite (bool, optional) – If False and filename is a str or PathLike, then raise a FileExistsError if a file already exists with the given filename (default True).

Raises:

ValueError –

If group 0x0000 Command Set elements are present in dataset. * If group 0x0002 File Meta Information Group elements are present in dataset. * If dataset.preamble exists but is not 128 bytes long.