color
Utilities for working with color in Koto.
At the core of the library is the Color type, with various initializers
available.
For convenience, the color module itself is callable as a shorthand for some standard initializers:
|String| -> Color
Equivalent to calling color.named, or color.hex if no matching name is found.
|Number| -> Color
Equivalent to calling color.hex with a number.
|r: Number, g: Number, b: Number| -> Color
|r: Number, g: Number, b: Number, a: Number| -> Color
Equivalent to calling color.rgb.
Example:
color 'red'
#: Color(RGB, r: 1, g: 0, b: 0, a: 1)
color '#00ffff'
#: Color(RGB, r: 0, g: 1, b: 1, a: 1)
color 0xff00ff
#: Color(RGB, r: 1, g: 0, b: 1, a: 1)
color 0, 0.5, 1, 0.5
#: Color(RGB, r: 0, g: 0.5, b: 1, a: 0.5)
named
|name: String| -> Color?
Returns a color in the sRGB color space corresponding to one of the named colors listed in the SVG color keywords specification.
If no name is found then null will be returned.
Example
color.named 'yellow'
#: Color(RGB, r: 1, g: 1, b: 0, a: 1)
hex
|String| -> Color
Creates a color in the sRGB color space from the given hex triplet string, e.g. '#7fee80'.
The # prefix is optional, and the 3 digit shorthand version (e.g. '#7e8') can also be used.
If the string can't be parsed as a hex triplet then null will be returned.
|String| -> Color
Example
color.hex '#ff00ff'
#: Color(RGB, r: 1, g: 0, b: 1, a: 1)
color.hex 'f0f'
#: Color(RGB, r: 1, g: 0, b: 1, a: 1)
color.hex 0x00ff00
#: Color(RGB, r: 0, g: 1, b: 0, a: 1)
hsl
|h: Number, s: Number, l: Number| -> Color
|h: Number, s: Number, l: Number, a: Number| -> Color
Returns a color produced from hue, saturation, lightness, and optional alpha components.
The hue component is specified in degrees.
The saturation, lightness, and alpha components are specified as numbers between 0
and 1.
Example
color.hsl 180, 1, 0.25
#: Color(HSL, h: 180, s: 1, l: 0.25, a: 1)
hsv
|h: Number, s: Number, v: Number| -> Color
|h: Number, s: Number, v: Number, a: Number| -> Color
Returns a color produced from hue, saturation, value, and optional alpha components.
The hue component is specified in degrees.
The saturation, value, and alpha components are specified as numbers between 0 and 1.
Example
color.hsv 90, 0.5, 1
#: Color(HSV, h: 90, s: 0.5, v: 1, a: 1)
oklab
|l: Number, a: Number, b: Number| -> Color
|l: Number, a: Number, b: Number, alpha: Number| -> Color
Returns a color produced from lightness, a, b,
and optional alpha components, using the Oklab color space.
The lightness and alpha components are specified as numbers between 0 and 1.
The a (green/red) and b (blue/yellow) components are numbers with values typically between -0.4 and 0.4.
Example
color.oklab 0.5, 0.1, -0.2
#: Color(Oklab, l: 0.5, a: 0.1, b: -0.2, alpha: 1)
oklch
|l: Number, c: Number, h: Number| -> Color
|l: Number, c: Number, h: Number, a: Number| -> Color
Returns a color produced from lightness, chroma, hue, and optional alpha components, using the Oklab color space.
The lightness and alpha components are specified as numbers between 0 and 1.
The hue component is specified in degrees.
The chroma component is a number between 0 and a maximum that depends on the
hue and lightness components.
Example
color.oklch 0.6, 0.1, 180
#: Color(Oklch, l: 0.6, c: 0.1, h: 180, a: 1)
rgb
|r: Number, g: Number, b: Number| -> Color
Returns a color produced from red, green, blue, and optional alpha components, using the sRGB color space.
The color components are specified as numbers between 0 and 1.
Example
color.rgb 0.5, 0.1, 0.9
#: Color(RGB, r: 0.5, g: 0.1, b: 0.9, a: 1)
color.rgb 0.2, 0.4, 0.3, 0.5
#: Color(RGB, r: 0.2, g: 0.4, b: 0.3, a: 0.5)
Color
The color module's core color type.
The color may belong to various different color spaces, with the space's components available by name, indexing, or via iteration.
The color's alpha value is always present as the color's fourth component.
Example
r, g, b = color 'yellow'
r, g, b
#: (1.0, 1.0, 0.0)
h, s, v, a = color.hsv 90, 0.5, 0.25
h, s, v, a
#: (90.0, 0.5, 0.25, 1.0)
red = color 'red'
red.r, red.g, red.b
#: (1.0, 0.0, 0.0)
c = color.oklch 0.5, 0.1, 180
#: Color(Oklch, l: 0.5, c: 0.1, h: 180, a: 1)
c = 0.25 # Set the lightness component to 0.25
c = 0.1 # Set the chroma component to 0.1
print c
#: Color(Oklch, l: 0.25, c: 0.1, h: 180, a: 1)
Color.red | Color.r
Number
The color's red component.
An error is thrown if the color space doesn't have a red component.
Example
c = color 'red'
#: Color(RGB, r: 1, g: 0, b: 0, a: 1)
c.red
#: 1.0
c.red = 0.5
c.r
#: 0.5
Color.green | Color.g
Number
The color's green component.
An error is thrown if the color space doesn't have a green component.
Example
c = color 'lime'
#: Color(RGB, r: 0, g: 1, b: 0, a: 1)
c.green
#: 1.0
c.green = 0.5
c.g
#: 0.5
Color.blue | Color.b
Number
The color's blue component.
An error is thrown if the color space doesn't have a blue component.
Example
c = color 'blue'
#: Color(RGB, r: 0, g: 0, b: 1, a: 1)
c.blue
#: 1.0
c.blue = 0.5
c.b
#: 0.5
Color.hue | Color.h
Number
The color's hue component.
An error is thrown if the color space doesn't have a hue component.
Example
c = color.hsv 90, 0.5, 1.0
#: Color(HSV, h: 90, s: 0.5, v: 1, a: 1)
c.hue
#: 90.0
c.hue = 45.0
c.h
#: 45.0
Color.saturation | Color.s
Number
The color's saturation component.
An error is thrown if the color space doesn't have a saturation component.
Example
c = color.hsv 90, 0.5, 1.0
#: Color(HSV, h: 90, s: 0.5, v: 1, a: 1)
c.saturation
#: 0.5
c.saturation = 0.25
c.s
#: 0.25
Color.value | Color.v
Number
The color's value component.
An error is thrown if the color space doesn't have a value component.
Example
c = color.hsv 90, 0.5, 1.0
#: Color(HSV, h: 90, s: 0.5, v: 1, a: 1)
c.value
#: 1.0
c.value = 0.5
c.v
#: 0.5
Color.lightness | Color.l
Number
The color's lightness component.
An error is thrown if the color space doesn't have a lightness component.
Example
c = color.oklab 0.5, 0.2, -0.1
#: Color(Oklab, l: 0.5, a: 0.2, b: -0.1, alpha: 1)
c.lightness
#: 0.5
c.lightness = 0.25
c.l
#: 0.25
Color.a
Number
The color's a component.
An error is thrown if the color space doesn't have an a component.
Example
c = color.oklab 0.5, 0.25, -0.1
#: Color(Oklab, l: 0.5, a: 0.25, b: -0.1, alpha: 1)
c.a
#: 0.25
c.a = 0.5
c.a
#: 0.5
Color.b
Number
The color's b component.
An error is thrown if the color space doesn't have a b component.
Example
c = color.oklab 0.5, 0.25, -0.25
#: Color(Oklab, l: 0.5, a: 0.25, b: -0.25, alpha: 1)
c.b
#: -0.25
c.b = 0.25
c.b
#: 0.25
Color.chroma | Color.c
Number
The color's chroma component.
An error is thrown if the color space doesn't have a chroma component.
Example
c = color.oklch 0.6, 0.25, 180
#: Color(Oklch, l: 0.6, c: 0.25, h: 180, a: 1)
c.chroma
#: 0.25
c.chroma = 0.5
c.c
#: 0.5
Color.alpha
Number
The color's alpha component.
Example
c = color 'red'
c.alpha
#: 1.0
c.alpha = 0.25
c.alpha
#: 0.25
Color.mix
|a: Color, b: Color| -> Color
Returns a new color representing an even mix of the two input colors.
An error is thrown if the colors do not belong to the same color space.
|a: Color, b: Color, weight: Number| -> Color
Returns a new color representing a weighted mix of the two input colors.
The weight argument is a number between 0 and 1, with values closer to
0 producing results closer to the first color, and values closer to 1
producing results closer to the second color.
An error is thrown if the colors do not belong to the same color space.
Example
a, b = color, color
a.mix b
#: Color(RGB, r: 0.5, g: 0, b: 0.5, a: 1)
a.mix b, 0.25
#: Color(RGB, r: 0.75, g: 0, b: 0.25, a: 1)
Color.to_hsl
|Color| -> Color
Returns a new color with the input converted into the HSL color space.
Example
color.to_hsl
#: Color(HSL, h: 240, s: 1, l: 0.5, a: 1)
Color.to_hsv
|Color| -> Color
Returns a new color with the input converted into the HSV color space.
Example
color.to_hsv
#: Color(HSV, h: 240, s: 1, v: 1, a: 1)
Color.to_oklab
|Color| -> Color
Returns a new color with the input converted into the Oklab color space.
Example
l, a, b = color.to_oklab
allowed_error = 1e-3
assert_near l, 0.452, allowed_error
assert_near a, -0.033, allowed_error
assert_near b, -0.312, allowed_error
Color.to_oklch
|Color| -> Color
Returns a new color with the input converted into the Oklch color space.
Example
l, c, h = color.to_oklch
allowed_error = 1e-3
assert_near l, 0.452, allowed_error
assert_near c, 0.313, allowed_error
assert_near h, 264.052, allowed_error
Color.to_rgb
|Color| -> Color
Returns a new color with the input converted into the sRGB color space.
Example
l, c, h = color.to_oklch
allowed_error = 1e-3
assert_near l, 0.452, allowed_error
assert_near c, 0.313, allowed_error
assert_near h, 264.052, allowed_error