BaseImage

Image class used by pygame-menu.

Drawing image modes

Drawing mode

Description

pygame_menu.baseimage.IMAGE_MODE_CENTER

Image is drawn at the center of the surface

pygame_menu.baseimage.IMAGE_MODE_FILL

Image fills the surface

pygame_menu.baseimage.IMAGE_MODE_REPEAT_X

Image repeats on X axis

pygame_menu.baseimage.IMAGE_MODE_REPEAT_XY

Image repeats on both axis

pygame_menu.baseimage.IMAGE_MODE_REPEAT_Y

Image repeats on Y axis

pygame_menu.baseimage.IMAGE_MODE_SIMPLE

Just place the image in the top/left corner

BaseImage - API

class pygame_menu.baseimage.BaseImage(image_path, drawing_mode=101, drawing_offset=(0, 0), drawing_position='position-northwest', load_from_file=True, frombase64=False, image_id='')[source]

Object that loads an image, stores as a surface, transform it and let write the image to a surface.

Parameters
  • image_path (Union[str, Path, BytesIO]) – Path of the image to be loaded. It can be a string (path, base64), pathlib.Path, or io.BytesIO

  • drawing_mode (int) – Drawing mode of the image

  • drawing_offset (Union[Tuple[Union[int, float], Union[int, float]], List[Union[int, float]]]) – Offset of the image in drawing method

  • drawing_position (str) – Drawing position if mode is IMAGE_MODE_SIMPLE. See pygame_menu.locals for valid position values

  • load_from_file (bool) – Loads the image from the given path

  • frombase64 (bool) – If True consider image_path as base64 string

  • image_id (str) – str

apply_image_function(image_function)[source]

Apply a function to each pixel of the image. The function will receive the red, green, blue and alpha colors and must return the same values. The color pixel will be overridden by the function output.

Note

See pygame_menu.baseimage.BaseImage.to_bw() method as an example.

Parameters

image_function (Callable[[int, int, int, int], Tuple[int, int, int, int]]) – Color function, takes colors as image_function=myfunc(r,g,b,a). Returns the same tuple (r, g, b, a)

Return type

BaseImage

Returns

Self reference

checkpoint()[source]

Updates the original surface to the current surface.

Return type

BaseImage

Returns

Self reference

copy()[source]

Return a copy of the image.

Return type

BaseImage

Returns

Image

crop(x, y, width, height)[source]

Crops the image from coordinate on x-axis and y-axis (x, y).

Parameters
Return type

BaseImage

Returns

Self reference

crop_rect(rect)[source]

Crop image from rect.

Parameters

rect (Rect) – Crop rect geometry

Return type

BaseImage

Returns

Self reference

draw(surface, area=None, position=(0, 0))[source]

Draw the image in a given surface.

Parameters
  • surface (Surface) – Pygame surface object

  • area (Optional[Rect]) – Area to draw; if None the image will be drawn on entire surface

  • position (Tuple[int, int]) – Position to draw on x-axis and y-axis (x, y) in px

Return type

BaseImage

Returns

Self reference

equals(image)[source]

Return True if the image is the same as the object.

Parameters

image (BaseImage) – Image object

Return type

bool

Returns

True if the image is the same (note, the surface)

flip(x, y)[source]

This method can flip the image either vertically, horizontally, or both. Flipping an image is non-destructive and does not change the dimensions.

Parameters
  • x (bool) – Flip on x-axis

  • y (bool) – Flip on y-axis

Return type

BaseImage

Returns

Self reference

get_angle()[source]

Return the image angle.

Return type

Union[int, float]

Returns

Angle in degrees

get_at(pos, ignore_alpha=False)[source]

Get the color from a certain position in image on x-axis and y-axis (x, y).

get_at return a copy of the RGBA Color value at the given pixel. If the Surface has no per pixel alpha, then the alpha value will always be 255 (opaque). If the pixel position is outside the area of the Surface an IndexError exception will be raised.

Getting and setting pixels one at a time is generally too slow to be used in a game or realtime situation. It is better to use methods which operate on many pixels at a time like with the blit, fill and draw methods - or by using pygame.surfarraypygame module for accessing surface pixel data using array interfaces/pygame.PixelArraypygame object for direct pixel access of surfaces.

Parameters
Return type

Union[Tuple[int, int, int], Tuple[int, int, int, int]]

Returns

Color

get_bitsize()[source]

Return the image bit size.

Return type

int

Returns

Image bit size

get_crop(x, y, width, height)[source]

Get a crop of the image from coordinate on x-axis and y-axis (x, y).

Parameters
Return type

Surface

Returns

Cropped surface

get_crop_rect(rect)[source]

Get a crop surface of the image from rect.

Parameters

rect (Rect) – Crop rect geometry

Return type

Surface

Returns

Cropped surface

get_drawing_mode()[source]

Return the image drawing mode.

Return type

int

Returns

Image drawing mode

get_drawing_offset()[source]

Return the image drawing offset.

Return type

Tuple[int, int]

Returns

Image drawing offset

get_extension()[source]

Return the extension of the image file.

Return type

str

Returns

File extension

get_filename()[source]

Return the name of the image file.

Return type

str

Returns

Filename

get_height()[source]

Return image height in px.

Return type

int

Returns

Image height

get_path()[source]

Return the image path.

Return type

Union[str, BytesIO]

Returns

Image path

get_rect()[source]

Return the pygame.Rect object of the BaseImage.

This method returns a new rectangle covering the entire surface. The rectangle will always start at (0, 0) with a same width and height size as the image.

Return type

Rect

Returns

Pygame rect object

get_size()[source]

Return the size in pixels of the image.

Return type

Tuple[int, int]

Returns

Image size tuple (width, height)

get_surface(new=True)[source]

Return the surface object of the image.

Parameters

new (bool) – Return a new surface; if False return the same object

Return type

Surface

Returns

Image surface

get_width()[source]

Return image width in px.

Return type

int

Returns

Image width

pick_channels(channels)[source]

Pick certain channels of the image, channels are "r" (red), "g" (green) and "b" (blue); channels param is a list/tuple of channels (non-empty).

For example, pick_channels(['r', 'g']): All channels not included on the list will be discarded.

Parameters

channels (Union[Literal[‘r’, ‘g’, ‘b’], Tuple[Literal[‘r’, ‘g’, ‘b’], Literal[‘r’, ‘g’, ‘b’]], Tuple[Literal[‘r’, ‘g’, ‘b’], Literal[‘r’, ‘g’, ‘b’], Literal[‘r’, ‘g’, ‘b’]], List[Literal[‘r’, ‘g’, ‘b’]]]) – Channels, list or tuple containing "r", "g" or "b" (all combinations are possible)

Return type

BaseImage

Returns

Self reference

resize(width, height, smooth=True)[source]

Resize the image to a desired (width, height) size in pixels.

Parameters
  • width (Union[int, float]) – New width of the image in px

  • height (Union[int, float]) – New height of the image in px

  • smooth (bool) – Smooth scaling

Return type

BaseImage

Returns

Self reference

restore()[source]

Restore image to the original surface.

Return type

BaseImage

Returns

Self reference

rotate(angle, auto_checkpoint=True)[source]

Unfiltered counterclockwise rotation. The angle argument represents degrees and can be any floating point value. Negative angle amounts will rotate clockwise.

Note

Unless rotating by 90 degree increments, the image will be padded larger to hold the new size. If the image has pixel alphas, the padded area will be transparent. Otherwise, pygame will pick a color that matches the image color-key or the topleft pixel value.

Warning

Image should be rotated once. If this method is called once the Class rotates the previously check-pointed state. If you wish to rotate the current image use checkpoint to update the surface. This may increase the image size, because the bounding rectangle of a rotated image is always greater than the bounding rectangle of the original image (except some rotations by multiples of 90 degrees). The image gets distort because of the multiply copies. Each rotation generates a small error (inaccuracy). The sum of the errors is growing and the images decays.

Parameters
  • angle (Union[int, float]) – Rotation angle (degrees 0-360)

  • auto_checkpoint (bool) – Checkpoint after first rotation to avoid rotating the same image. If multiple rotations are applied to the same surface it will increase its size very fast because of inaccuracies

Return type

BaseImage

Returns

Self reference

scale(width, height, smooth=True)[source]

Scale the image to a desired width and height factor.

Note

The scale transformation is permanent, and is applied over the same object. Thus, if image.scale(2, 2).scale(2, 2) the final scale of the initial image is equal to image.scale(4, 4).

Parameters
Return type

BaseImage

Returns

Self reference

scale2x()[source]

This will return a new image that is double the size of the original. It uses the AdvanceMAME Scale2X algorithm which does a “jaggy-less” scale of bitmap graphics.

This really only has an effect on simple images with solid colors. On photographic and anti-aliased images it will look like a regular unfiltered scale.

Return type

BaseImage

Returns

Self reference

scale4x()[source]

Applies a x4 scale factor using scale2x algorithm.

Return type

BaseImage

Returns

Self reference

set_alpha(value, flags=0)[source]

Set the current alpha value for the Surface. When blitting this Surface onto a destination, the pixels will be drawn slightly transparent. The alpha value is an integer from 0 to 255, 0 is fully transparent and 255 is fully opaque. If None is passed for the alpha value, then alpha blending will be disabled, including per-pixel alpha.

This value is different from the per pixel Surface alpha. For a surface with per pixel alpha, blanket alpha is ignored and None is returned.

For pygame 2.0: per-surface alpha can be combined with per-pixel alpha.

The optional flags argument can be set to pygame.RLEACCEL to provide better performance on non accelerated displays. A RLEACCEL Surface will be slower to modify, but quicker to blit as a source.

Parameters
  • value (Optional[int]) – Transparency value from 0 to 255

  • flags (int) – Optional flags

Return type

BaseImage

Returns

Self reference

set_at(pos, color)[source]

Set the color of pixel on x-axis and y-axis (x, y).

Parameters
Return type

BaseImage

Returns

Self reference

set_drawing_mode(drawing_mode)[source]

Set the image drawing mode.

Parameters

drawing_mode (int) – Drawing mode

Return type

BaseImage

Returns

Self reference

set_drawing_offset(offset)[source]

Set the image drawing offset.

Parameters

offset (Union[Tuple[Union[int, float], Union[int, float]], List[Union[int, float]]]) – Drawing offset tuple on x-axis and y-axis (x, y) in px

Return type

BaseImage

Returns

Self reference

set_drawing_position(position)[source]

Set the image position.

Note

See pygame_menu.locals for valid position values.

Parameters

position (str) – Image position

Return type

BaseImage

Returns

Self reference

subsurface(rect)[source]

Return a subsurface from a rect.

Parameters

rect (Union[Tuple[int, int, int, int], Rect]) – Rect

Return type

Surface

Returns

Subsurface

to_bw()[source]

Converts the image to black and white.

Note

This function is slow for large images.

Return type

BaseImage

Returns

Self reference