pydicom.dataelem.DataElement

class pydicom.dataelem.DataElement(tag: int | str | tuple[int, int], VR: str, value: Any, file_value_tell: int | None = None, is_undefined_length: bool = False, already_converted: bool = False, validation_mode: int | None = None)[source]

Contain and manipulate a DICOM Element.

Examples

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

>>> from pydicom import 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'

Empty DataElement objects (e.g. with VM = 0) show an empty string as value for text VRs and None for non-text (binary) VRs:

>>> ds = Dataset()
>>> ds.PatientName = None
>>> ds.PatientName
''
>>> ds.BitsAllocated = None
>>> ds.BitsAllocated
>>> str(ds.BitsAllocated)
'None'
descripWidth

For string display, this is the maximum width of the description field (default 35).

Type:

int

is_undefined_length

Indicates whether the length field for the element was 0xFFFFFFFFL (ie undefined).

Type:

bool

maxBytesToDisplay

For string display, elements with values containing data which is longer than this value will display "array of # bytes" (default 16).

Type:

int

showVR

For string display, include the element’s VR just before it’s value (default True).

Type:

bool

tag

The element’s tag.

Type:

pydicom.tag.BaseTag

VR

The element’s Value Representation.

Type:

str

__init__(tag: int | str | tuple[int, int], VR: str, value: Any, file_value_tell: int | None = None, is_undefined_length: bool = False, already_converted: bool = False, validation_mode: int | None = None) None[source]

Create a new DataElement.

Parameters:
  • tag (int or str or 2-tuple of int) – The DICOM (group, element) tag in any form accepted by Tag() such as 'PatientName', (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 value

    • a number

    • a list or tuple with all strings or all numbers

    • a multi-value string with backslash separator

  • file_value_tell (int, optional) – The byte offset to the start of the encoded element value.

  • is_undefined_length (bool) – Used internally to store whether the length field for this element was 0xFFFFFFFF, i.e. ‘undefined length’. Default is False.

  • already_converted (bool) – Used to determine whether or not the element’s value requires conversion to a value with VM > 1. Default is False.

  • validation_mode (int) – Defines if values are validated and how validation errors are handled.

Methods

__init__(tag, VR, value[, file_value_tell, ...])

Create a new DataElement.

clear()

Clears the value, e.g. sets it to the configured empty value.

from_json(dataset_class, tag, vr, value, ...)

Return a DataElement from a DICOM JSON Model attribute object.

to_json([bulk_data_threshold, ...])

Return a JSON representation of the DataElement.

to_json_dict(bulk_data_element_handler, ...)

Return a dictionary representation of the DataElement conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, Annex F.

validate(value)

Validate the current value against the DICOM standard.

Attributes

VM

Return the value multiplicity of the element as int.

descripWidth

empty_value

Return the value for an empty element.

is_empty

Return True if the element has no value.

is_private

Return True if the element's tag is private.

is_raw

is_retired

Return the element's retired status as bool.

keyword

Return the element's keyword (if known) as str.

maxBytesToDisplay

name

Return the DICOM dictionary name for the element as str.

repval

Return a str representation of the element's value.

showVR

value

Return the element's value.

property VM: int

Return the value multiplicity of the element as int.

Changed in version 3.0: SQ elements now always return a VM of 1.

clear() None[source]

Clears the value, e.g. sets it to the configured empty value.

See empty_value_for_VR().

property empty_value: bytes | list[str] | None | str | PersonName

Return the value for an empty element.

See empty_value_for_VR() for more information.

Returns:

The value this data element is assigned on decoding if it is empty.

Return type:

str or None

classmethod from_json(dataset_class: type[Dataset], tag: str, vr: str, value: Any, value_key: str | None, bulk_data_uri_handler: Callable[[str, str, str], None | str | int | float | bytes] | Callable[[str], None | str | int | float | bytes] | None = None) DataElement[source]

Return a DataElement from a DICOM JSON Model attribute object.

Parameters:
  • dataset_class (dataset.Dataset derived class) – The class object to use for SQ element items.

  • tag (str) – The data element’s tag as uppercase hex.

  • vr (str) – The data element’s value representation (VR).

  • value (str or List[None | str | int | float | bytes | dict]) – The data element’s value(s).

  • value_key (str or None) – The attribute name for value, should be one of: {"Value", "InlineBinary", "BulkDataURI"}. If the element’s VM is 0 and none of the keys are used then will be None.

  • bulk_data_uri_handler (callable or None) – Callable function that accepts either the tag, vr and “BulkDataURI” value or just the “BulkDataURI” value of the JSON representation of a data element and returns the actual value of that data element (retrieved via DICOMweb WADO-RS). If no bulk_data_uri_handler is specified (default) then the corresponding element will have an “empty” value such as "", b"" or None depending on the vr (i.e. the Value Multiplicity will be 0).

Return type:

DataElement

property is_empty: bool

Return True if the element has no value.

property is_private: bool

Return True if the element’s tag is private.

New in version 2.1.

property is_retired: bool

Return the element’s retired status as bool.

For officially registered DICOM Data Elements this will be True if the retired status as given in the DICOM Standard, Part 6, Table 6-1 is ‘RET’. For private or unknown elements this will always be False.

property keyword: str

Return the element’s keyword (if known) as str.

For officially registered DICOM Data Elements this will be the Keyword as given in Table 6-1. For private or unknown elements this will return an empty string ''.

property name: str

Return the DICOM dictionary name for the element as str.

Returns:

  • For officially registered DICOM Data Elements this will be the Name as given in Table 6-1.

  • For private elements known to pydicom this will be the Name in the format '[name]'.

  • For unknown private elements this will be 'Private tag data'.

  • Otherwise returns an empty string ''.

Return type:

str

property repval: str

Return a str representation of the element’s value.

to_json(bulk_data_threshold: int = 1024, bulk_data_element_handler: Callable[[DataElement], str] | None = None, dump_handler: Callable[[dict[str, Any]], str] | None = None) str[source]

Return a JSON representation of the DataElement.

Parameters:
  • bulk_data_threshold (int, optional) – Size of base64 encoded data element above which a value will be provided in form of a “BulkDataURI” rather than “InlineBinary”. Ignored if no bulk_data_element_handler is given.

  • bulk_data_element_handler (callable, optional) – Callable that accepts a bulk :class`data element <pydicom.dataelem.DataElement>` and returns the “BulkDataURI” as a str for retrieving the value of the data element via DICOMweb WADO-RS.

  • dump_handler (callable, optional) – Callable function that accepts a dict of {str: Any} and returns the serialized (dumped) JSON str (by default uses json.dumps()).

Returns:

Mapping representing a JSON encoded data element

Return type:

str

See also

Dataset.to_json

to_json_dict(bulk_data_element_handler: Callable[[DataElement], str] | None, bulk_data_threshold: int) dict[str, Any][source]

Return a dictionary representation of the DataElement conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, Annex F.

Parameters:
  • bulk_data_element_handler (callable or None) – Callable that accepts a bulk :class`data element <pydicom.dataelem.DataElement>` and returns the “BulkDataURI” as a str for retrieving the value of the data element via DICOMweb WADO-RS.

  • bulk_data_threshold (int) – Size of base64 encoded data element above which a value will be provided in form of a “BulkDataURI” rather than “InlineBinary”. Ignored if no bulk_data_element_handler is given.

Returns:

Mapping representing a JSON encoded data element as {str: Any}.

Return type:

dict

validate(value: Any) None[source]

Validate the current value against the DICOM standard. See validate_value() for details.

property value: Any

Return the element’s value.