From 4a70bc1150653e3e27c99ba92b178a51a76fc995 Mon Sep 17 00:00:00 2001 From: Frankie Dintino Date: Sun, 21 Feb 2021 09:39:28 -0500 Subject: [PATCH] avif: Add format and installation documentation --- docs/handbook/image-file-formats.rst | 68 +++++++++++++++++++++++++++- docs/installation.rst | 37 ++++++++++++--- docs/reference/features.rst | 1 + docs/reference/plugins.rst | 8 ++++ winbuild/build.rst | 1 + 5 files changed, 107 insertions(+), 8 deletions(-) diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst index 35c4177aab1..014293c83d3 100644 --- a/docs/handbook/image-file-formats.rst +++ b/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 ----------------- diff --git a/docs/installation.rst b/docs/installation.rst index 9693e2f4a22..db0ad5b2303 100644 --- a/docs/installation.rst +++ b/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:: diff --git a/docs/reference/features.rst b/docs/reference/features.rst index dd218fa0e70..a4eff035850 100644 --- a/docs/reference/features.rst +++ b/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 diff --git a/docs/reference/plugins.rst b/docs/reference/plugins.rst index 7094f87846c..6fe36b1c4f2 100644 --- a/docs/reference/plugins.rst +++ b/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 --------------------------------- diff --git a/winbuild/build.rst b/winbuild/build.rst index cd4a45e87b7..f79d7e07b22 100644 --- a/winbuild/build.rst +++ b/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=`` and ``--executable=`` override ``PYTHON`` and ``EXECUTABLE``. * ``--architecture=`` overrides ``ARCHITECTURE``. * ``--dir=`` and ``--depends=`` override ``PILLOW_BUILD``