Reading and writing DICOM files

Common pydicom functions called by user code

File Reading/Parsing

The main function to read and parse DICOM files using pydicom is dcmread. It is coded in the module dicom.filereader, but is also imported when the pydicom package is imported:

>>> import pydicom
>>> dataset = pydicom.dcmread(...)

If you need fine control over the reading, you can either call read_partial or use open_dicom. All are documented below:

pydicom.filereader.dcmread(fp, defer_size=None, stop_before_pixels=False, force=False, specific_tags=None)[source][source]

Read and parse a DICOM dataset stored in the DICOM File Format.

Read a DICOM dataset stored in accordance with the DICOM File Format (DICOM Standard Part 10 Section 7). If the dataset is not stored in accordance with the File Format (i.e. the preamble and prefix are missing, there are missing required Type 1 File Meta Information Group elements or the entire File Meta Information is missing) then you will have to set force to True.

Parameters
fpstr or file-like

Either a file-like object, or a string containing the file name. If a file-like object, the caller is responsible for closing it.

defer_sizeint or str or None

If None (default), all elements read into memory. If specified, then if a data element’s stored value is larger than defer_size, the value is not read into memory until it is accessed in code. Specify an integer (bytes), or a string value with units, e.g. “512 KB”, “2 MB”.

stop_before_pixelsbool

If False (default), the full file will be read and parsed. Set True to stop before reading (7FE0,0010) ‘Pixel Data’ (and all subsequent elements).

forcebool

If False (default), raises an InvalidDicomError if the file is missing the File Meta Information header. Set to True to force reading even if no File Meta Information header is found.

specific_tagslist or None

If not None, only the tags in the list are returned. The list elements can be tags or tag names. Note that the tag Specific Character Set is always returned if present - this ensures correct decoding of returned text values.

Returns
FileDataset

An instance of FileDataset that represents a parsed DICOM file.

Raises
InvalidDicomError

If force is True and the file is not a valid DICOM file.

See also

pydicom.dataset.FileDataset

Data class that is returned.

pydicom.filereader.read_partial

Only read part of a DICOM file, stopping on given conditions.

Examples

Read and return a dataset stored in accordance with the DICOM File Format:

>>> ds = pydicom.dcmread("rtplan.dcm")
>>> ds.PatientName

Read and return a dataset not in accordance with the DICOM File Format:

>>> ds = pydicom.dcmread("rtplan.dcm", force=True)
>>> ds.PatientName

Use within a context manager:

>>> with pydicom.dcmread("rtplan.dcm") as ds:
>>>     ds.PatientName
pydicom.filereader.read_partial(fileobj, stop_when=None, defer_size=None, force=False, specific_tags=None)[source][source]

Parse a DICOM file until a condition is met.

Parameters
fileobja file-like object

Note that the file will not close when the function returns.

stop_when :

Stop condition. See read_dataset for more info.

defer_sizeint, str, None, optional

See dcmread for parameter info.

forceboolean

See dcmread for parameter info.

specific_tagslist or None

See dcmread for parameter info.

Returns
FileDataset instance or DicomDir instance.

See also

dcmread

More generic file reading function.

Notes

Use dcmread unless you need to stop on some condition other than reaching pixel data.

File Writing

DICOM files can also be written using pydicom. There are two ways to do this. The first is to use dcmwrite with a prexisting FileDataset (derived from Dataset) instance. The second is to use the save_as method on an Dataset instance.

pydicom.filewriter.dcmwrite(filename, dataset, write_like_original=True)[source][source]

Write dataset to the filename specified.

If write_like_original is True 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). If write_like_original is False, dataset will be stored in the DICOM File Format in accordance with DICOM Standard Part 10 Section 7. The byte stream of the dataset will be placed into the file after the DICOM File Meta Information.

Parameters
filenamestr or file-like

Name of file or the file-like to write the new DICOM file to.

datasetpydicom.dataset.FileDataset

Dataset holding the DICOM information; e.g. an object read with pydicom.dcmread().

write_like_originalbool

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.

See also

pydicom.dataset.FileDataset

Dataset class with relevant attributes and information.

pydicom.dataset.Dataset.save_as

Write a DICOM file from a dataset that was read in with dcmread(). save_as wraps dcmwrite.

Dataset.save_as(self, filename, write_like_original=True)[source][source]

Write the Dataset to filename.

Saving a Dataset requires that the Dataset.is_implicit_VR and Dataset.is_little_endian attributes exist and are set appropriately. If Dataset.file_meta.TransferSyntaxUID is present then it should be set to a consistent value to ensure conformance.

Parameters
filenamestr or file-like

Name of file or the file-like to write the new DICOM file to.

write_like_originalbool

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.

See also

pydicom.filewriter.write_dataset

Write a DICOM Dataset to a file.

pydicom.filewriter.write_file_meta_info

Write the DICOM File Meta Information Group elements to a file.

pydicom.filewriter.dcmwrite

Write a DICOM file from a FileDataset instance.

You can find the complete API documentation for Dataset and other classes in the following section.