Skip to main content

loading Images

This repo describes how to load and display images from the SD card to the TFT LCD screen on Wio Terminal. This can be very useful implementation to your design and can be used in various places!

Libraries Installation

Installing the SD Card library for Wio Terminal

Installing the TFT LCD Library For Wio Terminal

Image Format configuration

STEP 1: Prepare the image

We need to convert the image format to Windows 24-bit BMP format and put the image in the right folder setup ready. We recommend to use `Microsoft paint` to do so.
  • Step 1-1: Using Microsoft paint to resize the image to fit into the maximum pixel size of your screen display area

  • Step 1-2: Then save the image by clicking Save as followed by BMP picture then from the file type dropdown select 24-bit bitmap (.bmp) file.

  • Step 1-3: Create a folder name bmp and save your Windows .bmp format images inside this folder.

STEP 2: Convert the 24-bit bitmap image to the microcontroller readable 8-bit or 16-bit bmp format

To display bmp images on our embedded system, we need to get rid of some information (head files) in our Windows bmp format. We wrote a python script to do this for us, so please choose one of the following two options to convert you images.

Option 1: Using Prebuilt Windows Executables (Windows only):

  • Step 2-1-1: We have prepared the executable by using the Pyinstaller{target=_blank} package, you can download the executable by simply clicking bmp_converter.exe

  • Step 2-1-2: Put the downloaded bmp_converter.exe into the same directory with the bmp folder created in Step 1-3.

  • Step 2-1-3: Double click to run the bmp_converter.exe, then in the pop up terminal select one of the two options: "Enter 1 for 8-bit colour convert; Enter 2 for 16-bit colour convert".

Option 2: Using Python Source Code (for cross platform)

You should have python installed on your computer
  • Step 2-2-1: Download the Python script , and save it in the same directory with the bmp folder created in Step 1-3.

  • Step 2-2-2: Open cmd or terminal to run the Python script. First, cd to the directory that saved the and bmp folder, then run the Python script.

  • Step 2-2-3: Two options: Enter 1 for 8-bit colour convert; Enter 2 for 16-bit colour convert

STEP 3: Image ready

Now, you are able to find converted the .bmp images inside another folder name rgb332(8-bit) or rgb565(16-bit) in the bmp folder.

Getting Started

Install the RawImage.h library

This library is used to make loading and displaying images much easier. Download the RawImage.h and attach this header file to your sketch location.

Image Initialisation in Arduino

  • To display images on the screen
//To draw on 8-bit color image on screen, starting from point (x, y):
drawImage<uint8_t>("path to sd card iamge", x, y);

//To draw on 16-bit color image on screen, starting from point (x, y):
drawImage<uint16_t>("path to sd card iamge", x, y);
  • To initialise image (Not needed if using the above drawImage function)
//when using 8-bit colour, initialise the image following this:
Raw8 * img8 = newImage<uint8_t>("path to sd card image");

//when using 16-bit colour, initialise the image following this:
Raw16 * img16 = newImage<uint16_t>("path to sd card image");

Example code

# include"TFT_eSPI.h"
# include "Seeed_FS.h" //Including SD card library
# include"RawImage.h" //Including image processing library
TFT_eSPI tft;

void setup() {
//Initialise SD card
while (1);

drawImage<uint8_t>("test.bmp", 0, 0); //Display this 8-bit image in sd card from (0, 0)


void loop() {


If ImportError: No module named PIL happened:

  • Install the python module by entering pip install pillow in the cmd or terminal

Tech Support & Product Discussion

Thank you for choosing our products! We are here to provide you with different support to ensure that your experience with our products is as smooth as possible. We offer several communication channels to cater to different preferences and needs.

Loading Comments...