gifio is the new animated GIF module added to CircuitPython in version 8.1.0-beta.1 and later builds. It will not work with earlier versions. It provides methods to write and read animated GIF files. This guide will show how to read files and display them on an attached LCD display.

Constraints

The gifio module is limited to working with images that are 320 pixels wide or less. The height is not specifically limited but very tall GIF's may run out of memory. Smaller dimensions are fine and will likely speed code execution on a smaller data set.

The GIF speed (time between frames) should be at least the time it takes the microcontroller to process and display one frame. You can benchmark this on your setup but generally the time between frames should be 4/100th of a second or longer. 7/100th of a second second or longer is likely better. A check in the code is best to ensure the GIF display function is passed a value greater or equal to zero, zero being "as fast as possible".

Usage

Our two example boards have integrated displays, such that board.DISPLAY is defined and connected via a defined display bus.

There are two methods for writing to the display: using the CircuitPython displayio module and writing to the display directly. There are times where one over the other may be desired. If using an entire display, the direct method is likely fastest, while if animation is in a displayio.Tilegrid, and a partial part of a display will be used for playback, displayio will be the route, although there will be slowdowns due to display code overhead to consider.

gifio.OnDiskGif Constructor

This constructor creates an OnDiskGif object. You use that object to load one frame of a GIF image file into memory at a time.

The code can be used in cooperation with displayio but this mode is slower than writing directly to the display.

Parameters for the function are:

• File name: (required) The name of a file in the CircuitPython file system (most often on the CIRCUITPY drive for speed). 

The next_frame() function is used to advance to the next frame in the animated GIF.

The deinit() function is used in conjunction with ensuring memory allocated by the OnDiskGif object is freed properly (important if multiple files are displayed or other memory activity is done.

Issues

The library may not take into account the file size, so long GIFs should be cut into segments perhaps and read sequentially using the multi GIF method.

Error with memory allocation are indicative of a file size issue. Try a file with a smaller size for testing.

GIF files may be edited for size, frame duration, and length in a GIF file editor. The free web-based https://ezgif.com/ does well.