Images require some resizing and conversion in preparation for the light painter. The code can only read one specific format — 24-bit BMP — because we currently lack the ability 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 CircuitPython code only handles the 24-bit variety.
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 DotStar strip length (e.g. 72 pixels, unless you’ve made a custom variant). Any wider and it’ll be cropped, any narrower and the strip isn’t fully utilized. No scaling is performed.
Vertical images are painted bottom to top. This might seem odd, but is on purpose: the ground or tabletop 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 (e.g. 72 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 CLUE board; it would otherwise take several minutes (instead of seconds) to decode an image when loading.
If LOOP mode is ON while painting, the image will be repeated. This can be used to create patterns…
Image files are large. BMP images doubly so, because they’re not compressed.
The light painter code processes BMPs to a temporary working file so they can be read back and issued to the DotStars very quickly. This requires some free space on the CIRCUITPY drive.
Therefore…any BMP images you’re not using, or other files like unrelated CircuitPython libraries you may have previously installed…move these off the CIRCUITPY drive to your computer for safe keeping. There’s no fixed limit (the software adapts to what’s available), but if possible aim for at least 600 kilobytes free. This is only true when using the light painter code, not a general rule for all situations.
Pixels don’t need to be square! While the DotStar strip length is fixed (e.g. 72px), the perpendicular axis is fluid…it’s all a matter of how fast you move the light stick while painting. We can exploit this to make slightly sharper images…
If your image editor allows freeform resizing of images (that is, the resulting aspect ratio doesn’t have to match the original), set only the minor axis of the image to the DotStar strip length, and keep the other axis at its original value. When light painting, the image can be squeezed back to its original aspect, but using the additional pixels for more detail on one axis:
Exception would be if the original image is truly enormous. Bigger images need more drive space, and we want to keep some available. A good upper limit is around 500 pixels, give or take a bit.
If the original image is already less than 500 pixels on the major axis, there’s no benefit to scaling it up! The light painter interpolates along this axis and will provide the best image it can with the data it’s given.