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:
- dataset[0x10, 0x10].value –> patient’s name
- 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.