ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
colorconv.h
Go to the documentation of this file.
1#pragma once
2
3#include <cstdint>
4#include <algorithm>
7
8/* Utility for converting internal \a Color RGB representation to supported IC hardware color keys
9 *
10 * Focus in driver layer is on efficiency.
11 * For optimum output quality on RGB inputs consider offline color keying/dithering.
12 * Also see e.g. Image component.
13 */
14
16
17// The Rec.601 luma helpers and the RGB565 mono lookup live in the shared display utilities, so other
18// drivers (e.g. it8951 in its 1 bit per pixel mode) can use them too.
22
24static constexpr uint8_t COLORCONV_GRAY_THRESHOLD = 50;
25
27enum class BwrColor : uint8_t {
31};
32
38constexpr uint8_t color_to_gray4(Color color) {
39 const uint8_t level = (uint8_t) ((rec601_luma(color) + 32u) >> 6); // quantize 0..255 to 0..3, rounded
40 return level > 3 ? 3 : level;
41}
42
53template<typename NATIVE_COLOR>
54constexpr NATIVE_COLOR color_to_bwyr(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white, NATIVE_COLOR hw_yellow,
55 NATIVE_COLOR hw_red) {
56 // --- Step 1: Check for Grayscale (Black or White) ---
57 // We define "grayscale" as a color where the min and max components
58 // are close to each other.
59
60 const auto [min_rgb, max_rgb] = std::minmax({color.r, color.g, color.b});
61
62 if ((max_rgb - min_rgb) < COLORCONV_GRAY_THRESHOLD) {
63 // It's a shade of gray. Map to BLACK or WHITE.
64 return color_to_mono(color) ? hw_white : hw_black;
65 }
66
67 // --- Step 2: Check for Primary/Secondary Colors ---
68 // If it's not gray, it's a color. We check which components are
69 // "on" (over 128) vs "off". This divides the RGB cube into 8 corners.
70 const bool r_on = (color.r > 128);
71 const bool g_on = (color.g > 128);
72 const bool b_on = (color.b > 128);
73
74 if (r_on) {
75 if (!b_on) {
76 return g_on ? hw_yellow : hw_red;
77 }
78
79 // At least red+blue high (but not gray) -> White
80 return hw_white;
81 } else {
82 return (b_on && g_on) ? hw_white : hw_black;
83 }
84}
85
98template<typename NATIVE_COLOR>
99constexpr NATIVE_COLOR color_to_bwr(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white, NATIVE_COLOR hw_red) {
100 const auto [min_rgb, max_rgb] = std::minmax({color.r, color.g, color.b});
101
102 if ((max_rgb - min_rgb) < COLORCONV_GRAY_THRESHOLD) {
103 return color_to_mono(color) ? hw_white : hw_black;
104 }
105
106 const int r = color.r;
107 const int g = color.g;
108 const int b = color.b;
109 const int d_black = r * r + g * g + b * b;
110 const int d_white = (255 - r) * (255 - r) + (255 - g) * (255 - g) + (255 - b) * (255 - b);
111 const int d_red = (255 - r) * (255 - r) + g * g + b * b;
112
113 if (d_red < d_white && d_red < d_black) {
114 return hw_red;
115 }
116 // Ties (e.g. yellow) go to white
117 return d_white <= d_black ? hw_white : hw_black;
118}
119
136template<typename NATIVE_COLOR>
137constexpr NATIVE_COLOR color_to_bwyrgb(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white,
138 NATIVE_COLOR hw_yellow, NATIVE_COLOR hw_red, NATIVE_COLOR hw_green,
139 NATIVE_COLOR hw_blue) {
140 const auto [min_rgb, max_rgb] = std::minmax({color.r, color.g, color.b});
141
142 if ((max_rgb - min_rgb) < COLORCONV_GRAY_THRESHOLD) {
143 return color_to_mono(color) ? hw_white : hw_black;
144 }
145
146 const bool r_on = (color.r > 128);
147 const bool g_on = (color.g > 128);
148 const bool b_on = (color.b > 128);
149
150 if (r_on && g_on && !b_on) {
151 return hw_yellow;
152 }
153 if (r_on && !g_on && !b_on) {
154 return hw_red;
155 }
156 if (!r_on && g_on && !b_on) {
157 return hw_green;
158 }
159 if (!r_on && !g_on && b_on) {
160 return hw_blue;
161 }
162 // Handle "impure" colors (cyan, magenta) by folding into the closest primary.
163 if (!r_on && g_on && b_on) {
164 return hw_green; // cyan
165 }
166 if (r_on && !g_on) {
167 return hw_red; // magenta
168 }
169 if (r_on) {
170 // All high (but not gray) -> white
171 return hw_white;
172 }
173 // !r_on && !g_on && !b_on
174 // All low (but not gray) -> black
175 return hw_black;
176}
177
194template<typename NATIVE_COLOR>
195constexpr NATIVE_COLOR color_to_bwyrgbo(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white,
196 NATIVE_COLOR hw_yellow, NATIVE_COLOR hw_red, NATIVE_COLOR hw_green,
197 NATIVE_COLOR hw_blue, NATIVE_COLOR hw_orange) {
198 const auto [min_rgb, max_rgb] = std::minmax({color.r, color.g, color.b});
199
200 if ((max_rgb - min_rgb) < COLORCONV_GRAY_THRESHOLD) {
201 return color_to_mono(color) ? hw_white : hw_black;
202 }
203
204 const bool r_on = (color.r > 128);
205 const bool g_on = (color.g > 128);
206 const bool b_on = (color.b > 128);
207
208 if (r_on && !b_on) {
209 // Between red and yellow: split the gradient in three instead of two, since this panel has a
210 // dedicated orange ink. Named orange (e.g. 0xFFA500) has g close to the midpoint, so the
211 // plain g_on (>128) threshold used by color_to_bwyrgb can't tell it apart from yellow.
212 if (color.g > 170) {
213 return hw_yellow;
214 }
215 if (color.g > 85) {
216 return hw_orange;
217 }
218 return hw_red;
219 }
220 if (!r_on && g_on && !b_on) {
221 return hw_green;
222 }
223 if (!r_on && !g_on && b_on) {
224 return hw_blue;
225 }
226 // Handle "impure" colors (cyan, magenta) by folding into the closest primary.
227 if (!r_on && g_on && b_on) {
228 return hw_green; // cyan
229 }
230 if (r_on && !g_on) {
231 return hw_red; // magenta
232 }
233 if (r_on) {
234 // All high (but not gray) -> white
235 return hw_white;
236 }
237 // !r_on && !g_on && !b_on
238 // All low (but not gray) -> black
239 return hw_black;
240}
241
242} // namespace esphome::epaper_spi
color_to_mono() of an RGB565 value as ColorUtil::to_color() reads it, from table lookups instead of a...
constexpr uint8_t rec601_luma(Color color)
Rec.601 luma of an RGB color, for optimum perceptual brightness.
constexpr uint8_t color_to_mono(Color color)
Map an RGB color to a single monochrome bit: 1 = white, 0 = black.
BwrColor
Native color keys for black/white/red panels, for use with color_to_bwr.
Definition colorconv.h:27
constexpr NATIVE_COLOR color_to_bwyrgbo(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white, NATIVE_COLOR hw_yellow, NATIVE_COLOR hw_red, NATIVE_COLOR hw_green, NATIVE_COLOR hw_blue, NATIVE_COLOR hw_orange)
Map RGB color to discrete BWYRGBO hex 7 color key.
Definition colorconv.h:195
constexpr uint8_t color_to_gray4(Color color)
Map RGB color to one of 4 discrete gray levels (2 bits per pixel)
Definition colorconv.h:38
constexpr NATIVE_COLOR color_to_bwr(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white, NATIVE_COLOR hw_red)
Map RGB color to discrete BWR (black/white/red) 3 color key.
Definition colorconv.h:99
constexpr NATIVE_COLOR color_to_bwyrgb(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white, NATIVE_COLOR hw_yellow, NATIVE_COLOR hw_red, NATIVE_COLOR hw_green, NATIVE_COLOR hw_blue)
Map RGB color to discrete BWYRGB hex 6 color key.
Definition colorconv.h:137
constexpr NATIVE_COLOR color_to_bwyr(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white, NATIVE_COLOR hw_yellow, NATIVE_COLOR hw_red)
Map RGB color to discrete BWYR hex 4 color key.
Definition colorconv.h:54
uint8_t g
Definition color.h:40
uint8_t b
Definition color.h:44
uint8_t r
Definition color.h:36