Colors Module

Adam Haile edited this page Mar 23, 2017 · 6 revisions

Module bibliopixel.colors

The colors module provides many useful methods for manipulating colors in both RGB and HSV format. There is no class to use and all methods can be called directly from the module.

All values used by colors are represented as 8-bit (0-255) values for the sake of performance. This includes HSV and brightness values which are normally represented as 0-359 and 0-100%, respectively. Using pure 8-bit values allow all calculations to be performed with much faster bitwise operations.

Built in colors

The colors module makes available all of the standard HTML color names, for example:

#produces a list of all the colors of the rainbow
import bibliopixel.colors as colors
rainbow = [colors.Red, colors.Orange, colors.Yellow, colors.Green, colors.Blue, colors.Indigo, colors.Violet]

color_scale

(color, level)

  • color - RGB color tuple, (r,g,b).
  • level - 8-bit color scalar. 0-255 (0 = 0%, 128 = 50%, 255 = 100%)

Scales the given color by the given value to decrease brightness. Given color is always assumed to be at full brightness and the resulting value will always be the same brightness or less. Returns an RGB color tuple.

color_blend

(a, b)

  • a - First color to blend.
  • b - Second color to blend.

Blends two colors together using the screen algorithm.

c = 255 - ((255-a) * (255-b) >> 8)

The resulting color will generally be slightly brighter than either of the two input colors. Returns an RGB color tuple.

gamma_correct

(color, gamma)

  • color - RGB color tuple, (r,g,b).
  • gamma - 256 value gamma correction list.

Gamma corrects the color with the given correction list and returns an RGB color tuple. The list MUST contain 256 8-bit integer values. Predefined corrections lists can be found in bibliopixel.gamma. For example, the WS2801 correction list is defined as:

gamma = [int(pow(float(i) / 255.0, 2.5) * 255.0) for i in range(256)]

hsv2rgb

(hsv)

  • hsv - An HSV color tuple, (h,s,v)

Returns an RGB color tuple given an HSV color tuple. This defaults to the hsv2rgb_rainbow implementation. See HSV Colors for more details.

hue2rgb

(hue)

  • hue - 8-bit hue value (0-255)

Returns an RGB color tuple given a hue value. This defaults to the hue2rgb_rainbow implementation. See HSV Colors for more details.

hsv2rgb_raw

(hsv)

  • hsv - An HSV color tuple, (h,s,v)

Returns an RGB color tuple given an HSV color tuple. This raw version returns values that are purely linear in relation to one another. See HSV Colors for more details.

hue2rgb_raw

(hue)

  • hue - 8-bit hue value (0-255)

Returns an RGB color tuple given a hue value. This is a convenience and speed method that simply returns a value from a pre-generated table as if you had called hsv2rgb_raw((hue, 255, 255)). See HSV Colors for more details.

hsv2rgb_spectrum

(hsv)

  • hsv - An HSV color tuple, (h,s,v)

Returns an RGB color tuple given an HSV color tuple. This spectrum version returns values that follow the same pattern as the visible color patter and are not purely linear. See HSV Colors for more details.

hue2rgb_spectrum

(hue)

  • hue - 8-bit hue value (0-255)

Returns an RGB color tuple given a hue value. This is a convenience and speed method that simply returns a value from a pre-generated table as if you had called hsv2rgb_spectrum((hue, 255, 255)). See HSV Colors for more details.

hsv2rgb_rainbow

(hsv)

  • hsv - An HSV color tuple, (h,s,v)

Returns an RGB color tuple given an HSV color tuple. This rainbow version returns values that are more evenly spaced between color shifts. See HSV Colors for more details.

hue2rgb_rainbow

(hue)

  • hue - 8-bit hue value (0-255)

Returns an RGB color tuple given a hue value. This is a convenience and speed method that simply returns a value from a pre-generated table as if you had called hsv2rgb_rainbow((hue, 255, 255)). See HSV Colors for more details.

hsv2rgb_360

(hsv)

  • hsv - Tuple of standard HSV color values: (0-359, 0-1.0, 0-1.0)

Returns an RGB color tuple given an tuple of standard HSV color values. This method is provided for when using 0-359 hue values is absolutely necessary. In this case, however, saturation and value use 0.0 through 1.0 instead of 0-255. This method uses the python native colorsys.hsv_to_rgb() function and is slower than the above, 8-bit, HSV conversion methods. See HSV Colors for more details.

hue2rgb_360

(hue)

  • hue - 0-359 hue value.

Returns an RGB color tuple given a standard hue value, 0 - 359. This is a convenience and speed method that simply returns a value from a pre-generated table as if you had called hsv2rgb_360((hue, 1.0, 1.0)). See HSV Colors for more details.

wheel_color

(position)

  • position - Color wheel value, 0 - 384

Returns an RGB color tuple. This method is provided for those used to using the Adafruit style color wheel functions.

wheel_helper

(pos, length, cycle_step)

  • pos - Position in the color wheel (0-384)
  • length - Total length to distribute the color wheel over (may be any positive integer).
  • cycle_step - Step in the shifting cycle that allows the wheel to move over time (may be any positive integer).

Helper method for distributing wheel_color values evenly over a length and allow that distribution to be shifted by cycle_step.

hue_helper

(pos, length, cycle_step)

  • pos - Position in the color wheel (0-255)
  • length - Total length to distribute the color wheel over (may be any positive integer).
  • cycle_step - Step in the shifting cycle that allows the wheel to move over time (may be any positive integer).

Same as wheel_helper but using 8-bit (0-255) position value.