|====================================| | ArtiCOLOR Library Version 1.03 | | Written by: Michel van Osenbruggen | | CopyRight 2026 ArtiLED B.V. | |====================================| Latest change : 22-02-2026 |==========| | Overview | |==========| Library : colors.py Purpose : Color extraction and manipulation for LED lighting Used by : Ambilight mode scripts, video processing pipelines Devices : Hub, Node, Master |=========| | Imports | |=========| import numpy as np : NumPy for array math import colorsys : Python standard library for HSV conversion from collections import Counter : For most_common_color() |===============| | Input Formats | |===============| Image Array (img_arr) : NumPy array with shape (height, width, 3) — RGB image data : Used by Color Extraction functions Color Array (input_array) : NumPy array or Python list of RGB values : Shape (N, 3) for a list of colors, or any shape with last dimension 3 : Used by Color Adjustment functions : If a Python list is passed, a Python list is returned |============================| | Color Extraction Functions | |============================| All extraction functions take an image array (height, width, 3) and return (red, green, blue) as integers. -------------------------- | average_color(img_arr) | -------------------------- Description : Calculates the mean RGB value across all pixels Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 --------------------------- | dominant_color(img_arr) | --------------------------- Description : Finds the most frequently occurring unique RGB value Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 ---------------------------- | brightest_color(img_arr) | ---------------------------- Description : Finds the pixel with the highest mean brightness across R, G, B Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 -------------------------- | darkest_color(img_arr) | -------------------------- Description : Finds the pixel with the lowest mean brightness across R, G, B Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 ------------------------------ | most_common_color(img_arr) | ------------------------------ Description : Finds the single most common RGB tuple using Counter Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 --------------------------------- | most_saturated_color(img_arr) | --------------------------------- Description : Finds the pixel with the highest saturation (max - min) / (max + eps) Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 ---------------------------------- | least_saturated_color(img_arr) | ---------------------------------- Description : Finds the pixel with the lowest saturation (max - min) / (max + eps) Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 ---------------------------------- | most_contrasted_color(img_arr) | ---------------------------------- Description : Finds the pixel that deviates most from the mean brightness Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 ----------------------------------- | least_contrasted_color(img_arr) | ----------------------------------- Description : Finds the pixel closest to the mean brightness Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 ------------------------- | median_color(img_arr) | ------------------------- Description : Finds the median color by lexicographic sorting of all pixels Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 ----------------------- | mode_color(img_arr) | ----------------------- Description : Finds the statistical mode (most frequent unique value via np.unique) Parameters : img_arr — image array (height, width, 3) Return : (red, green, blue) — color as uint8 |========================| | Single Color Functions | |========================| ------------------------------- | gamma_correct(value, gamma) | ------------------------------- Description : Applies gamma correction to a single color value (0-255) Parameters : value — single channel value (0-255) : gamma — gamma exponent (clamped to minimum 0.1) Return : int — corrected value (0-255) Formula : 255 * (value / 255) ^ gamma |============================| | Color Adjustment Functions | |============================| All adjustment functions accept a NumPy array or Python list. If a list is passed, a list is returned. Values are clipped to [0, 255] and returned as uint8. ------------------------------------------------- | gamma(input_array, gamma_r, gamma_g, gamma_b) | ------------------------------------------------- Description : Applies per-channel gamma correction to an array of RGB colors Parameters : input_array — color array : gamma_r — gamma exponent for red channel : gamma_g — gamma exponent for green channel : gamma_b — gamma exponent for blue channel Formula : channel = 255 * (channel / 255) ^ gamma ------------------------------------------- | white_balance(input_array, white_point) | ------------------------------------------- Description : Adjusts white balance by scaling channels relative to a white point Parameters : input_array — color array : white_point — (R, G, B) reference white point Formula : channel = channel * (255 / white_point_channel) ------------------------------------------ | contrast(input_array, contrast_factor) | ------------------------------------------ Description : Adjusts contrast around the midpoint (128) Parameters : input_array — color array : contrast_factor — multiplier (1.0 = no change, >1 = more contrast, <1 = less) Formula : channel = 128 + factor * (channel - 128) ---------------------------------------------- | saturation(input_array, saturation_factor) | ---------------------------------------------- Description : Adjusts saturation via HSV conversion per pixel Parameters : input_array — color array : saturation_factor — multiplier (1.0 = no change, >1 = more saturated, 0 = grayscale) Method : RGB -> HSV, multiply S by factor, HSV -> RGB --------------------------------------------------------------------- | color_balance(input_array, red_factor, green_factor, blue_factor) | --------------------------------------------------------------------- Description : Scales individual R, G, B channels by independent factors Parameters : input_array — color array : red_factor — multiplier for red channel : green_factor — multiplier for green channel : blue_factor — multiplier for blue channel Formula : R = R * red_factor, G = G * green_factor, B = B * blue_factor -------------------------------------- | adjust_hue(input_array, hue_shift) | -------------------------------------- Description : Shifts the hue of all colors by a degree offset via HSV conversion Parameters : input_array — color array : hue_shift — hue rotation in degrees (-360 to 360, wraps around) Method : RGB -> HSV, add shift/360 to H (modulo 1.0), HSV -> RGB --------------------------------------------- | brightness(input_array, brightness_value) | --------------------------------------------- Description : Adds or subtracts a flat value to all RGB channels Parameters : input_array — color array : brightness_value — offset (-255 to 255, positive = brighter, negative = darker) Formula : channel = channel + brightness_value ----------------------------------------------- | color_temperature(input_array, temperature) | ----------------------------------------------- Description : Shifts color temperature warm or cool Parameters : input_array — color array : temperature — shift amount (-100 to 100) : * Positive = warmer (more red, less blue) : * Negative = cooler (more blue, less red) Formula : R = R * (1 + temperature / 100) : B = B * (1 - temperature / 100) ----------------------------------------------- | blend(input_array_1, input_array_2, factor) | ----------------------------------------------- Description : Linear interpolation (lerp) between two color arrays Parameters : input_array_1 — first color array : input_array_2 — second color array (same shape as first) : factor — blend position (0.0 = all array_1, 1.0 = all array_2) Formula : result = array_1 * (1 - factor) + array_2 * factor