class p5.PImage

Image class for p5.

Note that the image “behaves” like a 2-D list and hence, doesn’t expose special methods for copying / pasting / cropping. All of these operations can be done by using appropriate indexing into the array. See the p5.PImage.__getitem__() and p5.PImage.__setitem__() methods for details.

  • width (int) – width of the image.
  • height – height of the image.
  • fmt (str) – color format to use for the image. Should be one of {‘RGB’, ‘RGBA’, ‘ALPHA’}. Defaults to ‘RGBA’

list of weak references to the object (if defined)


Return the aspect ratio of the image.

Return type:float | int
blend(other, mode)

Blend the specified image using the given blend mode.

  • other (p5.PImage) – The image to be blended to the current image.
  • mode (str) – Blending mode to use. Should be one of { ‘BLEND’, ‘ADD’, ‘SUBTRACT’, ‘LIGHTEST’, ‘DARKEST’, ‘MULTIPLY’, ‘SCREEN’,}
  • AssertionError – When the dimensions of img do not match the dimensions of the current image.
  • KeyError – When the blend mode is invalid.
filter(kind, param=None)

Filter the image.

  • kind (str) – The kind of filter to use on the image. Should be one of { ‘threshold’, ‘gray’, ‘opaque’, ‘invert’, ‘posterize’, ‘blur’, ‘erode’, ‘dilate’, }
  • param (int | float | None) – optional parameter for the filter in use (defaults to None). Only required for ‘threshold’ (the threshold to use, param should be a value between 0 and 1; defaults to 0.5), ‘posterize’ (limiting value for each channel should be between 2 and 255), and ‘blur’ (gaussian blur radius, defaults to 1.0).

The height of the image

Return type:int

Load internal pixel data for the image.

By default image data is only loaded lazily, i.e., right before displaying an image on the screen. Use this method to manually load the internal image data.


The size of the image

Return type:(int, int) tuple

Updates the display window with the data in the pixels[] array. Use in conjunction with loadPixels()


The width of the image

Return type:int

Loading and displaying


p5.image(img, x, y)
p5.image(img, x, y, w, h)
p5.image(img, location, size=None)

Draw an image to the display window.

Images must be in the same folder as the sketch (or the image path should be explicitly mentioned). The color of an image may be modified with the p5.tint() function.

  • img (PImage or Graphics) – PImage | Graphics object to be displayed.
  • x (float) – x-coordinate of the image by default
  • y (float) – y-coordinate of the image by default
  • w (float) – width to display the image by default
  • h (float) – height to display the image by default



Modify the locaton from which the images are drawn.

Modifies the location from which images are drawn by changing the way in which parameters given to p5.image() are intepreted.

The default mode is image_mode('corner'), which interprets the second parameter of image() as the upper-left corner of the image. If an additional parameter is specified, it is used to set the image’s width and height.

image_mode('corners') interprets the first parameter of image() as the location of one corner, and the second parameter as the opposite corner.

image_mode('center') interprets the first parameter of image() as the image’s center point. If an additional parameter is specified, it is used to set the width and height of the image.

Parameters:mode (str) – should be one of {'corner', 'center', 'corners'}
Raises:ValueError – When the given image mode is not understood. Check for types.



Load an image from the given filename (or URL).

Loads an image into a variable of type PImage. Four types of images may be loaded.

In most cases, load all images in setup() or outside the draw() call to preload them at the start of the program. Loading images inside draw() will reduce the speed of a program.

Parameters:filename (str) – Filename (or path or URL) of the given image. The file-extennsion is automatically inferred.
Returns:An PImage instance with the given image data
Return type:PImage


p5.tint(*color_args, **color_kwargs)

Set the tint color for the sketch.

  • color_args (tuple) – positional arguments to be parsed as a color.
  • color_kwargs (dict) – keyword arguments to be parsed as a color.

Both color_args and color_kwargs are directly sent to Color.parse_color


The tint color.

Return type:




Disable tinting of images.


p5.save_canvas(filename=None, canvas=None)

Saves the given Canvas as an image with filename :param filename: filename/path for the image :type filename: str

Parameters:canvas (PGraphics) – Canvas to be saved. If not specified default canvas is used




Load a snapshot of the display window into the pixels Image.

This context manager loads data into the global pixels Image. Once the program execution leaves the context manager, all changes to the image are written to the main display.


A p5.PImage containing the values for all the pixels in the display window. The size of the image is that of the main rendering window, width × height. This image is only available within the p5.load_pixels() context manager and set to None otherwise.

with load_pixels():
    # code manipulating the ``pixels`` object

Subsequent changes to this image object aren’t reflected until p5.load_pixels() is called again. The contents of the display are updated as soon as program execution leaves the context manager.