o iև @sdZddlZddlmZmZddlZddlmZddlZddl m Z m Z m Z ddl mZddlmZddlmZmZmZmZmZmZmZdd lmZdd lmZmZdd lmZdd l m!Z!dd l"m#Z#m$Z$m%Z%ddl&m'Z'ddl m(Z(ddl)m*Z*m+Z+m,Z,ddl-Z ddl-m.Z.m/Z/m0Z0m1Z1m2Z2m3Z3m4Z4m5Z5m6Z7m8Z8ej9rddl:Z:e rddl;mde?e@e=Be=BdBe/BfddZAGdddZBGddde ZCddddeCde=ee=BdBdd deBfd!d"ZD  d,d#eCde=ee=BdBd$d deBfd%d&ZEd'eEiZFd(e=de fd)d*ZGdS)-zDefine the DataElement class. A DataElement has a tag, a value representation (VR), a value multiplicity (VM) and a value. N)CallableMutableSequence)BufferedIOBase)Any TYPE_CHECKING NamedTuple)config)logger)dictionary_has_tagdictionary_descriptiondictionary_keyworddictionary_is_retiredprivate_dictionary_description dictionary_VRrepeater_has_tag)hooks)JsonDataElementConverter BulkDataType) warn_and_log) MultiValue)TagBaseTag_LUT_DESCRIPTOR_TAGS)UID)jsonrep) check_buffer buffer_lengthbuffer_equality) BUFFERABLE_VRS PersonNameBYTES_VR AMBIGUOUS_VRSTR_VRALLOW_BACKSLASHDEFAULT_CHARSET_VR LONG_VALUE_VRVRvalidate_value)DatasetFr&rawreturncCs^|tjkr |r dSgStjrdS|tjkr|rdStdS|ttjtjhvr-|r+dSdSdS)aReturn the value for an empty element for `VR`. The behavior of this property depends on the setting of :attr:`config.use_none_as_empty_value`. If that is set to ``True``, an empty value is represented by ``None`` (except for VR 'SQ'), otherwise it depends on `VR`. For text VRs (this includes 'AE', 'AS', 'CS', 'DA', 'DT', 'LO', 'LT', 'PN', 'SH', 'ST', 'TM', 'UC', 'UI', 'UR' and 'UT') an empty string is used as empty value representation, for all other VRs except 'SQ', ``None``. For empty sequence values (VR 'SQ') an empty list is used in all cases. Note that this is used only if decoding the element - it is always possible to set the value to another empty value representation, which will be preserved during the element object lifetime. Parameters ---------- VR : str or None The VR of the corresponding element. raw : bool, optional If ``True``, returns the value for a :class:`RawDataElement`, otherwise for a :class:`DataElement` Returns ------- str or bytes or None or list The value a data element with `VR` is assigned on decoding if it is empty. N) VR_SQruse_none_as_empty_text_VR_valuePNrr"DSIS)r&r)r3F/mnt/sdb/aimis/docanh/lib/python3.10/site-packages/pydicom/dataelem.pyempty_value_for_VR9s    r5c@seZdZdZdZdZdZdZ    dNdee Be eefBde d e d edBd e d e d edBddfddZ d e ddfddZe dOdeddedde de d e de dBdee e e gefee gefBdBddfddZdedge fdBdedee e ffddZ   dPdededge fdBd eee e fge fdBde fd!d"Zede fd#d$Zejd%e ddfd&d$Zedefd'd(Zede fd)d*Zede fd+d,Zedeee BdBe BeBfd-d.Z dQd/d0Z!d%e de fd1d2Z"d%e de fd3d4Z#d5eee fddfd6d7Z$d8e de fd9d:Z%d8e de fd;d<Z&de fd=d>Z'ede fd?d@Z(dAede fdBdCZ)ede fdDdEZ*ede fdFdGZ+ede fdHdIZ,ede fdJdKZ-de fdLdMZ.dS)R DataElementa8Contain and manipulate a DICOM Element. Examples -------- While its possible to create a new :class:`DataElement` directly and add it to a :class:`~pydicom.dataset.Dataset`: >>> from pydicom import Dataset >>> elem = DataElement(0x00100010, 'PN', 'CITIZEN^Joan') >>> ds = Dataset() >>> ds.add(elem) Its far more convenient to use a :class:`~pydicom.dataset.Dataset` to add a new :class:`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' Attributes ---------- descripWidth : int For string display, this is the maximum width of the description field (default ``35``). is_undefined_length : bool Indicates whether the length field for the element was ``0xFFFFFFFFL`` (ie undefined). maxBytesToDisplay : int For string display, elements with values containing data which is longer than this value will display ``"array of # bytes"`` (default ``16``). showVR : bool For string display, include the element's VR just before it's value (default ``True``). tag : pydicom.tag.BaseTag The element's tag. validation_mode : int The mode used to validate the element's value. See :attr:`Settings.writing_validation_mode ` for more information. VR : str The element's Value Representation. #TFNtagr&valuefile_value_tellis_undefined_lengthalready_convertedvalidation_moder*cCs|durtjj}t|tst|}||_|tjkr;|j s;tj r;|s+|dus+t |dkr;zt |}Wn t y:Ynw||_||_|rG||_n||_||_||_d|_dS)aCreate a new :class:`DataElement`. Parameters ---------- tag : int | str | tuple[int, int] The DICOM (group, element) tag in any form accepted by :func:`~pydicom.tag.Tag` such as ``'PatientName'``, ``(0x10, 0x10)``, ``0x00100010``, etc. VR : str The 2 character DICOM value representation (see DICOM Standard, Part 5, :dcm:`Section 6.2`). value : Any The value of the data element, the :doc:`allowed type depends on the VR ` and includes: * a single :class:`str` value * an :class:`int` or :class:`int` * a :class:`list` or :class:`tuple` containing only a single type of item such as :class:`str`, :class:`int` or :class:`float` * a raw :class:`bytes` value file_value_tell : int, optional The byte offset to the start of the encoded element value. is_undefined_length : bool, optional Used internally to store whether the length field for this element was ``0xFFFFFFFF``, i.e. 'undefined length'. Default is ``False``. already_converted : bool, optional Used to determine whether or not the element's value requires conversion to a value with VM > 1. Default is ``False``. validation_mode : int, optional Defines if values are validated and how validation errors are handled. Ni)rsettingsreading_validation_mode isinstancerrr9r-UN is_privatereplace_un_with_known_vrlenrKeyErrorr&r>_valuer: file_tellr<private_creator)selfr9r&r:r;r<r=r>r3r3r4__init__s4*     zDataElement.__init__cCst|j||jdS)zValidate the current value against the DICOM standard. See :func:`~pydicom.valuerep.validate_value` for details. N)r'r&r>)rJr:r3r3r4validateszDataElement.validatecls dataset_classr(vr value_keybulk_data_uri_handlerc Cst||||||}|}|tjkr-tjr-t|tr-tt ||t ||ddd} t | j }z||||dWSt yL} z td|d|| d} ~ ww)asReturn a :class:`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). Returns ------- DataElement rT)r9r:r&zData element 'z!' could not be loaded from JSON: N)rget_element_valuesr-rBrrDrAbytesRawDataElementrrEconvert_raw_data_elementr: Exception ValueError) rMrNr9rOr:rPrQ converter elem_valuer)excr3r3r4 from_jsons..   zDataElement.from_jsonbulk_data_element_handlerbulk_data_thresholdc sd|ji}|jttBtjhvrB|jsA|j}dur+t|ddkr+||d<nt | d}t d|j d||d <n|jtjkrXfd d |jD}||d <n|jtjkr|jsg}|jd krl|j}n|jg}|D]*}d|jdi} t|jd kr|jd | d<t|jdkr|jd| d<|| qr||d <n7|jtjkr|js|j}|jd kr|g}dd |D|d <n|js|jd kr|j}n|jg}dd |D|d <d |vrt|d |j|d <|S)aReturn a dictionary representation of the :class:`DataElement` conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, :dcm:`Annex F`. Parameters ---------- bulk_data_element_handler : callable or None Callable that accepts a bulk :class`data element ` and returns the "BulkDataURI" as a :class:`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 ------- dict Mapping representing a JSON encoded data element as ``{str: Any}``. rON BulkDataURIzutf-8zencode bulk data element 'z' inline InlineBinarycs g|] }|jdddqS)cS|SNr3dr3r3r4lsz5DataElement.to_json_dict...)r\r] dump_handler)to_json).0dsr\r]r3r4 hsz,DataElement.to_json_dict..Value Alphabeticr IdeographicPhoneticcSsg|]}t|dqS)08X)formatrivr3r3r4rlscSsg|]}|qSr3r3rur3r3r4rls)r&r r!r-US_SSis_emptyr:rEbase64 b64encodedecoder infonamer.r0VM componentsappendATrconvert_to_python_number) rJr\r] json_element binary_value encoded_valuer:rYrvcompsr3rkr4 to_json_dict>sb            zDataElement.to_json_dictrgcCs:dtttfdtfdd}|dur|n|}||||S)a(Return a JSON representation of the :class:`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 ` and returns the "BulkDataURI" as a :class:`str` for retrieving the value of the data element via DICOMweb WADO-RS. dump_handler : callable, optional Callable function that accepts a :class:`dict` of ``{str: Any}`` and returns the serialized (dumped) JSON :class:`str` (by default uses :func:`json.dumps`). Returns ------- str Mapping representing a JSON encoded data element See also -------- Dataset.to_json rer*cSstj|ddS)NT) sort_keys)jsondumpsrdr3r3r4 json_dumpsz&DataElement.to_json..json_dumpN)dictstrrr)rJr]r\rgrr3r3r4rhs " zDataElement.to_jsoncCs|jS)aGet or set the element's value. Parameters ---------- val : Any The value to use to set the element's value, should be an :doc:`appropriate type for the VR`. The value will be validated in accordance with the element's :attr:`~DataElement.validation_mode`. Returns ------- Any The element's value. )rGrJr3r3r4r:szDataElement.valuevalc Cst|trJ|jtvr!tddtD}td|jdd|zt|WntyD}zt |d|j d|j d|d}~ww||_ dS|jt vrpt|tr`d |vr]|d n|}nt|trpd |vrn|d n|}|||_ dS) Ncss |] }d|vrt|VqdS)orNr)rirOr3r3r4 sz$DataElement.value..zElements with a VR of 'z:' cannot be used with buffered values, supported VRs are: z, Invalid buffer for  '': \\)rArr&rsortedrWjoinrrVtyper9r}rGr#rsplitrS_convert_value)rJr supportedrZr3r3r4r:s,    "   c Cs|jtjkrdS|jdurdSt|jttBtBr |jrdSdSt|jtrOz t |jr/dWSdWSt yN}zt |d|j d|j d|d}~wwzt|jWn ty`YdSwt|jS)zReturn the value multiplicity of the element as :class:`int`. .. versionchanged:: 3.0 **SQ** elements now always return a VM of ``1``. rnNrrrr)r&r-r.r:rArrSrrrrVrr9r}iter TypeErrorrE)rJrZr3r3r4r~s&   "  zDataElement.VMcCs t|jtS)zvReturn ``True`` if the element's value is a :class:`io.BufferedIOBase` instance, ``False`` otherwise. )rArGrrr3r3r4 is_buffered zDataElement.is_bufferedcCs"|jtjkr t|j S|jdkS)z,Return ``True`` if the element has no value.r)r&r-r.boolr:r~rr3r3r4rxs   zDataElement.is_emptycCs t|jS)zReturn the value for an empty element. See :func:`empty_value_for_VR` for more information. Returns ------- str or None The value this data element is assigned on decoding if it is empty. )r5r&rr3r3r4 empty_value s zDataElement.empty_valuecCs |j|_dS)zoClears the value, e.g. sets it to the configured empty value. See :func:`empty_value_for_VR`. N)rrGrr3r3r4clear-rzDataElement.clearcCs|jdkrtjrt|tjrtd|jtj kr)ddl m }t||r%|S||St |ds3| |St|dkr@| |dS|jtvrp|rpdtdtfd d }ttj|d|j|dd D] }t|j||jq`t||St|j |S) zConvert `val` to an appropriate type and return the result. Uses the element's VR in order to determine the conversion method and resulting type. izThe value for (7FE0,0010) 'Pixel Data' should be set using 'bytes' not 'numpy.ndarray'. See the Dataset.set_pixel_data() method for an alternative that supports ndarrays.r)Sequencerrnrr*cSrbrcr3)rr3r3r4_skip_conversionYsz4DataElement._convert_value.._skip_conversionN)r9r have_numpyrAnumpyndarrayrr&r-r.pydicom.sequencerhasattr_convertrErrr'USr>r)rJrrrr:r3r3r4r4s0          zDataElement._convert_valuecCs<|jtvrt|tr|}|jtjkrtj||j S|jtj kr.t j r.tjj ||j dS|jtj kr=tj |d|j S|jtjkrOt j rOtjj||j dS|jtjkrat j ratjj||j dS|jtjkrs|durqt||j SdS|jtjkrt||j dS|jtjkr|dks|rt|tr|St|S|||S)z:Convert `val` to an appropriate type for the element's VR.)r>FNr)r&r$rArSr{r-r2pydicomvaluerepr>DArdatetime_conversionr1DTTMUIrr0rrrrrL)rJrr3r3r4rds(     zDataElement._convertmemoc Cs|j}||}||t|<|jD]?\}}|jrH|dkrHz t||t||Wqt yG}zt |d|j d|j d|d}~wwt||t||q|S)z"Implementation of copy.deepcopy().rGz'Error deepcopying the buffered element rrN) __class____new__id__dict__itemsrsetattrcopydeepcopyrVrr9r})rJrrMresultkrvrZr3r3r4 __deepcopy__s&   zDataElement.__deepcopy__otherc Cs||urdSt||jrs|j|jks|j|jkrdStjr6t|jtjr6t |jt |jko5t |j|jS|j sB|j sB|j|jkSz|j rNt |j|jWSt |j|jWSt yr}zt|d|jd|jd|d}~wwtS)aeCompare `self` and `other` for equality. Returns ------- bool The result if `self` and `other` are the same class NotImplemented If `other` is not the same class as `self` then returning :class:`NotImplemented` delegates the result to ``superclass.__eq__(subclass)``. TFrrrN)rArr9r&rrr:rrrEallcloserrrVrr}NotImplemented)rJrrZr3r3r4__eq__s(    "zDataElement.__eq__cCs ||k S)z*Compare `self` and `other` for inequality.r3)rJrr3r3r4__ne__s zDataElement.__ne__cCs`|jpd}|jd|jd|j}|jr%|jd|d|jd|S|jd|d|S)z2Return :class:`str` representation of the element.r,N< z: )repvalr} descripWidthshowVRr9r&)rJr:r}r3r3r4__str__s zDataElement.__str__cCs|jrt|jS|jtvr)zt|j}Wn tyYn w||jkr)d|dS|j|jkr6d|jdSt |jt r@|jj St|jS)z`. * 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 ``''``. []rzPrivate CreatorzPrivate tag dataz Group Lengthr,) r9rCrIrrFelementr rr )rJr}r3r3r4r}s&   zDataElement.namecCs|jjS)zXReturn ``True`` if the element's tag is private. .. versionadded:: 2.1 )r9rCrr3r3r4rCszDataElement.is_privatecCt|jr t|jSdS)a\Return the element's retired status as :class:`bool`. For officially registered DICOM Data Elements this will be ``True`` if the retired status as given in the DICOM Standard, Part 6, :dcm:`Table 6-1` is 'RET'. For private or unknown elements this will always be ``False``. F)r r9r rr3r3r4 is_retired# zDataElement.is_retiredcCr)a3Return the element's keyword (if known) as :class:`str`. For officially registered DICOM Data Elements this will be the *Keyword* as given in :dcm:`Table 6-1`. For private or unknown elements this will return an empty string ``''``. r,)r r9r rr3r3r4keyword1rzDataElement.keywordcCst|S)z)Return the representation of the element.rrr3r3r4__repr__?szDataElement.__repr__)NFFNrc)rNN)r*N)/__name__ __module__ __qualname____doc__rrris_rawintrtuplerrrKrL classmethodrrrr[rrrhpropertyr:setterr~rrxrSlistrrrrrrrrrrrr}rCrrrr3r3r3r4r6hs; K   C  W +"$ 0") (  r6c@sjeZdZUdZeed<edBed<eed<edBed<eed<e ed<e ed <d Z e ed <d Z e ed <dS)rTz=Container for the data from a raw (mostly) undecoded element.r9Nr&rr: value_tellis_implicit_VRis_little_endianTrFr) rrrrr__annotations__rrrSrrrr3r3r3r4rTDs    rTencodingrjrrjzDataset | NonecCsi}tjrtj|fitj}tjr/tj||f||dtjtj||f||dtjntj||||dtj||||dt|j|d|d|j |j dkddS)aReturn a :class:`DataElement` created from `raw`. .. versionadded:: 3.0 **Customization Hooks** All callback functions for :func:`convert_raw_data_element` use the function signature:: def func( raw: RawDataElement, data: dict[str, Any], *, encoding: str | MutableSequence[str] | None = None, ds: pydicom.dataset.Dataset | None = None, **kwargs: dict[str, Any], ) -> None: ... Where `raw`, `encoding` and `ds` are the objects passed to this function, `data` is a :class:`dict` that's persistent for each raw element and is used to store the results of the corresponding callback functions, and `kwargs` are keyword arguments passed by setting the ``"raw_element_kwargs"`` hook via :meth:`~pydicom.hooks.Hooks.register_kwargs`. Available :class:`hooks` are (in order of execution): * ``"raw_element_vr"``: a function to perform the VR lookup for the raw element, required to add ``{"VR": str}`` to `data`. * ``"raw_element_value"``: a function to perform the conversion of the raw element :class:`bytes` value to an appropriate type (such as :class:`int` for VR **US**), required to add ``{"value": Any}`` to `data`. :meth:`~pydicom.hooks.Hooks.register_callback` is used to set the callback function for a given hook, and only one callback can be set per hook. Parameters ---------- raw : pydicom.dataelem.RawDataElement The raw data to convert to a :class:`DataElement`. encoding : str | MutableSequence[str] | None The character set encodings for the raw data element. ds : pydicom.dataset.Dataset | None The parent dataset of `raw`. Returns ------- pydicom.dataelem.DataElement A :class:`~pydicom.dataelem.DataElement` instance created from `raw`. rr&r:lT)r=) rdata_element_callbackdata_element_callback_kwargsrraw_element_kwargsraw_element_vrraw_element_valuer6r9rr)r)rrjdatar3r3r4rURs88rUraw_data_elementdatasetcCsd}t|tt|||dS)a.Return a :class:`DataElement` created from `raw_data_element`. .. deprecated:: 3.0 ``DataElement_from_raw`` will be removed in v4.0, use :func:`~pydicom.dataelem.convert_raw_data_element` instead. Call the configured data_element_callbacks to do relevant pre/post-processing and convert values from raw to native types Parameters ---------- raw_data_element : pydicom.dataelem.RawDataElement The raw data to convert to a :class:`DataElement`. encoding : str | list[str] | None The character encoding of the raw data. dataset : pydicom.dataset.Dataset | None If given, used to resolve the VR for known private tags. Returns ------- DataElement A :class:`~pydicom.dataelem.DataElement` instance created from `raw`. z'pydicom.dataelem.DataElement_from_raw' is deprecated and will be removed in v4.0, please use 'pydicom.dataelem.convert_raw_data_element' instead)r)rrj)rDeprecationWarningrU)rrrmsgr3r3r4_DataElement_from_raws rDataElement_from_rawr}cCs*|tvr tjs t|Stdtd|)Nzmodule z has no attribute ) _DEPRECATEDr _use_futureAttributeErrorr)r}r3r3r4 __getattr__sr)F)NN)Hrrycollections.abcrrriorrtypingrrrrrpydicom.configr pydicom.datadictr r r r rrr pydicom.hooksrpydicom.jsonreprr pydicom.miscrpydicom.multivalr pydicom.tagrrr pydicom.uidrrpydicom.fileutilrrrpydicom.valuereprrr r!r"r#r$r%r&r-r'rrpydicom.datasetr(rrrSrr5r6rTrUrrrr3r3r3r4s   $     0   /a T +