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

Jump to bottom

Added headings before listing options #6632

Merged
merged 1 commit into from
Oct 2, 2022
Merged

Added headings before listing options #6632

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
109 changes: 104 additions & 5 deletions docs/handbook/image-file-formats.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ BLP is the Blizzard Mipmap Format, a texture format used in World of
Warcraft. Pillow supports reading ``JPEG`` Compressed or raw ``BLP1``
images, and all types of ``BLP2`` images.

Saving
~~~~~~

Pillow supports writing BLP images. The :py:meth:`~PIL.Image.Image.save` method
can take the following keyword arguments:

Expand All @@ -46,6 +49,9 @@ or ``RGB`` data. 16-colour images are read as ``P`` images. 4-bit run-length enc
is not supported. Support for reading 8-bit run-length encoding was added in Pillow
9.1.0.

Opening
~~~~~~~

The :py:meth:`~PIL.Image.open` method sets the following
:py:attr:`~PIL.Image.Image.info` properties:

Expand Down Expand Up @@ -78,6 +84,9 @@ EPS images. The EPS driver can read EPS images in ``L``, ``LAB``, ``RGB`` and
than leaving them in the original color space. The EPS driver can write images
in ``L``, ``RGB`` and ``CMYK`` modes.

Loading
~~~~~~~

If Ghostscript is available, you can call the :py:meth:`~PIL.Image.Image.load`
method with the following parameters to affect how Ghostscript renders the EPS

Expand Down Expand Up @@ -134,6 +143,11 @@ To restore the default behavior, where ``P`` mode images are only converted to
from PIL import GifImagePlugin
GifImagePlugin.LOADING_STRATEGY = GifImagePlugin.LoadingStrategy.RGB_AFTER_FIRST

.. _gif-opening:

Opening
~~~~~~~

The :py:meth:`~PIL.Image.open` method sets the following
:py:attr:`~PIL.Image.Image.info` properties:

Expand Down Expand Up @@ -171,6 +185,8 @@ to seek to the next frame (``im.seek(im.tell() + 1)``).

``im.seek()`` raises an :py:exc:`EOFError` if you try to seek after the last frame.

.. _gif-saving:

Saving
~~~~~~

Expand Down Expand Up @@ -278,6 +294,11 @@ sets the following :py:attr:`~PIL.Image.Image.info` property:
ask for ``(512, 512, 2)``, the final value of
:py:attr:`~PIL.Image.Image.size` will be ``(1024, 1024)``).

.. _icns-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:

**append_images**
Expand All @@ -292,6 +313,11 @@ ICO

ICO is used to store icons on Windows. The largest available icon is read.

.. _ico-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method supports the following options:

**sizes**
Expand Down Expand Up @@ -337,6 +363,11 @@ their original size while loading them.
By default Pillow doesn't allow loading of truncated JPEG files, set
:data:`.ImageFile.LOAD_TRUNCATED_IMAGES` to override this.

.. _jpeg-opening:

Opening
~~~~~~~

The :py:meth:`~PIL.Image.open` method may set the following
:py:attr:`~PIL.Image.Image.info` properties if available:

Expand Down Expand Up @@ -383,6 +414,10 @@ The :py:meth:`~PIL.Image.open` method may set the following

.. versionadded:: 7.1.0

.. _jpeg-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method supports the following options:

Expand Down Expand Up @@ -464,6 +499,11 @@ itself. It is also possible to set ``reduce`` to the number of resolutions to
discard (each one reduces the size of the resulting image by a factor of 2),
and ``layers`` to specify the number of quality layers to load.

.. _jpeg-2000-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method supports the following options:

**offset**
Expand Down Expand Up @@ -575,6 +615,11 @@ called.
By default Pillow doesn't allow loading of truncated PNG files, set
:data:`.ImageFile.LOAD_TRUNCATED_IMAGES` to override this.

.. _png-opening:

Opening
~~~~~~~

The :py:func:`~PIL.Image.open` function sets the following
:py:attr:`~PIL.Image.Image.info` properties, when appropriate:

Expand Down Expand Up @@ -613,6 +658,11 @@ decompression bombs. Additionally, the total size of all of the text
chunks is limited to :data:`.PngImagePlugin.MAX_TEXT_MEMORY`, defaulting to
64MB.

.. _png-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method supports the following options:

**optimize**
Expand Down Expand Up @@ -803,6 +853,11 @@ Pillow also reads SPIDER stack files containing sequences of SPIDER images. The
:py:meth:`~PIL.Image.Image.seek` and :py:meth:`~PIL.Image.Image.tell` methods are supported, and
random access is allowed.

.. _spider-opening:

Opening
~~~~~~~

The :py:meth:`~PIL.Image.open` method sets the following attributes:

**format**
Expand All @@ -819,8 +874,10 @@ is provided for converting floating point data to byte data (mode ``L``)::

im = Image.open("image001.spi").convert2byte()

Writing files in SPIDER format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _spider-saving:

Saving
~~~~~~

The extension of SPIDER files may be any 3 alphanumeric characters. Therefore
the output format must be specified explicitly::
Expand All @@ -837,6 +894,11 @@ Pillow reads and writes TGA images containing ``L``, ``LA``, ``P``,
``RGB``, and ``RGBA`` data. Pillow can read and write both uncompressed and
run-length encoded TGAs.

.. _tga-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:

**compression**
Expand Down Expand Up @@ -871,6 +933,11 @@ uncompressed files.
support for reading Packbits, LZW and JPEG compressed TIFFs
without using libtiff.

.. _tiff-opening:

Opening
~~~~~~~

The :py:meth:`~PIL.Image.open` method sets the following
:py:attr:`~PIL.Image.Image.info` properties:

Expand Down Expand Up @@ -922,8 +989,10 @@ and can be accessed in any order.
``im.seek()`` raises an :py:exc:`EOFError` if you try to seek after the
last frame.

Saving Tiff Images
~~~~~~~~~~~~~~~~~~
.. _tiff-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:

Expand Down Expand Up @@ -1035,6 +1104,11 @@ WebP
Pillow reads and writes WebP files. The specifics of Pillow's capabilities with
this format are currently undocumented.

.. _webp-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method supports the following options:

**lossless**
Expand All @@ -1058,7 +1132,7 @@ The :py:meth:`~PIL.Image.Image.save` method supports the following options:
the system WebP library was built with webpmux support.

Saving sequences
~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~

.. note::

Expand Down Expand Up @@ -1173,6 +1247,11 @@ GBR

The GBR decoder reads GIMP brush files, version 1 and 2.

.. _gbr-opening:

Opening
~~~~~~~

The :py:meth:`~PIL.Image.open` method sets the following
:py:attr:`~PIL.Image.Image.info` properties:

Expand All @@ -1188,6 +1267,11 @@ GD
Pillow reads uncompressed GD2 files. Note that you must use
:py:func:`PIL.GdImageFile.open` to read such a file.

.. _gd-opening:

Opening
~~~~~~~

The :py:meth:`~PIL.Image.open` method sets the following
:py:attr:`~PIL.Image.Image.info` properties:

Expand Down Expand Up @@ -1227,6 +1311,11 @@ image when first opened. The :py:meth:`~PIL.Image.Image.seek` and :py:meth:`~PIL
methods may be used to read other pictures from the file. The pictures are
zero-indexed and random access is supported.

.. _mpo-saving:

Saving
~~~~~~

When calling :py:meth:`~PIL.Image.Image.save` to write an MPO 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
Expand Down Expand Up @@ -1326,6 +1415,11 @@ XPM

Pillow reads X pixmap files (mode ``P``) with 256 colors or less.

.. _xpm-opening:

Opening
~~~~~~~

The :py:meth:`~PIL.Image.open` method sets the following
:py:attr:`~PIL.Image.Image.info` properties:

Expand All @@ -1350,6 +1444,11 @@ Pillow can write PDF (Acrobat) images. Such images are written as binary PDF 1.4
files, using either JPEG or HEX encoding depending on the image mode (and
whether JPEG support is available or not).

.. _pdf-saving:

Saving
~~~~~~

The :py:meth:`~PIL.Image.Image.save` method can take the following keyword arguments:

**save_all**
Expand Down