Deprecate pixel_data_handlers.util (#2037)

* Deprecate pixel_data_handlers.util

* Move tests to pixels

* Add tests for deprecation

* Documentation pass

doc/conf.py

@@ -94,9 +94,9 @@
 # intersphinx configuration
 intersphinx_mapping = {
     "python": (f"https://docs.python.org/{sys.version_info.major}", None),
-    "numpy": ("https://docs.scipy.org/doc/numpy/", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
-    "matplotlib": ("https://matplotlib.org", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
 }
 
 sphinx_gallery_conf = {

doc/guides/encoding/jpeg_2k.rst

@@ -24,8 +24,8 @@ Valid Image Pixel Parameters
 ----------------------------
 
 The table below lists the valid :dcm:`Image Pixel<part03/sect_C.7.6.3.html>`
-module parameters for *Pixel Data* encoded using *JPEG 2000 Lossless* or *JPEG 2000*
-encoding. For an explanation of each parameter and its relationship
+module parameters for *Pixel Data* encoded using the *JPEG 2000 Lossless* or *JPEG 2000*
+transfer syntaxes. For an explanation of each parameter and its relationship
 with the *Pixel Data* see the :doc:`glossary of Image Pixel elements<../glossary>`.
 
 +------------+-----------------------+-----------------+----------------+------------+---------+

doc/guides/encoding/jpeg_ls.rst

@@ -12,8 +12,8 @@ Valid Image Pixel Parameters
 ----------------------------
 
 The table below lists the valid :dcm:`Image Pixel<part03/sect_C.7.6.3.html>`
-module parameters for *Pixel Data* encoded using *JPEG-LS Lossless* or *JPEG-LS
-Near-lossless* encoding. For an explanation of each parameter and its relationship
+module parameters for *Pixel Data* encoded using the *JPEG-LS Lossless* or *JPEG-LS
+Near-lossless* transfer syntaxes. For an explanation of each parameter and its relationship
 with the *Pixel Data* see the :doc:`glossary of Image Pixel elements<../glossary>`.
 
 +------------+-----------------------+-----------------+----------------+------------+---------+
@@ -100,7 +100,7 @@ pixel data should already be in the corresponding color space:
 
     * For *Bits Allocated* and *Bits Stored* less than or equal to 8: pixel
       data must be :func:`converted into YCbCr color space
-      <pydicom.pixel_data_handlers.convert_color_space>`. However
+      <pydicom.pixels.processing.convert_color_space>`. However
       you should keep in mind that the conversion operation is lossy.
     * For *Bits Allocated* and *Bits Stored* between 9 and 16 (inclusive):
       pixel data should be downscaled to 8-bit (with *Bits Stored*, *Bits
@@ -113,7 +113,7 @@ pixel data should already be in the corresponding color space:
 
   * For *Photometric Interpretation* ``RGB`` the pixel data must first be
     :func:`converted into RGB color space
-    <pydicom.pixel_data_handlers.convert_color_space>`. However the conversion
+    <pydicom.pixels.processing.convert_color_space>`. However the conversion
     operation is lossy.
   * For *Photometric Interpretation* ``YBR_FULL`` nothing else is required.
 

doc/guides/encoding/rle_lossless.rst

@@ -12,8 +12,8 @@ Valid Image Pixel Parameters
 ----------------------------
 
 The table below lists the valid :dcm:`Image Pixel<part03/sect_C.7.6.3.html>`
-module parameters for *Pixel Data* encoded using *RLE Lossless* encoding. For
-an explanation of each parameter and its relationship with the
+module parameters for *Pixel Data* encoded using the *RLE Lossless* transfer
+syntax. For an explanation of each parameter and its relationship with the
 *Pixel Data* see the :doc:`glossary of Image Pixel elements<../glossary>`.
 
 +------------+-----------------+-----------------+------------+---------+
@@ -55,7 +55,7 @@ corresponding color space:
 
     * For *Bits Allocated* and *Bits Stored* less than or equal to 8: pixel
       data must be :func:`converted into YCbCr color space
-      <pydicom.pixel_data_handlers.convert_color_space>`. However
+      <pydicom.pixels.processing.convert_color_space>`. However
       you should keep in mind that the conversion operation is lossy.
     * For *Bits Allocated* and *Bits Stored* between 9 and 16 (inclusive):
       pixel data should be downscaled to 8-bit (with *Bits Stored*, *Bits
@@ -68,7 +68,7 @@ corresponding color space:
 
   * For *Photometric Interpretation* ``RGB`` the pixel data must first be
     :func:`converted into RGB color space
-    <pydicom.pixel_data_handlers.convert_color_space>`. However the conversion
+    <pydicom.pixels.processing.convert_color_space>`. However the conversion
     operation is lossy.
   * For *Photometric Interpretation* ``YBR_FULL`` nothing else is required.
 
@@ -153,7 +153,7 @@ new *SOP Instance UID*:
 .. code-block:: python
 
     >>> from pydicom import examples
-    >>> from pydicom.pixel_data_handlers import convert_color_space
+    >>> from pydicom.pixels import convert_color_space
     >>> from pydicom.uid import generate_uid
     >>> ds = examples.rgb_color
     >>> rgb = ds.pixel_array

doc/old/image_data_compression.rst

@@ -121,7 +121,7 @@ Compressing using third-party packages
 
 If you need to perform pixel data compression using an encoding method not
 supported by *pydicom* - such as :dcm:`ISO/IEC 10918-1 JPEG
-<part05/sect_8.2.html#sect_8.2.1> - then you'll need to find a third-party
+<part05/sect_8.2.html#sect_8.2.1>` - then you'll need to find a third-party
 package or application to do so. Once you've done that you have to follow the
 requirements for compressed *Pixel Data* in the DICOM Standard:
 

doc/old/working_with_overlays.rst

@@ -68,7 +68,7 @@ overlay pixels start 1 row above and 1 row to the left of the image pixels.
 
 NumPy can be used to modify the pixels, but if the changes are to be saved,
 they must be bit-packed (using something like
-:func:`~pydicom.pixel_data_handlers.numpy_handler.pack_bits`) and written
+:func:`~pydicom.pixels.utils.pack_bits`) and written
 back to the correct element:
 
 .. code-block:: python
@@ -77,7 +77,7 @@ back to the correct element:
   arr[10, :] = 1
 
   # Pack the data
-  from pydicom.pixel_data_handlers.numpy_handler import pack_bits
+  from pydicom.pixels import pack_bits
   packed_bytes = pack_bits(arr)
 
   # Update the element value

doc/old/working_with_pixel_data.rst

@@ -127,7 +127,7 @@ of ``3`` then the returned pixel data will be in the color space as given by
 
 *pydicom* offers a limited ability to convert between 8-bits/channel YBR and
 RGB color spaces through the
-:func:`~pydicom.pixel_data_handlers.util.convert_color_space`
+:func:`~pydicom.pixels.processing.convert_color_space`
 function. When changing the color space you should also change the value
 of *Photometric Interpretation* to match.
 
@@ -144,13 +144,13 @@ Some DICOM datasets store their output image pixel values in a lookup table
 (LUT), where the values in *Pixel Data* are the index to a corresponding
 LUT entry. When a dataset's (0028,0004) *Photometric Interpretation* value is
 ``PALETTE COLOR`` then the
-:func:`~pydicom.pixel_data_handlers.util.apply_color_lut` function can be used
+:func:`~pydicom.pixels.processing.apply_color_lut` function can be used
 to apply a palette color LUT to the pixel data to produce an RGB image.
 
 .. code-block:: python
 
     from pydicom import examples
-    from pydicom.pixel_data_handlers.util import apply_color_lut
+    from pydicom.pixels import apply_color_lut
 
     # Fetch an example PALETTE COLOR dataset
     ds = examples.palette_color
@@ -165,7 +165,7 @@ of the pixel data is 8-bit.
 .. code-block:: python
 
     from pydicom import examples
-    from pydicom.pixel_data_handlers.util import apply_color_lut
+    from pydicom.pixels import apply_color_lut
 
     ds = examples.palette_color
     arr = ds.pixel_array
@@ -186,7 +186,7 @@ Modality LUT or Rescale Operation
 The DICOM :dcm:`Modality LUT<part03/sect_C.11.html#sect_C.11.1>` module
 converts raw pixel data values to a specific (possibly unitless) physical
 quantity, such as Hounsfield units for CT. The
-:func:`~pydicom.pixel_data_handlers.util.apply_modality_lut` function can be
+:func:`~pydicom.pixels.processing.apply_modality_lut` function can be
 used with an input array of raw values and a dataset containing a Modality LUT
 module to return the converted values. When a dataset requires multiple
 grayscale transformations, the Modality LUT transformation is always applied
@@ -195,7 +195,7 @@ first.
 .. code-block:: python
 
     from pydicom import examples
-    from pydicom.pixel_data_handlers.util import apply_modality_lut
+    from pydicom.pixels import apply_modality_lut
 
     ds = examples.ct
     arr = ds.pixel_array
@@ -207,7 +207,7 @@ VOI LUT or Windowing Operation
 
 The DICOM :dcm:`VOI LUT<part03/sect_C.11.2.html>` module applies a
 VOI or windowing operation to input values. The
-:func:`~pydicom.pixel_data_handlers.util.apply_voi_lut` function
+:func:`~pydicom.pixels.processing.apply_voi_lut` function
 can be used with an input array and a dataset containing a VOI LUT module to
 return values with applied VOI LUT or windowing. When a dataset contains
 multiple VOI or windowing views then a particular view can be returned by
@@ -219,7 +219,7 @@ that the modality LUT or rescale operation has already been applied.
 .. code-block:: python
 
     from pydicom import examples
-    from pydicom.pixel_data_handlers.util import apply_voi_lut
+    from pydicom.pixels import apply_voi_lut
 
     ds = examples.overlay
     arr = ds.pixel_array

doc/reference/encaps.rst

@@ -3,6 +3,7 @@
 Bulk Data Encapsulation Utilities (:mod:`pydicom.encaps`)
 =========================================================
 
+.. module:: pydicom.encaps
 .. currentmodule:: pydicom.encaps
 
 Functions for parsing and applying encapsulation to bulk data elements such

doc/reference/handlers.pixel_data.rst

@@ -3,6 +3,11 @@
 Pixel Data Handlers (:mod:`pydicom.pixel_data_handlers`)
 ========================================================
 
+.. deprecated:: 3.0
+
+    The ``pydicom.pixel_data_handlers`` module is deprecated and will be removed
+    in v4.0. Use the :mod:`~pydicom.pixels` module instead.
+
 .. currentmodule:: pydicom.pixel_data_handlers
 
 .. autosummary::

doc/reference/handlers.rst

@@ -3,29 +3,15 @@
 Bulk Data Handlers
 ==================
 
+.. deprecated:: 3.0
+
+    The ``pydicom.pixel_data_handlers`` module is deprecated and will be removed
+    in v4.0. Use the :mod:`~pydicom.pixels` module instead.
+
 Functions for handling bulk data elements such as (7FE0,0010) *Pixel Data*
 
 .. toctree::
    :maxdepth: 1
    :includehidden:
 
    handlers.pixel_data
-
-Pixel Data Utilities
-====================
-
-Functions for manipulating (7FE0,0010) *Pixel Data*.
-
-.. currentmodule:: pydicom.pixel_data_handlers
-
-.. autosummary::
-   :toctree: generated/
-
-   apply_color_lut
-   apply_modality_lut
-   apply_rescale
-   apply_windowing
-   apply_voi
-   apply_voi_lut
-   convert_color_space
-   util

doc/reference/pixels.decoders.rst

@@ -3,11 +3,13 @@
 Pixel Data Decoders (:mod:`pydicom.pixels.decoders`)
 ====================================================
 
+.. module:: pydicom.pixels.decoders
+
 :class:`~pydicom.pixels.decoders.base.Decoder` class instances for decoding
 native and compressed (7FE0,0010) *Pixel Data*, (7FE0,0008) *Float Pixel Data* and
-(7FE0,0009) *Double Float Pixel Data*
+(7FE0,0009) *Double Float Pixel Data*.
 
-.. currentmodule:: pydicom.pixels.decoders.base
+.. currentmodule:: pydicom.pixels.decoders
 
 .. autosummary::
    :toctree: generated/
@@ -32,6 +34,8 @@ native and compressed (7FE0,0010) *Pixel Data*, (7FE0,0008) *Float Pixel Data* a
 
 Base decoder classes used by all decoders
 
+.. currentmodule:: pydicom.pixels.decoders.base
+
 .. autosummary::
    :toctree: generated/
 

doc/reference/pixels.encoders.rst

@@ -3,10 +3,12 @@
 Pixel Data Encoders (:mod:`pydicom.pixels.encoders`)
 ====================================================
 
+.. module:: pydicom.pixels.encoders
+
 :class:`~pydicom.pixels.encoders.base.Encoder` class instances for compressing
 (7FE0,0010) *Pixel Data*.
 
-.. currentmodule:: pydicom.pixels.encoders.base
+.. currentmodule:: pydicom.pixels.encoders
 
 .. autosummary::
    :toctree: generated/

doc/reference/pixels.processing.rst

@@ -0,0 +1,20 @@
+.. _api_pixel_processing:
+
+Pixel Data Processing (:mod:`pydicom.pixels.processing`)
+========================================================
+
+Functions for applying image processing to pixel data.
+
+.. module:: pydicom.pixels.processing
+.. currentmodule:: pydicom.pixels.processing
+
+.. autosummary::
+   :toctree: generated/
+
+   apply_color_lut
+   apply_modality_lut
+   apply_rescale
+   apply_voi_lut
+   apply_voi
+   apply_windowing
+   convert_color_space

doc/reference/pixels.rst

@@ -3,43 +3,45 @@
 Pixel Data (:mod:`pydicom.pixels`)
 ==================================
 
-Functions for handling bulk data elements such as(7FE0,0010) *Pixel Data*,
-(7FE0,0008) *Float Pixel Data* and (7FE0,0009) *Double Float Pixel Data*
-
-Pixel Data Decoding
--------------------
-
+.. module:: pydicom.pixels
 .. currentmodule:: pydicom.pixels
 
-.. toctree::
-   :maxdepth: 1
-   :includehidden:
-
-   pixels.decoders
-
 
-Pixel Data Encoding
--------------------
+Image processing functions
 
-.. currentmodule:: pydicom.pixels
-
-.. toctree::
-   :maxdepth: 1
-   :includehidden:
-
-   pixels.encoders
+.. autosummary::
+  :toctree: generated/
 
+   apply_color_lut
+   apply_modality_lut
+   apply_voi_lut
+   apply_voi
+   apply_windowing
+   convert_color_space
 
-Pixel Data Utilities
---------------------
 
-.. currentmodule:: pydicom.pixels
+Utility functions
 
 .. autosummary::
    :toctree: generated/
 
+   as_pixel_options
    get_decoder
    get_encoder
-   pixel_array
    iter_pixels
-   as_pixel_options
+   pack_bits
+   pixel_array
+   unpack_bits
+
+
+Sub-modules
+-----------
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   pixels.decoders
+   pixels.encoders
+   pixels.processing
+   pixels.utils