Craft and makingMatrixCraft

WLED pixel art: how to get pictures onto an LED matrix

How WLED pixel art works: WLED's own image tools, drawing at 16 x 16, colour and brightness tips, and saving your art as presets.

5 min readBy Zarkon

On this page
  1. Before you start: set the matrix up as 2D
  2. WLED pixel art from an image: WLED’s own tools
  3. Drawing LED matrix pixel art at low resolution
  4. Colour and brightness tips
  5. Keeping your art on the lights with presets
  6. Where MatrixCraft helps, and where it doesn’t
  7. Questions people ask
  8. Sources

Before you start: set the matrix up as 2D

Every route below depends on WLED knowing the shape of your panel. In WLED’s 2D Configuration you set “Strip or panel” to 2D Matrix, then give the size, the corner of the first LED and whether the panel is serpentine (zigzag). The WLED project’s documentation warns that getting the serpentine option wrong “can lead to very confusing results that look almost correct but not quite”. If your art looks shredded or every other row seems mirrored, fix that before anything else. Our guide to WLED matrix setup and serpentine wiring goes through it step by step.

WLED pixel art from an image: WLED’s own tools

Pixel Art Converter. According to the WLED documentation, this tool converts an image to 2D pixel art and sends it to the WLED device. PNG, JPG, WEBP and GIF files have been tested with it. You choose an image, check the preview, use the “Scale image” option if the picture is larger than your matrix, then press “Send to device”.

Newer versions. The same page says the Pixel Art Converter is deprecated as of WLED 16.0 in favour of a newer tool. WLED’s docs describe that as a built-in browser tool for images and scrolling text, reached from an icon below the colour picker, and note that its image converter is not available on ESP8266 controllers, because the GIF player isn’t either. Check which tools your WLED version supports before following a guide.

A WLED pixel art converter is the quickest route when you already have a picture. The catch is that a photo shrunk to 16 x 16 often turns into a blur, so drawing at the real size usually works better.

Drawing LED matrix pixel art at low resolution

A 16 x 16 matrix has 256 pixels, so every one counts. A few habits help:

  • Draw at the real size. Work on a grid the same size as your matrix, so what you draw is exactly what lights up. Scaling down afterwards blends colours and loses edges.
  • Use bold outlines and few colours. Strong shapes and a small palette read better from across a room than fine detail or gentle shading.
  • Leave black as black. An unlit LED is your darkest colour. Black backgrounds make the lit pixels stand out and use less power.
  • Check from a distance. Step back and look at the panel itself, not just the drawing on screen.
  • Animate in small steps. Short loops, such as a blinking eye, often read better than long, busy animations.

Colour and brightness tips

Colours on LEDs rarely match your screen. Adafruit’s guide to gamma correction explains why: our eyes are far more sensitive to changes at the dim end, so a value set to half brightness looks much brighter than half. Their example is orange (255, 127, 0) on screen showing as yellowish on LEDs. To look 50% bright, they say, the LED may need a value of only about 36 rather than 127.

WLED already deals with much of this. Its LED Preferences include “Use Gamma correction for color”, on by default, which the documentation describes as making colours look closer to what you see on a monitor and marks as strongly recommended.

For brightness, WLED’s automatic brightness limiter turns overall brightness down to keep the current under the Maximum PSU Current you set. A full panel of bright white can draw a lot of power, so pixel art with plenty of black is easier on your supply.

Keeping your art on the lights with presets

Art sent live from a browser or app does not stay put. The WLED JSON API documentation says that setting individual LEDs is not persistent: if the light is turned off, the segment returns to effect mode.

To keep a picture, save it as a preset. WLED stores presets in a presets.json file on the controller, with support for up to 250. WLED’s Time and Macros settings can apply presets at set times. The docs suggest keeping to around 50 single-segment presets so the controller stays responsive.

Where MatrixCraft helps, and where it doesn’t

MatrixCraft: WLED Pixel Art is our Android app for drawing on a WLED matrix from your phone. It finds WLED lights on your Wi-Fi and reads the LED count and 2D size. You draw with pencil, line, box, fill, eraser and colour picker, with mirror drawing and undo, and every stroke shows on the matrix as you draw. It also does frame by frame animations, streamed over DDP or WLED UDP realtime, and scrolling text.

Free: drawing, animations of up to 8 frames, scrolling text and three starter animations, on matrices up to 256 LEDs (such as 16 x 16 or 32 x 8). Streamed animations play only while the app is open.

Pro, a one-off purchase: saving pictures and animations to the lights as WLED presets and a playlist, so they play with your phone switched off, plus GIF and picture import, shows, all starter animations, matrices up to 64 x 64 and animations up to 120 frames.

Where it doesn’t help: it needs a WLED controller (ESP8266 or ESP32 with WLED 0.13 or later) on the same Wi-Fi as your phone, and it can’t fix wiring, power or a faulty panel. If you just want to throw an existing image onto the matrix, WLED’s own browser tools may be all you need. MatrixCraft is an independent app and is not made by the WLED project.

Questions people ask

What is the best size for WLED pixel art?

The same size as your matrix. A 16 x 16 panel shows 256 pixels, so drawing at 16 x 16 gives the cleanest result.

Why do my colours look different on the LEDs?

Eyes see LED brightness unevenly, so mid tones look brighter than on a screen. Keep WLED’s gamma correction for colour on and test your palette on the real panel.

Is there a WLED pixel art editor?

WLED has browser tools for converting images and scrolling text. To draw pixel by pixel you can use a paint tool or an app made for WLED, such as MatrixCraft.

Why does my picture disappear when I turn the lights off?

Pixels set directly are not persistent, according to the WLED docs. Save the picture as a preset to keep it.

Sources

  1. Pixel Art ConverterWLED Project kno.wled.ge
  2. PixelForge (Image and GIF Tool)WLED Project kno.wled.ge
  3. JSON APIWLED Project kno.wled.ge
  4. PresetsWLED Project kno.wled.ge
  5. SettingsWLED Project kno.wled.ge
  6. LED Tricks: Gamma CorrectionAdafruit learn.adafruit.com