Images will require some resizing and conversion in preparation for the NeoPixel Painter code. The software can only read one specific format — 24-bit BMP — because the Arduino lacks the sauce to decode complex formats like JPEG or PNG.

The BMP image format is sometimes called “Microsoft Bitmap” or “Windows Bitmap,” but there’s really nothing Windows-specific about it; plenty of software on Mac and Linux handles the format just as well, typically an option in a “Save As…” or “Export…” dialog box. Software like The GIMP, Pixelmator or Photoshop can export this format.

Be sure to select 24-bit BMP. Not 1- or 8- or 32-bit. The Arduino code only handles the 24-bit variety. Its OK if your image is not 24-bit color before saving, or monochrome. Its just that the file format is much easier to handle if its saved this way.

If painting an image vertically (that is, holding the strip horizontally and lifting it upward like a barbell), the image should be resized so its width matches the NeoPixel strip length (typically 144 pixels, unless you’ve made a custom variant). Images narrower than this will be centered in the strip, while wider images will be cropped; no scaling is performed.

Vertical images are painted bottom to top. This might seem odd, but is on purpose: the ground provides a consistent point of reference for starting. If you try painting from the top down, you may bump into the ground before the image is finished.

If painting an image horizontally (holding the strip vertically, moving left to right across the camera’s field of view), the image should be resized so its height matches the strip length (typically 144 pixels) and then rotated 90 degrees counter-clockwise (so the top of the image is now at the left side) before saving.

This extra step is necessary to reduce the amount of processing done on the Arduino; it would otherwise take minutes (instead of seconds) to decode a horizontal image at startup.

If the trigger is held (rather than tapped once) while painting, the image will be repeated. This can be used to create repeating patterns.

When transferring or saving a BMP file to the SD card, it must go in the root directory (not a sub-folder) and named frame000.bmp. No other file prefix or location is currently recognized, and no UI is provided for selecting alternates.

If the Arduino is refusing to load an image, connect a USB cable and open the Serial Monitor window in the Arduino IDE. The software will give some indication of its hangup; either accessing the card, locating the file or decoding the image format.

If you store multiple images to the card as frame000.bmp, frame001.bmp, frame002.bmp, etc. then each tap of the button will draw the next image in the series. The frame numbers must be contiguous, three digits, starting from zero (000). After the last image is painted the code will repeat the cycle from the start. Converting multiple images at startup can be very time consuming! Watch the red “SD” LED on the shield to see if it’s working.

Photography

You’ll just have to experiment with this part, there’s no one-size-fits-all setting. This requires a large, dark room, or go outdoors at night. It’s also much, much easier with a helper…one person can wield the paintbrush while the other tries different camera settings, sets focus, etc.

Place the camera on a tripod and set it to full manual mode, with a 3 second exposure to start. If the image is cut short, use longer exposures. Manual focus is recommended.

It’s not necessary to dress like a ninja for this. As long as you keep moving you won’t register in the photo.

For horizontal painting, move the brush from left to right across the camera’s field of view. To work in the opposite direction, flip the image before saving the BMP file. If the painted image appears upside-down (or mirrored when painting vertically), just turn the brush around…no need to edit the image file.

Sample Images

These are all in BMP format, 144 pixels wide, ready to go. Right-click over each image and select “Save Image As…” and rename as necessary (frame000.bmp, etc.)

It’s easiest to load up one image (or one animation sequence) per card, then swap cards and reset to paint different images. The code interprets multiple files as an animation sequence, and all frames must be processed at startup to ensure uniform brightness. This can be really time-consuming when there are a lot of files!

If you end up using these, or you have other awesome light-painting photos, send us a picture!