pydicom.dataelem.DataElement¶

class pydicom.dataelem.DataElement(tag: Union[int, str, Tuple[int, int]], VR: str, value: object, file_value_tell: Optional[int] = None, is_undefined_length: bool = False, already_converted: bool = False)[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: Union[int, str, Tuple[int, int]], VR: str, value: object, file_value_tell: Optional[int] = None, is_undefined_length: bool = False, already_converted: bool = False) → 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.

Methods

`__init__`(tag, VR, value[, file_value_tell, …])	Create a new `DataElement`.
`clear`()	Clears the value, e.g.
`description`()	Return the DICOM dictionary name for the element as `str`.
`from_json`(dataset_class, tag, vr, value, …)	Return a `DataElement` from JSON.
`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.

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¶: Return the value multiplicity of the element as int.

clear() → None [source]¶

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

New in version 1.4.

See empty_value_for_VR().

description() → str [source]¶: Return the DICOM dictionary name for the element as str.

property empty_value¶

Return the value for an empty element.

New in version 1.4.

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: Union[pydicom.tag.BaseTag, int], vr: str, value: object, value_key: Optional[str], bulk_data_uri_handler: Optional[Union[Callable[[pydicom.tag.BaseTag, str, str], object], Callable[[str], object]]] = None) → _DataElement[source]¶

Return a DataElement from JSON.

New in version 1.3.

Parameters

dataset_class (dataset.Dataset derived class) – Class used to create sequence items.
tag (pydicom.tag.BaseTag or int) – The data element tag.
vr (str) – The data element value representation.
value (list) – The data element’s value(s).
value_key (str or None) – Key of the data element that contains the value (options: {"Value", "InlineBinary", "BulkDataURI"})
bulk_data_uri_handler (callable or None) – Callable function that accepts either the tag, vr and “BulkDataURI” or just the “BulkDataURI” of the JSON representation of a data element and returns the actual value of that data element (retrieved via DICOMweb WADO-RS)

Returns

Return type

DataElement

property is_empty¶: Return True if the element has no value.

New in version 1.4.

property is_private¶: Return True if the element’s tag is private.

New in version 2.1.

property is_retired¶

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¶

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¶

Return the DICOM dictionary name for the element as str.

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 Creator'. For unknown elements this will return an empty string ''.

property repval¶: Return a str representation of the element’s value.

to_json(bulk_data_threshold: int = 1024, bulk_data_element_handler: Optional[Callable[[DataElement], str]] = None, dump_handler: Optional[Callable[[Dict[object, object]], str]] = None) → Dict[str, object][source]¶

Return a JSON representation of the DataElement.

New in version 1.3.

Parameters

bulk_data_element_handler (callable, optional) – Callable that accepts a bulk data element and returns the “BulkDataURI” for retrieving the value of the data element via DICOMweb WADO-RS
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 handler is given.
dump_handler (callable, optional) – Callable function that accepts a dict and returns the serialized (dumped) JSON string (by default uses json.dumps()).

Returns

Mapping representing a JSON encoded data element

Return type

dict