The png Module¶
Pure Python PNG Reader/Writer
This Python module implements support for PNG images (see PNG
specification at http://www.w3.org/TR/2003/REC-PNG-20031110/ ). It reads
and writes PNG files with all allowable bit depths
(1/2/4/8/16/24/32/48/64 bits per pixel) and colour combinations:
greyscale (1/2/4/8/16 bit); RGB, RGBA, LA (greyscale with alpha) with
8/16 bits per channel; colour mapped images (1/2/4/8 bit).
Adam7 interlacing is supported for reading and
writing. A number of optional chunks can be specified (when writing)
and understood (when reading): tRNS
, bKGD
, gAMA
.
For help, type import png; help(png)
in your python interpreter.
A good place to start is the Reader
and Writer
classes.
Requires Python 2.3. Best with Python 2.6 and higher. Installation is
trivial, but see the README.txt
file (with the source distribution)
for details.
This file can also be used as a command-line utility to convert
Netpbm PNM files to PNG, and the
reverse conversion from PNG to PNM. The interface is similar to that
of the pnmtopng
program from Netpbm. Type python png.py --help
at the shell prompt for usage and a list of options.
A note on spelling and terminology¶
Generally British English spelling is used in the documentation. So that’s “greyscale” and “colour”. This not only matches the author’s native language, it’s also used by the PNG specification.
The major colour models supported by PNG (and hence by this module) are: greyscale, RGB, greyscale–alpha, RGB–alpha. These are sometimes referred to using the abbreviations: L, RGB, LA, RGBA. In this case each letter abbreviates a single channel: L is for Luminance or Luma or Lightness which is the channel used in greyscale images; R, G, B stand for Red, Green, Blue, the components of a colour image; A stands for Alpha, the opacity channel (used for transparency effects, but higher values are more opaque, so it makes sense to call it opacity).
A note on formats¶
When getting pixel data out of this module (reading) and presenting data to this module (writing) there are a number of ways the data could be represented as a Python value. Generally this module uses one of three formats called “flat row flat pixel”, “boxed row flat pixel”, and “boxed row boxed pixel”. Basically the concern is whether each pixel and each row comes in its own little tuple (box), or not.
Consider an image that is 3 pixels wide by 2 pixels high, and each pixel has RGB components:
Boxed row flat pixel:
iter([R,G,B, R,G,B, R,G,B],
[R,G,B, R,G,B, R,G,B])
Each row appears as its own sequence, but the pixels are flattened so that three values for one pixel simply follow the three values for the previous pixel. This is the most common format used, because it provides a good compromise between space and convenience. Row sequence supposed to be compatible with ‘buffer’ protocol in addition to standard sequence methods so ‘buffer()’ can be used to get fast per-byte access. All rows are contained in iterable or iterable-compatible container. (use ‘iter()’ to ensure)
Flat row flat pixel:
[R,G,B, R,G,B, R,G,B,
R,G,B, R,G,B, R,G,B]
The entire image is one single giant sequence of colour values. Generally an array will be used (to save space), not a list.
Boxed row boxed pixel:
list([ (R,G,B), (R,G,B), (R,G,B) ],
[ (R,G,B), (R,G,B), (R,G,B) ])
Each row appears in its own list, but each pixel also appears in its own tuple. A serious memory burn in Python.
In all cases the top row comes first, and for each row the pixels are ordered from left-to-right. Within a pixel the values appear in the order, R-G-B-A (or L-A for greyscale–alpha).
There is a fourth format, mentioned because it is used internally,
is close to what lies inside a PNG file itself, and has some support
from the public API. This format is called packed. When packed,
each row is a sequence of bytes (integers from 0 to 255), just as
it is before PNG scanline filtering is applied. When the bit depth
is 8 this is essentially the same as boxed row flat pixel; when the
bit depth is less than 8, several pixels are packed into each byte;
when the bit depth is 16 (the only value more than 8 that is supported
by the PNG image format) each pixel value is decomposed into 2 bytes
(and packed is a misnomer). This format is used by the
Writer.write_packed()
method. It isn’t usually a convenient
format, but may be just right if the source data for the PNG image
comes from something that uses a similar format (for example, 1-bit
BMPs, or another PNG file).
And now, my famous members¶
-
class
png.
Image
(rows, info)¶ A PNG image.
You can create an
Image
object from an array of pixels by callingpng.from_array()
. It can be saved to disk with thesave()
method.The constructor is not public. Please do not call it.
-
save
(file)¶ Save the image to file.
If file looks like an open file descriptor then it is used, otherwise it is treated as a filename and a fresh file is opened.
In general, you can only call this method once; after it has been called the first time and the PNG image has been saved, the source data will have been streamed, and cannot be streamed again.
-
-
class
png.
Reader
(_guess=None, **kw)¶ PNG decoder in pure Python.
Create a PNG decoder object.
The constructor expects exactly one keyword argument. If you supply a positional argument instead, it will guess the input type. You can choose among the following keyword arguments:
- filename
- Name of input file (a PNG file).
- file
- A file-like object (object with a read() method).
- bytes
array
orstring
with PNG data.
-
asDirect
()¶ Returns the image data as a direct representation of an
x * y * planes
array. This method is intended to remove the need for callers to deal with palettes and transparency themselves. Images with a palette (colour type 3) are converted to RGB or RGBA; images with transparency (atRNS
chunk) are converted to LA or RGBA as appropriate. When returned in this format the pixel values represent the colour value directly without needing to refer to palettes or transparency information.Like the
read()
method this method returns a 4-tuple:(width, height, pixels, meta)
This method normally returns pixel values with the bit depth they have in the source image, but when the source PNG has an
sBIT
chunk it is inspected and can reduce the bit depth of the result pixels; pixel values will be reduced according to the bit depth specified in thesBIT
chunk (PNG nerds should note a single result bit depth is used for all channels; the maximum of the ones specified in thesBIT
chunk. An RGB565 image will be rescaled to 6-bit RGB666).The meta dictionary that is returned reflects the direct format and not the original source image. For example, an RGB source image with a
tRNS
chunk to represent a transparent colour, will haveplanes=3
andalpha=False
for the source image, but the meta dictionary returned by this method will haveplanes=4
andalpha=True
because an alpha channel is synthesized and added.pixels is the pixel data in boxed row flat pixel format (just like the
read()
method).All the other aspects of the image data are not changed.
-
asFloat
(maxval=1.0)¶ Return image pixels as per
asDirect()
method, but scale all pixel values to be floating point values between 0.0 and maxval.
-
asRGB
()¶ Return image as RGB pixels.
RGB colour images are passed through unchanged; greyscales are expanded into RGB triplets (there is a small speed overhead for doing this).
An alpha channel in the source image will raise an exception.
The return values are as for the
read()
method except that the metadata reflect the returned pixels, not the source image. In particular, for this methodmetadata['greyscale']
will beFalse
.
-
asRGB8
()¶ Return the image data as an RGB pixels with 8-bits per sample.
This is like the
asRGB()
method except that this method additionally rescales the values so that they are all between 0 and 255 (8-bit). In the case where the source image has a bit depth < 8 the transformation preserves all the information; where the source image has bit depth > 8, then rescaling to 8-bit values loses precision. No dithering is performed. LikeasRGB()
, an alpha channel in the source image will raise an exception.This function returns a 4-tuple: (width, height, pixels, metadata). width, height, metadata are as per the
read()
method.pixels is the pixel data in boxed row flat pixel format.
-
asRGBA
()¶ Return image as RGBA pixels.
Greyscales are expanded into RGB triplets; an alpha channel is synthesized if necessary. The return values are as for the
read()
method except that the metadata reflect the returned pixels, not the source image. In particular, for this methodmetadata['greyscale']
will beFalse
, andmetadata['alpha']
will beTrue
.
-
asRGBA8
()¶ Return the image data as RGBA pixels with 8-bits per sample.
This method is similar to
asRGB8()
andasRGBA()
: The result pixels have an alpha channel, and values are rescaled to the range 0 to 255. The alpha channel is synthesized if necessary (with a small speed penalty).
-
chunk
(seek=None, lenient=False)¶ Read the next PNG chunk from the input file
returns a (chunk_type, data) tuple. chunk_type is the chunk’s type as a byte string (all PNG chunk types are 4 bytes long). data is the chunk’s data content, as a byte string.
If the optional seek argument is specified then it will keep reading chunks until it either runs out of file or finds the chunk_type specified by the argument. Note that in general the order of chunks in PNGs is unspecified, so using seek can cause you to miss chunks.
If the optional lenient argument evaluates to True, checksum failures will raise warnings rather than exceptions.
-
chunklentype
()¶ Reads just enough of the input to determine the next chunk’s length and type, returned as a (length, chunk_type) pair where chunk_type is a string. If there are no more chunks,
None
is returned.
-
chunks
()¶ Return an iterator that will yield each chunk as a (chunktype, content) pair.
-
deinterlace
(raw)¶ Read raw pixel data, undo filters, deinterlace, and flatten.
Return in flat row flat pixel format.
-
idat
(lenient=False)¶ Iterator that yields all the
IDAT
chunks as strings.
-
idatdecomp
(lenient=False, max_length=0)¶ Iterator that yields decompressed
IDAT
strings.
-
iterboxed
(rows)¶ Iterator that yields each scanline in boxed row flat pixel format.
rows should be an iterator that yields the bytes of each row in turn.
-
iterstraight
(raw)¶ Iterator that undoes the effect of filtering
Yields each row in serialised format (as a sequence of bytes). Assumes input is straightlaced. raw should be an iterable that yields the raw bytes in chunks of arbitrary size.
-
palette
(alpha='natural')¶ Returns a palette that is a sequence of 3-tuples or 4-tuples
Synthesizing it from the
PLTE
andtRNS
chunks. These chunks should have already been processed (for example, by calling thepreamble()
method). All the tuples are the same size: 3-tuples if there is notRNS
chunk, 4-tuples when there is atRNS
chunk. Assumes that the image is colour type 3 and therefore aPLTE
chunk is required.If the alpha argument is
'force'
then an alpha channel is always added, forcing the result to be a sequence of 4-tuples.
-
preamble
(lenient=False)¶ Extract the image metadata
Extract the image metadata by reading the initial part of the PNG file up to the start of the
IDAT
chunk. All the chunks that precede theIDAT
chunk are read and either processed for metadata or discarded.If the optional lenient argument evaluates to True, checksum failures will raise warnings rather than exceptions.
-
process_chunk
(lenient=False)¶ Process the next chunk and its data.
If the optional lenient argument evaluates to True, checksum failures will raise warnings rather than exceptions.
-
read
(lenient=False)¶ Read the PNG file and decode it.
Returns (width, height, pixels, metadata).
May use excessive memory.
pixels are returned in boxed row flat pixel format.
If the optional lenient argument evaluates to True, checksum failures will raise warnings rather than exceptions.
-
read_flat
()¶ Read a PNG file and decode it into flat row flat pixel format.
Returns (width, height, pixels, metadata).
May use excessive memory.
pixels are returned in flat row flat pixel format.
See also the
read()
method which returns pixels in the more stream-friendly boxed row flat pixel format.
-
serialtoflat
(raw, width=None)¶ Convert serial format (byte stream) pixel data to flat row flat pixel.
-
validate_signature
()¶ If signature (header) has not been read then read and validate it
-
class
png.
Writer
(width=None, height=None, greyscale=False, alpha=False, bitdepth=8, palette=None, transparent=None, background=None, gamma=None, compression=None, interlace=False, chunk_limit=1048576, filter_type=None, icc_profile=None, icc_profile_name='ICC Profile', **kwargs)¶ PNG encoder in pure Python.
Create a PNG encoder object.
Arguments:
- width, height
- Image size in pixels, as two separate arguments.
- greyscale
- Input data is greyscale, not RGB.
- alpha
- Input data has alpha channel (RGBA or LA).
- bitdepth
- Bit depth: from 1 to 16.
- palette
- Create a palette for a colour mapped image (colour type 3).
- transparent
- Specify a transparent colour (create a
tRNS
chunk). - background
- Specify a default background colour (create a
bKGD
chunk). - gamma
- Specify a gamma value (create a
gAMA
chunk). - compression
- zlib compression level: 0 (none) to 9 (more compressed); default: -1 or None.
- interlace
- Create an interlaced image.
- chunk_limit
- Write multiple
IDAT
chunks to save memory. - filter_type
- Enable and specify PNG filter
- icc_profile
- Write ICC Profile
- icc_profile_name
- Name for ICC Profile
- Extra keywords:
- text
- see
set_text()
- modification_time
- see
set_modification_time()
- resolution
- see
set_resolution()
The image size (in pixels) can be specified either by using the width and height arguments, or with the single size argument. If size is used it should be a pair (width, height).
greyscale and alpha are booleans that specify whether an image is greyscale (or colour), and whether it has an alpha channel (or not).
bitdepth specifies the bit depth of the source pixel values. Each source pixel value must be an integer between 0 and
2**bitdepth-1
. For example, 8-bit images have values between 0 and 255. PNG only stores images with bit depths of 1,2,4,8, or 16. When bitdepth is not one of these values, the next highest valid bit depth is selected, and ansBIT
(significant bits) chunk is generated that specifies the original precision of the source image. In this case the supplied pixel values will be rescaled to fit the range of the selected bit depth.The details of which bit depth / colour model combinations the PNG file format supports directly, are somewhat arcane (refer to the PNG specification for full details). Briefly: “small” bit depths (1,2,4) are only allowed with greyscale and colour mapped images; colour mapped images cannot have bit depth 16.
For colour mapped images (in other words, when the palette argument is specified) the bitdepth argument must match one of the valid PNG bit depths: 1, 2, 4, or 8. (It is valid to have a PNG image with a palette and an
sBIT
chunk, but the meaning is slightly different; it would be awkward to press the bitdepth argument into service for this.)The palette option, when specified, causes a colour mapped image to be created: the PNG colour type is set to 3; greyscale must not be set; alpha must not be set; transparent must not be set; the bit depth must be 1, 2, 4, or 8. When a colour mapped image is created, the pixel values are palette indexes and the bitdepth argument specifies the size of these indexes (not the size of the colour values in the palette).
The palette argument value should be a sequence of 3- or 4-tuples. 3-tuples specify RGB palette entries; 4-tuples specify RGBA palette entries. If both 4-tuples and 3-tuples appear in the sequence then all the 4-tuples must come before all the 3-tuples. A
PLTE
chunk is created; if there are 4-tuples then atRNS
chunk is created as well. ThePLTE
chunk will contain all the RGB triples in the same sequence; thetRNS
chunk will contain the alpha channel for all the 4-tuples, in the same sequence. Palette entries are always 8-bit.If specified, the transparent and background parameters must be a tuple with three integer values for red, green, blue, or a simple integer (or singleton tuple) for a greyscale image.
If specified, the gamma parameter must be a positive number (generally, a float). A
gAMA
chunk will be created. Note that this will not change the values of the pixels as they appear in the PNG file, they are assumed to have already been converted appropriately for the gamma specified.The compression argument specifies the compression level to be used by the
zlib
module. Values from 1 to 9 specify compression, with 9 being “more compressed” (usually smaller and slower, but it doesn’t always work out that way). 0 means no compression. -1 andNone
both mean that the default level of compession will be picked by thezlib
module (which is generally acceptable).If interlace is true then an interlaced image is created (using PNG’s so far only interace method, Adam7). This does not affect how the pixels should be presented to the encoder, rather it changes how they are arranged into the PNG file. On slow connexions interlaced images can be partially decoded by the browser to give a rough view of the image that is successively refined as more image data appears.
Note
Enabling the interlace option requires the entire image to be processed in working memory.
chunk_limit is used to limit the amount of memory used whilst compressing the image. In order to avoid using large amounts of memory, multiple
IDAT
chunks may be created.filter_type is number or name of filter type for better compression see http://www.w3.org/TR/PNG/#9Filter-types for details It’s also possible to use adaptive strategy for choosing filter type per row. Predefined strategies are sum and entropy. Custom strategies can be added with
register_extra_filter()
or be callable passed with this argument. (see more atregister_extra_filter()
)-
array_scanlines
(pixels)¶ Generates boxed rows (flat pixels) from flat rows (flat pixels) in an array.
-
array_scanlines_interlace
(pixels)¶ Generator for interlaced scanlines from an array.
pixels is the full source image in flat row flat pixel format. The generator yields each scanline of the reduced passes in turn, in boxed row flat pixel format.
-
convert_pnm
(infile, outfile)¶ Convert a PNM file containing raw pixel data into a PNG file with the parameters set in the writer object. Works for (binary) PGM, PPM, and PAM formats.
-
convert_ppm_and_pgm
(ppmfile, pgmfile, outfile)¶ Convert a PPM and PGM file containing raw pixel data into a PNG outfile with the parameters set in the writer object.
-
file_scanlines
(infile)¶ Generates boxed rows in flat pixel format, from the input file.
It assumes that the input file is in a “Netpbm-like” binary format, and is positioned at the beginning of the first pixel. The number of pixels to read is taken from the image dimensions (width, height, planes) and the number of bytes per value is implied by the image bitdepth.
-
idat
(rows, packed=False)¶ Generator that produce IDAT chunks from rows
-
set_modification_time
(modification_time=True)¶ Add time to be written as last modification time
When called after initialisation configure to use time of writing file
-
set_rendering_intent
(rendering_intent)¶ Set rendering intent variant for sRGB chunk
-
set_resolution
(resolution=None)¶ Add physical pixel dimensions
resolution supposed two be tuple of two parameterts: pixels per unit and unit type; unit type may be omitted pixels per unit could be simple integer or tuple of (ppu_x, ppu_y) Also possible to use all three parameters im row
- resolution = ((1, 4), ) # wide pixels (4:1) without unit specifier
- resolution = (300, ‘inch’) # 300dpi in both dimensions
- resolution = (4, 1, 0) # tall pixels (1:4) without unit specifier
-
set_rgb_points
(rgb_points, *args)¶ Set rgb points part of cHRM chunk
-
set_text
(text=None, **kwargs)¶ Add textual information.
All pairs in dictionary will be written, but keys should be latin-1; registered keywords could be used as arguments.
When called more than once overwrite exist data.
-
set_white_point
(white_point, point2=None)¶ Set white point part of cHRM chunk
-
write
(outfile, rows)¶ Write a PNG image to the output file.
rows should be an iterable that yields each row in boxed row flat pixel format. The rows should be the rows of the original image, so there should be
self.height
rows ofself.width * self.planes
values. If interlace is specified (when creating the instance), then an interlaced PNG file will be written. Supply the rows in the normal image order; the interlacing is carried out internally.Note
Interlacing will require the entire image to be in working memory.
-
write_array
(outfile, pixels)¶ Write an array in flat row flat pixel format as a PNG file on the output file. See also
write()
method.
-
write_idat
(outfile, idat_sequence)¶ Write png with IDAT to file
idat_sequence should be iterable that produce IDAT chunks compatible with Writer configuration.
-
write_packed
(outfile, rows)¶ Write PNG file to outfile.
The pixel data comes from rows which should be in boxed row packed format. Each row should be a sequence of packed bytes.
Technically, this method does work for interlaced images but it is best avoided. For interlaced images, the rows should be presented in the order that they appear in the file.
This method should not be used when the source image bit depth is not one naturally supported by PNG; the bit depth should be 1, 2, 4, 8, or 16.
-
write_passes
(outfile, rows, packed=False)¶ Write a PNG image to the output file.
Most users are expected to find the
write()
orwrite_array()
method more convenient.The rows should be given to this method in the order that they appear in the output file. For straightlaced images, this is the usual top to bottom ordering, but for interlaced images the rows should have already been interlaced before passing them to this function.
rows should be an iterable that yields each row. When packed is
False
the rows should be in boxed row flat pixel format; when packed isTrue
each row should be a packed sequence of bytes.
-
exception
png.
Error
¶ Generic PurePNG error
-
exception
png.
FormatError
¶ Problem with input file format.
In other words, PNG file does not conform to the specification in some way and is invalid.
-
exception
png.
ChunkError
¶ Error in chunk handling
-
png.
register_extra_filter
(selector, name)¶ Register adaptive filter selection strategy for futher usage.
selector - callable like
def(line, cfg, filter_obj)
- line - line for filtering
- cfg - dict with optional tuning
- filter_obj - instance of this class to get context or apply base filters
callable should return chosen line
name - name which may be used later to recall this strategy
-
png.
write_chunks
(out, chunks)¶ Create a PNG file by writing out the chunks.
-
png.
from_array
(a, mode=None, info=None)¶ Create a PNG
Image
object from a 2- or 3-dimensional array.One application of this function is easy PIL-style saving:
png.from_array(pixels, 'L').save('foo.png')
.Unless they are specified using the info parameter, the PNG’s height and width are taken from the array size. For a 3 dimensional array the first axis is the height; the second axis is the width; and the third axis is the channel number. Thus an RGB image that is 16 pixels high and 8 wide will use an array that is 16x8x3. For 2 dimensional arrays the first axis is the height, but the second axis is
width*channels
, so an RGB image that is 16 pixels high and 8 wide will use a 2-dimensional array that is 16x24 (each row will be 8*3 = 24 sample values).mode is a string that specifies the image colour format in a PIL-style mode. It can be:
'L'
- greyscale (1 channel)
'LA'
- greyscale with alpha (2 channel)
'RGB'
- colour image (3 channel)
'RGBA'
- colour image with alpha (4 channel)
The mode string can also specify the bit depth (overriding how this function normally derives the bit depth, see below). Appending
';16'
to the mode will cause the PNG to be 16 bits per channel; any decimal from 1 to 16 can be used to specify the bit depth.When a 2-dimensional array is used mode determines how many channels the image has, and so allows the width to be derived from the second array dimension.
The array is expected to be a
numpy
array, but it can be any suitable Python sequence. For example, a list of lists can be used:png.from_array([[0, 255, 0], [255, 0, 255]], 'L')
. The exact rules are:len(a)
gives the first dimension, height;len(a[0])
gives the second dimension;len(a[0][0])
gives the third dimension, unless an exception is raised in which case a 2-dimensional array is assumed. It’s slightly more complicated than that because an iterator of rows can be used, and it all still works. Using an iterator allows data to be streamed efficiently.The bit depth of the PNG is normally taken from the array element’s datatype (but if mode specifies a bitdepth then that is used instead). The array element’s datatype is determined in a way which is supposed to work both for
numpy
arrays and for Pythonarray.array
objects. A 1 byte datatype will give a bit depth of 8, a 2 byte datatype will give a bit depth of 16. If the datatype does not have an implicit size, for example it is a plain Python list of lists, as above, then a default of 8 is used.The info parameter is a dictionary that can be used to specify metadata (in the same style as the arguments to the
png.Writer
class). For this function the keys that are useful are:- height
- overrides the height derived from the array dimensions and allows a to be an iterable.
- width
- overrides the width derived from the array dimensions.
- bitdepth
- overrides the bit depth derived from the element datatype (but must match mode if that also specifies a bit depth).
Generally anything specified in the info dictionary will override any implicit choices that this function would otherwise make, but must match any explicit ones. For example, if the info dictionary has a
greyscale
key then this must be true when mode is'L'
or'LA'
and false when mode is'RGB'
or'RGBA'
.
-
png.
parse_mode
(mode, default_bitdepth=None)¶ Parse PIL-style mode and return tuple (grayscale, alpha, bitdeph)
-
png.
read_pam_header
(infile)¶ Read (the rest of a) PAM header.
infile should be positioned immediately after the initial ‘P7’ line (at the beginning of the second line). Returns are as for read_pnm_header.
-
png.
read_pnm_header
(infile, supported=('P5', 'P6'))¶ Read a PNM header, returning (format,width,height,depth,maxval).
width and height are in pixels. depth is the number of channels in the image; for PBM and PGM it is synthesized as 1, for PPM as 3; for PAM images it is read from the header. maxval is synthesized (as 1) for PBM images.
-
png.
write_pnm
(file, width, height, pixels, meta)¶ Write a Netpbm PNM/PAM file.