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
ornp.uint16
values, depending on the 3rd value of (0028,1201) Red Palette Color Lookup Table Descriptor.Return type: numpy.ndarray
References
-
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
ornp.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 ofnp.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
- arr (numpy.ndarray) – The
-
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
ornp.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 ofnp.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
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
- arr (numpy.ndarray) – The
-
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
withshape
(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
- arr (numpy.ndarray) – The image(s) as a
-
pydicom.pixel_data_handlers.util.
dtype_corrected_for_endianness
(is_little_endian, numpy_dtype)¶ Return a
numpy.dtype
corrected for system andDataset
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 isNone
, e.g. not initialized.Returns: The numpy data type used for the Pixel Data without considering endianess.
Return type: numpy.dtype
- is_little_endian (bool) – The endianess of the affected
-
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
- ds (Dataset) – The
-
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 (withas_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: 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
- ds (dataset.Dataset) – The