Display a Bitmap

Make sure you have the latest CircuitPython firmware loaded for your board to use displayio. You can download it from the link below.

This example shows how to load and display a bitmap (.bmp) file. We will still need to create all the pieces - a TileGrid, a Group, etc. But they can be used in their most simple way.

OnDiskBitmap

First, let's use OnDiskBitmap to source the bitmap image directly from flash memory storage. This is like reading the image from disk instead of loading it into memory first (we'll do that next). The trade off here is the reduced use of memory for potentially slower pixel draw times.

We'll use a 320x240 pixel image. Here's the image:

Here's the code:

Download: file
import board
import displayio

display = board.DISPLAY

# Open the file
with open("/purple.bmp", "rb") as bitmap_file:

    # Setup the file as the bitmap data source
    bitmap = displayio.OnDiskBitmap(bitmap_file)

    # Create a TileGrid to hold the bitmap
    tile_grid = displayio.TileGrid(bitmap, pixel_shader=displayio.ColorConverter())

    # Create a Group to hold the TileGrid
    group = displayio.Group()

    # Add the TileGrid to the Group
    group.append(tile_grid)

    # Add the Group to the Display
    display.show(group)

    # Loop forever so you can enjoy your image
    while True:
        pass

ImageLoad

This approach use the CircuitPython Image Load library to load the image into memory and then display it. Using the same image from above, here's the code:

Download: file
import board
import displayio
import adafruit_imageload

display = board.DISPLAY

bitmap, palette = adafruit_imageload.load("/purple.bmp",
                                         bitmap=displayio.Bitmap,
                                         palette=displayio.Palette)

# Create a TileGrid to hold the bitmap
tile_grid = displayio.TileGrid(bitmap, pixel_shader=palette)

# Create a Group to hold the TileGrid
group = displayio.Group()

# Add the TileGrid to the Group
group.append(tile_grid)

# Add the Group to the Display
display.show(group)

# Loop forever so you can enjoy your image
while True:
    pass
This guide was first published on Apr 30, 2019. It was last updated on Apr 30, 2019.
This page (Display a Bitmap) was last updated on Aug 14, 2020.