Phase 5: Drawing Graphics — Shapes, Scenes, and Animation

Part of the Pico OLED project: start here and see all phases.

Where This Lesson Fits

In Phase 3, we mapped a coordinate to a byte and a bit. In Phase 4, we separated drawing in Pico RAM from sending that image with show().

Now we can build something with those ideas. How do a few drawing commands become a scene—and how does a sequence of scenes become movement?

Today’s goal is to assemble one complete picture, then change one part of it across several frames. We will keep using the supplied driver. Opening its classes is Phase 6.

Start with One Moving Shape

A frame is one complete still image. In an animation, we display successive frames with small changes between them. A square can appear to move right when we turn off its old pixels and light pixels farther right in the next image.

Try stepping through those images before writing a loop. The toy sends each frame for you; its code panel shows the drawing commands that produced the current picture.

Q1: What makes a trail?

Problem: Step through three frames with clearing enabled. Reset, turn clearing off, and repeat. What stays in the second version’s memory?

Get Ready on the Pico

Download the Phase 5 graphics lab . Only setup is executable; the rest contains instructions for code you write yourself. The lesson link is at the top.

Keep ssd1306.py in the same folder on the Pico as the lab file. Upload the driver from the Phase 1 kit if needed. Use the same wiring as before.

Run setup using MicroPico in VS Code or Thonny. Enter short experiments at the Pico’s >>> prompt or Thonny’s Shell. Write complete functions and animation loops in the lab file, then run the file with setup. Our loops will finish by themselves.

In VS Code, first read the grey Python-session note in Phase 4. It explains how to keep names such as oled available after running setup. No input() pauses are needed here.

Learn the Drawing Tools

A drawing primitive is a basic operation we can combine with others: a pixel, a line, a rectangle, or text. All the drawing operations below edit the same frame buffer. After preparing a picture, call oled.show() to display it.

For this monochrome display, 1 draws lit pixels and 0 draws dark pixels. Zero is useful as an eraser inside a larger picture.

The line methods are described in the MicroPython drawing reference; fill_rect() is also provided by the frame-buffer implementation.

Coordinates and Sizes Have Different Jobs

In rect(10, 20, 12, 8, 1), (10, 20) is the top-left corner. The next two numbers are a width of 12 pixels and a height of 8 pixels. They are counts, not the opposite corner.

Starting at column 10, twelve columns end at 10 + 12 - 1 = 21. The last row is 20 + 8 - 1 = 27.

right edge  = x + width - 1
bottom edge = y + height - 1

Q2: Do these two lines occupy the same pixels?

Problem: Compare oled.line(4, 12, 11, 12, 1) with oled.hline(4, 12, 8, 1). Predict the occupied columns and number of pixels, then test each on a cleared frame.

oled.fill(0)
oled.line(4, 12, 11, 12, 1)
oled.show()

Q3: What changes when a rectangle is filled?

Problem: Draw rect(10, 20, 12, 8, 1), then draw fill_rect(10, 20, 12, 8, 1) on a separately cleared frame. Find the last occupied column and row. Does filling change those bounds?

oled.fill(0)
oled.rect(10, 20, 12, 8, 1)
oled.show()

Q4: Where can an 8 × 8 square fit?

Problem: Find the largest top-left x and y that keep an 8 × 8 square completely inside a 128 × 64 display.

x + 8 - 1 ≤ 127  →  x ≤ 120
y + 8 - 1 ≤ 63   →  y ≤ 56

oled.fill(0)
oled.fill_rect(120, 56, 8, 8, 1)
oled.show()

Add Text and Compose a Scene

The built-in text font uses 8 × 8 character cells. A four-character word therefore occupies a 32-pixel-wide text area. The coordinates passed to text() locate the area’s top-left corner. These are the dimensions of the character cells; individual letters can have blank space inside them. See MicroPython’s text reference.

Drawing order matters too. A later operation can overwrite earlier pixels. Clearing after drawing a heading erases that heading. Clearing first, then adding every part, prepares a complete scene.

Q5: Can you center PICO?

Problem: Center the text area for PICO horizontally on our 128-pixel-wide display. Put its top at y = 4. Calculate x before drawing it.

text width = 4 × 8 = 32
remaining width = 128 - 32 = 96
left margin = 96 ÷ 2 = 48

oled.fill(0)
oled.text("PICO", 48, 4, 1)
oled.show()

Q6: Can several primitives make one picture?

Problem: Prepare a scene with a border around the full screen, the centered PICO heading, a ground line from (4, 56) to (123, 56), and a filled 8 × 8 square at (12, 28). Send the finished scene once.

oled.fill(0)
oled.rect(0, 0, 128, 64, 1)
oled.text("PICO", 48, 4, 1)
oled.line(4, 56, 123, 56, 1)
oled.fill_rect(12, 28, 8, 8, 1)
oled.show()

Describe the Scene with One Changing Value

To move the square, its x-coordinate must change between frames. The heading and ground can stay at fixed positions. The changing value is part of our program’s state.

A function can describe the whole scene using an argument such as x. Calling draw_scene(12) prepares the square at x = 12; calling draw_scene(16) prepares it four pixels farther right.

If the function clears the buffer, it must redraw the background too. The OLED can keep showing the previous frame while the Pico prepares the replacement. We will leave show() outside the function so drawing and sending remain separate.

Q7: Can one argument move only the square?

Problem: Turn Q6’s drawing code into draw_scene(x). Make the square’s x-coordinate depend on the argument, and keep the other positions fixed. Prepare and display the scene at x = 12, then at x = 16.

def draw_scene(x):
    oled.fill(0)
    oled.rect(0, 0, 128, 64, 1)
    oled.text("PICO", 48, 4, 1)
    oled.line(4, 56, 123, 56, 1)
    oled.fill_rect(x, 28, 8, 8, 1)

draw_scene(12)
oled.show()
# STOP: inspect the scene before entering the next pair.
draw_scene(16)
oled.show()

Turn Frames into Animation

Now repeat that process with a loop:

choose a position → prepare the whole frame → show it → pause
        ↑                                                   |
        └──────────────── next position ────────────────────┘

range(start, stop, step) produces positions starting at start, stopping before stop, and changing by step. For example, range(0, 121, 4) gives 0, 4, 8, …, 120. It finishes, so we can inspect the last picture afterward.

sleep_ms(100) pauses for at least 100 milliseconds; 1,000 milliseconds make one second. The starter imports it from time. Drawing and sending also take time, so a 100 ms pause alone does not guarantee ten frames per second. See the MicroPython timing reference.

Q8: Can you animate the scene across the screen?

Problem: After defining draw_scene(x), write a finite loop that moves the square from x = 0 to x = 120 in steps of four, displaying every frame and pausing 100 ms after each transfer. How many frames does it send?

for x in range(0, 121, 4):
    draw_scene(x)
    oled.show()
    sleep_ms(100)

Q9: What happens if you stop clearing?

Problem: Remove oled.fill(0) from draw_scene(x) and rerun the animation, starting from a cleared image. Predict what remains behind the square. Then restore clearing.

Q10: How can you slow the same movement?

Problem: Keep the same positions and change only the pause from 100 ms to 200 ms. Which parts of the animation stay the same? How much total deliberate pause does each version contain?

31 × 100 ms = 3,100 ms = 3.1 seconds of pauses
31 × 200 ms = 6,200 ms = 6.2 seconds of pauses

Q11: Why is this animation one frame behind?

Problem: Begin with a blank buffer and display, then run this code. What does the first show() send? After the loop finishes, where is the square in RAM and where is it on the OLED?

oled.fill(0)
oled.show()

for x in range(0, 9, 4):
    oled.show()
    draw_scene(x)
    sleep_ms(100)

Make Your Own Scene

Q12: Can you explain and animate a scene you designed?

Problem: Create a scene with a short heading, at least two kinds of drawing primitive, and one moving part. Sketch it first. Choose safe movement bounds and use a finite loop. Explain which values change and why the background remains visible.

Next: The SSD1306 Driver

We can now combine drawing primitives, prepare a scene with a function, and animate it by changing state between transfers. Where do pixel(), rect(), and text() actually come from? Why does the driver contain show() but so little drawing code?

Phase 6 will open ssd1306.py and follow how its classes share work with MicroPython’s frame-buffer tools.

Back to Phase 4: The Frame Buffer ← · See the full project roadmap

Glossary