3.3.3 Image Objects

An Image object encapsulates an in-memory bitmap.

Note on asynchronous methods: Methods resize, transpose, save, and load have an optional callback argument. If the callback is not given, the method call is synchronous; when the method returns, the operation is complete or an exception has been raised. If the callback is given, the method calls are asynchronous. If all parameters are valid and the operation can start, the method call will return immediately. The actual computation then proceeds in the background. When it is finished, the callback is called with an error code as the argument. If the given code is 0, the operation completed without errors, otherwise an error occurred.

It is legal to use an unfinished image as a source in a blit operation; this will use the image data as it is at the moment the blit is made and may thus show an incomplete result.

Image objects have the following methods:

resize( newsize[, callback=None, keepaspect=0]): Returns a new image that contains a resized copy of this image. If keepaspect is set to 1, the resize will maintain the aspect ratio of the image, otherwise the new image will be exactly the given size.
If callback is given, the operation is asynchronous, and the returned image will be only partially complete until callback is called.

transpose( direction[, callback=None])

Creates a new image that contains a transformed copy of this image. The direction parameter can be one of the following:

FLIP_LEFT_RIGHT: Flips the image horizontally, exchanging left and right edges.
FLIP_TOP_BOTTOM: Flips the image vertically, exchanging top and bottom edges.
ROTATE_90: Rotates the image 90 degrees counterclockwise.
ROTATE_180: Rotates the image 180 degrees.
ROTATE_270: Rotates the image 270 degrees counterclockwise.

If callback is given, the operation is asynchronous and the returned image will be only partially complete until callback is called.

load( filename[, callback=None]): Replaces the contents of this Image with the contents of the named file, while keeping the current image mode. This Image object must be of the same size as the file to be loaded.
If callback is given, the operation is asynchronous and the loaded image will be only partially complete until callback is called. filename should be a full path name.

save( filename[,callback=None, format=None, quality=75, bpp=24, compression='default'])

Saves the image into the given file. The supported formats are JPEG and PNG. If format is not given or is set to None, the format is determined based on the file name extension: '.jpg' or '.jpeg' are interpreted to be in JPEG format and '.png' to be in PNG format. filename should be a full path name.

When saving in JPEG format, the quality argument specifies the quality to be used and can range from 1 to 100.

When saving in PNG format, the bpp argument specifies how many bits per pixel the resulting file should have, and compression specifies the compression level to be used.

Valid values for bpp are:

1: Black and white, 1 bit per pixel
8: 256 gray shades, 8 bits per pixel
24: 16.7 million colors, 24 bits per pixel

Valid values for compression are:

'best': The highest possible compression ratio, the slowest speed
'fast': The fastest possible saving, moderate compression
'no': No compression, very large file size
'default': Default compression, a compromise between file size and speed

If callback is given, the operation is asynchronous. When the saving is complete, the callback is called with the result code.

stop( ): Stops the current asynchronous operation, if any. If an asynchronous call is not in progress, this method has no effect.

Image objects have the following attributes:

size: A two-element tuple that contains the size of the Image. Read-only.

twipsize: A two-element tuple that contains the size of the Image in twips. Read/Write.

See About this document... for information on suggesting changes.