Home

Welcome to the PixelMaestro documentation!

What is PixelMaestro?

PixelMaestro is a graphics library for LED displays. It features 24-bit colors, a variety of animations and visual effects, support for drawing bitmap images, and much more. It’s designed to be simple to use, flexible, and compatible with existing LED libraries such as Adafruit’s NeoPixel Library and FastLED.

This documentation is for the core PixelMaestro library. For the desktop app, see the PixelMaestro Studio documentation.

Getting Started

To jump right in, see the Tutorial. You can find complete code examples in the Arduino folder.

To learn about PixelMaestro’s architecture and components, see the Components page.

FAQ

How do I change a Pixel’s color?

Use Section::set_pixel_color(). For example, to immediately turn a Pixel blue:

`c++ section.set_step_count(1); section.set_pixel_color(0, 0, ColorPresets::Blue}; `

You can also use a Canvas, although this is a bit more complicated. See How Pixels Work to learn more.

How do I connect my LEDs to PixelMaestro?

PixelMaestro can’t control LEDs directly, but you can use it with a library like NeoPixel or LightWS2812. On each loop, grab the color value of each Pixel using maestro.get_pixel_color(section_id, x_coordinate, y_coordinate) and pass it to the library.

Why am I getting poor performance / running out of memory?

Performance is affected by:

  • How much RAM your device has and how fast its CPU is

  • The number of Pixels being rendered

  • How many Layers you have active

  • Whether you’re using Animations or Canvases

  • Whether you’re using Cues

  • Any other libraries you are using simultaneously

For a device like an Arduino, your biggest limitation is memory. Each Pixel requires at least 3 bytes of RAM (one for each color channel). If fading is enabled (which it is by default), each Pixel requires 3 additional bytes to store its target color. If accurate fading is enabled (it’s not by default), then each Pixel will require another 3 bytes. This means that a 10x10 grid needs anywhere between 300 and 900 bytes just to store color data.

Consider that adding a Layer doubles this amount, since it creates an entirely new framebuffer with the same dimensions as the base Section. Adding an Animation or Canvas adds an additional byte per Pixel to track each Pixel’s Palette color. You can reduce memory usage by tweaking Pixel performance options. Try using a library like MemoryFree to monitor memory usage as you tweak your configuration and options.

For performance, PixelMaestro becomes slower as the number of Pixels and effects increases. If your device takes a long time to draw changes, try removing certain effects or decreasing the number of LEDs.