Palette Noise - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Noise Palette on Twinkle Effect in 1D, Cycling Through Hues (see here for segment layout info)

Generates a palette where the colors vary over time using FastLED Perlin noise. You pick the size of the palette, a base hue, and how much the hue can vary by, and the utility does the rest. This allows you to create "themed or mood" palettes, such as a an ocean or forest palette, where all the colors vary between different blues or greens.

These palettes work well with a number of effects, notably Lava, Rolling Waves (Seg Line), Noise (Seg Line), both Rain effects.

See Palette Basics for more info on palettes.

The output palette of the utility is named noisePalette.

You can use it in your effects like:

//Sets an effect's palette to your Palette Noise's output palette
//Note that this assumes that the effect's "palette" var is a pointer (true in most effects)
//So we need to pass the Palette Noise's palette by address (using the "&")
yourEffect.palette = &yourPaletteNoise.noisePalette;

You can also pass yourPaletteNoise.noisePalette as part of the effect's constructor.

Note that you are free to change most of the utility's settings on the fly, with exception to the number of noise palette colors, which you must call setupPalette() to change.

Sometimes the palette colors can flicker at lower brightness values, setting FastLED.setDither(0) can help with this.

• You can set the utility to generate a set of complimentary palette colors (dual, triad, tetrad, etc) that vary over time, although the noise variations will force them in and out of being truly complimentary.

• The utility can be set to vary the noise palette's base hue over time, shifting the palette through the rainbow while still generating noise based colors. The rate change is tied to hueRate, which is a pointer, so it can be bound externally (like the utility's update rate).

Getting the palette colors to vary in the way you want can be a little tricky. The name of the game is finding a set of settings that give you a good variation of colors, but don't shift the hue too far away from your "main" color.

Overall, you have five main settings for adjusting the colors:

• hueBase and hueMax:

  The utility generates colors using the FastLED HSV colors (hue, saturation, and value). You can read more about this color space here, but basically the "hue" determines what your "base" color is, while the saturation and value control how much white and black are mixed into the color.

  FastLED maps the hue/sat/val range to 0 - 255 from the more common 0 - 360 range.

  A rough color to hue map is:

  • Red/Orange: 240 to ~10
  • Orange/Yellow: 10 to ~40
  • Yellow/Green: 40 to ~90
  • Green/Blue: 90 to ~150
  • Blue/Purple: 150 to ~180
  • Purple/Red: 180 to 240

  So a color with a hue of 240, saturation of 100, and a value of 255 will be a pale red/pink (saturation and value use a reverse scale, so at 255 the value has no effect, while at 0, the color would be fully black).

  For Palette Noise, hueBase is the minimum hue the palette colors can have, while hueMax is the maximum. The utility generates colors by treating the noise as a percentage of hueMax, and then adding that to hueBase, ie outputHue = hueBase + map8(noiseData, 0, hueMax);. In general, I recommend hueMax to between 30 - 100. Note that the noise tends to fall more towards the middle of the range, so baseHue + 1/2 * hueMax will be the most common color.

  Overall, larger hueMax's will generate a wider range of colors, but the colors will trend father from the baseHue. If you want to have a tighter range of colors, I recommend tweaking the satMin and valMin, as explained next.

• satMin (default 220) and valMin (default 180):

  These values (saturation and value) control how much white and black can be added to the hue color via noise. Their effect is minimized at 255 and maximized at 0. Like with hueMax, satMin and valMin set the lowest value they can be, ranging from satMin or valMin to 255. The defaults are set to give modest changes in bright/darkness, and work best with a hueMax of 60+.

  If you want to have a tighter hue, but keep a good variety of colors, lower satMin and valMin to the 100 - 150 range.

  Note that satMin is fluctuated using the same noise as the palette colors, while valMin has its own noise function. This helps prevent the values from moving in tandem, producing a better variation of colors.

The right combo of hueMax, satMin, and valMin will probably take some experimentation to determine.

• Noise speed:

  The speed at which the palette colors shift is governed by blendSpeed and briSpeed.

  • blendSpeed controls how fast the hue and saturation change. This is a multiplier, so there's not a good real-world approximation I can give you. I recommend a speed between 5 and 20. Smaller values mean faster color changes.

  • briSpeed controls how fast the HSV "value" changes. This is default to 10, and is separate from the hue and saturation multiplier to help produce a better variation of colors.

• colorScale (default 200) and briScale (default 100):

  These settings control how large the noise color patches are, or how "zoomed-in" the Perlin noise is.colorScale applies to the hue and saturation noise function, while briScale applies to the HSV "value" value. For both these, we want the noise pretty zoomed-out so that colors blend over a decent range of pixels. See FastLED's noise notes for more info.

• compliment (bool):

  If true, will set the palette colors to be compliments of the base hue, which means they will be equally spaced across the hue spectrum. This should generate color that are different but "look good" together. Note that the noise effects each palette color separately, so for larger hueMax's, the palette colors will not stay fully complimentary as they shift.

PaletteNoisePS paletteNoise(4, 160, 60, false, 15, 0, 60);
/*  Will generate a palette of 4 colors, using a base hue of 160 and a range of 60
    The colors will not be complimentary
    The noise changes with a speed scale of 15
    The hue will not shift over time (hueRate is 0)
    The palette colors update at a rate of 60ms */

PaletteNoisePS paletteNoise(2, 0, 40, true, 8, 500, 60);
/*  Will generate a palette of 2 colors, using a base hue of 0 and a range of 40
    The colors will be complimentary
    The noise changes with a speed scale of 8
    The hue will shift over time at a rate of 500ms
    The palette colors update at a rate of 60ms. */

PaletteNoisePS paletteNoise(3, 130, 40, 150, 120, false, 10, 0, 60);
/*  These settings generate a nice ocean-like palette
    Will generate a palette with a 3 colors, using a base hue of 130 and a range of 40
    The saturation min and value min are set to 150 and 120 respectively
    The colors will not be complimentary
    The noise changes with a speed scale of 10
    The hue will not shift over time (hueRate is 0)
    The palette colors update at a rate of 60ms. */

//Constructor with hueRate setting and default satMin and valMin values
PaletteNoisePS(uint8_t numColors, uint8_t HueBase, uint8_t HueMax, bool Compliment, uint16_t BlendSpeed,
               uint16_t HueRate, uint16_t Rate);

//Constructor with saturation and value min settings
PaletteNoisePS(uint8_t numColors, uint8_t HueBase, uint8_t HueMax, uint8_t SatMin, uint8_t ValMin, 
               bool Compliment, uint16_t BlendSpeed, uint16_t HueRate, uint16_t Rate);

• uint8_t numColors -- The number of colors in the output noise palette. Can be changed later using setupPalette().

• uint8_t hueBase -- The base hue for the palette colors (See Inputs Guide above).

• uint8_t hueMax -- The maximum variation for the palette hue (See Inputs Guide above).

• uint8_t satMin (optional, default 220) -- The palette color's HSV "saturation" minimum (See Inputs Guide above).

• uint8_t valMin (optional, default 180) -- The palette color's HSV "value" minimum (See Inputs Guide above).

• bool compliment -- If true, the utility will generate complimentary colors for the noise palette (See Inputs Guide above).

• uint16_t blendSpeed -- The speed factor at which the palette colors change, recommend between 5 and 20, smaller is faster (See Inputs Guide above).

• uint16_t hueRate (0 for no shift) -- The rate of change of hueBase in ms. Is a pointer, allowing you to bind it to an external variable. By default it's bound the effect's local variable, hueRateOrig, like the effect update rate.

• uint16_t* rate -- Update rate (ms). Is a pointer, allowing you to bind it to an external variable. By default it's bound the effect's local variable, rateOrig. See common vars rate entry for more.

• palettePS noisePalette -- The output palette for the noise colors.

• uint16_t colorScale (default 200) -- How "zoomed in" the color noise is (See Inputs Guide above).

• uint16_t briScale (default 100) -- Same as the colorScale, but for the HSV "value" value (darkness added).

• uint16_t briSpeed (default 255) -- Same as the blendSpeed, but for the HSV "value" value (darkness added). Higher -> slower.

• bool active (default true) -- If false, the utility/effect will be disabled (updates() will be ignored). See common vars active entry for more details.

• bool showNow (default true) -- Controls if the effect "draws" during each update cycle by calling FastLED.show(). Common to all effects. See common vars showNow entry for more details.

• void setupPalette( uint8_t numColors ); 

  Changes the number of colors in the noise palette. Note that if the new length is longer than the noise palette's maximum length (the longest it has been while the utility is running), the noise palette's memory will be re-allocated. See Memory Management for more. (You probably don't need to worry about this!).

• void update();

  Updates the utility.