View Source Ultraviolet.Color (Ultraviolet v0.1.1)

functions related to parsing and generating Color structs for use elsewhere in Ultraviolet.

Color Spaces

Colors, by default, are stored in sRGB representation, but supports other color spaces as input to new/4 and new/5, where the last parameter is the color space to translate from.

Available Spaces

sRGB (the default): :rgb
HSL: :hsl
HSV / HSV: :hsv
CIE Lab: :lab
LCH: :lch, :hcl
OKLab: :oklab
OKLCH: :oklch

Other Scales

I may add these based on need in the future:

GL (RGBA normalized to 0..1)
CMYK

Summary

Types

blend_mode()

Blend Modes for use with blend/2 or blend/3

channels()

Generic channel input for a color creation function.

input()

Generic input for a color creation function.

space()

The available color spaces for transformation, interpolation, and scales.

space_t()

t()

Defines the channels in an sRGB color.

Functions

alpha(color)

Get the color opacity.

alpha(color, alpha)

Set the color opacity.

average(color, targets, options \\ [])

Mixes several colors. If weights are given, a weighted average is calculated; the number of weights must equal the number of colors.

blend(color, mask, blend_mode \\ :normal)

Blends two colors using RGB channel-wise blend functions. See Ultraviolet.blend/3 for examples and valid blend spaces.

brighten!(color, amount \\ 1)

Brighten a color.

css(color)

Returns the CSS representation of an RGB color

darken!(color, amount \\ 1)

Darken a color.

desaturate!(color, amount \\ 1)

Decreases the saturation of a color by manipulating the Lch chromaticity.

hex(color)

Returns the hexadecimal representation of an RGB color.

into(color, space, options \\ [])

Converts a Color to a different colorspace.

mix(color, target, options \\ [])

Mixes two colors. The mix weight is a value between 0 and 1.

new(n)

Generates a Color from a hex string, W3CX11 specification color name, integer, or channel tuple/map/list/keyword list.

new(channels, options)

Creates a new Color from the given channels and options.

saturate!(color, amount \\ 1)

Increases the saturation of a color by manipulating the Lch chromaticity.

shade!(color, options \\ [])

Produces a shade of the given color. This is syntactic sugar for mix/4 with a target color of black.

temperature(color)

Estimates the temperature of a given color, though this only makes sense for colors from the temperature gradient.

tint!(color, options \\ [])

Produces a tint of the given color. This is syntactic sugar for mix/4 with a target color of white.

Types

blend_mode()

@type blend_mode() ::
  :normal | :multiply | :darken | :lighten | :screen | :overlay | :burn | :dodge

Blend Modes for use with blend/2 or blend/3

channels()

@type channels() :: [number()] | tuple() | [...] | map()

Generic channel input for a color creation function.

input()

@type input() :: String.t() | integer() | channels() | t()

Generic input for a color creation function.

space()

@type space() :: :rgb | :lrgb | :hsl | :lab | :lch | :hcl | :oklab | :oklch

The available color spaces for transformation, interpolation, and scales.

space_t()

@type space_t() ::
  t()
  | Ultraviolet.Color.HSL.t()
  | Ultraviolet.Color.HSV.t()
  | Ultraviolet.Color.Lab.t()
  | Ultraviolet.Color.LCH.t()
  | Ultraviolet.Color.OKLab.t()
  | Ultraviolet.Color.OKLCH.t()

t()

@type t() :: %Ultraviolet.Color{a: number(), b: number(), g: number(), r: number()}

Defines the channels in an sRGB color.

This is the core Ultraviolet structure. See Ultraviolet for examples of how it can be used.

Functions

alpha(color)

@spec alpha(space_t()) :: number()

Get the color opacity.

Examples

iex> {:ok, color} = Color.new("red");
iex> Color.alpha(color)
1.0

alpha(color, alpha)

@spec alpha(space_t(), number()) :: space_t()

Set the color opacity.

Examples

iex> {:ok, color} = Color.new("red");
iex> Color.alpha(color, 0.5)
%Color{r: 255, g: 0, b: 0, a: 0.5}

average(color, targets, options \\ [])

@spec average(t(), [t()], list()) :: {:ok, t()} | {:error, term()}

Mixes several colors. If weights are given, a weighted average is calculated; the number of weights must equal the number of colors.

See Ultraviolet.average/2 for documentation and examples.

blend(color, mask, blend_mode \\ :normal)

@spec blend(t(), t(), blend_mode()) :: {:ok, t()} | {:error, term()}

Blends two colors using RGB channel-wise blend functions. See Ultraviolet.blend/3 for examples and valid blend spaces.

brighten!(color, amount \\ 1)

@spec brighten!(t(), number()) :: t()

Brighten a color.

Examples

iex> {:ok, color} = Color.new("hotpink");
iex> Color.hex(Color.brighten!(color))
"#ff9ce6"
iex> Color.hex(Color.brighten!(color, 2))
"#ffd1ff"
iex> Color.hex(Color.brighten!(color, 3))
"#ffffff"

css(color)

@spec css(t()) :: String.t()

Returns the CSS representation of an RGB color

Examples

iex>Color.css(%Color{})
"rgb(0 0 0)"
iex>Color.css(%Color{r: 255})
"rgb(255 0 0)"
iex>Color.css(%Color{r: 255, a: 0.5})
"rgb(255 0 0 / 0.5)"

darken!(color, amount \\ 1)

@spec darken!(t(), number()) :: t()

Darken a color.

Examples

iex> {:ok, color} = Color.new("hotpink");
iex> Color.hex(Color.darken!(color))
"#c93384"
iex> Color.hex(Color.darken!(color, 2))
"#940058"
iex> Color.hex(Color.darken!(color, 2.6))
"#74003f"

desaturate!(color, amount \\ 1)

@spec desaturate!(t(), number()) :: t()

Decreases the saturation of a color by manipulating the Lch chromaticity.

Examples

iex> {:ok, color} = Color.new("hotpink");
iex> Color.hex(Color.desaturate!(color))
"#e77dae"
iex> Color.hex(Color.desaturate!(color, 2))
"#cd8ca8"
iex> Color.hex(Color.desaturate!(color, 3))
"#b199a3"

hex(color)

@spec hex(t()) :: String.t()

Returns the hexadecimal representation of an RGB color.

Examples

iex>Color.hex(%Color{})
"#000000"
iex>Color.hex(%Color{r: 255})
"#ff0000"
iex>Color.hex(%Color{r: 255, a: 0.5})
"#ff000080"

You can also use to_string to output this value

iex>to_string(%Color{r: 255, a: 0.5})
"#ff000080"

into(color, space, options \\ [])

@spec into(t(), space(), list()) :: {:ok, space_t()} | {:error, term()}

Converts a Color to a different colorspace.

Examples

HSL

iex>{:ok, color} = Ultraviolet.Color.new("#ff3399")
{:ok, %Ultraviolet.Color{r: 255, g: 51, b: 153}}
iex> Ultraviolet.Color.into(color, :hsl)
{:ok, %Ultraviolet.Color.HSL{h: 330, s: 1.0, l: 0.6}}

HSV / HSB

iex>{:ok, color} = Ultraviolet.Color.new("#ff3399")
{:ok, %Ultraviolet.Color{r: 255, g: 51, b: 153}}
iex> Ultraviolet.Color.into(color, :hsv)
{:ok, %Ultraviolet.Color.HSV{h: 330, s: 0.8, v: 1.0}}

Lab

iex>{:ok, color} = Ultraviolet.Color.new("hotpink")
{:ok, %Ultraviolet.Color{r: 255, g: 105, b: 180}}
iex> Ultraviolet.Color.into(color, :lab)
{:ok, %Ultraviolet.Color.Lab{l_: 65.49, a_: 64.24, b_: -10.65}}
iex> Ultraviolet.Color.into(color, :lab, reference: :f2)
{:ok, %Ultraviolet.Color.Lab{l_: 66.28, a_: 61.45, b_: -8.62}}
# try going the other way now
iex> Ultraviolet.new({66.28, 61.45, -8.62, 1.0}, space: :lab, reference: :f2)
{:ok, %Ultraviolet.Color{r: 255, g: 105, b: 180}}
iex> Ultraviolet.new(%{l_: 66.28, a_: 61.45, b_: -8.62}, space: :lab, reference: :f2)
{:ok, %Ultraviolet.Color{r: 255, g: 105, b: 180}}
iex> Ultraviolet.new({65.49, 64.24, -10.65, 1.0}, space: :lab)
{:ok, %Ultraviolet.Color{r: 255, g: 105, b: 180}}

LCH / HCL

iex>{:ok, color} = Ultraviolet.Color.new("#aad28c")
{:ok, %Ultraviolet.Color{r: 170, g: 210, b: 140, a: 1.0}}
iex> Ultraviolet.Color.into(color, :lch, round: 0)
{:ok, %Ultraviolet.Color.LCH{l: 80, c: 40, h: 130}}
iex> Ultraviolet.Color.into(color, :hcl, round: 0)
{:ok, %Ultraviolet.Color.LCH{l: 80, c: 40, h: 130}}

OKLab

iex>{:ok, color} = Ultraviolet.Color.new("#d9c500")
{:ok, %Ultraviolet.Color{r: 217, g: 197, b: 0, a: 1.0}}
iex> Ultraviolet.Color.into(color, :oklab, round: 2)
{:ok, %Ultraviolet.Color.OKLab{l_: 0.81, a_: -0.04, b_: 0.17}}

OKLCH

iex>{:ok, color} = Ultraviolet.Color.new("#aad28c")
{:ok, %Ultraviolet.Color{r: 170, g: 210, b: 140, a: 1.0}}
iex> Ultraviolet.Color.into(color, :oklch, round: 0)
{:ok, %Ultraviolet.Color.OKLCH{l: 1, c: 0, h: 132}}
iex> Ultraviolet.Color.into(color, :oklch, round: 1)
{:ok, %Ultraviolet.Color.OKLCH{l: 0.8, c: 0.1, h: 132.5}}

mix(color, target, options \\ [])

@spec mix(t(), t(), list()) :: {:ok, t()} | {:error, term()}

Mixes two colors. The mix weight is a value between 0 and 1.

See Ultraviolet.mix/3 for documentation and examples.

new(n)

@spec new(input()) :: {:ok, t()} | {:error, term()}

Generates a Color from a hex string, W3CX11 specification color name, integer, or channel tuple/map/list/keyword list.

See Ultraviolet.new/1 for more details.

new(channels, options)

@spec new(channels(), list()) :: {:ok, t()} | {:error, term()}

Creates a new Color from the given channels and options.

See Ultraviolet.new/2 for more details.

saturate!(color, amount \\ 1)

@spec saturate!(t(), number()) :: t()

Increases the saturation of a color by manipulating the Lch chromaticity.

Examples

iex> {:ok, color} = Color.new("slategray");
iex> Color.hex(Color.saturate!(color))
"#4b83ae"
iex> Color.hex(Color.saturate!(color, 2))
"#0087cd"
iex> Color.hex(Color.saturate!(color, 3))
"#008bec"

shade!(color, options \\ [])

@spec shade!(t(), list()) :: t()

Produces a shade of the given color. This is syntactic sugar for mix/4 with a target color of black.

Examples

iex>{:ok, color} = Color.new("hotpink");
iex> Color.hex(Color.shade!(color, ratio: 0.25))
"#dd5b9c"
iex> Color.hex(Color.shade!(color, ratio: 0.5))
"#b44a7f"
iex> Color.hex(Color.shade!(color, ratio: 0.75))
"#80355a"

temperature(color)

Estimates the temperature of a given color, though this only makes sense for colors from the temperature gradient.

Examples

iex> {:ok, color} = Color.new("#ff3300");
iex> Color.temperature(color)
1000
iex> {:ok, color} = Color.new("#ff8a13");
iex> Color.temperature(color)
2000
iex> {:ok, color} = Color.new("#ffe3cd");
iex> Color.temperature(color)
4985
iex> {:ok, color} = Color.new("#cbdbff");
iex> Color.temperature(color)
10049
iex> {:ok, color} = Color.new("#b3ccff");
iex> Color.temperature(color)
15005

tint!(color, options \\ [])

@spec tint!(t(), list()) :: t()

Produces a tint of the given color. This is syntactic sugar for mix/4 with a target color of white.

Examples

iex>{:ok, color} = Color.new("hotpink");
iex> Color.hex(Color.tint!(color, ratio: 0.25))
"#ff9dc9"
iex> Color.hex(Color.tint!(color, ratio: 0.5))
"#ffc3dd"
iex> Color.hex(Color.tint!(color, ratio: 0.75))
"#ffe3ee"