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 dicom package is imported:

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

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

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

Read and parse a DICOM file

Parameters:
  • fp – 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 – 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”. Default None means all elements read into memory.
  • stop_before_pixels – Set True to stop before reading pixels (and anything after them). If False (default), the full file will be read and parsed.
  • force – Set to True to force reading even if no header is found. If False, a dicom.filereader.InvalidDicomError is raised when the file is not valid DICOM.
Returns:

a FileDataset instance
dicom.filereader.read_partial(fileobj, stop_when=None, defer_size=None, force=False)

Parse a DICOM file until a condition is met

read_partial is normally not called directly. Use read_file instead, unless you need to stop on some condition other than reaching pixel data.

Parameters:
  • fileobj – a file-like object. This function does not close it.
  • stop_when – a callable which takes tag, VR, length, and returns True or False. If stop_when returns True, read_data_element will raise StopIteration. If None (default), then the whole file is read.
Returns:

a FileDataset instance, or if a DICOMDIR, a DicomDir instance.

Dataset

class dicom.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.