o i @sUdZddlZddlZddlZddlZddlZddlZddlmZddl m Z m Z m Z m Z mZmZddlmZddlmZddlmZddlmZdd lmZmZmZmZmZmZm Z zddl!Z!Wn e"yjYnwddl#Z#dd l#m$Z$m%Z%dd l&m'Z'dd l(m)Z)m*Z*dd l+m,Z,ddl-m.Z.m/Z/m0Z0m1Z1m2Z2m3Z3ddl4m5Z5m6Z6m7Z7ddl8m9Z9m:Z:ddl;mm?Z?ddl@mAZAmBZBmCZCmDZDddlEmFZFmGZGmHZHddlImJZJmKZKmLZLmMZMmNZNddlOmPZPmQZQddlRmSZTmUZUddlVmWZXhdZYGdddZZd2dddede[e\dBd e]fd!d"Z^e5e7BZ_d#Z`eead$<Gd%ddZbed&d'd(ZcGd)d'd'ebZd *d3d+d,d-e]d dfd.d/ZeGd0d,d,ebZfegd1ZhdS)4aDefine the Dataset and FileDataset classes. The Dataset class represents the DICOM Dataset while the FileDataset class adds extra functionality to Dataset when data is read from or written to file. Overview of DICOM object model ------------------------------ Dataset (dict subclass) Contains DataElement instances, each of which has a tag, VR, VM and value. The DataElement value can be: * A single value, such as a number, string, etc. (i.e. VM = 1) * A list of numbers, strings, etc. (i.e. VM > 1) * A Sequence (list subclass), where each item is a Dataset which contains its own DataElements, and so on in a recursive manner. N) bisect_left) ValuesViewIteratorCallableMutableSequenceMutableMappingSet) nullcontext) find_spec) takewhile) TracebackType) TypeAliasAnyAnyStrcastBinaryIOTypeVaroverload)jsonrepconfig)__version_info__)default_encodingconvert_encodings)logger)dictionary_description dictionary_VRtag_for_keywordkeyword_for_tagrepeater_has_keywordget_private_entry) DataElementconvert_raw_data_elementRawDataElement)ReadableBufferWriteableBuffer)path_from_pathlikePathType) warn_and_log)compressconvert_color_space decompress pixel_array)reshape_pixel_arrayget_image_pixel_idsset_pixel_data)TagBaseTagtag_in_exceptionTagType TAG_PIXREP)PYDICOM_IMPLEMENTATION_UIDUID)VR AMBIGUOUS_VR) numpy_handler> c@seZdZdZdeeefdddeddfdd Zd edefd d Z d ede fd dZ d ede fddZ d eddfddZd edededdfddZdeddfddZdS) PrivateBlockayHelper class for a private block in the :class:`Dataset`. See the DICOM Standard, Part 5, :dcm:`Section 7.8.1` - Private Data Element Tags Attributes ---------- group : int The private group where the private block is located as a 32-bit :class:`int`. private_creator : str The private creator string related to the block. dataset : Dataset The parent dataset. block_start : int The start element of the private block as a 32-bit :class:`int`. Note that the 2 low order hex digits of the element are always 0. keydatasetDatasetprivate_creator_elementreturnNcCs(|d|_|d|_||_|d>|_dS)aInitializes an object corresponding to a private tag block. Parameters ---------- key : tuple The private (tag group, creator) as ``(int, str)``. The group must be an odd number. dataset : Dataset The parent :class:`Dataset`. private_creator_element : int The element of the private creator tag as a 32-bit :class:`int`. rN)groupprivate_creatorr> block_start)selfr=r>r@rHE/mnt/sdb/aimis/docanh/lib/python3.10/site-packages/pydicom/dataset.py__init__is  zPrivateBlock.__init__element_offsetcCs"|dkrtdt|j|j|S)aReturn the private tag ID for the given `element_offset`. Parameters ---------- element_offset : int The lower 16 bits (e.g. 2 hex numbers) of the element tag. Returns ------- The tag ID defined by the private block location and the given element offset. Raises ------ ValueError If `element_offset` is too large. z$Element offset must be less than 256) ValueErrorr/rDrFrGrKrHrHrIget_tag}szPrivateBlock.get_tagcCs|||jvS)zjReturn ``True`` if the tag with given `element_offset` is in the parent :class:`Dataset`. )rOr>rNrHrHrI __contains__szPrivateBlock.__contains__cCs|j||S)a=Return the data element in the parent dataset for the given element offset. Parameters ---------- element_offset : int The lower 16 bits (e.g. 2 hex numbers) of the element tag. Returns ------- The data element of the tag in the parent dataset defined by the private block location and the given element offset. Raises ------ ValueError If `element_offset` is too large. KeyError If no data element exists at that offset. )r> __getitem__rOrNrHrHrIrQszPrivateBlock.__getitem__cCs|j||=dS)aDelete the tag with the given `element_offset` from the dataset. Parameters ---------- element_offset : int The lower 16 bits (e.g. 2 hex numbers) of the element tag to be deleted. Raises ------ ValueError If `element_offset` is too large. KeyError If no data element exists at that offset. N)r>rOrNrHrHrI __delitem__szPrivateBlock.__delitem__r6valuecCs,||}|j||||j|j|_dS)aXAdd a private element to the parent :class:`Dataset`. Adds the private tag with the given `VR` and `value` to the parent :class:`Dataset` at the tag ID defined by the private block and the given `element_offset`. Parameters ---------- element_offset : int The lower 16 bits (e.g. 2 hex numbers) of the element tag to be added. VR : str The 2 character DICOM value representation. value The value of the data element. See :meth:`Dataset.add_new()` for a description. N)rOr>add_newrE)rGrKr6rStagrHrHrIrTs zPrivateBlock.add_newmemocCs.||j|jf|j|jd?}||t|<|S)NrC) __class__rDrEr>rFid)rGrVcopiedrHrHrI __deepcopy__s  zPrivateBlock.__deepcopy__)__name__ __module__ __qualname____doc__tupleintstrrJr0rOboolrPr rQrRobjectrTrrZrHrHrHrIr<Ts"  r<ar?bexcluderAcsHttko#tfddDo#tfddDS)aCommon method for Dataset.__eq__ and FileDataset.__eq__ Uses .keys() as needed because Dataset iter return items not keys `exclude` is used in FileDataset__eq__ ds.__dict__ compare, which would also compare the wrapped _dict member (entire dataset) again. c3s|]}|vVqdSNrH.0r=)rerHrI sz_dict_equal..c3s0|]}dus |vr||kVqdSrgrHrhrdrerfrHrIrjs)lenallkeysrkrHrkrI _dict_equalsroz0Dataset | MutableMapping[BaseTag, _DatasetValue] _DatasetTypecs eZdZdZdZdededdfddZdd d Zd e e dBd e dBd e dBde dBfddZ deddfddZdedededdfddZ ddedededededBddf ddZddd Zd!ededBfd"d#Zd!ede fd$d%Zdd&d'Zdd(d)Zd!eddfd*d+Zdd.d/Zdeeffd0d1 Zd2edeefd3d4Zd5ede fd6d7Ze dd,ed8edBdefd9d:Z!e dd,ee"eefBe#Bd8edBdefd;d:Z! dd,eeBe"eefBe#Bd8edBdeeBfdZ&de$e#fd?d@Z'de(e%fdAdBZ)d!edefdCdDZ*e+deeeBfdEdFZ,e+dee-eBfdGdHZ.e+dee-eBfdIdJZ/e/j0dee-eBddfdKdJZ/e d,e1ddfdLdMZ2e d,edefdNdMZ2ddQdMZ2 RddededSe de3fdTdUZ4dedeefdVdWZ5dedededefdXdYZ6e dZd[d,e1d\e ddfd]d^Z7e dZd[d,ed\e defd_d^Z7dRd[d,dOd\e dd`fdad^Z7dbe1ddfdcddZ8e+de dBfdedfZ9e9j0de dBddfdgdfZ9e+de dBfdhdiZ:e:j0de dBddfdjdiZ:e+de fdkdlZ;e+de"e e fe"dmBfdndoZ< ddpe dBdqe dBdree-eBdBddfdsdtZ=deddfdudvZ>de?efdwdxZ@de?eeABfdydzZBdefd{d|ZCd5ede fd}d~ZDdddZEd,ddede%fddZFde"e#e%ffddZGdd,ed8edBdefddZHd deddfddZId!eddfddZJdddZKdeddfddZL  Rd ddddddedddede de dedBdeeMdBdeeMdBdeddfddZN d dddddede de dededdf ddZOdeddfddZPe+dddZQddRddRddedBde dede deddf ddZRdeddfddZSdZTdZUeTeUdfdedededBde?efddZVd dede defddZWe+de dBfddZXe+de dBfddZYdddZZ ddddRddœde dBdee[j\e]Be^Be_Bde dBde dBde de deddfddʄZ`ddd̄Zad!ededdfdd΄Zbd ddфZcd,dOde%ddfddԄZddd՜dddedede ddf ddلZededdfddۄZfdddddedBdee#fddZgdefddZhdefddZideefddZjdeddfddZkde?efddZl d demdegdfde ddfddZneo dde ddepeefeBeqBerBdemeeegdeBeBeMBeqBfemegdeBeBeMBeqBfBdBddfddZs  RddedemegefdBde depeeffddZt   RddedemegefdBdemepeefgefdBde def ddZuddddededBdeqdBddfddZvehZwZxS(r?a:A DICOM dataset as a mutable mapping of DICOM Data Elements. Examples -------- Add an element to the :class:`Dataset` (for elements in the DICOM dictionary): >>> ds = Dataset() >>> ds.PatientName = "CITIZEN^Joan" >>> ds.add_new(0x00100020, 'LO', '12345') >>> ds[0x0010, 0x0030] = DataElement(0x00100030, 'DA', '20010101') Add a sequence element to the :class:`Dataset` >>> ds.BeamSequence = [Dataset(), Dataset(), Dataset()] >>> ds.BeamSequence[0].Manufacturer = "Linac, co." >>> ds.BeamSequence[1].Manufacturer = "Linac and Sons, co." >>> ds.BeamSequence[2].Manufacturer = "Linac and Daughters, co." Add private elements to the :class:`Dataset` >>> block = ds.private_block(0x0041, 'My Creator', create=True) >>> block.add_new(0x01, 'LO', '12345') Updating and retrieving element values: >>> ds.PatientName = "CITIZEN^Joan" >>> ds.PatientName 'CITIZEN^Joan' >>> ds.PatientName = "CITIZEN^John" >>> ds.PatientName 'CITIZEN^John' Retrieving an element's value from a Sequence: >>> ds.BeamSequence[0].Manufacturer 'Linac, co.' >>> ds.BeamSequence[1].Manufacturer 'Linac and Sons, co.' Accessing the :class:`~pydicom.dataelem.DataElement` items: >>> elem = ds['PatientName'] >>> elem (0010,0010) Patient's Name PN: 'CITIZEN^John' >>> elem = ds[0x00100010] >>> elem (0010,0010) Patient's Name PN: 'CITIZEN^John' >>> elem = ds.data_element('PatientName') >>> elem (0010,0010) Patient's Name PN: 'CITIZEN^John' Accessing a private :class:`~pydicom.dataelem.DataElement` item: >>> block = ds.private_block(0x0041, 'My Creator') >>> elem = block[0x01] >>> elem (0041,1001) Private tag data LO: '12345' >>> elem.value '12345' Alternatively: >>> ds.get_private_item(0x0041, 0x01, 'My Creator').value '12345' Deleting an element from the :class:`Dataset` >>> del ds.PatientID >>> del ds.BeamSequence[1].Manufacturer >>> del ds.BeamSequence[2] Deleting a private element from the :class:`Dataset` >>> block = ds.private_block(0x0041, 'My Creator') >>> if 0x01 in block: ... del block[0x01] Determining if an element is present in the :class:`Dataset` >>> 'PatientName' in ds True >>> 'PatientID' in ds False >>> (0x0010, 0x0030) in ds True >>> 'Manufacturer' in ds.BeamSequence[0] True Iterating through the top level of a :class:`Dataset` only (excluding Sequences): >>> for elem in ds: ... print(elem) (0010,0010) Patient's Name PN: 'CITIZEN^John' Iterating through the entire :class:`Dataset` (including Sequences): >>> for elem in ds.iterall(): ... print(elem) (0010,0010) Patient's Name PN: 'CITIZEN^John' Recursively iterate through a :class:`Dataset` (including Sequences): >>> def recurse(ds): ... for elem in ds: ... if elem.VR == 'SQ': ... [recurse(item) for item in elem.value] ... else: ... # Do something useful with each DataElement Converting the :class:`Dataset` to and from JSON: >>> ds = Dataset() >>> ds.PatientName = "Some^Name" >>> jsonmodel = ds.to_json() >>> ds2 = Dataset() >>> ds2.from_json(jsonmodel) (0010,0010) Patient's Name PN: 'Some^Name' Attributes ---------- default_element_format : str The default formatting for string display. default_sequence_element_format : str The default formatting for string display of sequences. indent_chars : str For string display, the characters used to indent nested Sequences. Default is ``" "``. z argskwargsrANcOs|dt|_||si|_nt|dtr|dj|_n|d|_d|_d|_d|_d|_ t j s7d|_ d|_ d|_i|_d|_ddi|_i|_||dS)z'Create a new :class:`Dataset` instance.parent_encodingrFNuse_pdh)getr_parent_encoding_dict isinstancer?is_decompressed _read_little_read_implicit _read_charsetr _use_future_is_little_endian_is_implicit_VR!is_undefined_length_sequence_item_private_blocks _pixel_array_pixel_array_opts _pixel_idrGrqrrrHrHrIrJs.  zDataset.__init__cCs|S)z,Method invoked on entry to a with statement.rHrGrHrHrI __enter__zDataset.__enter__exc_typeexc_valexc_tbcCsdS)z-Method invoked on exit from a with statement.NrH)rGrrrrHrHrI__exit__szDataset.__exit__ data_elementcCs|||j<dS)aAdd an element to the :class:`Dataset`. Equivalent to ``ds[data_element.tag] = data_element`` Parameters ---------- data_element : dataelem.DataElement The :class:`~pydicom.dataelem.DataElement` to add. N)rU)rGrrHrHrIadds z Dataset.addrUr6rScCs|t|||dS)a8Create a new element and add it to the :class:`Dataset`. Parameters ---------- tag The DICOM (group, element) tag in any form accepted by :func:`~pydicom.tag.Tag` such as ``[0x0010, 0x0010]``, ``(0x10, 0x10)``, ``0x00100010``, etc. VR : str The 2 character DICOM value representation (see DICOM Standard, Part 5, :dcm:`Section 6.2`). value The value of the data element. One of the following: * a single string or number * a :class:`list` or :class:`tuple` with all strings or all numbers * a multi-value string with backslash separator * for a sequence element, an empty :class:`list` or ``list`` of :class:`Dataset` N)rr )rGrUr6rSrHrHrIrTszDataset.add_newrErDrKvrcCs<|j||dd}|durt||f|d}||||dS)a4Create a new private element and add it to the :class:`Dataset`. Parameters ---------- private_creator : str The private creator string related to the new tag. group : int The group ID (0x0009 - 0xFFFF) for the private tag. Must be an odd number. element_offset : int The tag offset, e.g. the lower byte of the tag element of the private tag (0x00 - 0xFF). The higher byte is defined by the location of the private creator tag. value : Any The value of the data element. One of the following: * a single string or number * a :class:`list` or :class:`tuple` with all strings or all numbers * a multi-value string with backslash separator * for a sequence element, an empty :class:`list` or ``list`` of :class:`Dataset` vr : str | None The two-letter DICOM value representation, or ``None``. If set to ``None``, it is taken from the private tag dictionary. Raises ------ ValueError If `group` doesn't belong to a private tag or `private_creator` is empty. KeyError If `vr` is ``None`` and the tag is not found in the private tag dictionary. T)createNr) private_blockrrT)rGrErDrKrSrblockrHrHrIadd_new_privates(zDataset.add_new_private numpy.ndarraycCs t|jS)z1Support accessing the dataset from a numpy array.)numpyasarrayrxrrHrHrI __array__ zDataset.__array__namecCst|}|dur ||SdS)aReturn the element corresponding to the element keyword `name`. Parameters ---------- name : str A DICOM element keyword. Returns ------- dataelem.DataElement or None For the given DICOM element `keyword`, return the corresponding :class:`~pydicom.dataelem.DataElement` if present, ``None`` otherwise. N)rrGrrUrHrHrIrszDataset.data_elementc Cszt||jvWStyC}z/d|d}t|trd}tjdkr't|ntjdkr1t||WYd}~dSWYd}~dSd}~ww)aSimulate dict.__contains__() to handle DICOM keywords. Examples -------- >>> ds = Dataset() >>> ds.SliceLocation = '2' >>> 'SliceLocation' in ds True Parameters ---------- name : str or int or 2-tuple The element keyword or tag to search for. Returns ------- bool ``True`` if the corresponding element is in the :class:`Dataset`, ``False`` otherwise. zInvalid value 'z`' used with the 'in' operator: must be an element tag as a 2-tuple or int, or an element keywordzdInvalid element tag value used with the 'in' operator: tags have a maximum value of (0xFFFF, 0xFFFF)WARNRAISENF) r/rx Exceptionry OverflowErrorrINVALID_KEY_BEHAVIORr'rM)rGrexcmsgrHrHrIrP)s$        zDataset.__contains__cs<|jtjjdddtddffdd }|j|dd dS) zApply character set decoding to the elements in the :class:`Dataset`. See DICOM Standard, Part 5, :dcm:`Section 6.1.1`. dsr?rrANcs8|jtjkr|jD] }|_|q dS|dS)z"Callback to decode `data_element`.N)r6VR_SQrSrwdecode)rrdsetdecode_data_elementdicom_character_setrHrIdecode_callbackcs   z'Dataset.decode..decode_callbackF) recursive)_character_setpydicomcharsetdecode_elementr walk)rGrrHrrIrSs  zDataset.decodecCs t|S)z%Return a shallow copy of the dataset.)copyrrHrHrIrn z Dataset.copycCsbttt|}|dur"||jvr"|j|=|tvr d|_i|_dSdS||jvr-|j|=dSt|)aIntercept requests to delete an attribute by `name`. Examples -------- >>> ds = Dataset() >>> ds.PatientName = 'foo' >>> ds.some_attribute = True If `name` is a DICOM keyword - delete the corresponding :class:`~pydicom.dataelem.DataElement` >>> del ds.PatientName >>> 'PatientName' in ds False If `name` is another attribute - delete it >>> del ds.some_attribute >>> hasattr(ds, 'some_attribute') False Parameters ---------- name : str The keyword for the DICOM element or the class attribute to delete. N) rr0rrxPIXEL_KEYWORDSrr__dict__AttributeErrorrrHrHrI __delattr__rs   zDataset.__delattr__r=slice | BaseTag | TagTypecCst|tr-||j|j|jD]}|j|=|jr t|j r i|_|t vr*d|_ i|_ qdSt|trM|j|=|jr?|j r?i|_|t vrKd|_ i|_ dSdSt |}|j|=|jr^|j r^i|_|t vrjd|_ i|_ dSdS)aIntercept requests to delete an attribute by key. Examples -------- Indexing using :class:`~pydicom.dataelem.DataElement` tag >>> ds = Dataset() >>> ds.CommandGroupLength = 100 >>> ds.PatientName = 'CITIZEN^Jan' >>> del ds[0x00000000] >>> ds (0010,0010) Patient's Name PN: 'CITIZEN^Jan' Slicing using :class:`~pydicom.dataelem.DataElement` tag >>> ds = Dataset() >>> ds.CommandGroupLength = 100 >>> ds.SOPInstanceUID = '1.2.3' >>> ds.PatientName = 'CITIZEN^Jan' >>> del ds[:0x00100000] >>> ds (0010,0010) Patient's Name PN: 'CITIZEN^Jan' Parameters ---------- key The key for the attribute to be deleted. If a ``slice`` is used then the tags matching the slice conditions will be deleted. N)ryslice_slice_datasetstartstopsteprxrr0is_private_creatorrrrr/)rGr=rUrHrHrIrRs4      zDataset.__delitem__cs&tt}t|}t||BS)zReturn a list of methods, properties, attributes and element keywords available in the :class:`Dataset`. List of attributes is used, for example, in auto-completion in editors or command-line environments. )setsuper__dir__dirsorted)rGnameskeywordsrWrHrIrs  zDataset.__dir__filterscsvdd|jD}dd|D}i}|D]fdd|D}|dd|Dq|r7t|St|S)aReturn an alphabetical list of element keywords in the :class:`Dataset`. Intended mainly for use in interactive Python sessions. Only lists the element keywords in the current level of the :class:`Dataset` (i.e. the contents of any sequence elements are ignored). Parameters ---------- filters : str Zero or more string arguments to the function. Used for case-insensitive match to any part of the DICOM keyword. Returns ------- list of str The matching element keywords in the dataset. If no filters are used then all element keywords are returned. cSg|]}t|qSrH)rrirUrHrHrI zDataset.dir..cSsg|]}|r|qSrHrHrixrHrHrIrrcs"g|] }|dkr|qS))lowerfindrfilter_rHrIrs"cSsi|]}|dqSrBrHrrHrHrI zDataset.dir..)rxrnrupdater)rGrallnamesmatchesmatchrHrrIrs z Dataset.dirothercCs&||urdSt||jrt||StS)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)``. T)ryrWroNotImplementedrGrrHrHrI__eq__ s    zDataset.__eq__defaultcCdSrgrHrGr=rrHrHrIrv"rz Dataset.getcCrrgrHrrHrHrIrv&sc Cst|trzt||WSty|YSwzt|}Wnty.}ztd|d}~wwz||WSty@|YSw)a5Simulate ``dict.get()`` to handle element tags and keywords. Parameters ---------- key : str or int or Tuple[int, int] or BaseTag The element keyword or tag or the class attribute name to get. default : obj or None, optional If the element or class attribute is not present, return `default` (default ``None``). Returns ------- value If `key` is the keyword for an element in the :class:`Dataset` then return the element's value. dataelem.DataElement If `key` is a tag for a element in the :class:`Dataset` then return the :class:`~pydicom.dataelem.DataElement` instance. value If `key` is a class attribute then return its value. z'Dataset.get key must be a string or tagN) ryragetattrrr/r TypeErrorrQKeyError)rGr=rrrHrHrIrv,s"       cC |jS)aReturn the :class:`Dataset` items to simulate :meth:`dict.items`. Returns ------- dict_items The top-level (:class:`~pydicom.tag.BaseTag`, :class:`~pydicom.dataelem.DataElement`) items for the :class:`Dataset`. )rxitemsrrHrHrIrWs z Dataset.itemscCr)zReturn the :class:`Dataset` keys to simulate :meth:`dict.keys`. Returns ------- dict_keys The :class:`~pydicom.tag.BaseTag` of all the elements in the :class:`Dataset`. )rxrnrrHrHrIrnc z Dataset.keyscCr)aReturn the :class:`Dataset` values to simulate :meth:`dict.values`. Returns ------- dict_keys The :class:`DataElements` that make up the values of the :class:`Dataset`. )rxvaluesrrHrHrIrnrzDataset.valuescCsDt|}|durt|}||jvr||jS|dkriSt||S)a Intercept requests for :class:`Dataset` attribute names. If `name` matches a DICOM keyword, return the value for the element with the corresponding tag. Parameters ---------- name : str An element keyword or a class attribute name. Returns ------- value If `name` matches a DICOM keyword, returns the corresponding element's value. Otherwise returns the class attribute's value (if present). Nrx)rr/rxrSrc__getattribute__rrHrHrI __getattr__ys   zDataset.__getattr__cCs$|tdd}|s |jSt|jS)z-The character set used to encode text values.N)rvr0rwrrS)rGchar_setrHrHrIrs zDataset._character_setcCs|jS)aReturn the original character set encoding for a dataset decoded from a file or buffer. Returns ------- str | MutableSequence[str] The original character set encoding of the dataset as given by the (0008,0005) *Specific Character Set*, or `iso8859 `_ if the dataset has been created from scratch. )r}rrHrHrIoriginal_character_sets zDataset.original_character_setcC>t|j}tjrtd|dtd|d|dt|jS)zReturn the original character set encoding for a decoded dataset. .. deprecated:: 3.0 ``read_encoding`` will be removed in v4.0, use :attr:`~pydicom.dataset.Dataset.original_character_set` instead. ')' object has no attribute 'read_encoding'..read_encoding' will be removed in v4.0, use ' .original_character_set' instead)typer[rr~rr'DeprecationWarningrrGrrHrHrI read_encodings zDataset.read_encodingcCBt|j}tjrtd|dtd|d|dt||_dS)Nrrrr)rr[rr~rr'rr}rGrSrrHrHrIrs  cCrrgrHrGr=rHrHrIrQrzDataset.__getitem__cCrrgrHrrHrHrIrQrslice | TagTypeDataset | DataElementc Cs`t|tr ||St|tr|}nzt|}Wnty-}z td|d|d}~ww|j|}t|tr|j durg|j dkrgddl m }|j pM|j}|j r^|jr^t|jdds^|j}||j||j|}|tdkrt|jpr|j}nt}t|||d||<||jtjkr|||||jtvrdd lm}|||||d ||<tt|j|S) a!Operator for ``Dataset[key]`` request. Any deferred data elements will be read in and an attempt will be made to correct any elements with ambiguous VRs. Examples -------- Indexing using :class:`~pydicom.dataelem.DataElement` tag >>> ds = Dataset() >>> ds.SOPInstanceUID = '1.2.3' >>> ds.PatientName = 'CITIZEN^Jan' >>> ds.PatientID = '12345' >>> ds[0x00100010].value 'CITIZEN^Jan' Slicing using element tags; all group ``0x0010`` elements in the dataset >>> ds[0x00100000:0x00110000] (0010,0010) Patient's Name PN: 'CITIZEN^Jan' (0010,0020) Patient ID LO: '12345' All group ``0x0002`` elements in the dataset >>> ds[(0x0002, 0x0000):(0x0003, 0x0000)] Parameters ---------- key The DICOM (group, element) tag in any form accepted by :func:`~pydicom.tag.Tag` such as ``[0x0010, 0x0010]``, ``(0x10, 0x10)``, ``0x00100010``, etc. May also be a :class:`slice` made up of DICOM tags. Returns ------- dataelem.DataElement or Dataset If a single DICOM element tag is used then returns the corresponding :class:`~pydicom.dataelem.DataElement`. If a :class:`slice` is used then returns a :class:`Dataset` object containing the corresponding :class:`DataElements`. rNr)read_deferred_data_elementclosedFrencodingr)correct_ambiguous_vr_element) ryr_dataset_slicer0r/rrrxr"rSlengthpydicom.filereaderrfilenamebufferr fileobj_type timestamprrrr!r6rr_set_pixel_representationr7pydicom.filewriterrrr rv) rGr=rUrelemrsrc character_setrrHrHrIrQsF 0           Frcsdtdtffdd }fjvrjSs tdddkr*tdd fd f}tfd d |Dd }|d urJ||jjS|sTtddtfdd td d D} t |d||S)aReturn the block for the given tag `group` and `private_creator`. If `create` is ``True`` and the `private_creator` does not exist, the private creator tag is added. Notes ----- We ignore the unrealistic case that no free block is available. Parameters ---------- group : int The group of the private tag to be found as a 32-bit :class:`int`. Must be an odd number (e.g. a private group). private_creator : str The private creator string associated with the tag. create : bool, optional If ``True`` and `private_creator` does not exist, a new private creator tag is added at the next free block. If ``False`` (the default) and `private_creator` does not exist, :class:`KeyError` is raised instead. Returns ------- PrivateBlock The existing or newly created private block. Raises ------ ValueError If `group` doesn't belong to a private tag or `private_creator` is empty. KeyError If the private creator tag is not found in the given group and the `create` parameter is ``False``. elementrAcst|}|j<|Srg)r<r)r r)r=rGrHrI new_blockks  z(Dataset.private_block..new_blockz!Private creator must have a valuerz/Tag must be private if private creator is givenc3s|] }|jkr|VqdSrgrS)rir )rErHrIrj|sz(Dataset.private_block..NzPrivate creator 'z ' not foundc3s$|] }t|jvr|VqdSrg)r/rx)riel)rDrGrHrIrjsLO) r`r<rrMnextrUr rrangerTr/)rGrDrErrrdata_el first_free_elrH)rDr=rErGrIrCs&(    zDataset.private_blockcCs6|ddkr td||df|df}dd|DS)aReturn a list of private creator names in the given group. Examples -------- This can be used to check if a given private creator exists in the group of the dataset: >>> ds = Dataset() >>> if 'My Creator' in ds.private_creators(0x0041): ... block = ds.private_block(0x0041, 'My Creator') Parameters ---------- group : int The private group as a 32-bit :class:`int`. Must be an odd number. Returns ------- list of str All private creator names for private blocks in the group. Raises ------ ValueError If `group` is not a private group. rrzGroup must be an odd numberrrcSsg|]}|jqSrHrrrHrHrIrrz,Dataset.private_creators..)rM)rGrDrrHrHrIprivate_creatorss zDataset.private_creatorscCs|||}|||S)a.Return the data element for the given private tag `group`. This is analogous to ``Dataset.__getitem__()``, but only for private tags. This allows to find the private tag for the correct private creator without the need to add the tag to the private dictionary first. Parameters ---------- group : int The private tag group where the item is located as a 32-bit int. element_offset : int The lower 16 bits (e.g. 2 hex numbers) of the element tag. private_creator : str The private creator for the tag. Must match the private creator for the tag to be returned. Returns ------- dataelem.DataElement The corresponding element. Raises ------ ValueError If `group` is not part of a private tag or `private_creator` is empty. KeyError If the private creator tag is not found in the given group. If the private tag is not found. )rrQrO)rGrDrKrErrHrHrIget_private_items "zDataset.get_private_item.) keep_deferredrcCrrgrHrGr=rrHrHrIget_itemrzDataset.get_itemcCrrgrHrrHrHrIrrz-Dataset | DataElement | RawDataElement | NonecCsHt|tr ||S|jt|}t|tr"|s"|jdur"||S|S)aReturn the raw data element if possible. It will be raw if the user has never accessed the value, or set their own value. Note if the data element is a deferred-read element, then it is read and converted before being returned. .. versionchanged: 3.0 Added the `keep_deferred` keyword argument. Parameters ---------- key The DICOM (group, element) tag in any form accepted by :func:`~pydicom.tag.Tag` such as ``[0x0010, 0x0010]``, ``(0x10, 0x10)``, ``0x00100010``, etc. May also be a :class:`slice` made up of DICOM tags. keep_deferred : bool, optional If ``True`` then when returning :class:`~pydicom.dataelem.RawDataElement` do not perform the deferred read of the element's value (accessing the value will return ``None`` instead). Default ``False``. Returns ------- dataelem.DataElement | dataelem.RawDataElement The corresponding element. N)ryrrrxrvr/r"rS)rGr=rr rHrHrIrs !  slcecs^|j|j|j}tfdd|D}j\}}|||jtj s-j |_ j |_ |S)aReturn a slice that has the same properties as the original dataset. That includes properties related to endianness and VR handling, and the specific character set. No element conversion is done, e.g. elements of type ``RawDataElement`` are kept. csi|]}||qSrH)rrrrHrIrz*Dataset._dataset_slice..)rrrrr?original_encodingset_original_encodingrrr~is_little_endianris_implicit_VRr)rGrtagsr is_implicit is_littlerHrrIr s zDataset._dataset_slicecC"tjrtdt|jd|jS)a:Get/set the VR method used when encoding the dataset. .. deprecated:: 3.0 ``is_implicit_VR`` will be removed in v4.0, set the *Transfer Syntax UID* or use the `implicit_vr` argument with :meth:`~pydicom.dataset.Dataset.save_as` or :func:`~pydicom.filewriter.dcmwrite` instead. Returns ------- bool | None If the dataset has been created from scratch then returns ``None``, otherwise returns the VR encoding method used by the decoded dataset. r*' object has no attribute 'is_implicit_VR')rr~rrr[rrrHrHrIr# zDataset.is_implicit_VRcCr)Nrr(zm.is_implicit_VR' will be removed in v4.0, set the Transfer Syntax UID or use the 'implicit_vr' argument with .save_as() or dcmwrite() instead)rr[rr~rr'rrrrHrHrIr#3  cCr')aGGet/set the endianness used when encoding the dataset. .. deprecated:: 3.0 ``is_little_endian`` will be removed in v4.0, set the *Transfer Syntax UID* or use the `little_endian` argument with :meth:`~pydicom.dataset.Dataset.save_as` or :func:`~pydicom.filewriter.dcmwrite` instead. Returns ------- bool | None If the dataset has been created from scratch then returns ``None``, otherwise returns the endianness of the encoding used by the decoded dataset. r,' object has no attribute 'is_little_endian')rr~rrr[rrrHrHrIr"Cr)zDataset.is_little_endiancCr)Nrr,zq.is_little_endian' will be removed in v4.0, set the Transfer Syntax UID or use the 'little_endian' argument with r*)rr[rr~rr'rrrrHrHrIr"\r+cCs<tjr |j|jkS|j|jf}d|vo|j|ko|j|jkS)aReturn ``True`` if the encoding to be used for writing is set and is the same as that used to originally encode the :class:`Dataset`. This includes properties related to endianness, VR handling and the (0008,0005) *Specific Character Set*. N)rr~rrr#r"r )rGcurrent_encodingrHrHrIis_original_encodingls   zDataset.is_original_encodingNNcCs"ttttftdB|j|jfS)aReturn the original encoding used for a dataset decoded from a file or buffer. Returns ------- tuple[bool, bool] | tuple[None, None] For a dataset decoded from a file or buffer this is whether the encoding used implicit/explicit VR and little/big endian as ``(encoded as implicit VR, encoded as little endian)``. Returns ``(None, None)`` for a dataset created from scratch. r/)rr_rbr|r{rrHrHrIr ~s  zDataset.original_encodingis_implicit_vrr"character_encodingcCs"||_||_|dur||_dSdS)aSet the values for the original dataset encoding. Can be used for a :class:`Dataset` with raw data elements to enable optimized writing (e.g. without decoding the data elements). .. versionchanged:: 3.0 `character_encoding` is now optional Parameters ---------- is_implicit_vr : bool | None The the original VR encoding of the dataset, ``True`` for implicit VR, ``False`` for explicit VR or ``None`` to reset. is_little_endian : bool | None Set the original endianness of the dataset, ``True`` for little endian, ``False`` for big or ``None`` to reset. character_encoding : str | MutableSequence[str], optional Set the original character set encoding of the dataset. If ``None`` then no changes will be made to the original character set encoding. N)r|r{r})rGr0r"r1rHrHrIr!s  zDataset.set_original_encodingcCs||df|ddfS)aJReturn a :class:`Dataset` containing only elements of a certain group. Parameters ---------- group : int The group part of a DICOM (group, element) tag. Returns ------- Dataset A :class:`Dataset` containing elements of the group specified. rrBrH)rGrDrHrHrI group_datasetszDataset.group_datasetccs(t|j}|D]}||Vq dS)aIterate through the top-level of the Dataset, yielding DataElements. Examples -------- >>> ds = Dataset() >>> for elem in ds: ... print(elem) The :class:`DataElements` are returned in increasing tag value order. Sequence items are returned as a single :class:`~pydicom.dataelem.DataElement`, so it is up to the calling code to recurse into the Sequence items if desired. Yields ------ dataelem.DataElement The :class:`Dataset`'s :class:`DataElements`, sorted by increasing tag order. N)rrxrnrGtaglistrUrHrHrI__iter__s  zDataset.__iter__ccs*t|j}|D]}||Vq dS)aYield the top-level elements of the :class:`Dataset`. Examples -------- >>> ds = Dataset() >>> for elem in ds.elements(): ... print(elem) The elements are returned in the same way as in ``Dataset.__getitem__()``. Yields ------ dataelem.DataElement or dataelem.RawDataElement The unconverted elements sorted by increasing tag order. N)rrxrnrr3rHrHrIelementss zDataset.elementscCs t|jS)z>Return the number of elements in the top level of the dataset.)rlrxrrHrHrI__len__rzDataset.__len__cCs ||k S)z*Compare `self` and `other` for inequality.rHrrHrHrI__ne__rzDataset.__ne__cCs|jdS)z2Delete all the elements from the :class:`Dataset`.N)rxclearrrHrHrIr9sz Dataset.clearzBaseTag | TagTypecGs:zt|}Wn tyYnw|jjtt|g|RS)aEmulate :meth:`dict.pop` with support for tags and keywords. Removes the element for `key` if it exists and returns it, otherwise returns a default value if given or raises :class:`KeyError`. Parameters ---------- key : int or str or 2-tuple * If :class:`tuple` - the group and element number of the DICOM tag * If :class:`int` - the combined group/element number * If :class:`str` - the DICOM keyword of the tag *args : zero or one argument Defines the behavior if no tag exists for `key`: if given, it defines the return value, if not given, :class:`KeyError` is raised Returns ------- RawDataElement or DataElement The element for `key` if it exists, or the default value if given. Raises ------ KeyError If the `key` is not a valid tag or keyword. If the tag does not exist and no default is given. )r/rrxpoprr0)rGr=rqrHrHrIr:s   z Dataset.popcCr)zoEmulate :meth:`dict.popitem`. Returns ------- tuple of (BaseTag, DataElement) )rxpopitemrrHrHrIr;%s zDataset.popitemcCst|}||vr ||St|tsG|jrtj}n)zt|}Wn"ty@tj j tj kr3td|tj}t d|dYnwt|||}|||<|S)aEmulate :meth:`dict.setdefault` with support for tags and keywords. Examples -------- >>> ds = Dataset() >>> elem = ds.setdefault((0x0010, 0x0010), "Test") >>> elem (0010,0010) Patient's Name PN: 'Test' >>> elem.value 'Test' >>> elem = ds.setdefault('PatientSex', ... DataElement(0x00100040, 'CS', 'F')) >>> elem.value 'F' Parameters ---------- key : int, str or 2-tuple of int * If :class:`tuple` - the group and element number of the DICOM tag * If :class:`int` - the combined group/element number * If :class:`str` - the DICOM keyword of the tag default : pydicom.dataelem.DataElement or object, optional The :class:`~pydicom.dataelem.DataElement` to use with `key`, or the value of the :class:`~pydicom.dataelem.DataElement` to use with `key` (default ``None``). Returns ------- pydicom.dataelem.DataElement or object The :class:`~pydicom.dataelem.DataElement` for `key`. Raises ------ ValueError If `key` is not convertible to a valid tag or a known element keyword. KeyError If :attr:`~pydicom.config.settings.reading_validation_mode` is ``RAISE`` and `key` is an unknown non-private tag. zUnknown DICOM tag z - setting VR to 'UN') r/ryr is_privaterUNrrrsettingswriting_validation_moderr')rGr=rrUrrHrHrI setdefault.s"+    zDataset.setdefaultrt handler_namecCstjrtdt|jdd}t|dsd}n|jdurd}|jt|kr(d}|r,dS|j }|r7| n| dd}|d sU||d<t |fi||_t||_dS|r^||dS|dS) aConvert pixel data to a :class:`numpy.ndarray` internally. .. deprecated:: 3.0 This method will be removed in v4.0, use :meth:`~pydicom.dataset.Dataset.pixel_array_options` instead. Parameters ---------- handler_name : str, optional The name of the pixel handler or decoding plugin to use to decode the dataset's pixel data. Support values are: * If using the :mod:`~pydicom.pixel_data_handlers` backend: ``'gdcm'``, ``'pillow'``, ``'jpeg_ls'``, ``'rle'``, ``'numpy'`` and ``'pylibjpeg'``. * If using the :mod:`~pydicom.pixels` backend see the :doc:`documentation for the decoder` corresponding to the dataset's *Transfer Syntax UID*. If not used (the default) then all available handlers or plugins will be tried and the data from first successful one will be used. Returns ------- None Converted pixel data is stored internally in the dataset, it can be accessed with the :attr:`~pydicom.dataset.Dataset.pixel_array` property. Raises ------ ValueError If `handler_name` is not a valid handler name. NotImplementedError If the given handler or any handler, if none given, is unable to decompress pixel data with the current transfer syntax RuntimeError If the given handler, or the handler that has been selected if none given, is not available. Notes ----- If the pixel data is in a compressed image format, the data is decompressed and any related data elements are changed accordingly. rz.' object has no attribute 'convert_pixel_data'TrFNdecoding_pluginrtru)rr~rrr[hasattrrrr-rrrrvr+!_convert_pixel_data_using_handler#_convert_pixel_data_without_handler)rGrA already_haveoptsrrHrHrIconvert_pixel_dataqs,1    zDataset.convert_pixel_datacCs|}|ds |d7}|dkrd}|dkrd}ttj|s'td|dttj|}|jj}| |sEt d|d |j d |d | sQt d |d ||dS)zConvert the pixel data using handler with the given name. See :meth:`~Dataset.convert_pixel_data` for more information. _handlerr8 np_handlerjpeg_ls_handlerjpegls_handlerrz' is not a known handler name;Unable to decode pixel data with a transfer syntax UID of '' (z ) using the pixel data handler 'zW'. Please see the pydicom documentation for information on supported transfer syntaxes.zThe pixel data handler 'z{' is not available on your system. Please refer to the pydicom documentation for information on installing needed packages.N)rendswithrCrrrMr file_metaTransferSyntaxUIDsupports_transfer_syntaxNotImplementedErrorr is_available RuntimeError_do_pixel_data_conversion)rGrrAhandlertsyntaxrHrHrIrDs4     z)Dataset._convert_pixel_data_using_handlerc s:|jjfddtjjD}|stddjddd|D}|sZd}g}|D]$}|jddD}fd d|D}||j d d |d q,t |d |d }|D]&} z | | Wd St y} ztjd| d| }WYd } ~ q^d } ~ wwd |_i|_tdd dd|D|)zConvert the pixel data using the first matching handler. See :meth:`~Dataset.convert_pixel_data` for more information. cs"g|] }|dur|r|qSrg)rRrihh)tsrHrIrs z?Dataset._convert_pixel_data_without_handler..rMrNz) as there are no pixel data handlers available that support it. Please see the pydicom documentation for information on supported transfer syntaxes cSsg|]}|r|qSrH)rTrYrHrHrIrrznThe following handlers are available to decode the pixel data however they are missing required dependencies: cSsg|] }t|dur|qSrg) have_package)riddrHrHrIrscsg|]}|dqSrrH)rir)hh_depsrHrIrrz (req. , )Nz&Exception raised by pixel data handler)exc_infozUnable to decode the pixel data using the following handlers: {}.Please see the list of supported Transfer Syntaxes in the pydicom documentation for alternative packages that might be able to decode the datacSrrH)rarYrHrHrIr-r)rPrQrrpixel_data_handlersrSr DEPENDENCIESappend HANDLER_NAMEjoinrUrVrrdebugrrinfoformat) rGpossible_handlersavailable_handlersrpkg_msgrZmissingrlast_exceptionrWrrH)r^r[rIrEsT    z+Dataset._convert_pixel_data_without_handlerrWcCs>||}t|||_||rt|jdd|_t||_dS)z6Do the actual data conversion using the given handler.YBR_FULLRGBN) get_pixeldatar,rneeds_to_convert_to_RGBr)r-r)rGrWarrrHrHrIrV2s   z!Dataset._do_pixel_data_conversionT)generate_instance_uid jls_errorj2k_crj2k_psnrtransfer_syntax_uidrsznumpy.ndarray | Noneencoding_pluginencapsulate_extrtrurvrwc Ks&t|||f||||||d| dS)aCompress uncompressed pixel data and update `ds` in-place with the resulting :dcm:`encapsulated` codestream. .. versionadded:: 2.2 The dataset `ds` must already have the following :dcm:`Image Pixel` module elements present with correct values that correspond to the resulting compressed pixel data: * (0028,0002) *Samples per Pixel* * (0028,0004) *Photometric Interpretation* * (0028,0008) *Number of Frames* (if more than 1 frame will be present) * (0028,0010) *Rows* * (0028,0011) *Columns* * (0028,0100) *Bits Allocated* * (0028,0101) *Bits Stored* * (0028,0103) *Pixel Representation* If *Samples per Pixel* is greater than 1 then the following element is also required: * (0028,0006) *Planar Configuration* This method will add the file meta dataset if none is present and add or modify the following elements: * (0002,0010) *Transfer Syntax UID* * (7FE0,0010) *Pixel Data* If the compressed pixel data is too large for encapsulation using a basic offset table then an :dcm:`extended offset table ` will also be used, in which case the following elements will also be added: * (7FE0,0001) *Extended Offset Table* * (7FE0,0002) *Extended Offset Table Lengths* If `generate_instance_uid` is ``True`` (default) then a new (0008,0018) *SOP Instance UID* value will be generated. **Supported Transfer Syntax UIDs** +-----------------------------------------------+-----------+----------------------------------+ | UID | Plugins | Encoding Guide | +------------------------+----------------------+ | | | Name | Value | | | +========================+======================+===========+==================================+ |*JPEG-LS Lossless* |1.2.840.10008.1.2.4.80| pyjpegls | :doc:`JPEG-LS | +------------------------+----------------------+ | ` | | *JPEG-LS Near Lossless*|1.2.840.10008.1.2.4.81| | | +------------------------+----------------------+-----------+----------------------------------+ | *JPEG 2000 Lossless* |1.2.840.10008.1.2.4.90| pylibjpeg | :doc:`JPEG 2000 | +------------------------+----------------------+ | ` | | *JPEG 2000* |1.2.840.10008.1.2.4.91| | | +------------------------+----------------------+-----------+----------------------------------+ | *RLE Lossless* | 1.2.840.10008.1.2.5 | pydicom, | :doc:`RLE Lossless | | | | pylibjpeg,| ` | | | | gdcm | | +------------------------+----------------------+-----------+----------------------------------+ .. versionchanged:: 3.0 Added the `jls_error`, `j2k_cr`, `j2k_psnr` and `generate_instance_uid` keyword parameters. Examples -------- Compress the existing uncompressed *Pixel Data* in place: >>> from pydicom import examples >>> from pydicom.uid import RLELossless >>> ds = examples.ct >>> ds.compress(RLELossless) >>> ds.save_as("ct_rle_lossless.dcm") Parameters ---------- transfer_syntax_uid : pydicom.uid.UID The UID of the :dcm:`transfer syntax` to use when compressing the pixel data. arr : numpy.ndarray, optional Compress the uncompressed pixel data in `arr` and use it to set the *Pixel Data*. If `arr` is not used then the existing *Pixel Data* in the dataset will be compressed instead. The :attr:`~numpy.ndarray.shape`, :class:`~numpy.dtype` and contents of the array should match the dataset. encoding_plugin : str, optional Use the `encoding_plugin` to compress the pixel data. See the :doc:`user guide ` for a list of plugins available for each UID and their dependencies. If not specified then all available plugins will be tried (default). encapsulate_ext : bool, optional If ``True`` then force the addition of an extended offset table. If ``False`` (default) then an extended offset table will be added if needed for large amounts of compressed *Pixel Data*, otherwise just the basic offset table will be used. generate_instance_uid : bool, optional If ``True`` (default) then generate a new (0008,0018) *SOP Instance UID* value for the dataset using :func:`~pydicom.uid.generate_uid`, otherwise keep the original value. jls_error : int, optional **JPEG-LS Near Lossless only**. The allowed absolute compression error in the pixel values. j2k_cr : list[float], optional **JPEG 2000 only**. A list of the compression ratios to use for each quality layer. There must be at least one quality layer and the minimum allowable compression ratio is ``1``. When using multiple quality layers they should be ordered in decreasing value from left to right. For example, to use 2 quality layers with 20x and 5x compression ratios then `j2k_cr` should be ``[20, 5]``. Cannot be used with `j2k_psnr`. j2k_psnr : list[float], optional **JPEG 2000 only**. A list of the peak signal-to-noise ratios (in dB) to use for each quality layer. There must be at least one quality layer and when using multiple quality layers they should be ordered in increasing value from left to right. For example, to use 2 quality layers with PSNR of 80 and 300 then `j2k_psnr` should be ``[80, 300]``. Cannot be used with `j2k_cr`. **kwargs Optional keyword parameters for the encoding plugin may also be present. See the :doc:`encoding plugins options ` for more information. )ryrzrtrurvrwN)r() rGrxrsryrzrtrurvrwrrrHrHrIr(Cs  zDataset.compress)as_rgbrtrBr{rBcKsrtjr|d|rtt|jd|j}|r||d<|r$||d<|jdi|t |f||d|dS)a Perform an in-place decompression of a dataset with a compressed *Transfer Syntax UID*. .. warning:: This function requires `NumPy `_ and may require the installation of additional packages to perform the actual pixel data decoding. See the :doc:`pixel data decompression documentation ` for more information. * The dataset's *Transfer Syntax UID* will be set to *Explicit VR Little Endian*. * The *Pixel Data* will be decompressed in its entirety and the *Pixel Data* element's value updated with the decompressed data, padded to an even length. * The *Pixel Data* element's VR will be set to **OB** if *Bits Allocated* <= 8, otherwise it will be set to **OW**. * The :attr:`DataElement.is_undefined_length ` attribute for the *Pixel Data* element will be set to ``False``. * Any :dcm:`image pixel` module elements may be modified as required to match the uncompressed *Pixel Data*. * If `generate_instance_uid` is ``True`` (default) then a new (0008,0018) *SOP Instance UID* value will be generated. .. versionchanged:: 3.0 Added the `as_rgb` and `generate_instance_uid` keyword parameters. .. deprecated:: 3.0 The `handler_name` parameter will be removed in v4.0, use `decoding_plugin` instead. Parameters ---------- handler_name : str, optional Deprecated and will be removed in v4.0, use `decoding_plugin` instead. as_rgb : bool, optional :mod:`~pydicom.pixels` **backend only.** If ``True`` (default) then convert pixel data with a YCbCr :ref:`photometric interpretation ` such as ``"YBR_FULL_422"`` to RGB. generate_instance_uid : bool, optional If ``True`` (default) then generate a new (0008,0018) *SOP Instance UID* value for the dataset using :func:`~pydicom.uid.generate_uid`, otherwise keep the original value. decoding_plugin : str, optional The name of the decoding plugin to use when decoding compressed pixel data. If no `decoding_plugin` is specified (default) then all available plugins will be tried and the result from the first successful one yielded. * If using the :mod:`~pydicom.pixels` backend (default) then see the :doc:`API documentation` for the available plugins for each *Transfer Syntax UID*. * If using the deprecated :mod:`~pydicom.pixel_data_handlers` backend supported plugins are: ``'gdcm'``, ``'pillow'``, ``'jpeg_ls'``, ``'rle'``, ``'numpy'`` and ``'pylibjpeg'``. kwargs : dict[str, Any], optional :mod:`~pydicom.pixels` **backend only.** Optional keyword parameters for the decoding plugin may also be present. See the :doc:`decoding plugins options` for more information. rAz?.decompress() got an unexpected keyword argument 'handler_name'rB)r{rtNrH) rr~rvrrr[rrrr*)rGrAr{rtrBrrrGrHrHrIr*s$I  zDataset.decompresscCsJ|dks|dkr tdtjstdt|jdddlm}|||S)aOReturn the *Overlay Data* in `group` as a :class:`numpy.ndarray`. Parameters ---------- group : int The group number of the overlay data. Returns ------- numpy.ndarray The (`group`,3000) *Overlay Data* converted to a :class:`numpy.ndarray`. i`i`z^The group part of the 'Overlay Data' element tag must be between 0x6000 and 0x60FF (inclusive)zNumPy is required for z.overlay_array()r)get_overlay_array)rMr have_numpy ImportErrorrr[pydicom.overlaysr|)rGrDr|rHrHrI overlay_array8s  zDataset.overlay_arraycCs|td|jS)a Return the pixel data as a :class:`numpy.ndarray`. .. warning:: This property requires `NumPy `_ and may require the installation of additional packages to perform the actual pixel data decoding. See the :doc:`pixel data decompression documentation ` for more information. .. versionchanged:: 3.0 The backend used for pixel data decoding has changed from the :mod:`~pydicom.pixel_data_handlers` module to the :mod:`~pydicom.pixels` module. The behavior of the new backend is not backwards compatible with the old one, in particular the default color space should now be RGB when previously YCbCr data was returned. To revert to the deprecated :mod:`~pydicom.pixel_data_handlers` backend pass ``use_v2_backend=True`` to the :meth:`~pydicom.dataset.Dataset.pixel_array_options` method:: >>> from pydicom import examples >>> ds = examples.ct >>> ds.pixel_array_options(use_v2_backend=True) >>> arr = ds.pixel_array The :mod:`~pydicom.pixel_data_handlers` module and the `use_v2_backend` keyword argument will be removed in v4.0. Returns ------- numpy.ndarray The contents of the (7FE0,0008) *Float Pixel Data*, (7FE0,0009) *Double Float Pixel Data* or (7FE0,0010) *Pixel Data* elements converted to a :class:`numpy.ndarray`. The array will be shaped as: * (rows, columns) for single frame, single sample data * (rows, columns, samples) for single frame, multi-sample data * (frames, rows, columns) for multi-frame, single sample data * (frames, rows, columns, samples) for multi-frame, multi-sample data When using the :mod:`pydicom.pixels` backend the decoding options used with the returned array can be customized via the :meth:`~pydicom.dataset.Dataset.pixel_array_options` method. See Also -------- pydicom.pixels.pixel_array A function for returning the pixel data from the path to a dataset, a readable file-like containing a dataset or a :class:`~pydicom.dataset.Dataset` instance. Can be used to minimize the memory required to return the pixel data when used with a path or file-like. pydicom.pixels.iter_pixels Similar to :func:`pydicom.pixels.pixel_array` but returns a generator that iterates through the image frames. r)rHrrrrHrHrIr+Us< zDataset.pixel_array)indexrawrBuse_v2_backendrrrcKsntjr|d|rtt|jd||d<||d<|r#||d<tjr(dn||d<||_d|_i|_ dS) aSet the decoding and processing options used by the :attr:`~pydicom.dataset.Dataset.pixel_array` property. .. versionadded:: 3.0 .. deprecated:: 3.0 The `use_v2_backend` keyword parameter will be removed in v4.0. **Processing** The following processing operations on the raw pixel data will always be performed: * Natively encoded bit-packed pixel data for a :ref:`bits allocated ` of ``1`` will be unpacked. * Natively encoded pixel data with a :ref:`photometric interpretation ` of ``"YBR_FULL_422"`` will have it's sub-sampling removed. * The output array will be reshaped to the specified dimensions. * JPEG-LS or JPEG 2000 encoded data whose signedness doesn't match the expected :ref:`pixel representation` will be converted to match. With the :mod:`pydicom.pixels` backend, if ``raw = False`` (the default) then the following processing operation will also be performed: * Pixel data with a :ref:`photometric interpretation ` of ``"YBR_FULL"`` or ``"YBR_FULL_422"`` will be converted to RGB. Examples -------- Convert the *Pixel Data* to an array that's a view on the original buffer:: >>> from pydicom import examples >>> ds = examples.ct >>> ds.pixel_array_options(view_only=True) >>> arr = ds.pixel_array Use the deprecated :mod:`~pydicom.pixel_data_handlers` backend to convert the *Pixel Data* to an array:: >>> from pydicom import examples >>> ds = examples.ct >>> ds.pixel_array_options(use_v2_backend=True) >>> arr = ds.pixel_array Parameters ---------- index : int | None, optional If ``None`` (default) then return an array containing all the frames in the pixel data, otherwise return one containing only the frame from the specified `index`, which starts at 0 for the first frame. Only available with the :mod:`~pydicom.pixels` backend. raw : bool, optional If ``True`` then return the decoded pixel data after only minimal processing (see the processing section above). If ``False`` (default) then additional processing may be applied to convert the pixel data to it's most commonly used form (such as converting from YCbCr to RGB). Only available with the :mod:`~pydicom.pixels` backend. decoding_plugin : str, optional The name of the decoding plugin to use when decoding compressed pixel data. If no `decoding_plugin` is specified (default) then all available plugins will be tried and the result from the first successful one returned. For information on the available plugins for each *Transfer Syntax UID*: * If using the :mod:`~pydicom.pixels` backend see the :doc:`documentation for the decoder` corresponding to the dataset's *Transfer Syntax UID*. * If using the :mod:`~pydicom.pixel_data_handlers` backend supported values are ``'gdcm'``, ``'pillow'``, ``'jpeg_ls'``, ``'rle'``, ``'numpy'`` and ``'pylibjpeg'``. use_v2_backend : bool, optional If ``False`` (default) then use the :mod:`pydicom.pixels` backend to decode the pixel data, otherwise use the deprecated :mod:`pydicom.pixel_data_handlers` backend. **kwargs Optional keyword parameters for controlling decoding with the :mod:`~pydicom.pixels` backend, please see the :doc:`decoding options documentation` for more information. rzJ.pixel_array_options() got an unexpected keyword argument 'use_v2_backend'rrrBFruN) rr~rvrrr[rrrr)rGrrrBrrrrHrHrIpixel_array_optionss^  zDataset.pixel_array_optionscCs tstdtj||ddS)a9Return an :class:`~numpy.ndarray` for the multiplex group at `index` in the (5400,0100) *Waveform Sequence*. .. versionadded:: 2.1 Parameters ---------- index : int The index of the multiplex group to return the array for. Returns ------ numpy.ndarray The *Waveform Data* for the multiplex group as an :class:`~numpy.ndarray` with shape (samples, channels). If (003A,0210) *Channel Sensitivity* is present then the values will be in the units specified by the (003A,0211) *Channel Sensitivity Units Sequence*. See Also -------- :func:`~pydicom.waveforms.numpy_handler.generate_multiplex` :func:`~pydicom.waveforms.numpy_handler.multiplex_array` z(The waveform data handler requires numpyF)as_raw) wave_handlerrTrUmultiplex_array)rGrrHrHrIwaveform_array szDataset.waveform_arrayz)%(tag)s %(name)-35.35s %(VR)s: %(repval)selement_formatsequence_element_format indent_formatc#sRd|D]fddtD}jtjkr!||Vq||VqdS)aTIterate through the :class:`Dataset` yielding formatted :class:`str` for each element. Parameters ---------- element_format : str The string format to use for non-sequence elements. Formatting uses the attributes of :class:`~pydicom.dataelem.DataElement`. Default is ``"%(tag)s %(name)-35.35s %(VR)s: %(repval)s"``. sequence_element_format : str The string format to use for sequence elements. Formatting uses the attributes of :class:`~pydicom.dataelem.DataElement`. Default is ``"%(tag)s %(name)-35.35s %(VR)s: %(repval)s"`` indent_format : str or None Placeholder for future functionality. Yields ------ str A string representation of an element. ) from_jsonto_json to_json_dictr9 descriptionvalidatecsDi|]}|ds |vr|tt|rt|nt|qS)_) startswithcallabler)riattrr  exclusionrHrIrO s z+Dataset.formatted_lines..N)iterallrr6rr)rGrrr elem_dictrHrrIformatted_lines% s    zDataset.formatted_linesrindenttop_level_onlyc CsRg}|j|}|j|d}t|drL|jrLtjjrL|dd|jD] }t|j||t |Wdn1s?wYq$|dd|D]U}t|jF|j t j kr|||jd|j dt|jd|s|jD]}|||d||d qvn ||t |Wdn1swYqNd |S) aReturn a string of the DataElements in the Dataset, with indented levels. This private method is called by the ``__str__()`` method for handling print statements or ``str(dataset)``, and the ``__repr__()`` method. It is also used by ``top()``, therefore the `top_level_only` flag. This function recurses, with increasing indentation levels. ..versionchanged:: 2.0 The file meta information is returned in its own section, if :data:`~pydicom.config.show_file_meta` is ``True`` (default) Parameters ---------- indent : int, optional The indent level offset (default ``0``). top_level_only : bool, optional When True, only create a string for the top level elements, i.e. exclude elements within any Sequences (default ``False``). Returns ------- str A string representation of the Dataset. rBrPzDataset.file_meta z-<49Nrtz z item(s) ---- z --------- ) indent_charsrCrPrrshow_file_metardr1rUreprr6rrrrlrS _pretty_strrf)rGrrstrings indent_strnextindent_strr r>rHrHrIr] sD       zDataset._pretty_strcCr)aGet the VR method used by the original encoding of the dataset. .. deprecated:: 3.0 ``read_implicit_vr`` will be removed in v4.0, , use :attr:`~pydicom.dataset.Dataset.original_encoding` instead. Returns ------- bool | None Returns ``None`` if the dataset has been created from scratch, otherwise returns ``True`` if the dataset was decoded from file or buffer and used implicit VR, ``False`` if it used explicit VR. rz,' object has no attribute 'read_implicit_vr'z1.read_implicit_vr' will be removed in v4.0, use 'z.original_encoding[0]' instead)rr[rr~rr'rr|rrHrHrIread_implicit_vr s zDataset.read_implicit_vrcCr)aGet the endianness used by the original encoding of the dataset. .. deprecated:: 3.0 ``read_little_endian`` will be removed in v4.0, use :attr:`~pydicom.dataset.Dataset.original_encoding` instead. Returns ------- bool | None Returns ``None`` if the dataset has been created from scratch, otherwise returns ``True`` if the dataset was decoded from file or buffer and used little endian encoding, ``False`` for big endian. rz.' object has no attribute 'read_little_endian'z3.read_little_endian' will be removed in v4.0, use 'z.original_encoding[1]' instead)rr[rr~rr'rr{rrHrHrIread_little_endian s  zDataset.read_little_endiancCs$dddtddfdd}||dS)z6Remove all private elements from the :class:`Dataset`.r>r?r rANcSs|jjr ||j=dSdS)z4Internal method to use as callback to walk() method.N)rUr<)r>r rHrHrIremove_callback s z4Dataset.remove_private_tags..remove_callback)r r)rGrrHrHrIremove_private_tags szDataset.remove_private_tags implicit_vr little_endianenforce_file_format overwrite_Dataset__write_like_originalrrrrrc Ks|dur |dur d}|jddurSt|di}|dd} d} z| j} Wnttfy<|dur4|} ntjs:|j} Ynw| durS|jd| krStdt|j dt j |||f||||d|dS) a Encode the current :class:`Dataset` and write it to `filename`. See the documentation for :func:`~pydicom.filewriter.dcmwrite` for more detailed information. .. warning:: Encoding a dataset with ``little_endian=False`` (i.e. as big endian) is not recommended. Big endian encoding was retired from the DICOM Standard in 2006. .. warning:: This function cannot be used to convert a decoded dataset to an encoding that uses a different endianness, such as from big to little endian. :func:`~pydicom.filewriter.dcmwrite()` must be used instead, however the process is not automatic. See the documentation of :func:`~pydicom.filewriter.dcmwrite()` for details. .. versionchanged:: 3.0 Added `implicit_vr`, `little_endian`, `enforce_file_format` and `overwrite` keyword arguments .. deprecated:: 3.0 `write_like_original` will be removed in v4.0, please use `enforce_file_format` instead Parameters ---------- filename : str | PathLike | BinaryIO The path, file-like or writeable buffer to write the encoded dataset to. If using a buffer it must have ``write()``, ``seek()`` and ``tell()`` methods. write_like_original : bool, optional If ``True`` (default) then write the dataset as-is, otherwise ensure that the dataset is written in the DICOM File Format or raise an exception is that isn't possible. This parameter is deprecated, please use `enforce_file_format` instead. implicit_vr : bool, optional Required if the dataset has no valid public *Transfer Syntax UID* set in the file meta and :attr:`~pydicom.dataset.Dataset.is_implicit_VR` or :attr:`~pydicom.dataset.Dataset.original_encoding` are ``None``. If ``True`` then encode using implicit VR, otherwise use explicit VR. little_endian : bool, optional Required if the dataset has no valid public *Transfer Syntax UID* set in the file meta and :attr:`~pydicom.dataset.Dataset.is_little_endian` or :attr:`~pydicom.dataset.Dataset.original_encoding` are ``None``. If ``True`` (default) then use little endian byte order when encoding, otherwise use big endian (not recommended). enforce_file_format : bool, optional If ``True`` then ensure the dataset is written in the DICOM File Format or raise an exception if that isn't possible. If ``False`` (default) then write the dataset as-is, preserving the following - which may result in a non-conformant file: - ``Dataset.preamble``: if the dataset has no preamble then none will be written - ``Dataset.file_meta``: if the dataset is missing any required *File Meta Information Group* elements then they will not be added or written overwrite : bool, optional If ``False`` and `filename` is a :class:`str` or PathLike, then raise a :class:`FileExistsError` if a file already exists with the given filename (default ``True``). See Also -------- pydicom.filewriter.dcmwrite Encode a :class:`Dataset` and write it to a file or buffer. NTrBrPrQrz.save_as()' cannot be used to convert between little and big endian encoding. Please read the documentation for filewriter.dcmwrite() if this is what you really want to dor) r rrvr"rrMrr~rr[rdcmwrite) rGrrrrrrrrrPsyntax use_littlerHrHrIsave_as s>Z    zDataset.save_ascCst|ds t|_dSdS)z5Create an empty ``Dataset.file_meta`` if none exists.rPN)rCFileMetaDatasetrPrrHrHrIensure_file_meta] s  zDataset.ensure_file_metacCs|ds |r|dkr||dSt|||dSt|}|durA||vr4t|}t|||}n||}||_|||<dSt |rMt d|dt |rkd|d}t jdkrbt|n t jd krkt |t|||dS) a.Intercept any attempts to set a value for an instance attribute. If name is a DICOM keyword, set the corresponding tag and DataElement. Else, set an instance (python) attribute as any other class would do. Parameters ---------- name : str The keyword for the element you wish to add/change. If `name` is not a DICOM element keyword then this will be the name of the attribute to be added/changed. value The value for the attribute to be added/changed. is_rPNrz\' is a DICOM repeating group element and must be added using the add() or add_new() methods.zCamel case attribute 'z:' used which is not in the element keyword data dictionaryrr)rislower_set_file_metarc __setattr__rrr rSrrM_RE_CAMEL_CASErrINVALID_KEYWORD_BEHAVIORr')rGrrSrUrr rrHrHrIrc s4        zDataset.__setattr__Dataset | NonecCsX|dur ||jd<dSt|ts|jj}td|dt|ts%t|}||jd<dS)z2Set the Dataset's File Meta Information attribute.NrPrz0.file_meta' must be a 'FileMetaDataset' instance)rryr?rWr[rr)rGrScls_namerHrHrIr s    zDataset._set_file_metar c Csjt|tr tdzt|}Wnty$}z td|d|d}~wwt|ttBs0tdt|j t r:|j }nt|j }||krNtd|d|d|j rt d ||jd ?}t|j|}||vr||krt|tryt||j|d }||j|_|tvrd|_i|_||j|<|jtjkrt|trt|jtjst|j|_|tt|dSdSdS) a3Operator for ``Dataset[key] = elem``. Parameters ---------- key : int or Tuple[int, int] or str The tag for the element to be added to the :class:`Dataset`. elem : dataelem.DataElement or dataelem.RawDataElement The element to add to the :class:`Dataset`. Raises ------ NotImplementedError If `key` is a :class:`slice`. ValueError If the `key` value doesn't match the corresponding :attr:`DataElement.tag`. z3Slicing is not supported when setting Dataset itemszUnable to convert the key 'z' to an element tagNz-Dataset items must be 'DataElement' instancesz The key 'z'' doesn't match the 'DataElement' tag 'rzSetting private tag rCr)ryrrSr/rrMr r"rrUr0r<rrgr rDr!rrSrErrrrxr6rrrSequencerr)rGr=r relem_tagrprivate_creator_tagrHrHrI __setitem__ sT          zDataset.__setitem__rtphotometric_interpretation bits_storedcCst|||||ddS)a Use an :class:`~numpy.ndarray` to set the *Pixel Data* and related Image Pixel module elements. .. versionadded:: 3.0 The following :dcm:`Image Pixel` module elements values will be added, updated or removed as necessary: * (0028,0002) *Samples per Pixel* using a value corresponding to `photometric_interpretation`. * (0028,0104) *Photometric Interpretation* from `photometric_interpretation`. * (0028,0006) *Planar Configuration* will be added and set to ``0`` if *Samples per Pixel* is > 1, otherwise it will be removed. * (0028,0008) *Number of Frames* from the array :attr:`~numpy.ndarray.shape`, however it will be removed if `arr` only contains a single frame. * (0028,0010) *Rows* and (0028,0011) *Columns* from the array :attr:`~numpy.ndarray.shape`. * (0028,0100) *Bits Allocated* from the array :class:`~numpy.dtype`. * (0028,0101) *Bits Stored* and (0028,0102) *High Bit* from `bits_stored`. * (0028,0103) *Pixel Representation* from the array :class:`~numpy.dtype`. In addition: * The *Transfer Syntax UID* will be set to *Explicit VR Little Endian* if it doesn't already exist or uses a compressed (encapsulated) transfer syntax. * If `generate_instance_uid` is ``True`` (default) then the *SOP Instance UID* will be added or updated. Parameters ---------- arr : numpy.ndarray An array with :class:`~numpy.dtype` uint8, uint16, int8 or int16. The array must be shaped as one of the following: * (rows, columns) for a single frame of grayscale data. * (frames, rows, columns) for multi-frame grayscale data. * (rows, columns, samples) for a single frame of multi-sample data such as RGB. * (frames, rows, columns, samples) for multi-frame, multi-sample data. photometric_interpretation : str The value to use for (0028,0004) *Photometric Interpretation*. Valid values are ``"MONOCHROME1"``, ``"MONOCHROME2"``, ``"PALETTE COLOR"``, ``"RGB"``, ``"YBR_FULL"``, ``"YBR_FULL_422"``. bits_stored : int The value to use for (0028,0101) *Bits Stored*. Must be no greater than the number of bits used by the :attr:`~numpy.dtype.itemsize` of `arr`. generate_instance_uid : bool, optional If ``True`` (default) then add or update the (0008,0018) *SOP Instance UID* element with a value generated using :func:`~pydicom.uid.generate_uid`. Raises ------ NotImplementedError If the dataset has a big-endian *Transfer Syntax UID*. rN)r.)rGrsrrrtrHrHrIr. s? zDataset.set_pixel_datacCsd}t|jvr |tj}nt|dr|j}|dur't|tr$td|vn||_|jt j kr/dS|jD]3}t|jvr\|jtj}|durRt|trNtd|vn||_q2t|dr[|j|_q2t|dre|j|_q2dS)zqSet the `_pixel_rep` attribute for the current dataset and child datasets of the sequence element `elem`.N _pixel_rep) r3rxrSrCrrybytesr`r6rr)rGr pritemrHrHrIr? s,         z!Dataset._set_pixel_representationrzTagType | Nonerrcs|durt|}durtt|j}|sgS|durHdur0|dkr)|S|dd|Sttfdd|}|dkrA|S|dd|St||}durX||d|St|}||||S)aReturn the element tags in the Dataset that match the slice. Parameters ---------- start : int or 2-tuple of int or None The slice's starting element tag value, in any format accepted by :func:`~pydicom.tag.Tag`. stop : int or 2-tuple of int or None The slice's stopping element tag value, in any format accepted by :func:`~pydicom.tag.Tag`. step : int or None The slice's step size. Returns ------ list of BaseTag The tags in the :class:`Dataset` that meet the conditions of the slice. NrBcs|kSrgrH)rrrHrI sz(Dataset._slice_dataset..)r/rrxrnlistr r)rGrrrall_tags step1_listi_starti_stoprHrrIr_ s"  zDataset._slice_datasetcCs|S)zHandle str(dataset). ..versionchanged:: 2.0 The file meta information was added in its own section, if :data:`pydicom.config.show_file_meta` is ``True`` rrrHrHrI__str__ s zDataset.__str__cCs |jddS)z?Return a :class:`str` representation of the top level elements.T)rrrrHrHrItop rz Dataset.topcCst|S)zReturn a :class:`list` of valid names for auto-completion code. Used in IPython, so that data element names can be found and offered for autocompletion on the IPython command line. )rrrHrHrI trait_names szDataset.trait_namesdcCsDt|D]\}}t|trt|||q||ttt|<qdS)zExtend :meth:`dict.update` to handle DICOM tags and keywords. Parameters ---------- d : dict or Dataset The :class:`dict` or :class:`Dataset` to use when updating the current object. N)rrryrasetattrr/rr`)rGrr=rSrHrHrIr s  zDataset.updateccs<|D]}|V|jtjkr|jD] }|EdHqqdS)aIterate through the :class:`Dataset`, yielding all the elements. Unlike ``iter(Dataset)``, this *does* recurse into sequences, and so yields all elements as if dataset were "flattened". Yields ------ dataelem.DataElement N)r6rrrSr)rGr rrHrHrIr s   zDataset.iterallcallbackrc Cst|j}|D]8}t|*||}||||r2||vr2|jtjkr2|j}|D]}||q*Wdn1s` elements and run `callback` on each. Visit all elements in the :class:`Dataset`, possibly recursing into sequences and their items. The `callback` function is called for each :class:`~pydicom.dataelem.DataElement` (including elements with a VR of 'SQ'). Can be used to perform an operation on certain types of elements. For example, :meth:`~Dataset.remove_private_tags` finds all elements with private tags and deletes them. The elements will be returned in order of increasing tag number within their current :class:`Dataset`. Parameters ---------- callback A callable function that takes two arguments: * a :class:`Dataset` * a :class:`~pydicom.dataelem.DataElement` belonging to that :class:`Dataset` recursive : bool, optional Flag to indicate whether to recurse into sequences (default ``True``). N) rrxrnr1r6rrrSr)rGrrr4rUrsequencer>rHrHrIr s    z Dataset.walkcls json_datasetbulk_data_uri_handlerc Cst|ttBtBrttttft|}|}| D]8\}}|d}t t | t t j@}t|dkr=d}dg} n|d}||} t|||| ||} || q|S)a;Return a :class:`Dataset` from a DICOM JSON Model object. See the DICOM Standard, Part 18, :dcm:`Annex F`. Parameters ---------- json_dataset : dict, str, bytes or bytearray :class:`dict`, :class:`str`, :class:`bytes` or :class:`bytearray` representing a DICOM Data Set formatted based on the :dcm:`DICOM JSON Model`. bulk_data_uri_handler : callable, optional 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 ------- Dataset rrNrt)ryrar bytearrayrdictrjsonloadsrr_rrnrJSON_VALUE_KEYSrlr rr) rrrr>rUmappingrunique_value_keys value_keyrSrrHrHrIr s$"   zDataset.from_jsonbulk_data_thresholdbulk_data_element_handlersuppress_invalid_tagsc Csi}|rtnt}|L|D]>}|d}z||}|j||d||<WqtyP} z|s;td|| td|d| WYd} ~ qd} ~ wwWd|S1s\wY|S)aReturn a dictionary representation of the :class:`Dataset` conforming to the DICOM JSON Model as described in the DICOM Standard, Part 18, :dcm:`Annex F`. Parameters ---------- bulk_data_threshold : int, optional Threshold for the length of a base64-encoded binary data element above which the element should be considered bulk data and the value provided as a URI rather than included inline (default: ``1024``). Ignored if no bulk data handler is given. bulk_data_element_handler : callable, optional Callable function that accepts a bulk data element and returns a JSON representation of the data element (dictionary including the "vr" key and either the "InlineBinary" or the "BulkDataURI" key). suppress_invalid_tags : bool, optional Flag to specify if errors while serializing tags should be logged and the tag dropped or if the error should be bubbled up. Returns ------- dict :class:`Dataset` representation based on the DICOM JSON Model. 08X)rrzError while processing tag z: N) rstrict_readingr rnrrrerrorwarning) rGrrrrcontextr=json_keyrrrHrHrIr1 s. " zDataset.to_json_dict dump_handlercCs2|durdtdtfdd}|}||j|||dS)aReturn a JSON representation of the :class:`Dataset`. See the DICOM Standard, Part 18, :dcm:`Annex F`. Parameters ---------- bulk_data_threshold : int, optional Threshold for the length of a base64-encoded binary data element above which the element should be considered bulk data and the value provided as a URI rather than included inline (default: ``1024``). Ignored if no bulk data handler is given. bulk_data_element_handler : callable, optional Callable function that accepts a bulk data element and returns a JSON representation of the data element (dictionary including the "vr" key and either the "InlineBinary" or the "BulkDataURI" key). dump_handler : callable, optional Callable function that accepts a :class:`dict` and returns the serialized (dumped) JSON string (by default uses :func:`json.dumps`). .. note: Make sure to use a dump handler that sorts the keys (see example below) to create DICOM-conformant JSON. suppress_invalid_tags : bool, optional Flag to specify if errors while serializing tags should be logged and the tag dropped or if the error should be bubbled up. Returns ------- str :class:`Dataset` serialized into a string based on the DICOM JSON Model. Examples -------- >>> def my_json_dumps(data): ... return json.dumps(data, indent=4, sort_keys=True) >>> ds.to_json(dump_handler=my_json_dumps) NrrAcSstj|ddS)NT) sort_keys)rdumps)rrHrHrI json_dump sz"Dataset.to_json..json_dump)r)rrar)rGrrrrrrHrHrIrc s/zDataset.to_json)rrScCs|dur |dur td|dur&zt|Wnty%td|dw|dur:t|ts:tdt|jdt|}| |}|durOtd|dt|t s\td|d |durb|n|j }|durk|n|j }|j ||d |j|<dS) a Modify the VR or value for the raw element with `tag`. When a :class:`Dataset` is created most of it's elements are in their :class:`~pydicom.dataelem.RawDataElement` form, and only upon trying to access the element is it converted to a :class:`~pydicom.dataelem.DataElement`. When this conversion fails due to non-conformance issues, this method can be used to modify the raw element data prior to conversion in order to fix any issues. Example ------- Change the VR for the element with tag (0029,1026) before conversion to :class:`~pydicom.dataelem.DataElement`. >>> from pydicom import examples >>> ds = examples.ct >>> ds.update_raw_element(0x00291026, vr="US") >>> elem = ds[0x00291026] # conversion to DataElement occurs here >>> type(elem) >>> elem.VR "US" Parameters ---------- tag : int | str | tuple[int, int] | BaseTag The tag for a :class:`~pydicom.dataelem.RawDataElement` in the dataset. vr : str, optional Required if `value` is not used, the value to use for the modified element's VR, if not used then the existing VR will be kept. value : bytes, optional Required if `vr` is not used, the value to use for the modified element's raw encoded value, if not used then the existing value will be kept. Nz/Either or both of 'vr' and 'value' are requiredzInvalid VR value 'rz'value' must be bytes, not 'zNo element with tag z was foundzThe element with tag z[ has already been converted to a 'DataElement' instance, this method must be called earlier)r6rS)rMrrryrrrr[r/rr"r6rS_replacerx)rGrUrrSrrHrHrIupdate_raw_element s*&     zDataset.update_raw_element)rAr?rg)rAr)rAN)r=rrAN)r=rrAr)F)rt)NrtF)rF)rSrrANT)rNF)rNNF)yr[r\r]r^rrprrJrr BaseExceptionr rbrr rr2rarTr`rrrrPrrrrRrrrrrrvr_r0r _DatasetValuerrnrrrpropertyrrrrsetterrrQr<rrrrrr#r"r.r r!r2rr5r"r6r7r8r9r:r;r@rHrDrErVfloatr(r*rr+rrdefault_element_formatdefault_sequence_element_formatrrrrrosPathLikerrr$rrrrrr.rrrrrrrrr classmethodrrrrrrr__repr__ __classcell__rHrHrrIr?s 2     - *  -? #   +    d I! % /  ! % CV %F     ^A n  8:    ~ <M G  5  ,  <  4 ? A _FileDataset FileDataset)boundc@sfeZdZdZ    ddeeBeBdededBddd e d e d dfd d Z de e e fd dfddZdS)raAn extension of :class:`Dataset` to make reading and writing to file-like easier. .. versionchanged:: 3.0 Added the `buffer` attribute and the `filename` attribute has been changed to only contain the filename the dataset was read from (if any). Attributes ---------- preamble : str | bytes | None The optional DICOM preamble prepended to the :class:`FileDataset`, if available. file_meta : FileMetaDataset | None The Dataset's file meta information as a :class:`FileMetaDataset`, if available (``None`` if not present). Consists of group ``0x0002`` elements. filename : str | None The filename associated with the :class:`FileDataset` if read from a file or file-like, or ``None`` if the dataset has been read from a buffer-like object. buffer : ReadableBuffer | None The buffer-like object the :class:`FileDataset` was read from, or ``None`` if the dataset has been read from a file or file-like. fileobj_type The type of object the :class:`FileDataset` was read from. timestamp : float | None The modification time of the file the :class:`FileDataset` was read from, ``None`` if the modification time is not available. NTfilename_or_objr>preamblerPzFileMetaDataset | Noner#r"rAcCst||||_|dur|nt|_tjs||_||_||_ ||_ d|_ d|_ d|_ t|}t|tr;||_ t|_ n+t|tjrI|j|_ t|_ n||_ t||_ t|ddr\|j|_ n t|ddrf|j |_ d|_|j r}tj|j rt|j j|_dSdSdS)aInitialize a :class:`FileDataset` read from a DICOM file. Parameters ---------- filename_or_obj : str, PathLike, file-like or readable buffer * :class:`str` or path: the full path to the dataset file * file-like: a file-like object in "rb" mode * readable buffer: an object with ``read()``, ``tell()`` and ``seek()`` methods such as :class:`io.BytesIO`. dataset : Dataset or dict Some form of dictionary, usually a :class:`Dataset` returned from :func:`~pydicom.filereader.dcmread`. preamble : bytes or str, optional The 128-byte DICOM preamble. file_meta : FileMetaDataset, optional The file meta :class:`FileMetaDataset`, such as the one returned by :func:`~pydicom.filereader.read_file_meta_info`, or an empty :class:`FileMetaDataset` if no file meta information is in the file. is_implicit_VR : bool, optional ``True`` (default) if implicit VR transfer syntax used; ``False`` if explicit VR. is_little_endian : bool ``True`` (default) if little-endian transfer syntax used; ``False`` if big-endian. Nrr)r?rJrrrPrr~rrr|r{rrrr%ryraopenioBufferedReaderrrrrrpathexistsstatst_mtime)rGrr>rrPr#r"rHrHrIrJ s: $      zFileDataset.__init__rVc Cs|j}||}||t|<|jD]I\}}|dkrRz t||t||WqtyQ}zt dt |j d|dt||td|WYd}~qd}~wwt||t||q|S)zReturn a deep copy of the file dataset. Sets the `buffer` to ``None`` if it's been closed or is otherwise not copyable. Returns ------- FileDataset A deep copy of the file dataset. rzThe z exception 'z' occurred trying to deepcopy the buffer-like the dataset was read from, the 'buffer' attribute will be set to 'None' in the copied objectN) rW__new__rXrrrrdeepcopyrr'rr[)rGrVrresultkvrrHrHrIrZS s     zFileDataset.__deepcopy__)NNTT)r[r\r]r^r&rr#rprrbrJrr`rrZrHrHrHrIr s,"  LTrPrenforce_standardcsD] }|jjdkrtdq|rOdvsdjrd_dvs(djr-tt_dvr:dd t _ fd d d D}|rQt d d |dSdS)aValidate the *File Meta Information* elements in `file_meta`. Parameters ---------- file_meta : Dataset The *File Meta Information* data elements. enforce_standard : bool, optional If ``False``, then only a check for invalid elements is performed. If ``True`` (default), the following elements will be added if not already present and the Type 1 elements given a value if empty: * (0002,0001) *File Meta Information Version*, Type 1 * (0002,0012) *Implementation Class UID*, Type 1 * (0002,0013) *Implementation Version Name*, Type 3 and the following elements will be checked to ensure they're present and have a non-empty value: * (0002,0002) *Media Storage SOP Class UID*, Type 1 * (0002,0003) *Media Storage SOP Instance UID*, Type 1 * (0002,0010) *Transfer Syntax UID*, Type 1 Raises ------ ValueError If `enforce_standard` is ``True`` and any of the Type 1 *File Meta Information* elements are missing from `file_meta` or have no value. ValueError If any non-Group 2 Elements are present in `file_meta`. rzTOnly File Meta Information group (0002,eeee) elements may be present in 'file_meta'.FileMetaInformationVersionsImplementationClassUIDImplementationVersionNamezPYDICOM .cs4g|]}|vs |jrt|dt|qS) )is_emptyr/rrrPrHrIr s z&validate_file_meta..)iiizSRequired File Meta Information elements are either missing or have an empty value: r_N) r6rUrDrMrrr5r4rrfrrr)rPrr invalidrHrrIvalidate_file_metar s: "   rcseZdZdZdededdffdd Zededdfd d Zd d d e ddffdd Z e de e e fe dBfddZZS)rzContains a collection (dictionary) of group 2 DICOM Data Elements. .. versionadded:: 2.0 Derived from :class:`~pydicom.dataset.Dataset`, but only allows Group 2 (File Meta Information) data elements rqrrrANcsZtj|i|t|j||||||||||||||dS)arInitialize a FileMetaDataset Parameters are as per :class:`Dataset`; this overrides the super class only to check that all are group 2 data elements Raises ------ ValueError If any data elements are not group 2. TypeError If the passed argument is not a :class:`dict` or :class:`Dataset` N)rrJrrrxrrrHrIrJ s  zFileMetaDataset.__init__ init_valuecCsZ|durdSt|ttBstdt|dd|D}|r+tdd|dS)aRaise errors if initialization value is not acceptable for file_meta Parameters ---------- init_value: dict or Dataset The tag:data element pairs to initialize a file meta dataset Raises ------ TypeError If the passed argument is not a :class:`dict` or :class:`Dataset` ValueError If any data elements passed are not group 2. Nz(Argument must be a dict or Dataset, not cSs&g|]}t|jdkrtt|qS)r)r/rDrarrHrHrIr s&z,FileMetaDataset.validate..z]File meta datasets may only contain group 2 elements but the following elements are present: r_)ryr?rrrrnrMrf)r non_group2rHrHrIr s zFileMetaDataset.validater=rrScsBt|jtr |j}nt|j}|jdkrtdt||dS)aOverride parent class to only allow setting of group 2 elements. Parameters ---------- key : int or Tuple[int, int] or str The tag for the element to be added to the Dataset. value : dataelem.DataElement or dataelem.RawDataElement The element to add to the :class:`FileMetaDataset`. Raises ------ ValueError If `key` is not a DICOM Group 2 tag. rz;Only group 2 data elements are allowed in a FileMetaDatasetN)ryrUr0r/rDrMrr)rGr=rSrUrrHrIrs   zFileMetaDataset.__setitem__r/cCs,|dd}|r|js|jsdS|j|jfS)a"Return the transfer syntax encoding method (if any) Returns ------- tuple[bool, bool] | tuple[None, None] If the file meta has a valid public Transfer Syntax UID then returns (is implicit, is little), otherwise returns (None, None). rQNr/)rvr<is_transfer_syntaxr#r")rGrXrHrHrI_tsyntax_encodings  z!FileMetaDataset._tsyntax_encoding)r[r\r]r^rprrJ staticmethodrrrrr_rbrrrHrHrrIr s (za(?P(^[A-Za-z])((?=.+?[A-Z])[A-Za-z0-9]+)|(^[A-Z])([A-Za-z0-9]+))(?P[A-Za-z0-9][^_]$)rgr)ir^rrrros.pathrebisectrcollections.abcrrrrrr contextlibr importlib.utilr r\ itertoolsr typesr typingr rrrrrrrr~rrrpydicom._versionrpydicom.charsetrrpydicom.configrpydicom.datadictrrrrrrpydicom.dataelemr r!r"pydicom.filebaser#r$pydicom.fileutilr%r& pydicom.miscr'pydicom.pixelsr(r)r*r+pydicom.pixels.utilsr,r-r. pydicom.tagr/r0r1r2r3 pydicom.uidr4r5pydicom.valuerepr6rr7pydicom.waveformsr8rrr<rrarbrorrp__annotations__r?rrrrcompilerrHrHrHrIs      $       $    Hu