Skip to content
Easy color scales and color conversion for Python.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
spectra Relax requirements to just colormath>=3.0.0 Jan 24, 2018
test Clarify that len(domain) must equal len(colors) Jul 16, 2015
.gitignore Initial commit Mar 22, 2015
LICENSE.txt Initial commit Mar 22, 2015
MANIFEST.in
README.md Change walkthrough link from nbviewer -> GitHub Jul 16, 2015
requirements.txt Relax requirements to just colormath>=3.0.0 Jan 24, 2018
setup.py Pin colormath and networkx requirements Nov 27, 2017
tox.ini Pin colormath and networkx requirements Nov 27, 2017

README.md

Spectra

Spectra is a Python library that makes color math, color scales, and color-space conversion easy. Support for:

  • Color scales
  • Color ranges
  • Color blending
  • Brightening/darkening colors
  • Saturating/desaturating colors
  • Conversion to/from multiple color spaces

Spectra is built on colormath and grapefruit. Spectra is enormously inspired by chroma.js and d3's scales.

Installation

pip install spectra

Walkthrough

See this walkthrough to see what Spectra can do.

API

Creating color objects from web-colors or hexcode strings

spectra.html(html_string)

E.g., spectra.html("papayawhip"), spectra.html("#BAABAA") spectra.html("#FFF")

Creating color objects from color space values

spectra.rgb(r, g, b)

Specifically: sRGB


spectra.lab(L, a, b)

Specifically: CIELAB


spectra.lch(L, c, h)

Also known elsewhere as "hcl"


spectra.hsl(h, s, l)

spectra.hsv(h, s, v)

spectra.xyz(x, y, z)

spectra.cmy(c, m, y)

spectra.cmky(c, m, y, k)

Getting color values

Instances of spectra.Color have four main properties:

  • .values: An array representation of the color's values in its own color space, e.g. (L, a, b) for an lab color.
  • .hexcode: The hex encoding of this color, e.g. #ffffff for rgb(255, 255, 255)/html(\"white\").
  • .rgb: The (r, g, b) values for this color in the rgb color space; these are allowed to go out of gamut.
  • .clamped_rgb: The "clamped" (r, g, b) values for this color in the rgb color space.

Note on .rgb and .rgb_clamped: Spectra follows colormath's convention:

RGB spaces tend to have a smaller gamut than some of the CIE color spaces. When converting to RGB, this can cause some of the coordinates to end up being out of the acceptable range (0.0-1.0 or 1-255, depending on whether your RGB color is upscaled). [...] Rather than clamp these for you, we leave them as-is.

Modifying colors

color.to(space)

Convert this color to another color space.

teal_lab = spectra.html("teal").to("lab")
print(teal_lab.values)
>>> (48.25453959565715, -28.843707890081394, -8.48135382506432)

color.blend(other_color, ratio=0.5)

Blend this color with another color, using ratio of that other color.

yellow, red = spectra.html("red"), spectra.html("yellow")
orange = yellow.blend(red)
print(orange.hexcode)
>>> '#ff8000'

color.brighten(amount=10)

Brighten this color by amount luminance. (Converts this color to the LCH color space, and then increases the L parameter by amount.)

teal = spectra.html("teal")
light_teal = light_teal.brighten(30)
print(light_teal.hexcode)
>>> '#75d1d0'

color.darken(amount=10)

The opposite of color.brighten; reduces color by amount luminance.


color.saturate(amount=10)

Saturate this color by amount chroma. (Converts this color to the LCH color space, and then increases the C parameter by amount.)


color.desaturate(amount=10)

The opposite of color.saturate; reduces color by amount chroma.


Creating color scales

spectra.scale(colors)

colors should be a list of two or more colors (created by any of the methods above), web-color names, or hexcodes.

Returns a spectra.Scale object, which translates numbers to their corresponding colors:

my_scale = spectra.scale([ "gray", "red" ])
halfway = my_scale(0.5)
print(halfway.hexcode)
>>> '#c04040'

Modifying color scales

scale.domain(numbers)

By default, a scale's domain is [ 0, 1 ]. But you can change it to be anything else, e.g.:

my_scale = spectra.scale([ "gray", "red" ]).domain([ 10, 20 ])
halfway = my_scale(15)
print(halfway.hexcode)
>>> '#c04040'

Creating color ranges

scale.range(count)

This function returns a list of spectra.Color objects evenly spaced between a scale's colors. For example:

my_scale = spectra.scale([ "gray", "red" ])
my_range = my_scale.range(5)

print(my_range)
>>> [<spectra.core.Color object at 0x10f4759d0>, <spectra.core.Color object at 0x10f475a90>, 
    <spectra.core.Color object at 0x10f475b50>, <spectra.core.Color object at 0x10f475cd0>, 
    <spectra.core.Color object at 0x10f475d50>]

print([ c.hexcode for c in my_range ])
>>> ['#808080', '#a06060', '#c04040', '#df2020', '#ff0000']

Alternatively, as a shortcut, you can use spectra.range(colors, count).


Feedback/Suggestions

Issues and pull requests very much appreciated.

You can’t perform that action at this time.