bitmaptools – Collection of bitmap manipulation tools — Adafruit CircuitPython 1 documentation (original) (raw)

Note

If you’re looking for information about displaying bitmaps on screens in CircuitPython, see this Learn guidefor information about using the displayio module.

Available on these boards

bitmaptools.rotozoom(dest_bitmap: displayio.Bitmap, source_bitmap: displayio.Bitmap, *, ox: int, oy: int, dest_clip0: Tuple[int, int], dest_clip1: Tuple[int, int], px: int, py: int, source_clip0: Tuple[int, int], source_clip1: Tuple[int, int], angle: float, scale: float, skip_index: int) → None

Inserts the source bitmap region into the destination bitmap with rotation (angle), scale and clipping (both on source and destination bitmaps).

Parameters:

class bitmaptools.BlendMode

The blend mode for alphablend to operate use

Normal_: BlendMode_

Blend with equal parts of the two source bitmaps

Screen_: BlendMode_

Blend based on the value in each color channel. The result keeps the lighter colors and discards darker colors.

bitmaptools.alphablend(dest_bitmap: displayio.Bitmap, source_bitmap_1: displayio.Bitmap, source_bitmap_2: displayio.Bitmap, colorspace: displayio.Colorspace, factor1: float = 0.5, factor2: float | None = None, blendmode: BlendMode | None = BlendMode.Normal, skip_source1_index: int | None = None, skip_source2_index: int | None = None) → None

Alpha blend the two source bitmaps into the destination.

It is permitted for the destination bitmap to be one of the two source bitmaps.

Parameters:

For the L8 colorspace, the bitmaps must have a bits-per-value of 8. For the RGB colorspaces, they must have a bits-per-value of 16.

bitmaptools.fill_region(dest_bitmap: displayio.Bitmap, x1: int, y1: int, x2: int, y2: int, value: int) → None

Draws the color value into the destination bitmap within the rectangular region bounded by (x1,y1) and (x2,y2), exclusive.

Parameters:

bitmaptools.boundary_fill(dest_bitmap: displayio.Bitmap, x: int, y: int, fill_color_value: int, replaced_color_value: int) → None

Draws the color value into the destination bitmap enclosed area of pixels of the background_value color. Like “Paint Bucket” fill tool.

Parameters:

bitmaptools.draw_line(dest_bitmap: displayio.Bitmap, x1: int, y1: int, x2: int, y2: int, value: int) → None

Draws a line into a bitmap specified two endpoints (x1,y1) and (x2,y2).

Parameters:

bitmaptools.draw_polygon(dest_bitmap: displayio.Bitmap, xs: circuitpython_typing.ReadableBuffer, ys: circuitpython_typing.ReadableBuffer, value: int, close: bool | None = True) → None

Draw a polygon connecting points on provided bitmap with provided value

Parameters:

import board import displayio import bitmaptools

display = board.DISPLAY main_group = displayio.Group() display.root_group = main_group

palette = displayio.Palette(3) palette[0] = 0xffffff palette[1] = 0x0000ff palette[2] = 0xff0000

bmp = displayio.Bitmap(128,128, 3) bmp.fill(0)

xs = bytes([4, 101, 101, 19]) ys = bytes([4, 19, 121, 101]) bitmaptools.draw_polygon(bmp, xs, ys, 1)

xs = bytes([14, 60, 110]) ys = bytes([14, 24, 90]) bitmaptools.draw_polygon(bmp, xs, ys, 2)

tilegrid = displayio.TileGrid(bitmap=bmp, pixel_shader=palette) main_group.append(tilegrid)

while True: pass

bitmaptools.arrayblit(bitmap: displayio.Bitmap, data: circuitpython_typing.ReadableBuffer, x1: int = 0, y1: int = 0, x2: int | None = None, y2: int | None = None, skip_index: int | None = None) → None

Inserts pixels from data into the rectangle of width×height pixels with the upper left corner at (x,y)

The values from data are taken modulo the number of color values available in the destination bitmap.

If x1 or y1 are not specified, they are taken as 0. If x2 or y2 are not specified, or are given as None, they are taken as the width and height of the image.

The coordinates affected by the blit are x1 <= x < x2 and y1 <= y < y2.

data must contain at least as many elements as required. If it contains excess elements, they are ignored.

The blit takes place by rows, so the first elements of data go to the first row, the next elements to the next row, and so on.

Parameters:

bitmaptools.readinto(bitmap: displayio.Bitmap, file: BinaryIO, bits_per_pixel: int, element_size: int = 1, reverse_pixels_in_element: bool = False, swap_bytes_in_element: bool = False, reverse_rows: bool = False) → None

Reads from a binary file into a bitmap.

The file must be positioned so that it consists of bitmap.height rows of pixel data, where each row is the smallest multiple of element_size bytes that can hold bitmap.width pixels.

The bytes in an element can be optionally swapped, and the pixels in an element can be reversed. Also, the row loading direction can be reversed, which may be requires for loading certain bitmap files.

This function doesn’t parse image headers, but is useful to speed up loading of uncompressed image formats such as PCF glyph data.

Parameters:

class bitmaptools.DitherAlgorithm

Identifies the algorithm for dither to use

Atkinson_: DitherAlgorithm_

The classic Atkinson dither, often associated with the Hypercard esthetic

FloydStenberg_: DitherAlgorithm_

The Floyd-Stenberg dither

bitmaptools.dither(dest_bitmap: displayio.Bitmap, source_bitmapp: displayio.Bitmap, source_colorspace: displayio.Colorspace, algorithm: DitherAlgorithm = DitherAlgorithm.Atkinson) → None

Convert the input image into a 2-level output image using the given dither algorithm.

Parameters:

bitmaptools.draw_circle(dest_bitmap: displayio.Bitmap, x: int, y: int, radius: int, value: int) → None

Draws a circle into a bitmap specified using a center (x0,y0) and radius r.

Parameters:

import board import displayio import bitmaptools

display = board.DISPLAY main_group = displayio.Group() display.root_group = main_group

palette = displayio.Palette(2) palette[0] = 0xffffff palette[1] = 0x440044

bmp = displayio.Bitmap(128,128, 2) bmp.fill(0)

bitmaptools.circle(64,64, 32, 1)

tilegrid = displayio.TileGrid(bitmap=bmp, pixel_shader=palette) main_group.append(tilegrid)

while True: pass

bitmaptools.blit(dest_bitmap: displayio.Bitmap, source_bitmap: displayio.Bitmap, x: int, y: int, *, x1: int = 0, y1: int = 0, x2: int | None = None, y2: int | None = None, skip_source_index: int | None = None, skip_dest_index: int | None = None) → None

Inserts the source_bitmap region defined by rectangular boundaries (x1,y1) and (x2,y2) into the bitmap at the specified (x,y) location.

Parameters: