Skip to main content

Image Display (JPG / PNG / Animation)

A screen only ever shows pixels, never "files". The Beetle S1 image APIs split by how they decode: jpg() decodes and pushes in one go (simplest), png() streams row by row (lowest memory, supports transparency), and bitmap() shows a pre-converted bitmap (fastest). What people call "playing a GIF" is really just showing frame after frame as fast as possible, so this page gives three workable frame-by-frame approaches.

jpg() needs an explicit mode

The third argument is st7789.FAST (default) or st7789.SLOW. Use FAST for small images and SLOW for full-screen backgrounds.

The image must fit entirely

When the window runs past the screen edge the whole image is simply not shown (not half of it), and no error is raised.

png() uses the least memory

png() decodes one row at a time and needs only a single-row buffer, while jpg() needs room for the whole image.

Quick Start​

Copy the image to the SD card, say /sd/apps/myapp/logo.jpg, then:

import st7789
import tft_config

tft = tft_config.config(1) # 1 = landscape 240×135
tft.init()

tft.fill(st7789.BLACK)
tft.jpg('/sd/apps/myapp/logo.jpg', 10, 10, st7789.FAST)

What you'll see: the image with its top-left corner at (10, 10).

To fill the whole screen with one image, use this form, which covers the screen under any rotation:

tft.jpg('/sd/apps/myapp/bg.jpg', 0, 0, st7789.SLOW)

Displaying a JPG​

tft.jpg('/sd/apps/myapp/logo.jpg', 10, 10, st7789.FAST)

The first argument can be a file path string or a bytes buffer in memory (for example image data downloaded over the network).

Choosing FAST vs SLOW​

st7789.FAST (value 0)st7789.SLOW (value 1)
DecodingDecodes the whole image into memory, then pushes it in one windowDecodes and pushes one 8×8 (or 16×16) block at a time
Memory2 × width × height bytes, must be contiguous2 × (width rounded up to 8) × (height rounded up to 8) bytes
SpeedFaster for small images (one SPI transfer)Steadier for large images and full-screen backgrounds (block by block)
Best forIcons, frame-by-frame animationFull-screen backgrounds

Omitting the third argument defaults to FAST. The official light-painting app confirms exactly this split: SLOW for the full-screen background, FAST for small images.

tft.jpg('/sd/apps/light-painter/main.jpg', 0, 0, st7789.SLOW) # full-screen background
tft.jpg('/sd/image/photo.jpg', (tft.width() - 100) // 2, 20, st7789.FAST) # small image

The image must fit on screen​

This is the easiest trap to fall into. Before pushing pixels, the driver sets a display window, and a window that runs out of range is rejected as a whole:

  • FAST: the window is (x, y) to (x + width - 1, y + height - 1), so it needs x + width ≤ screen width and y + height ≤ screen height.
  • SLOW: each block sets its own window, and out-of-range blocks stay unpainted.

When that happens there is no error at all — the image does not appear at all, or part of the screen shows garbage. The Beetle S1 screen is only 135 × 240 (landscape 240 × 135), so this limit is easy to hit; compute the position with width() / height() before drawing:

w, h = 100, 100
x = (tft.width() - w) // 2
y = (tft.height() - h) // 2
tft.jpg('/sd/image/logo.jpg', x, y, st7789.FAST)

Displaying a PNG​

tft.png('/sd/apps/myapp/logo.png', 10, 10) # opaque, alpha ignored
tft.png('/sd/apps/myapp/logo.png', 10, 10, True) # transparency on: transparent pixels keep what's on screen

png() accepts only a file path (unlike jpg(), which also takes bytes). It decodes row by row and needs only a one-row buffer (image width × 2 bytes), so it is lighter than jpg() and suits large images.

The fourth argument is the transparency switch:

  • False (default): the alpha channel is ignored and transparent pixels are drawn opaque using their own RGB.
  • True: pixels with alpha 0 are skipped, so whatever is already on screen shows through — that is how you overlay a PNG icon on top of another background.

Pixels that land outside the screen are skipped without error.

Playing Frame-by-Frame Animation (GIF)​

The firmware has no built-in GIF decoder. To play an animation, split the GIF into still frames first (or generate bitmap frames with a tool), then loop over them with one of the three approaches below.

Approach 1: A sequence of JPG frames (simplest)​

Split the GIF into frame-0.jpg, frame-1.jpg, … on the SD card and loop:

import os
import time

import st7789
import tft_config

tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)

frame_dir = '/sd/apps/myapp/frames/'
frames = sorted(os.listdir(frame_dir))
delay = 0.05 # 50 ms per frame ≈ 20 fps

try:
while True:
for name in frames:
tft.jpg(frame_dir + name, 17, 70, st7789.FAST)
time.sleep(delay)
except KeyboardInterrupt:
tft.fill(st7789.BLACK)
  • Pros: no conversion needed; changing the frame rate is just changing delay.
  • Cons: every frame is decoded again, so high frame rates cannot keep up.
  • Best for: animations with many frames, each with few pixels.

Approach 2: jpg_decode() + blit_buffer() (decode and display separately)​

jpg_decode() turns an image into a pixel buffer you can blit straight onto the screen, and blit_buffer() places it anywhere. Good when one decoded frame is reused at several positions.

import time

import st7789
import tft_config

tft = tft_config.config(1)
tft.init()

# with no crop args, decode the whole image as (buffer, width, height)
frame, w, h = tft.jpg_decode('/sd/apps/myapp/hero.jpg')

for i in range(20):
tft.fill_rect(i * 6, 20, w, h, st7789.BLACK) # erase the previous frame
tft.blit_buffer(frame, i * 6, 20, w, h) # draw this frame
time.sleep(0.03)

With six arguments, jpg_decode(path, x, y, width, height) means which region to crop from the source image (not where to draw it), and the returned buffer is exactly width × height.

Watch your memory

In the driver source, every jpg_decode() call allocates 2 × width × height bytes and never frees it. Calling it repeatedly inside a loop will exhaust the heap. Decode once and blit_buffer() repeatedly, or use Approach 1 / Approach 3 instead.

Approach 3: Bitmap frames with bitmap() (fastest)​

Use the PC-side sprites2bitmap.py to pre-convert a sprite sheet into a Python module; at runtime there is no JPEG decoding at all, only palette expansion.

python3 sprites2bitmap.py frames.bmp 64 64 4 > sprites.py

The generated module carries WIDTH / HEIGHT / BPP / PALETTE / BITMAPS / BITMAP; copy it to the SD card and import it directly before handing it to bitmap():

import time

import st7789
import tft_config
import sprites # the bitmap frame module generated above

tft = tft_config.config(1)
tft.init()
tft.fill(st7789.BLACK)

while True:
for i in range(sprites.BITMAPS): # BITMAPS is the total frame count
tft.bitmap(sprites, 30, 30, i) # the third argument is the frame index
time.sleep(0.06)
  • Pros: no decoding at runtime, so the highest achievable frame rate.
  • Cons: needs a conversion step, and the whole frame sequence must fit in memory.
  • PALETTE entries must be byte-swapped RGB565 (the conversion script handles this; be careful if you write a module by hand).
  • A frame index beyond BITMAPS raises OSError: index out of range; omitting the index shows frame 0.

Drawing Text on a Background Image​

text() draws with only a foreground and background color and covers the background. To overlay text on a background image while keeping the background detail, use the bg_tuple and fill arguments of write():

import st7789
import tft_config
import NotoSans_32 as font

tft = tft_config.config(1)
tft.init()

tft.jpg('/sd/apps/myapp/main.jpg', 0, 0, st7789.SLOW) # 1. lay down the background

# 2. crop the patch of background where the text will go, sized to the font
bg, w, h = tft.jpg_decode('/sd/apps/myapp/main.jpg', 10, 10, font.MAX_WIDTH, font.HEIGHT)

# 3. write(font, text, x, y, fg, bg, (buffer, width, height), fill)
tft.write(font, "Hello", 10, 10, st7789.WHITE, st7789.BLACK, (bg, w, h), 1)

How it works (from the driver source): pixels whose glyph bit is 1 are painted with the foreground color, while bits that are 0 keep the background color at the same position from bg_tuple. With fill set to 1 each character is padded to the font's widest character width, which keeps the background patches aligned. The background buffer must be exactly font.MAX_WIDTH × font.HEIGHT.

write() uses fonts generated by font2bitmap (with MAX_WIDTH / WIDTHS / OFFSETS / BITMAPS) and cannot use fixed-width vga* fonts. See Font Library.

API Reference​

tft is the st7789.ST7789 instance returned by tft_config.config(), and every image API hangs off it.

jpg(src, x, y[, mode])​

tft.jpg(src, x, y, st7789.FAST)
ParameterTypeRequiredDescription
srcstr or bytesyesFile path, or JPEG data in memory
x / yintyesTop-left corner of the image on screen
modeintnost7789.FAST (0, default) or st7789.SLOW (1)

Returns None. Fails when the image is out of range or memory runs out (see the troubleshooting table).

png(filename, x, y[, mask])​

tft.png(filename, x, y, mask)
ParameterTypeRequiredDescription
filenamestryesFile path; paths only
x / yintyesTop-left corner
maskboolnoDefault False. When True, pixels with alpha 0 are skipped so the screen content shows through

Returns None. Row-by-row decoding keeps memory low.

jpg_decode(src[, x, y, width, height])​

buffer, width, height = tft.jpg_decode(src)
buffer, width, height = tft.jpg_decode(src, x, y, width, height)
ParameterTypeRequiredDescription
srcstr or bytesyesFile path or in-memory data
x / yintnoCrop origin in the source image, not a screen coordinate
width / heightintnoCrop size; the returned buffer has exactly these dimensions

Returns a 3-tuple (buffer, width, height): buffer is a byte-swapped RGB565 bytearray, ready to hand to blit_buffer(). Passing 1 argument (2 in total, counting self) decodes the whole image; any argument count other than 2 or 6 raises TypeError: jpg_decode requires either 2 or 6 arguments.

blit_buffer(buffer, x, y, width, height)​

tft.blit_buffer(buffer, x, y, width, height)

Copies an RGB565 pixel buffer to (x, y) on screen and requires all 6 arguments. The driver sends min(buffer length, width × height × 2) bytes, so an undersized buffer shows only part of the image without raising.

bitmap(bitmap_module, x, y[, index])​

tft.bitmap(bitmap_module, x, y, index)
ParameterTypeRequiredDescription
bitmap_modulemoduleyesMust define WIDTH, HEIGHT, BPP, PALETTE, BITMAP; multi-frame modules also need BITMAPS
x / yintyesWhere to draw
indexintnoFrame index, starting at 0, default 0

An index beyond BITMAPS raises OSError: index out of range; a frame whose x + WIDTH runs off screen is not drawn at all.

write(font, s, x, y[, fg, bg, bg_tuple, fill])​

tft.write(font, s, x, y, fg, bg, (buffer, width, height), fill)
ParameterTypeDefaultDescription
fontmodule—A font generated by font2bitmap
sstr—Text to draw
x / yint—Start coordinate
fgintWHITEColor for glyph bits set to 1
bgintBLACKColor for glyph bits set to 0 when there is no background image
bg_tupletuplenone(buffer, width, height), usually from jpg_decode()
fillint0When 1, each character pads out to the font's widest character width; use with a background image

Returns the number of pixels actually printed. Characters absent from the font are skipped silently.

Common Pitfalls​

PitfallCause and fix
The image never appearsx + width or y + height is off screen, so the window is rejected as a whole with no error → compute positions from width() / height()
Full-screen background does not fillThe image resolution does not match the screen (135 × 240 / 240 × 135) → make the image match the screen resolution, or cover the screen with an opaque full-size image
out of memory on a large imagejpg() needs 2 × width × height contiguous bytes → shrink the image, or switch to png()
Setting buffer_size makes init failbuffer_size is a resident buffer; anything smaller than what an operation needs raises OSError: buffer too small. N bytes required. → normally leave it at 0
jpg_decode() in a loop exhausts memoryThe driver never frees that allocation → decode once and blit_buffer() repeatedly, or use jpg(FAST) per frame
bitmap() shows garbage or wrong colorsPALETTE must hold byte-swapped RGB565 → generate with the matching sprites2bitmap.py / imgtobitmap.py
write() shows no textWrong font family: write() needs a font2bitmap library (with MAX_WIDTH), while text() takes fixed-width vga* fonts
Animation flickersClearing the whole screen before each frame → erase only the previous frame and draw only the new one, or overwrite with an opaque full frame
Frame-by-frame animation stuttersEvery frame decodes the JPEG again → shrink the frames, lower the frame rate, or switch to the bitmap-frame approach

Troubleshooting​

Error / symptomFix
TypeError: jpg_decode requires either 2 or 6 argumentsjpg_decode() accepts only 2 or 6 arguments (including self); to decode the whole image, pass no crop arguments
OSError: out of memoryThe image is too large; the 2 × width × height allocation for jpg() failed
OSError: buffer too small. N bytes required.The buffer_size set at init is smaller than this operation needs; enlarge it or set 0
OSError: index out of rangeThe bitmap() frame index is ≥ BITMAPS
RuntimeError: jpg prepare failed.Not a valid JPEG, or the path does not exist
RuntimeError: jpg decompress failed.Corrupted JPEG data
RuntimeError: png decompress failed: ...Corrupted PNG or an unsupported format
All black / garbageThe image is out of range (window rejected), or buffer_size does not match the image size
Only part of the image drawsThe blit_buffer() buffer is smaller than width × height × 2 → pass the w / h returned by jpg_decode() unchanged

Related modules: Display (ST7789) · Font Library · USB Serial Control (CDC)

AI usage (coming soon)​

Soon you won't need to remember the FAST vs SLOW difference or work out whether an image fits on screen: describe the picture you want in plain language, and the Agent will follow the APIs in this document to generate a complete program that runs on the Beetle S1.

For example, just tell it:

Show a full-screen background at boot, then loop a 12-frame animation in the bottom-right corner, and clear the screen on exit.

It will combine jpg(), jpg_decode() / blit_buffer(), and tft_config into a runnable program and place it under /sd/apps/ on the SD card.

Agent entry (coming soon)

The entry link will go here. Once it is live, one click takes you straight to describing the app you want.