Merge pull request #6868 from radarhere/filters

Refer to Resampling enum

docs/handbook/concepts.rst

@@ -148,44 +148,44 @@ pixel, the Python Imaging Library provides different resampling *filters*.
 
 .. py:currentmodule:: PIL.Image
 
-.. data:: NEAREST
+.. data:: Resampling.NEAREST
 
     Pick one nearest pixel from the input image. Ignore all other input pixels.
 
-.. data:: BOX
+.. data:: Resampling.BOX
 
     Each pixel of source image contributes to one pixel of the
     destination image with identical weights.
-    For upscaling is equivalent of :data:`NEAREST`.
+    For upscaling is equivalent of :data:`Resampling.NEAREST`.
     This filter can only be used with the :py:meth:`~PIL.Image.Image.resize`
     and :py:meth:`~PIL.Image.Image.thumbnail` methods.
 
     .. versionadded:: 3.4.0
 
-.. data:: BILINEAR
+.. data:: Resampling.BILINEAR
 
     For resize calculate the output pixel value using linear interpolation
     on all pixels that may contribute to the output value.
     For other transformations linear interpolation over a 2x2 environment
     in the input image is used.
 
-.. data:: HAMMING
+.. data:: Resampling.HAMMING
 
-    Produces a sharper image than :data:`BILINEAR`, doesn't have dislocations
+    Produces a sharper image than :data:`Resampling.BILINEAR`, doesn't have
-    on local level like with :data:`BOX`.
+    dislocations on local level like with :data:`Resampling.BOX`.
     This filter can only be used with the :py:meth:`~PIL.Image.Image.resize`
     and :py:meth:`~PIL.Image.Image.thumbnail` methods.
 
     .. versionadded:: 3.4.0
 
-.. data:: BICUBIC
+.. data:: Resampling.BICUBIC
 
     For resize calculate the output pixel value using cubic interpolation
     on all pixels that may contribute to the output value.
     For other transformations cubic interpolation over a 4x4 environment
     in the input image is used.
 
-.. data:: LANCZOS
+.. data:: Resampling.LANCZOS
 
     Calculate the output pixel value using a high-quality Lanczos filter (a
     truncated sinc) on all pixels that may contribute to the output value.
@@ -198,19 +198,19 @@ pixel, the Python Imaging Library provides different resampling *filters*.
 Filters comparison table
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-+----------------+-------------+-----------+-------------+
++---------------------------+-------------+-----------+-------------+
-| Filter         | Downscaling | Upscaling | Performance |
+| Filter                    | Downscaling | Upscaling | Performance |
-|                | quality     | quality   |             |
+|                           | quality     | quality   |             |
-+================+=============+===========+=============+
++===========================+=============+===========+=============+
-|:data:`NEAREST` |             |           | ⭐⭐⭐⭐⭐  |
+|:data:`Resampling.NEAREST` |             |           | ⭐⭐⭐⭐⭐  |
-+----------------+-------------+-----------+-------------+
++---------------------------+-------------+-----------+-------------+
-|:data:`BOX`     | ⭐          |           | ⭐⭐⭐⭐    |
+|:data:`Resampling.BOX`     | ⭐          |           | ⭐⭐⭐⭐    |
-+----------------+-------------+-----------+-------------+
++---------------------------+-------------+-----------+-------------+
-|:data:`BILINEAR`| ⭐          | ⭐        | ⭐⭐⭐      |
+|:data:`Resampling.BILINEAR`| ⭐          | ⭐        | ⭐⭐⭐      |
-+----------------+-------------+-----------+-------------+
++---------------------------+-------------+-----------+-------------+
-|:data:`HAMMING` | ⭐⭐        |           | ⭐⭐⭐      |
+|:data:`Resampling.HAMMING` | ⭐⭐        |           | ⭐⭐⭐      |
-+----------------+-------------+-----------+-------------+
++---------------------------+-------------+-----------+-------------+
-|:data:`BICUBIC` | ⭐⭐⭐      | ⭐⭐⭐    | ⭐⭐        |
+|:data:`Resampling.BICUBIC` | ⭐⭐⭐      | ⭐⭐⭐    | ⭐⭐        |
-+----------------+-------------+-----------+-------------+
++---------------------------+-------------+-----------+-------------+
-|:data:`LANCZOS` | ⭐⭐⭐⭐    | ⭐⭐⭐⭐  | ⭐          |
+|:data:`Resampling.LANCZOS` | ⭐⭐⭐⭐    | ⭐⭐⭐⭐  | ⭐          |
-+----------------+-------------+-----------+-------------+
++---------------------------+-------------+-----------+-------------+

docs/reference/Image.rst

@@ -430,6 +430,7 @@ See :ref:`concept-filters` for details.
 .. autoclass:: Resampling
     :members:
     :undoc-members:
+    :noindex:
 
 Some deprecated filters are also available under the following names:
 

docs/releasenotes/2.7.0.rst

@@ -29,84 +29,78 @@ Image resizing filters
 Image resizing methods :py:meth:`~PIL.Image.Image.resize` and
 :py:meth:`~PIL.Image.Image.thumbnail` take a ``resample`` argument, which tells
 which filter should be used for resampling. Possible values are:
-:py:data:`PIL.Image.NEAREST`, :py:data:`PIL.Image.BILINEAR`,
+``NEAREST``, ``BILINEAR``, ``BICUBIC`` and ``ANTIALIAS``. Almost all of them
-:py:data:`PIL.Image.BICUBIC` and :py:data:`PIL.Image.ANTIALIAS`.
+were changed in this version.
-Almost all of them were changed in this version.
 
 Bicubic and bilinear downscaling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-From the beginning :py:data:`~PIL.Image.BILINEAR` and
+From the beginning ``BILINEAR`` and ``BICUBIC`` filters were based on affine
-:py:data:`~PIL.Image.BICUBIC` filters were based on affine transformations
+transformations and used a fixed number of pixels from the source image for
-and used a fixed number of pixels from the source image for every destination
+every destination pixel (2x2 pixels for ``BILINEAR`` and 4x4 for ``BICUBIC``).
-pixel (2x2 pixels for :py:data:`~PIL.Image.BILINEAR` and 4x4 for
+This gave an unsatisfactory result for downscaling. At the same time, a high
-:py:data:`~PIL.Image.BICUBIC`). This gave an unsatisfactory result for
+quality convolutions-based algorithm with flexible kernel was used for
-downscaling. At the same time, a high quality convolutions-based algorithm with
+``ANTIALIAS`` filter.
-flexible kernel was used for :py:data:`~PIL.Image.ANTIALIAS` filter.
 
 Starting from Pillow 2.7.0, a high quality convolutions-based algorithm is used
 for all of these three filters.
 
 If you have previously used any tricks to maintain quality when downscaling with
-:py:data:`~PIL.Image.BILINEAR` and :py:data:`~PIL.Image.BICUBIC` filters
+``BILINEAR`` and ``BICUBIC`` filters (for example, reducing within several
-(for example, reducing within several steps), they are unnecessary now.
+steps), they are unnecessary now.
 
 Antialias renamed to Lanczos
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-A new :py:data:`PIL.Image.LANCZOS` constant was added instead of
+A new ``LANCZOS`` constant was added instead of ``ANTIALIAS``.
-:py:data:`~PIL.Image.ANTIALIAS`.
 
-When :py:data:`~PIL.Image.ANTIALIAS` was initially added, it was the only
+When ``ANTIALIAS`` was initially added, it was the only high-quality filter
-high-quality filter based on convolutions. It's name was supposed to reflect
+based on convolutions. It's name was supposed to reflect this. Starting from
-this. Starting from Pillow 2.7.0 all resize method are based on convolutions.
+Pillow 2.7.0 all resize method are based on convolutions. All of them are
-All of them are antialias from now on. And the real name of the
+antialias from now on. And the real name of the ``ANTIALIAS`` filter is Lanczos
-:py:data:`~PIL.Image.ANTIALIAS` filter is Lanczos filter.
+filter.
 
-The :py:data:`~PIL.Image.ANTIALIAS` constant is left for backward compatibility
+The ``ANTIALIAS`` constant is left for backward compatibility and is an alias
-and is an alias for :py:data:`~PIL.Image.LANCZOS`.
+for ``LANCZOS``.
 
 Lanczos upscaling quality
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The image upscaling quality with :py:data:`~PIL.Image.LANCZOS` filter was
+The image upscaling quality with ``LANCZOS`` filter was almost the same as
-almost the same as :py:data:`~PIL.Image.BILINEAR` due to bug. This has been fixed.
+``BILINEAR`` due to a bug. This has been fixed.
 
 Bicubic upscaling quality
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The :py:data:`~PIL.Image.BICUBIC` filter for affine transformations produced
+The ``BICUBIC`` filter for affine transformations produced sharp, slightly
-sharp, slightly pixelated image for upscaling. Bicubic for convolutions is
+pixelated image for upscaling. Bicubic for convolutions is more soft.
-more soft.
 
 Resize performance
 ^^^^^^^^^^^^^^^^^^
 
 In most cases, convolution is more a expensive algorithm for downscaling
 because it takes into account all the pixels of source image. Therefore
-:py:data:`~PIL.Image.BILINEAR` and :py:data:`~PIL.Image.BICUBIC` filters'
+``BILINEAR`` and ``BICUBIC`` filters' performance can be lower than before.
-performance can be lower than before. On the other hand the quality of
+On the other hand the quality of ``BILINEAR`` and ``BICUBIC`` was close to
-:py:data:`~PIL.Image.BILINEAR` and :py:data:`~PIL.Image.BICUBIC` was close to
+``NEAREST``. So if such quality is suitable for your tasks you can switch to
-:py:data:`~PIL.Image.NEAREST`. So if such quality is suitable for your tasks
+``NEAREST`` filter for downscaling, which will give a huge improvement in
-you can switch to :py:data:`~PIL.Image.NEAREST` filter for downscaling,
+performance.
-which will give a huge improvement in performance.
 
 At the same time performance of convolution resampling for downscaling has been
 improved by around a factor of two compared to the previous version.
-The upscaling performance of the :py:data:`~PIL.Image.LANCZOS` filter has
+The upscaling performance of the ``LANCZOS`` filter has remained the same. For
-remained the same. For :py:data:`~PIL.Image.BILINEAR` filter it has improved by
+``BILINEAR`` filter it has improved by 1.5 times and for ``BICUBIC`` by four
-1.5 times and for :py:data:`~PIL.Image.BICUBIC` by four times.
+times.
 
 Default filter for thumbnails
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In Pillow 2.5 the default filter for :py:meth:`~PIL.Image.Image.thumbnail` was
-changed from :py:data:`~PIL.Image.NEAREST` to :py:data:`~PIL.Image.ANTIALIAS`.
+changed from ``NEAREST`` to ``ANTIALIAS``. Antialias was chosen because all the
-Antialias was chosen because all the other filters gave poor quality for
+other filters gave poor quality for reduction. Starting from Pillow 2.7.0,
-reduction. Starting from Pillow 2.7.0, :py:data:`~PIL.Image.ANTIALIAS` has been
+``ANTIALIAS`` has been replaced with ``BICUBIC``, because it's faster and
-replaced with :py:data:`~PIL.Image.BICUBIC`, because it's faster and
+``ANTIALIAS`` doesn't give any advantages after downscaling with libjpeg, which
-:py:data:`~PIL.Image.ANTIALIAS` doesn't give any advantages after
+uses supersampling internally, not convolutions.
-downscaling with libjpeg, which uses supersampling internally, not convolutions.
 
 Image transposition
 -------------------

src/PIL/ImageOps.py

@@ -248,7 +248,8 @@ def contain(image, size, method=Image.Resampling.BICUBIC):
     :param size: The requested output size in pixels, given as a
                  (width, height) tuple.
     :param method: Resampling method to use. Default is
-                   :py:attr:`PIL.Image.BICUBIC`. See :ref:`concept-filters`.
+                   :py:attr:`~PIL.Image.Resampling.BICUBIC`.
+                   See :ref:`concept-filters`.
     :return: An image.
     """
 
@@ -276,7 +277,8 @@ def pad(image, size, method=Image.Resampling.BICUBIC, color=None, centering=(0.5
     :param size: The requested output size in pixels, given as a
                  (width, height) tuple.
     :param method: Resampling method to use. Default is
-                   :py:attr:`PIL.Image.BICUBIC`. See :ref:`concept-filters`.
+                   :py:attr:`~PIL.Image.Resampling.BICUBIC`.
+                   See :ref:`concept-filters`.
     :param color: The background color of the padded image.
     :param centering: Control the position of the original image within the
                       padded version.
@@ -328,7 +330,8 @@ def scale(image, factor, resample=Image.Resampling.BICUBIC):
     :param image: The image to rescale.
     :param factor: The expansion factor, as a float.
     :param resample: Resampling method to use. Default is
-                     :py:attr:`PIL.Image.BICUBIC`. See :ref:`concept-filters`.
+                     :py:attr:`~PIL.Image.Resampling.BICUBIC`.
+                     See :ref:`concept-filters`.
     :returns: An :py:class:`~PIL.Image.Image` object.
     """
     if factor == 1:
@@ -425,7 +428,8 @@ def fit(image, size, method=Image.Resampling.BICUBIC, bleed=0.0, centering=(0.5,
     :param size: The requested output size in pixels, given as a
                  (width, height) tuple.
     :param method: Resampling method to use. Default is
-                   :py:attr:`PIL.Image.BICUBIC`. See :ref:`concept-filters`.
+                   :py:attr:`~PIL.Image.Resampling.BICUBIC`.
+                   See :ref:`concept-filters`.
     :param bleed: Remove a border around the outside of the image from all
                   four edges. The value is a decimal percentage (use 0.01 for
                   one percent). The default value is 0 (no border).