Source: https://mokxi.com/docs/editor/image-on-a-display Updated: 2026-11-08 The editor # Show an image on a MicroPython display Turn a PNG or JPG into the Python module that a display driver's bitmap() draws. Open the editor All the docs ### Contents Start here The editor The sidebar and the editor's pages Placing parts Wiring Sticky notes Drawing on the canvas Tidying up Pinned comments Frames Schematic view PCB view Reusable blocks Chips made from parts Custom chips written in C The code editor and compiling Writing assembly Show an image on a MicroPython display Run and the serial monitor The serial plotter Operating point, sweeps and frequency response The logic analyzer tab The debugger Mokxi AI, Mokxi's helper The AI Builder WiFi, simulated Real internet Blynk, simulated Bluetooth, simulated ESP-NOW between boards The properties panel Undo, copy and paste Keyboard shortcuts Customize: code themes, colors and the toolbar Saving and autosave Sharing a project Embedding a circuit on another site Export and download Send a program to a real board VS Code and GitHub with Mokxi Run a prebuilt firmware SPICE netlists in Mokxi Working on a phone Install it as an app Boards Parts Accounts and plans Live collaboration Classrooms Lessons and the learning game Hobby builds Troubleshooting Reference Docs / The editor / Show an image on a MicroPython display Mokxi team ยท The editor ## Why a plain image file will not do Russ Hughes' display drivers (gc9a01py, st7789py and the ILI9342C one) draw a picture with tft.bitmap(module, x, y). The module has to hold WIDTH, HEIGHT, BPP, a PALETTE and a BITMAP, which is what his imgtobitmap.py writes. A file with only WIDTH, HEIGHT and a block of data stops with "module has nothing called BITMAP", on Mokxi and on a real board alike. Mokxi makes the right file for you. ## Make the module - Open a MicroPython project (a board with a main.py). A CircuitPython project's + asks for a file name only. - Click + in the file tabs and choose Add image as bitmap. - Pick a PNG or JPG. - Set the Width and Height. Changing one changes the other so the picture keeps its shape. They start at the biggest size that fits 240 x 240, or the display in your circuit when it has one. - Choose the Colors: 2, 4, 16 or 256. More colors look better and take more room: a 70 x 70 picture is 613 bytes at 1 bit a pixel in 2 colors, and 4,900 bytes at 8 bits a pixel in 256 colors. - Check the preview, change the file name if you like, and press Add to project. The new .py opens in its own tab. Nothing is uploaded: the picture is read and shrunk in your browser. ## Draw it Copy the driver into the project the way you do for any library, then import the new module next to it. For a round GC9A01 display: The picture has to fit on the display from the x, y you give: a driver draws nothing, or too much, when it does not. ## If the colors look wrong The palette is stored as the C drivers read it, with the two bytes of each color swapped. st7789py reads it that way when its needs_swap is on, and shows the bytes the other way around when it is off. If red and blue trade places on your display, that is the swap. The same driver and file behave the same on a real board. The published gc9a01py computes the two bytes of each pixel in bitmap() with a mistake in one line (color & 0xff00 >> 8 groups as color & 0xff), so its low byte is the palette index rather than part of the color. That shows as slightly wrong shades. Changing those two lines to buffer[i] = color & 0xff and buffer[i + 1] = color >> 8 fixes it. Previous: Writing assembly Next: Run and the serial monitor ### On this page Why a plain image file will not do Make the module Draw it If the colors look wrong ### Other guides Run and the serial monitor What Run actually does, what the readout means, and how to talk to a board. The serial plotter Graph the numbers your sketch prints, in the Plot tab beside Serial. Operating point, sweeps and frequency response Three readings one probe will not give you: every node's voltage at once, what a node does as you turn something, and what the circuit does at every frequency.