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 Modes for use with blend/2 or blend/3

Generic channel input for a color creation function.

Generic input for a color creation function.

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

t()

Defines the channels in an sRGB color.

Functions

Get the color opacity.

Set the color opacity.

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

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

Brighten a color.

Returns the CSS representation of an RGB color

Darken a color.

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

Returns the hexadecimal representation of an RGB color.

Converts a Color to a different colorspace.

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

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

Creates a new Color from the given channels and options.

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

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

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

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

Types

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

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

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

Generic channel input for a color creation function.

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

Generic input for a color creation function.

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

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

@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

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

Get the color opacity.

Examples

iex> {:ok, color} = Color.new("red");
iex> Color.alpha(color)
1.0
@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}
Link to this function

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

View Source
@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.

Link to this function

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

View Source
@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.

Link to this function

brighten!(color, amount \\ 1)

View Source
@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"
@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)"
Link to this function

darken!(color, amount \\ 1)

View Source
@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"
Link to this function

desaturate!(color, amount \\ 1)

View Source
@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"
@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"
Link to this function

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

View Source
@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}}
Link to this function

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

View Source
@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.

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

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

Link to this function

saturate!(color, amount \\ 1)

View Source
@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"
Link to this function

shade!(color, options \\ [])

View Source
@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"

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
Link to this function

tint!(color, options \\ [])

View Source
@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"