GIF to OLED Animation Converter

How an OLED animation actually works

There is no animation support in any of the common display libraries. An SSD1306 has no frame buffer of its own beyond the single screen it is showing, and no concept of a timeline. What you call an animation is your sketch drawing one still bitmap, waiting, drawing the next one, and repeating. Everything this tool produces serves that loop: a list of bitmaps and the delay between them.

That framing explains the two things people get stuck on. The first is memory, because every frame is stored in full, uncompressed. The second is speed, because pushing a frame to the panel takes real time on the I2C bus and that time sets your ceiling on frames per second.

Working out the memory cost before you compile

A monochrome frame costs one bit per pixel, so a full screen 128x64 animation is 128 × 64 ÷ 8 = 1024 bytes per frame. The arithmetic from there is unforgiving:

• 10 frames at 128x64 = 10 KB
• 30 frames at 128x64 = 30 KB, already past an Uno's entire flash
• 30 frames at 64x32 = 7.5 KB, comfortable

An Arduino Uno has 32 KB of flash and the bootloader takes about 0.5 KB of it. Adafruit_SSD1306 with Adafruit_GFX costs roughly another 10 KB once you use text. That leaves something near 20 KB for your animation and the rest of your program, which is why the panel on this page warns well before the theoretical limit.

The single most effective saving is not fewer frames, it is a smaller drawing area. Halving both dimensions quarters the cost. A pair of animated robot eyes rarely needs the full panel: a 64x32 region placed in the middle of the screen looks the same and costs a quarter as much.

Note also that the arrays must be marked PROGMEM. Without it the compiler copies them into SRAM, and an Uno has 2 KB of that in total, so even two full frames will not fit. The checkbox above is on by default and the generated sketch reads the frames back with pgm_read_ptr(), which is the matching half of that decision.

Frame rate and the I2C bottleneck

A 128x64 frame is 1024 bytes, and I2C at the default 100 kHz moves roughly 10 KB per second once the protocol overhead is counted. That works out at about 90 ms per frame, or 11 frames per second, before your own code has done anything. If your animation looks slower than the GIF did, this is usually why rather than the delay you set.

Raising the bus with Wire.setClock(400000) takes it to roughly 40 frames per second, which is past what the eye needs. Most SSD1306 modules handle 400 kHz without complaint; if you see corruption, your pull-up resistors or wire length are the limit rather than the controller. An SPI display avoids the question entirely, since SPI runs an order of magnitude faster.

Choosing the right output format

The same pixels can be packed three different ways and picking the wrong one produces a recognisable failure, which makes them easy to diagnose.

Adafruit GFX stores pixels row by row, eight per byte, with the most significant bit on the left. Use it with display.drawBitmap(). This is the default and the right answer for most projects.

U8g2 XBM uses the same row layout but reverses the bit order inside each byte, because that is what the X11 bitmap format did. Use it with u8g2.drawXBMP(). If your image comes out mirrored in horizontal blocks of eight pixels, you have picked the wrong one of these two.

Raw page format matches how the SSD1306 controller stores its own memory: vertical pages of eight rows, one byte per column. It lets you memcpy a frame straight into the library's buffer and skip the per-pixel drawing loop, which is noticeably faster. The cost is that it only works at position 0,0 at the panel's exact size. If your picture appears sliced into horizontal stripes, you have used a vertical array where a horizontal one was expected.

Getting a good looking 1 bit image

A monochrome panel has no grey. Every pixel is on or off, so a photographic source has to be reduced, and how you reduce it matters more than the source resolution.

Hard threshold keeps everything above the cutoff and discards the rest. It is the right choice for line art, logos, text and pixel art, which is most of what ends up on these displays. Adjust the threshold slider until the shape reads clearly.

Floyd-Steinberg spreads the error from each pixel into its neighbours, producing the fine grain that makes photographs readable. On an animation it has one drawback: the grain changes completely between frames, which the eye reads as noise. If your animation looks like it is boiling, switch to a hard threshold.

Bayer uses a fixed 4x4 matrix, so the pattern stays still between frames. That makes it the better dithering choice for animation specifically, even though a single still frame usually looks better under Floyd-Steinberg.

Frequently asked questions