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 aDataset
:>>> 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 newDataElement
, 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"
(default16
).- Type
int
-
showVR
¶ For string display, include the element’s VR just before it’s value (default
True
).- Type
bool
-
value
¶ The element’s stored value(s).
-
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
ortuple
with all strings or all numbersa multi-value string with backslash separator
file_value_tell (int or None) – Used internally by
Dataset
to store the write position for theReplaceDataElementValue()
method. Default isNone
.is_undefined_length (bool) – Used internally to store whether the length field for this element was
0xFFFFFFFFL
, i.e. ‘undefined length’. Default isFalse
.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.
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
Return the value multiplicity of the element as
int
.Return the value for an empty element.
Return
True
if the element has no value.is_raw
Return the element’s retired status as
bool
.Return the element’s keyword (if known) as
str
.Return the DICOM dictionary name for the element as
str
.Return a
str
representation of the element’s value.Return the element’s value.
-
property
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
.
-
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, 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
-
property
is_empty
¶ Return
True
if the element has no value.New in version 1.4.
-
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 beFalse
.
-
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=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 usesjson.dumps()
).
- Returns
Mapping representing a JSON encoded data element
- Return type
dict
See also
Dataset.to_json()
-
to_json_dict
(bulk_data_element_handler, bulk_data_threshold)¶ Return a dictionary representation of the
DataElement
conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, Annex F.New in version 1.4.
- 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.
- Returns
Mapping representing a JSON encoded data element
- Return type
dict
-
property
value
Return the element’s value.
-