Color.Harmony (Color v0.4.0)

Color harmony helpers — rotations and named combinations on the hue circle.

All helpers operate in Oklch by default, which gives visually consistent rotations across the hue wheel. Pass :in to select a different cylindrical space (Color.LCHab, Color.LCHuv, Color.HSL, Color.HSV).

Every function accepts any color accepted by Color.new/1 and returns a list of Color.SRGB structs, ordered starting with the input color.

Summary

Functions

analogous(color, options \\ [])

Returns the three-color analogous set ([-30°, 0, +30°]).

complementary(color, options \\ [])

Returns the two-color complementary pair ([input, +180°]).

rotate_hue(color, degrees, options \\ [])

Rotates a color's hue by degrees.

split_complementary(color, options \\ [])

Returns the three-color split-complementary set ([0, 180 − spread, 180 + spread]).

tetradic(color, options \\ [])

Returns the four-color tetradic set ([0, +90°, +180°, +270°]).

triadic(color, options \\ [])

Returns the three-color triadic set ([0, +120°, +240°]).

Functions

analogous(color, options \\ [])

@spec analogous(
  Color.input(),
  keyword()
) :: {:ok, [Color.SRGB.t()]} | {:error, Exception.t()}

Returns the three-color analogous set ([-30°, 0, +30°]).

Arguments

color is any color accepted by Color.new/1.
options is the same as for rotate_hue/3, plus :spread (degrees, default 30).

Returns

{:ok, [%Color.SRGB{}, %Color.SRGB{}, %Color.SRGB{}]} ordered [anchor, anchor - spread, anchor + spread].

complementary(color, options \\ [])

@spec complementary(
  Color.input(),
  keyword()
) :: {:ok, [Color.SRGB.t()]} | {:error, Exception.t()}

Returns the two-color complementary pair ([input, +180°]).

Arguments

color is any color accepted by Color.new/1.
options is the same as for rotate_hue/3.

Returns

{:ok, [%Color.SRGB{}, %Color.SRGB{}]}.

rotate_hue(color, degrees, options \\ [])

@spec rotate_hue(Color.input(), number(), keyword()) ::
  {:ok, Color.SRGB.t()} | {:error, Exception.t()}

Rotates a color's hue by degrees.

Arguments

color is any color accepted by Color.new/1.
degrees is the rotation in degrees. Positive is counter-clockwise on the hue wheel.
options is a keyword list.

Options

:in is the cylindrical color space to rotate in. Defaults to Color.Oklch.

Returns

{:ok, %Color.SRGB{}}.

Examples

iex> {:ok, rotated} = Color.Harmony.rotate_hue("red", 120)
iex> hex = Color.SRGB.to_hex(rotated)
iex> String.starts_with?(hex, "#")
true

split_complementary(color, options \\ [])

@spec split_complementary(
  Color.input(),
  keyword()
) :: {:ok, [Color.SRGB.t()]} | {:error, Exception.t()}

Returns the three-color split-complementary set ([0, 180 − spread, 180 + spread]).

Arguments

color is any color accepted by Color.new/1.
options is the same as for rotate_hue/3, plus :spread (degrees, default 30).

Returns

{:ok, [%Color.SRGB{}, %Color.SRGB{}, %Color.SRGB{}]}.

tetradic(color, options \\ [])

@spec tetradic(
  Color.input(),
  keyword()
) :: {:ok, [Color.SRGB.t()]} | {:error, Exception.t()}

Returns the four-color tetradic set ([0, +90°, +180°, +270°]).

Arguments

color is any color accepted by Color.new/1.
options is the same as for rotate_hue/3.

Returns

{:ok, [%Color.SRGB{}, %Color.SRGB{}, %Color.SRGB{}, %Color.SRGB{}]}.

triadic(color, options \\ [])

@spec triadic(
  Color.input(),
  keyword()
) :: {:ok, [Color.SRGB.t()]} | {:error, Exception.t()}

Returns the three-color triadic set ([0, +120°, +240°]).

Arguments

color is any color accepted by Color.new/1.
options is the same as for rotate_hue/3.

Returns

{:ok, [%Color.SRGB{}, %Color.SRGB{}, %Color.SRGB{}]}.