Construction and Conversion

Available colorspaces

The colorspaces used by Colors are defined in ColorTypes. Briefly, the defined spaces are:

  • Red-Green-Blue spaces: RGB, BGR, XRGB, RGBX, RGB24, plus transparent versions ARGB, RGBA, ABGR, BGRA, and ARGB32.

  • HSV, HSL, HSI, plus all 6 transparent variants (AHSV, HSVA, AHSL, HSLA, AHSI, HSIA)

S 1 0.5 V 1 0.5 0 H 360 0 HSV S 1 0.5 L 1 0.5 0 H 360 0 HSL S 1 0.5 I 1 0.5 0 H 360 0 HSI
  • XYZ, xyY, LMS and all 6 transparent variants

  • Lab, Luv, LCHab, LCHuv and all 8 transparent variants

a* 100 b* 100 0 L* 100 0 Lab u* 100 v* 100 0 L* 100 0 Luv C* 100 50 L* 100 50 0 H 360 0 LCHab C* 100 50 L* 100 50 0 H 360 0 LCHuv
  • Oklab, Oklch and their transparent variants
a 0.4 b 0.4 0 L 1 0 Oklab C 0.4 0.2 L 1 0.5 0 h 360 0 Oklch
  • DIN99, DIN99d, DIN99o and all 6 transparent variants

  • Storage formats YIQ, YCbCr and their transparent variants

I 1 Q 1 0 Y 1 0 YIQ Cb 256 128 Cr 256 128 0 Y 256 0 YCbCr
  • Gray, Gray24, and the transparent variants AGray, GrayA, and AGray32.

Color Parsing

You can parse any CSS color specification with the exception of currentColor. You can construct colors from strings using the @colorant_str macro and the parse function.

julia> using Colors

julia> colorant"red" # named color
RGB{N0f8}(1.0, 0.0, 0.0)

julia> parse(Colorant, "DeepSkyBlue") # color names are case-insensitive
RGB{N0f8}(0.0, 0.749, 1.0)

julia> colorant"#FF0000" # 6-digit hex notation
RGB{N0f8}(1.0, 0.0, 0.0)

julia> colorant"#f00" # 3-digit hex notation
RGB{N0f8}(1.0, 0.0, 0.0)

julia> colorant"rgb(255,0,0)" # rgb() notation with integers in [0, 255]
RGB{N0f8}(1.0, 0.0, 0.0)

julia> colorant"rgba(255,0,0,0.6)" # with alpha in [0, 1]
RGBA{N0f8}(1.0, 0.0, 0.0, 0.6)

julia> colorant"rgba(100%,80%,0.0%,0.6)" # with percentages
RGBA{N0f8}(1.0, 0.8, 0.0, 0.6)

julia> parse(ARGB, "rgba(255,0,0,0.6)") # you can specify the return type
ARGB{N0f8}(1.0, 0.0, 0.0, 0.6)

julia> colorant"hsl(120, 100%, 25%)" # hsl() notation
HSL{Float32}(120.0, 1.0, 0.25)

julia> colorant"hsla(120, 100%, 25%, 60%)" # hsla() notation
HSLA{Float32}(120.0, 1.0, 0.25, 0.6)

julia> colorant"transparent" # transparent "black"
RGBA{N0f8}(0.0, 0.0, 0.0, 0.0)

All CSS/SVG named colors are supported, in addition to X11 named colors, when their definitions do not clash with SVG. You can find all names and their color swatches in Named Colors page.

When writing functions the colorant"red" version is preferred, because the slow step runs when the code is parsed (i.e., during compilation rather than run-time).

The element types of the return types depend on the colorspaces, i.e. the hsl() and hsla() notations return HSL/HSLA colors with Float32 elements, and other notations return RGB/RGBA colors with N0f8 elements. The result colors can be converted to RGB{N0f16} (for example) using:

julia> using FixedPointNumbers

julia> RGB{N0f16}(colorant"indianred")
RGB{N0f16}(0.80392, 0.36078, 0.36078)

or

julia> parse(RGB{N0f16}, "indianred")
RGB{N0f16}(0.80392, 0.36078, 0.36078)

You can convert colors to hexadecimal strings using the hex function. Note that the conversion result does not have the prefix "#".

julia> col = colorant"#C0FFEE"
RGB{N0f8}(0.753, 1.0, 0.933)

julia> hex(col)
"C0FFEE"

Color Conversions

Colors.jl allows you to convert from one colorspace to another using the convert function.

For example:

julia> convert(RGB, HSL(270, 0.5, 0.5)) # without the element type
RGB{Float64}(0.5, 0.25, 0.75)

julia> convert(RGB{N0f8}, HSL(270, 0.5, 0.5)) # with the element type
RGB{N0f8}(0.502, 0.251, 0.749)

Depending on the source and destination colorspace, this may not be perfectly lossless.

Transparent - Opaque Conversions

Colors.jl allows you to convert colors to transparent or opaque types.

julia> col = colorant"yellow"
RGB{N0f8}(1.0, 1.0, 0.0)

julia> transparent = alphacolor(col, 0.5)  # or coloralpha(col)
ARGB{N0f8}(1.0, 1.0, 0.0, 0.502)

julia> opaque = color(transparent)
RGB{N0f8}(1.0, 1.0, 0.0)

Conversion to/from linear RGB

By default, RGB is interpreted as representing the sRGB color space, but it can also be used to represent other RGB color spaces, such as Adobe RGB or DCI-P3.

For interpolation in linear RGB or when working with other RGB color spaces, you can convert RGB colors to and from linear RGB.

julia> to_linear_rgb(RGB{Float32}(1.0, 0.5, 0.0)) # from sRGB to linear RGB
RGB{Float32}(1.0, 0.21404114, 0.0)

julia> from_linear_rgb(RGB{Float32}(1.0, 0.21404114, 0.0)) # from linear RGB to sRGB
RGB{Float32}(1.0, 0.5, 0.0)
Note

to_linear_rgb and from_linear_rgb apply only a transfer function (or its inverse). They do not convert between RGB primaries or white points.


Base.parse — Function
parse(Colorant, desc)

Parse a color description.

This parses a subset of HTML/CSS color specifications. In particular, everything is supported but: currentColor.

It does support named colors (though it uses X11 named colors, which are slightly different than W3C named colors in some cases), rgb(), hsl(), #RGB, and #RRGGBB syntax.

Arguments

  • Colorant: literal Colorant
  • desc: color name or description

A literal Colorant will parse according to the desc string (usually returning an RGB); any more specific choice will return a color of the specified type.

Returns

  • an RGB{N0f8} color, or

  • an HSL color if hsl(h, s, l) was used

  • an RGBA color if rgba(r, g, b, a) was used

  • an HSLA color if hsla(h, s, l, a) was used

  • an ARGB{N0f8} color if 0xAARRGGBB/0xARGB was used

  • a specific Colorant type as specified in the first argument

Note for X11 named colors

The X11 color names with spaces (e.g. "sea green") are not recommended because they are not allowed in the SVG/CSS.

Note for hex notations

You can parse not only the CSS-style hex notations #RRGGBB/#RGB, but also 0xRRGGBB/0xRGB.

You can also parse the 8-digit or 4-digit hex notation into an RGB color with alpha. However, the result depends on the prefix (i.e. # or 0x).

julia> parse(Colorant, "#FF8800AA") # transparent orange
RGBA{N0f8}(1.0,0.533,0.0,0.667)

julia> parse(Colorant, "0xFF8800AA") # opaque purple
ARGB{N0f8}(0.533,0.0,0.667,1.0)
source
Colors.hex — Function
hex(c::Colorant)
hex(c::Colorant, style::Symbol)

Convert a color to a hexadecimal string, optionally specifying its style.

Arguments

  • c: a target color.
  • style: a symbol to specify the hexadecimal notation. Specifying the uppercase symbols means the return values are in uppercase. The following symbols are available:
    • :AUTO: notation automatically selected according to the type of c
    • :RRGGBB/:rrggbb: 6-digit opaque notation
    • :AARRGGBB/:aarrggbb: 8-digit notation with alpha at the head
    • :RRGGBBAA/:rrggbbaa: 8-digit notation with alpha at the tail
    • :RGB/:rgb/:ARGB/:argb/:RGBA/:rgba: 3-digit or 4-digit noatation
    • :S/:s: short notation if available

Examples

julia> hex(RGB(1,0.5,0))
"FF8000"

julia> hex(ARGB(1,0.5,0,0.25))
"40FF8000"

julia> hex(HSV(30,1.0,1.0), :AARRGGBB)
"FFFF8000"

julia> hex(ARGB(1,0.533,0,0.267), :rrggbbaa)
"ff880044"

julia> hex(ARGB(1,0.533,0,0.267), :rgba)
"f804"

julia> hex(ARGB(1,0.533,0,0.267), :S)
"4F80"
Colors v0.12

style requires at least Colors v0.12.

source
Colors.normalize_hue — Function
normalize_hue(h::Real)
normalize_hue(c::Colorant)

Returns a normalized (wrapped-around) hue angle, or a color with the normalized hue, in degrees, in [0, 360]. The normalization is essentially equivalent to mod(h, 360), but is faster at the expense of some accuracy.

source
Colors.mean_hue — Function
mean_hue(h1::Real, h2::Real)
mean_hue(a::C, b::C) where {C <: Colorant}

Compute the mean of two hue angles in degrees.

If the inputs are HSV-like or Lab-like color objects, this will also return a hue, not a color. If one of the colors is achromatic, i.e. has zero saturation or chroma, the hue of the other color is returned instead of the mean.

When the hue difference is exactly 180 degrees, which of the two mean hues is returned depends on the implementation. In other words, it may vary by the color type and version.

source
Colors.to_linear_rgb — Function
to_linear_rgb([C,] rgb; builtin)
to_linear_rgb([C,] rgb [, transfer::Colors.AbstractTransferFunction{N}])

Applies the transfer function to convert an RGB color to the linear RGB.

The transfer argument must be an instance of Colors.AbstractTransferFunction, not a Julia Function. For RGB colors, N must be 1 or 3. The default transfer function is the sRGB transfer function.

C is the result type of the conversion, and defaults to the type of rgb.

See also from_linear_rgb for the inverse operation.

Keyword Arguments

  • builtin: A symbol that specifies a built-in transfer function. The choices are:
    • :Gamma2_4: The gamma 2.4 transfer function, commonly used as an approximation to BT.1886.
    • :sRGB: The sRGB transfer function (approximately gamma 2.2).

Examples

julia> to_linear_rgb(RGB{Float32}, RGB(1.0, 0.5, 0.0))
RGB{Float32}(1.0, 0.21404114, 0.0)

julia> to_linear_rgb(RGB(1, 0.5f0, 0), builtin=:Gamma2_4)
RGB{Float32}(1.0, 0.18946457, 0.0)

julia> to_linear_rgb(RGB(1, 0.5f0, 0), Colors.TransferFunction{:Gamma2_4}())
RGB{Float32}(1.0, 0.18946457, 0.0)
Note

This function does not perform any clamping or validation of the input components, even if the standard specifications require them. Accuracy cannot be guaranteed for input components that exceed the range of [0, 1]. In other words, HDR colors are not supported. Also, the behavior when an output component cannot be represented by the output type is implementation-dependent.

Tip

Specifying builtin=:Gamma2_4 is functionally equivalent to specifying Colors.TransferFunction{:Gamma2_4}() for transfer. However, since the latter style determines the type at compile time, it may be faster than the former.

Colors v0.13.5

to_linear_rgb and from_linear_rgb are introduced in Colors v0.13.5.

source
Colors.from_linear_rgb — Function
from_linear_rgb([C,] rgb; builtin)
from_linear_rgb([C,] rgb [, transfer::AbstractTransferFunction{N}])

Applies the (inverse) transfer function to convert an RGB color from the linear RGB.

The default transfer function is the sRGB transfer function.

C is the result type of the conversion, and defaults to the type of rgb.

See to_linear_rgb for details.

source
Colors.AbstractTransferFunction — Type
Colors.AbstractTransferFunction{N}

Abstract supertype for transfer functions that operate on N real-valued components at a time.

The parameter N specifies the number of components processed by a single application of the transfer function. It is independent of any particular color space or color model.

For N == 1, the transfer function operates on a single Real value. For N > 1, it operates on an NTuple{N} of Real values.

Custom subtypes should implement Colors.to_linear and Colors.from_linear.

source
Colors.TransferFunction — Type
Colors.TransferFunction{S} <: Colors.AbstractTransferFunction{1}

A singleton type that represents a built-in scalar transfer function identified by the symbol S.

source
Colors.to_linear — Function
Colors.to_linear([T,] v::Real, transfer::Colors.AbstractTransferFunction{1})
Colors.to_linear([T,] vs::NTuple{N}, transfer::Colors.AbstractTransferFunction{N}) where {N}

Applies the transfer function to convert a value to its linear representation. T is the result element type, defaulting to typeof(v) or eltype(vs).

See also Colors.from_linear for the inverse operation.

source
Colors.from_linear — Function
Colors.from_linear([T,] v::Real, transfer::Colors.AbstractTransferFunction{1})
Colors.from_linear([T,] vs::NTuple{N}, transfer::Colors.AbstractTransferFunction{N}) where {N}

Applies the (inverse) transfer function to convert a value from its linear representation.

See Colors.to_linear for details.

source