ColourClass

ColourClass

colour.adjust_colour

Lightens or darkens a colour by a given amount.

The amount parameter defaults to 30. The lighten parameter defaults to true.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• amount (number?) - The amount to adjust the colour by.
• lighten (boolean?) - Whether to lighten (true) or darken (false) the colour.

Returns

table - The adjusted RGB colour as a table with three elements: red, green, and blue.

Examples

colour.adjust_colour({100,100,100},50, true)
-- {150, 150, 150}

colour.adjust_saturation

Adjusts the saturation of a colour by a given factor.

The factor parameter defaults to 0.5.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• factor (number?) - A factor between 0 (fully desaturated) and 1 (fully saturated).

Returns

table - The adjusted RGB colour as a table with three elements: red, green, and blue.

Examples

colour.adjust_saturation({35,50,100}, 0.5)
-- {48, 55, 80}

colour.analogous

Generates the analogous colours of a given colour. The analogous colours are generated by rotating the hue of the given colour by a given angle.

The angle parameter defaults to 30.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• angle (number?) - The angle to separate the analogous colours by.

Returns

table - A table of RGB colours that are analogous to the given colour.

Examples

colour.analogous({100,100,100})
-- { { 70, 100, 100 }, { 100, 100, 100 }, { 130, 100, 100 } }

colour.complementary

Returns the complementary colour of a given colour.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.

Returns

table - The complementary RGB colour as a table with three elements: red, green, and blue.

Examples

colour.complementary({150,150,150})
-- {105, 105, 105}

colour.contrast

Calculates the contrasting colour based on the luminance of a given colour.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.

Returns

table - The contrasting colour as a table with three elements: red, green, and blue.

Examples

colour.contrast({100,100,100})
-- {0, 0, 0}

colour.contrast_ratio

Calculates the contrast ratio between two colours.

Parameters

• rgb1 (table) - The first RGB colour as a table with three elements: red, green, and blue.
• rgb2 (table) - The second RGB colour as a table with three elements: red, green, and blue.

Returns

number - The contrast ratio between the two colours.

Examples

colour.contrast_ratio({100,100,100}, {0,0,0})
-- 12.0

colour.darken

Darkens a colour by a given amount.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• amount (number?) - The amount to darken the colour by.

Returns

table - The darkened RGB colour as a table with three elements: red, green, and blue.

Examples

colour.darken({100,100,100},50)
-- {50, 50, 50}

colour.grayscale

Converts a colour to its grayscale equivalent.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.

Returns

table - The grayscale RGB colour as a table with three elements: red, green, and blue.

Examples

colour.grayscale({35,50,100})
-- {62, 62, 62}

colour.hsl_to_rgb

Converts an HSL colour to an RGB colour.

Parameters

• hsl (table) - The HSL colour as a table with three elements: hue, saturation, and lightness.

Returns

table - The RGB colour as a table with three elements: red, green, and blue.

Examples

colour.hsl_to_rgb({180, 50, 50})
-- {127, 127, 127}

colour.interpolate

Interpolates between two RGB colours based on a step value. Functionally, it takes two colours and returns a third colour somewhere between the two colours, based on the step value. Generally used to fade between two colours. The step value is the current transition percentage as a whole number between the two colours, with 0 being the first colour and 100 being the second colour.

Available interpolation methods are:

• linear
• smooth (default)
• smoother
• ease_in
• ease_out

Parameters

• rgb1 (table) - The first RGB colour as a table with three elements: red, green, and blue.
• rgb2 (table) - The second RGB colour as a table with three elements: red, green, and blue.
• factor (number) - The step value between 0 and 1.
• method (string?) - The interpolation method to use.

Returns

table - The interpolated RGB colour as a table with three elements: red, green, and blue.

Examples

colour.interpolate({255, 0, 0}, {0, 0, 255}, 50)
-- {127, 0, 127}

colour.is_light

Determines if a colour is a light colour. The colour is considered light if the luminance is greater than 0.5.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.

Returns

boolean - True if the colour is light, false otherwise.

Examples

colour.is_light({255, 255, 255})
-- true

colour.lighten

Lightens a colour by a given amount.

The amount parameter defaults to 30.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• amount (number?) - The amount to lighten the colour by.

Returns

table - The lightened RGB colour as a table with three elements: red, green, and blue.

Examples

colour.lighten({100,100,100},50)
-- {150, 150, 150}

colour.lighten_or_darken

Lightens or darkens the first colour by a given amount based only a comparison with the second colour. If the colours are already contrasting, the original colour is returned.

The amount parameter defaults to 30.

Parameters

• rgb_colour (table) - The first RGB colour as a table with three elements: red, green, and blue.
• rgb_compare (table) - The second RGB colour as a table with three elements: red, green, and blue.
• amount (number?) - The amount to darken the colour by.

Returns

table - The darkened RGB colour as a table with three elements: red, green, and blue.

Examples

colour.lighten_or_darken({100,100,100}, {255,255,255}, 50)
-- {100, 100, 100}

colour.monochrome

Generates a series of monochromatic colours based on a given colour.

The steps parameter defaults to 5.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• steps (number?) - The number of variations to generate.

Returns

table - A table of RGB colours that are monochromatic variations of the given colour.

Examples

colour.monochrome({ 100, 100, 100 })
-- { { 100, 100, 100 }, { 100, 100, 100 }, { 100, 100, 100 } }

colour.random

Generates a random RGB colour.

Returns

table - A random RGB colour as a table with three elements: red, green, and blue.

Examples

colour.random()
-- { 123, 45, 67 }

colour.random_shade

Generates a random shade of a given colour within a range.

The range parameter defaults to 50.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• range (number?) - The range to adjust the colour by (e.g., 50 means +/- 50 for R, G, and B).

Returns

table - A random RGB colour that is a shade of the given colour.

Examples

colour.random_shade({100,100,100}, 50)
-- {150, 150, 150}

colour.rgb_to_hsl

Converts an RGB colour to an HSL colour.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.

Returns

table - The HSL colour as a table with three elements: hue, saturation, and lightness.

Examples

colour.rgb_to_hsl({255, 255, 255})
-- {0, 0, 100}

colour.split_complement

Generates the split complement colours of a given colour.

The angle parameter defaults to 30.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• angle (number?) - The angle to separate the split complement colours by.

Returns

table - A table of RGB colours that are the split complement of the given colour.

Examples

colour.split_complement({100,100,100})
-- { { 15, 204, 204 }, { 100, 204, 204 } }

colour.tetrad

Generates the tetrad colours of a given colour.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.

Returns

table - A table of RGB colours that are the tetrad of the given colour.

Examples

colour.tetrad({100,100,100})
-- { { 100, 100, 100 }, { 100, 100, 100 }, { 100, 100, 100 }, { 100, 100, 100 } }

colour.to_hex

Converts an RGB colour to a hex string. Whether the hex string includes a background colour depends on the include_background parameter. This parameter defaults to false.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.
• include_background (boolean?) - Whether to include a background colour.

Returns

string - The hex string.

Examples

colour.to_hex({255, 255, 255})
-- "#ffffff"

colour.triad

Generates the triad colours of a given colour. Does not return the original colour, but two returned colours that are considered tritones of the original colour.

Parameters

• rgb (table) - The RGB colour as a table with three elements: red, green, and blue.

Returns

table - A table of RGB colours that are the triad of the given colour.

Examples

colour.triad({100,100,100})
-- { { 15, 204, 204 }, { 100, 204, 204 } }