Reader Class

Inheritance diagram of Reader

class Reader(_guess=None, **kw)

PNG decoder in pure Python.

Constructor:

__init__(_guess=None, **kw)

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 or string with PNG data.

Methods:

asDirect() Returns the image data as a direct representation of an x * y * planes array.
asFloat([maxval]) 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.
asRGB8() Return the image data as an RGB pixels with 8-bits per sample.
asRGBA() Return image as RGBA pixels.
asRGBA8() Return the image data as RGBA pixels with 8-bits per sample.
chunk([seek, lenient]) Read the next PNG chunk from the input file; returns a (type,*data*) tuple.
chunklentype() Reads just enough of the input to determine the next chunk’s length and type, returned as a (length, type) pair where type is a string.
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.
iterboxed(rows) Iterator that yields each scanline in boxed row flat pixel format.
iterstraight(raw) Iterator that undoes the effect of filtering, and yields each row in serialised format (as a sequence of bytes).
palette([alpha]) Returns a palette that is a sequence of 3-tuples or 4-tuples, synthesizing it from the PLTE and tRNS chunks.
preamble([lenient]) Extract the image metadata by reading the initial part of the PNG file up to the start of the IDAT chunk.
process_chunk([lenient]) Process the next chunk and its data.
read([lenient]) Read the PNG file and decode it.
read_flat() Read a PNG file and decode it into flat row flat pixel format.
serialtoflat(bytes[, width]) Convert serial format (byte stream) pixel data to flat row flat pixel.
undo_filter(filter_type, scanline, previous) Undo the filter for a scanline.
validate_signature() If signature (header) has not been read then read and validate it; otherwise do nothing.

Methods

Reader.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 (a tRNS 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 the sBIT chunk (PNG nerds should note a single result bit depth is used for all channels; the maximum of the ones specified in the sBIT 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 have planes=3 and alpha=False for the source image, but the meta dictionary returned by this method will have planes=4 and alpha=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.

Reader.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.

Reader.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 method metadata['greyscale'] will be False.

Reader.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. Like asRGB(), 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.

Reader.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 method metadata['greyscale'] will be False, and metadata['alpha'] will be True.

Reader.asRGBA8()

Return the image data as RGBA pixels with 8-bits per sample. This method is similar to asRGB8() and asRGBA(): 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).

Reader.chunk(seek=None, lenient=False)

Read the next PNG chunk from the input file; returns a (type,*data*) tuple. type is the chunk’s type as a string (all PNG chunk types are 4 characters long). data is the chunk’s data content, as a string.

If the optional seek argument is specified then it will keep reading chunks until it either runs out of file or finds the 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.

Reader.chunklentype()

Reads just enough of the input to determine the next chunk’s length and type, returned as a (length, type) pair where type is a string. If there are no more chunks, None is returned.

Reader.chunks()

Return an iterator that will yield each chunk as a (chunktype, content) pair.

Reader.deinterlace(raw)

Read raw pixel data, undo filters, deinterlace, and flatten. Return in flat row flat pixel format.

Reader.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.

Reader.iterstraight(raw)

Iterator that undoes the effect of filtering, and 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.

Reader.palette(alpha='natural')

Returns a palette that is a sequence of 3-tuples or 4-tuples, synthesizing it from the PLTE and tRNS chunks. These chunks should have already been processed (for example, by calling the preamble() method). All the tuples are the same size: 3-tuples if there is no tRNS chunk, 4-tuples when there is a tRNS chunk. Assumes that the image is colour type 3 and therefore a PLTE 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.

Reader.preamble(lenient=False)

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 the IDAT 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.

Reader.process_chunk(lenient=False)

Process the next chunk and its data. This only processes the following chunk types, all others are ignored: IHDR, PLTE, bKGD, tRNS, gAMA, sBIT.

If the optional lenient argument evaluates to True, checksum failures will raise warnings rather than exceptions.

Reader.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.

Reader.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.

Reader.serialtoflat(bytes, width=None)

Convert serial format (byte stream) pixel data to flat row flat pixel.

Reader.undo_filter(filter_type, scanline, previous)

Undo the filter for a scanline. scanline is a sequence of bytes that does not include the initial filter type byte. previous is decoded previous scanline (for straightlaced images this is the previous pixel row, but for interlaced images, it is the previous scanline in the reduced image, which in general is not the previous pixel row in the final image). When there is no previous scanline (the first row of a straightlaced image, or the first row in one of the passes in an interlaced image), then this argument should be None.

The scanline will have the effects of filtering removed, and the result will be returned as a fresh sequence of bytes.

Reader.validate_signature()

If signature (header) has not been read then read and validate it; otherwise do nothing.

Table Of Contents

Previous topic

Image Class

Next topic

Writer Class