Pydicom Reference Guide

Common pydicom functions called by user code

File Reading/Parsing

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

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

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

pydicom.filereader.read_file(fp, defer_size=None, stop_before_pixels=False, force=False)

Read and parse a DICOM file.

fp : file-like object, str
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_size : int, str, None, optional
If None (default), all elements read into memory. If specified, if a data element value is larger than defer_size, then 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_pixels : boolean, optional
If False (default), the full file will be read and parsed. Set True to stop before reading pixels (and anything after them).
force : boolean, optional
If False (default), raises an InvalidDicomError if the file is not valid DICOM. Set to True to force reading even if no header is found.
FileDataset
An instance of FileDataset that represents a parsed DICOM file.
InvalidDicomError
If the force flag is True and the file is not a valid DICOM file.
pydicom.dataset.FileDataset
Data class that is returned.
pydicom.filereader.read_partial
Only read part of a DICOM file, stopping on given conditions.

Read file and return file dataset: >>> rtplan = pydicom.read_file(“rtplan.dcm”) >>> rtplan.PatientName

Use within a context manager: >>> with pydicom.read_file(“rtplan.dcm”) as rtplan: >>> rtplan.PatientName

pydicom.filereader.read_partial(fileobj, stop_when=None, defer_size=None, force=False)

Parse a DICOM file until a condition is met.

fileobj : a 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_size : int, str, None, optional
See read_file for parameter info.
force : boolean
See read_file for parameter info.

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

FileDataset instance or DicomDir instance.

read_file
More generic file reading function.

File Writing

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

pydicom.filewriter.write_file(filename, dataset, write_like_original=True)

Store a FileDataset to the filename specified.

filename : str
Name of file to save new DICOM file to.
dataset : FileDataset
Dataset holding the DICOM information; e.g. an object read with read_file().
write_like_original : boolean

If True (default), preserves the following information from the dataset: -preamble – if no preamble in read file, than not used here -hasFileMeta – if writer did not do file meta information,

then don’t write here either
-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 “nicer” DICOM file for other readers,
where all lengths are explicit.
pydicom.dataset.FileDataset
Dataset class with relevant attrs and information.
pydicom.dataset.Dataset.save_as
Write a DICOM file from a dataset that was read in with read_file(). save_as wraps write_file.

Set dataset.preamble if you want something other than 128 0-bytes. If the dataset was read from an existing dicom file, then its preamble was stored at read time. It is up to the user to ensure the preamble is still correct for its purposes.

If there is no Transfer Syntax tag in the dataset, then set dataset.is_implicit_VR and dataset.is_little_endian to determine the transfer syntax used to write the file.

Dataset.save_as(filename, write_like_original=True)

Write the dataset to a file.

filename : str
Name of file to save new DICOM file to.
write_like_original : boolean

If True (default), preserves the following information from the dataset: -preamble – if no preamble in read file, than not used here -hasFileMeta – if writer did not do file meta information,

then don’t write here either
-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 “nicer” DICOM file for other readers,
where all lengths are explicit.
pydicom.filewriter.write_file
Write a DICOM file from a FileDataset instance.

Set dataset.preamble if you want something other than 128 0-bytes. If the dataset was read from an existing dicom file, then its preamble was stored at read time. It is up to the user to ensure the preamble is still correct for its purposes.

If there is no Transfer Syntax tag in the dataset, then set dataset.is_implicit_VR and dataset.is_little_endian to determine the transfer syntax used to write the file.

Dataset

class pydicom.dataset.Dataset(*args, **kwargs)

A collection (dictionary) of Dicom DataElement instances.

Example of two ways to retrieve or set values:

  1. dataset[0x10, 0x10].value –> patient’s name
  2. dataset.PatientName –> patient’s name

Example (2) uses DICOM “keywords”, defined starting in 2011 standard. PatientName is not actually a member of the object, but unknown member requests are checked against the DICOM dictionary. If the name matches a DicomDictionary descriptive string, the corresponding tag is used to look up or set the DataElement instance’s value.

Attribute indent_chars:
 for string display, the characters used to indent nested Data Elements (e.g. sequence items). Default is three spaces.