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 versionsARGB
,RGBA
,ABGR
,BGRA
, andARGB32
.HSV
,HSL
,HSI
, plus all 6 transparent variants (AHSV
,HSVA
,AHSL
,HSLA
,AHSI
,HSIA
)
XYZ
,xyY
,LMS
and all 6 transparent variantsLab
,Luv
,LCHab
,LCHuv
and all 8 transparent variants
Oklab
,Oklch
and their transparent variants
DIN99
,DIN99d
,DIN99o
and all 6 transparent variantsStorage formats
YIQ
,YCbCr
and their transparent variants
Gray
,Gray24
, and the transparent variantsAGray
,GrayA
, andAGray32
.
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)
Colors.@colorant_str
— Macro@colorant_str(ex)
Parse a literal color name as a Colorant. See Base.parse(Colorant, desc)
.
Base.parse
— Functionparse(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 Colorantdesc
: 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, oran
HSL
color ifhsl(h, s, l)
was usedan
RGBA
color ifrgba(r, g, b, a)
was usedan
HSLA
color ifhsla(h, s, l, a)
was usedan
ARGB{N0f8}
color if0xAARRGGBB
/0xARGB
was useda specific
Colorant
type as specified in the first argument
The X11 color names with spaces (e.g. "sea green") are not recommended because they are not allowed in the SVG/CSS.
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)
Colors.hex
— Functionhex(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. Spesifying the uppercase symbols means the return values are in uppercase. The following symbols are available::AUTO
: notation automatically selected according to the type ofc
: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"
style
requires at least Colors v0.12.
Colors.normalize_hue
— Functionnormalize_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.
Colors.mean_hue
— Functionmean_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.