.. $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. PyPNG supports all valid combinations, except for interlacing. The PNG spec has only 2 values for interlacing and has done for years: no interlacing, and Adam7. PyPNG supports either option when reading a PNG file, but when writing only supports no interlacing. Versions released prior to 2024 did support interlaced writing, if you want to poke about in the archives. ``PLTE`` ^^^^^^^^ Correctly handled when a PNG image is read. For writing, use the ``palette`` argument to the :meth:`png.Writer` class. This can work with PNG colour type 3 (palette required), and other colour types (palette optional). ``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`` ^^^^^^^^ When writing, 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. When reading will be processed into the alpha channel (if the appropriate method is used). ``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. Note that there is no code to adjust the pixel values for gamma. Your code has to do that, if you want it. ``iCCP`` ^^^^^^^^ International Color Consortium Profile. Ignored when reading. Not generated. The supported ``prichunkpng`` command line tool can add an ``iCCP`` chunk; and the not so supported ``iccp.py`` script can extract one from a PNG file and display one in "readable" format. The not so supported ``mkiccp.py`` script can make certain ICC Profiles. ``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``. The default is to not write this chunk. ``sPLT`` ^^^^^^^^ Ignored when reading. Not generated. ``tIME`` ^^^^^^^^ Ignored when reading. Not generated. Non-standard Chunks ------------------- Generally it is not possible using PyPNG 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).