# pydicom.pixel_data_handlers.util

Utility functions used in the pixel data handlers.

Functions

`apply_color_lut`(arr[, ds, palette]) | Apply a color palette lookup table to arr.
`apply_modality_lut`(arr, ds) | Apply a modality lookup table or rescale operation to arr.
`apply_voi_lut`(arr, ds[, index]) | Apply a VOI lookup table or windowing operation to arr.
`convert_color_space`(arr, current, desired) | Convert the image(s) in arr from one color space to another.
`dtype_corrected_for_endianness`(…) | Return a `numpy.dtype` corrected for system and `Dataset` endianness.
`get_expected_length`(ds[, unit]) | Return the expected length (in terms of bytes or pixels) of the Pixel Data.
`get_image_pixel_ids`(ds) | Return a dict of the pixel data affecting element’s `id()` values.
`pixel_dtype`(ds[, as_float]) | Return a `numpy.dtype` for the pixel data in ds.
`reshape_pixel_array`(ds, arr) | Return a reshaped `numpy.ndarray` arr.

`pydicom.pixel_data_handlers.util.``apply_color_lut`(arr, ds=None, palette=None)

  Apply a color palette lookup table to arr.

  New in version 1.4.

  If (0028,1201-1203) Palette Color Lookup Table Data are missing then (0028,1221-1223) Segmented Palette Color Lookup Table Data must be present and vice versa. The presence of (0028,1204) Alpha Palette Color Lookup Table Data or (0028,1224) Alpha Segmented Palette Color Lookup Table Data is optional.

  Use of this function with the Enhanced Palette Color Lookup Table Module or Supplemental Palette Color LUT Module is not currently supported.

  Parameters:

  - arr (numpy.ndarray) – The pixel data to apply the color palette to.
  - ds (dataset.Dataset, optional) – Required if palette is not supplied. A `Dataset` containing a suitable Image Pixel or Palette Color Lookup Table Module.
  - palette (str or uid.UID, optional) – Required if ds is not supplied. The name of one of the well-known color palettes defined by the DICOM Standard. One of: `'HOT_IRON'`, `'PET'`, `'HOT_METAL_BLUE'`, `'PET_20_STEP'`, `'SPRING'`, `'SUMMER'`, `'FALL'`, `'WINTER'` or the corresponding well-known (0008,0018) SOP Instance UID.

  Returns: | The RGB or RGBA pixel data as an array of `np.uint8` or `np.uint16` values, depending on the 3rd value of (0028,1201) Red Palette Color Lookup Table Descriptor.
  Return type: | numpy.ndarray

  References

  - Image Pixel Module
  - Supplemental Palette Color LUT Module
  - Enhanced Palette Color LUT Module
  - Palette Colour LUT Module
  - Supplemental Palette Color LUTs

`pydicom.pixel_data_handlers.util.``apply_modality_lut`(arr, ds)

  Apply a modality lookup table or rescale operation to arr.

  New in version 1.4.

  Parameters:

  - arr (numpy.ndarray) – The `ndarray` to apply the modality LUT or rescale operation to.
  - ds (dataset.Dataset) – A dataset containing a Modality LUT Module.

  Returns: | An array with applied modality LUT or rescale operation. If (0028,3000) Modality LUT Sequence is present then returns an array of `np.uint8` or `np.uint16`, depending on the 3rd value of (0028,3002) LUT Descriptor. If (0028,1052) Rescale Intercept and (0028,1053) Rescale Slope are present then returns an array of `np.float64`. If neither are present then arr will be returned unchanged.
  Return type: | numpy.ndarray

  Notes

  When Rescale Slope and Rescale Intercept are used, the output range is from (min. pixel value * Rescale Slope + Rescale Intercept) to (max. pixel value * Rescale Slope + Rescale Intercept), where min. and max. pixel value are determined from (0028,0101) Bits Stored and (0028,0103) Pixel Representation.

  References

  - DICOM Standard, Part 3, Annex C.11.1
  - DICOM Standard, Part 4, Annex N.2.1.1

`pydicom.pixel_data_handlers.util.``apply_voi_lut`(arr, ds, index=0)

  Apply a VOI lookup table or windowing operation to arr.

  New in version 1.4.

  Parameters:

  - arr (numpy.ndarray) – The `ndarray` to apply the VOI LUT or windowing operation to.
  - ds (dataset.Dataset) – A dataset containing a VOI LUT Module. If (0028,3010) VOI LUT Sequence is present then returns an array of `np.uint8` or `np.uint16`, depending on the 3rd value of (0028,3002) LUT Descriptor. If (0028,1050) Window Center and (0028,1051) Window Width are present then returns an array of `np.float64`. If neither are present then arr will be returned unchanged.
  - index (int, optional) – Where the VOI LUT Module contains multiple possible views, this is the index of the view to return (default `0`).

  Returns: | An array with applied VOI LUT or windowing operation.
  Return type: | numpy.ndarray

  Notes

  When the dataset requires a modality LUT or rescale operation as part of the Modality LUT module then that must be applied before any windowing operation.

  See also

  `apply_modality_lut()`

  References

  - DICOM Standard, Part 3, Annex C.11.2
  - DICOM Standard, Part 3, Annex C.8.11.3.1.5
  - DICOM Standard, Part 4, Annex N.2.1.1

`pydicom.pixel_data_handlers.util.``convert_color_space`(arr, current, desired)

  Convert the image(s) in arr from one color space to another.

  Changed in version 1.4: Added support for `YBR_FULL_422`

  Parameters:

  - arr (numpy.ndarray) – The image(s) as a `numpy.ndarray` with `shape` (frames, rows, columns, 3) or (rows, columns, 3).
  - current (str) – The current color space, should be a valid value for (0028,0004) Photometric Interpretation. One of `'RGB'`, `'YBR_FULL'`, `'YBR_FULL_422'`.
  - desired (str) – The desired color space, should be a valid value for (0028,0004) Photometric Interpretation. One of `'RGB'`, `'YBR_FULL'`, `'YBR_FULL_422'`.

  Returns: | The image(s) converted to the desired color space.
  Return type: | numpy.ndarray

  References

  - DICOM Standard, Part 3, Annex C.7.6.3.1.2
  - ISO/IEC 10918-5:2012 (ITU T.871), Section 7

`pydicom.pixel_data_handlers.util.``dtype_corrected_for_endianness`(is_little_endian, numpy_dtype)

  Return a `numpy.dtype` corrected for system and `Dataset` endianness.

  Parameters:

  - is_little_endian (bool) – The endianess of the affected `Dataset`.
  - numpy_dtype (numpy.dtype) – The numpy data type used for the Pixel Data without considering endianess.

  Raises: | `ValueError` – If is_little_endian is `None`, e.g. not initialized.
  Returns: | The numpy data type used for the Pixel Data without considering endianess.
  Return type: | numpy.dtype

`pydicom.pixel_data_handlers.util.``get_expected_length`(ds, unit='bytes')

  Return 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

  Changed in version 1.4: Added support for a Photometric Interpretation of `YBR_FULL_422`

  Parameters:

  - ds (Dataset) – The `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: | The expected length of the Pixel Data in either whole bytes or pixels, excluding the NULL trailing padding byte for odd length data.
  Return type: | int

`pydicom.pixel_data_handlers.util.``get_image_pixel_ids`(ds)

  Return a dict of the pixel data affecting element’s `id()` values.

  New in version 1.4.

  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 `Dataset` containing the pixel data.
  Returns: | A dict containing the `id()` values for the elements that affect the pixel data.
  Return type: | dict

`pydicom.pixel_data_handlers.util.``pixel_dtype`(ds, as_float=False)

  Return a `numpy.dtype` for the pixel data in ds.

  Suitable for use with IODs containing the Image Pixel module (with `as_float=False`) and the Floating Point Image Pixel and Double Floating Point Image Pixel modules (with `as_float=True`).

  Element | Supported values
  --- | ---
  Tag | Keyword | Type
  (0028,0101) | BitsAllocated | 1 | 1, 8, 16, 32, 64
  (0028,0103) | PixelRepresentation | 1 | 0, 1

  Changed in version 1.4: Added as_float keyword parameter and support for float dtypes.

  Parameters:

  - ds (Dataset) – The `Dataset` containing the pixel data you wish to get the data type for.
  - as_float (bool, optional) – If `True` then return a float dtype, otherwise return an integer dtype (default `False`). Float dtypes are only supported when (0028,0101) Bits Allocated is 32 or 64.

  Returns: | A `numpy.dtype` suitable for containing the pixel data.
  Return type: | numpy.dtype
  Raises: | `NotImplementedError` – If the pixel data is of a type that isn’t supported by either numpy or pydicom.

`pydicom.pixel_data_handlers.util.``reshape_pixel_array`(ds, arr)

  Return a reshaped `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, Non-hierarchical | 0
  1.2.840.10008.1.2.4.70 | JPEG Lossless, Non-hierarchical, SV1 | 0
  1.2.840.10008.1.2.4.80 | JPEG-LS Lossless | 1
  1.2.840.10008.1.2.4.81 | JPEG-LS Lossy | 1
  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

  Parameters:

  - ds (dataset.Dataset) – The `Dataset` containing the Image Pixel module corresponding to the data in arr.
  - arr (numpy.ndarray) – The 1D array containing the pixel data.

  Returns:

  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, planes)
  - For multi-frame, single sample data (frames, rows, columns)
  - For multi-frame, multi-sample data (frames, rows, columns, planes)

  Return type: | numpy.ndarray

  References

  - DICOM Standard, Part 3, Annex C.7.6.3.1
  - DICOM Standard, Part 5, Section 8.2