Basic color definitions and traits
Clone or download

README.md

ColorTypes

Build Status codecov.io

This "minimalistic" package serves as the foundation for working with colors in Julia. It defines basic color types and their constructors, and sets up traits and show methods to make them easier to work with.

Of related interest is the Colors.jl package, which provides "colorimetry" and conversion functions for working with colors. You may also be interested in the ColorVectorSpace.jl package, which defines mathematical operations for certain color types. Both of these packages are based on ColorTypes, which ensures that any color objects will be broadly usable.

Types available in ColorTypes

The type hierarchy and abstract types

Here is the type hierarchy used in ColorTypes:

Types

  • Colorant is the general term used for any object exported by this package. True colors are called Color; TransparentColor indicates an object that also has alpha-channel information.

  • Color{T,3} is a 3-component color (like RGB = red, green, blue); Color{T,1} is a 1-component color, i.e., grayscale).

  • Most colors have both AlphaColor and ColorAlpha variants; for example, RGB has both ARGB and RGBA. These indicate different underlying storage in memory: AlphaColor stores the alpha-channel first, then the color, whereas ColorAlpha stores the color first, then the alpha-channel. Storage order can be particularly important for interfacing with certain external libraries (e.g., OpenGL and Cairo).

  • To support generic programming, TransparentColor constructors always take the alpha channel last, independent of their internal storage order. That is, one uses

RGBA(red, green, blue, alpha)
RGBA(RGB(red, green, blue), alpha)
ARGB(red, green, blue, alpha)       # note alpha is last
ARGB(RGB(red, green, blue), alpha)

This way you can write code with a generic C<:Colorant type and not worry about the proper order for supplying arguments to the constructor. See the traits section for some useful utilities.

Colors

RGB plus BGR, RGB1, RGB4, and RGB24: the AbstractRGB group

The sRGB colorspace.

struct RGB{T} <: AbstractRGB{T}
    r::T # Red in [0,1]
    g::T # Green in [0,1]
    b::T # Blue in [0,1]
end

RGBs may be defined with two broad number types: FloatingPoint and FixedPoint. FixedPoint come from the FixedPointNumbers package, and represent fractional numbers internally using integers. For example, N0f8(1) creates a Normed{UInt8,8} (N0f8 for short) number with value equal to 1.0 but which internally is represented as 0xff. This strategy ensures that 1 always means "saturated color", regardless of how that value is represented. Ordinary integers should not be used, although the convenience constructor RGB(1,0,0) will create a value RGB{N0f8}(1.0, 0.0, 0.0).

The analogous BGR type is defined as

struct BGR{T} <: AbstractRGB{T}
    b::T
    g::T
    r::T
end

i.e., identical to RGB except in the opposite storage order. One crucial point: for all AbstractRGB types, the constructor accepts values in the order (r,g,b) regardless of how they are arranged internally in memory.

RGB1 and RGB4 seem exactly like RGB, but internally they insert one extra ("invisible") padding element; when the element type is N0f8, these have favorable memory alignment for interfacing with libraries like OpenGL.

Finally, one may represent an RGB color as 8-bit values packed into a 32-bit integer:

struct RGB24 <: AbstractRGB{N0f8}
    color::UInt32
end

The storage order is 0xAARRGGBB, where RR means the red channel, GG means the green, and BB means the blue. AA is ignored for RGB24; there is also an ARGB32, for which that byte represents alpha. Note that this type can also be constructed as RGB24(0.8,0.5,0.2). However, since this type has no fields named r, g, b, it is better to extract values from AbstractRGB objects using red(c), green(c), blue(c).

HSV

Hue-Saturation-Value. A common projection of RGB to cylindrical coordinates. This is also sometimes called "HSB" for Hue-Saturation-Brightness.

struct HSV{T} <: Color{T,3}
    h::T # Hue in [0,360)
    s::T # Saturation in [0,1]
    v::T # Value in [0,1]
end

For HSV (and all remaining color types), T must be of FloatingPoint type, since the values range beyond what can be represented with most FixedPoint types.

HSL

Hue-Saturation-Lightness. Another common projection of RGB to cylindrical coordinates.

struct HSL{T} <: Color{T,3}
    h::T # Hue in [0,360)
    s::T # Saturation in [0,1]
    l::T # Lightness in [0,1]
end

HSI

Hue, saturation, intensity, a variation of HSL and HSV commonly used in computer vision.

struct HSI{T} <: Color{T,3}
    h::T
    s::T
    i::T
end

XYZ

The XYZ colorspace standardized by the CIE in 1931, based on experimental measurements of color perception culminating in the CIE standard observer (see Colors.jl's cie_color_match function).

struct XYZ{T} <: Color{T,3}
    x::T
    y::T
    z::T
end

This colorspace is noteworthy because it is linear---values may be added or scaled as if they form a vector space. See further discussion in the ColorVectorSpace.jl package.

xyY

The xyY colorspace is another CIE standardized color space, based directly off of a transformation from XYZ. It was developed specifically because the xy chromaticity space is invariant to the lightness of the patch.

struct xyY{T} <: Color{T,3}
    x::T
    y::T
    Y::T
end

Lab

A perceptually uniform colorspace standardized by the CIE in 1976. See also LUV, the associated colorspace standardized the same year.

struct Lab{T} <: Color{T,3}
    l::T # Luminance in approximately [0,100]
    a::T # Red/Green
    b::T # Blue/Yellow
end

Luv

A perceptually uniform colorspace standardized by the CIE in 1976. See also LAB, a similar colorspace standardized the same year.

struct Luv{T} <: Color{T,3}
    l::T # Luminance
    u::T # Red/Green
    v::T # Blue/Yellow
end

LCHab

The LAB colorspace reparameterized using cylindrical coordinates.

struct LCHab{T} <: Color{T,3}
    l::T # Luminance in [0,100]
    c::T # Chroma
    h::T # Hue in [0,360)
end

LCHuv

The LUV colorspace reparameterized using cylindrical coordinates.

struct LCHuv{T} <: Color{T,3}
    l::T # Luminance
    c::T # Chroma
    h::T # Hue
end

DIN99

The DIN99 uniform colorspace as described in the DIN 6176 specification.

struct DIN99{T} <: Color{T,3}
    l::T # L99 (Lightness)
    a::T # a99 (Red/Green)
    b::T # b99 (Blue/Yellow)
end

DIN99d

The DIN99d uniform colorspace is an improvement on the DIN99 color space that adds a correction to the X tristimulus value in order to emulate the rotation term present in the DeltaE2000 equation.

struct DIN99d{T} <: Color{T,3}
    l::T # L99d (Lightness)
    a::T # a99d (Reddish/Greenish)
    b::T # b99d (Bluish/Yellowish)
end

DIN99o

Revised version of the DIN99 uniform colorspace with modified coefficients for an improved metric. Similar to DIN99d X correction and the DeltaE2000 rotation term, DIN99o achieves comparable results by optimized a*/b* rotation and chroma compression terms.

struct DIN99o{T} <: Color{T,3}
    l::T # L99o (Lightness)
    a::T # a99o (Red/Green)
    b::T # b99o (Blue/Yellow)
end

LMS

Long-Medium-Short cone response values. Multiple methods of converting to LMS space have been defined. Here the CAT02 chromatic adaptation matrix is used.

struct LMS{T} <: Color{T,3}
    l::T # Long
    m::T # Medium
    s::T # Short
end

Like XYZ, LMS is a linear color space.

YIQ (NTSC)

A color-encoding format used by the NTSC broadcast standard.

struct YIQ{T} <: Color{T,3}
    y::T
    i::T
    q::T
end

Y'CbCr

A color-encoding format common in video and digital photography.

struct YCbCr{T} <: Color{T,3}
    y::T
    cb::T
    cr::T
end

Grayscale "colors"

Gray

Gray is a simple wrapper around a number:

struct Gray{T} <: AbstractGray{T}
    val::T
end

In many situations you don't need a Gray wrapper, but there are times when it can be helpful to clarify meaning or assist with dispatching to appropriate methods. It is also present for consistency with the two corresponding grayscale-plus-transparency types, AGray and GrayA.

Gray24 and AGray32

Gray24 is a grayscale value encoded as a UInt32:

struct Gray24 <: AbstractGray{N0f8}
    color::UInt32
end

The storage format is 0xAAIIIIII, where each II pair (I=intensity) must be identical. The AA is ignored, but in the corresponding AGray32 type it encodes alpha.

Traits (utility functions for instances and types)

One of the nicest things about this package is that it provides a rich set of trait-functions for working with color types:

  • eltype(c) extracts the underlying element type, e.g., Float32

  • length(c) extracts the number of components (including alpha, if present)

  • alphacolor(c) and coloralpha(c) convert a Color to an object with transparency (either ARGB or RGBA, respectively).

  • color_type(c) extracts the opaque (color-only) type of the object (e.g., RGB{N0f8} from an object of type ARGB{N0f8}).

  • base_color_type(c) and base_colorant_type(c) extract type information and discard the element type (e.g., base_colorant_type(ARGB{N0f8}) yields ARGB)

  • ccolor(Cdest, Csrc) helps pick a concrete element type for methods where the output may be left unstated, e.g., convert(RGB, c) rather than convert(RGB{N0f8}, c).

All of these methods are individually documented (typically with greater detail); just type ?ccolor at the REPL.

Getters

  • red, green, blue extract channels from AbstractRGB types; gray extracts the intensity from a grayscale object

  • alpha extracts the alpha channel from any Color object (returning 1 if there is no alpha channel)

  • comp1, comp2, and comp3 extract color components in the order expected by the constructor

Functions

  • mapc(f, c) executes the function f on each color channel of c, returning a new color in the same colorspace.

  • reducec(op, v0, c) returns a single number based on a binary operator op across the color channels of c. v0 is the initial value.

  • mapreducec(f, op, v0, c) is similar to reducec except it applies f to each color channel before combining values with op.

Extending ColorTypes and Colors

In most cases, adding a new color space is quite straightforward:

  • Add your new type to types.jl, following the model of the other color types;
  • Add the type to the list of exports in ColorTypes.jl;
  • In the Colors package, add conversions to and from your new colorspace.

In special cases, there may be other considerations:

  • For RGB-related types, 0 means "black" and 1 means "saturated." If your type has unusual numeric interpretation, you may need to add a new number type to FixedPointNumbers and set up appropriate eltype_default and eltype_ub traits.
  • If your type has extra fields, check the "Generated code" section of types.jl carefully. You may need to define a colorfields function and/or call @make_constructors or @make_alpha manually.