ColorTypes.ColorTypesModule

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 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.

ColorTypes.AGray32Type

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).

ColorTypes.ARGB32Type

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).

ColorTypes.AbstractRGBType

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.

ColorTypes.AlphaColorType

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).

ColorTypes.BGRType

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.

ColorTypes.ColorType

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

ColorTypes.ColorAlphaType

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

ColorTypes.ColorantType

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.

ColorTypes.GrayType

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

ColorTypes.Gray24Type

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).

ColorTypes.HSBType

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

ColorTypes.HSIType

HSI is the Hue-Saturation-Intensity colorspace.

ColorTypes.HSLType

HSL is the Hue-Saturation-Lightness colorspace.

ColorTypes.LCHabType

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

ColorTypes.LCHuvType

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

ColorTypes.LMSType

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

ColorTypes.RGBType

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).

ColorTypes.RGB24Type

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).

ColorTypes.RGBXType

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).

ColorTypes.TransparentColorType

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).

ColorTypes.XRGBType

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).

ColorTypes.XYZType

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.

ColorTypes.YCbCrType

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

ColorTypes.YIQType

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

ColorTypes.xyYType

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

ColorTypes.alphaMethod

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

ColorTypes.alphacolorFunction

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

ColorTypes.base_color_typeMethod
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.

ColorTypes.base_colorant_typeMethod
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)
ColorTypes.blueMethod

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

ColorTypes.ccolorMethod
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.

ColorTypes.chromaMethod

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

Note

The other color types (e.g. RGB, HSV or YCbCr) are not supported because their definitions of chroma are not clear. Colorfulness, chroma and saturation are defined as distinct aspects by the CIE.

ColorTypes.colorMethod

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

ColorTypes.color_typeMethod
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.

ColorTypes.coloralphaFunction

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

ColorTypes.colorsplitMethod
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.

ColorTypes.comp1Method

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.

ColorTypes.comp2Method

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

ColorTypes.comp3Method

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

ColorTypes.comp4Method

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

ColorTypes.comp5Method

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

ColorTypes.grayMethod

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

ColorTypes.greenMethod

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

ColorTypes.hueMethod

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

ColorTypes.issupportedMethod
issupported(C::Type, T::Type)::Bool

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

ColorTypes.mapcMethod
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)
ColorTypes.mapreducecMethod
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.nanMethod
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)
ColorTypes.parametric_colorantMethod
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
ColorTypes.redMethod

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

ColorTypes.reducecMethod
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.

FixedPointNumbers.floattypeMethod
CF = floattype(C::Type)

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

Info

Non-parametric colorants will be promoted to corresponding parametric colorants. For example, floattype(RGB24) == RGB{Float32}.