# pydicom.dataelem.DataElement

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

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

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

  clear() → None

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

    New in version 1.4.

    See `empty_value_for_VR()`.

  description() → str

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

  property empty_value: Union[bytes, List[str], None, str, pydicom.valuerep.PersonName]

    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: str, vr: str, value: Any, value_key: Optional[str], bulk_data_uri_handler: Optional[Union[Callable[[str, str, str], Union[None, str, int, float, bytes]], Callable[[str], Union[None, str, int, float, bytes]]]] = None) → DataElement

    Return a `DataElement` from a DICOM JSON Model attribute object.

    New in version 1.3.

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

    Returns

    Return type

      DataElement

  property is_empty: bool

    Return `True` if the element has no value.

    New in version 1.4.

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

    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: str

    Return a `str` representation of the element’s value.

  to_json(bulk_data_threshold: int = 1024, bulk_data_element_handler: Optional[Callable[[pydicom.dataelem.DataElement], str]] = None, dump_handler: Optional[Callable[[Dict[str, Any]], str]] = None) → str

    Return a JSON representation of the `DataElement`.

    New in version 1.3.

    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: Optional[Callable[[pydicom.dataelem.DataElement], str]], bulk_data_threshold: int) → Dict[str, Any]

    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 :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

  property value: Any

    Return the element’s value.