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)[source][source]

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

Note

Dataset is derived from dict only to make it work in a NumPy array. The parent dict class is never called, as all dict methods are overridden.

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:

>>> block = ds.private_block(0x0041, 'My Creator', create=True)
>>> block.add_new(0x01, 'LO', '12345')

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^John'
>>> elem = ds.data_element('PatientName')
>>> elem
(0010, 0010) Patient's Name                      PN: 'CITIZEN^John'

Retrieving a private DataElement:

>>> block = ds.private_block(0x0041, 'My Creator')
>>> elem = block[0x01]
>>> elem
(0041, 1001) Private tag data                    LO: '12345'
>>> elem.value
'12345'

Alternatively: >>> ds.get_private_item(0x0041, 0x01, ‘My Creator’).value ‘12345’

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:

>>> block = ds.private_block(0x0041, 'My Creator')
>>> if 0x01 in block:
...     del block[0x01]

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)   #doctest: +ELLIPSIS
(0010, 0010) Patient's Name                      PN: 'CITIZEN^John'...

Iterating through the entire Dataset (including Sequences):

>>> for elem in ds.iterall():
...     print(elem)  #doctest: +ELLIPSIS
(0010, 0010) Patient's Name                      PN: 'CITIZEN^John'...

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

Converting a dataset to and from json:

>>> ds = Dataset()
>>> ds.PatientName = "Some^Name"
>>> jsonmodel = ds.to_json()
>>> ds2 = Dataset()
>>> ds2.from_json(jsonmodel)
(0010, 0010) Patient's Name                      PN: u'Some^Name'
Attributes
default_element_formatstr

The default formatting for string display.

default_sequence_element_formatstr

The default formatting for string display of sequences.

indent_charsstr

For string display, the characters used to indent nested Sequences. Default is ” “.

is_little_endianbool

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_VRbool

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(self, data_element)

Add a DataElement to the Dataset.

add_new(self, tag, VR, value)

Add a DataElement to the Dataset.

clear(self)

Delete all data elements.

convert_pixel_data(self)

Convert the Pixel Data to a numpy array internally.

copy()

data_element(self, name)

Return the DataElement corresponding to the element keyword name.

decode(self)

Apply character set decoding to all DataElements in the Dataset.

decompress(self)

Decompresses pixel data and modifies the Dataset in-place

dir(self, \*filters)

Return an alphabetical list of DataElement keywords in the Dataset.

elements(self)

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

ensure_file_meta(self)

Create an empty file meta dataset if none exists.

fix_meta_info(self[, enforce_standard])

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

formatted_lines(self[, element_format, …])

Iterate through the Dataset yielding formatted str for each element.

from_json(json_dataset[, …])

Loads DICOM Data Set in DICOM JSON format.

fromkeys(iterable[, value])

Create a new dictionary with keys from iterable and values set to value.

get(self, key[, default])

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

get_item(self, key)

Return the raw data element if possible.

get_private_item(self, group, …)

Return the data element for the given private tag.

group_dataset(self, group)

Return a Dataset containing only DataElements of a certain group.

items(self)

Return the elements in the Dataset as a list of tuple.

iterall(self)

Iterate through the Dataset, yielding all DataElements.

keys(self)

Return the DICOM tag keys to simulate dict.

pop(self, key, \*args)

Emulate dictionary pop, but additionally support tag ID tuple and DICOM keyword.

popitem(self)

2-tuple; but raise KeyError if D is empty.

private_block(self, group, private_creator)

Return the block for the given tag and private creator.

private_creators(self, group)

Return a list of private creator names in the given group.

remove_private_tags(self)

Remove all private DataElements in the Dataset.

save_as(self, filename[, write_like_original])

Write the Dataset to filename.

set_original_encoding(self, is_implicit_vr, …)

Set the values for the original transfer syntax and encoding.

setdefault(self, key[, default])

Emulate dictionary setdefault, but additionally support tag ID tuple and DICOM keyword for key, and data element value for default.

to_json(self[, bulk_data_threshold, …])

Converts the data set into JSON representation based on the DICOM JSON Model http://dicom.nema.org/medical/dicom/current/output/chtml/part18/chapter_F.html.

top(self)

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

trait_names(self)

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

update(self, dictionary)

Extend dict.update() to handle DICOM keywords.

values(self)

Return the DICOM tag values to simulate dict.

walk(self, callback[, recursive])

Iterate through the DataElements and run callback on each.

add(self, data_element)[source][source]

Add a DataElement to the Dataset.

Equivalent to ds[data_element.tag] = data_element

Parameters
data_elementpydicom.dataelem.DataElement

The DataElement to add to the Dataset.

add_new(self, tag, VR, value)[source][source]

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.

VRstr

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(self)[source][source]

Delete all data elements.

convert_pixel_data(self)[source][source]

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(self, name)[source][source]

Return the DataElement corresponding to the element keyword name.

Parameters
namestr

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(self)[source][source]

Apply character set decoding to all DataElements in the Dataset.

See DICOM PS3.5-2008 6.1.1.

decompress(self)[source][source]

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(self, *filters)[source][source]

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
filtersstr

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(self)[source][source]

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

>>> ds = Dataset()
>>> 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(self)[source][source]

Create an empty file meta dataset if none exists.

fix_meta_info(self, enforce_standard=True)[source][source]

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_standardboolean

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

formatted_lines(self, 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)[source][source]

Iterate through the Dataset yielding formatted str for each element.

Parameters
element_formatstr

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_formatstr

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_formatstr or None

Placeholder for future functionality.

Yields
str

A string representation of a DataElement.

classmethod from_json(json_dataset, bulk_data_uri_handler=None, encodings=None)[source][source]

Loads DICOM Data Set in DICOM JSON format. See: http://dicom.nema.org/medical/dicom/current/output/chtml/part18/chapter_F.html

Parameters
json_dataset: Union[dict, str]

dictionary or string representing a DICOM Data Set formatted based on the DICOM JSON Model (Annex F)

bulk_data_uri_handler: Union[Callable, None]

callable that accepts the “BulkDataURI” of the JSON representation of a data element and returns the actual value of data element (retrieved via DICOMweb WADO-RS)

encodings: Union[list, None]

encodings from SpecificCharacterSet, or None for default

Returns
——-
pydicom.dataset.Dataset
get(self, key, default=None)[source][source]

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

Parameters
keystr or pydicom.tag.Tag

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

defaultobj 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(self, key)[source][source]

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
get_private_item(self, group, element_offset, private_creator)[source][source]

Return the data element for the given private tag.

This is analogous to __getitem__, but only for private tags. This allows to find the private tag for the correct private creator without the need to add the tag to the private dictionary first.

Parameters
group32 bit int

The private group where the item is located.

element_offset16 bit int

The lower 16 bit (e.g. 2 hex numbers) of the element tag.

private_creatorstr

The private creator for the tag. Must match the private creator for the tag to be returned.

Returns
pydicom.dataelem.DataElement
Raises
ValueError

If tag is not a private tag or private_creator is empty.

KeyError

If the private creator tag is not found in the given group. If the private tag is not found.

group_dataset(self, group)[source][source]

Return a Dataset containing only DataElements of a certain group.

Parameters
groupint

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

Returns
pydicom.dataset.Dataset

A dataset instance containing elements of the group specified.

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

items(self)[source][source]

Return the elements in the Dataset as a list of tuple.

Returns
list of tuple

The top-level (element tag, element) for the Dataset.

iterall(self)[source][source]

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(self)[source][source]

Return the DICOM tag keys to simulate dict.

property pixel_array

Return the Pixel Data as a NumPy array.

Returns
numpy.ndarray

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

pop(self, key, *args)[source][source]

Emulate dictionary pop, but additionally support tag ID tuple and DICOM keyword.

Removes the data element for key if it exists and returns it, otherwise returns a default value if given or raises KeyError.

Parameters
key: int or str or 2-tuple

if tuple - the group and element number of the DICOM tag if int - the combined group/element number if str - the DICOM keyword of the tag

*args: zero or one argument

defines the behavior if no tag exists for key: if given, it defines the return value, if not given, KeyError is raised

Returns
The data element for key if it exists, or the default value if given.
Raises
KeyError

If the key is not a valid tag ID or keyword. If the tag does not exist and no default is given.

popitem(self)[source][source]

2-tuple; but raise KeyError if D is empty.

private_block(self, group, private_creator, create=False)[source][source]

Return the block for the given tag and private creator.

If create is set and the private creator does not exist, the private creator tag is added. Note: We ignore the unrealistic case that no free block is available.

Parameters
group32 bit int

The group of the private tag to be found. Must be an odd number (e.g. a private group).

private_creatorstr

The private creator string associated with the tag.

createbool

If True and private_creator does not exist, a new private creator tag is added at the next free block. If False (the default) and private_creator does not exist, KeyError is raised instead.

Returns
32 bit int

Element base for the given tag (the last 2 hex digits are always 0)

Raises
ValueError

If tag is not a private tag or private_creator is empty.

KeyError

If the private creator tag is not found in the given group and the create parameter is not set.

private_creators(self, group)[source][source]

Return a list of private creator names in the given group.

This can be used to check if a given private creator exists in the group of the dataset: >>> ds = Dataset() >>> if ‘My Creator’ in ds.private_creators(0x0041): … block = ds.private_block(0x0041, ‘My Creator’)

Parameters
group32 bit int

The private group. Must be an odd number.

Returns
list of str

List of all private creator names for private blocks in the group.

Raises
ValueError

If group is not a private group.

remove_private_tags(self)[source][source]

Remove all private DataElements in the Dataset.

save_as(self, filename, write_like_original=True)[source][source]

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
filenamestr or file-like

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

write_like_originalbool

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(self, is_implicit_vr, is_little_endian, character_encoding)[source][source]

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

setdefault(self, key, default=None)[source][source]

Emulate dictionary setdefault, but additionally support tag ID tuple and DICOM keyword for key, and data element value for default.

>>> ds = Dataset()
>>> pname = ds.setdefault((0x0010, 0x0010), "Test")
>>> pname
(0010, 0010) Patient's Name                      PN: 'Test'
>>> pname.value
'Test'
>>> psex = ds.setdefault('PatientSex',
...     DataElement(0x00100040, 'CS', 'F'))
>>> psex.value
'F'
Parameters
key: int or str or 2-tuple

if tuple - the group and element number of the DICOM tag if int - the combined group/element number if str - the DICOM keyword of the tag

default: DataElement or value type or None

The default value that is inserted and returned if no data element exists for the given key. If it is not of type DataElement, a DataElement is constructed instead for the given tag ID and default as value. This is only possible for known tags (e.g. tags found via the dictionary lookup).

Returns
The data element for key if it exists, or the default value if
it is a DataElement or None, or a DataElement constructed with
default as value.
Raises
KeyError

If the key is not a valid tag ID or keyword. If no tag exists for key, default is not a DataElement and not None, and key is not a known DICOM tag.

to_json(self, bulk_data_threshold=1, bulk_data_element_handler=None, dump_handler=None)[source][source]

Converts the data set into JSON representation based on the DICOM JSON Model http://dicom.nema.org/medical/dicom/current/output/chtml/part18/chapter_F.html.

Parameters
bulk_data_threshold: int, optional

threshold for the length of a base64-encoded binary data element above which the element should be considered bulk data and the value provided as a URI rather than included inline (default: 1)

bulk_data_element_handler: Union[Callable, None], optional

callable that accepts a bulk data element and returns a JSON representation of the data element (dictionary including the “vr” key and either the “InlineBinary” or the “BulkDataURI” key)

dump_handler: Union[Callable, None], optional

callable that accepts a dict and returns the serialized (dumped) JSON string (by default uses json.dumps())

Returns
str

data set serialized into a string based on the DICOM JSON Model

Examples

>>> def my_json_dumps(data):
...     return json.dumps(data, indent=4)
>>> dataset.to_json(dump_handler=my_json_dumps)
top(self)[source][source]

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

trait_names(self)[source][source]

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(self, dictionary)[source][source]

Extend dict.update() to handle DICOM keywords.

Parameters
dictionarydict or Dataset

The dict or Dataset to use when updating the current object.

values(self)[source][source]

Return the DICOM tag values to simulate dict.

walk(self, callback, recursive=True)[source][source]

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

recursivebool

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)[source][source]

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

Attributes
preamblestr or bytes or None

The optional DICOM preamble prepended to the dataset, if available.

file_metapydicom.dataset.Dataset or None

The Dataset’s file meta information as a Dataset, if available (None if not present). Consists of group 0002 elements.

filenamestr 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_VRbool

True if the dataset encoding is implicit VR, False otherwise.

is_little_endianbool

True if the dataset encoding is little endian byte ordering, False otherwise.

timestampfloat or None

The modification time of the file the dataset was read from, None if the modification time is not available.

Methods

add(self, data_element)

Add a DataElement to the Dataset.

add_new(self, tag, VR, value)

Add a DataElement to the Dataset.

clear(self)

Delete all data elements.

convert_pixel_data(self)

Convert the Pixel Data to a numpy array internally.

copy()

data_element(self, name)

Return the DataElement corresponding to the element keyword name.

decode(self)

Apply character set decoding to all DataElements in the Dataset.

decompress(self)

Decompresses pixel data and modifies the Dataset in-place

dir(self, \*filters)

Return an alphabetical list of DataElement keywords in the Dataset.

elements(self)

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

ensure_file_meta(self)

Create an empty file meta dataset if none exists.

fix_meta_info(self[, enforce_standard])

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

formatted_lines(self[, element_format, …])

Iterate through the Dataset yielding formatted str for each element.

from_json(json_dataset[, …])

Loads DICOM Data Set in DICOM JSON format.

fromkeys(iterable[, value])

Create a new dictionary with keys from iterable and values set to value.

get(self, key[, default])

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

get_item(self, key)

Return the raw data element if possible.

get_private_item(self, group, …)

Return the data element for the given private tag.

group_dataset(self, group)

Return a Dataset containing only DataElements of a certain group.

items(self)

Return the elements in the Dataset as a list of tuple.

iterall(self)

Iterate through the Dataset, yielding all DataElements.

keys(self)

Return the DICOM tag keys to simulate dict.

pop(self, key, \*args)

Emulate dictionary pop, but additionally support tag ID tuple and DICOM keyword.

popitem(self)

2-tuple; but raise KeyError if D is empty.

private_block(self, group, private_creator)

Return the block for the given tag and private creator.

private_creators(self, group)

Return a list of private creator names in the given group.

remove_private_tags(self)

Remove all private DataElements in the Dataset.

save_as(self, filename[, write_like_original])

Write the Dataset to filename.

set_original_encoding(self, is_implicit_vr, …)

Set the values for the original transfer syntax and encoding.

setdefault(self, key[, default])

Emulate dictionary setdefault, but additionally support tag ID tuple and DICOM keyword for key, and data element value for default.

to_json(self[, bulk_data_threshold, …])

Converts the data set into JSON representation based on the DICOM JSON Model http://dicom.nema.org/medical/dicom/current/output/chtml/part18/chapter_F.html.

top(self)

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

trait_names(self)

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

update(self, dictionary)

Extend dict.update() to handle DICOM keywords.

values(self)

Return the DICOM tag values to simulate dict.

walk(self, callback[, recursive])

Iterate through the DataElements and run callback on each.

class pydicom.dataset.PrivateBlock(key, dataset, private_creator_element)[source][source]

Helper class for a private block in the dataset. (See PS3.5, Section 7.8.1 - Private Data Element Tags)

Attributes
group32 bit int

The private group where the private block is located.

private_creatorstr

The private creator string related to the block.

datasetDataset

The parent dataset.

block_start32 bit int

The start element of the private block. Note that the 2 low order hex digits of the element are always 0.

Methods

add_new(self, element_offset, VR, value)

Adds the private tag with the given VR and value to the

get_tag(self, element_offset)

Return the private tag ID for the given element offset.

add_new(self, element_offset, VR, value)[source][source]
Adds the private tag with the given VR and value to the

parent dataset at the tag ID defined by the private block and the given element offset.

Parameters
element_offset16 bit int

The lower 16 bit (e.g. 2 hex numbers) of the element tag to be added.

VRstr

The 2 character DICOM value representation.

value

The value of the data element. See pydicom.Dataset.add_new for a description.

get_tag(self, element_offset)[source][source]

Return the private tag ID for the given element offset.

Parameters
element_offset16 bit int

The lower 16 bit (e.g. 2 hex numbers) of the element tag.

Returns
The tag ID defined by the private block location and the

given element offset.

Raises
ValueError

If element_offset is too large.

exception pydicom.dataset.PropertyError[source][source]

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

pydicom.dataset.validate_file_meta(file_meta, enforce_standard=True)[source][source]

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

Parameters
file_metapydicom.dataset.Dataset

The File Meta Information data elements.

enforce_standardbool

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.

Various helper modules

Configuration of pydicom behavior - the config module

Pydicom configuration options.

pydicom.config.DS_decimal(use_Decimal_boolean=True)[source][source]

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)[source][source]

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.pixel_data_handlers = [<module 'pydicom.pixel_data_handlers.numpy_handler' from '/home/circleci/project/pydicom/pixel_data_handlers/numpy_handler.py'>, <module 'pydicom.pixel_data_handlers.rle_handler' from '/home/circleci/project/pydicom/pixel_data_handlers/rle_handler.py'>, <module 'pydicom.pixel_data_handlers.gdcm_handler' from '/home/circleci/project/pydicom/pixel_data_handlers/gdcm_handler.py'>, <module 'pydicom.pixel_data_handlers.pillow_handler' from '/home/circleci/project/pydicom/pixel_data_handlers/pillow_handler.py'>, <module 'pydicom.pixel_data_handlers.jpeg_ls_handler' from '/home/circleci/project/pydicom/pixel_data_handlers/jpeg_ls_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)[source][source]

Read encapsulated data and return a list of strings.

Parameters
datastr

String of encapsulated data, typically dataset.PixelData

Returns
list of bytes

All fragments in a list of byte strings

pydicom.encaps.defragment_data(data)[source][source]

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

Parameters
datalist of bytes

The encapsulated pixel data fragments.

Returns
bytes

All fragments concatenated together.

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

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
frameslist of bytes

The frame data to encapsulate.

fragments_per_frameint, optional

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

has_botbool, 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)[source][source]

Yield one or more fragments from frame.

Parameters
framebytes

The data to fragment.

nr_fragmentsint, 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)[source][source]

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
bytestreambytes

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)[source][source]

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
fppydicom.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)[source][source]

Yield an encapsulated pixel data frame as bytes.

Parameters
bytestreambytes

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)[source][source]

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
fppydicom.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)[source][source]

Return an itemised fragment.

Parameters
fragmentbytes

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)[source][source]

Yield items generated from frame.

Parameters
framebytes

The data to fragment and itemise.

nr_fragmentsint, 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)[source]

Return an itemised fragment.

Parameters
fragmentbytes

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)[source]

Yield items generated from frame.

Parameters
framebytes

The data to fragment and itemise.

nr_fragmentsint, 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)[source][source]

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

Parameters
fppydicom.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)[source][source]

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_pathstr

The path to the file.

See also

filereader.read_preamble
filereader.read_partial
pydicom.misc.size_in_bytes(expr)[source][source]

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)[source][source]

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