ColorTypes summary:

Type hierarchy:

                          Colorant{T,N}
             Color{T,N}                    TransparentColor{C,T,N}
     AbstractRGB{T}                  AlphaColor{C,T,N}  ColorAlpha{C,T,N}

Concrete types:

• RGB, BGR, XRGB, RGBX, RGB24 are all subtypes of AbstractRGB

• HSV, HSL, HSI, XYZ, xyY, Lab, LCHab, Luv, LCHuv, DIN99, DIN99d, DIN99o, LMS, YIQ, YCbCR, Oklab, and Oklch are subtypes of Color{T,3}

• Alpha-channel analogs in such as ARGB and RGBA for most of those types (with a few exceptions like RGB24, which has ARGB32)

• Grayscale types Gray and Gray24 (subtypes of Color{T,1}), and the corresponding transparent types AGray, GrayA, and AGray32

• Trait functions eltype, length, alphacolor, coloralpha, color_type, base_color_type, base_colorant_type, ccolor

• Getters red, green, blue, alpha, gray, comp1, comp2, comp3

Use ? to get more information about specific types or functions.

AGray32 uses a UInt32 representation of color, 0xAAIIIIII, where I=intensity (grayscale value) and A=alpha. Each II pair is assumed to be the same. This format is often used by external libraries such as Cairo.

You can extract the single gray value with gray(c) and the alpha as alpha(c). You can construct them directly from a UInt32, or as AGray32(i,alpha). Note that i and alpha are interpreted on a scale from 0 (black) to 1 (white).

ARGB32 uses a UInt32 representation of color, 0xAARRGGBB, where R=red, G=green, B=blue and A is the alpha channel. This format is often used by external libraries such as Cairo. On a little-endian machine, this type has the exact same storage format as BGRA{N0f8}.

ARGB32 colors do not have fields named alpha, r, g, b, but you can still extract the individual components with alpha(c), red(c), green(c), blue(c). You can construct them directly from a UInt32, or as ARGB32(r, g, b, alpha).

AbstractRGB{T} is an abstract supertype for red/green/blue color types that can be constructed as C(r, g, b) and for which the elements can be extracted as red(c), green(c), blue(c). You should not make assumptions about internal storage order, the number of fields, or the representation. One AbstractRGB color-type, RGB24, is not parametric and does not have fields named r, g, b.

AlphaColor is an abstract supertype for types like ARGB, where the alpha channel comes first in the internal storage order. Note that the constructor order is still (color, alpha).

BGR is a variant of RGB with the opposite storage order. Note that the constructor is still called in the order BGR(r, g, b). This storage order is noteworthy because on little-endian machines, BGRA (with transparency) can be reinterpreted to the UInt32 color format used by libraries such as Cairo and OpenGL.

Color{T,N} is the abstract supertype for a color (or grayscale) with no transparency.

ColorAlpha is an abstract supertype for types like RGBA, where the alpha channel comes last in the internal storage order.

Colorant{T,N} is the abstract super-type of all types in ColorTypes, and refers to both (opaque) colors and colors-with-transparency (alpha channel) information. T is the element type (extractable with eltype) and N is the number of meaningful entries (extractable with length), i.e., the number of arguments you would supply to the constructor.

DIN99 is the (L99, a99, b99) adaptation of CIELAB

DIN99d is the (L99d, a99d, b99d) improvement on DIN99

DIN99o is the (L99o, a99o, b99o) adaptation of CIELAB

Gray is a grayscale object. You can extract its value with gray(c).

Gray24 uses a UInt32 representation of color, 0xAAIIIIII, where I=intensity (grayscale value) and A is irrelevant. Each II pair is assumed to be the same. This format is often used by external libraries such as Cairo.

You can extract the single gray value with gray(c). You can construct them directly from a UInt32, or as Gray24(i). Note that i is interpreted on a scale from 0 (black) to 1 (white).

HSB (Hue-Saturation-Brightness) is an alias for HSV.

HSI is the Hue-Saturation-Intensity colorspace.

HSL is the Hue-Saturation-Lightness colorspace.

HSV is the Hue-Saturation-Value colorspace.

LCHab is the Luminance-Chroma-Hue, Polar-Lab colorspace

LCHuv is the Luminance-Chroma-Hue, Polar-Luv colorspace

LMS is the Long-Medium-Short colorspace based on activation of the three cone photoreceptors. Like XYZ, this is a linear color space.

Lab is the CIELAB colorspace.

Luv is the CIELUV colorspace

Oklab is the Oklab colorspace.

Oklch is the Luminance-Chroma-Hue, Polar-Oklab colorspace.

RGB is the standard Red-Green-Blue (sRGB) colorspace. Values of the individual color channels range from 0 (black) to 1 (saturated). If you want "Integer" storage types (e.g., 255 for full color), use N0f8(1) instead (see FixedPointNumbers).

RGB24 uses a UInt32 representation of color, 0xAARRGGBB, where R=red, G=green, B=blue and A is irrelevant. This format is often used by external libraries such as Cairo.

RGB24 colors do not have fields named r, g, b, but you can still extract the individual components with red(c), green(c), blue(c). You can construct them directly from a UInt32, or as RGB(r, g, b).

RGBX is a variant of RGB which has a padding element inserted at the end. In some applications it may have useful memory-alignment properties.

Like all other AbstractRGB objects, the constructor is still called RGBX(r, g, b).

TransparentColor{C,T,N} is the abstract type for any color-with-transparency. The C parameter refers to the type of the pure color (without transparency) and can be extracted with color_type. T is the element type of both C and the alpha channel, and N has the same meaning as in Colorant (and is 1 larger than the corresponding color type).

All transparent types should support two modes of construction:

P(color, alpha)
P(component1, component2, component3, alpha) (assuming a 3-component color)

For a Colorant c, the color component can be extracted with color(c), and the alpha channel with alpha(c). Note that types such as ARGB32 do not have a field named alpha.

Most concrete types, like RGB, have both ARGB and RGBA transparent analogs. These two indicate different internal storage order (see AlphaColor and ColorAlpha, and the alphacolor and coloralpha functions).

XRGB is a variant of RGB which has a padding element inserted at the beginning. In some applications it may have useful memory-alignment properties.

Like all other AbstractRGB objects, the constructor is still called XRGB(r, g, b).

XYZ is the CIE 1931 XYZ colorspace. It is a linear colorspace, meaning that mathematical operations such as addition, subtraction, and scaling make "colorimetric sense" in this colorspace.

YCbCr is the Y'CbCr color encoding often used in digital photography or video

YIQ is a color encoding, for example used in NTSC transmission.

xyY is the CIE 1931 xyY (chromaticity + luminance) space

alpha(p) extracts the alpha component of a color. For a color without an alpha channel, it will always return 1.

alphacolor(RGB) returns ARGB, i.e., the corresponding transparent color type with storage order (alpha, color).

Cbase = base_color_type(C::Type)
Cbase = base_color_type(c::Colorant)

Return the Color type without alpha channel or a specified numeric element type. base_color_type is similar to color_type, except it "strips off" the element type. It always returns a parametric type, which makes it convenient for switching the numeric element type.

For example, compare

base_color_type(RGB{N0f8})  === RGB
base_color_type(RGBA{N0f8}) === RGB

vs

color_type(RGB{N0f8})       === RGB{N0f8}

Switching element types can be done as follows:

c64 = base_color_type(c){Float64}(color(c))

base_color_type discards any alpha channel. See base_colorant_type if you want to preserve the alpha channel.

Cbase = base_colorant_type(C::Type)
Cbase = base_colorant_type(c::Colorant)

Return the Colorant type without specified numeric element type.

For example, compare

base_colorant_type(ARGB{N0f8}) === ARGB

vs

base_color_type(ARGB{N0f8})    === RGB
color_type(ARGB{N0f8})         === RGB{N0f8}

When possible, base_colorant_type returns a parametric UnionAll, so that Cbase{T} can be used to specify a colorant with element type T. However, base_colorant_type is not guaranteed to return a parametric result, for example

julia> base_colorant_type(RGB24)
RGB24

In generic code, you can check whether Cbase is a DataType or UnionAll; Cbase{T} will be valid only if it's a UnionAll.

Usage example

A safe and easy way to switch the element type of a colorant value c to be Float64 is

Cbase = base_colorant_type(parametric_colorant(typeof(c)))
c64 = Cbase{Float64}(c)

blue(c) returns the blue component of an AbstractRGB opaque or transparent color.

C = ccolor(Cdest, Csrc)

ccolor ("concrete color") supports independent selection of colorspace and numeric element type. ccolor chooses the numeric element type from Cdest if available, but if not specified gets it from Csrc.

julia> ccolor(RGB, Gray{Float32})
RGB{Float32}

julia> ccolor(RGB, Gray{N0f8}) == RGB{N0f8}
true

julia> ccolor(RGB{Float32}, Gray{N0f8})
RGB{Float32}

Some colorspaces don't support FixedPoint numeric element types; in such cases the eltype_default for Cdest is chosen:

julia> ccolor(HSV, RGB{N0f8})
HSV{Float32}

Cdest can be an abstract type, in which case Csrc must be in that abstract color space.

julia> ccolor(Color{Float32}, RGB{N0f8})
RGB{Float32}

julia> ccolor(AbstractRGB{Float32}, BGR{N0f8})
BGR{Float32}

julia> ccolor(AbstractRGB{Float32}, HSV{Float32})
ERROR: in ccolor, empty intersection between AbstractRGB and HSV
[...]

ccolor will throw an error when no unambiguous concrete type can be determined. In the previous case, AbstractRGB{Float32} encompases RGB{Float32} and BGR{Float32}.

ccolor is most useful in defining other methods. For example, to allow users to write convert(RGB, c) without having to specify the numeric element type of RGB, define

convert(::Type{C}, p::Colorant) where C<:Colorant = cnvt(ccolor(C,typeof(p)), p)

where cnvt is the function that performs explicit conversion.

chroma(c) returns the chroma of a Lab, Luv, Oklab or their variants color.

color(c) extracts the opaque color component from a Colorant (e.g., omits the alpha channel, if present).

CT = color_type(C::Type)
CT = color_type(c::Colorant)

Return the type of the Color object, discarding any alpha channel. For example,

color_type(RGB)          === RGB
color_type(RGB{Float32}) === RGB{Float32}
color_type(ARGB{N0f8})   === RGB{N0f8}
color_type(RGB(1,0,0))   === RGB{N0f8}

color_type, and related functions like base_color_type, base_colorant_type, and ccolor are useful for manipulating types when writing generic code.

coloralpha(RGB) returns RGBA, i.e., the corresponding transparent color type with storage order (color, alpha).

Calpha, Cbase, T = colorsplit(C)

Split a color type C into three components: T is the numeric type, Cbase is the base_color_type(C), and Calpha is one of Nothing (when C has no transparency), AlphaColor, or ColorAlpha.

If C is an abstract type, Calpha may be TransparentColor or Any.

comp1(c) extracts the first component you'd pass to the constructor of the corresponding object. For most color types without an alpha channel, this is just the first field, but for types like BGR that reverse the internal storage order this provides the value that you'd use to reconstruct the color.

Specifically, for any Color{T,3},

c == typeof(c)(comp1(c), comp2(c), comp3(c))

returns true.

comp2(c) extracts the second constructor argument (see comp1).

comp3(c) extracts the third constructor argument (see comp1).

comp4(c) extracts the fourth constructor argument (see comp1).

comp5(c) extracts the fifth constructor argument (see comp1).

gray(c) returns the gray component of a grayscale opaque or transparent color.

green(c) returns the green component of an AbstractRGB opaque or transparent color.

hue(c) returns the hue in degrees. This function does not guarantee that the return value is in [0, 360].

issupported(C::Type, T::Type)::Bool

Returns true if T is a valid numeric eltype for C<:Colorant.

mapc(f, rgb) -> rgbf
mapc(f, rgb1, rgb2) -> rgbf
mapc(f, rgb1, rgb2, rgb3) -> rgbf

mapc applies the function f to each color channel of the input color(s), returning an output color in the same colorspace.

Examples:

julia> mapc(x->clamp(x,0,1), RGB(-0.2,0.3,1.2))
RGB{Float64}(0.0,0.3,1.0)

julia> mapc(clamp, RGB(-0.2,0.3,1.2), RGB(0, 0.4, 0.5), RGB(1, 0.8, 0.7))
RGB{Float64}(0.0,0.4,0.7)

julia> mapc(max, RGB(0.1,0.8,0.3), RGB(0.5,0.5,0.5))
RGB{Float64}(0.5,0.8,0.5)

julia> mapc(+, RGB(0.1,0.8,0.3), RGB(0.5,0.5,0.5))
RGB{Float64}(0.6,1.3,0.8)

mapreducec(f, op, v0, c)

Reduce across color channels of c with the binary operator op, first applying f to each channel. v0 is the neutral element used to initiate the reduction. For grayscale,

mapreducec(f, op, v0, c::Gray) = op(v0, f(comp1(c)))

whereas for RGB

mapreducec(f, op, v0, c::RGB) = op(f(comp3(c)), op(f(comp2(c)), op(v0, f(comp1(c)))))

If c has an alpha channel, it is always the last one to be folded into the reduction.

ColorTypes.nan(C)

Return a color instance of the specified type in which all components are NaN.

Examples

julia> ColorTypes.nan(RGB{Float32})
RGB{Float32}(NaN32,NaN32,NaN32)

julia> ColorTypes.nan(AHSV{Float64})
AHSV{Float64}(NaN,NaN,NaN,NaN)

Cp = parametric_colorant(C::Type)

Return a parametric colorant type.

Examples

julia> parametric_colorant(RGB)
RGB

julia> parametric_colorant(RGB{Float32})
RGB{Float32}

julia> parametric_colorant(BGR)
BGR

julia> parametric_colorant(RGB24) == RGB{N0f8}
true

red(c) returns the red component of an AbstractRGB opaque or transparent color.

reducec(op, v0, c)

Reduce across color channels of c with the binary operator op. v0 is the neutral element used to initiate the reduction. For grayscale,

reducec(op, v0, c::Gray) = op(v0, comp1(c))

whereas for RGB

reducec(op, v0, c::RGB) = op(comp3(c), op(comp2(c), op(v0, comp1(c))))

If c has an alpha channel, it is always the last one to be folded into the reduction.

CF = floattype(C::Type)

Promote storage data type of colorant type C to AbstractFloat while keeping the base_colorant_type the same.