Package pyglet.image

Image load, capture and high-level texture functions.

Only basic functionality is described here; for full reference see the accompanying documentation.

To load an image:

from pyglet import image
pic = image.load('picture.png')

The supported image file types include PNG, BMP, GIF, JPG, and many more, somewhat depending on the operating system. To load an image from a file-like object instead of a filename:

pic = image.load('hint.jpg', file=fileobj)

The hint helps the module locate an appropriate decoder to use based on the file extension. It is optional.

Once loaded, images can be used directly by most other modules of pyglet. All images have a width and height you can access:

width, height = pic.width, pic.height

You can extract a region of an image (this keeps the original image intact; the memory is shared efficiently):

subimage = pic.get_region(x, y, width, height)

Remember that y-coordinates are always increasing upwards.

Drawing images

To draw an image at some point on the screen:

pic.blit(x, y, z)

This assumes an appropriate view transform and projection have been applied.

Some images have an intrinsic "anchor point": this is the point which will be aligned to the x and y coordinates when the image is drawn. By default the anchor point is the lower-left corner of the image. You can use the anchor point to center an image at a given point, for example:

pic.anchor_x = pic.width // 2
pic.anchor_y = pic.height // 2
pic.blit(x, y, z)

Texture access

If you are using OpenGL directly, you can access the image as a texture:

texture = pic.get_texture()

(This is the most efficient way to obtain a texture; some images are immediately loaded as textures, whereas others go through an intermediate form). To use a texture with pyglet.gl:

from pyglet.gl import *
glEnable(texture.target)        # typically target is GL_TEXTURE_2D
glBindTexture(texture.target, texture.id)
# ... draw with the texture

Pixel access

To access raw pixel data of an image:

rawimage = pic.get_image_data()

(If the image has just been loaded this will be a very quick operation; however if the image is a texture a relatively expensive readback operation will occur). The pixels can be accessed as a string:

format = 'RGBA'
pitch = rawimage.width * len(format)
pixels = rawimage.get_data(format, pitch)

"format" strings consist of characters that give the byte order of each color component. For example, if rawimage.format is 'RGBA', there are four color components: red, green, blue and alpha, in that order. Other common format strings are 'RGB', 'LA' (luminance, alpha) and 'I' (intensity).

The "pitch" of an image is the number of bytes in a row (this may validly be more than the number required to make up the width of the image, it is common to see this for word alignment). If "pitch" is negative the rows of the image are ordered from top to bottom, otherwise they are ordered from bottom to top.

Retrieving data with the format and pitch given in ImageData.format and ImageData.pitch avoids the need for data conversion (assuming you can make use of the data in this arbitrary format).

Submodules

pyglet.image.atlas
Group multiple small images into larger textures.

Classes

  ImageException
  ImagePattern
Abstract image creation class.
  SolidColorImagePattern
Creates an image filled with a solid color.
  CheckerImagePattern
Create an image with a tileable checker image.
  AbstractImage
Abstract class representing an image.
  AbstractImageSequence
Abstract sequence of images.
  TextureSequence
Interface for a sequence of textures.
  UniformTextureSequence
Interface for a sequence of textures, each with the same dimensions.
  ImageData
An image represented as a string of unsigned bytes.
  ImageDataRegion
  CompressedImageData
Image representing some compressed data suitable for direct uploading to driver.
  Texture
An image loaded into video memory that can be efficiently drawn to the framebuffer.
  TextureRegion
A rectangular region of a texture, presented as if it were a separate texture.
  Texture3D
A texture with more than one image slice.
  TileableTexture
A texture that can be tiled efficiently.
  DepthTexture
A texture with depth samples (typically 24-bit).
  BufferManager
Manages the set of framebuffers for a context.
  BufferImage
An abstract framebuffer.
  ColorBufferImage
A color framebuffer.
  DepthBufferImage
The depth buffer.
  BufferImageMask
A single bit of the stencil buffer.
  ImageGrid
An imaginary grid placed over an image allowing easy access to regular regions of that image.
  TextureGrid
A texture containing a regular grid of texture regions.
  Animation
Sequence of images with timing information.
  AnimationFrame
A single frame of an animation.

Functions

AbstractImage load(filename, file=None, decoder=None)
Load an image from a file.
AbstractImage create(width, height, pattern=None)
Create an image optionally filled with the given pattern.
BufferManager get_buffer_manager()
Get the buffer manager for the current OpenGL context.
Animation load_animation(filename, file=None, decoder=None)
Load an animation from a file.

Function Details

load

load(filename, file=None, decoder=None)
Load an image from a file.
Parameters:
filename : str
Used to guess the image format, and to load the file if file is unspecified.
file : file-like object or None
Source of image data in any supported format.
decoder : ImageDecoder or None
If unspecified, all decoders that are registered for the filename extension are tried. If none succeed, the exception from the first decoder is raised.
Returns: AbstractImage

Note: You can make no assumptions about the return type; usually it will be ImageData or CompressedImageData, but decoders are free to return any subclass of AbstractImage.

create

create(width, height, pattern=None)
Create an image optionally filled with the given pattern.
Parameters:
width : int
Width of image to create
height : int
Height of image to create
pattern : ImagePattern or None
Pattern to fill image with. If unspecified, the image will intially be transparent.
Returns: AbstractImage

Note: You can make no assumptions about the return type; usually it will be ImageData or CompressedImageData, but patterns are free to return any subclass of AbstractImage.

load_animation

load_animation(filename, file=None, decoder=None)

Load an animation from a file.

Currently, the only supported format is GIF.

Parameters:
filename : str
Used to guess the animation format, and to load the file if file is unspecified.
file : file-like object or None
File object containing the animation stream.
decoder : ImageDecoder or None
If unspecified, all decoders that are registered for the filename extension are tried. If none succeed, the exception from the first decoder is raised.
Returns: Animation