# 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.