man/chunk.rst

.. $URL$
.. $Rev$

PNG: Chunk by Chunk
===================

The PNG specification defines 18 chunk types.  This document is intended
to help users who are interested in a particular PNG chunk type.  If you
have a particular PNG chunk type in mind, you can look here to see what
support PyPNG provides for it.

Critical Chunks
---------------

``IHDR``
^^^^^^^^

Generated automatically by PyPNG.  The ``IHDR`` chunk specifies image
size, colour model, bit depth, and interlacing.  All possible
(valid) combinations can be produced with suitable arguments to the
:meth:`png.Writer` class.

``PLTE``
^^^^^^^^

Correctly handled when a PNG image is read.  Can be generated for a
colour type 3 image by using the ``palette`` argument to the
:meth:`png.Writer` class.  PNG images with colour types other than 3 can
also have a ``PLTE`` chunk (a suggested palette); it is not currently
possible to add a ``PLTE`` chunk for these images using PyPNG.

``IDAT``
^^^^^^^^

Generated automatically from the pixel data presented to PyPNG.
Multiple ``IDAT`` chunks (of bounded size) can be generated by using
``chunk_limit`` argument to the :meth:`png.Writer` class.

``IEND``
^^^^^^^^

Generated automatically.


Ancillary Chunks
----------------

``tRNS``
^^^^^^^^

Generated for most colour types when the ``transparent`` argument is
supplied to the :meth:`png.Writer` to specify a transparent colour.  For
colour type 3, colour mapped images, a ``tRNS`` chunk will be generated
automatically from the ``palette`` argument when a palette with alpha
(opacity) values is supplied.

``cHRM``
^^^^^^^^

Ignored when reading.  Not generated.

``gAMA``
^^^^^^^^

When reading a PNG image the ``gAMA`` chunk is converted to a floating
point gamma value; this value is returned in the ``info`` dictionary:
``info['gamma']``.  When writing, the ``gamma`` argument to the
:meth:`png.Writer` class will generate a ``gAMA`` chunk.

``iCCP``
^^^^^^^^

Ignored when reading.  Not generated.

``sBIT``
^^^^^^^^

When reading a PNG image the ``sBIT`` chunk will make PyPNG rescale the
pixel values so that they all have the width implied by the ``sBIT``
chunk.  It is possible for a PNG image to have an ``sBIT`` chunk that
specifies 3 different values for the significant bits in each of the 3
colour channels.  In this case PyPNG only uses the largest value.  When
writing a PNG image, an ``sBIT`` chunk will be generated if need
according to the ``bitdepth`` argument specified.  Values other than 1,
2, 4, 8, or 16 will generate an ``sBIT`` chunk, as will values less than
8 for images with more than one plane.

``sRGB``
^^^^^^^^

Ignored when reading.  Not generated.

``tEXt``
^^^^^^^^

Ignored when reading.  Not generated.

``zTXt``
^^^^^^^^

Ignored when reading.  Not generated.

``iTXt``
^^^^^^^^

Ignored when reading.  Not generated.

``bKGD``
^^^^^^^^

When a PNG image is read, a ``bKGD`` chunk will add the ``background``
key to the ``info`` dictionary.  When writing a PNG image, a ``bKGD``
chunk will be generated when the ``background`` argument is used.

``hIST``
^^^^^^^^

Ignored when reading.  Not generated.

``pHYs``
^^^^^^^^

When a PNG image is read, a ``pHYs`` chunk will add the ``physical`` key to
the ``info`` dictionary. When writing a PNG image, a ``pHYs`` chunk will
be generated if ``x_pixels_per_unit`` and ``y_pixels_per_unit`` is not ``None``
(default: ``None``).

``sPLT``
^^^^^^^^

Ignored when reading.  Not generated.

``tIME``
^^^^^^^^

Ignored when reading.  Not generated.

Non-standard Chunks
-------------------

Generally it is not possible to generate PNG images with any other chunk
types.  When reading a PNG image, processing it using the chunk
interface, ``png.Reader.chunks``, will allow any chunk to be processed
(by user code).