pydicom.dataelem.DataElement¶

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

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_retired¶

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.

Type:	bool

is_undefined_length¶

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

Type:	bool

keyword¶

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

Type:	str

maxBytesToDisplay¶

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

Type:	int

name¶

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

Type:	str

showVR¶

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

Type:	bool

tag¶

The element’s tag.

Type:	BaseTag

value¶: The element’s stored value(s).

VM¶

The Value Multiplicity of the element’s stored value(s).

Type:	int

VR¶

The element’s Value Representation.

Type:	str

__init__(tag, VR, value, file_value_tell=None, is_undefined_length=False, already_converted=False)¶

Create a new DataElement.

Parameters:

tag (int or or str or list or tuple) – The DICOM (group, element) tag in any form accepted by 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 value
- a number
- a list or tuple with all strings or all numbers
- a multi-value string with backslash separator
file_value_tell (int or None) – Used internally by Dataset to store the write position for the ReplaceDataElementValue() method. Default is None.
is_undefined_length (bool) – Used internally to store whether the length field for this element was 0xFFFFFFFFL, 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_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.

VM: Return the value multiplicity of the element as int.

clear()¶

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

New in version 1.4.

See empty_value_for_VR().

description()¶: Return the DICOM dictionary name for the element as str.

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, tag, vr, value, value_key, bulk_data_uri_handler=None)¶

Return a DataElement from JSON.

New in version 1.3.

Parameters:	dataset_class (dataset.Dataset derived class) – Class used to create sequence items. 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 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

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

New in version 1.4.

is_retired: Return the element’s retired status as bool.

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

name: Return the DICOM dictionary name for the element as str.

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

to_json(bulk_data_threshold=1024, bulk_data_element_handler=None, dump_handler=None)¶

Return a JSON representation of the DataElement.

New in version 1.3.

Parameters:	bulk_data_element_handler (callable or None) – 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) – 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