pyglet.extlibs.png
¶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. Limited support is available for Python 2.2, but
not everything works. Best with Python 2.4 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.
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 PyPNG) 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).
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:
list([R,G,B, R,G,B, R,G,B],
[R,G,B, R,G,B, R,G,B])
Each row appears as its own list, 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. PyPNG regards itself as at liberty to replace any sequence type with any sufficiently compatible other sequence type; in practice each row is an array (from the array module), and the outer list is sometimes an iterator rather than an explicit list (so that streaming is possible).
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).
Image |
A PNG image. |
Reader |
PNG decoder in pure Python. |
Writer |
PNG encoder in pure Python. |
pngfilters |
ChunkError |
|
Error |
|
FormatError |
Problem with input file format. |
check_bitdepth_colortype (bitdepth, colortype) |
Check that bitdepth and colortype are both valid, and specified in a valid combination. |
check_color (c, greyscale, which) |
Checks that a colour argument for transparent or background options is the right form. |
check_palette (palette) |
Check a palette argument (to the Writer class) for validity. |
check_sizes (size, width, height) |
Check that these arguments, in supplied, are consistent. |
color_triple (color) |
Convert a command line colour value to a RGB triple of integers. |
filter_scanline (type, line, fo[, prev]) |
Apply a scanline filter to a scanline. |
from_array (a[, mode, info]) |
Create a PNG Image object from a 2- or 3-dimensional array. |
fromarray (a[, mode, info]) |
Create a PNG Image object from a 2- or 3-dimensional array. |
group (s, n) |
|
interleave_planes (ipixels, apixels, ipsize, ...) |
Interleave (colour) planes, e.g. |
isarray (x) |
Same as isinstance(x, array) except on Python 2.2, where it always returns False . |
isinteger (x) |
|
read_pam_header (infile) |
Read (the rest of a) PAM header. |
read_pnm_header (infile[, supported]) |
Read a PNM header, returning (format,width,height,depth,maxval). |
tostring (row) |
Convert row of bytes to string. |
write_chunk (outfile, tag[, data]) |
Write a PNG chunk to the output file, including length and checksum. |
write_chunks (out, chunks) |
Create a PNG file by writing out the chunks. |
write_pnm (file, width, height, pixels, meta) |
Write a Netpbm PNM/PAM file. |
Defined
itertools
math
operator
struct
sys
warnings
zlib