Image Handling tcod.image#

Libtcod functionality for handling images.

This module is generally seen as outdated. To load images you should typically use Pillow or imageio unless you need to use a feature exclusive to libtcod.

Python-tcod is unable to render pixels to consoles. The best it can do with consoles is convert an image into semigraphics which can be shown on non-emulated terminals. For true pixel-based rendering you’ll want to access the SDL rendering port at tcod.sdl.render.

class tcod.image.Image(width: int, height: int)[source]#

A libtcod image.

Parameters:

  • width (int) – Width of the new Image.

  • height (int) – Height of the new Image.

width#

Read only width of this Image.

Type:

int

height#

Read only height of this Image.

Type:

int

blit(console: Console, x: float, y: float, bg_blend: int, scale_x: float, scale_y: float, angle: float) → None[source]#

Blit onto a Console using scaling and rotation.

Parameters:

  • console (Console) – Blit destination Console.

  • x (float) – Console X position for the center of the Image blit.

  • y (float) – Console Y position for the center of the Image blit. The Image blit is centered on this position.

  • bg_blend (int) – Background blending mode to use.

  • scale_x (float) – Scaling along Image x axis. Set to 1 for no scaling. Must be over 0.

  • scale_y (float) – Scaling along Image y axis. Set to 1 for no scaling. Must be over 0.

  • angle (float) – Rotation angle in radians. (Clockwise?)

blit_2x(console: Console, dest_x: int, dest_y: int, img_x: int = 0, img_y: int = 0, img_width: int = -1, img_height: int = -1) → None[source]#

Blit onto a Console with double resolution.

Parameters:

  • console (Console) – Blit destination Console.

  • dest_x (int) – Console tile X position starting from the left at 0.

  • dest_y (int) – Console tile Y position starting from the top at 0.

  • img_x (int) – Left corner pixel of the Image to blit

  • img_y (int) – Top corner pixel of the Image to blit

  • img_width (int) – Width of the Image to blit. Use -1 for the full Image width.

  • img_height (int) – Height of the Image to blit. Use -1 for the full Image height.

blit_rect(console: Console, x: int, y: int, width: int, height: int, bg_blend: int) → None[source]#

Blit onto a Console without scaling or rotation.

Parameters:

  • console (Console) – Blit destination Console.

  • x (int) – Console tile X position starting from the left at 0.

  • y (int) – Console tile Y position starting from the top at 0.

  • width (int) – Use -1 for Image width.

  • height (int) – Use -1 for Image height.

  • bg_blend (int) – Background blending mode to use.

clear(color: tuple[int, int, int]) → None[source]#

Fill this entire Image with color.

Parameters:

color (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

classmethod from_array(array: numpy.typing.ArrayLike) → Image[source]#

Create a new Image from a copy of an array-like object.

Example

>>> import numpy as np
>>> import tcod
>>> array = np.zeros((5, 5, 3), dtype=np.uint8)
>>> image = tcod.image.Image.from_array(array)

New in version 11.4.

classmethod from_file(path: str | PathLike[str]) → Image[source]#

Return a new Image loaded from the given path.

New in version 16.0.

get_alpha(x: int, y: int) → int[source]#

Get the Image alpha of the pixel at x, y.

Parameters:

  • x (int) – X pixel of the image. Starting from the left at 0.

  • y (int) – Y pixel of the image. Starting from the top at 0.

Returns:

The alpha value of the pixel. With 0 being fully transparent and 255 being fully opaque.

Return type:

int

get_mipmap_pixel(left: float, top: float, right: float, bottom: float) → tuple[int, int, int][source]#

Get the average color of a rectangle in this Image.

Parameters should stay within the following limits: * 0 <= left < right < Image.width * 0 <= top < bottom < Image.height

Parameters:

  • left (float) – Left corner of the region.

  • top (float) – Top corner of the region.

  • right (float) – Right corner of the region.

  • bottom (float) – Bottom corner of the region.

Returns:

An (r, g, b) tuple containing the averaged color value. Values are in a 0 to 255 range.

Return type:

Tuple[int, int, int]

get_pixel(x: int, y: int) → tuple[int, int, int][source]#

Get the color of a pixel in this Image.

Parameters:

  • x (int) – X pixel of the Image. Starting from the left at 0.

  • y (int) – Y pixel of the Image. Starting from the top at 0.

Returns:

An (r, g, b) tuple containing the pixels color value. Values are in a 0 to 255 range.

Return type:

Tuple[int, int, int]

hflip() → None[source]#

Horizontally flip this Image.

invert() → None[source]#

Invert all colors in this Image.

put_pixel(x: int, y: int, color: tuple[int, int, int]) → None[source]#

Change a pixel on this Image.

Parameters:

  • x (int) – X pixel of the Image. Starting from the left at 0.

  • y (int) – Y pixel of the Image. Starting from the top at 0.

  • color (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

refresh_console(console: Console) → None[source]#

Update an Image created with libtcodpy.image_from_console.

The console used with this function should have the same width and height as the Console given to libtcodpy.image_from_console. The font width and height must also be the same as when libtcodpy.image_from_console was called.

Parameters:

console (Console) – A Console with a pixel width and height matching this Image.

rotate90(rotations: int = 1) → None[source]#

Rotate this Image clockwise in 90 degree steps.

Parameters:

rotations (int) – Number of 90 degree clockwise rotations.

save_as(filename: str | PathLike[str]) → None[source]#

Save the Image to a 32-bit .bmp or .png file.

Parameters:

filename (Text) – File path to same this Image.

Changed in version 16.0: Added PathLike support.

scale(width: int, height: int) → None[source]#

Scale this Image to the new width and height.

Parameters:

  • width (int) – The new width of the Image after scaling.

  • height (int) – The new height of the Image after scaling.

set_key_color(color: tuple[int, int, int]) → None[source]#

Set a color to be transparent during blitting functions.

Parameters:

color (Union[Tuple[int, int, int], Sequence[int]]) – An (r, g, b) sequence or Color instance.

vflip() → None[source]#

Vertically flip this Image.

tcod.image.load(filename: str | PathLike[str]) → NDArray[np.uint8][source]#

Load a PNG file as an RGBA array.

filename is the name of the file to load.

The returned array is in the shape: (height, width, RGBA).

New in version 11.4.