299 lines
9.6 KiB
Lua
299 lines
9.6 KiB
Lua
-- colors.lua
|
||
-- Pure color math utilities for eye_spy.
|
||
-- No minetest API calls: safe to use from any context.
|
||
|
||
eye_spy.colors = {}
|
||
|
||
-- ---------------------------------------------------------------------------
|
||
-- Clamp
|
||
-- ---------------------------------------------------------------------------
|
||
|
||
--- Clamp v to [minv, maxv].
|
||
local function clamp(v, minv, maxv)
|
||
return math.max(minv, math.min(maxv, v))
|
||
end
|
||
|
||
-- ---------------------------------------------------------------------------
|
||
-- RGB packing / unpacking
|
||
-- ---------------------------------------------------------------------------
|
||
|
||
--- Split a packed 24-bit integer into its R, G, B byte components.
|
||
local function split_rgb(color)
|
||
local r = math.floor(color / 65536) % 256
|
||
local g = math.floor(color / 256) % 256
|
||
local b = color % 256
|
||
return r, g, b
|
||
end
|
||
|
||
--- Pack R, G, B byte components into a 24-bit integer.
|
||
local function join_rgb(r, g, b)
|
||
return (r * 65536) + (g * 256) + b
|
||
end
|
||
|
||
-- ---------------------------------------------------------------------------
|
||
-- Luminance helpers
|
||
-- ---------------------------------------------------------------------------
|
||
|
||
--- Linearise a single 0–255 channel value for WCAG relative-luminance maths.
|
||
local function channel_luminance(channel)
|
||
local c = channel / 255
|
||
|
||
if c <= 0.03928 then
|
||
return c / 12.92
|
||
end
|
||
|
||
return ((c + 0.055) / 1.055) ^ 2.4
|
||
end
|
||
|
||
--- WCAG 2.1 relative luminance of a packed 24-bit RGB integer.
|
||
local function color_luminance(color)
|
||
local r, g, b = split_rgb(color)
|
||
|
||
return (0.2126 * channel_luminance(r))
|
||
+ (0.7152 * channel_luminance(g))
|
||
+ (0.0722 * channel_luminance(b))
|
||
end
|
||
|
||
--- WCAG 2.1 contrast ratio between two packed 24-bit colours.
|
||
local function contrast_ratio(color_a, color_b)
|
||
local a_l = color_luminance(color_a)
|
||
local b_l = color_luminance(color_b)
|
||
|
||
return (math.max(a_l, b_l) + 0.05) / (math.min(a_l, b_l) + 0.05)
|
||
end
|
||
|
||
-- ---------------------------------------------------------------------------
|
||
-- Colour arithmetic
|
||
-- ---------------------------------------------------------------------------
|
||
|
||
--- Multiply every channel of a packed colour by factor and re-pack.
|
||
local function scale_color(color, factor)
|
||
local r, g, b = split_rgb(color)
|
||
r = clamp(math.floor(r * factor), 0, 255)
|
||
g = clamp(math.floor(g * factor), 0, 255)
|
||
b = clamp(math.floor(b * factor), 0, 255)
|
||
return join_rgb(r, g, b)
|
||
end
|
||
|
||
--- Linear interpolation between two packed colours.
|
||
-- t = 0 → color_a, t = 1 → color_b.
|
||
local function blend_color(color_a, color_b, t)
|
||
local factor = clamp(t or 0.5, 0, 1)
|
||
local ar, ag, ab = split_rgb(color_a)
|
||
local br, bg, bb = split_rgb(color_b)
|
||
|
||
return join_rgb(
|
||
math.floor((ar * (1 - factor)) + (br * factor) + 0.5),
|
||
math.floor((ag * (1 - factor)) + (bg * factor) + 0.5),
|
||
math.floor((ab * (1 - factor)) + (bb * factor) + 0.5)
|
||
)
|
||
end
|
||
|
||
-- ---------------------------------------------------------------------------
|
||
-- HSL conversion
|
||
-- ---------------------------------------------------------------------------
|
||
|
||
--- Convert R, G, B bytes to HSL (hue 0–360, saturation 0–1, lightness 0–1).
|
||
local function rgb_to_hsl(r, g, b)
|
||
local rn, gn, bn = r / 255, g / 255, b / 255
|
||
local max_c = math.max(rn, gn, bn)
|
||
local min_c = math.min(rn, gn, bn)
|
||
local l = (max_c + min_c) * 0.5
|
||
|
||
if max_c == min_c then
|
||
return 0, 0, l
|
||
end
|
||
|
||
local d = max_c - min_c
|
||
local s = l > 0.5 and d / (2 - max_c - min_c) or d / (max_c + min_c)
|
||
local h
|
||
|
||
if max_c == rn then
|
||
h = ((gn - bn) / d) % 6
|
||
elseif max_c == gn then
|
||
h = (bn - rn) / d + 2
|
||
else
|
||
h = (rn - gn) / d + 4
|
||
end
|
||
|
||
return (h / 6) * 360, s, l
|
||
end
|
||
|
||
-- Hoisted helper for hsl_to_rgb — avoids allocating a new closure per call.
|
||
-- Converts a hue position p/q at offset t (all normalised 0–1) to a channel value.
|
||
local function hue2rgb(p, q, t)
|
||
t = t % 1.0
|
||
if t < 1 / 6 then return p + (q - p) * 6 * t end
|
||
if t < 1 / 2 then return q end
|
||
if t < 2 / 3 then return p + (q - p) * (2 / 3 - t) * 6 end
|
||
return p
|
||
end
|
||
|
||
--- Convert HSL (hue 0–360, saturation 0–1, lightness 0–1) to R, G, B bytes.
|
||
local function hsl_to_rgb(h, s, l)
|
||
if s <= 0 then
|
||
local v = clamp(math.floor(l * 255 + 0.5), 0, 255)
|
||
return v, v, v
|
||
end
|
||
|
||
h = h / 360
|
||
local q = l < 0.5 and l * (1 + s) or l + s - l * s
|
||
local p = 2 * l - q
|
||
|
||
return clamp(math.floor(hue2rgb(p, q, h + 1 / 3) * 255 + 0.5), 0, 255),
|
||
clamp(math.floor(hue2rgb(p, q, h) * 255 + 0.5), 0, 255),
|
||
clamp(math.floor(hue2rgb(p, q, h - 1 / 3) * 255 + 0.5), 0, 255)
|
||
end
|
||
|
||
-- ---------------------------------------------------------------------------
|
||
-- Background luminance (BT.601 perceived brightness, not WCAG)
|
||
-- ---------------------------------------------------------------------------
|
||
|
||
--- Perceived brightness (BT.601) from R, G, B bytes (0–255 range).
|
||
-- Returns a value in [0, 255].
|
||
local function get_bg_luminance_rgb(r, g, b)
|
||
return (r * 0.299) + (g * 0.587) + (b * 0.114)
|
||
end
|
||
|
||
--- Perceived brightness (BT.601) from a 6-character lowercase hex string
|
||
-- such as "1a1a1b". Returns a value in [0, 255].
|
||
local function get_bg_luminance(rgb_hex)
|
||
local r = tonumber(rgb_hex:sub(1, 2), 16) or 26
|
||
local g = tonumber(rgb_hex:sub(3, 4), 16) or 26
|
||
local b = tonumber(rgb_hex:sub(5, 6), 16) or 27
|
||
return get_bg_luminance_rgb(r, g, b)
|
||
end
|
||
|
||
-- ---------------------------------------------------------------------------
|
||
-- Foreground selection helpers
|
||
-- ---------------------------------------------------------------------------
|
||
|
||
--- Return whichever of near-black or near-white has the higher contrast ratio
|
||
-- against bg_color (packed 24-bit integer).
|
||
local function best_monochrome_for_bg(bg_color)
|
||
local dark = 0x111111
|
||
local light = 0xF0F0F0
|
||
|
||
if contrast_ratio(light, bg_color) >= contrast_ratio(dark, bg_color) then
|
||
return light
|
||
end
|
||
|
||
return dark
|
||
end
|
||
|
||
--- Map a value in [0, 255] to a spectrum colour (red → green → blue → white).
|
||
local function spectrum_color(val)
|
||
local v = clamp(val or 255, 0, 255)
|
||
local r, g, b = 0, 0, 0
|
||
|
||
if v < 85 then
|
||
r = 255 - (v * 3)
|
||
g = v * 3
|
||
elseif v < 170 then
|
||
local x = v - 85
|
||
g = 255 - (x * 3)
|
||
b = x * 3
|
||
elseif v < 230 then
|
||
local x = v - 170
|
||
r = x * 4
|
||
b = 255 - (x * 4)
|
||
else
|
||
local x = math.floor((v - 230) * (255 / 25))
|
||
r, g, b = x, x, x
|
||
end
|
||
|
||
return join_rgb(r, g, b)
|
||
end
|
||
|
||
--- Darken color when the background (given as a hex string) is light,
|
||
-- so the colour remains legible.
|
||
-- Uses get_bg_luminance_rgb + split_rgb to avoid duplicating the BT.601 formula.
|
||
local function adapt_for_bg(color, bg_hex)
|
||
if get_bg_luminance(bg_hex) <= 140 then
|
||
return color
|
||
end
|
||
|
||
local luminance = get_bg_luminance_rgb(split_rgb(color))
|
||
|
||
if luminance > 130 then
|
||
return scale_color(color, 0.45)
|
||
end
|
||
|
||
return color
|
||
end
|
||
|
||
--- Iteratively blend color toward black or white until it reaches min_ratio
|
||
-- contrast against bg_color. Makes up to 5 nudge passes.
|
||
local function nudge_contrast(color, bg_color, min_ratio)
|
||
local candidate = color
|
||
local bg_l = color_luminance(bg_color)
|
||
|
||
for _ = 1, 5 do
|
||
if contrast_ratio(candidate, bg_color) >= (min_ratio or 4.5) then
|
||
return candidate
|
||
end
|
||
|
||
local fg_l = color_luminance(candidate)
|
||
|
||
if fg_l < bg_l then
|
||
candidate = blend_color(candidate, 0x000000, 0.32)
|
||
else
|
||
candidate = blend_color(candidate, 0xFFFFFF, 0.32)
|
||
end
|
||
end
|
||
|
||
return candidate
|
||
end
|
||
|
||
--- Adjust color to meet min_ratio contrast against bg_color while
|
||
-- preserving hue by blending toward white or black (whichever gives
|
||
-- the better contrast) in up to 8 steps.
|
||
local function tune_contrast_preserve_hue(color, bg_color, min_ratio)
|
||
local required_ratio = min_ratio or 4.0
|
||
local candidate = color
|
||
|
||
if contrast_ratio(candidate, bg_color) >= required_ratio then
|
||
return candidate
|
||
end
|
||
|
||
for step = 1, 8 do
|
||
if contrast_ratio(candidate, bg_color) >= required_ratio then
|
||
return candidate
|
||
end
|
||
|
||
local t = clamp(step * 0.09, 0, 0.70)
|
||
local lighter = blend_color(color, 0xFFFFFF, t)
|
||
local darker = blend_color(color, 0x000000, t)
|
||
|
||
if contrast_ratio(lighter, bg_color) >= contrast_ratio(darker, bg_color) then
|
||
candidate = lighter
|
||
else
|
||
candidate = darker
|
||
end
|
||
end
|
||
|
||
return candidate
|
||
end
|
||
|
||
-- ---------------------------------------------------------------------------
|
||
-- Public API
|
||
-- ---------------------------------------------------------------------------
|
||
|
||
eye_spy.colors.clamp = clamp
|
||
eye_spy.colors.split_rgb = split_rgb
|
||
eye_spy.colors.join_rgb = join_rgb
|
||
eye_spy.colors.channel_luminance = channel_luminance
|
||
eye_spy.colors.color_luminance = color_luminance
|
||
eye_spy.colors.contrast_ratio = contrast_ratio
|
||
eye_spy.colors.scale_color = scale_color
|
||
eye_spy.colors.blend_color = blend_color
|
||
eye_spy.colors.rgb_to_hsl = rgb_to_hsl
|
||
eye_spy.colors.hsl_to_rgb = hsl_to_rgb
|
||
eye_spy.colors.get_bg_luminance_rgb = get_bg_luminance_rgb
|
||
eye_spy.colors.get_bg_luminance = get_bg_luminance
|
||
eye_spy.colors.best_monochrome_for_bg = best_monochrome_for_bg
|
||
eye_spy.colors.spectrum_color = spectrum_color
|
||
eye_spy.colors.adapt_for_bg = adapt_for_bg
|
||
eye_spy.colors.nudge_contrast = nudge_contrast
|
||
eye_spy.colors.tune_contrast_preserve_hue = tune_contrast_preserve_hue
|