M5Stack image formats
I recently started to getting familiar with my M5Stack M5Core device. I installed M5ez and had a look at the image menu. It supports JPEG files from FLASH memory and SD card.
I wanted to display circle shaped images on the screen - like this:
It is a PNG file with transparent background. The problem is that JPEG files don’t support transparency, so when I converted my original file, it was displayed like this:
It looks ok, if the dark M5ez theme was used, but it looks ugly when the theme was switched to default.
I wanted to have a good looking solution, so I investigated the various image formats supported by the M5Stack LCD API
M5Stack image formats
According to the documentation, M5Stack Arduino API supports the following image formats:
From these file formats only PNG supports transparency.
The XBMP file format is a binary format. It means that the images are displayed in two colors - one background and one foreground.
The PNG file type support is not documented on the API, but it is available on the code level.
M5Stack storage types
The images can come from these two places:
- Memory
- File
Memory means Flash memory. It means that the image data was transformed into an array and stored in a C header file, which will be included into the main program.
1 | // Image data in FLASH memory |
File is the original image file. It is usually stored on an SD card.
Storage type restrictions
In M5Stack the following storage type restrictions applies:
Memory
The following file formats can come from FLASH memory:
In case of BMP the color code is expressed by a total of 16 bits: red 5 bits, green 6 bits and blue 5 bits from the top. It means only 16 bpp (bit per pixel) BMP files are supported.
The following online converter tools are recommended:
File
The following file formats can come from an SD card:
Please note that only 24 bpp (bit per pixel) - True Color - BMP files are supported!
M5ez support
At the time of writing M5ez only supports the JPEG file format. I thought that it would be great that the other file formats become available as well. I implemented the required changes in my GitHub fork. Of course I will contribute these back to M5ez in a pull request.
I also created an example called M5images, which displays an image menu with all the available M5Stack file formats and storage types.
My experiences
Just go back to the original problem, where I wanted to display a circle shaped image with transparent background.
Of course I can put the original PNG file onto an SD card and display it in the menu. There are two problems with this approach:
- Application distribution
- Speed
Once you build your application in Arduino, you just put all files into a single directory. These files then can be compiled and uploaded by Arduino IDE onto your microcontroller development board like the M5Stack M5Core device.
If something has to be installed onto the SD card prior to these steps, it just introduces complications and further error conditions for the end users.
The obvious solution is to store those images, which are essential part of your application in the Flash memory. The downside of this solution is the limited capacity of the Flash memory compared to the SD card.
Transparent background is only supported by the PNG file type. It means that Flash memory is not an option, so the files have to be placed onto an SD card.
Once it is done and the application is started, speed will be a problem. The PNG files are loaded quite slowly from SD card. M5Stack renders these images with a considerable delay. You can spot the scrolling load on the UI. It means no go for frequently used places - like menus - in the application.
XBMP was ruled out at the first place, because its binary nature. Two color images just look ugly.
There are two options left:
Both of them are non transparent image types, so this problem has to be solved later.
In case of BMP the ImageConverter (UTFT) produces some alterations on the input images:
- Cut down rounded edges
- Distort the image
- Change some colors
After the image conversion the end result is not looking as good as the original PNG file.
At the end the only remaining option is the usage of the JPEG file format. M5Stack displays JPEG files quite fast from memory and SD card.
I solved the transparency issue with two images for the two themes:
- Default - #EFEFEF (RGB888) = 0xEF7D (RGB565) as the background color
- Dark - #000000 (black) as the backgound color
Image conversion
I recommend the Free Online Converter in order to create BMP files in variable bbp (bits per pixels) rate.
I used Ezgif.com PNG to JPEG converter.
The images in the M5images example comes from IconArchive free image collection.
