gamut

README

gamut

Go package to generate and manage color palettes & schemes

import "github.com/muesli/gamut"
import "github.com/muesli/gamut/palette"
import "github.com/muesli/gamut/theme"

Colors

gamut operates on various color spaces internally, but all color values you pass in as parameters and all return values will match Go’s color.Color interface.

Let’s start with the basics. Just for convenience there’s a hex-value parser:

color = gamut.Hex("#333")
color = gamut.Hex("#ABCDEF")

Both the short and standard formats are supported.

Conversely you can retrieve the hex encoding of any color.Color value:

hex = gamut.ToHex(color)

Around the Color Wheel

The Darker and Lighter functions darken and lighten respectively a given color value by a specified percentage, without changing the color's hue:

// returns a 10% darker version of color
color = gamut.Darker(color, 0.1)
// returns a 30% lighter version of color
color = gamut.Lighter(color, 0.3)

Complementary returns the complementary color for a given color:

color = gamut.Complementary(color)

Contrast returns the color with the highest contrast to a given color, either black or white:

color = gamut.Contrast(color)

To retrieve a color with the same lightness and saturation, but a different angle on the color wheel, you can use the HueOffset function:

color = gamut.HueOffset(color, 90)

You can also go in the opposite direction by using negative values.

Schemes

All the following functions return colors of a different hue, but with the same lightness and saturation as the given colors:

Triadic schemes are made up of three hues equally spaced around the color wheel:

colors = gamut.Triadic(color)

Quadratic schemes are made up of four hues equally spaced around the color wheel:

colors = gamut.Quadratic(color)

Tetradic schemes are made up by two colors and their complementary values:

colors = gamut.Tetradic(color1, color2)

Analogous schemes are created by using colors that are next to each other on the color wheel:

colors = gamut.Analogous(color)

SplitComplementary schemes are created by using colors next to the complementary value of a given color:

colors = gamut.SplitComplementary(color)

Warm/Cool Colors

ok = gamut.Warm(color)
ok = gamut.Cool(color)

Shades, Tints & Tones

Monochromatic returns colors of the same hue, but with a different saturation/lightness:

colors = gamut.Monochromatic(color, 8)

Shades returns colors blended from the given color to black:

colors = gamut.Shades(color, 8)

Tints returns colors blended from the given color to white:

colors = gamut.Tints(color, 8)

Tones returns colors blended from the given color to gray:

colors = gamut.Tones(color, 8)

Blending Colors

Blends returns interpolated colors by blending two colors:

colors = gamut.Blends(color1, color2, 8)

Palettes

Gamut comes with six curated color palettes: Wikipedia, Crayola, CSS, RAL, Resene, and Monokai. The Wikipedia palette is an import of common colors from Wikipedia’s List of Colors. New curated palettes and importers are welcome. Send me a pull request!

Name	Colors	Source
Wikipedia	1609	https://en.wikipedia.org/wiki/List_of_colors_(compact)
Crayola	180	https://en.wikipedia.org/wiki/List_of_Crayola_crayon_colors
CSS	147	https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
RAL	213	https://en.wikipedia.org/wiki/List_of_RAL_colors
Resene	759	http://www.resene.co.nz
Monokai	17

The function Colors lets you retrieve all colors in a palette:

for _, c := range palette.Wikipedia.Colors() {
    fmt.Println(c.Name, c.Color)
}

This will print out a list of 1609 color names, as defined by Wikipedia.

Creating Your Own Palettes

var p gamut.Palette
p.AddColors(
    gamut.Colors{
        {"Name", gamut.Hex("#123456"), "Reference"},
        ...
    }
)

Name and Reference are optional when creating your own palettes.

Names

Each color in the curated palettes comes with an “official” name. You can filter palettes by colors with specific names. This code snippet will return a list of all “blue” colors in the Wikipedia palette:

colors = palette.Wikipedia.Filter("blue")

You can access a color with a specific name using the Color function:

color, ok = palette.Wikipedia.Color("Pastel blue")

Calling a palette’s Name function with a given color returns the name & distance of the closest (perceptually) matching color in it:

name, distance = palette.Wikipedia.Name(color)
// name = "Baby blue"
// distance between 0.0 and 1.0

Mixing Palettes

You can combine all colors of two palettes by mixing them:

p = palette.Crayola.MixedWith(palette.Monokai)

Perception

Sometimes you got a slice of colors, but you have a limited color palette to work with. The Clamped function returns a slice of the closest perceptually matching colors in a palette, maintaining the same order as the original slice you provided. Finally you can remix your favorite wallpapers in Crayola-style!

colors = palette.Crayola.Clamped(colors)

Generating Color Palettes

Color Generators, like the provided PastelGenerator, WarmGenerator or HappyGenerator can produce random (within the color space constraints of the generator) color palettes:

colors, err = gamut.Generate(8, gamut.PastelGenerator{})

The SimilarHueGenerator produces colors with a hue similar to a given color:

colors, err = gamut.Generate(8, gamut.SimilarHueGenerator{Color: gamut.Hex("#2F1B82")})

Using the ColorGenerator interface, you can also write your own color generators:

type BrightGenerator struct {
	BroadGranularity
}

func (cc BrightGenerator) Valid(col colorful.Color) bool {
	_, _, l := col.Lab()
	return 0.7 <= l && l <= 1.0
}

...
colors, err := gamut.Generate(8, BrightGenerator{})

Only colors with a lightness between 0.7 and 1.0 will be accepted by this generator.

Themes

Name	Colors
Monokai	7

Roles

color = theme.MonokaiTheme.Role(theme.Foreground)

Available roles are Foreground, Background, Base, AlternateBase, Text, Selection, Highlight.

Feedback

Got some feedback or suggestions? Please open an issue or drop me a note!

• Twitter
• The Fediverse

Documentation

Index

• func Analogous(c color.Color) []color.Color
• func Blends(c1, c2 color.Color, count int) []color.Color
• func Complementary(c color.Color) color.Color
• func Contrast(c color.Color) color.Color
• func Cool(c color.Color) bool
• func Darker(c color.Color, percent float64) color.Color
• func Generate(count int, generator ColorGenerator) ([]color.Color, error)
• func Hex(s string) color.Color
• func HueOffset(c color.Color, degrees int) color.Color
• func Lighter(c color.Color, percent float64) color.Color
• func Monochromatic(c color.Color, count int) []color.Color
• func Quadratic(c color.Color) []color.Color
• func Shades(c color.Color, count int) []color.Color
• func SplitComplementary(c color.Color) []color.Color
• func Tetradic(c1 color.Color, c2 color.Color) []color.Color
• func Tints(c color.Color, count int) []color.Color
• func ToHex(c color.Color) string
• func Tones(c color.Color, count int) []color.Color
• func Triadic(c color.Color) []color.Color
• func Warm(c color.Color) bool
• type BroadGranularity
  • func (g BroadGranularity) Granularity() (l, c float64)
• type Color
• type ColorGenerator
• type ColorObservation
  • func (c ColorObservation) Coordinates() clusters.Coordinates
  • func (c ColorObservation) Distance(pos clusters.Coordinates) float64
• type Colors
• type FineGranularity
  • func (g FineGranularity) Granularity() (l, c float64)
• type HappyGenerator
  • func (cc HappyGenerator) Valid(col colorful.Color) bool
• type Palette
  • func (g *Palette) AddColors(cc Colors)
  • func (g Palette) Clamped(cc []color.Color) Colors
  • func (g Palette) Color(name string) (color.Color, bool)
  • func (g Palette) Colors() Colors
  • func (g Palette) Filter(name string) Colors
  • func (g Palette) MixedWith(p Palette) Palette
  • func (g Palette) Name(color color.Color) (Colors, float64)
• type PastelGenerator
  • func (cc PastelGenerator) Valid(col colorful.Color) bool
• type SimilarHueGenerator
  • func (gen SimilarHueGenerator) Valid(col colorful.Color) bool
• type WarmGenerator
  • func (cc WarmGenerator) Valid(col colorful.Color) bool

Functions

func Analogous

func Analogous(c color.Color) []color.Color

Analogous returns the analogous values for any given color

func Blends

func Blends(c1, c2 color.Color, count int) []color.Color

Blends returns a slice of interpolated colors, blended between two colors

func Complementary

func Complementary(c color.Color) color.Color

Complementary returns the complementary value for any given color

func Contrast

func Contrast(c color.Color) color.Color

Contrast returns the color with the most contrast (hence either black or white)

func Cool

func Cool(c color.Color) bool

Cool returns whether a color is considered to have a cool temperature

func Darker

func Darker(c color.Color, percent float64) color.Color

Darker returns a darker version of the specified color

func Generate

func Generate(count int, generator ColorGenerator) ([]color.Color, error)

Generate returns a slice with the requested amount of colors, generated by the provided ColorGenerator.

func Hex

func Hex(s string) color.Color

Hex returns the color encoded by a hex-string, e.g. "#ABCDEF".

func HueOffset

func HueOffset(c color.Color, degrees int) color.Color

HueOffset returns color with a different hue angle

func Lighter

func Lighter(c color.Color, percent float64) color.Color

Lighter returns a lighter version of the specified color

func Monochromatic

func Monochromatic(c color.Color, count int) []color.Color

Monochromatic returns the specified amount of monochromatic colors based on a given color's hues

func Quadratic

func Quadratic(c color.Color) []color.Color

Quadratic returns the quadratic values for any given color

func Shades

func Shades(c color.Color, count int) []color.Color

Shades returns the specified amount of a color's shades

func SplitComplementary

func SplitComplementary(c color.Color) []color.Color

SplitComplementary returns the split complementary values for any given color

func Tetradic

func Tetradic(c1 color.Color, c2 color.Color) []color.Color

Tetradic returns the tetradic values for any given color

func Tints

func Tints(c color.Color, count int) []color.Color

Tints returns the specified amount of a color's tints

func ToHex

func ToHex(c color.Color) string

ToHex returns the hex encoding of a color, e.g. "#ABCDEF".

func Tones

func Tones(c color.Color, count int) []color.Color

Tones returns the specified amount of a color's tone

func Triadic

func Triadic(c color.Color) []color.Color

Triadic returns the triadic values for any given color

func Warm

func Warm(c color.Color) bool

Warm returns whether a color is considered to have a warm temperature

Types

type BroadGranularity

type BroadGranularity struct {
}

BroadGranularity is used for wider color spaces, e.g. by the PastelGenerator

func (BroadGranularity) Granularity

func (g BroadGranularity) Granularity() (l, c float64)

Granularity returns BroadGranularity's default values

type Color

type Color struct {
	Name      string
	Color     color.Color
	Reference string
}

A Color is a color including its name and reference URL

type ColorGenerator

type ColorGenerator interface {
	Valid(col colorful.Color) bool
	Granularity() (l, c float64)
}

A ColorGenerator checks whether a point in the three dimensional CIELab space is suitable for color generation.

type ColorObservation

type ColorObservation struct {
	colorful.Color
}

ColorObservation is a wrapper around colorful.Color, implementing the clusters.Observation interface

func (ColorObservation) Coordinates

func (c ColorObservation) Coordinates() clusters.Coordinates

Coordinates returns the data points of a Lab color value

func (ColorObservation) Distance

func (c ColorObservation) Distance(pos clusters.Coordinates) float64

Distance calculates the distance between two ColorObservations in the Lab color space

type Colors

type Colors []Color

Colors is a slice of colors

type FineGranularity

type FineGranularity struct {
}

FineGranularity is used for tighter color spaces, e.g. by the SimilarHueGenerator

func (FineGranularity) Granularity

func (g FineGranularity) Granularity() (l, c float64)

Granularity returns FineGranularity's default values

type HappyGenerator

type HappyGenerator struct {
	BroadGranularity
}

HappyGenerator produces "happy" colors

func (HappyGenerator) Valid

func (cc HappyGenerator) Valid(col colorful.Color) bool

Valid returns true if the color is considered a "happy" color

type Palette

type Palette struct {
	// contains filtered or unexported fields
}

A Palette is a collection of colors

func (*Palette) AddColors

func (g *Palette) AddColors(cc Colors)

AddColors adds colors to the palette

func (Palette) Clamped

func (g Palette) Clamped(cc []color.Color) Colors

Clamped expects a slice of colors and returns a slice of the nearest matching colors from the palette

func (Palette) Color

func (g Palette) Color(name string) (color.Color, bool)

Color returns the color with a specific name

func (Palette) Colors

func (g Palette) Colors() Colors

Colors returns the Palette's colors

func (Palette) Filter

func (g Palette) Filter(name string) Colors

Filter returns colors matching name

func (Palette) MixedWith

func (g Palette) MixedWith(p Palette) Palette

MixedWith mixes two palettes

func (Palette) Name

func (g Palette) Name(color color.Color) (Colors, float64)

Name returns the name of the closest matching color

type PastelGenerator

type PastelGenerator struct {
	BroadGranularity
}

PastelGenerator produces "pastel" colors

func (PastelGenerator) Valid

func (cc PastelGenerator) Valid(col colorful.Color) bool

Valid returns true if the color is considered a "pastel" color

type SimilarHueGenerator

type SimilarHueGenerator struct {
	FineGranularity
	Color color.Color
}

SimilarHueGenerator produces colors with a similar hue as the given color

func (SimilarHueGenerator) Valid

func (gen SimilarHueGenerator) Valid(col colorful.Color) bool

Valid returns true if the given color has a similar hue as the original color

type WarmGenerator

type WarmGenerator struct {
	BroadGranularity
}

WarmGenerator produces "warm" colors

func (WarmGenerator) Valid

func (cc WarmGenerator) Valid(col colorful.Color) bool

Valid returns true if the color is considered a "warm" color