o i@sdZddlmZddlmZmZddlZddlmZm Z ddl m Z ddl m Z ddlmZdd lmZmZmZdd lmZmZdd lmZmZmZd d deeBeBdedeefddZ d d deeBeBdede!eeeffddZ"d d deeBeBdedeefddZ#ddd ddeeBeBdedBde!eeeefe!eefBdBdedee!edff ddZ$ddd ddeeBdedBde!eeeefe!eefBdBdedeef ddZ%ddd ddeeBeBd ede!eeeefe!eefBdBdedBdedef d!d"Z&Gd#d$d$Z'Gd%d&d&eZ(dVd(ed)edeefd*d+Z)d,edefd-d.Z*dVd(ed)edeefd/d0Z+ 1dWd2eed3ed4e,defd5d6Z- 1dXd7eed4e,de(fd8d9Z.d2eede!eeeffd:d;Z/d7eede!e(eeffdede!e,eeffd?d@Z1d>edefdAdBZ2d>edeefdCdDZ3 dYdEedFedBdeefdGdHZ4 dYdEedFedBdee!edffdIdJZ5dKedeefdLdMZ6dKedefdNdOZ7d>ededBfdPdQZ8e1e2e3e4e5e6e7e8e+e*dR Z9dSede fdTdUZ:dS)Zz@Functions for working with encapsulated (compressed) pixel data.)Iterator)BytesIOBufferedIOBaseN)packunpack)Any)config) warn_and_log) DicomBytesIODicomIOReadableBuffer) buffer_lengthreset_buffer_position)TagItemTagSequenceDelimiterTag< endiannessbufferrreturncCst|ttBr t|}t|d|d\}}|d>|Bdkr+tdt||dt|d|dd}|dr@td |dkrFgStt||dd||S) a Return the encapsulated pixel data's basic offset table frame offsets. .. versionadded:: 3.0 Parameters ---------- buffer : bytes | bytearray | readable buffer A buffer containing the encapsulated frame data, positioned at the beginning of the Basic Offset Table. May be :class:`bytes`, :class:`bytearray` or an object with ``read()``, ``tell()`` and ``seek()`` methods. If the latter then after reading it will be positioned at the start of the item tag of the first fragment after the Basic Offset Table. endianness : str, optional If ``"<"`` (default) then the encapsulated data uses little endian encoding, otherwise if ``">"`` it uses big endian encoding. Returns ------- list[int] A list of the offset positions to the first item tag of each frame, as measured from the end of the basic offset table. References ---------- :dcm:`DICOM Standard, Part 5, Annex A.4` HH`zFound unexpected tag z@ instead of (FFFE,E000) when parsing the Basic Offset Table itemLr@The length of the Basic Offset Table item is not a multiple of 4) isinstancebytes bytearrayrrread ValueErrorrlist)rrgroupelemlengthr&D/mnt/sdb/aimis/docanh/lib/python3.10/site-packages/pydicom/encaps.pyparse_basic_offsetss"r(c CsBt|ttBr t|}|}d}g} zt|d|d\}}Wn ty,Ynkw|d>|B}|dkrt|d}dkrRt d|t|ddt|d |d} | d krlt d |dd |d 7}| |d| | d n|dkrnt dt |d|ddq| |d||fS)aReturn the number of fragments and their positions in `buffer`. .. versionadded:: 3.0 Parameters ---------- buffer : bytes | bytearray | readable buffer A buffer containing the encapsulated frame data, starting at the first byte of item tag for a fragment, such as after the end of the Basic Basic Offset Table. May be :class:`bytes`, :class:`bytearray` or an object with ``read()``, ``tell()`` and ``seek()`` methods. If the latter then the offset will be reset to the starting position afterwards. endianness : str, optional If ``"<"`` (default) then the encapsulated data uses little endian encoding, otherwise if ``">"`` it uses big endian encoding. Returns ------- tuple[int, list[int]] The number of fragments and the absolute offset position of the first byte of the item tag for each fragment in `buffer`. rTrrrr5Unable to determine the length of the item at offset U as the end of the data has been reached - the encapsulated pixel data may be invalidr Undefined item length at offset 3 when parsing the encapsulated pixel data fragments`Unexpected tag ' ' at offset 8 when parsing the encapsulated pixel data fragment items) rrrrtellrr Exceptionlenr!appendseekr) rr start_offset nr_fragmentsfragment_offsetsr#r$tag raw_lengthr%r&r&r'parse_fragmentsFsF   r>ccs t|ttBr t|} zt|d|d\}}Wn ty&YdSw|d>|B}|dkrmt|d}dkrLtd| t|ddt|d|d }|d krftd | dd ||Vn|d krsdStdt |d| ddq )a@Yield frame fragments from the encapsulated pixel data in `buffer`. .. versionadded:: 3.0 Parameters ---------- buffer : bytes | bytearray | readable buffer A buffer containing the encapsulated frame data, starting at the first byte of item tag for a fragment, usually this will be after the end of the Basic Offset Table. May be :class:`bytes`, :class:`bytearray` or an object with ``read()``, ``tell()`` and ``seek()`` methods. If the latter than the final offset position depends on how many fragments have been yielded. endianness : str, optional If ``"<"`` (default) then the encapsulated data uses little endian encoding, otherwise if ``">"`` it uses big endian encoding. Yields ------ bytes A pixel data fragment. Trrrrr)r*rrr+r,r-r0r1r2r3N) rrrrrr r5r6r!r4r)rrr#r$r<r=r%r&r&r'generate_fragmentss:  r?number_of_framesextended_offsetsrrArB.ccst|ttBr t|}t||d}|ryt|dtr2t|dd}tt||d|d}n|d}t|dtrTt|dd}tt||d|d}n|d}|}t ||D]\} } | || dd| | fVqadS|rg} d} d} t|d}t ||dD].}| |kr| |q| || dkr| |n t| V| d7} |g} | t|d7} qt| VdSt||d\}}t ||d}|dkrt|fVdS|std||krdd |DEdHdS|dkrtd d |DVdS||krQd }g} d}|D]}| |||d dvr,t| V|d7}g} q| rF||kr9d }nd}t|t| VdS||krOtddStd)aYield fragmented pixel data frames from `buffer`. .. versionadded:: 3.0 .. note:: When the Basic Offset Table is empty and the Extended Offset Table isn't supplied then more fragmented frames may be yielded than given by `number_of_frames` provided there are sufficient excess fragments available. Parameters ---------- buffer : bytes | bytearray | readable buffer A buffer containing the encapsulated frame data, positioned at the first byte of the basic offset table. May be :class:`bytes`, :class:`bytearray` or an object with ``read()``, ``tell()`` and ``seek()`` methods. If the latter then the final position depends on how many fragmented frames have been yielded. number_of_frames : int, optional Required when the Basic Offset Table is empty and the Extended Offset Table has not been supplied. This should be the value of (0028,0008) *Number of Frames* or the expected number of frames in the encapsulated data. extended_offsets : tuple[list[int], list[int]] or tuple[bytes, bytes], optional The (offsets, lengths) of the Extended Offset Table as taken from (7FE0,0001) *Extended Offset Table* and (7FE0,0002) *Extended Offset Table Lengths* as either the raw encoded values or a list of their decoded equivalents. endianness : str, optional If ``"<"`` (default) then the encapsulated data uses little endian encoding, otherwise if ``">"`` it uses big endian encoding. Yields ------- tuple[bytes, ...] An encapsulated pixel data frame, with the contents of the tuple the frame's fragmented encoded data. rrr/Qr.NzUnable to determine the frame boundaries for the encapsulated pixel data as there is no Basic or Extended Offset Table and the number of frames has not been suppliedcss|]}|fVqdSNr&.0fragmentr&r&r' Isz-generate_fragmented_frames..cs|]}|VqdSrDr&rEr&r&r'rHNzThe end of the encapsulated pixel data has been reached but no JPEG EOI/EOC marker was found, the final frame may be be invalidzThe end of the encapsulated pixel data has been reached but fewer frames than expected have been found. Please confirm that the generated frame data is correctzfThe end of the encapsulated pixel data has been reached but fewer frames than expected have been foundzUnable to generate frames from the encapsulated pixel data as there are fewer fragments than frames; the dataset may be corrupt or the number of frames may be incorrect)rrrrr(r6r"rr4zipr8r r?r7tupler>nextr!r )rrArBr basic_offsets nr_offsetsoffsetslengthsfragments_startoffsetr%frame current_indexcurrent_offset final_indexrGr:_ fragments eoi_markerframe_nrmsgr&r&r'generate_fragmented_framess-               r_ccs,t||||d}|D]}d|Vq dS)aYield complete pixel data frames from `buffer`. .. versionadded:: 3.0 .. note:: When the Basic Offset Table is empty and the Extended Offset Table isn't supplied then more frames may be yielded than given by `number_of_frames` provided there are sufficient excess fragments available. Parameters ---------- buffer : bytes | readable buffer A buffer containing the encapsulated frame data, starting at the first byte of the basic offset table. May be :class:`bytes`, :class:`bytearray` or an object with ``read()``, ``tell()`` and ``seek()`` methods. If the latter then the final offset position depends on the number of yielded frames. number_of_frames : int, optional Required when the Basic Offset Table is empty and the Extended Offset Table has not been supplied. This should be the value of (0028,0008) *Number of Frames* or the expected number of frames in the encapsulated data. extended_offsets : tuple[list[int], list[int]] or tuple[bytes, bytes], optional The (offsets, lengths) of the Extended Offset Table as taken from (7FE0,0001) *Extended Offset Table* and (7FE0,0002) *Extended Offset Table Lengths* as either the raw encoded values or a list of their decoded equivalents. endianness : str, optional If ``"<"`` (default) then the encapsulated data uses little endian encoding, otherwise if ``">"`` it uses big endian encoding. Yields ------ bytes The encoded pixel data, one frame at a time. References ---------- DICOM Standard Part 5, :dcm:`Annex A ` r@Nr_join)rrArBrfragmented_framesr[r&r&r'generate_framess0rd)rBrArindexcCs^t|ttBr t|}|}t||d}|rt|dtr5t|dd}tt||d|d}n|d}t|dtrWt|dd}tt||d|d} n|d} |t|krkt d|dd| ||dd| | |} | || S|r|t|krt d|dd|t|dkr||d||} | ||dt | | |d} n| |d dt ||d} d d d | D} | || St||d\} }| dkr|dkrtt ||d} | |d| St d |st d| |kr2|| dkrt d| d|d| ||dtt ||d} | |d| St ||d} |dkrX|dkrTd dd | D} | |d| St dd}g}d}| D]+}||||ddvr||krd |} | |d| S|d7}g}q`|r||krtdd |} | |d| St d|dd)aReturn the specified frame at `index`. .. versionadded:: 3.0 .. note:: When the Basic Offset Table is empty and the Extended Offset Table isn't supplied then it's possible to return a frame at a higher `index` than expected from the supplied `number_of_frames` value provided there are sufficient excess fragments available. Parameters ---------- buffer : bytes | bytearray | readable buffer A buffer containing the encapsulated frame data, positioned at the first byte of the basic offset table. May be :class:`bytes`, :class:`bytearray` or an object with ``read()``, ``tell()`` and ``seek()`` methods. If the latter then the buffer will be reset to the starting position if the frame was returned successfully. index : int The index of the frame to be returned, starting at ``0`` for the first frame. number_of_frames : int, optional Required for multi-frame data when the Basic Offset Table is empty, the Extended Offset Table has not been supplied and there are multiple frames. This should be the value of (0028,0008) *Number of Frames* or the expected number of frames in the encapsulated data. extended_offsets : tuple[list[int], list[int]] or tuple[bytes, bytes], optional The (offsets, lengths) of the Extended Offset Table as taken from (7FE0,0001) *Extended Offset Table* and (7FE0,0002) *Extended Offset Table Lengths* as either the raw encoded values or a list of their decoded equivalents. endianness : str, optional If ``"<"`` (default) then the encapsulated data uses little endian encoding, otherwise if ``">"`` it uses big endian encoding. Returns ------- bytes A single frame of encoded pixel data. References ---------- DICOM Standard Part 5, :dcm:`Annex A ` rrr/rCr.z=There aren't enough offsets in the Extended Offset Table for z framesz:There aren't enough offsets in the Basic Offset Table for r`csrIrDr&rEr&r&r'rH-rJzget_frame..zHFound 1 frame fragment in the encapsulated pixel data, 'index' must be 0zUnable to determine the frame boundaries for the encapsulated pixel data as there is no basic or extended offset table data and the number of frames has not been suppliedzFound z? frame fragments in the encapsulated pixel data, an 'index' of z is invalidcsrIrDr&rEr&r&r'rH^rJz2The 'index' must be 0 if the number of frames is 1rKrLNzThe end of the encapsulated pixel data has been reached but no JPEG EOI/EOC marker was found, the returned frame data may be invalidz,There is insufficient pixel data to contain )rrrrr4r(r6r"rr!r8r r?rbr>rOr7r )rrerBrArstarting_positionrPrQrRrSrVr%r[r:r;r\frame_fragmentsr]rGr&r&r' get_frames7                   ric@s8eZdZdZdeddfddZdededefd d ZdS) _BufferedItemarConvenience class for a buffered encapsulation item. Attributes ---------- buffer : io.BufferedIOBase The buffer containing data to be encapsulated. length : int The total length of the encapsulated item, including the item tag and value and any trailing padding required to bring the item data up to an even length. rrNcCsl||_t||_|jdkrtdd|j|jd|_t|jd|_dd|jdjddd f|_ d S) zCreate a new ``_BufferedItem`` instance. Parameters ---------- buffer : io.BufferedIOBase The buffer containing data to be encapsulated, may be empty. lz?Buffers containing more than 4294967294 bytes are not supportedr/r`rlittle)r% byteorderN) rr _blenr!r%bool_paddingrbto_bytes_item)selfrr&r&r'__init__s   z_BufferedItem.__init__startsizecCs*d|kr |jksntd|d|jddd}t}||}r||}|dkr7|j|||}nBd|dkrD|jkrjnn$t|j|j|d|j|}Wdn1sdwYn|j rw||jdkrwd}nd }|s t |S|t |7}| |||}s%t |S) aReturn data from the encapsulated frame. Parameters ---------- start : int The initial position in the encapsulated item where data should be read from, must be greater than or equal to 0, where ``0`` is the first byte of the item tag. size : int The number of bytes to read from the buffer. Returns ------- bytes The data read from the buffer. rzInvalid 'start' value 'z&', must be in the closed interval [0, r.]r/Nr`) r%r!rrsrorrr8r rqr6extendr)rtrvrwnr_readoutr%rU_readr&r&r'r s8    z_BufferedItem.read) __name__ __module__ __qualname____doc__rruintrr r&r&r&r'rjs rjc@seZdZdZd%deededdfddZede fd d Z edefd d Z ede fd dZ ede fddZ edefddZedeefddZedeefddZd&dedBde fddZdefddZejfdededefdd Zdefd!d"Zdefd#d$ZdS)'EncapsulatedBufferzConvenience class for managing the encapsulation of one or more buffers containing compressed *Pixel Data*. .. versionadded:: 3.0 Fbuffersuse_botrNcst|ts tddd|D|_d|_||_|jdg|_|jfdd|j D|j |j ddt |jD|_ ttdd |j d<d S) a@Create a new class instance. Parameters ---------- buffers : list[io.BufferedIOBase] The buffered pixel data frames to be encapsulated on writing the dataset. Only a single frame of pixel data can be in each buffer and the buffers must inherit from :class:`io.BufferedIODBase` and be readable and seekable. use_bot : bool, optional If ``True`` then the Basic Offset Table will include the offsets for each encapsulated items, otherwise no offsets will be included (default). zI'buffers' must be a list of objects that inherit from 'io.BufferedIOBase'cSg|]}t|qSr&)rj)rFbr&r&r' z/EncapsulatedBuffer.__init__..rcsg|]}|tqSr&r6)rFrUbotr&r'r cSsi|] \}}|d|qSr.r&)rFidxitemr&r&r' sz/EncapsulatedBuffer.__init__..r/N)rr" TypeError_items_offset_use_botbasic_offset_table _item_offsetsrzrRr7encapsulated_length enumerate_buffersrjr)rtrrr&rr'rus zEncapsulatedBuffer.__init__cCsZ|jsdSdg}|tddt|j|tdt|jdg|jRd|S)z%Return an encoded Basic Offset Table.srlReturn ``True`` if any of the encapsulated buffers are closed.css|]}|jjVqdSrD)rclosedrFrr&r&r'rH&z,EncapsulatedBuffer.closed..)anyrrtr&r&r'r#zEncapsulatedBuffer.closedcCs*tdt|jdgdd|jDRS)zReturn an encoded *Extended Offset Table Lengths* value from `lengths` Returns ------- bytes The encoded lengths of the frame. rrCcss|]}|dVqdS)r/Nr&)rFr%r&r&r'rH2rz6EncapsulatedBuffer.extended_lengths..)rr6rSrr&r&r'extended_lengths(s* z#EncapsulatedBuffer.extended_lengthscCs tdt|jdg|jRS)aZReturn an encoded *Extended Offset Table* value from `offsets` Returns ------- bytes The encoded offsets to the first byte of the item tag of the first fragment for every frame, as measured from the first byte of the first item tag following the empty Basic Offset Table Item. rrC)rr6rRrr&r&r'rB4s z#EncapsulatedBuffer.extended_offsetscCst|jt|jS)z>Return the total length of the encapulated *Pixel Data* value.)r6rsumrSrr&r&r'rArz&EncapsulatedBuffer.encapsulated_lengthcCsdd|jDS)z%Return the encapsulated item lengths.cSsg|]}|jqSr&)r%rr&r&r'rIsz.EncapsulatedBuffer.lengths..)rrr&r&r'rSFszEncapsulatedBuffer.lengthscsfddtjDS)zGReturn the encapsulated item offsets, starting at 0 for the first item.cs"g|] \}}tjd|qS)r)rrS)rFrrZrr&r'rNs"z.EncapsulatedBuffer.offsets..)rrSrr&rr'rRKszEncapsulatedBuffer.offsets rwc Cs|j|jkrdS|dur|jn|}d}t}||}rytt|j|jdd}|D]!\}\}}||jkr<|krLnq+|j||j||} nq+| sT t |S|jt| 7_|t| 7}| | |j|jkrs t |S||}st |S)aJRead up to `size` bytes of data from the encapsulated buffers. Parameters ---------- size : int, optional The amount of data to be read, if ``None`` then all data will be returned. Returns ------- bytes The data read from the encapsulated buffers. r`Nrr.) rrrrrMrrr r6rzr) rtrwr{r|r%iteratorrrvendr}r&r&r'r Ps.       zEncapsulatedBuffer.readcCr)z=Return ``True`` if all the encapsulated buffers are readable.cs|]}|jVqdSrD)rreadablerr&r&r'rHyz.EncapsulatedBuffer.readable..allrrr&r&r'rwzEncapsulatedBuffer.readablerUwhencecCs|tjtjtjfvrtd|tjkr!|dkrtd||}n%|tjkr4|j|}|dkr1dn|}n|tjkrF|j|}|dkrDdn|}||_|jS)zChange the encapsulated buffers position to the given byte `offset`, relative to the position indicated by `whence` and return the new absolute position. z+Invalid 'whence' value, should be 0, 1 or 2rzNegative seek 'offset' value )osSEEK_SETSEEK_CURSEEK_ENDr!rr)rtrUr new_offsetr&r&r'r8{s     zEncapsulatedBuffer.seekcCr)z=Return ``True`` if all the encapsulated buffers are seekable.csrrD)rseekablerr&r&r'rHrz.EncapsulatedBuffer.seekable..rrr&r&r'rrzEncapsulatedBuffer.seekablecCs|jS)z>Return the current stream position of the encapsulated buffers)rrr&r&r'r4szEncapsulatedBuffer.tell)F)r)r~rrrr"rrprupropertyrrrrrBrrrSrRr rrrr8rr4r&r&r&r'rs,-  'rr.rVr:ccst|}||ddkrtdt||}|dr|d7}td||d|D] }||||Vq)||d}||d}||drK|d7}|VdS)a4Yield one or more fragments from `frame`. .. versionadded:: 1.2 Parameters ---------- frame : bytes The data to fragment. nr_fragments : int, optional The number of fragments (default ``1``). Yields ------ bytes The fragmented data, with all fragments as an even number of bytes greater than or equal to two. Notes ----- * All items containing an encoded fragment shall be made of an even number of bytes greater than or equal to two. * The last fragment of a frame may be padded, if necessary to meet the sequence item format requirements of the DICOM Standard. * Any necessary padding may be appended after the end of image marker. * Encapsulated Pixel Data has the Value Representation OB. * Values with a VR of OB shall be padded with a single trailing NULL byte value (``0x00``) to achieve even length. References ---------- DICOM Standard, Part 5, :dcm:`Section 6.2 ` and :dcm:`Annex A.4 ` r.g@zCToo many fragments requested (the minimum fragment size is 2 bytes)rkrNry)r6r!rrange)rVr: frame_lengthr%rUrGr&r&r'fragment_frames #     rrGcCs"d}|tdt|7}||7}|S)aReturn an itemized `fragment`. .. versionadded:: 1.2 Parameters ---------- fragment : bytes The fragment to itemize. Returns ------- bytes The itemized fragment. Notes ----- * The encoding of the item shall be in Little Endian. * Each fragment is encapsulated as a DICOM Item with tag (FFFE,E000), then a 4 byte length. rlr)rr6)rGrr&r&r'itemize_fragmentsrccs t||D]}t|VqdS)aYield items generated from `frame`. .. versionadded:: 1.2 Parameters ---------- frame : bytes The data to fragment and itemise. nr_fragments : int, optional The number of fragments/items (default 1). Yields ------ bytes An itemized fragment of the frame, encoded as little endian. Notes ----- * The encoding of the items shall be in Little Endian. * Each fragment is encapsulated as a DICOM Item with tag (FFFE,E000), then a 4 byte length. References ---------- DICOM Standard, Part 5, :dcm:`Section 7.5 ` and :dcm:`Annex A.4 ` N)rr)rVr:rGr&r&r' itemize_frames rTframesfragments_per_framehas_botc Cs$t|}t}|d|rB|ddtdd|ddD}|dkr0td |d dd |td d ||d|n|td ddg}t|D]"\}}d} t||D] } | t| 7} || q\|||| qQ|rtd|dg|ddR|ddd |<t |S)aiReturn encapsulated `frames`. .. versionadded:: 1.2 When using a compressed transfer syntax (such as RLE Lossless or one of JPEG formats) then any *Pixel Data* must be :dcm:`encapsulated `:: # Where `frame1`, `frame2` are single frames that have been encoded # using the corresponding compression method to Transfer Syntax UID ds.PixelData = encapsulate([frame1, frame2, ...]) For multi-frame data each frame must be encoded separately and then all encoded frames encapsulated together. When many large frames are to be encapsulated, the total length of encapsulated data may exceed the maximum length available with the :dcm:`Basic Offset Table` (2**31 - 1 bytes). Under these circumstances you can: * Pass ``has_bot=False`` to :func:`~pydicom.encaps.encapsulate` * Use :func:`~pydicom.encaps.encapsulate_extended` and add the :dcm:`Extended Offset Table` elements to your dataset (recommended) Data will be encapsulated with a Basic Offset Table Item at the beginning, then one or more fragment items. Each item will be of even length and the final fragment of each frame may be padded with ``0x00`` if required. Parameters ---------- frames : list of bytes The frame data to encapsulate, one frame per item. fragments_per_frame : int, optional The number of fragments to use for each frame (default ``1``). has_bot : bool, optional ``True`` to include values in the Basic Offset Table, ``False`` otherwise (default ``True``). If `fragments_per_frame` is not ``1`` then it's strongly recommended that this be ``True``. Returns ------- bytes The encapsulated pixel data. References ---------- DICOM Standard, Part 5, :dcm:`Section 7.5 ` and :dcm:`Annex A.4 ` See Also -------- :func:`~pydicom.encaps.encapsulate_buffer` :func:`~pydicom.encaps.encapsulate_extended` :func:`~pydicom.encaps.encapsulate_extended_buffer` rlr.r/cSrr&r)rFfr&r&r'rcrzencapsulate..Nrfr+z1The total length of the encapsulated frame data (zL bytes) will be greater than the maximum allowed by the Basic Offset Table (z bytes), it's recommended that you use the Extended Offset Table instead (see the 'encapsulate_extended' function for more information)rrsrrr) r6rrzrr!rrrr7r) rrr nr_framesoutputtotal bot_offsetsiirVitemised_lengthrr&r&r' encapsulate s0; &   0rrcCs t||dS)aReturn an :class:`~pydicom.encaps.EncapsulatedBuffer` instance from `buffers`. .. versionadded:: 3.0 Examples -------- .. code-block:: python from pydicom import Dataset, FileMetaDataset from pydicom.encaps import encapsulate_buffer from pydicom.uid import JPEG2000Lossless # Open the compressed image frames as io.BufferedReader instances frame1 = open("frame1.j2k", "rb") frame2 = open("frame2.j2k", "rb") frame3 = open("frame3.j2k", "rb") ds = Dataset() ds.file_meta = FileMetaDataset() ds.file_meta.TransferSyntaxUID = JPEG2000Lossless ds.PixelData = encapsulate_buffer([frame1, frame2, frame3]) # Write the encapsulated buffer data to file ds.save_as("buffered_dataset.dcm") # Close the buffers frame1.close() frame2.close() frame3.close() Parameters ---------- buffers : list[io.BufferedIOBase] A list of objects inheriting :class:`io.BufferedIOBase` containing the compressed *Pixel Data* frames to be encapsulated. Returns ------- EncapsulatedBuffer A :class:`~pydicom.encaps.EncapsulatedBuffer` instance that can be used as the value for a *Pixel Data* element. See Also -------- :func:`~pydicom.encaps.encapsulate` :func:`~pydicom.encaps.encapsulate_extended` :func:`~pydicom.encaps.encapsulate_extended_buffer` )r)r)rrr&r&r'encapsulate_buffers 5rcCst|}dd|D}dd|D}dg}t|ddD]\}}||||dqtd|d g|R}td|d g|R}t|d d ||fS) aReturn encapsulated image data and values for the Extended Offset Table elements. When using a compressed transfer syntax (such as RLE Lossless or one of JPEG formats) then any *Pixel Data* must be :dcm:`encapsulated `. When many large frames are to be encapsulated, the total length of encapsulated data may exceed the maximum offset available with the :dcm:`Basic Offset Table` (2**32 - 1 bytes). Under these circumstances you can: * Use :func:`~pydicom.encaps.encapsulate_extended` and add the :dcm:`Extended Offset Table` elements to your dataset (recommended) * Pass ``has_bot=False`` to :func:`~pydicom.encaps.encapsulate` Examples -------- .. code-block:: python from pydicom import Dataset, FileMetaDataset from pydicom.encaps import encapsulate_extended from pydicom.uid import JPEG2000Lossless # 'frames' is a list of image frames that have been each been encoded # separately using the compression method corresponding to the Transfer # Syntax UID frames: list[bytes] = [...] out: tuple[bytes, bytes, bytes] = encapsulate_extended(frames) ds = Dataset() ds.file_meta = FileMetaDataset() ds.file_meta.TransferSyntaxUID = JPEG2000Lossless ds.PixelData = out[0] ds.ExtendedOffsetTable = out[1] ds.ExtendedOffsetTableLengths = out[2] Parameters ---------- frames : list of bytes The compressed frame data to encapsulate, one frame per item. Returns ------- bytes, bytes, bytes The (encapsulated frames, extended offset table, extended offset table lengths). See Also -------- :func:`~pydicom.encaps.encapsulate` :func:`~pydicom.encaps.encapsulate_buffer` :func:`~pydicom.encaps.encapsulate_extended_buffer` cSrr&r)rFrVr&r&r'rrz(encapsulate_extended..cSsg|]}||dqS)rkr&rFrr&r&r'rrrNrfr/rrCF)r)r6rr7rr)rr frame_lengths frame_offsetsrr%rRrSr&r&r'encapsulate_extendeds8rcCst|}||j|jfS)aReturn :class:`~pydicom.encaps.EncapsulatedBuffer` as well as encoded offsets and lengths for the Extended Offset Table elements. .. versionadded:: 3.0 Examples -------- .. code-block:: python from pydicom import Dataset, FileMetaDataset from pydicom.encaps import encapsulate_extended_buffer from pydicom.uid import JPEG2000Lossless # Open the compressed image frames as io.BufferedReader instances frame1 = open("frame1.j2k", "rb") frame2 = open("frame2.j2k", "rb") frame3 = open("frame3.j2k", "rb") out: tuple[EncapsulatedBuffer, bytes, bytes] = ( encapsulate_extended_buffer([frame1, frame2, frame3]) ) ds = Dataset() ds.file_meta = FileMetaDataset() ds.file_meta.TransferSyntaxUID = JPEG2000Lossless ds.PixelData = out[0] ds.ExtendedOffsetTable = out[1] ds.ExtendedOffsetTableLengths = out[2] # Write the encapsulated buffer data to file ds.save_as("buffered_dataset.dcm") # Close the buffers frame1.close() frame2.close() frame3.close() Parameters ---------- buffers : list[io.BufferedIOBase] A list of objects inheriting :class:`io.BufferedIOBase` containing the compressed *Pixel Data* frames to be encapsulated. Returns ------- tuple[EncapsulatedBuffer, bytes, bytes] The (:class:`~pydicom.encaps.EncapsulatedBuffer`, extended offset table, extended offset table lengths). See Also -------- :func:`~pydicom.encaps.encapsulate` :func:`~pydicom.encaps.encapsulate_buffer` :func:`~pydicom.encaps.encapsulate_extended` )rrBr)rebr&r&r'encapsulate_extended_buffers<rfpcsjstdt}|dkrtd|d}|dr%tdg}|dkr0|d|fdd t|dDt||fS) atReturn a list of the fragment offsets from the Basic Offset Table. .. deprecated:: 3.0 This function will be removed in v4.0, please use :func:`~pydicom.encaps.parse_basic_offsets` instead. **Basic Offset Table** The Basic Offset Table Item must be present and have a tag (FFFE,E000) and a length, however it may or may not have a value. Basic Offset Table with no value :: Item Tag | Length | FE FF 00 E0 00 00 00 00 Basic Offset Table with value (2 frames) :: Item Tag | Length | Offset 1 | Offset 2 | FE FF 00 E0 08 00 00 00 00 00 00 00 10 00 00 00 For single or multi-frame images with only one frame, the Basic Offset Table may or may not have a value. When it has no value then its length shall be ``0x00000000``. For multi-frame images with more than one frame, the Basic Offset Table should have a value containing concatenated 32-bit unsigned integer values that are the byte offsets to the first byte of the Item tag of the first fragment of each frame as measured from the first byte of the first item tag following the Basic Offset Table Item. All decoders, both for single and multi-frame images should accept both an empty Basic Offset Table and one containing offset values. .. versionchanged:: 1.4 Changed to return (is BOT empty, list of offsets). Parameters ---------- fp : filebase.DicomIO The encapsulated pixel data positioned at the start of the Basic Offset Table. ``fp.is_little_endian`` should be set to ``True``. Returns ------- bool, list of int Whether or not the BOT is empty, and a list of the byte offsets to the first fragment of each frame, as measured from the start of the first item following the Basic Offset Table item. Raises ------ ValueError If the Basic Offset Table item's tag is not (FFEE,E000) or if the length in bytes of the item's value is not a multiple of 4. References ---------- DICOM Standard, Part 5, :dcm:`Annex A.4 ` "'fp.is_little_endian' must be Truerr1z*' when parsing the Basic Offset Table itemrrrc3s|]}VqdSrD)read_ULrrr&r'rHrz%_get_frame_offsets..) is_little_endianr!rread_tagrr7rzrrp)rr<r%rRr&rr'_get_frame_offsetsGs"A     rcCs|jstdt|dS)zReturn the number of fragments in `fp`. .. deprecated:: 3.0 This function will be removed in v4.0, please use :func:`~pydicom.encaps.parse_fragments` instead. rr)rr!r>rr&r&r'_get_nr_fragmentss rccs"|jstdt|EdHdS)apYield the encapsulated pixel data fragments. .. deprecated:: 3.0 This function will be remove in v4.0, please use :func:`~pydicom.encaps.generate_fragments` instead. For compressed (encapsulated) Transfer Syntaxes, the (7FE0,0010) *Pixel Data* element is encoded in an encapsulated format. **Encapsulation** The encoded pixel data stream is fragmented into one or more Items. The stream may represent a single or multi-frame image. Each *Data Stream Fragment* shall have tag of (FFFE,E000), followed by a 4 byte *Item Length* field encoding the explicit number of bytes in the Item. All Items containing an encoded fragment shall have an even number of bytes greater than or equal to 2, with the last fragment being padded if necessary. The first Item in the Sequence of Items shall be a 'Basic Offset Table', however the Basic Offset Table item value is not required to be present. It is assumed that the Basic Offset Table item has already been read prior to calling this function (and that `fp` is positioned past this item). The remaining items in the Sequence of Items are the pixel data fragments and it is these items that will be read and returned by this function. The Sequence of Items is terminated by a (FFFE,E0DD) *Sequence Delimiter Item* with an Item Length field of value ``0x00000000``. The presence or absence of the *Sequence Delimiter Item* in `fp` has no effect on the returned fragments. *Encoding* The encoding of the data shall be little endian. Parameters ---------- fp : filebase.DicomIO The encoded (7FE0,0010) *Pixel Data* element value, positioned at the start of the item tag for the first item after the Basic Offset Table item. ``fp.is_little_endian`` should be set to ``True``. Yields ------ bytes A pixel data fragment. Raises ------ ValueError If the data contains an item with an undefined length or an unknown tag. References ---------- DICOM Standard Part 5, :dcm:`Annex A.4 ` rN)rr!r?rr&r&r'_generate_pixel_data_fragments=r bytestreamrccs$t||dD]}d|VqdS)a]Yield complete frames from `buffer` as :class:`bytes`. .. deprecated:: 3.0 This function will be remove in v4.0, please use :func:`~pydicom.encaps.generate_frames` instead Parameters ---------- bytestream : bytes The value of the (7FE0,0010) *Pixel Data* element from an encapsulated dataset. The Basic Offset Table item should be present and the Sequence Delimiter item may or may not be present. nr_frames : int, optional Required for multi-frame data when the Basic Offset Table is empty and there are multiple frames. This should be the value of (0028,0008) *Number of Frames*. Yields ------ bytes A frame contained in the encapsulated pixel data. References ---------- DICOM Standard Part 5, :dcm:`Annex A ` rAr`Nra)rrrVr&r&r'_generate_pixel_data_framesrccst||dEdHdS)a] Yield an encapsulated pixel data frame. .. deprecated:: 3.0 Please use :func:`~pydicom.encaps.generate_fragmented_frames` instead. For the following transfer syntaxes, a fragment may not contain encoded data from more than one frame. However data from one frame may span multiple fragments. * 1.2.840.10008.1.2.4.50 - JPEG Baseline (Process 1) * 1.2.840.10008.1.2.4.51 - JPEG Baseline (Process 2 and 4) * 1.2.840.10008.1.2.4.57 - JPEG Lossless, Non-Hierarchical (Process 14) * 1.2.840.10008.1.2.4.70 - JPEG Lossless, Non-Hierarchical, First-Order Prediction (Process 14 [Selection Value 1]) * 1.2.840.10008.1.2.4.80 - JPEG-LS Lossless Image Compression * 1.2.840.10008.1.2.4.81 - JPEG-LS Lossy (Near-Lossless) Image Compression * 1.2.840.10008.1.2.4.90 - JPEG 2000 Image Compression (Lossless Only) * 1.2.840.10008.1.2.4.91 - JPEG 2000 Image Compression * 1.2.840.10008.1.2.4.92 - JPEG 2000 Part 2 Multi-component Image Compression (Lossless Only) * 1.2.840.10008.1.2.4.93 - JPEG 2000 Part 2 Multi-component Image Compression For the following transfer syntaxes, each frame shall be encoded in one and only one fragment. * 1.2.840.10008.1.2.5 - RLE Lossless Parameters ---------- bytestream : bytes The value of the (7FE0,0010) *Pixel Data* element from an encapsulated dataset. The Basic Offset Table item should be present and the Sequence Delimiter item may or may not be present. nr_frames : int, optional Required for multi-frame data when the Basic Offset Table is empty and there are multiple frames. This should be the value of (0028,0008) *Number of Frames*. Yields ------- tuple of bytes An encapsulated pixel data frame, with the contents of the :class:`tuple` the frame's fragmented data. Notes ----- If the Basic Offset Table is empty and there are multiple fragments per frame then an attempt will be made to locate the frame boundaries by searching for the JPEG/JPEG-LS/JPEG2000 EOI/EOC marker (``0xFFD9``). If the marker is not present or the pixel data hasn't been compressed using one of the JPEG standards then the generated pixel data may be incorrect. References ---------- DICOM Standard Part 5, :dcm:`Annex A ` rN)r_)rrr&r&r'_generate_pixel_datas=rdatacCs^t|!}d|_t|}g} t|}|sn||q|WdS1s(wYdS)a Read encapsulated data and return a list of bytes. .. deprecated:: 3.0 This function will be removed in v4.0, Please use :func:`~pydicom.encaps.generate_frames` for generating frame data or :func:`~pydicom.encaps.generate_fragments` for generating fragment data. Parameters ---------- data : bytes The encapsulated data, typically the value from ``Dataset.PixelData``. Returns ------- list of bytes All fragments as a list of ``bytes``. TN)r r _read_itemr7)rrBasicOffsetTableseqrr&r&r'_decode_data_sequenceUs   $rcCsdt|S)aRead encapsulated data and return the fragments as one continuous bytes. .. deprecated:: 3.0 This function will be removed in v4.0, Please use :func:`~pydicom.encaps.generate_frames` for generating frame data or :func:`~pydicom.encaps.generate_fragments` for generating fragment data. Parameters ---------- data : bytes The encapsulated pixel data fragments. Returns ------- bytes All fragments concatenated together. r`)rbr)rr&r&r'_defragment_data|srcCstj}z|}Wn tyYdSw|tkr8|}|d|d||dkr6|d||ddS|t krL|dt |d|}n|}|d|d||d krkt d |dd | |}|S) axRead and return a single Item in the fragmented data stream. .. deprecated:: 3.0 This function will be removed in v4.0, please use :func:`~pydicom.encaps.generate_fragments` instead. Parameters ---------- fp : filebase.DicomIO The file-like to read the item from. Returns ------- bytes The Item's raw bytes. Nz%%04x: Sequence Delimiter, length 0x%xr/rzFExpected 0x00000000 after delimiter, found 0x%x, at data position 0x%xrz/Expected Item with tag %s at data position 0x%xz%04x: Item, length 0x%xr+zCEncapsulated data fragment had Undefined Length at data position 0xx) rloggerrEOFErrorrrdebugr4warningrr!r )rrr<r% item_datar&r&r'rs>      r) get_frame_offsetsget_nr_fragmentsgenerate_pixel_data_fragmentgenerate_pixel_data_framegenerate_pixel_datadecode_data_sequencedefragment_data read_item itemise_frameitemise_fragmentnamecCs:|tvrtjst|dtt|Stdtd|)Nz* is deprecated and will be removed in v4.0zmodule z has no attribute ) _DEPRECATEDr _use_futurer DeprecationWarningAttributeErrorr~)rr&r&r' __getattr__srr)r.T)TrD);rcollections.abcriorrrstructrrtypingrpydicomr pydicom.miscr pydicom.filebaser r r pydicom.fileutilr r pydicom.tagrrrrrstrr"rr(rNr>r?r_rdrirjrrrrrprrrrrrrrrrrrrrr&r&r&r's"      5  F  ? " C" > " C^A? " h 8G  A[D # @'>