color - Library for RGB and HSV colors

Note

This library was ported from FastLED

group rgb

Functions for RGB colors.

Ported from FastLED

MIT Licensed as described in the file LICENSE

Functions

static inline bool rgb_is_zero(rgb_t a)

This allows testing a RGB for zero-ness.

static inline rgb_t rgb_from_code(uint32_t color_code)

Create rgb_t color from 24-bit color code 0x00RRGGBB.

static inline rgb_t rgb_from_values(uint8_t r, uint8_t g, uint8_t b)

Create rgb_t color from values.

static inline uint32_t rgb_to_code(rgb_t color)

Convert RGB color to 24-bit color code 0x00RRGGBB.

static inline rgb_t rgb_add(rgb_t a, uint8_t val)

Add a constant to each channel of RGB color, saturating at 0xFF.

static inline rgb_t rgb_sub(rgb_t a, uint8_t val)

Subtract a constant from each channel of RGB color, saturating at 0x00.

static inline rgb_t rgb_mul(rgb_t a, uint8_t val)

Multiply each of the channels by a constant, saturating each channel at 0xFF.

static inline rgb_t rgb_add_rgb(rgb_t a, rgb_t b)

Add one RGB to another, saturating at 0xFF for each channel.

static inline rgb_t rgb_sub_rgb(rgb_t a, rgb_t b)

Subtract one RGB from another, saturating at 0x00 for each channel.

static inline rgb_t rgb_scale(rgb_t a, uint8_t scaledown)

Scale down a RGB to N 256ths of it’s current brightness, using ‘plain math’ dimming rules, which means that if the low light levels may dim all the way to 100% black.

static inline rgb_t rgb_scale_video(rgb_t a, uint8_t scaledown)

Scale down a RGB to N 256ths of it’s current brightness, using ‘video’ dimming rules, which means that unless the scale factor is ZERO each channel is guaranteed NOT to dim down to zero.

If it’s already nonzero, it’ll stay nonzero, even if that means the hue shifts a little at low brightness levels.

static inline rgb_t rgb_fade_light(rgb_t a, uint8_t fade_factor)

rgb_fade_light is a synonym for rgb_scale_video(…, 255 - fade_factor)

static inline rgb_t rgb_fade(rgb_t a, uint8_t fade_factor)

rgb_fade_light is a synonym for rgb_scale(…, 255 - fade_factor)

static inline rgb_t rgb_invert(rgb_t a)

Invert each channel of RGB color.

static inline uint8_t rgb_luma(rgb_t a)

Get the ‘luma’ of a RGB color - aka roughly how much light the RGB pixel is putting out (from 0 to 255).

static inline uint8_t rgb_average_light(rgb_t a)

Get the average of the R, G, and B values.

static inline rgb_t rgb_max_brightness(rgb_t a, uint8_t limit)

Maximize the brightness of this RGB color.

static inline rgb_t rgb_lerp8(rgb_t a, rgb_t b, fract8 frac)

Return a new RGB color after performing a linear interpolation between colors a and b.

static inline rgb_t rgb_lerp16(rgb_t a, rgb_t b, fract16 frac)

Return a new RGB color after performing a linear interpolation between colors a and b.

static inline rgb_t rgb_blend(rgb_t existing, rgb_t overlay, fract8 amount)

Computes a new color blended some fraction of the way between two other colors.

struct rgb_t
#include <rgb.h>

RGB color representation.

group hsv

Functions for HSV colors.

Ported from FastLED

MIT Licensed as described in the file LICENSE

Defines

HUE_RED
HUE_ORANGE
HUE_YELLOW
HUE_GREEN
HUE_AQUA
HUE_BLUE
HUE_PURPLE
HUE_PINK

Enums

enum color_gradient_direction_t

Values:

enumerator COLOR_FORWARD_HUES
enumerator COLOR_BACKWARD_HUES
enumerator COLOR_SHORTEST_HUES
enumerator COLOR_LONGEST_HUES

Functions

static inline bool hsv_is_zero(hsv_t a)

This allows testing a HSV for zero-ness.

static inline hsv_t hsv_from_values(uint8_t h, uint8_t s, uint8_t v)

Create HSV color from values.

hsv_t blend(hsv_t existing, hsv_t overlay, fract8 amount, color_gradient_direction_t direction)

Computes a new color blended some fraction of the way between two other colors.

struct hsv_t
#include <hsv.h>

HSV color representation.

group color

Functions for RGB and HSV colors.

Ported from FastLED

MIT Licensed as described in the file LICENSE

Defines

HUE_MAX_RAINBOW
HUE_MAX_SPECTRUM
HUE_MAX_RAW

Typedefs

typedef size_t (*xy_to_offs_cb)(void *ctx, size_t x, size_t y)

Function which must be provided by the application for use in two-dimensional filter functions.

Functions

rgb_t hsv2rgb_rainbow(hsv_t hsv)

Convert HSV to RGB using balanced rainbow.

Convert a hue, saturation, and value to RGB using a visually balanced rainbow (vs a straight mathematical spectrum). This ‘rainbow’ yields better yellow and orange than a straight ‘spectrum’.

Note

here hue is 0-255, not just 0-191

Parameters:

hsv – HSV color

Returns:

RGB color

rgb_t hsv2rgb_spectrum(hsv_t hsv)

Convert HSV to RGB using mathematically straight spectrum.

Convert a hue, saturation, and value to RGB using a mathematically straight spectrum (vs a visually balanced rainbow). This ‘spectrum’ will have more green & blue than a ‘rainbow’, and less yellow and orange.

Note

here hue is 0-255, not just 0-191

Parameters:

hsv – HSV color

Returns:

RGB color

rgb_t hsv2rgb_raw(hsv_t hsv)

Convert HSV to RGB using spectrum.

Convert hue, saturation, and value to RGB. This ‘spectrum’ conversion will be more green & blue than a real ‘rainbow’, and the hue is specified just in the range 0-191. Together, these result in a slightly faster conversion speed, at the expense of color balance.

Note

Hue is 0-191 only! Saturation & value are 0-255 each.

Parameters:

hsv – HSV color

Returns:

RGB color

hsv_t rgb2hsv_approximate(rgb_t rgb)

Recover approximate HSV values from RGB.

This function is a long-term work in process; expect results to change slightly over time as this function is refined and improved.

This function is most accurate when the input is an RGB color that came from a fully-saturated HSV color to start with.

This function is not nearly as fast as HSV-to-RGB. It is provided for those situations when the need for this function cannot be avoided, or when extremely high performance is not needed.

Why is this ‘only’ an “approximation”? Not all RGB colors have HSV equivalents! For example, there is no HSV value that will ever convert to RGB(255,255,0) using the code provided in this library. So if you try to convert RGB(255,255,0) ‘back’ to HSV, you’ll necessarily get only an approximation. Emphasis has been placed on getting the ‘hue’ as close as usefully possible, but even that’s a bit of a challenge. The 8-bit HSV and 8-bit RGB color spaces are not a “bijection”. Nevertheless, this function does a pretty good job, particularly at recovering the ‘hue’ from fully saturated RGB colors that originally came from HSV rainbow colors. The more desaturated the original RGB color is, the rougher the approximation, and the less accurate the results.

Parameters:

rgb – RGB color

Returns:

Approximated HSV color

rgb_t rgb_heat_color(uint8_t temperature)

Approximates a ‘black body radiation’ spectrum for a given ‘heat’ level.

This is useful for animations of ‘fire’. Heat is specified as an arbitrary scale from 0 (cool) to 255 (hot). This is NOT a chromatically correct ‘black body radiation’ spectrum, but it’s surprisingly close, and it’s fast and small.

void hsv_fill_solid_hsv(hsv_t *target, hsv_t color, size_t num)

Fill an array of HSV colors with a solid HSV color.

void rgb_fill_solid_hsv(rgb_t *target, hsv_t color, size_t num)

Fill an array of RGB colors with a solid HSV color.

void rgb_fill_solid_rgb(rgb_t *target, rgb_t color, size_t num)

Fill an array of RGB colors with a solid RGB color.

void hsv_fill_gradient_hsv(hsv_t *target, size_t startpos, hsv_t startcolor, size_t endpos, hsv_t endcolor, color_gradient_direction_t direction)

Fill an array of HSV colors with a smooth HSV gradient between two specified HSV colors.

Since ‘hue’ is a value around a color wheel, there are always two ways to sweep from one hue to another. This function lets you specify which way you want the hue gradient to sweep around the color wheel:

FORWARD_HUES: hue always goes clockwise
BACKWARD_HUES: hue always goes counter-clockwise
SHORTEST_HUES: hue goes whichever way is shortest
LONGEST_HUES: hue goes whichever way is longest
The default is SHORTEST_HUES, as this is nearly always what is wanted.

static inline void hsv_fill_gradient2_hsv(hsv_t *target, size_t num, hsv_t c1, hsv_t c2, color_gradient_direction_t direction)
static inline void hsv_fill_gradient3_hsv(hsv_t *target, size_t num, hsv_t c1, hsv_t c2, hsv_t c3, color_gradient_direction_t direction)
static inline void hsv_fill_gradient4_hsv(hsv_t *target, size_t num, hsv_t c1, hsv_t c2, hsv_t c3, hsv_t c4, color_gradient_direction_t direction)
void rgb_fill_gradient_hsv(rgb_t *target, size_t startpos, hsv_t startcolor, size_t endpos, hsv_t endcolor, color_gradient_direction_t direction)

Same as hsv_fill_gradient_hsv(), but for array of RGB.

The gradient is computed in HSV space, and then HSV values are converted to RGB as they’re written into the RGB array.

static inline void rgb_fill_gradient2_hsv(rgb_t *target, size_t num, hsv_t c1, hsv_t c2, color_gradient_direction_t direction)
static inline void rgb_fill_gradient3_hsv(rgb_t *target, size_t num, hsv_t c1, hsv_t c2, hsv_t c3, color_gradient_direction_t direction)
static inline void rgb_fill_gradient4_hsv(rgb_t *target, size_t num, hsv_t c1, hsv_t c2, hsv_t c3, hsv_t c4, color_gradient_direction_t direction)
void rgb_fill_gradient_rgb(rgb_t *leds, size_t startpos, rgb_t startcolor, size_t endpos, rgb_t endcolor)

Fill a range of LEDs with a smooth RGB gradient between two specified RGB colors.

Unlike HSV, there is no ‘color wheel’ in RGB space, and therefore there’s only one ‘direction’ for the gradient to go, and no ‘direction’ is needed.

static inline void rgb_fill_gradient2_rgb(rgb_t *target, size_t num, rgb_t c1, rgb_t c2)
static inline void rgb_fill_gradient3_rgb(rgb_t *target, size_t num, rgb_t c1, rgb_t c2, rgb_t c3)
static inline void rgb_fill_gradient4_rgb(rgb_t *target, size_t num, rgb_t c1, rgb_t c2, rgb_t c3, rgb_t c4)
hsv_t color_from_palette_hsv(const hsv_t *palette, uint8_t pal_size, uint8_t index, uint8_t brightness, bool blend)

Return an HSV color with ‘index’ from ‘palette’ (array of HSV colors).

Even though palette has lesser than 256 explicily defined entries, you can use an ‘index’ from 0..255. The ‘pal_size’ explicit palette entries will be spread evenly across the 0..255 range, and the intermedate values will be HSV-interpolated between adjacent explicit entries.

rgb_t color_from_palette_rgb(const rgb_t *palette, uint8_t pal_size, uint8_t index, uint8_t brightness, bool blend)

Same for RGB palette.

void blur1d(rgb_t *leds, size_t num_leds, fract8 blur_amount)

One-dimensional blur filter.

Spreads light to 2 line neighbors.

0 = no spread at all 64 = moderate spreading 172 = maximum smooth, even spreading

173..255 = wider spreading, but increasing flicker

Total light is NOT entirely conserved, so many repeated calls to ‘blur’ will also result in the light fading, eventually all the way to black; this is by design so that it can be used to (slowly) clear the LEDs to black.

void blur_columns(rgb_t *leds, size_t width, size_t height, fract8 blur_amount, xy_to_offs_cb xy, void *ctx)

Perform a blur1d on each column of a rectangular matrix.

void blur_rows(rgb_t *leds, size_t width, size_t height, fract8 blur_amount, xy_to_offs_cb xy, void *ctx)

Perform a blur1d on each row of a rectangular matrix.

void blur2d(rgb_t *leds, size_t width, size_t height, fract8 blur_amount, xy_to_offs_cb xy, void *ctx)

Two-dimensional blur filter.

Spreads light to 8 XY neighbors.

0 = no spread at all 64 = moderate spreading 172 = maximum smooth, even spreading

173..255 = wider spreading, but increasing flicker

Total light is NOT entirely conserved, so many repeated calls to ‘blur’ will also result in the light fading, eventually all the way to black; this is by design so that it can be used to (slowly) clear the LEDs to black.

uint8_t apply_gamma2brightness(uint8_t brightness, float gamma)

Single gamma adjustment to a single scalar value.

Bear in mind that RGB leds have only eight bits per channel of color resolution, and that very small, subtle shadings may not be visible.

rgb_t apply_gamma2rgb(rgb_t c, float gamma)

Single gamma adjustment to each channel of a RGB color.

rgb_t apply_gamma2rgb_channels(rgb_t c, float gamma_r, float gamma_g, float gamma_b)

Different gamma adjustments for each channel of a RGB color.