Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sort formats alphabetically in documentation #22

Open
wants to merge 2 commits into
base: libavif-plugin
Choose a base branch
from
Open

Sort formats alphabetically in documentation #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
244c084
Sort formats alphabetically
radarhere Feb 15, 2025
1d6f6bd
Simplified code
radarhere Feb 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 80 additions & 80 deletions docs/handbook/image-file-formats.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,86 @@ present, and the :py:attr:`~PIL.Image.Image.format` attribute will be ``None``.
Fully supported formats
-----------------------

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, 0-100, defaults to 75. 0 gives the smallest size and poorest
quality, 100 the largest and best 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 6.

**max_threads**
Limit the number of active threads used. By default, there is no limit. If the aom
codec is used, there is a maximum of 64.

**range**
YUV range, either "full" or "limited". Defaults to "full"

**codec**
AV1 codec to use for encoding. Specific values are "aom", "rav1e", and
"svt", presuming the chosen codec is available. Defaults to "auto", which
will choose the first available codec in the order of the preceding list.

**tile_rows** / **tile_cols**
For tile encoding, the (log 2) number of tile rows and columns to use.
Valid values are 0-6, default 0. Ignored if "autotiling" is set to true in libavif
version **0.11.0** or greater.

**autotiling**
Split the image up to allow parallelization. Enabled automatically if "tile_rows"
and "tile_cols" both have their default values of zero. Requires libavif version
**0.11.0** or greater.

**alpha_premultiplied**
Encode the image with premultiplied alpha. Defaults to ``False``. Requires libavif
version **0.9.0** or greater.

**advanced**
Codec specific options. Requires libavif version **0.8.2** or greater.

**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.

BLP
^^^

Expand Down Expand Up @@ -1349,86 +1429,6 @@ 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, 0-100, defaults to 75. 0 gives the smallest size and poorest
quality, 100 the largest and best 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 6.

**max_threads**
Limit the number of active threads used. By default, there is no limit. If the aom
codec is used, there is a maximum of 64.

**range**
YUV range, either "full" or "limited". Defaults to "full"

**codec**
AV1 codec to use for encoding. Specific values are "aom", "rav1e", and
"svt", presuming the chosen codec is available. Defaults to "auto", which
will choose the first available codec in the order of the preceding list.

**tile_rows** / **tile_cols**
For tile encoding, the (log 2) number of tile rows and columns to use.
Valid values are 0-6, default 0. Ignored if "autotiling" is set to true in libavif
version **0.11.0** or greater.

**autotiling**
Split the image up to allow parallelization. Enabled automatically if "tile_rows"
and "tile_cols" both have their default values of zero. Requires libavif version
**0.11.0** or greater.

**alpha_premultiplied**
Encode the image with premultiplied alpha. Defaults to ``False``. Requires libavif
version **0.9.0** or greater.

**advanced**
Codec specific options. Requires libavif version **0.8.2** or greater.

**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
-----------------

Expand Down
10 changes: 4 additions & 6 deletions src/PIL/AvifImagePlugin.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,12 +77,10 @@ def _open(self) -> None:
)

# Get info from decoder
self._size, n_frames, mode, icc, exif, exif_orientation, xmp = (
self._size, self.n_frames, self._mode, icc, exif, exif_orientation, xmp = (
self._decoder.get_info()
)
self.n_frames = n_frames
self.is_animated = self.n_frames > 1
self._mode = mode

if icc:
self.info["icc_profile"] = icc
Expand All @@ -107,19 +105,19 @@ def seek(self, frame: int) -> None:
if not self._seek_check(frame):
return

# Set tile
self.__frame = frame
self.tile = [ImageFile._Tile("raw", (0, 0) + self.size, 0, self.mode)]

def load(self) -> Image.core.PixelAccess | None:
if self.tile:
# We need to load the image data for this frame
data, timescale, pts_in_timescales, dur_in_timescales = (
data, timescale, pts_in_timescales, duration_in_timescales = (
self._decoder.get_frame(self.__frame)
)
self.info["timestamp"] = round(1000 * (pts_in_timescales / timescale))
self.info["duration"] = round(1000 * (dur_in_timescales / timescale))
self.info["duration"] = round(1000 * (duration_in_timescales / timescale))

# Set tile
if self.fp and self._exclusive_fp:
self.fp.close()
self.fp = BytesIO(data)
Expand Down
Loading