PixelMaestro – An Open Source Animation Library

This is the first public release of PixelMaestro, a C++ library for generating 2D animations!

Wait, what is this exactly?

PixelMaestro is a software library for designing and rendering multicolored animations on a 2D grid. It started while I was learning how to light strands of RGB LEDs using tiny, low-power computers. While it’s still a small hobbyist project, it’s developed into a general purpose tool for creating animated displays on any scale.

How does it work?

PixelMaestro is based on the concept of a grid of points, or Pixels, which are arranged into rows and columns. Each Pixel can display a single Color at a time. A collection of Pixels is known as a Section, and every Section is controlled by a single Maestro.

  • A Color defines a single color. It consists of a Red, Green, and Blue (RGB) value that, when combined in different ways, can create over 16 million distinct colors.
  • A Pixel represents a single point on a 2D grid. A Pixel’s current Color is determined by the current animation.
  • A Section is a group of Pixels logically arranged into rows and columns, although the actual physical layout of the Pixels doesn’t matter. Sections are responsible for tracking the state of the current animation, as well as setting each Pixel’s Color.
  • A Maestro is a group of Sections. Maestros simply control the state of multiple Sections, such as updating each Section and starting or pausing each Section.
  • A Show is an optional addition that dictates instructions to a Maestro over the course of the program. These instructions can be anything from changing the speed of the animation, to changing the animation itself to, changing the color scheme. Each of these instructions is called a Transition, and a Transition triggers when the program has been running for an amount of time that you specify for the Transition.

You start by defining a Maestro, one or more Sections, a collection of Pixels assigned to that Section, and one or more Colors that the Section will use in its animations. For each Section, specify the animation that you want to render. Update the grid by calling the Maestro::update() method in a loop, passing in the program’s current runtime as an argument.

The next step is to take each Pixel’s color value and pass it to some sort of output. The original intention of PixelMaestro was to drive RGB LEDs using an Arduino. However, a Color is stored as a simple RGB value, where R, G, and B are integer values, so you can adapt it to any output including LED strands, computer displays, or low-resolution monitors. Sample projects will be included later.

PixelMaestro is mostly just a way for me to learn Arduino and C++ while playing with pretty lights. Some time after this release, I’ll publish another post providing an in-depth look at the logic driving PixelMaestro, including sample programs, sample animations, and a (non-interactive) desktop GUI application for testing and previewing animations. The project is completely open source, and even if you’re not tech-inclined, I encourage you to check it out and tinker with it.

Where do I get it?

You can download the project from GitHub:


Thanks for reading, and happy hacking!

Leave a Reply