Pydicom Complete API Reference

Auto-generated API documentation

DICOM Dataset

Define the Dataset and FileDataset classes.

The Dataset class represents the DICOM Dataset while the FileDataset class adds extra functionality to Dataset when data is read from or written to file.

Overview of DICOM object model

Dataset (dict subclass)

Contains DataElement instances, each of which has a tag, VR, VM and value.

The DataElement value can be:

• A single value, such as a number, string, etc. (i.e. VM = 1)
• A list of numbers, strings, etc. (i.e. VM > 1)

• A Sequence (list subclass), where each item is a Dataset which

  contains its own DataElements, and so on in a recursive manner.

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

Contains a collection (dictionary) of DICOM DataElements. Behaves like a dictionary.

Examples

Add DataElements to the Dataset (for elements in the DICOM dictionary):

>>> ds = Dataset()
>>> ds.PatientName = "CITIZEN^Joan"
>>> ds.add_new(0x00100020, 'LO', '12345')
>>> ds[0x0010, 0x0030] = DataElement(0x00100030, 'DA', '20010101')

Add Sequence DataElement to the Dataset:

>>> ds.BeamSequence = [Dataset(), Dataset(), Dataset()]
>>> ds.BeamSequence[0].Manufacturer = "Linac, co."
>>> ds.BeamSequence[1].Manufacturer = "Linac and Sons, co."
>>> ds.BeamSequence[2].Manufacturer = "Linac and Daughters, co."

Add private DataElements to the Dataset:

>>> ds.add(DataElement(0x0043102b, 'SS', [4, 4, 0, 0]))
>>> ds.add_new(0x0043102b, 'SS', [4, 4, 0, 0])
>>> ds[0x0043, 0x102b] = DataElement(0x0043102b, 'SS', [4, 4, 0, 0])

Updating and retrieving DataElement values:

>>> ds.PatientName = "CITIZEN^Joan"
>>> ds.PatientName
'CITIZEN^Joan"
>>> ds.PatientName = "CITIZEN^John"
>>> ds.PatientName
'CITIZEN^John'

Retrieving a DataElement’s value from a Sequence:

>>> ds.BeamSequence[0].Manufacturer
'Linac, co.'
>>> ds.BeamSequence[1].Manufacturer
'Linac and Sons, co.'

Retrieving DataElements:

>>> elem = ds[0x00100010]
>>> elem
(0010, 0010) Patient's Name                      PN: 'CITIZEN^Joan'
>>> elem = ds.data_element('PatientName')
>>> elem
(0010, 0010) Patient's Name                      PN: 'CITIZEN^Joan'

Deleting a DataElement from the Dataset:

>>> del ds.PatientID
>>> del ds.BeamSequence[1].Manufacturer
>>> del ds.BeamSequence[2]

Deleting a private DataElement from the Dataset:

>>> del ds[0x0043, 0x102b]

Determining if a DataElement is present in the Dataset:

>>> 'PatientName' in ds
True
>>> 'PatientID' in ds
False
>>> (0x0010, 0x0030) in ds
True
>>> 'Manufacturer' in ds.BeamSequence[0]
True

Iterating through the top level of a Dataset only (excluding Sequences):

>>> for elem in ds:
>>>    print(elem)

Iterating through the entire Dataset (including Sequences):

>>> for elem in ds.iterall():
>>>     print(elem)

Recursively iterate through a Dataset (including Sequences):

>>> def recurse(ds):
>>>     for elem in ds:
>>>         if elem.VR == 'SQ':
>>>             [recurse(item) for item in elem]
>>>         else:
>>>             # Do something useful with each DataElement

Attributes

default_element_format	(str) The default formatting for string display.
default_sequence_element_format	(str) The default formatting for string display of sequences.
indent_chars	(str) For string display, the characters used to indent nested Sequences. Default is ” “.
is_little_endian	(bool) Shall be set before writing with write_like_original=False. The written dataset (excluding the pixel data) will be written using the given endianess.
is_implicit_VR	(bool) Shall be set before writing with write_like_original=False. The written dataset will be written using the transfer syntax with the given VR handling, e.g LittleEndianImplicit if True, and LittleEndianExplicit or BigEndianExplicit (depending on is_little_endian) if False.

Methods

add(data_element)	Add a DataElement to the Dataset.
add_new(tag, VR, value)	Add a DataElement to the Dataset.
clear()	Delete all data elements.
convert_pixel_data()	Convert the Pixel Data to a numpy array internally.
data_element(name)	Return the DataElement corresponding to the element keyword name.
decode()	Apply character set decoding to all DataElements in the Dataset.
decompress()	Decompresses pixel data and modifies the Dataset in-place
dir(*filters)	Return an alphabetical list of DataElement keywords in the Dataset.
elements()	Iterate through the top-level of the Dataset, yielding DataElements or RawDataElements (no conversion done).
ensure_file_meta()	Create an empty file meta dataset if none exists.
fix_meta_info([enforce_standard])	Ensure the file meta info exists and has the correct values for transfer syntax and media storage uids.
formatted_lines([element_format, …])	Iterate through the Dataset yielding formatted str for each element.
get(key[, default])	Simulate dict.get() to handle DICOM DataElement tags and keywords.
get_item(key)	Return the raw data element if possible.
group_dataset(group)	Return a Dataset containing only DataElements of a certain group.
iterall()	Iterate through the Dataset, yielding all DataElements.
keys()	Return the DICOM tag keys to simulate dict.
pop(*args, **kwargs)
popitem()
remove_private_tags()	Remove all private DataElements in the Dataset.
save_as(filename[, write_like_original])	Write the Dataset to filename.
set_original_encoding(is_implicit_vr, …)	Set the values for the original transfer syntax and encoding.
setdefault(*args, **kwargs)
top()	Return a str of the Dataset’s top level DataElements only.
trait_names()	Return a list of valid names for auto-completion code.
update(dictionary)	Extend dict.update() to handle DICOM keywords.
values()	Return the DICOM tag values to simulate dict.
walk(callback[, recursive])	Iterate through the DataElements and run callback on each.

add(data_element)

Add a DataElement to the Dataset.

Equivalent to ds[data_element.tag] = data_element

Parameters:

data_element : pydicom.dataelem.DataElement

The DataElement to add to the Dataset.

add_new(tag, VR, value)

Add a DataElement to the Dataset.

Parameters:

tag

The DICOM (group, element) tag in any form accepted by pydicom.tag.Tag such as [0x0010, 0x0010], (0x10, 0x10), 0x00100010, etc.

VR : str

The 2 character DICOM value representation (see DICOM standard part 5, Section 6.2).

value

The value of the data element. One of the following: * a single string or number * a list or tuple with all strings or all numbers * a multi-value string with backslash separator * for a sequence DataElement, an empty list or list of Dataset

clear()

Delete all data elements.

convert_pixel_data()

Convert the Pixel Data to a numpy array internally.

Returns:

None

Converted pixel data is stored internally in the dataset.

Notes

If the pixel data is in a compressed image format, the data is decompressed and any related data elements are changed accordingly.

data_element(name)

Return the DataElement corresponding to the element keyword name.

Parameters:

name : str

A DICOM element keyword.

Returns:

pydicom.dataelem.DataElement or None

For the given DICOM element keyword, return the corresponding Dataset DataElement if present, None otherwise.

decode()

Apply character set decoding to all DataElements in the Dataset.

See DICOM PS3.5-2008 6.1.1.

decompress()

Decompresses pixel data and modifies the Dataset in-place

If not a compressed tranfer syntax, then pixel data is converted to a numpy array internally, but not returned.

If compressed pixel data, then is decompressed using an image handler, and internal state is updated appropriately:

• TransferSyntax is updated to non-compressed form
• is_undefined_length for pixel data is set False

Returns:

None

Raises:

NotImplementedError

If the pixel data was originally compressed but file is not ExplicitVR LittleEndian as required by Dicom standard

dir(*filters)

Return an alphabetical list of DataElement keywords in the Dataset.

Intended mainly for use in interactive Python sessions. Only lists the DataElement keywords in the current level of the Dataset (i.e. the contents of any Sequence elements are ignored).

Parameters:

filters : str

Zero or more string arguments to the function. Used for case-insensitive match to any part of the DICOM keyword.

Returns:

list of str

The matching DataElement keywords in the dataset. If no filters are used then all DataElement keywords are returned.

elements()

Iterate through the top-level of the Dataset, yielding DataElements or RawDataElements (no conversion done).

>>> for elem in ds.elements():
>>>     print(elem)

The elements are returned in the same way as in __getitem__.

Yields:

pydicom.dataelem.DataElement or pydicom.dataelem.RawDataElement

The Dataset’s DataElements, sorted by increasing tag order.

ensure_file_meta()

Create an empty file meta dataset if none exists.

fix_meta_info(enforce_standard=True)

Ensure the file meta info exists and has the correct values for transfer syntax and media storage uids.

Warning

The transfer syntax for is_implicit_VR = False and is_little_endian = True is ambiguous and will therefore not be set.

Parameters:

enforce_standard : boolean

If True, a check for incorrect and missing elements is performed. (see pydicom.filewriter.validate_file_meta)

formatted_lines(element_format='%(tag)s %(name)-35.35s %(VR)s: %(repval)s', sequence_element_format='%(tag)s %(name)-35.35s %(VR)s: %(repval)s', indent_format=None)

Iterate through the Dataset yielding formatted str for each element.

Parameters:

element_format : str

The string format to use for non-sequence elements. Formatting uses the attributes of DataElement. Default is “%(tag)s %(name)-35.35s %(VR)s: %(repval)s”.

sequence_element_format : str

The string format to use for sequence elements. Formatting uses the attributes of DataElement. Default is “%(tag)s %(name)-35.35s %(VR)s: %(repval)s”

indent_format : str or None

Placeholder for future functionality.

Yields:

str

A string representation of a DataElement.

get(key, default=None)

Simulate dict.get() to handle DICOM DataElement tags and keywords.

Parameters:

key : str or pydicom.tag.Tag

The element keyword or Tag or the class attribute name to get.

default : obj or None

If the DataElement or class attribute is not present, return default (default None).

Returns:

value

If key is the keyword for a DataElement in the Dataset then return the DataElement’s value.

pydicom.dataelem.DataElement

If key is a tag for a DataElement in the Dataset then return the DataElement instance.

value

If key is a class attribute then return its value.

get_item(key)

Return the raw data element if possible.

It will be raw if the user has never accessed the value, or set their own value. Note if the data element is a deferred-read element, then it is read and converted before being returned.

Parameters:

key

The DICOM (group, element) tag in any form accepted by pydicom.tag.Tag such as [0x0010, 0x0010], (0x10, 0x10), 0x00100010, etc. May also be a slice made up of DICOM tags.

Returns:

pydicom.dataelem.DataElement

group_dataset(group)

Return a Dataset containing only DataElements of a certain group.

Parameters:

group : int

The group part of a DICOM (group, element) tag.

Returns:

pydicom.dataset.Dataset

A dataset instance containing elements of the group specified.

is_original_encoding

Return True if the properties to be used for writing are set and have the same value as the ones in the dataset after reading it. This includes properties related to endianess, VR handling and the specific character set.

iterall()

Iterate through the Dataset, yielding all DataElements.

Unlike Dataset.__iter__, this does recurse into sequences, and so returns all data elements as if the file were “flattened”.

Yields:pydicom.dataelem.DataElement

keys()

Return the DICOM tag keys to simulate dict.

pixel_array

Return the Pixel Data as a NumPy array.

Returns:

numpy.ndarray

The Pixel Data (7FE0,0010) as a NumPy ndarray.

remove_private_tags()

Remove all private DataElements in the Dataset.

save_as(filename, write_like_original=True)

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:

filename : str or file-like

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

write_like_original : bool

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.

set_original_encoding(is_implicit_vr, is_little_endian, character_encoding)

Set the values for the original transfer syntax and encoding. Can be used for a dataset with raw data elements to enable optimized writing (e.g. without decoding the data elements).

top()

Return a str of the Dataset’s top level DataElements only.

trait_names()

Return a list of valid names for auto-completion code.

Used in IPython, so that data element names can be found and offered for autocompletion on the IPython command line.

update(dictionary)

Extend dict.update() to handle DICOM keywords.

values()

Return the DICOM tag values to simulate dict.

walk(callback, recursive=True)

Iterate through the DataElements and run callback on each.

Visit all DataElements, possibly recursing into sequences and their datasets. The callback function is called for each DataElement (including SQ element). Can be used to perform an operation on certain types of DataElements. E.g., `remove_private_tags`() finds all private tags and deletes them. DataElement`s will come back in DICOM order (by increasing tag number within their dataset).

Parameters:

callback

A callable that takes two arguments:

• a Dataset
• a DataElement belonging to that Dataset

recursive : bool

Flag to indicate whether to recurse into Sequences.

class pydicom.dataset.FileDataset(filename_or_obj, dataset, preamble=None, file_meta=None, is_implicit_VR=True, is_little_endian=True)

An extension of Dataset to make reading and writing to file-like easier.

Attributes

preamble	(str or bytes or None) The optional DICOM preamble prepended to the dataset, if available.
file_meta	(pydicom.dataset.Dataset or None) The Dataset’s file meta information as a Dataset, if available (None if not present). Consists of group 0002 elements.
filename	(str or None) The filename that the dataset was read from (if read from file) or None if the filename is not available (if read from a BytesIO or similar).
fileobj_type	The object type of the file-like the Dataset was read from.
is_implicit_VR	(bool) True if the dataset encoding is implicit VR, False otherwise.
is_little_endian	(bool) True if the dataset encoding is little endian byte ordering, False otherwise.
timestamp	(float or None) The modification time of the file the dataset was read from, None if the modification time is not available.

Methods

add(data_element)	Add a DataElement to the Dataset.
add_new(tag, VR, value)	Add a DataElement to the Dataset.
clear()	Delete all data elements.
convert_pixel_data()	Convert the Pixel Data to a numpy array internally.
data_element(name)	Return the DataElement corresponding to the element keyword name.
decode()	Apply character set decoding to all DataElements in the Dataset.
decompress()	Decompresses pixel data and modifies the Dataset in-place
dir(*filters)	Return an alphabetical list of DataElement keywords in the Dataset.
elements()	Iterate through the top-level of the Dataset, yielding DataElements or RawDataElements (no conversion done).
ensure_file_meta()	Create an empty file meta dataset if none exists.
fix_meta_info([enforce_standard])	Ensure the file meta info exists and has the correct values for transfer syntax and media storage uids.
formatted_lines([element_format, …])	Iterate through the Dataset yielding formatted str for each element.
get(key[, default])	Simulate dict.get() to handle DICOM DataElement tags and keywords.
get_item(key)	Return the raw data element if possible.
group_dataset(group)	Return a Dataset containing only DataElements of a certain group.
iterall()	Iterate through the Dataset, yielding all DataElements.
keys()	Return the DICOM tag keys to simulate dict.
pop(*args, **kwargs)
popitem()
remove_private_tags()	Remove all private DataElements in the Dataset.
save_as(filename[, write_like_original])	Write the Dataset to filename.
set_original_encoding(is_implicit_vr, …)	Set the values for the original transfer syntax and encoding.
setdefault(*args, **kwargs)
top()	Return a str of the Dataset’s top level DataElements only.
trait_names()	Return a list of valid names for auto-completion code.
update(dictionary)	Extend dict.update() to handle DICOM keywords.
values()	Return the DICOM tag values to simulate dict.
walk(callback[, recursive])	Iterate through the DataElements and run callback on each.

exception pydicom.dataset.PropertyError

For AttributeErrors caught in a property, so do not go to __getattr__

pydicom.dataset.validate_file_meta(file_meta, enforce_standard=True)

Validates the File Meta Information elements in file_meta and adds some tags if missing and enforce_standard is True.

Parameters:

file_meta : pydicom.dataset.Dataset

The File Meta Information data elements.

enforce_standard : bool

If False, then only a check for invalid elements is performed. If True, the following elements will be added if not already present:

• (0002,0001) FileMetaInformationVersion
• (0002,0012) ImplementationClassUID
• (0002,0013) ImplementationVersionName

and the following elements will be checked:

• (0002,0002) MediaStorageSOPClassUID
• (0002,0003) MediaStorageSOPInstanceUID
• (0002,0010) TransferSyntaxUID

Raises:

ValueError

If enforce_standard is True and any of the checked File Meta Information elements are missing from file_meta.

ValueError

If any non-Group 2 Elements are present in file_meta.

Modules related to DICOM File Input/Output

Reading DICOM files - the filereader module

Read a dicom media file

class pydicom.filereader.DicomIter(fp, stop_when=None, force=False)

Iterator over DICOM data elements created from a file-like object

pydicom.filereader.data_element_generator(fp, is_implicit_VR, is_little_endian, stop_when=None, defer_size=None, encoding='iso8859', specific_tags=None)

Create a generator to efficiently return the raw data elements.

Parameters:

fp : file-like object

is_implicit_VR : boolean

is_little_endian : boolean

stop_when : None, callable, optional

If None (default), then the whole file is read. A callable which takes tag, VR, length, and returns True or False. If it returns True, read_data_element will just return.

defer_size : int, str, None, optional

See dcmread for parameter info.

encoding :

Encoding scheme

specific_tags : list or None

See dcmread for parameter info.

Returns:

VR : None if implicit VR, otherwise the VR read from the file

length :

the length as in the DICOM data element (could be DICOM “undefined length” 0xffffffffL)

value_bytes :

the raw bytes from the DICOM file (not parsed into python types)

is_little_endian : boolean

True if transfer syntax is little endian; else False.

pydicom.filereader.data_element_offset_to_value(is_implicit_VR, VR)

Return number of bytes from start of data element to start of value

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

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:

fp : str 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_size : int 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_pixels : bool

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

force : bool

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_tags : list 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_dataset(fp, is_implicit_VR, is_little_endian, bytelength=None, stop_when=None, defer_size=None, parent_encoding='iso8859', specific_tags=None)

Return a Dataset instance containing the next dataset in the file.

Parameters:

fp : an opened file object

is_implicit_VR : boolean

True if file transfer syntax is implicit VR.

is_little_endian : boolean

True if file has little endian transfer syntax.

bytelength : int, None, optional

None to read until end of file or ItemDeliterTag, else a fixed number of bytes to read

stop_when : None, optional

optional call_back function which can terminate reading. See help for data_element_generator for details

defer_size : int, None, optional

Size to avoid loading large elements in memory. See dcmread for more parameter info.

parent_encoding :

optional encoding to use as a default in case a Specific Character Set (0008,0005) isn’t specified

specific_tags : list or None

See dcmread for parameter info.

Returns:

a Dataset instance

See also

pydicom.dataset.Dataset

A collection (dictionary) of Dicom DataElement instances.

pydicom.filereader.read_deferred_data_element(fileobj_type, filename, timestamp, raw_data_elem)

Read the previously deferred value from the file into memory and return a raw data element

pydicom.filereader.read_dicomdir(filename='DICOMDIR')

Read a DICOMDIR file and return a DicomDir instance.

This is a wrapper around dcmread, which gives a default file name.

Parameters:

filename : str, optional

Full path and name to DICOMDIR file to open

Returns:

DicomDir

Raises:

InvalidDicomError

Raised if filename is not a DICOMDIR file.

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

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:

fp : str 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_size : int 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_pixels : bool

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

force : bool

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_tags : list 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_file_meta_info(filename)

Read and return the DICOM file meta information only.

This function is meant to be used in user code, for quickly going through a series of files to find one which is referenced to a particular SOP, without having to read the entire files.

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

Parse a DICOM file until a condition is met.

Parameters:

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 dcmread for parameter info.

force : boolean

See dcmread for parameter info.

specific_tags : list 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.

pydicom.filereader.read_preamble(fp, force)

Return the 128-byte DICOM preamble in fp if present.

fp should be positioned at the start of the file-like. If the preamble and prefix are found then after reading fp will be positioned at the first byte after the prefix (byte offset 133). If either the preamble or prefix are missing and force is True then after reading fp will be positioned at the start of the file-like.

Parameters:

fp : file-like object

The file-like to read the preamble from.

force : bool

Flag to force reading of a file even if no header is found.

Returns:

preamble : str/bytes or None

The 128-byte DICOM preamble will be returned if the appropriate prefix (‘DICM’) is found at byte offset 128. Returns None if the ‘DICM’ prefix is not found and force is True.

Raises:

InvalidDicomError

If force is False and no appropriate header information found.

Notes

Also reads past the ‘DICM’ marker. Rewinds file to the beginning if no header found.

pydicom.filereader.read_sequence(fp, is_implicit_VR, is_little_endian, bytelength, encoding, offset=0)

Read and return a Sequence – i.e. a list of Datasets

pydicom.filereader.read_sequence_item(fp, is_implicit_VR, is_little_endian, encoding, offset=0)

Read and return a single sequence item, i.e. a Dataset

Writing DICOM files - the filewriter module

Functions related to writing DICOM data.

pydicom.filewriter.correct_ambiguous_vr(ds, is_little_endian)

Iterate through ds correcting ambiguous VR elements (if possible).

When it’s not possible to correct the VR, the element will be returned unchanged. Currently the only ambiguous VR elements not corrected for are all retired or part of DICONDE.

If the VR is corrected and is ‘US’ or ‘SS’ then the value will be updated using the pydicom.values.convert_numbers() method.

Parameters:

ds : pydicom.dataset.Dataset

The dataset containing ambiguous VR elements.

is_little_endian : bool

The byte ordering of the values in the dataset.

Returns:

ds : pydicom.dataset.Dataset

The corrected dataset

Raises:

AttributeError

If a tag is missing in ds that is required to resolve the ambiguity.

pydicom.filewriter.correct_ambiguous_vr_element(elem, ds, is_little_endian)

Attempt to correct the ambiguous VR element elem.

When it’s not possible to correct the VR, the element will be returned unchanged. Currently the only ambiguous VR elements not corrected for are all retired or part of DICONDE.

If the VR is corrected and is ‘US’ or ‘SS’ then the value will be updated using the pydicom.values.convert_numbers() method.

Parameters:

elem : pydicom.dataelem.DataElement

The element with an ambiguous VR.

ds : pydicom.dataset.Dataset

The dataset containing elem.

is_little_endian : bool

The byte ordering of the values in the dataset.

Returns:

elem : pydicom.dataelem.DataElement

The corrected element

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

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:

filename : str or file-like

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

dataset : pydicom.dataset.FileDataset

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

write_like_original : bool

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.

pydicom.filewriter.multi_string(val)

Put a string together with delimiter if has more than one value

pydicom.filewriter.write_ATvalue(fp, data_element)

Write a data_element tag to a file.

pydicom.filewriter.write_OBvalue(fp, data_element)

Write a data_element with VR of ‘other byte’ (OB).

pydicom.filewriter.write_OWvalue(fp, data_element)

Write a data_element with VR of ‘other word’ (OW).

Note: This does not currently do the byte swapping for Endian state.

pydicom.filewriter.write_UI(fp, data_element)

Write a data_element with VR of ‘unique identifier’ (UI).

pydicom.filewriter.write_UN(fp, data_element)

Write a byte string for an DataElement of value ‘UN’ (unknown).

pydicom.filewriter.write_data_element(fp, data_element, encodings=None)

Write the data_element to file fp according to dicom media storage rules.

pydicom.filewriter.write_dataset(fp, dataset, parent_encoding='iso8859')

Write a Dataset dictionary to the file. Return the total length written.

Attempt to correct ambiguous VR elements when explicit little/big

encoding Elements that can’t be corrected will be returned unchanged.

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

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:

filename : str or file-like

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

dataset : pydicom.dataset.FileDataset

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

write_like_original : bool

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.

pydicom.filewriter.write_file_meta_info(fp, file_meta, enforce_standard=True)

Write the File Meta Information elements in file_meta to fp.

If enforce_standard is True then the file-like fp should be positioned past the 128 byte preamble + 4 byte prefix (which should already have been written).

From the DICOM standard, Part 10 Section 7.1, any DICOM file shall contain a 128-byte preamble, a 4-byte DICOM prefix ‘DICM’ and (at a minimum) the following Type 1 DICOM Elements (from Table 7.1-1):

• (0002,0000) FileMetaInformationGroupLength, UL, 4
• (0002,0001) FileMetaInformationVersion, OB, 2
• (0002,0002) MediaStorageSOPClassUID, UI, N
• (0002,0003) MediaStorageSOPInstanceUID, UI, N
• (0002,0010) TransferSyntaxUID, UI, N
• (0002,0012) ImplementationClassUID, UI, N

If enforce_standard is True then (0002,0000) will be added/updated, (0002,0001) and (0002,0012) will be added if not already present and the other required elements will be checked to see if they exist. If enforce_standard is False then file_meta will be written as is after minimal validation checking.

The following Type 3/1C Elements may also be present:

• (0002,0013) ImplementationVersionName, SH, N
• (0002,0016) SourceApplicationEntityTitle, AE, N
• (0002,0017) SendingApplicationEntityTitle, AE, N
• (0002,0018) ReceivingApplicationEntityTitle, AE, N
• (0002,0100) PrivateInformationCreatorUID, UI, N
• (0002,0102) PrivateInformation, OB, N

If enforce_standard is True then (0002,0013) will be added/updated.

The encoding of the File Meta Information shall be Explicit VR Little Endian

Parameters:

fp : file-like

The file-like to write the File Meta Information to.

file_meta : pydicom.dataset.Dataset

The File Meta Information DataElements.

enforce_standard : bool

If False, then only the File Meta Information elements already in file_meta will be written to fp. If True (default) then a DICOM Standards conformant File Meta will be written to fp.

Raises:

ValueError

If enforce_standard is True and any of the required File Meta Information elements are missing from file_meta, with the exception of (0002,0000), (0002,0001) and (0002,0012).

ValueError

If any non-Group 2 Elements are present in file_meta.

pydicom.filewriter.write_number_string(fp, data_element)

Handle IS or DS VR - write a number stored as a string of digits.

pydicom.filewriter.write_numbers(fp, data_element, struct_format)

Write a “value” of type struct_format from the dicom file.

“Value” can be more than one number.

struct_format – the character format as used by the struct module.

pydicom.filewriter.write_sequence(fp, data_element, encodings)

Write a dicom Sequence contained in data_element to the file fp.

pydicom.filewriter.write_sequence_item(fp, dataset, encodings)

Write an item (dataset) in a dicom Sequence to the dicom file fp.

This is similar to writing a data_element, but with a specific tag for Sequence Item

see Dicom standard Part 5, p. 39 (‘03 version)

pydicom.filewriter.write_string(fp, data_element, padding=' ')

Write a single or multivalued ASCII string.

pydicom.filewriter.write_text(fp, data_element, encodings=None)

Write a single or multivalued text string.

Base classes for file I/O - the filebase module

Hold DicomFile class, which does basic I/O for a dicom file.

class pydicom.filebase.DicomIO(*args, **kwargs)

File object which holds transfer syntax info and anything else we need.

Attributes

is_implicit_VR
is_little_endian

defer_size

Methods

read([length, need_exact_length])	Reads the required length, returns
read_beUL()	Return an unsigned long read with big endian byte order
read_beUS()	Return an unsigned short from the file
read_be_tag()	Read and return two unsigned shorts (big endian) from the file.
read_leUL()	Return an unsigned long read with
read_leUS()	Return an unsigned short from the file
read_le_tag()	Read and return two unsigned shorts (little endian) from the file.
write_UL(val)	Write an unsigned long with little endian byte order
write_US(val)	Write an unsigned short with little endian byte order
write_beUL(val)	Write an unsigned long with big endian byte order
write_beUS(val)	Write an unsigned short with big endian byte order
write_leUL(val)	Write an unsigned long with little endian byte order
write_leUS(val)	Write an unsigned short with little endian byte order
write_tag(tag)	Write a dicom tag (two unsigned shorts) to the file.

read(length=None, need_exact_length=False)

Reads the required length, returns EOFError if gets less

If length is None, then read all bytes

read_beUL()

Return an unsigned long read with big endian byte order

read_beUS()

Return an unsigned short from the file with big endian byte order

read_be_tag()

Read and return two unsigned shorts (big endian) from the file.

read_leUL()

Return an unsigned long read with little endian byte order

read_leUS()

Return an unsigned short from the file with little endian byte order

read_le_tag()

Read and return two unsigned shorts (little endian) from the file.

write_UL(val)

Write an unsigned long with little endian byte order

write_US(val)

Write an unsigned short with little endian byte order

write_beUL(val)

Write an unsigned long with big endian byte order

write_beUS(val)

Write an unsigned short with big endian byte order

write_leUL(val)

Write an unsigned long with little endian byte order

write_leUS(val)

Write an unsigned short with little endian byte order

write_tag(tag)

Write a dicom tag (two unsigned shorts) to the file.

Handling a DicomDir object - the dicomdir module

Module for DicomDir class

class pydicom.dicomdir.DicomDir(filename_or_obj, dataset, preamble=None, file_meta=None, is_implicit_VR=True, is_little_endian=True)

Hold a DICOMDIR dataset read from file.

Derived from FileDataset, but additional methods are available, specific to the Directory structure

Attributes

is_original_encoding	Return True if the properties to be used for writing are set and have the same value as the ones in the dataset after reading it.
pixel_array	Return the Pixel Data as a NumPy array.

Methods

add(data_element)	Add a DataElement to the Dataset.
add_new(tag, VR, value)	Add a DataElement to the Dataset.
clear()	Delete all data elements.
convert_pixel_data()	Convert the Pixel Data to a numpy array internally.
data_element(name)	Return the DataElement corresponding to the element keyword name.
decode()	Apply character set decoding to all DataElements in the Dataset.
decompress()	Decompresses pixel data and modifies the Dataset in-place
dir(*filters)	Return an alphabetical list of DataElement keywords in the Dataset.
elements()	Iterate through the top-level of the Dataset, yielding DataElements or RawDataElements (no conversion done).
ensure_file_meta()	Create an empty file meta dataset if none exists.
fix_meta_info([enforce_standard])	Ensure the file meta info exists and has the correct values for transfer syntax and media storage uids.
formatted_lines([element_format, …])	Iterate through the Dataset yielding formatted str for each element.
get(key[, default])	Simulate dict.get() to handle DICOM DataElement tags and keywords.
get_item(key)	Return the raw data element if possible.
group_dataset(group)	Return a Dataset containing only DataElements of a certain group.
iterall()	Iterate through the Dataset, yielding all DataElements.
keys()	Return the DICOM tag keys to simulate dict.
parse_records()	Build the hierarchy of given directory records, and structure into Patient, Studies, Series, Images hierarchy.
pop(*args, **kwargs)
popitem()
remove_private_tags()	Remove all private DataElements in the Dataset.
save_as(filename[, write_like_original])	Write the Dataset to filename.
set_original_encoding(is_implicit_vr, …)	Set the values for the original transfer syntax and encoding.
setdefault(*args, **kwargs)
top()	Return a str of the Dataset’s top level DataElements only.
trait_names()	Return a list of valid names for auto-completion code.
update(dictionary)	Extend dict.update() to handle DICOM keywords.
values()	Return the DICOM tag values to simulate dict.
walk(callback[, recursive])	Iterate through the DataElements and run callback on each.

parse_records()

Build the hierarchy of given directory records, and structure into Patient, Studies, Series, Images hierarchy.

This is intended for initial read of file only, it will not reorganize correctly if records are changed.

Returns:None

Helper functions for reading files - the fileutil module

Functions for reading to certain bytes, e.g. delimiters.

pydicom.fileutil.absorb_delimiter_item(fp, is_little_endian, delimiter)

Read (and ignore) undefined length sequence or item terminators.

pydicom.fileutil.find_bytes(fp, bytes_to_find, read_size=128, rewind=True)

Read in the file until a specific byte sequence found.

Parameters:

fp : file-like object

bytes_to_find : str

Contains the bytes to find. Must be in correct endian order already.

read_size : int

Number of bytes to read at a time.

rewind : boolean

Flag to rewind file reading position.

Returns:

found_at : byte, None

Position where byte sequence was found, else None.

pydicom.fileutil.find_delimiter(fp, delimiter, is_little_endian, read_size=128, rewind=True)

Return file position where 4-byte delimiter is located.

Parameters:

delimiter :

is_little_endian : boolean

read_size : int

See find_bytes for parameter info.

rewind : boolean

Flag to rewind to initial position after searching.

Returns:

file position of delimiter, None

Returns None if end of file is reached without finding the delimiter.

pydicom.fileutil.length_of_undefined_length(fp, delimiter, is_little_endian, read_size=128, rewind=True)

Search through the file to find the delimiter and return the length of the data element.

Parameters:

fp : file-like object

delimiter :

See find_delimiter for parameter info.

is_little_endian : boolean

read_size : int

See find_bytes for parameter info.

rewind : boolean

Flag to rewind to initial position after searching.

Returns:

length to delimiter

Notes

Note the data element that the delimiter starts is not read here, the calling routine must handle that. Delimiter must be 4 bytes long.

pydicom.fileutil.read_delimiter_item(fp, delimiter)

Read and ignore an expected delimiter.

If the delimiter is not found or correctly formed, a warning is logged.

pydicom.fileutil.read_undefined_length_value(fp, is_little_endian, delimiter_tag, defer_size=None, read_size=8192)

Read until the delimiter tag found and return the value;

ignore the delimiter.

On completion, the file will be set to the first byte after the delimiter and its following four zero bytes.

Parameters:

fp : a file-like object

is_little_endian : boolean

True if file transfer syntax is little endian, else False.

delimiter_tag : BaseTag

tag used as and marker for reading

defer_size : int, None, optional

Size to avoid loading large elements in memory. See filereader.dcmread for more parameter info.

read_size : int

Number of bytes to read at one time.

Returns:

delimiter : str, None

The file delimiter

Raises:

EOFError

If EOF is reached before delimiter found.

DICOM Tag related modules

DICOM data dictionary - the datadict module

Access dicom dictionary information

pydicom.datadict.add_dict_entries(new_entries_dict)

Update pydicom’s DICOM dictionary with new entries.

Parameters:

new_entries_dict : dict

Dictionary of form: {tag: (VR, VM, description, is_retired, keyword),…} where parameters are as described in add_dict_entry

See also

add_dict_entry

Simpler function to add a single entry to the dictionary.

Examples

>>> from pydicom import Dataset
>>> new_dict_items = {
...        0x10011001: ('UL', '1', "Test One", '', 'TestOne'),
...        0x10011002: ('DS', '3', "Test Two", '', 'TestTwo'),
... }
>>> add_dict_entries(new_dict_items)
>>> ds = Dataset()
>>> ds.TestOne = 'test'
>>> ds.TestTwo = ['1', '2', '3']

>>> add_dict_entry(0x10011001, "UL", "TestOne", "Test One")
>>> ds = Dataset()
>>> ds.TestOne = 'test'

pydicom.datadict.add_dict_entry(tag, VR, keyword, description, VM='1', is_retired='')

Update pydicom’s DICOM dictionary with a new entry.

Dose not permanently update the dictionary, but only during run-time. Will replace an existing entry if the tag already exists in the dictionary.

Parameters:

tag : int

The tag number for the new dictionary entry

VR : str

DICOM value representation

description : str

The descriptive name used in printing the entry. Often the same as the keyword, but with spaces between words.

VM : str, optional

DICOM value multiplicity. If not specified, then ‘1’ is used.

is_retired : str, optional

Usually leave as blank string (default). Set to ‘Retired’ if is a retired data element.

See also

pydicom.examples.add_dict_entry

Example file which shows how to use this function

add_dict_entries

Update multiple values at once.

Examples

>>> from pydicom import Dataset
>>> add_dict_entry(0x10011001, "UL", "TestOne", "Test One")
>>> add_dict_entry(0x10011002, "DS", "TestTwo", "Test Two", VM='3')
>>> ds = Dataset()
>>> ds.TestOne = 'test'
>>> ds.TestTwo = ['1', '2', '3']

pydicom.datadict.dictionary_VM(tag)

Return the dicom value multiplicity for the given dicom tag.

pydicom.datadict.dictionary_VR(tag)

Return the dicom value representation for the given dicom tag.

pydicom.datadict.dictionary_description(tag)

Return the descriptive text for the given dicom tag.

pydicom.datadict.dictionary_has_tag(tag)

Return True if the dicom dictionary has an entry for the given tag.

pydicom.datadict.dictionary_is_retired(tag)

Return True if the dicom retired status is ‘Retired’ for the given tag

pydicom.datadict.dictionary_keyword(tag)

Return the official DICOM standard (since 2011) keyword for the tag

pydicom.datadict.get_entry(tag)

Return the tuple (VR, VM, name, is_retired, keyword) from the DICOM dictionary

If the entry is not in the main dictionary, check the masked ones, e.g. repeating groups like 50xx, etc.

pydicom.datadict.get_private_entry(tag, private_creator)

Return the tuple (VR, VM, name, is_retired) from a private dictionary

pydicom.datadict.keyword_for_tag(tag)

Return the DICOM keyword for the given tag.

Will return GroupLength for group length tags, and returns empty string (“”) if the tag doesn’t exist in the dictionary.

pydicom.datadict.private_dictionary_VM(tag, private_creator)

Return the dicom value multiplicity for the given dicom tag.

pydicom.datadict.private_dictionary_VR(tag, private_creator)

Return the dicom value representation for the given dicom tag.

pydicom.datadict.private_dictionary_description(tag, private_creator)

Return the descriptive text for the given dicom tag.

pydicom.datadict.repeater_has_keyword(keyword)

Return True if the DICOM repeaters element exists with keyword.

pydicom.datadict.repeater_has_tag(tag)

Return True if the DICOM repeaters dictionary has an entry for tag.

pydicom.datadict.tag_for_keyword(keyword)

Return the dicom tag corresponding to keyword, or None if none exist.

pydicom.datadict.tag_for_name(name)

Deprecated – use tag_for_keyword

DICOM data elements - the dataelem module

Define the DataElement class.

A DataElement has a tag,

a value representation (VR), a value multiplicity (VM) and a value.

class pydicom.dataelem.DataElement(tag, VR, value, file_value_tell=None, is_undefined_length=False, already_converted=False)

Contain and manipulate a DICOM Element.

While its possible to create a new DataElement directly and add it to a Dataset:

>>> elem = DataElement(0x00100010, 'PN', 'CITIZEN^Joan')
>>> ds = Dataset()
>>> ds.add(elem)

Its far more convenient to use a Dataset to add a new DataElement, as the VR and tag are determined automatically from the DICOM dictionary:

>>> ds = Dataset()
>>> ds.PatientName = 'CITIZEN^Joan'

Attributes

is_retired	The element’s retired status.
keyword	The element’s keyword (if known).
name	Return the DICOM dictionary name for the element.
value	Return the element’s value.
VM	Return the value multiplicity (as an int) of the element.

descripWidth	(int) For string display, this is the maximum width of the description field (default 35 characters).
file_tell	(int or None)
is_undefined_length	(bool) Indicates whether the length field for the element was 0xFFFFFFFFL (ie undefined).
maxBytesToDisplay	(int) For string display, elements with values containing data which is longer than this value will display “array of # bytes” (default 16 bytes).
showVR	(bool) For string display, include the Element’s VR just before it’s value (default True)
tag	(pydicom.tag.Tag) The DICOM Tag for the Data Element
VR	(str) The Data Element’s Value Representation value

Methods

description()

Return the DICOM dictionary name for the element.

VM

Return the value multiplicity (as an int) of the element.

description()

Return the DICOM dictionary name for the element.

is_retired

The element’s retired status.

keyword

The element’s keyword (if known).

name

Return the DICOM dictionary name for the element.

repval

Return a str representation of the element’s value.

value

Return the element’s value.

pydicom.dataelem.DataElement_from_raw(raw_data_element, encoding=None)

Return a DataElement created from the data in raw_data_element.

Parameters:

raw_data_element : RawDataElement namedtuple

The raw data to convert to a DataElement

encoding : str

The encoding of the raw data

Returns:

pydicom.dataelem.DataElement

class pydicom.dataelem.DeferredDataElement(tag, VR, fp, file_mtime, data_element_tell, length)

Subclass of DataElement where value is not read into memory until needed

Attributes

VM	Return the value multiplicity (as an int) of the element.
is_retired	The element’s retired status.
keyword	The element’s keyword (if known).
name	Return the DICOM dictionary name for the element.
repval
value	Get method for ‘value’ property

Methods

description()

Return the DICOM dictionary name for the element.

value

Get method for ‘value’ property

class pydicom.dataelem.RawDataElement(tag, VR, length, value, value_tell, is_implicit_VR, is_little_endian)

Attributes

VR	Alias for field number 1
is_implicit_VR	Alias for field number 5
is_little_endian	Alias for field number 6
length	Alias for field number 2
tag	Alias for field number 0
value	Alias for field number 3
value_tell	Alias for field number 4

Methods

count(value)
index(value, [start, [stop]])	Raises ValueError if the value is not present.

VR

Alias for field number 1

is_implicit_VR

Alias for field number 5

is_little_endian

Alias for field number 6

length

Alias for field number 2

tag

Alias for field number 0

value

Alias for field number 3

value_tell

Alias for field number 4

pydicom.dataelem.isMultiValue(value)

Return True if value is list-like (iterable), False otherwise.

pydicom.dataelem.isString(val)

Return True if val is string-like, False otherwise.

pydicom.dataelem.isStringOrStringList(val)

Return True if val is a str or an iterable containing only strings.

DICOM sequences - the sequence module

Define the Sequence class, which contains a sequence DataElement’s items.

Sequence is a list of pydicom Dataset objects.

class pydicom.sequence.Sequence(iterable=None)

Class to hold multiple Datasets in a list.

This class is derived from MultiValue and as such enforces that all items added to the list are Dataset instances. In order to due this, a validator is substituted for type_constructor when constructing the MultiValue super class

Methods

append(value)	S.append(value) – append value to the end of the sequence
clear()
count(value)
extend(values)	S.extend(iterable) – extend sequence by appending elements from the iterable
index(value, [start, [stop]])	Raises ValueError if the value is not present.
insert(position, val)
pop([index])	Raise IndexError if list is empty or index is out of range.
remove(value)	S.remove(value) – remove first occurrence of value.
reverse()	S.reverse() – reverse IN PLACE
sort([key, reverse])

pydicom.sequence.validate_dataset(elem)

Check that elem is a Dataset instance.

DICOM tags - the tag module

Define Tag class to hold a DICOM (group, element) tag and related functions.

The 4 bytes of the DICOM tag are stored as an arbitrary length ‘long’ for Python 2 and as an ‘int’ for Python 3. Tags are stored as a single number and separated to (group, element) as required.

class pydicom.tag.BaseTag

Represents a DICOM element (group, element) tag.

If using python 2.7 then tags are represented as a long, while for python 3 they are represented as an int.

Attributes

element	Return the tag’s element number.
group	Return the tag’s group number.
is_private	Return True if the tag is private (has an odd group number).

Methods

bit_length()	Number of bits necessary to represent self in binary.
conjugate	Returns self, the complex conjugate of any int.
from_bytes(bytes, byteorder, *[, signed])	Return the integer represented by the given array of bytes.
to_bytes(length, byteorder, *[, signed])	Return an array of bytes representing an integer.

elem

Return the tag’s element number.

element

Return the tag’s element number.

group

Return the tag’s group number.

is_private

Return True if the tag is private (has an odd group number).

is_private_creator

Return True if the tag is a private creator.

pydicom.tag.Tag(arg, arg2=None)

Create a Tag.

General function for creating a Tag in any of the standard forms:

• Tag(0x00100015)
• Tag(‘0x00100015’)
• Tag((0x10, 0x50))
• Tag((‘0x10’, ‘0x50’))
• Tag(0x0010, 0x0015)
• Tag(0x10, 0x15)
• Tag(2341, 0x10)
• Tag(‘0xFE’, ‘0x0010’)

Parameters:

arg : int or str or 2-tuple/list

If int or str, then either the group or the combined group/element number of the DICOM tag. If 2-tuple/list then the (group, element) numbers as int or str.

arg2 : int or str, optional

The element number of the DICOM tag, required when arg only contains the group number of the tag.

Returns:

pydicom.tag.BaseTag

pydicom.tag.TupleTag(group_elem)

Fast factory for BaseTag object with known safe (group, elem) tuple

pydicom.tag.tag_in_exception(tag)

Use tag within a context.

Used to include the tag details in the traceback message when an exception is raised within the context.

Parameters:

tag : pydicom.tag.Tag

The tag to use in the context.

DICOM tag values - the values module

Functions for converting values of DICOM data elements to proper python types

pydicom.values.convert_AE_string(byte_string, is_little_endian, struct_format=None)

Read a byte string for a VR of ‘AE’.

Elements with VR of ‘AE’ have non-significant leading and trailing spaces.

pydicom.values.convert_ATvalue(byte_string, is_little_endian, struct_format=None)

Read and return AT (tag) data_element value(s)

pydicom.values.convert_DA_string(byte_string, is_little_endian, struct_format=None)

Read and return a DA value

pydicom.values.convert_DS_string(byte_string, is_little_endian, struct_format=None)

Read and return a DS value or list of values

pydicom.values.convert_DT_string(byte_string, is_little_endian, struct_format=None)

Read and return a DT value

pydicom.values.convert_IS_string(byte_string, is_little_endian, struct_format=None)

Read and return an IS value or list of values

pydicom.values.convert_OBvalue(byte_string, is_little_endian, struct_format=None)

Return the raw bytes from reading an OB value

pydicom.values.convert_OWvalue(byte_string, is_little_endian, struct_format=None)

Return the raw bytes from reading an OW value rep

Note: pydicom does NOT do byte swapping, except in dataset.pixel_array function

pydicom.values.convert_PN(byte_string, encodings=None)

Read and return string(s) as PersonName instance(s)

pydicom.values.convert_SQ(byte_string, is_implicit_VR, is_little_endian, encoding='iso8859', offset=0)

Convert a sequence that has been read as bytes but not yet parsed.

pydicom.values.convert_TM_string(byte_string, is_little_endian, struct_format=None)

Read and return a TM value

pydicom.values.convert_UI(byte_string, is_little_endian, struct_format=None)

Read and return a UI values or values

pydicom.values.convert_UN(byte_string, is_little_endian, struct_format=None)

Return a byte string for a VR of ‘UN’ (unknown)

pydicom.values.convert_UR_string(byte_string, is_little_endian, struct_format=None)

Read a byte string for a VR of ‘UR’

Elements with VR of ‘UR’ shall not be multi-valued and trailing spaces shall be ignored.

pydicom.values.convert_numbers(byte_string, is_little_endian, struct_format)

Convert byte_string to a value,

depending on struct_format.

Given an encoded DICOM Element value, use struct_format and the endianness of the data to decode it.

Parameters:

byte_string : bytes

The raw byte data to decode.

is_little_endian : bool

The encoding of byte_string.

struct_format : str

The type of data encoded in byte_string.

Returns:

str

If there is no encoded data in byte_string then an empty string will be returned.

value

If byte_string encodes a single value

then it will be returned.

list

If byte_string encodes multiple values then a list of the decoded values will be returned.

pydicom.values.convert_single_string(byte_string, encodings=None)

Read and return a single string (backslash character does not split)

pydicom.values.convert_string(byte_string, is_little_endian, struct_format=None)

Read and return a string or strings

pydicom.values.convert_text(byte_string, encodings=None)

Read and return a string or strings

pydicom.values.convert_value(VR, raw_data_element, encodings=None)

Return the converted value (from raw bytes) for the given VR

DICOM values with VM > 1 - the multival module

Code for multi-value data elements values, or any list of items that must all be the same type.

class pydicom.multival.MultiValue(type_constructor, iterable)

Class to hold any multi-valued DICOM value, or any list of items that are all of the same type.

This class enforces that any items added to the list are of the correct type, by calling the constructor on any items that are added. Therefore, the constructor must behave nicely if passed an object that is already its type. The constructor should raise TypeError if the item cannot be converted.

Note, however, that DS and IS types can be a blank string ‘’ rather than an instance of their classes.

Methods

append(value)	S.append(value) – append value to the end of the sequence
clear()
count(value)
extend(values)	S.extend(iterable) – extend sequence by appending elements from the iterable
index(value, [start, [stop]])	Raises ValueError if the value is not present.
insert(position, val)
pop([index])	Raise IndexError if list is empty or index is out of range.
remove(value)	S.remove(value) – remove first occurrence of value.
reverse()	S.reverse() – reverse IN PLACE
sort([key, reverse])

Handling of DICOM VRs - the valuerep module

Special classes for DICOM value representations (VR)

class pydicom.valuerep.DA(val)

Store value for DICOM VR DA (Date) as datetime.date.

Note that the datetime.date base class is immutable.

Attributes

day
month
year

Methods

ctime	Return ctime() style string.
fromordinal	int -> date corresponding to a proleptic Gregorian ordinal.
fromtimestamp	timestamp -> local date from a POSIX timestamp (like time.time()).
isocalendar	Return a 3-tuple containing ISO year, week number, and weekday.
isoformat	Return string in ISO 8601 format, YYYY-MM-DD.
isoweekday	Return the day of the week represented by the date.
replace	Return date with new specified fields.
strftime	format -> strftime() style string.
timetuple	Return time tuple, compatible with time.localtime().
today	Current date or datetime: same as self.__class__.fromtimestamp(time.time()).
toordinal	Return proleptic Gregorian ordinal.
weekday	Return the day of the week represented by the date.

pydicom.valuerep.DS(val)

Factory function for creating DS class instances. Checks for blank string; if so, return that. Else calls DSfloat or DSdecimal to create the class instance. This avoids overriding __new__ in DSfloat (which carries a time penalty for large arrays of DS). Similarly the string clean and check can be avoided and DSfloat called directly if a string has already been processed.

pydicom.valuerep.DSclass

alias of pydicom.valuerep.DSfloat

class pydicom.valuerep.DSdecimal(val)

Store values for DICOM VR of DS (Decimal String). Note: if constructed by an empty string, returns the empty string, not an instance of this class.

Attributes

imag
real

Methods

adjusted($self, /)	Return the adjusted exponent of the number.
as_integer_ratio()	Return a pair of integers, whose ratio is exactly equal to the original Decimal and with a positive denominator.
as_tuple($self, /)	Return a tuple representation of the number.
canonical($self, /)	Return the canonical encoding of the argument.
compare($self, /, other[, context])	Compare self to other.
compare_signal($self, /, other[, context])	Identical to compare, except that all NaNs signal.
compare_total($self, /, other[, context])	Compare two operands using their abstract representation rather than their numerical value.
compare_total_mag($self, /, other[, context])	Compare two operands using their abstract representation rather than their value as in compare_total(), but ignoring the sign of each operand.
conjugate($self, /)	Return self.
copy_abs($self, /)	Return the absolute value of the argument.
copy_negate($self, /)	Return the negation of the argument.
copy_sign($self, /, other[, context])	Return a copy of the first operand with the sign set to be the same as the sign of the second operand.
exp($self, /[, context])	Return the value of the (natural) exponential function e**x at the given number.
fma($self, /, other, third[, context])	Fused multiply-add.
from_float($type, f, /)	Class method that converts a float to a decimal number, exactly.
is_canonical($self, /)	Return True if the argument is canonical and False otherwise.
is_finite($self, /)	Return True if the argument is a finite number, and False if the argument is infinite or a NaN.
is_infinite($self, /)	Return True if the argument is either positive or negative infinity and False otherwise.
is_nan($self, /)	Return True if the argument is a (quiet or signaling) NaN and False otherwise.
is_normal($self, /[, context])	Return True if the argument is a normal finite non-zero number with an adjusted exponent greater than or equal to Emin.
is_qnan($self, /)	Return True if the argument is a quiet NaN, and False otherwise.
is_signed($self, /)	Return True if the argument has a negative sign and False otherwise.
is_snan($self, /)	Return True if the argument is a signaling NaN and False otherwise.
is_subnormal($self, /[, context])	Return True if the argument is subnormal, and False otherwise.
is_zero($self, /)	Return True if the argument is a (positive or negative) zero and False otherwise.
ln($self, /[, context])	Return the natural (base e) logarithm of the operand.
log10($self, /[, context])	Return the base ten logarithm of the operand.
logb($self, /[, context])	For a non-zero number, return the adjusted exponent of the operand as a Decimal instance.
logical_and($self, /, other[, context])	Return the digit-wise ‘and’ of the two (logical) operands.
logical_invert($self, /[, context])	Return the digit-wise inversion of the (logical) operand.
logical_or($self, /, other[, context])	Return the digit-wise ‘or’ of the two (logical) operands.
logical_xor($self, /, other[, context])	Return the digit-wise ‘exclusive or’ of the two (logical) operands.
max($self, /, other[, context])	Maximum of self and other.
max_mag($self, /, other[, context])	Similar to the max() method, but the comparison is done using the absolute values of the operands.
min($self, /, other[, context])	Minimum of self and other.
min_mag($self, /, other[, context])	Similar to the min() method, but the comparison is done using the absolute values of the operands.
next_minus($self, /[, context])	Return the largest number representable in the given context (or in the current default context if no context is given) that is smaller than the given operand.
next_plus($self, /[, context])	Return the smallest number representable in the given context (or in the current default context if no context is given) that is larger than the given operand.
next_toward($self, /, other[, context])	If the two operands are unequal, return the number closest to the first operand in the direction of the second operand.
normalize($self, /[, context])	Normalize the number by stripping the rightmost trailing zeros and converting any result equal to Decimal(‘0’) to Decimal(‘0e0’).
number_class($self, /[, context])	Return a string describing the class of the operand.
quantize($self, /, exp[, rounding, context])	Return a value equal to the first operand after rounding and having the exponent of the second operand.
radix($self, /)	Return Decimal(10), the radix (base) in which the Decimal class does all its arithmetic.
remainder_near($self, /, other[, context])	Return the remainder from dividing self by other.
rotate($self, /, other[, context])	Return the result of rotating the digits of the first operand by an amount specified by the second operand.
same_quantum($self, /, other[, context])	Test whether self and other have the same exponent or whether both are NaN.
scaleb($self, /, other[, context])	Return the first operand with the exponent adjusted the second.
shift($self, /, other[, context])	Return the result of shifting the digits of the first operand by an amount specified by the second operand.
sqrt($self, /[, context])	Return the square root of the argument to full precision.
to_eng_string($self, /[, context])	Convert to an engineering-type string.
to_integral($self, /[, rounding, context])	Identical to the to_integral_value() method.
to_integral_exact($self, /[, rounding, context])	Round to the nearest integer, signaling Inexact or Rounded as appropriate if rounding occurs.
to_integral_value($self, /[, rounding, context])	Round to the nearest integer without signaling Inexact or Rounded.

class pydicom.valuerep.DSfloat(val)

Store values for DICOM VR of DS (Decimal String) as a float.

If constructed from an empty string, return the empty string, not an instance of this class.

Attributes

imag	the imaginary part of a complex number
real	the real part of a complex number

Methods

as_integer_ratio()	Return a pair of integers, whose ratio is exactly equal to the original float and with a positive denominator.
conjugate	Return self, the complex conjugate of any float.
fromhex(string)	Create a floating-point number from a hexadecimal string.
hex()	Return a hexadecimal representation of a floating-point number.
is_integer	Return True if the float is an integer.

class pydicom.valuerep.DT(val)

Store value for DICOM VR DT (DateTime) as datetime.datetime.

Note that the datetime.datetime base class is immutable.

Attributes

day
fold
hour
microsecond
minute
month
second
tzinfo
year

Methods

astimezone	tz -> convert to local time in new timezone tz
combine	date, time -> datetime with same date and time fields
ctime	Return ctime() style string.
date	Return date object with same year, month and day.
dst	Return self.tzinfo.dst(self).
fromordinal	int -> date corresponding to a proleptic Gregorian ordinal.
fromtimestamp	timestamp[, tz] -> tz’s local time from POSIX timestamp.
isocalendar	Return a 3-tuple containing ISO year, week number, and weekday.
isoformat	[sep] -> string in ISO 8601 format, YYYY-MM-DDT[HH[:MM[:SS[.mmm[uuu]]]]][+HH:MM].
isoweekday	Return the day of the week represented by the date.
now($type, /[, tz])	Returns new datetime object representing current time local to tz.
replace	Return datetime with new specified fields.
strftime	format -> strftime() style string.
strptime	string, format -> new datetime parsed from a string (like time.strptime()).
time	Return time object with same time but with tzinfo=None.
timestamp	Return POSIX timestamp as float.
timetuple	Return time tuple, compatible with time.localtime().
timetz	Return time object with same time and tzinfo.
today	Current date or datetime: same as self.__class__.fromtimestamp(time.time()).
toordinal	Return proleptic Gregorian ordinal.
tzname	Return self.tzinfo.tzname(self).
utcfromtimestamp	Construct a naive UTC datetime from a POSIX timestamp.
utcnow	Return a new datetime representing UTC day and time.
utcoffset	Return self.tzinfo.utcoffset(self).
utctimetuple	Return UTC time tuple, compatible with time.localtime().
weekday	Return the day of the week represented by the date.

class pydicom.valuerep.IS(val)

Derived class of int. Stores original integer string for exact rewriting of the string originally read or stored.

Attributes

denominator	the denominator of a rational number in lowest terms
imag	the imaginary part of a complex number
numerator	the numerator of a rational number in lowest terms
real	the real part of a complex number

Methods

bit_length()	Number of bits necessary to represent self in binary.
conjugate	Returns self, the complex conjugate of any int.
from_bytes(bytes, byteorder, *[, signed])	Return the integer represented by the given array of bytes.
to_bytes(length, byteorder, *[, signed])	Return an array of bytes representing an integer.

pydicom.valuerep.MultiString(val, valtype=<class 'str'>)

Split a bytestring by delimiters if there are any

val – DICOM bytestring to split up valtype – default str, but can be e.g. UID to overwrite to a specific type

class pydicom.valuerep.PersonName(val)

Human-friendly class to hold VR of Person Name (PN)

Name is parsed into the following properties: single-byte, ideographic, and phonetic components (PS3.5-2008 6.2.1) family_name, given_name, middle_name, name_prefix, name_suffix

Methods

capitalize()	Return a copy of B with only its first character capitalized (ASCII) and the rest lower-cased.
center(width[, fillchar])	Return B centered in a string of length width.
count(sub[, start[, end]])	Return the number of non-overlapping occurrences of subsection sub in bytes B[start:end].
decode($self, /[, encoding, errors])	Decode the bytes using the codec registered for encoding.
encode(*args)	Dummy method to mimic py2 str behavior in py3 bytes subclass
endswith(suffix[, start[, end]])	Return True if B ends with the specified suffix, False otherwise.
expandtabs([tabsize])	Return a copy of B where all tab characters are expanded using spaces.
family_comma_given()	Return name as ‘Family-name, Given-name’
find(sub[, start[, end]])	Return the lowest index in B where subsection sub is found, such that sub is contained within B[start,end].
formatted(format_str)	Return a formatted string according to the format pattern
fromhex($type, string, /)	Create a bytes object from a string of hexadecimal numbers.
hex()	Create a string of hexadecimal numbers from a bytes object.
index(sub[, start[, end]])	Return the lowest index in B where subsection sub is found, such that sub is contained within B[start,end].
isalnum()	Return True if all characters in B are alphanumeric and there is at least one character in B, False otherwise.
isalpha()	Return True if all characters in B are alphabetic and there is at least one character in B, False otherwise.
isdigit()	Return True if all characters in B are digits and there is at least one character in B, False otherwise.
islower()	Return True if all cased characters in B are lowercase and there is at least one cased character in B, False otherwise.
isspace()	Return True if all characters in B are whitespace and there is at least one character in B, False otherwise.
istitle()	Return True if B is a titlecased string and there is at least one character in B, i.e.
isupper()	Return True if all cased characters in B are uppercase and there is at least one cased character in B, False otherwise.
join($self, iterable_of_bytes, /)	Concatenate any number of bytes objects.
ljust(width[, fillchar])	Return B left justified in a string of length width.
lower()	Return a copy of B with all ASCII characters converted to lowercase.
lstrip($self[, bytes])	Strip leading bytes contained in the argument.
maketrans(frm, to, /)	Return a translation table useable for the bytes or bytearray translate method.
parse()	Break down the components and name parts
partition($self, sep, /)	Partition the bytes into three parts using the given separator.
replace($self, old, new[, count])	Return a copy with all occurrences of substring old replaced by new.
rfind(sub[, start[, end]])	Return the highest index in B where subsection sub is found, such that sub is contained within B[start,end].
rindex(sub[, start[, end]])	Return the highest index in B where subsection sub is found, such that sub is contained within B[start,end].
rjust(width[, fillchar])	Return B right justified in a string of length width.
rpartition($self, sep, /)	Partition the bytes into three parts using the given separator.
rsplit($self, /[, sep, maxsplit])	Return a list of the sections in the bytes, using sep as the delimiter.
rstrip($self[, bytes])	Strip trailing bytes contained in the argument.
split($self, /[, sep, maxsplit])	Return a list of the sections in the bytes, using sep as the delimiter.
splitlines($self, /[, keepends])	Return a list of the lines in the bytes, breaking at line boundaries.
startswith(prefix[, start[, end]])	Return True if B starts with the specified prefix, False otherwise.
strip($self[, bytes])	Strip leading and trailing bytes contained in the argument.
swapcase()	Return a copy of B with uppercase ASCII characters converted to lowercase ASCII and vice versa.
title()	Return a titlecased version of B, i.e.
translate($self, table, /[, delete])	Return a copy with each character mapped by the given translation table.
upper()	Return a copy of B with all ASCII characters converted to uppercase.
zfill(width)	Pad a numeric string B with zeros on the left, to fill a field of the specified width.

encode(*args)

Dummy method to mimic py2 str behavior in py3 bytes subclass

family_comma_given()

Return name as ‘Family-name, Given-name’

class pydicom.valuerep.PersonNameBase(val)

Base class for Person Name classes

Methods

formatted(format_str)	Return a formatted string according to the format pattern
parse()	Break down the components and name parts

formatted(format_str)

Return a formatted string according to the format pattern

Use “…%(property)…%(property)…” where property is one of family_name, given_name,

middle_name, name_prefix, name_suffix

parse()

Break down the components and name parts

class pydicom.valuerep.PersonNameUnicode(val, encodings)

Unicode version of Person Name

Methods

capitalize()	Return a capitalized version of S, i.e.
casefold()	Return a version of S suitable for caseless comparisons.
center(width[, fillchar])	Return S centered in a string of length width.
count(sub[, start[, end]])	Return the number of non-overlapping occurrences of substring sub in string S[start:end].
encode(encodings)	Encode the unicode using the specified encoding
endswith(suffix[, start[, end]])	Return True if S ends with the specified suffix, False otherwise.
expandtabs([tabsize])	Return a copy of S where all tab characters are expanded using spaces.
family_comma_given()	Return name as ‘Family-name, Given-name’
find(sub[, start[, end]])	Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
format(*args, **kwargs)	Return a formatted version of S, using substitutions from args and kwargs.
format_map(mapping)	Return a formatted version of S, using substitutions from mapping.
formatted(format_str)	Return a formatted string according to the format pattern
index(sub[, start[, end]])	Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
isalnum()	Return True if all characters in S are alphanumeric and there is at least one character in S, False otherwise.
isalpha()	Return True if all characters in S are alphabetic and there is at least one character in S, False otherwise.
isdecimal()	Return True if there are only decimal characters in S, False otherwise.
isdigit()	Return True if all characters in S are digits and there is at least one character in S, False otherwise.
isidentifier()	Return True if S is a valid identifier according to the language definition.
islower()	Return True if all cased characters in S are lowercase and there is at least one cased character in S, False otherwise.
isnumeric()	Return True if there are only numeric characters in S, False otherwise.
isprintable()	Return True if all characters in S are considered printable in repr() or S is empty, False otherwise.
isspace()	Return True if all characters in S are whitespace and there is at least one character in S, False otherwise.
istitle()	Return True if S is a titlecased string and there is at least one character in S, i.e.
isupper()	Return True if all cased characters in S are uppercase and there is at least one cased character in S, False otherwise.
join(iterable)	Return a string which is the concatenation of the strings in the iterable.
ljust(width[, fillchar])	Return S left-justified in a Unicode string of length width.
lower()	Return a copy of the string S converted to lowercase.
lstrip([chars])	Return a copy of the string S with leading whitespace removed.
maketrans(x[, y, z])	Return a translation table usable for str.translate().
parse()	Break down the components and name parts
partition(sep)	Search for the separator sep in S, and return the part before it, the separator itself, and the part after it.
replace(old, new[, count])	Return a copy of S with all occurrences of substring old replaced by new.
rfind(sub[, start[, end]])	Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
rindex(sub[, start[, end]])	Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
rjust(width[, fillchar])	Return S right-justified in a string of length width.
rpartition(sep)	Search for the separator sep in S, starting at the end of S, and return the part before it, the separator itself, and the part after it.
rsplit([sep, maxsplit])	Return a list of the words in S, using sep as the delimiter string, starting at the end of the string and working to the front.
rstrip([chars])	Return a copy of the string S with trailing whitespace removed.
split([sep, maxsplit])	Return a list of the words in S, using sep as the delimiter string.
splitlines([keepends])	Return a list of the lines in S, breaking at line boundaries.
startswith(prefix[, start[, end]])	Return True if S starts with the specified prefix, False otherwise.
strip([chars])	Return a copy of the string S with leading and trailing whitespace removed.
swapcase()	Return a copy of S with uppercase characters converted to lowercase and vice versa.
title()	Return a titlecased version of S, i.e.
translate(table)	Return a copy of the string S in which each character has been mapped through the given translation table.
upper()	Return a copy of S converted to uppercase.
zfill(width)	Pad a numeric string S with zeros on the left, to fill a field of the specified width.

encode(encodings)

Encode the unicode using the specified encoding

family_comma_given()

Return name as ‘Family-name, Given-name’

class pydicom.valuerep.TM(val)

Store value for DICOM VR of TM (Time) as datetime.time.

Note that the datetime.time base class is immutable.

Attributes

fold
hour
microsecond
minute
second
tzinfo

Methods

dst	Return self.tzinfo.dst(self).
isoformat	Return string in ISO 8601 format, [HH[:MM[:SS[.mmm[uuu]]]]][+HH:MM].
replace	Return time with new specified fields.
strftime	format -> strftime() style string.
tzname	Return self.tzinfo.tzname(self).
utcoffset	Return self.tzinfo.utcoffset(self).

Handling of character encoding - the charset module

Handle alternate character sets for character strings.

pydicom.charset.convert_encodings(encodings)

Converts DICOM encodings into corresponding python encodings. Handles some common spelling mistakes and issues a warning in this case. Handled stand-alone encodings: if they are the first encodings, additional encodings are ignored, if they are not the first encoding, they are ignored. In both cases, a warning is issued.

Parameters:

encodings : list of str

The list of encodings as read from Specific Character Set.

Returns:

list of str

The list of Python encodings corresponding to the DICOM encodings. If conversion fails, encodings is returned unchanged, assuming that it already has been converted to Python encodings.

pydicom.charset.decode(data_element, dicom_character_set)

Apply the DICOM character encoding to the data element

data_element – DataElement instance containing a value to convert dicom_character_set – the value of Specific Character Set (0008,0005),

which may be a single value, a multiple value (code extension), or may also be ‘’ or None. If blank or None, ISO_IR 6 is used.

pydicom.charset.decode_string(value, encodings, delimiters)

Convert a raw byte string into a unicode string using the given list of encodings.

Parameters:

value : byte string

The raw string as encoded in the DICOM tag value.

encodings : list

The encodings needed to decode the string as a list of Python encodings, converted from the encodings in Specific Character Set.

delimiters: set of int (Python 3) or characters (Python 2)

A set of characters or character codes, each of which resets the encoding in byte_str.

Returns:

text type

The decoded unicode string. If the value could not be decoded, and config.enforce_valid_values is not set, a warning is issued, and the value is decoded using the first encoding with replacement characters, resulting in data loss.

Raises:

UnicodeDecodeError

If config.enforce_valid_values is set and value could not be decoded with the given encodings.

pydicom.charset.encode_string(value, encodings)

Convert a unicode string into a byte string using the given list of encodings.

Parameters:

value : text type

The unicode string as presented to the user.

encodings : list

The encodings needed to encode the string as a list of Python encodings, converted from the encodings in Specific Character Set.

Returns:

byte string

The encoded string. If the value could not be encoded with any of the given encodings, and config.enforce_valid_values is not set, a warning is issued, and the value is encoded using the first encoding with replacement characters, resulting in data loss.

Raises:

UnicodeEncodeError

If config.enforce_valid_values is set and value could not be encoded with the given encodings.

DICOM UIDs - the uid module

Functions for handling DICOM unique identifiers (UIDs)

class pydicom.uid.UID

Subclass python string so have human-friendly UIDs.

Attributes

info	Return the UID info from the UID dictionary.
is_compressed	Return True if a compressed transfer syntax UID.
is_deflated	Return True if a deflated transfer syntax UID.
is_encapsulated	Return True if an encasulated transfer syntax UID.
is_implicit_VR	Return True if an implicit VR transfer syntax UID.
is_little_endian	Return True if a little endian transfer syntax UID.
is_private	Return True if the UID isn’t an officially registered DICOM UID.
is_retired	Return True if the UID is retired, False otherwise or if private.
is_transfer_syntax	Return True if a transfer syntax UID.
is_valid	Return True if self is a valid UID, False otherwise.
name	Return the UID name from the UID dictionary.
type	Return the UID type from the UID dictionary.

Methods

capitalize()	Return a capitalized version of S, i.e.
casefold()	Return a version of S suitable for caseless comparisons.
center(width[, fillchar])	Return S centered in a string of length width.
count(sub[, start[, end]])	Return the number of non-overlapping occurrences of substring sub in string S[start:end].
encode([encoding, errors])	Encode S using the codec registered for encoding.
endswith(suffix[, start[, end]])	Return True if S ends with the specified suffix, False otherwise.
expandtabs([tabsize])	Return a copy of S where all tab characters are expanded using spaces.
find(sub[, start[, end]])	Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
format(*args, **kwargs)	Return a formatted version of S, using substitutions from args and kwargs.
format_map(mapping)	Return a formatted version of S, using substitutions from mapping.
index(sub[, start[, end]])	Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end].
isalnum()	Return True if all characters in S are alphanumeric and there is at least one character in S, False otherwise.
isalpha()	Return True if all characters in S are alphabetic and there is at least one character in S, False otherwise.
isdecimal()	Return True if there are only decimal characters in S, False otherwise.
isdigit()	Return True if all characters in S are digits and there is at least one character in S, False otherwise.
isidentifier()	Return True if S is a valid identifier according to the language definition.
islower()	Return True if all cased characters in S are lowercase and there is at least one cased character in S, False otherwise.
isnumeric()	Return True if there are only numeric characters in S, False otherwise.
isprintable()	Return True if all characters in S are considered printable in repr() or S is empty, False otherwise.
isspace()	Return True if all characters in S are whitespace and there is at least one character in S, False otherwise.
istitle()	Return True if S is a titlecased string and there is at least one character in S, i.e.
isupper()	Return True if all cased characters in S are uppercase and there is at least one cased character in S, False otherwise.
join(iterable)	Return a string which is the concatenation of the strings in the iterable.
ljust(width[, fillchar])	Return S left-justified in a Unicode string of length width.
lower()	Return a copy of the string S converted to lowercase.
lstrip([chars])	Return a copy of the string S with leading whitespace removed.
maketrans(x[, y, z])	Return a translation table usable for str.translate().
partition(sep)	Search for the separator sep in S, and return the part before it, the separator itself, and the part after it.
replace(old, new[, count])	Return a copy of S with all occurrences of substring old replaced by new.
rfind(sub[, start[, end]])	Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
rindex(sub[, start[, end]])	Return the highest index in S where substring sub is found, such that sub is contained within S[start:end].
rjust(width[, fillchar])	Return S right-justified in a string of length width.
rpartition(sep)	Search for the separator sep in S, starting at the end of S, and return the part before it, the separator itself, and the part after it.
rsplit([sep, maxsplit])	Return a list of the words in S, using sep as the delimiter string, starting at the end of the string and working to the front.
rstrip([chars])	Return a copy of the string S with trailing whitespace removed.
split([sep, maxsplit])	Return a list of the words in S, using sep as the delimiter string.
splitlines([keepends])	Return a list of the lines in S, breaking at line boundaries.
startswith(prefix[, start[, end]])	Return True if S starts with the specified prefix, False otherwise.
strip([chars])	Return a copy of the string S with leading and trailing whitespace removed.
swapcase()	Return a copy of S with uppercase characters converted to lowercase and vice versa.
title()	Return a titlecased version of S, i.e.
translate(table)	Return a copy of the string S in which each character has been mapped through the given translation table.
upper()	Return a copy of S converted to uppercase.
zfill(width)	Pad a numeric string S with zeros on the left, to fill a field of the specified width.

info

Return the UID info from the UID dictionary.

is_compressed

Return True if a compressed transfer syntax UID.

is_deflated

Return True if a deflated transfer syntax UID.

is_encapsulated

Return True if an encasulated transfer syntax UID.

is_implicit_VR

Return True if an implicit VR transfer syntax UID.

is_little_endian

Return True if a little endian transfer syntax UID.

is_private

Return True if the UID isn’t an officially registered DICOM UID.

is_retired

Return True if the UID is retired, False otherwise or if private.

is_transfer_syntax

Return True if a transfer syntax UID.

is_valid

Return True if self is a valid UID, False otherwise.

name

Return the UID name from the UID dictionary.

type

Return the UID type from the UID dictionary.

pydicom.uid.generate_uid(prefix='1.2.826.0.1.3680043.8.498.', entropy_srcs=None)

Return a 64 character UID which starts with prefix.

Parameters:

prefix : str or None

The UID prefix to use when creating the UID. Default is the pydicom root UID ‘1.2.826.0.1.3680043.8.498.’. If None then a value of ‘2.25.’ will be used (as described on David Clunie’s website).

entropy_srcs : list of str or None

If a list of str, the prefix will be appended with a SHA512 hash of the list which means the result is deterministic and should make the original data unrecoverable. If None random data will be used (default).

Returns:

pydicom.uid.UID

A 64 character DICOM UID.

Raises:

ValueError

If prefix is invalid or greater than 63 characters.

Various helper modules

Configuration of pydicom behavior - the config module

Pydicom configuration options.

pydicom.config.DS_decimal(use_Decimal_boolean=True)

Set DS class to be derived from Decimal (True) or from float (False) If this function is never called, the default in pydicom >= 0.9.8 is for DS to be based on float.

pydicom.config.allow_DS_float = False

Set allow_float to True to allow DSdecimal instances to be created with floats; otherwise, they must be explicitly converted to strings, with the user explicity setting the precision of digits and rounding. Default: False

pydicom.config.data_element_callback = None

Set data_element_callback to a function to be called from read_dataset every time a RawDataElement has been returned, before it is added to the dataset.

pydicom.config.data_element_callback_kwargs = {}

Set this to use as keyword arguments passed to the data_element_callback function

pydicom.config.datetime_conversion = False

Set datetime_conversion to convert DA, DT and TM data elements to datetime.date, datetime.datetime and datetime.time respectively. Default: False

pydicom.config.debug(debug_on=True)

Turn debugging of DICOM file reading and writing on or off. When debugging is on, file location and details about the elements read at that location are logged to the ‘pydicom’ logger using python’s logging module.

Parameters:debug_on – True (default) to turn on debugging,

False to turn off.

pydicom.config.enforce_valid_values = False

Raise errors if any value is not allowed by DICOM standard, e.g. DS strings that are longer than 16 characters; IS strings outside the allowed range.

pydicom.config.image_handlers = [<module 'pydicom.pixel_data_handlers.numpy_handler' from '/build/pydicom-1.2.1/pydicom/pixel_data_handlers/numpy_handler.py'>, <module 'pydicom.pixel_data_handlers.rle_handler' from '/build/pydicom-1.2.1/pydicom/pixel_data_handlers/rle_handler.py'>, <module 'pydicom.pixel_data_handlers.pillow_handler' from '/build/pydicom-1.2.1/pydicom/pixel_data_handlers/pillow_handler.py'>]

Handlers for converting (7fe0,0010) Pixel Data. This is an ordered list that the dataset.convert_pixel_data() method will try to extract a correctly sized numpy array from the PixelData element.

Handers shall have two methods:

def supports_transfer_syntax(ds)

This returns True if the handler might support the transfer syntax indicated in the dicom_dataset

def get_pixeldata(ds):

This shall either throw an exception or return a correctly sized numpy array derived from the PixelData. Reshaping the array to the correct dimensions is handled outside the image handler

The first handler that both announces that it supports the transfer syntax and does not throw an exception, either in getting the data or when the data is reshaped to the correct dimensions, is the handler that will provide the data.

If they all fail, the last one to throw an exception gets to see its exception thrown up.

If no one throws an exception, but they all refuse to support the transfer syntax, then this fact is announced in a NotImplementedError exception.

Working with compressed pixel data - the encaps module

Functions for working with encapsulated (compressed) pixel data.

pydicom.encaps.decode_data_sequence(data)

Read encapsulated data and return a list of strings.

Parameters:

data : str

String of encapsulated data, typically dataset.PixelData

Returns:

list of bytes

All fragments in a list of byte strings

pydicom.encaps.defragment_data(data)

Read encapsulated data and return the fragments as one continuous string.

Parameters:

data : list of bytes

The encapsulated pixel data fragments.

Returns:

bytes

All fragments concatenated together.

pydicom.encaps.encapsulate(frames, fragments_per_frame=1, has_bot=True)

Return encapsulated frames.

Data will be encapsulated with a Basic Offset Table Item at the beginning, then one or more fragment Items. Each item will be of even length and the final fragment of each frame may be padded with 0x00 if required.

Parameters:

frames : list of bytes

The frame data to encapsulate.

fragments_per_frame : int, optional

The number of fragments to use for each frame (default 1).

has_bot : bool, optional

True to include values in the Basic Offset Table, False otherwise (default True). If fragments_per_frame is not 1 then its strongly recommended that this be True.

Returns:

bytes

The encapsulated data.

Notes

• The encoding shall be in Little Endian.
• Each fragment is encapsulated as a DICOM Item with tag (FFFE,E000), then a 4 byte length.
• The first item shall be a Basic Offset Table item.
• The Basic Offset Table item, however, is not required to have a value.
• If no value is present, the Basic Offset Table length is 0.
• If the value is present, it shall contain concatenated 32-bit unsigned integer values that are byte offsets to the first byte of the Item tag of the first fragment in each frame as measured from the first byte of the first Item tag following the Basic Offset Table Item.

References

DICOM Standard, Part 5, Section 7.5 and Annex A.4

pydicom.encaps.fragment_frame(frame, nr_fragments=1)

Yield one or more fragments from frame.

Parameters:

frame : bytes

The data to fragment.

nr_fragments : int, optional

The number of fragments (default 1).

Yields:

bytes

The fragmented data, with all fragments as an even number of bytes greater than or equal to two.

Notes

• All items containing an encoded fragment shall be made of an even number of bytes greater than or equal to two.
• The last fragment of a frame may be padded, if necessary to meet the sequence item format requirements of the DICOM Standard.
• Any necessary padding may be appended after the end of image marker.
• Encapsulated Pixel Data has the Value Representation OB.
• Values with a VR of OB shall be padded with a single trailing NULL byte value (0x00) to achieve even length.

References

DICOM Standard, Part 5, Section 6.2 and Annex A.4

pydicom.encaps.generate_pixel_data(bytestream)

Yield an encapsulated pixel data frame as a tuples of bytes.

For the following transfer syntaxes, a fragment may not contain encoded data from more than one frame. However data from one frame may span multiple fragments.

• 1.2.840.10008.1.2.4.50 - JPEG Baseline (Process 1)
• 1.2.840.10008.1.2.4.51 - JPEG Baseline (Process 2 and 4)
• 1.2.840.10008.1.2.4.57 - JPEG Lossless, Non-Hierarchical (Process 14)
• 1.2.840.10008.1.2.4.70 - JPEG Lossless, Non-Hierarchical, First-Order Prediction (Process 14 [Selection Value 1])
• 1.2.840.10008.1.2.4.80 - JPEG-LS Lossless Image Compression
• 1.2.840.10008.1.2.4.81 - JPEG-LS Lossy (Near-Lossless) Image Compression
• 1.2.840.10008.1.2.4.90 - JPEG 2000 Image Compression (Lossless Only)
• 1.2.840.10008.1.2.4.91 - JPEG 2000 Image Compression
• 1.2.840.10008.1.2.4.92 - JPEG 2000 Part 2 Multi-component Image Compression (Lossless Only)
• 1.2.840.10008.1.2.4.93 - JPEG 2000 Part 2 Multi-component Image Compression

For the following transfer syntaxes, each frame shall be encoded in one and only one fragment.

• 1.2.840.10008.1.2.5 - RLE Lossless

Parameters:

bytestream : bytes

The value of the (7fe0, 0010) Pixel Data element from an encapsulated dataset. The Basic Offset Table item should be present and the Sequence Delimiter item may or may not be present.

Yields:

tuple of bytes

A tuple representing an encapsulated pixel data frame, with the contents of the tuple the frame’s fragmented data.

References

DICOM Standard Part 5, Annex A

pydicom.encaps.generate_pixel_data_fragment(fp)

Yield the encapsulated pixel data fragments as bytes.

For compressed (encapsulated) Transfer Syntaxes, the (7fe0,0010) ‘Pixel Data’ element is encoded in an encapsulated format.

Encapsulation

The encoded pixel data stream is fragmented into one or more Items. The stream may represent a single or multi-frame image.

Each Data Stream Fragment shall have tag of (fffe,e000), followed by a 4 byte Item Length field encoding the explicit number of bytes in the Item. All Items containing an encoded fragment shall have an even number of bytes greater than or equal to 2, with the last fragment being padded if necessary.

The first Item in the Sequence of Items shall be a ‘Basic Offset Table’, however the Basic Offset Table item value is not required to be present. It is assumed that the Basic Offset Table item has already been read prior to calling this function (and that fp is positioned past this item).

The remaining items in the Sequence of Items are the pixel data fragments and it is these items that will be read and returned by this function.

The Sequence of Items is terminated by a Sequence Delimiter Item with tag (fffe,e0dd) and an Item Length field of value 0x00000000. The presence or absence of the Sequence Delimiter Item in fp has no effect on the returned fragments.

The encoding of the data shall be little endian.

Parameters:

fp : pydicom.filebase.DicomBytesIO

The encoded (7fe0,0010) Pixel Data element value, positioned at the start of the item tag for the first item after the Basic Offset Table item. fp.is_little_endian should be set to True.

Yields:

bytes

A pixel data fragment.

Raises:

ValueError

If the data contains an item with an undefined length or an unknown tag.

References

DICOM Standard Part 5, Annex A.4

pydicom.encaps.generate_pixel_data_frame(bytestream)

Yield an encapsulated pixel data frame as bytes.

Parameters:

bytestream : bytes

The value of the (7fe0, 0010) Pixel Data element from an encapsulated dataset. The Basic Offset Table item should be present and the Sequence Delimiter item may or may not be present.

Yields:

bytes

A frame contained in the encapsulated pixel data.

References

DICOM Standard Part 5, Annex A

pydicom.encaps.get_frame_offsets(fp)

Return a list of the fragment offsets from the Basic Offset Table.

Basic Offset Table

The Basic Offset Table Item must be present and have a tag (FFFE,E000) and a length, however it may or may not have a value.

Basic Offset Table with no value

Item Tag   | Length    |
FE FF 00 E0 00 00 00 00

Basic Offset Table with value (2 frames)

Item Tag   | Length    | Offset 1  | Offset 2  |
FE FF 00 E0 08 00 00 00 00 00 00 00 10 00 00 00

For single or multi-frame images with only one frame, the Basic Offset Table may or may not have a value. When it has no value then its length shall be 0x00000000.

For multi-frame images with more than one frame, the Basic Offset Table should have a value containing concatenated 32-bit unsigned integer values that are the byte offsets to the first byte of the Item tag of the first fragment of each frame as measured from the first byte of the first item tag following the Basic Offset Table Item.

All decoders, both for single and multi-frame images should accept both an empty Basic Offset Table and one containing offset values.

Parameters:

fp : pydicom.filebase.DicomBytesIO

The encapsulated pixel data positioned at the start of the Basic Offset Table. fp.is_little_endian should be set to True.

Returns:

list of int

The byte offsets to the first fragment of each frame, as measured from the start of the first item following the Basic Offset Table item.

Raises:

ValueError

If the Basic Offset Table item’s tag is not (FFEE,E000) or if the length in bytes of the item’s value is not a multiple of 4.

References

DICOM Standard Part 5, Annex A.4

pydicom.encaps.itemise_fragment(fragment)

Return an itemised fragment.

Parameters:

fragment : bytes

The fragment to itemise.

Returns:

bytes

The itemised fragment.

Notes

• The encoding of the item shall be in Little Endian.
• Each fragment is encapsulated as a DICOM Item with tag (FFFE,E000), then a 4 byte length.

pydicom.encaps.itemise_frame(frame, nr_fragments=1)

Yield items generated from frame.

Parameters:

frame : bytes

The data to fragment and itemise.

nr_fragments : int, optional

The number of fragments/items (default 1).

Yields:

bytes

An itemised fragment of the frame, encoded as little endian.

Notes

• The encoding of the items shall be in Little Endian.
• Each fragment is encapsulated as a DICOM Item with tag (FFFE,E000), then a 4 byte length.

References

DICOM Standard, Part 5, Section 7.5 and Annex A.4

pydicom.encaps.itemize_fragment(fragment)

Return an itemised fragment.

Parameters:

fragment : bytes

The fragment to itemise.

Returns:

bytes

The itemised fragment.

Notes

• The encoding of the item shall be in Little Endian.
• Each fragment is encapsulated as a DICOM Item with tag (FFFE,E000), then a 4 byte length.

pydicom.encaps.itemize_frame(frame, nr_fragments=1)

Yield items generated from frame.

Parameters:

frame : bytes

The data to fragment and itemise.

nr_fragments : int, optional

The number of fragments/items (default 1).

Yields:

bytes

An itemised fragment of the frame, encoded as little endian.

Notes

• The encoding of the items shall be in Little Endian.
• Each fragment is encapsulated as a DICOM Item with tag (FFFE,E000), then a 4 byte length.

References

DICOM Standard, Part 5, Section 7.5 and Annex A.4

pydicom.encaps.read_item(fp)

Read and return a single Item in the fragmented data stream.

Parameters:

fp : pydicom.filebase.DicomIO

The file-like to read the item from.

Returns:

bytes

The Item’s raw bytes (value?).

Miscellaneous helper functions - the misc module

Miscellaneous helper functions

pydicom.misc.is_dicom(file_path)

Boolean specifying if file is a proper DICOM file.

This function is a pared down version of read_preamble meant for a fast return. The file is read for a proper preamble (‘DICM’), returning True if so, and False otherwise. This is a conservative approach.

Parameters:

file_path : str

The path to the file.

See also

filereader.read_preamble, filereader.read_partial

pydicom.misc.size_in_bytes(expr)

Return the number of bytes for a defer_size argument to dcmread()

Pydicom-specific exceptions - the errors module

Module for pydicom exception classes

exception pydicom.errors.InvalidDicomError(*args)

Exception that is raised when the the file does not seem to be a valid dicom file, usually when the four characters “DICM” are not present at position 128 in the file. (According to the dicom specification, each dicom file should have this.)

To force reading the file (because maybe it is a dicom file without a header), use dcmread(…, force=True).