o i&@sVUdZddlmZmZmZddlZddlZddlmZddl m Z m Z ddl m Z ddlmZmZmZmZzddlZdZWn eyHd ZYnwdd lmZdd lmZdd lmZmZdd lmZddl m!Z!ddl"m#Z#m$Z$m%Z%m&Z&m'Z'ddl(m)Z)erddl*m+Z+ddl,m-Z-e.e/Z0dde1DZ2dddddddddd Z3dde34Dd d!hBZ5d"d#d$d%Z6d&d'e7d(DZ8e9e:e;fee d.j Z?d/ed0e@e!e:Bd1ed2eAd3e9eBefffd4d5ZCd6d3d1ed2e9eBeffd7d8ZD d~d9d ddddd:d6d3d;eBdeBd?eEd@eEdAe:dBdBe@eFdBdCe@eFdBd1ed2d3fdDdEZGddd9dFd6d3dGeEd@eEdHeBd1ed2d3f dIdJZHdKede:d2e;fdLdMZIdd6d3dOeBd2e:fdPdQZJd6d3d2e9eBe:ffdRdSZKdTe;d2e9eBeffdUdVZLdKe;d2e9eBeffdWdXZMdd6d3dYeEd2e:fdZd[ZNdddd d9d\dKd]d^d_d0e@e!e:BdBd`ee:dBdaeEdHeBd1ed2edbfdcddZOdd)s&r&samples_per_pixelphotometric_interpretationplanar_configurationnumber_of_framesrowscolumnsbits_allocated bits_storedpixel_representation) i(i(i((i(i(i(i(i(cCsh|]}|qSr!r!r"r#r!r!r%r&9FloatPixelDataDoubleFloatPixelData PixelData)))r8 )r8rcCs(i|]}|tddt|dDqS)cs|]}t|VqdSNintr"sr!r!r% Az.08b)bytesreversedr1r!r!r% @srF _UNPACK_LUT>cCsh|] }|jdddqS)big)lengthr )to_bytesr"xr!r!r%r&Vsiiz>Hf specific_tagskwargsreturnrcKs>ddlm}m}m}m}||dd||}|d|dd}|s&tdt|}|||j |j ||d } || _ t | fi|} || d<z| d } t| d ksRJWn ty^td wd |j } |j rud} t| d | \}}}nt| d| \}}} }| t| d<t| d| dt||f| d<| | fS)aReturn a dataset from `f` and a corresponding decoding options dict. Parameters ---------- f : BinaryIO The opened file-like containing the DICOM dataset, positioned at the start of the file. specific_tags : list[BaseTag | int] A list of additional tags to be read from the dataset and possibly returned via the `ds_out` dataset. kwargs : dict[str, Any] Required and optional arguments for the pixel data decoding functions. Returns ------- tuple[Dataset, dict[str, Any]] * A dataset containing the group 0x0028 elements, the extended offset elements (if any) and elements from `specific_tags`. * The required and optional arguments for the pixel data decoding functions. r) read_preamble_read_file_meta_info read_dataset_at_pixel_dataT)forcetransfer_syntax_uidTransferSyntaxUIDNzY'transfer_syntax_uid' is required if the dataset in 'src' is not in the DICOM File Format)is_implicit_VRis_little_endian stop_whenr^r9zzThe dataset in 'src' has no 'Pixel Data', 'Float Pixel Data' or 'Double Float Pixel Data' element, no pixel data to decodez><HHLHH2sHpixel_vrL pixel_keyword)pydicom.filereaderrarbrcrd setdefaultgetAttributeErrorrrhri file_metaas_pixel_optionsreadlen Exceptionrdecoder_PIXEL_KEYWORDS)r]r^r_rarbrcrdrutsyntaxdsoptsdata endiannessvrgroupelemrYr!r!r% _array_commonZsN     rr}c sfddtD}djvrd|d<|d}t|tr!t|n|}|dvr1td|dd}||d<d jvrGd jvrGjjf|d <| ||S) aReturn a dict containing the image pixel element values from `ds`. .. versionadded:: 3.0 Parameters ---------- ds : pydicom.dataset.Dataset A dataset containing Image Pixel module elements. **kwargs A :class:`dict` containing (key, value) pairs to be used to override the values taken from `ds`. For example, if ``kwargs = {'rows': 64}`` then the returned :class:`dict` will have a 'rows' value of 64 rather than whatever ``ds.Rows`` may be. Returns ------- dict[str, Any] A dictionary which may contain the following keys, depending on which elements are present in `ds` and the contents of `kwargs`: * `samples_per_pixel` * `photometric_interpretation` * `planar_configuration` * `number_of_frames` (always present) * `rows` * `columns` * `bits_allocated` * `bits_stored` * `pixel_representation` cs&i|]\}}|jvr||jqSr!)_dictvalue)r"tagattrr}r!r%rFs z$as_pixel_options..r0r*)Nrz A value of 'zA' for (0028,0008) 'Number of Frames' is invalid, assuming 1 framer3extended_offsets) _IMAGE_PIXELitemsr isinstancestrr>rExtendedOffsetTableExtendedOffsetTableLengthsupdate)r}r_r~ nr_framesr!rr%rvs&    rvr )encoding_pluginencapsulate_extgenerate_instance_uid jls_errorj2k_crj2k_psnrrfarrznp.ndarray | NonerrrrrrcKsddlm} ddlm} tD]} | | dqt|} | | }|js:d dd|j D}t d| j d || t krF|durF|| d <| tkrZ|durR|| d <|durZ|| d <|dur|d i}|dd}|sptd|jrwtd|j|fd|i| }nt|fi| }|j|fd|i|}dd|D}t|}|ddtdd|ddD}|s|dkrt|\|_|_|_nt||_|d}d|_tj|_d|_i|_ t!|d s| |_"| |j"_#|rt$}||_%||j"_&|S)aCompress uncompressed pixel data and update `ds` in-place with the resulting :dcm:`encapsulated` codestream. .. versionadded:: 3.0 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 | | +------------------------+----------------------+-----------+----------------------------------+ Examples -------- Compress the existing uncompressed *Pixel Data* in place: >>> from pydicom import examples >>> from pydicom.pixels import compress >>> from pydicom.uid import RLELossless >>> ds = examples.ct >>> compress(ds, RLELossless) >>> ds.save_as("ct_rle_lossless.dcm") Parameters ---------- ds : pydicom.dataset.Dataset The dataset to be compressed. 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 uncompressed *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 `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. rFileMetaDataset) get_encoderN cSg|]}d|qSz r!r?r!r!r% zcompress..zThe pixel data encoder for 'zF' is unavailable because all of its plugins are missing dependencies: rrrrurgr zUnable to determine the initial compression state of the dataset as there's no (0002,0010) 'Transfer Syntax UID' element in the dataset's 'file_meta' attributez,Only uncompressed datasets may be compressedrcSsg|]}|qSr!r!r"r]r!r!r%rr2rr9cSsg|]}t|qSr!rxrr!r!r%rsr7T)'pydicom.datasetrpydicom.pixelsrrvaluespopr is_availablejoinmissing_dependencies RuntimeErrornamerrrsrt is_compressed ValueError iter_encodervrxsumrr7rrris_undefined_lengthrOB _pixel_array _pixel_idhasattrrurgrSOPInstanceUIDMediaStorageSOPInstanceUID)r}rfrrrrrrrr_rroptionuidencodermissingrur|frame_iteratorr~encodedrtotalr instance_uidr!r!r%compresss     &   r)as_rgbrdecoding_pluginrrcKsddlm}d|vrtd|di}|dd}|s tdt|}|js+td |d d } | r?|||j g} n?||} | j s\d d d| j D} t d|jd| |dd| j|f||d|} g} | D] \}}| | qrtdd| D}|dkrtdt| }|dr| d|d}d dd| D|_d |_|jdkrtjntj|_t|j_|rt}||_||j_| s|d|_ t!t"|ddkrt!t"|d |_#d!|vs|dkr||_$d|_%i|_&|S)"a Perform an in-place decompression of a dataset with a compressed *Transfer Syntax UID*. .. versionadded:: 3.0 .. 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 uncompressed 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. Parameters ---------- ds : pydicom.dataset.Dataset A dataset containing compressed *Pixel Data* to be decoded and the corresponding *Image Pixel* module elements, along with a :attr:`~pydicom.dataset.FileDataset.file_meta` attribute containing a suitable (0002,0010) *Transfer Syntax UID*. as_rgb : bool, optional 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. For information on the available plugins for each decoder see the :doc:`API documentation`. kwargs : dict[str, Any], optional Optional keyword parameters for the decoding plugin may also be present. See the :doc:`decoding plugins options ` for more information. Returns ------- pydicom.dataset.Dataset The dataset `ds` decompressed in-place. r get_decoderr7zKUnable to decompress as the dataset has no (7FE0,0010) 'Pixel Data' elementrurgr zUnable to determine the initial compression state as there's no (0002,0010) 'Transfer Syntax UID' element in the dataset's 'file_meta' attributez#The dataset is already uncompresseduse_pdhFrcSrrr!r?r!r!r%r4rzdecompress..z-Unable to decompress as the plugins for the 'z(' decoder are all missing dependencies: indexN)rrcsr;r<rr"framer!r!r%rAGrBzdecompress..rzUnable to decompress as the length of the uncompressed pixel data will be greater than the maximum allowed by the DICOM StandardrWcss|]}|VqdSr<r!rr!r!r%rATsr9r(r'rr)NumberOfFrames)'rrrtrsrrrconvert_pixel_data pixel_arraytobytesrrrrrr iter_arrayappendrrxrr BitsAllocatedrrOWrrurgrrrPhotometricInterpretationr r>PlanarConfigurationrrr)r}rrrr_rrur|rrframesdecoderrframe_generatorr image_pixel value_lengthrrrr!r!r% decompresss C         rsrcc Cs|d}t|dd}t|}|d}|d}t|D]l}|d||d|}|d||d|} |d||d||d||d|<||d||d|<| |d||d|<|d||d||d||d|<||d||d|<| |d ||d|<qt|S) aReturn ``YBR_FULL_422`` data expanded to ``YBR_FULL``. Uncompressed datasets with a (0028,0004) *Photometric Interpretation* of ``"YBR_FULL_422"`` are subsampled in the horizontal direction by halving the number of Cb and Cr pixels (i.e. there are two Y pixels for every Cb and Cr pixel). This function expands the ``YBR_FULL_422`` data to remove the subsampling and the output is therefore ``YBR_FULL``. Parameters ---------- src : bytes or bytearray The YBR_FULL_422 pixel data to be expanded. bits_allocated : int The number of bits used to store each pixel, as given by (0028,0100) *Bits Allocated*. Returns ------- bytes The expanded data (as YBR_FULL). r9rWrroNrr)rx bytearrayrangerD) rr-n_bytesrYdststep_srcstep_dstiic_bc_rr!r!r% expand_ybr422os ((rrDunitcCstt|j}tt|j}tt|j}tt|j}|||}|t|9}|dkr*|S|dkr9|d|ddk}n||d9}|jdkrJ|dd}|S)aReturn the expected length (in terms of bytes or pixels) of the *Pixel Data*. +------------------------------------------------+-------------+ | Element | Required or | +-------------+---------------------------+------+ optional | | Tag | Keyword | Type | | +=============+===========================+======+=============+ | (0028,0002) | SamplesPerPixel | 1 | Required | +-------------+---------------------------+------+-------------+ | (0028,0004) | PhotometricInterpretation | 1 | Required | +-------------+---------------------------+------+-------------+ | (0028,0008) | NumberOfFrames | 1C | Optional | +-------------+---------------------------+------+-------------+ | (0028,0010) | Rows | 1 | Required | +-------------+---------------------------+------+-------------+ | (0028,0011) | Columns | 1 | Required | +-------------+---------------------------+------+-------------+ | (0028,0100) | BitsAllocated | 1 | Required | +-------------+---------------------------+------+-------------+ Parameters ---------- ds : Dataset The :class:`~pydicom.dataset.Dataset` containing the Image Pixel module and *Pixel Data*. unit : str, optional If ``'bytes'`` then returns the expected length of the *Pixel Data* in whole bytes and NOT including an odd length trailing NULL padding byte. If ``'pixels'`` then returns the expected length of the *Pixel Data* in terms of the total number of pixels (default ``'bytes'``). Returns ------- int The expected length of the *Pixel Data* in either whole bytes or pixels, excluding the NULL trailing padding byte for odd length data. pixelsrr9r YBR_FULL_422rrW)r r>RowsColumnsSamplesPerPixelr get_nr_framesr)r}rr+r,r'r-rYr!r!r%get_expected_lengths '        rcsgd}fdd|DS)aReturn a dict of the pixel data affecting element's :func:`id` values. +------------------------------------------------+ | Element | +-------------+---------------------------+------+ | Tag | Keyword | Type | +=============+===========================+======+ | (0028,0002) | SamplesPerPixel | 1 | +-------------+---------------------------+------+ | (0028,0004) | PhotometricInterpretation | 1 | +-------------+---------------------------+------+ | (0028,0006) | PlanarConfiguration | 1C | +-------------+---------------------------+------+ | (0028,0008) | NumberOfFrames | 1C | +-------------+---------------------------+------+ | (0028,0010) | Rows | 1 | +-------------+---------------------------+------+ | (0028,0011) | Columns | 1 | +-------------+---------------------------+------+ | (0028,0100) | BitsAllocated | 1 | +-------------+---------------------------+------+ | (0028,0101) | BitsStored | 1 | +-------------+---------------------------+------+ | (0028,0103) | PixelRepresentation | 1 | +-------------+---------------------------+------+ | (7FE0,0008) | FloatPixelData | 1C | +-------------+---------------------------+------+ | (7FE0,0009) | DoubleFloatPixelData | 1C | +-------------+---------------------------+------+ | (7FE0,0010) | PixelData | 1C | +-------------+---------------------------+------+ Parameters ---------- ds : Dataset The :class:`~pydicom.dataset.Dataset` containing the pixel data. Returns ------- dict A dict containing the :func:`id` values for the elements that affect the pixel data. ) rrrrrrr BitsStoredPixelRepresentationr5r6r7csi|] }|tt|dqSr<)idgetattr)r"kwrr!r%rFsz'get_image_pixel_ids..r!)r}keywordsr!rr%get_image_pixel_idss-r codestreamc Csd}ddi}|dr?d|d<t|}d}||kr?tj|||ddd }||d|d d kr7|d 7}n||7}||kszB|||d d krMiWS||d |ddkr\iWS||d}|d@ru|d@d|d<d|d<|WS|d|d<d|d<|WSttfyYiSw)aReturn a dict containing JPEG 2000 component parameters. .. versionadded:: 2.1 Parameters ---------- codestream : bytes The JPEG 2000 (ISO/IEC 15444-1) codestream to be parsed. Returns ------- dict A dict containing parameters for the first component sample in the JPEG 2000 `codestream`, or an empty dict if unable to parse the data. Available parameters are ``{"precision": int, "is_signed": bool}``. rjp2Fs jP T rorXrr9sjp2crWsOsQ*r precision is_signed) startswithrxr> from_bytes IndexError TypeError)roffsetinfo total_lengthrYssizr!r!r%get_j2k_parameterss<    r cCsi}z|dddkr|WSd}i}|||d}tvrPt||d|dd}|tvr>||d|d|||<||d7}|||d}tvs|rV||d<|d7}||d|d<t||d|dd|d <t||d|d d|d <||d |d <|d 7}g|d<t|d D]}|d|||d7}q|dkr|WS|||ddkr|t||d|ddd7}|||ddks|d||dd7}|||d<||d|d<W|StyiYSw)aReturn a dict containing JPEG or JPEG-LS encoding parameters. Parameters ---------- src : bytes The JPEG (ISO/IEC 10918-1) or JPEG-LS (ISO/IEC 14495-1) codestream to be parsed. Returns ------- dict[str, int | dict[bytes, bytes] | list[int]] A dict containing JPEG or JPEG-LS encoding parameters or an empty dict if unable to parse the data. Available parameters are: * ``precision``: int * ``height``: int * ``width``: int * ``components``: int * ``component_ids``: list[int] * ``app``: dict[bytes: bytes] * ``interleave_mode``: int, JPEG-LS only * ``lossy_error``: int, JPEG-LS only rrWsroapprrrheightwidth componentsr9 component_idsrVs lossy_errorrinterleave_mode)_SOF _UNPACK_SHORT_APPrrry)rrr app_markersmarkerrY_r!r!r%_get_jpg_parametersYsH     $  rwarncCs,t|dd}|s|rtd|dd}|S)aReturn NumberOfFrames or 1 if NumberOfFrames is None or 0. Parameters ---------- ds : dataset.Dataset The :class:`~pydicom.dataset.Dataset` containing the Image Pixel module corresponding to the data in `arr`. warn : bool If ``True`` (the default), a warning is issued if NumberOfFrames has an invalid value. Returns ------- int An integer for the NumberOfFrames or 1 if NumberOfFrames is None or 0 rrz A value of zg for (0028,0008) 'Number of Frames' is non-conformant. It's recommended that this value be changed to 1)rr)r}rrr!r!r%rs  r)ds_outr^indicesrawrz(str | PathLike[str] | BinaryIO | DatasetrzDataset | Nonerr np.ndarrayc ks$ddlm}ddlm}t||r_|} t| di} | dd} s&tdz|| } Wnty<td| j d wt | fi|} | j | f|d ||d | }|D]\}}|VqUdSt |d srt |jd d }|d}ntt|}|}|dt}|dur|rt|nt}|tBddhB}zit|t|fi|\} } t||r| j|_|j| j|j| j| d} z|| } Wntytd| j d w| j |f|d ||d | }|D]\}}|VqWt |d s|dS||dSt |d s |w||w)aYield decoded pixel data frames from `src` as :class:`~numpy.ndarray`. .. versionadded:: 3.0 .. warning:: This function requires `NumPy `_ and may require the installation of additional packages to perform the actual pixel data decompression. See the :doc:`pixel data decompression documentation ` for more information. **Memory Usage** To minimize memory usage `src` should be the path to the dataset or a `file-like object `_ containing the dataset. **Processing** The following processing operations on the raw pixel data are always 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. 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 -------- Read a DICOM dataset then iterate through all the pixel data frames:: from pydicom import dcmread from pydicom.pixels import iter_pixels ds = dcmread("path/to/dataset.dcm") for arr in iter_pixels(ds): print(arr.shape) Iterate through all the pixel data frames in a dataset while minimizing memory usage:: from pydicom.pixels import iter_pixels for arr in iter_pixels("path/to/dataset.dcm"): print(arr.shape) Iterate through the even frames for a dataset with 10 frames:: from pydicom.pixels import iter_pixels with open("path/to/dataset.dcm", "rb") as f: for arr in iter_pixels(f, indices=range(0, 10, 2)): print(arr.shape) Parameters ---------- src : str | PathLike[str] | file-like | pydicom.dataset.Dataset * :class:`str` | :class:`os.PathLike`: the path to a DICOM dataset containing pixel data, or * file-like: a `file-like object `_ in 'rb' mode containing the dataset. * :class:`~pydicom.dataset.Dataset`: a dataset instance ds_out : pydicom.dataset.Dataset, optional A :class:`~pydicom.dataset.Dataset` that will be updated with the non-retired group ``0x0028`` image pixel module elements and the group ``0x0002`` file meta information elements from the dataset in `src`. **Only available when `src` is a path or file-like.** specific_tags : list[int | pydicom.tag.BaseTag], optional A list of additional tags from the dataset in `src` to be added to the `ds_out` dataset. indices : Iterable[int] | None, optional If ``None`` (default) then iterate through the entire pixel data, otherwise only iterate through the frames specified by `indices`. raw : bool, optional If ``True`` then yield 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). 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. For information on the available plugins for each decoder see the :doc:`API documentation`. **kwargs Optional keyword parameters for controlling decoding are also available, please see the :doc:`decoding options documentation ` for more information. Yields ------- numpy.ndarray A single frame of decoded pixel data with shape: * (rows, columns) for single sample data * (rows, columns, samples) for multi-sample data A writeable :class:`~numpy.ndarray` is yielded by default. For native transfer syntaxes with ``view_only=True`` a read-only :class:`~numpy.ndarray` will be yielded. rrrrurgNmUnable to decode the pixel data as the dataset's 'file_meta' has no (0002,0010) 'Transfer Syntax UID' elementQUnable to decode the pixel data as a (0002,0010) 'Transfer Syntax UID' value of '' is not supportedT)rvalidaterrrwstrictrbr3r4rf)rrrrrrrsrtNotImplementedErrorrrvrrrresolveopenr r tellseek _DEFAULT_TAGSset _GROUP_0028rlistruset_original_encodingoriginal_encodingrrclose)rrr^rrrr_rrr}rur|rr~iteratorrrpathr] file_offsettagsr!r!r% iter_pixelss                    r6padcCs|jdkrdSt||tstdt|jdkr|}|jddr6t|t d|jdd}tj |ddd }| }|rRt|d rP|d S|S|S) afPack a binary :class:`numpy.ndarray` for use with *Pixel Data*. Should be used in conjunction with (0028,0100) *Bits Allocated* = 1. .. versionchanged:: 2.1 Added the `pad` keyword parameter and changed to allow `arr` to be 2 or 3D. Parameters ---------- arr : numpy.ndarray The :class:`numpy.ndarray` containing 1-bit data as ints. `arr` must only contain integer values of 0 and 1 and must have an 'uint' or 'int' :class:`numpy.dtype`. For the sake of efficiency it's recommended that the length of `arr` be a multiple of 8 (i.e. that any empty bit-padding to round out the byte has already been added). The input `arr` should either be shaped as (rows, columns) or (frames, rows, columns) or the equivalent 1D array used to ensure that the packed data is in the correct order. pad : bool, optional If ``True`` (default) then add a null byte to the end of the packed data to ensure even length, otherwise no padding will be added. Returns ------- bytes The bit packed data. Raises ------ ValueError If `arr` contains anything other than 0 or 1. References ---------- DICOM Standard, Part 5, :dcm:`Section 8.1.1` and :dcm:`Annex D` )rrz=Only binary arrays (containing ones or zeroes) can be packed.rrr9u1littlebitorderrWr) shapenp array_equalastypeboolrrxravelrzerospackbitsr)rr7packedr!r!r% pack_bitss ) rE package_nameminimum_version.c Cs^zt|d}tdd|jdD|kWSty.}z t|WYd}~dSd}~ww)zlReturn True if `package_name` is available and its version is greater or equal to `minimum_version` __version__csr;r<r=r[r!r!r%rArBz(_passes_version_check...NF) importlib import_moduletuplerHsplitryLOGGERdebug)rFrGmoduleexcr!r!r%_passes_version_checks  rR)rr^rrrrc Ksddlm}ddlm}t||rT|} t| di} | dd} s%tdz|| } Wnty;td| j d wt | fi|} | j | f|d ||d | dSt |d sgt |jd d }|d}ntt|}|}|dt}|dur|rt|nt}|tBddhB}zIt|t|fi|\} } | d} z|| } Wntytd| j d w| j |f|d ||d | \}}Wt |d s|n||nt |d s|w||wt||r| j|_|j| j|j| j|S)adReturn decoded pixel data from `src` as :class:`~numpy.ndarray`. .. versionadded:: 3.0 .. warning:: This function requires `NumPy `_ and may require the installation of additional packages to perform the actual pixel data decompression. See the :doc:`pixel data decompression documentation ` for more information. **Memory Usage** To minimize memory usage `src` should be the path to the dataset or a `file-like object `_ containing the dataset. **Processing** The following processing operations on the raw pixel data are always 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. 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 -------- Read a DICOM dataset and return the entire pixel data:: from pydicom import dcmread from pydicom.pixels import pixel_array ds = dcmread("path/to/dataset.dcm") arr = pixel_array(ds) Return the entire pixel data from a dataset while minimizing memory usage:: from pydicom.pixels import pixel_array arr = pixel_array("path/to/dataset.dcm") Return the 3rd frame of a dataset containing at least 3 frames while minimizing memory usage:: from pydicom.pixels import pixel_array with open("path/to/dataset.dcm", "rb") as f: arr = pixel_array(f, index=2) # 'index' starts at 0 Parameters ---------- src : str | PathLike[str] | file-like | pydicom.dataset.Dataset * :class:`str` | :class:`os.PathLike`: the path to a DICOM dataset containing pixel data, or * file-like: a `file-like object `_ in 'rb' mode containing the dataset. * :class:`~pydicom.dataset.Dataset`: a dataset instance ds_out : pydicom.dataset.Dataset, optional A :class:`~pydicom.dataset.Dataset` that will be updated with the non-retired group ``0x0028`` image pixel module elements and the group ``0x0002`` file meta information elements from the dataset in `src`. **Only available when `src` is a path or file-like.** specific_tags : list[int | pydicom.tag.BaseTag], optional A list of additional tags from the dataset in `src` to be added to the `ds_out` dataset. index : int | None, optional If ``None`` (default) then return an array containing all the frames in the pixel data, otherwise return only the frame from the specified `index`, which starts at 0 for the first frame. 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). 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 decoder see the :doc:`API documentation`. **kwargs Optional keyword parameters for controlling decoding, please see the :doc:`decoding options documentation` for more information. Returns ------- numpy.ndarray One or more frames of decoded pixel data with shape: * (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 A writeable :class:`~numpy.ndarray` is returned by default. For native transfer syntaxes with ``view_only=True`` a read-only :class:`~numpy.ndarray` will be returned. rrrrurgNrr r!T)rr"rrrwr#r%r3r4rf)rrrrrrrsrtr&rrvas_arrayrrr'r(r r r)r*r+r,r-rr.r1rur/r0rr)rrr^rrrr_rrr}rur|rr~r3r]r4r5rrr!r!r%rs                  ras_floatznp.dtypecCs tstdt|dr|jjd}n|jd}|dur&tdt|jd|sDt t |j }|dkr5d}n|dkrzRUnable to determine the data type to use to contain the Pixel Data as a value of 'z3' for '(0028,0103) Pixel Representation' is invalidfloatuint8r9z-' for '(0028,0100) Bits Allocated' is invalidzThe data type 'z<' needed to contain the Pixel Data is not supported by numpyr9S)HAVE_NP ImportErrorrru_tsyntax_encodingr0rttype__name__r r>rrrrr=dtyperr&r newbyteorder)r}rTri pixel_repr dtype_strr-r^r!r!r% pixel_dtypesV&        rbcCsNtstdt|}tt|j}|dkrtd|d|dkrA|jj}|dvr+d}n |dvr2d}n|j }|dvrAtd|d tt|j }tt|j }|dkr~|dkr^| |||}|S|dkrl| ||||}|S| ||||}| dd d d}|S|dkr| ||}|S|dkr| |||}|S| |||}| dd d}|S) aReturn a reshaped :class:`numpy.ndarray` `arr`. +------------------------------------------+-----------+----------+ | Element | Supported | | +-------------+---------------------+------+ values | | | Tag | Keyword | Type | | | +=============+=====================+======+===========+==========+ | (0028,0002) | SamplesPerPixel | 1 | N > 0 | Required | +-------------+---------------------+------+-----------+----------+ | (0028,0006) | PlanarConfiguration | 1C | 0, 1 | Optional | +-------------+---------------------+------+-----------+----------+ | (0028,0008) | NumberOfFrames | 1C | N > 0 | Optional | +-------------+---------------------+------+-----------+----------+ | (0028,0010) | Rows | 1 | N > 0 | Required | +-------------+---------------------+------+-----------+----------+ | (0028,0011) | Columns | 1 | N > 0 | Required | +-------------+---------------------+------+-----------+----------+ (0028,0008) *Number of Frames* is required when *Pixel Data* contains more than 1 frame. (0028,0006) *Planar Configuration* is required when (0028,0002) *Samples per Pixel* is greater than 1. For certain compressed transfer syntaxes it is always taken to be either 0 or 1 as shown in the table below. +---------------------------------------------+-----------------------+ | Transfer Syntax | Planar Configuration | +------------------------+--------------------+ | | UID | Name | | +========================+====================+=======================+ | 1.2.840.10008.1.2.4.50 | JPEG Baseline | 0 | +------------------------+--------------------+-----------------------+ | 1.2.840.10008.1.2.4.57 | JPEG Lossless, | 0 | | | Non-hierarchical | | +------------------------+--------------------+-----------------------+ | 1.2.840.10008.1.2.4.70 | JPEG Lossless, | 0 | | | Non-hierarchical, | | | | SV1 | | +------------------------+--------------------+-----------------------+ | 1.2.840.10008.1.2.4.80 | JPEG-LS Lossless | 0 | +------------------------+--------------------+-----------------------+ | 1.2.840.10008.1.2.4.81 | JPEG-LS Lossy | 0 | +------------------------+--------------------+-----------------------+ | 1.2.840.10008.1.2.4.90 | JPEG 2000 Lossless | 0 | +------------------------+--------------------+-----------------------+ | 1.2.840.10008.1.2.4.91 | JPEG 2000 Lossy | 0 | +------------------------+--------------------+-----------------------+ | 1.2.840.10008.1.2.5 | RLE Lossless | 1 | +------------------------+--------------------+-----------------------+ .. versionchanged:: 2.1 JPEG-LS transfer syntaxes changed to *Planar Configuration* of 0 Parameters ---------- ds : dataset.Dataset The :class:`~pydicom.dataset.Dataset` containing the Image Pixel module corresponding to the data in `arr`. arr : numpy.ndarray The 1D array containing the pixel data. Returns ------- numpy.ndarray A reshaped array containing the pixel data. The shape of the array depends on the contents of the dataset: * For single frame, single sample data (rows, columns) * For single frame, multi-sample data (rows, columns, samples) * For multi-frame, single sample data (frames, rows, columns) * For multi-frame, multi-sample data (frames, rows, columns, samples) References ---------- * DICOM Standard, Part 3, :dcm:`Annex C.7.6.3.1` * DICOM Standard, Part 5, :dcm:`Section 8.2` z-Numpy is required to reshape the pixel array.rz0Unable to reshape the pixel array as a value of z0 for (0028,0002) 'Samples per Pixel' is invalid.)z1.2.840.10008.1.2.4.50z1.2.840.10008.1.2.4.57z1.2.840.10008.1.2.4.70z1.2.840.10008.1.2.4.80z1.2.840.10008.1.2.4.81z1.2.840.10008.1.2.4.90z1.2.840.10008.1.2.4.91r)z1.2.840.10008.1.2.5)rrz3 for (0028,0006) 'Planar Configuration' is invalid.rWr)rYrZrr r>rrrurgrrrreshape transpose)r}rr nr_samplestransfer_syntaxr)r+r,r!r!r%reshape_pixel_array:sTP       rg)rc Csddlm}ddlm}|dd}s|dd}r-td|jd|jd |jd t|d s6||_ |j d d}|rK|j sKt d |jdi} |j |j |j} } } | jdvsb| jdvrjtd| d|jd|jd|jd|jd|jd|jdi} z| |}Wntytd|dw|dkr| dvrtd|d| | dkrd| dfnd| d<d| dkr| dn| df| d<d| dkr| dn| df| d<nN| d vrtd|d!| | d"|krtd|d#| | dkrdnd| df| d<d| dkr | dn| df| d<d| dkr| dn| df| d<d|kr2| jd$ksBntd%|d&|jjd$d||}}| jd'krSdnd|d }| jd'krfd|dnd|dd}||ksx||krtd(|d)|d*|d)|d+ d|f| d,<|dkrd-nd| d.<d|f| d/<d| jd$f| d0<d|f| d1<d|df| d2<d| jd'krdndf| d3<| D]!\}\}}|dkrt|||q|d4kr||vr||=q||jkr3|}tj|j dd| d5}|ddd6|ddd7<|ddd6|ddd7<|ddd6|ddd7<|ddd6|ddd7<|}|!}t"|ddkrB|nd8#|d9f|_$|d:}|j%d$krWt&j'nt&j(|_&d;|_)d|_*i|_+|rk|j,rot-|j _.|r~t/}||_0||j _1dSdS)` module elements values will be added, updated or removed as necessary: * (0028,0002) *Samples per Pixel* using a value corresponding to `photometric_interpretation`. * (0028,0004) *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 ---------- ds : pydicom.dataset.Dataset The little endian encoded dataset to be modified. arr : np.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`. rr)riNi zThe dataset has an existing z 'zv' element which indicates the (0008,0016) 'SOP Class UID' value is not suitable for a dataset with 'Pixel Data'. The 'z<' element should be deleted and the 'SOP Class UID' changed.rurgzThe dataset's transfer syntax 'z'' is big-endian, which is not supported)ui)rrWzUnsupported ndarray dtype 'z'', must be int8, int16, uint8 or uint16rrz0Unsupported 'photometric_interpretation' value '')rWrzAn ndarray with 'z(' data must have 2 or 3 dimensions, not +)-NrrrWr)rroz(' data must have 3 or 4 dimensions, not rzM' data must have shape (rows, columns, 3) or (frames, rows, columns, 3), not r9zInvalid 'bits_stored' value 'zc', must be greater than 0 and less than or equal to the number of bits for the ndarray's itemsize 'rhz$The range of values in the ndarray [z, z;] is greater than that allowed by the 'bits_stored' value []r)rkrrrrrHighBitrrlr^rrorrr7F)2rrpydicom.pixels.commonrrsrtrrrrurir&r<ndimr^kinditemsizer MONOCHROME1 MONOCHROME2 PALETTE_COLORRGBYBR_FULLrKeyErrorminmaxrsetattrrAr=emptysizerrxrr7rrrrrrrrrrgrrr)r}rr(r.rrPIrr|changesr<rqr^interpretationsre actual_min actual_max allowed_min allowed_maxkeyword operationroutrrr!r!r%set_pixel_datas =         " ""  &     & rrSznp.ndarray | bytescCsNtrtj|dd}tj|dd}|r|S|S|rtddttj |S)aUnpack the bit-packed data in `src`. Suitable for use when (0028,0011) *Bits Allocated* or (60xx,0100) *Overlay Bits Allocated* is 1. If `NumPy `_ is available then it will be used to unpack the data, otherwise only the standard library will be used, which is about 20 times slower. .. versionchanged:: 2.3 Added the `as_array` keyword parameter, support for unpacking without NumPy, and added :class:`bytes` as a possible return type Parameters ---------- src : bytes The bit-packed data. as_array : bool, optional If ``False`` then return the unpacked data as :class:`bytes`, otherwise return a :class:`numpy.ndarray` (default, requires NumPy). Returns ------- bytes or numpy.ndarray The unpacked data as an :class:`numpy.ndarray` (if NumPy is available and ``as_array == True``) or :class:`bytes` otherwise. Raises ------ ValueError If `as_array` is ``True`` and NumPy is not available. References ---------- DICOM Standard, Part 5, :dcm:`Section 8.1.1` and :dcm:`Annex D` r8ror9r:z1unpack_bits() requires NumPy if 'as_array = True'r) rYr= frombuffer unpackbitsrrrmaprH __getitem__)rrSrr!r!r% unpack_bitss(rr<)rD)T)F)r}rrrr`r)W__doc__collections.abcrrrrJloggingpathlibrstructrrsysr typingr r r r numpyr=rYrZpydicom.charsetrpydicom._dicom_dictrpydicom.encapsrr pydicom.miscr pydicom.tagr pydicom.uidrrrrrpydicom.valuereprosrrr getLoggerr]rNrr-rkeysr+r{rrHdictr>rD__annotations__rrrr.rLrrrvr@rVrrrrrr rrr6rErRrrbrgrrr!r!r!r%sj               ZA    g ,B?=g"  UB  O j M