Utils.Color module

For playing with colors.

Usage

local Color = require('__stdlib__/stdlib/utils/color')

Tables

color
anticolor
lightcolor

Color Constructors

new(any)	Create a new Color object.
load(color)	Loads the color metatmethods into table without any checking.
copy(color[, alpha])	Copies the color into a new Color.
white()	Returns a white Color.
black()	Returns a black color.
from_string(string_name[, alpha])	Returns a color from a string name if known.
from_params([r=0][, g=0][, b=0][, a=255])	Converts a color in the rgb format to a color table.
from_rgb
from_array(color[, alpha])	Converts a color in the array format to a color in the table format.
from_table(color[, alpha])	Converts a color in the dictionary format to a color in the Color format.
from_hex(color[, alpha=1])	Get a color table with a hexadecimal string.

Color Methods

normalize(color)	Normalizes a color between 0 and 1
alpha(color, alpha)	Set the alpha channel on a color
premul_alpha(color, alpha)	Premultiply alpha
add(lhs, rhs)	Add 2 colors together.
subtract(lhs, rhs)	Subtract 2 colors together.
multiply(lhs, rhs)	Multiply 2 colors together.
divide(lhs, rhs)	Add 2 colors together.
modulo(lhs, rhs)	Modulo of 2 colors.
unary(color)	Flip a color to white or black.

Color Functions

len(color)	Get the length of a color by adding all its values together
equals(lhs, rhs)	Are both colors equal.
less_than(lhs, rhs)	Is LHS less than RHS.
less_than_eq(lhs, rhs)	Is LHS less than or equal to RHS.
to_hex(color)	Return a hex formated string from a color.
to_array(color)	Return an array with 4 paramaters.
pack
to_params(color)	Return the color as 4 paramaters.
unpack
to_string(color)	Return the Color as a string.
is_complex(color)	Is this a correctly formatted color.
is_Color(color)	Is this a Color object.
is_color(color)	Is this a Color object or correctly formatted color table.

Tables

# color

defines.color

# anticolor

defines.anticolor

# lightcolor

defines.lightcolor

Color Constructors

# new(any)

Create a new Color object.

it can be passed, A Color, a string color name, an array, a list of float paramaters (RGB), a color dictionary, or hex

Parameters:

• any

Returns:

• (Color)

# load(color)

Loads the color metatmethods into table without any checking.

Parameters:

• color : (Color)

Returns:

• (color)

# copy(color[, alpha])

Copies the color into a new Color.

Parameters:

• color : (Color)
• alpha : (float) Change the alpha of the copied color (optional)

Returns:

• (Color)

# white()

Returns a white Color.

Returns:

• (Color)

# black()

Returns a black color.

Returns:

• (Color)

# from_string(string_name[, alpha])

Returns a color from a string name if known.

Returns white if color string is unknown

Parameters:

• string_name : (string)
• alpha : (float) (optional)

Returns:

• (Color)

# from_params([r=0][, g=0][, b=0][, a=255])

Converts a color in the rgb format to a color table.

Parameters:

• r : (float) 0-255 red (default: 0)
• g : (float) 0-255 green (default: 0)
• b : (float) 0-255 blue (default: 0)
• a : (float) 0-255 alpha (default: 255)

Returns:

• (Color)

# from_rgb

See also:

• Color.from_params

# from_array(color[, alpha])

Converts a color in the array format to a color in the table format.

Parameters:

• color : (array) the color to convert — { [1] = float, [2] = float, [3] = float, [4] = float }
• alpha : (float) (optional)

Returns:

• (Color) a converted color — { r = c_arr[1], g = c_arr[2], b = c_arr[3], a = c_arr[4] }

# from_table(color[, alpha])

Converts a color in the dictionary format to a color in the Color format.

Parameters:

• color : (table) the color to convert
• alpha : (float) (optional)

Returns:

• (Color)

# from_hex(color[, alpha=1])

Get a color table with a hexadecimal string.

Optionally provide the value for the alpha channel.

Parameters:

• color : (string) hexadecimal color string (#ffffff, not #fff)
• alpha : (float) the alpha value to set; such that 0 ⋜ value ⋜ 1 (default: 1)

Returns:

• (Color) a color table with RGB converted from Hex and with alpha

Color Methods

# normalize(color)

Normalizes a color between 0 and 1

Parameters:

• color : (Color)

Returns:

• Color

# alpha(color, alpha)

Set the alpha channel on a color

Parameters:

• color : (Color)
• alpha : (float)

Returns:

• (Color)

# premul_alpha(color, alpha)

Premultiply alpha

Parameters:

• color : (Color)
• alpha : (float)

Returns:

• Color

# add(lhs, rhs)

Add 2 colors together.

Parameters:

• lhs : (Color)
• rhs : (Color)

Returns:

• Color

# subtract(lhs, rhs)

Subtract 2 colors together.

Parameters:

• lhs : (Color)
• rhs : (Color)

Returns:

• Color

# multiply(lhs, rhs)

Multiply 2 colors together.

Parameters:

• lhs : (Color)
• rhs : (Color)

Returns:

• Color

# divide(lhs, rhs)

Add 2 colors together.

Parameters:

• lhs : (Color)
• rhs : (Color)

Returns:

• Color

# modulo(lhs, rhs)

Modulo of 2 colors.

Parameters:

• lhs : (Color)
• rhs : (Color)

Returns:

• (Color)

# unary(color)

Flip a color to white or black.

Parameters:

• color : (Color)

Returns:

• (Color)

Color Functions

# len(color)

Get the length of a color by adding all its values together

Parameters:

• color : (Color)

Returns:

• (number)

# equals(lhs, rhs)

Are both colors equal.

Parameters:

• lhs : (Color)
• rhs : (Color)

Returns:

• (boolean)

# less_than(lhs, rhs)

Is LHS less than RHS.

Parameters:

• lhs : (Color)
• rhs : (Color)

Returns:

• (boolean)

# less_than_eq(lhs, rhs)

Is LHS less than or equal to RHS.

Parameters:

• lhs : (Color)
• rhs : (Color)

Returns:

• (boolean)

# to_hex(color)

Return a hex formated string from a color.

Parameters:

• color : (Color)

Returns:

• (string)

# to_array(color)

Return an array with 4 paramaters.

Parameters:

• color : (Color)

Returns:

• (array)

# pack

See also:

• Color.to_array

# to_params(color)

Return the color as 4 paramaters.

Parameters:

• color : (Color)

Returns:

• float
• float
• float
• float

# unpack

See also:

• Color.to_params

# to_string(color)

Return the Color as a string.

Parameters:

• color : (Color)

Returns:

• (string)

# is_complex(color)

Is this a correctly formatted color.

Parameters:

• color : (Color)

Returns:

• (boolean)

# is_Color(color)

Is this a Color object.

Parameters:

• color : (Color)

Returns:

• (boolean)

# is_color(color)

Is this a Color object or correctly formatted color table.

Parameters:

• color : (Color)

Returns:

• (boolean)