avif: Add format and installation documentation

docs/handbook/image-file-formats.rst

@@ -125,7 +125,7 @@ following options are available::
 **append_images**
     A list of images to append as additional frames. Each of the
     images in the list can be single or multiframe images.
-    This is currently supported for GIF, PDF, PNG, TIFF, and WebP.
+    This is currently supported for GIF, PDF, PNG, TIFF, WebP, and AVIF.
 
     It is also supported for ICO and ICNS. If images are passed in of relevant
     sizes, they will be used instead of scaling down the main image.
@@ -999,6 +999,72 @@ XBM
 
 Pillow reads and writes X bitmap files (mode ``1``).
 
+AVIF
+^^^^
+
+Pillow reads and writes AVIF files, including AVIF sequence images. Currently,
+it is only possible to save 8-bit AVIF images, and all AVIF images are decoded
+as 8-bit RGB(A).
+
+The :py:meth:`~PIL.Image.Image.save` method supports the following options:
+
+**quality**
+    Integer, 1-100, Defaults to 90. 0 gives the smallest size and poorest
+    quality, 100 the largest and best quality. The value of this setting
+    controls the ``qmin`` and ``qmax`` encoder options.
+
+**qmin** / **qmax**
+    Integer, 0-63. The quality of images created by an AVIF encoder are
+    controlled by minimum and maximum quantizer values. The higher these
+    values are, the worse the quality.
+
+**subsampling**
+    If present, sets the subsampling for the encoder. Defaults to ``"4:2:0``".
+    Options include:
+
+    * ``"4:0:0"``
+    * ``"4:2:0"``
+    * ``"4:2:2"``
+    * ``"4:4:4"``
+
+**speed**
+    Quality/speed trade-off (0=slower-better, 10=fastest). Defaults to 8.
+
+**range**
+    YUV range, either "full" or "limited." Defaults to "full"
+
+**codec**
+    AV1 codec to use for encoding. Possible values are "aom", "rav1e", and
+    "svt", depending on what codecs were compiled with libavif. Defaults to
+    "auto", which will choose the first available codec in the order of the
+    preceding list.
+
+**icc_profile**
+    The ICC Profile to include in the saved file.
+
+**exif**
+    The exif data to include in the saved file.
+
+**xmp**
+    The XMP data to include in the saved file.
+
+Saving sequences
+~~~~~~~~~~~~~~~~~
+
+When calling :py:meth:`~PIL.Image.Image.save` to write an AVIF file, by default
+only the first frame of a multiframe image will be saved. If the ``save_all``
+argument is present and true, then all frames will be saved, and the following
+options will also be available.
+
+**append_images**
+    A list of images to append as additional frames. Each of the
+    images in the list can be single or multiframe images.
+
+**duration**
+    The display duration of each frame, in milliseconds. Pass a single
+    integer for a constant duration, or a list or tuple to set the
+    duration for each frame separately.
+
 Read-only formats
 -----------------
 

docs/installation.rst

@@ -196,6 +196,15 @@ Many of Pillow's features require external libraries:
     is available if all the libraries are installed.
   * Windows support: Raqm is not included in prebuilt wheels
 
+* **libavif** provides support for the AVIF format.
+
+  * Pillow requires libavif version **0.8.0** or greater, which is when
+    AVIF image sequence support was added.
+  * libavif is merely an API that wraps AVIF codecs. If you are compiling
+    libavif from source, you will also need to install both an AVIF encoder
+    and decoder, such as rav1e and dav1d, or libaom, which both encodes and
+    decodes AVIF images.
+
 * **libxcb** provides X11 screengrab support.
 
 Once you have installed the prerequisites, run::
@@ -231,14 +240,14 @@ Build Options
 * Build flags: ``--disable-zlib``, ``--disable-jpeg``,
   ``--disable-tiff``, ``--disable-freetype``, ``--disable-lcms``,
   ``--disable-webp``, ``--disable-webpmux``, ``--disable-jpeg2000``,
-  ``--disable-imagequant``, ``--disable-xcb``.
+  ``--disable-imagequant``, ``--disable-xcb``, ``--disable-avif``.
   Disable building the corresponding feature even if the development
   libraries are present on the building machine.
 
 * Build flags: ``--enable-zlib``, ``--enable-jpeg``,
   ``--enable-tiff``, ``--enable-freetype``, ``--enable-lcms``,
   ``--enable-webp``, ``--enable-webpmux``, ``--enable-jpeg2000``,
-  ``--enable-imagequant``, ``--enable-xcb``.
+  ``--enable-imagequant``, ``--enable-xcb``, ``--enable-avif``.
   Require that the corresponding feature is built. The build will raise
   an exception if the libraries are not found. Webpmux (WebP metadata)
   relies on WebP support. Tcl and Tk also must be used together.
@@ -283,6 +292,12 @@ To install libraqm on macOS use Homebrew to install its dependencies::
 
 Then see ``depends/install_raqm_cmake.sh`` to install libraqm.
 
+To install libavif on macOS use Homebrew to install its build dependencies::
+
+    brew install nasm ninja meson cmake
+
+Then see ``depends/install_libavif.sh`` to install libavif.
+
 Now install Pillow with::
 
     python3 -m pip install --upgrade pip
@@ -328,7 +343,8 @@ Prerequisites are installed on **MSYS2 MinGW 64-bit** with::
         mingw-w64-x86_64-libwebp \
         mingw-w64-x86_64-openjpeg2 \
         mingw-w64-x86_64-libimagequant \
-        mingw-w64-x86_64-libraqm
+        mingw-w64-x86_64-libraqm \
+        mingw-w64-x86_64-libavif
 
 Now install Pillow with::
 
@@ -345,11 +361,11 @@ Make sure you have Python's development libraries installed::
 
     sudo pkg install python3
 
-Prerequisites are installed on **FreeBSD 10 or 11** with::
+Prerequisites are installed on **FreeBSD 11 or 12** with::
 
-    sudo pkg install jpeg-turbo tiff webp lcms2 freetype2 openjpeg harfbuzz fribidi libxcb
+    sudo pkg install jpeg-turbo tiff webp lcms2 freetype2 openjpeg harfbuzz fribidi libxcb libavif
 
-Then see ``depends/install_raqm_cmake.sh`` to install libraqm.
+See ``depends/install_raqm_cmake.sh`` to install libraqm.
 
 
 Building on Linux
@@ -374,7 +390,14 @@ Prerequisites for **Ubuntu 16.04 LTS - 20.04 LTS** are installed with::
         libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk \
         libharfbuzz-dev libfribidi-dev libxcb1-dev
 
-Then see ``depends/install_raqm.sh`` to install libraqm.
+See ``depends/install_raqm.sh`` to install libraqm.
+
+Build prerequisites for libavif on Ubuntu are installed with::
+
+    sudo apt-get install cmake ninja-build nasm
+    sudo python3 -m pip install meson
+
+Then see ``depends/install_libavif.sh`` to build and install libavif.
 
 Prerequisites are installed on recent **Red Hat**, **CentOS** or **Fedora** with::
 

docs/reference/features.rst

@@ -21,6 +21,7 @@ Support for the following modules can be checked:
 * ``freetype2``: FreeType font support via :py:func:`PIL.ImageFont.truetype`.
 * ``littlecms2``: LittleCMS 2 support via :py:mod:`PIL.ImageCms`.
 * ``webp``: WebP image support.
+* ``avif``: AVIF image support.
 
 .. autofunction:: PIL.features.check_module
 .. autofunction:: PIL.features.version_module

docs/reference/plugins.rst

@@ -1,6 +1,14 @@
 Plugin reference
 ================
 
+:mod:`~PIL.AvifImagePlugin` Module
+----------------------------------
+
+.. automodule:: PIL.AvifImagePlugin
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 :mod:`~PIL.BmpImagePlugin` Module
 ---------------------------------
 

winbuild/build.rst

@@ -57,6 +57,7 @@ behaviour of ``build_prepare.py``:
 * ``--no-imagequant`` will skip GPL-licensed ``libimagequant`` optional dependency
 * ``--no-raqm`` will skip optional dependency Raqm (which itself depends on
   LGPL-licensed ``fribidi``).
+* ``--no-avif`` will skip the optional libavif dependency.
 * ``--python=<path>`` and ``--executable=<exe>`` override ``PYTHON`` and ``EXECUTABLE``.
 * ``--architecture=<arch>`` overrides ``ARCHITECTURE``.
 * ``--dir=<path>`` and ``--depends=<path>`` override ``PILLOW_BUILD``