If you want to expand the capabilities of the CharliePlex LED Matrix even more, we can add Pillow into the mix. So we'll show you how to add Pillow and then go over a couple of examples that use Pillow.

Additional Setup

If you haven't already installed the library, follow the setup section on the Python & CircuitPython page. If you have, then continue.

DejaVu TTF Font

Raspberry Pi usually comes with the DejaVu font already installed, but in case it didn't, you can run the following to install it:

  • sudo apt-get install ttf-dejavu

Pillow Library

We also need Pillow, also known as PIL, the Python Imaging Library, to allow using text with custom fonts. There are several system libraries that PIL relies on, so installing via a package manager is the easiest way to bring in everything:

  • sudo apt-get install python3-pil

That's it. You should be ready to go.

Speeding up the Display on Raspberry Pi

For the best performance, especially if you are doing fast animations, you'll want to tweak the I2C core to run at 1MHz. By default it may be 100KHz or 400KHz

To do this, edit the config with sudo nano /boot/config.txt

and add to the end of the file

dtparam=i2c_baudrate=1000000

Reboot to 'set' the change.

Scrolling Marquee Example

The first example, we're going to take a look at an example that will take some text, draw it in a TrueType font and then scroll the rendered text. Let's start by looking at the code in each section.

We start by importing the libraries we need which include the board, a few Pillow modules, and the IS31FL3731 driver for the matrix itself.

Download: file
import board
from PIL import Image, ImageDraw, ImageFont
import adafruit_is31fl3731

Next we set a couple of variables. We have the SCROLLING_TEXT variable. Go ahead and change the text if you would like. It shouldn't matter how long, though you probably shouldn't make it too long if you want to see it loop. You can set BRIGHTNESS as well, in case you want to adjust the intensity.

Download: file
SCROLLING_TEXT = "You can display a personal message here..."
BRIGHTNESS = 64  # Brightness can be between 0-255

Next we do the basic setup for the display by declaring the I2C object and passing that into the display. If you have the breakout instead of the bonnet, you'll want to uncomment that and comment out the bonnet line.

Download: file
i2c = board.I2C()

# uncomment line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix
#display = adafruit_is31fl3731.Matrix(i2c)
# uncomment line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix
display = adafruit_is31fl3731.CharlieBonnet(i2c)

Next we go ahead and load up the Deja Vu font into an object. We are going with an 8 pixel high font because that's the largest we can fit on the display and still see everything.

Download: file
# Load a font
font = ImageFont.truetype('/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf', 8)

In this next part, we first start by getting the width and height of what the text would be when rendered with the font we chose. Then we create a virtual image of that width and height and draw the text onto it.

Download: file
# Create an image that contains the text
text_width, text_height = font.getsize(SCROLLING_TEXT)
text_image = Image.new('L', (text_width, text_height))
text_draw = ImageDraw.Draw(text_image)
text_draw.text((0, 0), SCROLLING_TEXT, font=font, fill=BRIGHTNESS)

Next we create a virtual image that's the same size as the display. This will be where we draw what we want to actually display.

Download: file
# Create an image for the display
image = Image.new('L', (display.width, display.height))
draw = ImageDraw.Draw(image)

Finally we get to our main loop. We start by drawing a rectangle to be sure we are not leaving any existing text behind. Then we paste our image of the text onto the image we are going to display using the value of x, which represents the left offset we want to use to give a nice scrolling effect. We have a for loop which will scroll the complete text plus empty display width by one iteration. That's all placed inside an infinite while loop for endless iterations.

Download: file
while True:
    for x in range(text_width + display.width):
        draw.rectangle((0, 0, display.width, display.height), outline=0, fill=0)
        image.paste(text_image, (display.width - x, display.height // 2 - text_height // 2 - 1))
        display.image(image)

Now go ahead and run the example code.

python3 is31fl3731_pillow_marquee.py

You should see the display showing a message scrolling from right to left.

Full Source Code

"""
Example to scroll some text as a marquee

This example is for use on (Linux) computers that are using CPython with
Adafruit Blinka to support CircuitPython libraries. CircuitPython does
not support PIL/pillow (python imaging library)!

Author(s): Melissa LeBlanc-Williams for Adafruit Industries
"""

import board
from PIL import Image, ImageDraw, ImageFont
import adafruit_is31fl3731

SCROLLING_TEXT = "You can display a personal message here..."
BRIGHTNESS = 64  # Brightness can be between 0-255

i2c = board.I2C()

# uncomment line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix
# display = adafruit_is31fl3731.Matrix(i2c)
# uncomment line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix
display = adafruit_is31fl3731.CharlieBonnet(i2c)

# Load a font
font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 8)

# Create an image that contains the text
text_width, text_height = font.getsize(SCROLLING_TEXT)
text_image = Image.new("L", (text_width, text_height))
text_draw = ImageDraw.Draw(text_image)
text_draw.text((0, 0), SCROLLING_TEXT, font=font, fill=BRIGHTNESS)

# Create an image for the display
image = Image.new("L", (display.width, display.height))
draw = ImageDraw.Draw(image)

# Load the text in each frame
while True:
    for x in range(text_width + display.width):
        draw.rectangle((0, 0, display.width, display.height), outline=0, fill=0)
        image.paste(
            text_image, (display.width - x, display.height // 2 - text_height // 2 - 1)
        )
        display.image(image)

Animated GIF Example

Next let's take a look at an animated GIF player example. First we'll start by downloading an animated GIF and copying that into the same folder as the script as adafruit-star-rotating.gif. It looks tiny and that's because it is. It is 8x8 pixels which works out nicely for the CharliePlex matrix.

Now let's start with the first section, the imports. You may be surprised that this code uses fewer Pillow modules than the previous example. We are also adding sys, which we mostly use for passing the name of an animated gif.

Download: file
import sys
import board
from PIL import Image
import adafruit_is31fl3731

Next we do the usual setup for the CharliePlex display.

Download: file
i2c = board.I2C()

# uncomment line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix
#display = adafruit_is31fl3731.Matrix(i2c)
# uncomment line if you are using Adafruit 16x9 Charlieplexed PWM LED Matrix
display = adafruit_is31fl3731.CharlieBonnet(i2c)

Now we make sure the user specified a gif file, so we have something to work with that's not hard-coded and open the file. If the file wasn't specified, we are using sys.exit(), since that is the preferred way to do it if you are importing sys anyways.

Download: file
# Check that the gif was specified
if len(sys.argv) < 2:
    print("No image file specified")
    print("Usage: python3 is31fl3731_pillow_animated_gif.py animated.gif")
    sys.exit()

# Open the gif
image = Image.open(sys.argv[1])

We need to check that this is an animated gif. While we could have just displayed it as a static gif in this case, the point was to show how to display the animation.

Download: file
# Make sure it's animated
if not image.is_animated:
    print("Specified image is not animated")
    sys.exit()

Next we get some gif animation information such as the delay. Only the duration of the first frame is extractable at the time of this writing with Pillow.

Download: file
# Get the autoplay information from the gif
delay = image.info['duration']

The loop number is a little trickier because it means different things between the IS31FL3731 chip and an animated gif. With an animated gif, it is guaranteed to play at least once and then loop by the number of times is provided by the loop value, unless it is zero, which means forever.

With the IS31FL3731, loops mean exactly the number of loops to play the animation, unless it is zero, in which case it will play forever.

So if loop is 0, we just pass it on. If we only want to play the animation once, then loop is not provided in the image information. If it is more than once, we need to count the first time it plays plus the number of times to loop the animation.

Download: file
# Figure out the correct loop count
if "loop" in image.info:
    loops = image.info['loop']
    if loops > 0:
        loops += 1
else:
    loops = 1

Next, we need to make sure these values are in the ranges that the driver likes. The number of frames in the animation is available from the property n_frames and the IS31FL3731 can handle a maximum of 8 frames, so if a longer animation is provided, only the first 8 frames are used.

Download: file
# IS31FL3731 only supports 0-7
if loops > 7:
    loops = 7

# Get the frame count (maximum 8 frames)
frame_count = image.n_frames
if frame_count > 8:
    frame_count = 8

Now that we have a frame count, we will go through each of those frames and load the frame image into the IS31FL3731 using the paste function and center the image. First the frame is converted to a 256-grayscale image, which is what mode L is, and then it is copied into a centered position, which is calculated from the difference in size between the display and image. After that, it is inserted as the current frame number.

Download: file
# Load each frame of the gif onto the Matrix
for frame in range(frame_count):
    image.seek(frame)
    frame_image = Image.new('L', (display.width, display.height))
    frame_image.paste(image.convert("L"), (display.width // 2 - image.width // 2,
                                           display.height // 2 - image.height // 2))
    display.image(frame_image, frame=frame)

Finally, we call the auto_play function using the delay and loop information from the animated gif.

Download: file
display.autoplay(delay=delay, loops=loops)

Now go ahead and run the example code.

python3 is31fl3731_pillow_animated_gif.py adafruit-star-rotating.gif

You should see the rotating star appear on the display.

This guide was first published on Mar 13, 2019. It was last updated on Mar 13, 2019.
This page (Python Examples) was last updated on Oct 25, 2020.