One of the example projects for the Adafruit_Protomatter library (Arduino environment) is an animated GIF player. The previously-mentioned Python script doesn’t handle animated GIFs, but there’s another tool — ImageMagick — that may be able to help.

ImageMagick is a free command line tool for image conversion, available for most popular systems. The download page for ImageMagick explains a few different ways to access the software. We’ll assume here you have ImageMagick installed and working on your system.

Sometimes the different ports of ImageMagick aren’t in perfect sync, and commands that work in one environment aren’t available in another. The steps we’ll go through here worked on a Mac but might not work the same on Windows. If you encounter incompatibility, check that you’re running the latest available for your platform, or consider a nearby Linux system (e.g. Raspberry Pi) if you have access to one.

If Image Already Matches Matrix Pixel Dimensions…

…it’s fairly straightforward, ImageMagick’s “gamma” command will pull down the brightness:

convert in.gif -coalesce -gamma 0.4 -dispose None -interlace None -ordered-dither o4x4,32,64,32 -layers OptimizeFrame out.gif

You can adjust the 0.4 down (darker) or up (lighter) to get things dialed in just right for the matrix. Usually 0.4 works fine though.

The “-ordered-dither” part is optional. This adds dithering to recover some of the detail otherwise lost during the gamma adjustment.

The coalesce/dispose/interlace settings are to ensure better compatibility with the AnimatedGIF library. It doesn’t support interlaced GIFs, a reasonable tradeoff to allow handling arbitrarily long or complex animations.

If Image Does Not Match Matrix Size…

Let’s suppose we had an animated GIF of the classic Amiga juggler demo, and we want to prepare this for the RGB matrix.

The GIF, at 320x200 pixels, is much larger than the matrix. And the 16:10 aspect ratio doesn’t match.

One option is to scale the whole image to fit the matrix, disregarding the pixel aspect ratio. If there’s a significant change to the aspect ratio, distortion will be apparent, but the full frame will be used.

For a 64x32 pixel matrix:

convert juggler.gif -coalesce -gamma 0.4 -resize 64x32\! -dispose None -interlace None -ordered-dither o4x4,32,64,32 -layers OptimizeFrame out.gif

This should be entered as a single unbroken line, regardless how it may be formatted in the web browser. Change the input and output filenames to suit your needs.

The reference to 64x32 is the matrix pixel dimensions…change this if using a larger or smaller matrix. The \! tells ImageMagick to scale/stretch to this size absolutely, regardless of distortion it may incur. The o4x4,32,64,32 is not related to the matrix size…keep that part intact!

To maintain the original pixel aspect ratio instead, cropping the image as necessary:

convert juggler.gif -coalesce -gamma 0.4 -resize 64x32^ -gravity center -extent 64x32 -dispose None -interlace None -ordered-dither o4x4,32,64,32 -layers OptimizeFrame out.gif

Now there’s two 64x32 references to the matrix pixel dimensions…change both for different matrix sizes. The ^ on the first one means we’ll be cropping to this size, not distorting. Do not change the o4x4,32,64,32, regardless of matrix size.

The resulting GIFs will look dark on your computer (left). But played back on the LED matrix (simulated on the right), it will more closely match the original’s colors and brightness:

This guide was first published on Oct 19, 2020. It was last updated on Mar 08, 2024.

This page (Animated GIFs using ImageMagick) was last updated on Mar 08, 2024.

Text editor powered by tinymce.