Introduction¶

This library decodes an image file into new bitmap and palette objects of the provided type. It’s designed to load code needed during decoding as needed. This is meant to minimize the memory overhead of the decoding code.

Usage Example¶

import board
import displayio
import adafruit_imageload

image, palette = adafruit_imageload.load(
    "images/4bit.bmp", bitmap=displayio.Bitmap, palette=displayio.Palette
)
tile_grid = displayio.TileGrid(image, pixel_shader=palette)

group = displayio.Group()
group.append(tile_grid)
board.DISPLAY.show(group)

while True:
    pass

Contributing¶

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Documentation¶

For information on building library documentation, please check out this guide.

Table of Contents¶

Simple test¶

Ensure your image loads with this simple test.

examples/imageload_simpletest.py¶

import board
import displayio
import adafruit_imageload

image, palette = adafruit_imageload.load(
    "images/4bit.bmp", bitmap=displayio.Bitmap, palette=displayio.Palette
)
tile_grid = displayio.TileGrid(image, pixel_shader=palette)

group = displayio.Group()
group.append(tile_grid)
board.DISPLAY.show(group)

while True:
    pass

`adafruit_imageload`¶

Load pixel values (indices or colors) into a bitmap and colors into a palette.

Author(s): Scott Shawcroft

adafruit_imageload.load(filename, *, bitmap=None, palette=None)¶

Load pixel values (indices or colors) into a bitmap and colors into a palette.

bitmap is the desired type. It must take width, height and color_depth in the constructor. It must also have a _load_row method to load a row’s worth of pixel data.

palette is the desired pallete type. The constructor should take the number of colors and support assignment to indices via [].

`adafruit_imageload.bmp`¶

Load pixel values (indices or colors) into a bitmap and colors into a palette from a BMP file.

Author(s): Scott Shawcroft

adafruit_imageload.bmp.load(file, *, bitmap=None, palette=None)¶

Loads a bmp image from the open file.

Returns tuple of bitmap object and palette object.

Parameters:	bitmap (object) – Type to store bitmap data. Must have API similar to `displayio.Bitmap`. Will be skipped if None palette (object) – Type to store the palette. Must have API similar to `displayio.Palette`. Will be skipped if None

`adafruit_imageload.bmp.indexed`¶

Load pixel values (indices or colors) into a bitmap and colors into a palette from an indexed BMP.

Author(s): Scott Shawcroft

adafruit_imageload.bmp.indexed.decode_rle(bitmap, file, compression, y_range, width)¶: Helper to decode RLE images

adafruit_imageload.bmp.indexed.load(file, width, height, data_start, colors, color_depth, compression, *, bitmap=None, palette=None)¶

Loads indexed bitmap data into bitmap and palette objects.

Parameters:

file (file) – The open bmp file
width (int) – Image width in pixels
height (int) – Image height in pixels
data_start (int) – Byte location where the data starts (after headers)
colors (int) – Number of distinct colors in the image
color_depth (int) – Number of bits used to store a value
compression (int) – 0 - none, 1 - 8bit RLE, 2 - 4bit RLE

Developing¶

Strategy: * read headers to determine file type * keep a pointer to the start of data * read data into the Palette for all colors present * rewind the file pointer back to start of data * read data into the Bitmap * return a bitmap and palette instance

Shared Bindings¶

This library uses interfaces from CircuitPython’s displayio module (Bitmap and Palette) to load images from disk into memory.

The Bitmap and Palette objects are related, and together can be used to display the image on a screen for the user.

The Palette is a list of colors present in the image. Its constructor takes a single argument: (int) max_colors, representing how many colors will be populated in the palette.

Palette code example¶

palette = Palette(4)  # 4 represents that we will define four colors in palette
palette[0] = b'\x00\x00\x00\x00'  # white
palette[1] = b'\xFF\x00\x00\x00'  # red
palette[2] = b'\x00\xFF\x00\x00'  # green
palette[3] = b'\x00\x00\xFF\x00'  # blue

Bitmap code example¶

bitmap = Bitmap(3, 2, 4)  # 3 pixels wide, two pixels tall, 4 colors
bitmap[0,0] = 0  # palette color 0
bitmap[0,1] = 1  # palette color 1
...

Example of Palette and Image¶

The example is 4bit.bmp from the examples/images folder:

The Palette object appears like this after loading:

Palette:
[0] b'\x00\x00\x00\x00'
[1] b'\x7f\x00\x00\x00'
[2] b'\xff\x00\x00\x00'
[3] b'w\x00\xb1\x00'
[4] b'\xff\x00\x9d\x00'
[5] b'\x00\x00\xff\x00'
[6] b'\xff\x00\xfe\x00'
[7] b'\xbf\x80\x00\x00'
[8] b'zzz\x00'
[9] b'\xff\x9e\xa5\x00'
[10] b'\x00\x98\xff\x00'
[11] b'\x00\xff\x00\x00'
[12] b'h\xff\x00\x00'
[13] b'\xfb\xff\x9e\x00'
[14] b'\x00\xfb\xff\x00'
[15] b'\xfb\xfb\xfb\x00'

This palette has 16 colors. The value in square brackets [] is the color’s index in the palette. The byte values are the RGB or RGB + padding of each color.

The Bitmap is an grid of which palette color to use in each position of the image.

The corresponding Bitmap to the example above appears like this after loading:

 5   5   5   5   5   5   5   5   5   5   5   5   5   5
 5   5   5   5   5   5   5   5   5   5   5   5   5   5
 5   5   5   5   5   5   5   5   5   5   5   5   5   5
11  11   5   5   5  15  15  15   5   5   5   2   2   2
11  11   5   5   5  15  15  15   5   5   5   2   2   2
 6   6   5   5   5   1   1   1   5   5   5  10  10  10
 6   6   5   5   5   1   1   1   5   5   5  10  10  10
 6   6   5   5   5   1   1   1   5   5   5  10  10  10
14  14   5   5   5   9   9   9   5   5   5   8   8   8
14  14   5   5   5   9   9   9   5   5   5   8   8   8
14  14   5   5   5   9   9   9   5   5   5   8   8   8
 3   3   5   5   5   0   0   0   5   5   5  13  13  13
 3   3   5   5   5   0   0   0   5   5   5  13  13  13
 4   4   5   5   5  12  12  12   5   5   5   7   7   7
 4   4   5   5   5  12  12  12   5   5   5   7   7   7
 4   4   5   5   5  12  12  12   5   5   5   7   7   7
 5   5   5   5   5   5   5   5   5   5   5   5   5   5

This grid represents the example image (15 pixels wide and 17 pixels tall). The coordinates are arranged in a zero indexed grid, starting in the top left at [0,0], and continuing down and to the right to a final coordinate of [14,16].

The value at each position is an integer, representing an entry in the palette object.

For example, the Bitmap coordinate [0,0] has the value (integer) 5.

This corresponds to the the Palette object’s, [5] which is b'\x00\x00\xff\x00'. This is a byte string that represents a color.