colorful

package
v3.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 12, 2022 License: MIT, MIT Imports: 8 Imported by: 0

README

colorful

A library for playing with colors in Go. Supports Go 1.13 onwards.

Why?

I love games. I make games. I love detail and I get lost in detail. One such detail popped up during the development of Memory Which Does Not Suck, when we wanted the server to assign the players random colors. Sometimes two players got very similar colors, which bugged me. The very same evening, I want hue was the top post on HackerNews' frontpage and showed me how to Do It Right™. Last but not least, there was no library for handling color spaces available in go. Colorful does just that and implements Go's color.Color interface.

What?

Go-Colorful stores colors in RGB and provides methods from converting these to various color-spaces. Currently supported colorspaces are:

  • RGB: All three of Red, Green and Blue in [0..1].
  • HSL: Hue in [0..360], Saturation and Luminance in [0..1]. For legacy reasons; please forget that it exists.
  • HSV: Hue in [0..360], Saturation and Value in [0..1]. You're better off using HCL, see below.
  • Hex RGB: The "internet" color format, as in #FF00FF.
  • Linear RGB: See gamma correct rendering.
  • CIE-XYZ: CIE's standard color space, almost in [0..1].
  • CIE-xyY: encodes chromacity in x and y and luminance in Y, all in [0..1]
  • CIE-L*a*b*: A perceptually uniform color space, i.e. distances are meaningful. L* in [0..1] and a*, b* almost in [-1..1].
  • CIE-L*u*v*: Very similar to CIE-L*a*b*, there is no consensus on which one is "better".
  • CIE-L*C*h° (HCL): This is generally the most useful one; CIE-L*a*b* space in polar coordinates, i.e. a better HSV. H° is in [0..360], C* almost in [0..1] and L* as in CIE-L*a*b*.
  • CIE LCh(uv): Called LuvLCh in code, this is a cylindrical transformation of the CIE-L*u*v* color space. Like HCL above: H° is in [0..360], C* almost in [0..1] and L* as in CIE-L*u*v*.
  • HSLuv: The better alternative to HSL, see here and here. Hue in [0..360], Saturation and Luminance in [0..1].
  • HPLuv: A variant of HSLuv. The color space is smoother, but only pastel colors can be included. Because the valid colors are limited, it's easy to get invalid Saturation values way above 1.0, indicating the color can't be represented in HPLuv beccause it's not pastel.

For the colorspaces where it makes sense (XYZ, Lab, Luv, HCl), the D65 is used as reference white by default but methods for using your own reference white are provided.

A coordinate being almost in a range means that generally it is, but for very bright colors and depending on the reference white, it might overflow this range slightly. For example, C* of #0000ff is 1.338.

Unit-tests are provided.

Nice, but what's it useful for?

  • Converting color spaces. Some people like to do that.
  • Blending (interpolating) between colors in a "natural" look by using the right colorspace.
  • Generating random colors under some constraints (e.g. colors of the same shade, or shades of one color.)
  • Generating gorgeous random palettes with distinct colors of a same temperature.

So which colorspace should I use?

It depends on what you want to do. I think the folks from I want hue are on-spot when they say that RGB fits to how screens produce color, CIE L*a*b* fits how humans perceive color and HCL fits how humans think colors.

Whenever you'd use HSV, rather go for CIE-L*C*h°. for fixed lightness L* and chroma C* values, the hue angle h° rotates through colors of the same perceived brightness and intensity.

How?

Installing

Installing the library is as easy as

$ go get github.com/webnice/kit/v3/module/dye/colorful

The package can then be used through an

import "github.com/webnice/kit/v3/module/dye/colorful"
Basic usage

Create a beautiful blue color using different source space:

// Any of the following should be the same
c := colorful.Color{0.313725, 0.478431, 0.721569}
c, err := colorful.Hex("#517AB8")
if err != nil {
    log.Fatal(err)
}
c = colorful.Hsv(216.0, 0.56, 0.722)
c = colorful.Xyz(0.189165, 0.190837, 0.480248)
c = colorful.Xyy(0.219895, 0.221839, 0.190837)
c = colorful.Lab(0.507850, 0.040585,-0.370945)
c = colorful.Luv(0.507849,-0.194172,-0.567924)
c = colorful.Hcl(276.2440, 0.373160, 0.507849)
fmt.Printf("RGB values: %v, %v, %v", c.R, c.G, c.B)

And then converting this color back into various color spaces:

hex := c.Hex()
h, s, v := c.Hsv()
x, y, z := c.Xyz()
x, y, Y := c.Xyy()
l, a, b := c.Lab()
l, u, v := c.Luv()
h, c, l := c.Hcl()

Note that, because of Go's unfortunate choice of requiring an initial uppercase, the name of the functions relating to the xyY space are just off. If you have any good suggestion, please open an issue. (I don't consider XyY good.)

The color.Color interface

Because a colorful.Color implements Go's color.Color interface (found in the image/color package), it can be used anywhere that expects a color.Color.

Furthermore, you can convert anything that implements the color.Color interface into a colorful.Color using the MakeColor function:

c, ok := colorful.MakeColor(color.Gray16{12345})

Caveat: Be aware that this latter conversion (using MakeColor) hits a corner-case when alpha is exactly zero. Because color.Color uses pre-multiplied alpha colors, this means the RGB values are lost (set to 0) and it's impossible to recover them. In such a case MakeColor will return false as its second value.

Comparing colors

In the RGB color space, the Euclidian distance between colors doesn't correspond to visual/perceptual distance. This means that two pairs of colors which have the same distance in RGB space can look much further apart. This is fixed by the CIE-L*a*b*, CIE-L*u*v* and CIE-L*C*h° color spaces. Thus you should only compare colors in any of these space. (Note that the distance in CIE-L*a*b* and CIE-L*C*h° are the same, since it's the same space but in cylindrical coordinates)

Color distance comparison

The two colors shown on the top look much more different than the two shown on the bottom. Still, in RGB space, their distance is the same. Here is a little example program which shows the distances between the top two and bottom two colors in RGB, CIE-L*a*b* and CIE-L*u*v* space. You can find it in doc/colordist/colordist.go.

package main

import "fmt"
import "github.com/webnice/kit/v3/module/dye/colorful"

func main() {
	c1a := colorful.Color{150.0 / 255.0, 10.0 / 255.0, 150.0 / 255.0}
	c1b := colorful.Color{53.0 / 255.0, 10.0 / 255.0, 150.0 / 255.0}
	c2a := colorful.Color{10.0 / 255.0, 150.0 / 255.0, 50.0 / 255.0}
	c2b := colorful.Color{99.9 / 255.0, 150.0 / 255.0, 10.0 / 255.0}

	fmt.Printf("DistanceRgb:       c1: %v\tand c2: %v\n", c1a.DistanceRgb(c1b), c2a.DistanceRgb(c2b))
	fmt.Printf("DistanceLab:       c1: %v\tand c2: %v\n", c1a.DistanceLab(c1b), c2a.DistanceLab(c2b))
	fmt.Printf("DistanceLuv:       c1: %v\tand c2: %v\n", c1a.DistanceLuv(c1b), c2a.DistanceLuv(c2b))
	fmt.Printf("DistanceCIE76:     c1: %v\tand c2: %v\n", c1a.DistanceCIE76(c1b), c2a.DistanceCIE76(c2b))
	fmt.Printf("DistanceCIE94:     c1: %v\tand c2: %v\n", c1a.DistanceCIE94(c1b), c2a.DistanceCIE94(c2b))
	fmt.Printf("DistanceCIEDE2000: c1: %v\tand c2: %v\n", c1a.DistanceCIEDE2000(c1b), c2a.DistanceCIEDE2000(c2b))
}

Running the above program shows that you should always prefer any of the CIE distances:

$ go run colordist.go
DistanceRgb:       c1: 0.3803921568627451	and c2: 0.3858713931171159
DistanceLab:       c1: 0.32048458312798056	and c2: 0.24397151758565272
DistanceLuv:       c1: 0.5134369614199698	and c2: 0.2568692839860636
DistanceCIE76:     c1: 0.32048458312798056	and c2: 0.24397151758565272
DistanceCIE94:     c1: 0.19799168128511324	and c2: 0.12207136371167401
DistanceCIEDE2000: c1: 0.17274551120971166	and c2: 0.10665210031428465

It also shows that DistanceLab is more formally known as DistanceCIE76 and has been superseded by the slightly more accurate, but much more expensive DistanceCIE94 and DistanceCIEDE2000.

Note that AlmostEqualRgb is provided mainly for (unit-)testing purposes. Use it only if you really know what you're doing. It will eat your cat.

Blending colors

Blending is highly connected to distance, since it basically "walks through" the colorspace thus, if the colorspace maps distances well, the walk is "smooth".

Colorful comes with blending functions in RGB, HSV and any of the LAB spaces. Of course, you'd rather want to use the blending functions of the LAB spaces since these spaces map distances well but, just in case, here is an example showing you how the blendings (#fdffcc to #242a42) are done in the various spaces:

Blending colors in different spaces.

What you see is that HSV is really bad: it adds some green, which is not present in the original colors at all! RGB is much better, but it stays light a little too long. LUV and LAB both hit the right lightness but LAB has a little more color. HCL works in the same vein as HSV (both cylindrical interpolations) but it does it right in that there is no green appearing and the lighthness changes in a linear manner.

While this seems all good, you need to know one thing: When interpolating in any of the CIE color spaces, you might get invalid RGB colors! This is important if the starting and ending colors are user-input or random. An example of where this happens is when blending between #eeef61 and #1e3140:

Invalid RGB colors may crop up when blending in CIE spaces.

You can test whether a color is a valid RGB color by calling the IsValid method and indeed, calling IsValid will return false for the redish colors on the bottom. One way to "fix" this is to get a valid color close to the invalid one by calling Clamped, which always returns a nearby valid color. Doing this, we get the following result, which is satisfactory:

Fixing invalid RGB colors by clamping them to the valid range.

The following is the code creating the above three images; it can be found in doc/colorblend/colorblend.go

package main

import "fmt"
import "github.com/webnice/kit/v3/module/dye/colorful"
import "image"
import "image/draw"
import "image/png"
import "os"

func main() {
    blocks := 10
    blockw := 40
    img := image.NewRGBA(image.Rect(0,0,blocks*blockw,200))

    c1, _ := colorful.Hex("#fdffcc")
    c2, _ := colorful.Hex("#242a42")

    // Use these colors to get invalid RGB in the gradient.
    //c1, _ := colorful.Hex("#EEEF61")
    //c2, _ := colorful.Hex("#1E3140")

    for i := 0 ; i < blocks ; i++ {
        draw.Draw(img, image.Rect(i*blockw,  0,(i+1)*blockw, 40), &image.Uniform{c1.BlendHsv(c2, float64(i)/float64(blocks-1))}, image.Point{}, draw.Src)
        draw.Draw(img, image.Rect(i*blockw, 40,(i+1)*blockw, 80), &image.Uniform{c1.BlendLuv(c2, float64(i)/float64(blocks-1))}, image.Point{}, draw.Src)
        draw.Draw(img, image.Rect(i*blockw, 80,(i+1)*blockw,120), &image.Uniform{c1.BlendRgb(c2, float64(i)/float64(blocks-1))}, image.Point{}, draw.Src)
        draw.Draw(img, image.Rect(i*blockw,120,(i+1)*blockw,160), &image.Uniform{c1.BlendLab(c2, float64(i)/float64(blocks-1))}, image.Point{}, draw.Src)
        draw.Draw(img, image.Rect(i*blockw,160,(i+1)*blockw,200), &image.Uniform{c1.BlendHcl(c2, float64(i)/float64(blocks-1))}, image.Point{}, draw.Src)

        // This can be used to "fix" invalid colors in the gradient.
        //draw.Draw(img, image.Rect(i*blockw,160,(i+1)*blockw,200), &image.Uniform{c1.BlendHcl(c2, float64(i)/float64(blocks-1)).Clamped()}, image.Point{}, draw.Src)
    }

    toimg, err := os.Create("colorblend.png")
    if err != nil {
        fmt.Printf("Error: %v", err)
        return
    }
    defer toimg.Close()

    png.Encode(toimg, img)
}
Generating color gradients

A very common reason to blend colors is creating gradients. There is an example program in doc/gradientgen.go; it doesn't use any API which hasn't been used in the previous example code, so I won't bother pasting the code in here. Just look at that gorgeous gradient it generated in HCL space:

Getting random colors

It is sometimes necessary to generate random colors. You could simply do this on your own by generating colors with random values. By restricting the random values to a range smaller than [0..1] and using a space such as CIE-H*C*l° or HSV, you can generate both random shades of a color or random colors of a lightness:

random_blue := colorful.Hcl(180.0+rand.Float64()*50.0, 0.2+rand.Float64()*0.8, 0.3+rand.Float64()*0.7)
random_dark := colorful.Hcl(rand.Float64()*360.0, rand.Float64(), rand.Float64()*0.4)
random_light := colorful.Hcl(rand.Float64()*360.0, rand.Float64(), 0.6+rand.Float64()*0.4)

Since getting random "warm" and "happy" colors is quite a common task, there are some helper functions:

colorful.WarmColor()
colorful.HappyColor()
colorful.FastWarmColor()
colorful.FastHappyColor()

The ones prefixed by Fast are faster but less coherent since they use the HSV space as opposed to the regular ones which use CIE-L*C*h° space. The following picture shows the warm colors in the top two rows and happy colors in the bottom two rows. Within these, the first is the regular one and the second is the fast one.

Warm, fast warm, happy and fast happy random colors, respectively.

Don't forget to initialize the random seed! You can see the code used for generating this picture in doc/colorgens/colorgens.go.

Getting random palettes

As soon as you need to generate more than one random color, you probably want them to be distinguishible. Playing against an opponent which has almost the same blue as I do is not fun. This is where random palettes can help.

These palettes are generated using an algorithm which ensures that all colors on the palette are as distinguishible as possible. Again, there is a Fast method which works in HSV and is less perceptually uniform and a non-Fast method which works in CIE spaces. For more theory on SoftPalette, check out I want hue. Yet again, there is a Happy and a Warm version, which do what you expect, but now there is an additional Soft version, which is more configurable: you can give a constraint on the color space in order to get colors within a certain feel.

Let's start with the simple methods first, all they take is the amount of colors to generate, which could, for example, be the player count. They return an array of colorful.Color objects:

pal1, err1 := colorful.WarmPalette(10)
pal2 := colorful.FastWarmPalette(10)
pal3, err3 := colorful.HappyPalette(10)
pal4 := colorful.FastHappyPalette(10)
pal5, err5 := colorful.SoftPalette(10)

Note that the non-fast methods may fail if you ask for way too many colors. Let's move on to the advanced one, namely SoftPaletteEx. Besides the color count, this function takes a SoftPaletteSettings object as argument. The interesting part here is its CheckColor member, which is a boolean function taking three floating points as arguments: l, a and b. This function should return true for colors which lie within the region you want and false otherwise. The other members are Iteration, which should be within [5..100] where higher means slower but more exact palette, and ManySamples which you should set to true in case your CheckColor constraint rejects a large part of the color space.

For example, to create a palette of 10 brownish colors, you'd call it like this:

func isbrowny(l, a, b float64) bool {
    h, c, L := colorful.LabToHcl(l, a, b)
    return 10.0 < h && h < 50.0 && 0.1 < c && c < 0.5 && L < 0.5
}
// Since the above function is pretty restrictive, we set ManySamples to true.
brownies := colorful.SoftPaletteEx(10, colorful.SoftPaletteSettings{isbrowny, 50, true})

The following picture shows the palettes generated by all of these methods (sourcecode in doc/palettegens/palettegens.go), in the order they were presented, i.e. from top to bottom: Warm, FastWarm, Happy, FastHappy, Soft, SoftEx(isbrowny). All of them contain some randomness, so YMMV.

All example palettes

Sorting colors

Sorting colors is not a well-defined operation. For example, {dark blue, dark red, light blue, light red} is already sorted if darker colors should precede lighter colors but would need to be re-sorted as {dark red, light red, dark blue, light blue} if longer-wavelength colors should precede shorter-wavelength colors.

Go-Colorful's Sorted function orders a list of colors so as to minimize the average distance between adjacent colors, including between the last and the first. (Sorted does not necessarily find the true minimum, only a reasonably close approximation.) The following picture, illustrates Sorted's behavior:

Sorting colors

The first row represents the input: a slice of 512 randomly chosen colors. The second row shows the colors sorted in CIE-L*C*h° space, ordered first by lightness (L), then by hue angle (h), and finally by chroma (C). Note that distracting pinstripes permeate the colors. Sorting using any color space and any ordering of the channels yields a similar pinstriped pattern. The third row of the image was sorted using Go-Colorful's Sorted function. Although the colors do not appear to be in any particular order, the sequence at least appears smoother than the one sorted by channel.

Using linear RGB for computations

There are two methods for transforming RGB⟷Linear RGB: a fast and almost precise one, and a slow and precise one.

r, g, b := colorful.Hex("#FF0000").FastLinearRgb()

TODO: describe some more.

Want to use some other reference point?
c := colorful.LabWhiteRef(0.507850, 0.040585,-0.370945, colorful.D50)
l, a, b := c.LabWhiteRef(colorful.D50)
Reading and writing colors from databases

The type HexColor makes it easy to store colors as strings in a database. It implements the https://godoc.org/database/sql#Scanner and database/sql/driver.Value interfaces which provide automatic type conversion.

Example:

var hc HexColor
_, err := db.QueryRow("SELECT '#ff0000';").Scan(&hc)
// hc == HexColor{R: 1, G: 0, B: 0}; err == nil

Who?

This library was developed by Lucas Beyer with contributions from Bastien Dejean (@baskerville), Phil Kulak (@pkulak), Christian Muehlhaeuser (@muesli), and Scott Pakin (@spakin).

It is now maintained by makeworld (@makeworld-the-better-one).

License

This repo is under the MIT license, see LICENSE for details.

Documentation

Overview

The colorful package provides all kinds of functions for working with colors.

Index

Constants

View Source 
const Delta = 1.0 / 255.0

Delta This is the tolerance used when comparing colors using AlmostEqualRgb.

View Source 
const LAB_DELTA = 1e-6

Variables

View Source 
var D50 = [3]float64{0.96422, 1.00000, 0.82521}

D50 And another one.

View Source 
var D65 = [3]float64{0.95047, 1.00000, 1.08883}

D65 This is the default reference white point.

Functions

func HPLuvToLuvLCh 

func HPLuvToLuvLCh(h, s, l float64) (float64, float64, float64)

func HSLuvToLuvLCh 

func HSLuvToLuvLCh(h, s, l float64) (float64, float64, float64)

func HclToLab 

func HclToLab(h, c, l float64) (L, a, b float64)

HclToLab func

func LabToHcl 

func LabToHcl(L, a, b float64) (h, c, l float64)

LabToHcl func

func LabToXyz 

func LabToXyz(l, a, b float64) (x, y, z float64)

LabToXyz func

func LabToXyzWhiteRef 

func LabToXyzWhiteRef(l, a, b float64, wref [3]float64) (x, y, z float64)

LabToXyzWhiteRef func

func LinearRgbToXyz 

func LinearRgbToXyz(r, g, b float64) (x, y, z float64)

LinearRgbToXyz func

func LuvLChToHPLuv 

func LuvLChToHPLuv(l, c, h float64) (float64, float64, float64)

func LuvLChToHSLuv 

func LuvLChToHSLuv(l, c, h float64) (float64, float64, float64)

func LuvLChToLuv 

func LuvLChToLuv(l, c, h float64) (L, u, v float64)

LuvLChToLuv func

func LuvToLuvLCh 

func LuvToLuvLCh(L, u, v float64) (l, c, h float64)

LuvToLuvLCh func

func LuvToXyz 

func LuvToXyz(l, u, v float64) (x, y, z float64)

LuvToXyz func

func LuvToXyzWhiteRef 

func LuvToXyzWhiteRef(l, u, v float64, wref [3]float64) (x, y, z float64)

LuvToXyzWhiteRef func

func XyyToXyz 

func XyyToXyz(x, y, Y float64) (X, Yout, Z float64)

XyyToXyz func

func XyzToLab 

func XyzToLab(x, y, z float64) (l, a, b float64)

XyzToLab func

func XyzToLabWhiteRef 

func XyzToLabWhiteRef(x, y, z float64, wref [3]float64) (l, a, b float64)

XyzToLabWhiteRef func

func XyzToLinearRgb 

func XyzToLinearRgb(x, y, z float64) (r, g, b float64)

XyzToLinearRgb converts from CIE XYZ-space to Linear RGB space.

func XyzToLuv 

func XyzToLuv(x, y, z float64) (l, a, b float64)

XyzToLuv func

func XyzToLuvWhiteRef 

func XyzToLuvWhiteRef(x, y, z float64, wref [3]float64) (l, u, v float64)

XyzToLuvWhiteRef func

func XyzToXyy 

func XyzToXyy(X, Y, Z float64) (x, y, Yout float64)

XyzToXyy Well, the name is bad, since it's xyY but Golang needs me to start with a capital letter to make the method public.

func XyzToXyyWhiteRef 

func XyzToXyyWhiteRef(X, Y, Z float64, wref [3]float64) (x, y, Yout float64)

XyzToXyyWhiteRef func

Types

type Color 

type Color struct {
	R, G, B float64
}

Color A color is stored internally using sRGB (standard RGB) values in the range 0-1

func FastHappyColor 

func FastHappyColor() Color

FastHappyColor Creates a random bright, "pimpy" color through a restricted HSV space.

func FastHappyPalette 

func FastHappyPalette(colorsCount int) (colors []Color)

FastHappyPalette Uses the HSV color space to generate colors with similar S,V but distributed evenly along their Hue. This is fast but not always pretty. If you've got time to spare, use Lab (the non-fast below).

func FastLinearRgb 

func FastLinearRgb(r, g, b float64) Color

FastLinearRgb is much faster than and almost as accurate as LinearRgb. BUT it is important to NOTE that they only produce good results for valid inputs r,g,b in [0,1].

func FastWarmColor 

func FastWarmColor() Color

FastWarmColor Creates a random dark, "warm" color through a restricted HSV space.

func FastWarmPalette 

func FastWarmPalette(colorsCount int) (colors []Color)

FastWarmPalette Uses the HSV color space to generate colors with similar S,V but distributed evenly along their Hue. This is fast but not always pretty. If you've got time to spare, use Lab (the non-fast below).

func HPLuv 

func HPLuv(h, s, l float64) Color

HPLuv creates a new Color from values in the HPLuv color space. Hue in [0..360], a Saturation [0..1], and a Luminance (lightness) in [0..1].

The returned color values are clamped (using .Clamped), so this will never output an invalid color.

func HSLuv 

func HSLuv(h, s, l float64) Color

HSLuv creates a new Color from values in the HSLuv color space. Hue in [0..360], a Saturation [0..1], and a Luminance (lightness) in [0..1].

The returned color values are clamped (using .Clamped), so this will never output an invalid color.

func HappyColor 

func HappyColor() (c Color)

HappyColor Creates a random bright, "pimpy" color through restricted HCL space. This is slower than FastHappyColor but will likely give you colors which have the same "brightness" if you run it many times.

func HappyPalette 

func HappyPalette(colorsCount int) ([]Color, error)

HappyPalette func

func Hcl 

func Hcl(h, c, l float64) Color

Hcl Generates a color by using data given in HCL space using D65 as reference white. H values are in [0..360], C and L values are in [0..1] WARNING: many combinations of `h`, `c`, and `l` values do not have corresponding valid RGB values, check the FAQ in the README if you're unsure.

func HclWhiteRef 

func HclWhiteRef(h, c, l float64, wref [3]float64) Color

HclWhiteRef Generates a color by using data given in HCL space, taking into account a given reference white. (i.e. the monitor's white) H values are in [0..360], C and L values are in [0..1]

func Hex 

func Hex(scol string) (Color, error)

Hex parses a "html" hex color-string, either in the 3 "#f0c" or 6 "#ff1034" digits form.

func Hsl 

func Hsl(h, s, l float64) Color

Hsl creates a new Color given a Hue in [0..360], a Saturation [0..1], and a Luminance (lightness) in [0..1]

func Hsv 

func Hsv(H, S, V float64) Color

Hsv creates a new Color given a Hue in [0..360], a Saturation and a Value in [0..1]

func Lab 

func Lab(l, a, b float64) Color

Lab Generates a color by using data given in CIE L*a*b* space using D65 as reference white. WARNING: many combinations of `l`, `a`, and `b` values do not have corresponding valid RGB values, check the FAQ in the README if you're unsure.

func LabWhiteRef 

func LabWhiteRef(l, a, b float64, wref [3]float64) Color

LabWhiteRef Generates a color by using data given in CIE L*a*b* space, taking into account a given reference white. (i.e. the monitor's white)

func LinearRgb 

func LinearRgb(r, g, b float64) Color

LinearRgb creates an sRGB color out of the given linear RGB color (see http://www.sjbrown.co.uk/2004/05/14/gamma-correct-rendering/).

func Luv 

func Luv(l, u, v float64) Color

Luv Generates a color by using data given in CIE L*u*v* space using D65 as reference white. L* is in [0..1] and both u* and v* are in about [-1..1] WARNING: many combinations of `l`, `u`, and `v` values do not have corresponding valid RGB values, check the FAQ in the README if you're unsure.

func LuvLCh 

func LuvLCh(l, c, h float64) Color

LuvLCh Generates a color by using data given in LuvLCh space using D65 as reference white. h values are in [0..360], C and L values are in [0..1] WARNING: many combinations of `l`, `c`, and `h` values do not have corresponding valid RGB values, check the FAQ in the README if you're unsure.

func LuvLChWhiteRef 

func LuvLChWhiteRef(l, c, h float64, wref [3]float64) Color

LuvLChWhiteRef Generates a color by using data given in LuvLCh space, taking into account a given reference white. (i.e. the monitor's white) h values are in [0..360], C and L values are in [0..1]

func LuvWhiteRef 

func LuvWhiteRef(l, u, v float64, wref [3]float64) Color

LuvWhiteRef Generates a color by using data given in CIE L*u*v* space, taking into account a given reference white. (i.e. the monitor's white) L* is in [0..1] and both u* and v* are in about [-1..1]

func MakeColor 

func MakeColor(col color.Color) (Color, bool)

MakeColor Constructs a colorful.Color from something implementing color.Color

func SoftPalette 

func SoftPalette(colorsCount int) ([]Color, error)

A wrapper which uses common parameters.

func SoftPaletteEx 

func SoftPaletteEx(colorsCount int, settings SoftPaletteSettings) ([]Color, error)

SoftPaletteEx Yeah, windows-stype Foo, FooEx, screw you golang... Uses K-means to cluster the color-space and return the means of the clusters as a new palette of distinctive colors. Falls back to K-medoid if the mean happens to fall outside of the color-space, which can only happen if you specify a CheckColor function.

func Sorted 

func Sorted(cs []Color) []Color

Sorted sorts a list of Color values. Sorting is not a well-defined operation for colors so the intention here primarily is to order colors so that the transition from one to the next is fairly smooth.

func WarmColor 

func WarmColor() (c Color)

WarmColor Creates a random dark, "warm" color through restricted HCL space. This is slower than FastWarmColor but will likely give you colors which have the same "warmness" if you run it many times.

func WarmPalette 

func WarmPalette(colorsCount int) ([]Color, error)

func Xyy 

func Xyy(x, y, Y float64) Color

Xyy Generates a color by using data given in CIE xyY space. x, y and Y are in [0..1]

func Xyz 

func Xyz(x, y, z float64) Color

Xyz func

func (Color) AlmostEqualRgb 

func (c1 Color) AlmostEqualRgb(c2 Color) bool

AlmostEqualRgb Check for equality between colors within the tolerance Delta (1/255).

func (Color) BlendHcl 

func (col1 Color) BlendHcl(col2 Color, t float64) Color

BlendHcl blends two colors in the CIE-L*C*h° color-space, which should result in a smoother blend. t == 0 results in c1, t == 1 results in c2

func (Color) BlendHsv 

func (c1 Color) BlendHsv(c2 Color, t float64) Color

BlendHsv You don't really want to use this, do you? Go for BlendLab, BlendLuv or BlendHcl.

func (Color) BlendLab 

func (c1 Color) BlendLab(c2 Color, t float64) Color

BlendLab blends two colors in the L*a*b* color-space, which should result in a smoother blend. t == 0 results in c1, t == 1 results in c2

func (Color) BlendLinearRgb 

func (c1 Color) BlendLinearRgb(c2 Color, t float64) Color

BlendLinearRgb blends two colors in the Linear RGB color-space. Unlike BlendRgb, this will not produce dark color around the center. t == 0 results in c1, t == 1 results in c2

func (Color) BlendLuv 

func (c1 Color) BlendLuv(c2 Color, t float64) Color

BlendLuv blends two colors in the CIE-L*u*v* color-space, which should result in a smoother blend. t == 0 results in c1, t == 1 results in c2

func (Color) BlendLuvLCh 

func (col1 Color) BlendLuvLCh(col2 Color, t float64) Color

BlendLuvLCh blends two colors in the cylindrical CIELUV color space. t == 0 results in c1, t == 1 results in c2

func (Color) BlendRgb 

func (c1 Color) BlendRgb(c2 Color, t float64) Color

BlendRgb You don't really want to use this, do you? Go for BlendLab, BlendLuv or BlendHcl.

func (Color) Clamped 

func (c Color) Clamped() Color

Clamped Returns Clamps the color into valid range, clamping each value to [0..1] If the color is valid already, this is a no-op.

func (Color) DistanceCIE76 

func (c1 Color) DistanceCIE76(c2 Color) float64

DistanceCIE76 is the same as DistanceLab.

func (Color) DistanceCIE94 

func (cl Color) DistanceCIE94(cr Color) float64

DistanceCIE94 Uses the CIE94 formula to calculate color distance. More accurate than DistanceLab, but also more work.

func (Color) DistanceCIEDE2000 

func (cl Color) DistanceCIEDE2000(cr Color) float64

DistanceCIEDE2000 uses the Delta E 2000 formula to calculate color distance. It is more expensive but more accurate than both DistanceLab and DistanceCIE94.

func (Color) DistanceCIEDE2000klch 

func (cl Color) DistanceCIEDE2000klch(cr Color, kl, kc, kh float64) float64

DistanceCIEDE2000klch uses the Delta E 2000 formula with custom values for the weighting factors kL, kC, and kH.

func (Color) DistanceHPLuv 

func (c1 Color) DistanceHPLuv(c2 Color) float64

DistanceHPLuv calculates Euclidean distance in the HPLuv colorspace. No idea how useful this is.

The Hue value is divided by 100 before the calculation, so that H, S, and L have the same relative ranges.

func (Color) DistanceHSLuv 

func (c1 Color) DistanceHSLuv(c2 Color) float64

DistanceHSLuv calculates Euclidan distance in the HSLuv colorspace. No idea how useful this is.

The Hue value is divided by 100 before the calculation, so that H, S, and L have the same relative ranges.

func (Color) DistanceLab 

func (c1 Color) DistanceLab(c2 Color) float64

DistanceLab is a good measure of visual similarity between two colors! A result of 0 would mean identical colors, while a result of 1 or higher means the colors differ a lot.

func (Color) DistanceLinearRGB 

func (c1 Color) DistanceLinearRGB(c2 Color) float64

DistanceLinearRGB is deprecated in favour of DistanceLinearRgb. They do the exact same thing.

func (Color) DistanceLinearRgb 

func (c1 Color) DistanceLinearRgb(c2 Color) float64

DistanceLinearRgb computes the distance between two colors in linear RGB space. This is not useful for measuring how humans perceive color, but might be useful for other things, like dithering.

func (Color) DistanceLuv 

func (c1 Color) DistanceLuv(c2 Color) float64

DistanceLuv is a good measure of visual similarity between two colors! A result of 0 would mean identical colors, while a result of 1 or higher means the colors differ a lot.

func (Color) DistanceRgb 

func (c1 Color) DistanceRgb(c2 Color) float64

DistanceRgb computes the distance between two colors in RGB space. This is not a good measure! Rather do it in Lab space.

func (Color) DistanceRiemersma 

func (c1 Color) DistanceRiemersma(c2 Color) float64

DistanceRiemersma is a color distance algorithm developed by Thiadmer Riemersma. It uses RGB coordinates, but he claims it has similar results to CIELUV. This makes it both fast and accurate.

Sources: 

https://www.compuphase.com/cmetric.htm
https://github.com/lucasb-eyer/go-colorful/issues/52

func (Color) FastLinearRgb 

func (col Color) FastLinearRgb() (r, g, b float64)

FastLinearRgb is much faster than and almost as accurate as LinearRgb. BUT it is important to NOTE that they only produce good results for valid colors r,g,b in [0,1].

func (Color) HPLuv 

func (col Color) HPLuv() (h, s, l float64)

HPLuv returns the Hue, Saturation and Luminance of the color in the HSLuv color space. Hue in [0..360], a Saturation [0..1], and a Luminance (lightness) in [0..1].

Note that HPLuv can only represent pastel colors, and so the Saturation value could be much larger than 1 for colors it can't represent.

func (Color) HSLuv 

func (col Color) HSLuv() (h, s, l float64)

HSLuv returns the Hue, Saturation and Luminance of the color in the HSLuv color space. Hue in [0..360], a Saturation [0..1], and a Luminance (lightness) in [0..1].

func (Color) Hcl 

func (col Color) Hcl() (h, c, l float64)

Hcl Converts the given color to HCL space using D65 as reference white. H values are in [0..360], C and L values are in [0..1] although C can overshoot 1.0

func (Color) HclWhiteRef 

func (col Color) HclWhiteRef(wref [3]float64) (h, c, l float64)

HclWhiteRef Converts the given color to HCL space, taking into account a given reference white. (i.e. the monitor's white) H values are in [0..360], C and L values are in [0..1]

func (Color) Hex 

func (col Color) Hex() string

Hex returns the hex "html" representation of the color, as in #ff0080.

func (Color) Hsl 

func (col Color) Hsl() (h, s, l float64)

Hsl returns the Hue [0..360], Saturation [0..1], and Luminance (lightness) [0..1] of the color.

func (Color) Hsv 

func (col Color) Hsv() (h, s, v float64)

Hsv returns the Hue [0..360], Saturation and Value [0..1] of the color.

func (Color) IsValid 

func (c Color) IsValid() bool

IsValid Checks whether the color exists in RGB space, i.e. all values are in [0..1]

func (Color) Lab 

func (col Color) Lab() (l, a, b float64)

Lab Converts the given color to CIE L*a*b* space using D65 as reference white.

func (Color) LabWhiteRef 

func (col Color) LabWhiteRef(wref [3]float64) (l, a, b float64)

LabWhiteRef Converts the given color to CIE L*a*b* space, taking into account a given reference white. (i.e. the monitor's white)

func (Color) LinearRgb 

func (col Color) LinearRgb() (r, g, b float64)

LinearRgb converts the color into the linear RGB space (see http://www.sjbrown.co.uk/2004/05/14/gamma-correct-rendering/).

func (Color) Luv 

func (col Color) Luv() (l, u, v float64)

Luv Converts the given color to CIE L*u*v* space using D65 as reference white. L* is in [0..1] and both u* and v* are in about [-1..1]

func (Color) LuvLCh 

func (col Color) LuvLCh() (l, c, h float64)

LuvLCh Converts the given color to LuvLCh space using D65 as reference white. h values are in [0..360], C and L values are in [0..1] although C can overshoot 1.0

func (Color) LuvLChWhiteRef 

func (col Color) LuvLChWhiteRef(wref [3]float64) (l, c, h float64)

LuvLChWhiteRef Converts the given color to LuvLCh space, taking into account a given reference white. (i.e. the monitor's white) h values are in [0..360], c and l values are in [0..1]

func (Color) LuvWhiteRef 

func (col Color) LuvWhiteRef(wref [3]float64) (l, u, v float64)

LuvWhiteRef Converts the given color to CIE L*u*v* space, taking into account a given reference white. (i.e. the monitor's white) L* is in [0..1] and both u* and v* are in about [-1..1]

func (Color) RGB255 

func (col Color) RGB255() (r, g, b uint8)

RGB255 Might come in handy sometimes to reduce boilerplate code.

func (Color) RGBA 

func (col Color) RGBA() (r, g, b, a uint32)

RGBA Implement the Go color.Color interface.

func (Color) Xyy 

func (col Color) Xyy() (x, y, Y float64)

Xyy Converts the given color to CIE xyY space using D65 as reference white. (Note that the reference white is only used for black input.) x, y and Y are in [0..1]

func (Color) XyyWhiteRef 

func (col Color) XyyWhiteRef(wref [3]float64) (x, y, Y float64)

XyyWhiteRef Converts the given color to CIE xyY space, taking into account a given reference white. (i.e. the monitor's white) (Note that the reference white is only used for black input.) x, y and Y are in [0..1]

func (Color) Xyz 

func (col Color) Xyz() (x, y, z float64)

Xyz func

type HexColor 

type HexColor Color

A HexColor is a Color stored as a hex string "#rrggbb". It implements the database/sql.Scanner, database/sql/driver.Value, encoding/json.Unmarshaler and encoding/json.Marshaler interfaces.

func (*HexColor) Decode 

func (hc *HexColor) Decode(hexCode string) error

Decode - deserialize function for https://github.com/kelseyhightower/envconfig

func (HexColor) MarshalJSON 

func (hc HexColor) MarshalJSON() ([]byte, error)

func (HexColor) MarshalYAML 

func (hc HexColor) MarshalYAML() (interface{}, error)

func (*HexColor) Scan 

func (hc *HexColor) Scan(value interface{}) error

func (*HexColor) UnmarshalJSON 

func (hc *HexColor) UnmarshalJSON(data []byte) error

func (*HexColor) UnmarshalYAML 

func (hc *HexColor) UnmarshalYAML(unmarshal func(interface{}) error) error

func (*HexColor) Value 

func (hc *HexColor) Value() (driver.Value, error)

type SoftPaletteSettings 

type SoftPaletteSettings struct {
	// A function which can be used to restrict the allowed color-space.
	CheckColor func(l, a, b float64) bool

	// The higher, the better quality but the slower. Usually two figures.
	Iterations int

	// Use up to 160000 or 8000 samples of the L*a*b* space (and thus calls to CheckColor).
	// Set this to true only if your CheckColor shapes the Lab space weirdly.
	ManySamples bool
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.