How to display your own custom image on a small OLED screen using our free tool

We're often asked 'How do we get those cool images on our tiny OLED screens?' Now you can have them too with our free Online Image To Code Tool.

This article is brand new, images are coming soon!!

• Video
• Overview
• Benefits
• Grab All Our Code And Sample Images
• Image To Code Tools
  • Our Online Encoder
  • The Command Line Tool
  • Our Online Decoder
• How To Display The Image On Your Project
  • How Does It Work
    • Convert Image To Code
    • Convert Code To Image
• Base64 Encoding - How does it work?

Video#

Overview#

In this article we show you how to put your own image on a tiny OLED screen using our free tool.

We used this approach in Pico Pong to put the logo onto an SSD1306 in MicroPython but you can use your coding language and screen of choice.

You take your image, drag it on the tool and copy the code it produces into your project. We give you MicroPython and CircuitPython example code.

We will explain exactly how everything works. We will also explain to you Base 64 encoding.

Benefits#

It's very handy to encode an image as a simple string we can put in our code. No need to load and save image files, it's quick and easy.

We tried using a binary array (you'll see that on the command line tool) but this makes the source code too long. Turning it into a Base64 encoded string is much shorter.

Grab All Our Code And Sample Images#

We have bundled up some sample images, and sample code to display the images. We also have included the command line tool to convert images to code.

Click here to Download all our code, sample images, and terminal command or open a terminal and type:

git clone https://github.com/gurgleapps/image-to-code.git

Image To Code Tools#

We have an online tool where you can drag and drop, copy and paste. We also have a command line tool written in python you can have on your own machine, and tinker with the code.

Our Online Encoder#

Here is the Link to our online encoder. Just drag your image into the box. It should now appear below with a little thumbnail.

Click convert and it will convert your image into (Base64 encoded) text. Copy the text in the box below your image.

The Command Line Tool#

You will find the command line tool bundled in . our image to code Github repo

You can add the path to the tool in your PATH environment variable or just open a shell and navigate to the folder with the convert_image.py script you downloaded.

Now if you run the terminal command:

./convert_image.py

you will probably get this error:

zsh: permission denied: ./convert_image.py

All this is saying is you don't have permission to execute/run this command.

To fix this just type:

chmod a+x convert_image.py

The a stands for all and the x stands for execute. So this will give everyone on your computer the permission to run this command. now run it again but pass it a path to your image as shown below:

./convert_image.py path_to_image.png

Copy from after where it says Base64 decoded to the end.

Take a look at the code in the script if you like and see how it works.

Our Online Decoder#

Curious about the code you just produced?

Here is the Link to our online decoder. You don't need this to get your image onto your screen but it's a nice way to understand what's happening. Just simply paste you Base64 Encoded string into the text box and below you can convert that into different number bases like binary for example! Soon you'll understand where all the numbers come from.

How To Display The Image On Your Project#

You will find sample code for MicroPython and CircuitPython bundled in . our image to code Github repo

We used SSD1306 & SSD1305 screens and it worked great, it's easy to modify for other screens and languages.

The code will make much more sense if you know the simple method we use to encode and decode the images.

How Does It Work#

Convert Image To Code#

Your images is converted into a list of bytes (8 bits which are 1's or 0's). The first byte is the width of the image, the next is the height.

Then we read the 1st 8 pixels horizontally from the top left of your image. On is 1 off is 0 and these make up the next byte.

The next 8 pixels make up the next byte and we keep going until we reach the end of the screen then move onto the next row. We repeat this until you image has turned into a list of bytes.

Now we Base64 encode the bytes. We will explain how this works but all you need to know is the bytes turn into letters.

Convert Code To Image#

Now we reverse the process and turn the Base64 encoded list of bytes from letters back into bytes.

Then we read off the width and height of the image which is the 1st 2 bytes.

Then we read the 3rd byte to get the 1st 8 pixels and draw them into our image, then grab the next byte and repeat until our images has been reconstructed.

Base64 Encoding - How does it work?#

This is so simple, and used a lot. When you send an email attachment it's Base64 encoded for the exact same reasons we use it for our images.

You line up your list of bytes to make one long list of bits (0s and 1s). Then you collect up the bits in groups of 6 instead of groups of 8 (bytes).

There are 64 possible combinations for 6 0s and 1s and each combination has a letter assigned. So each 6 bit group is turned into a letter.