Adminius / NeoPixelPainter

Arduino library for easy creation of LED strip animations, based on the NeoPixel library.

NeoPixel Painter Library

https://github.com/DedeHai/NeoPixelPainter A library to ease the creation of simple LED-strip animations. See examples for some inspiration.

How to use

The basic principle is to use a brush that can be moved to any pixel. The brush holds a color using the HSV color space rather than RGB. This allows for making colorful animations with color fading as well as brightness fading. To make the brush move on its own, give it a speed and it will move a little on each function call. It only paints each pixel once, even if it stays at the same location for a longer time.

The brush paints on a canvas, which holds one HSV color for each pixel as well as a value to fade to, the fade speed and some fading properties (flags). You should only use one fading type (hue, saturation or value) at a time. Although multiple fadings are allowed, each pixel only holds one 'fade-to' value to not use excessive amounts of RAM. Also, all fading is implemented without the use of floats. This makes it fast and uses a lot less of the precious RAM. The downside is, that color fadings are slightly less accurate but almost indistinguishable to the naked eye because I implemented the fadings using 16bit variables and bit-shifts (aka fixed point arithmetic), making it almost as accurate as when using floats.

Basic procedure

• create a Adafruit_NeoPixel object (myneopixels)
• create a canvas object (mycanvas), passing the just created neopixel object
• create a brush object (mybrush), passing it the canvas object
• set the brush properties (see examples for some inspiration)
• apply the paint to the canvas by calling mybrush.paint()
• clear the NeoPixel buffer by calling myneopixels.clear()
• transfer the paint from the canvas to the pixels by calling mycanvas.transfer()
• send out the data to the pixels by calling myneopixels.show()
• loop the last four steps (paint the canvas, clear the buffer, transfer the paint, sendout data)

Reference

NeoPixelPainterBrush-Class functions

• NeoPixelPainterBrush(NeoPixelPainterCanvas hsv_canvas)*
  • class constructor, taking a pointer to a canvas (use &canvasname to pass the pointer)
• ~NeoPixelPainterBrush(void)
  • class deconstructor, is called automatically when the created class leaves the local scope (i.e. a loop)
• bool isvalid(void)
  • returns true if memory allocation for the class was successful. Use it if you are not sure if enough memory was available
• void paint(void)
  • applies all the painting properties to the current pixel of assigned canvas and updates the brush (moves the brush if it has any speed). Call this before calling canvas.transfer()
• void moveTo(uint16_t position)
  • move the brush to a certain pixel in the strip
• int16_t getPosition(void)
  • read current pixel position the brush is at
• int32_t getSubPosition(void)
  • read current sub-pixel position the brush is at
• void setSpeed(int16_t speed)
  • set the speed of the brush. since sub-pixel speed is used, one pixel per iteration is (1<<12) or 4095
• uint16_t getSpeed(void)
  • get the current speed
• void setSpeedlimit(int16_t limit)
  • set a limit the brush cannot exceed. useful when using sensors for speed mapping
• void setColor(HSV color)
  • set the color of the brush in HSV, see examples for detail
• HSV getColor(void)
  • read the current color of the brush
• void setFadeSpeed(uint8_t fadeSpeed)
  • set the fade speed of all fading effects (cannot have different speeds since the canvas can only hold one speed per pixel)
• uint8_t getFadeSpeed(void)
  • read the current fade speed of the brush
• void setFadeout(bool value)
  • activate brightness fade-out. fade-out starts as soon as the maximum brightness is reached (if fade-in is also used)
• void setFadein(bool value)
  • activate fade-in: pixel will start out dark and fade to the set color with the set fading speed
• void setFadeHueNear(bool value)
  • fade hue from current pixel color of the canvas to the painted color chosing the nearest path around the colorcircle
• void setFadeHueFar(bool value)
  • like setFadeHueNear but going the long way around the colorcircle
• void setFadeSaturation_in(bool value)
  • the canvas will fade the color saturation from current value to the painted value (if painted value is smaller than current value, use FadeSaturation_out)
• void setFadeSaturation_out(bool value)
  • the canvas will fade the color saturation from the current value to the set value (or to zero if saturation fade-in is also active)
• void setBounce(bool value)
  • bounce the brush once it reaches either end of the strip instead of jumping to the other end
• void setStop(bool value)
  • stop brush at the and and don't move any more

NeoPixelPainterCanvas-Class functions

• NeoPixelPainterCanvas(Adafruit_NeoPixel NeoPixels)*
  • class constructor, pass the neopixels as a pointer (using '&myneopixels')
• NeoPixelPainterCanvas(Adafruit_NeoPixel NeoPixels, uint16_t count)*
  • class constructor, pass the neopixels as a pointer (using '&myneopixels') and the count of pixels (can be shorter as a &myneopixels stripe)
• ~NeoPixelPainterCanvas(void)
  • class deconstructor, is called automatically when the created class leaves the local scope (i.e. a loop)
• *setAddColorRGBext(void (func)(int, RGB))
  • set pointer to user defined addColorRGB function (used for user defined canvas length, that is shorter that real stripe)
• bool isvalid(void)
  • returns true if memory allocation for the class was successful. Use it if you are not sure if enough memory was available. The canvas uses a lot of memory: 6 bytes per pixel.
• void clear(void)
  • clear the canvas from all paint
• void transfer(void)
  • transfer the paint from the canvas to the LEDs. Always call this function before calling the neopixels.show() function.