colorconv.h

Go to the documentation of this file.

#pragma once
 
#include <cstdint>
#include <algorithm>
#include "esphome/components/display/display_color_utils.h"
#include "esphome/core/color.h"
 
/* Utility for converting internal \a Color RGB representation to supported IC hardware color keys
 *
 * Focus in driver layer is on efficiency.
 * For optimum output quality on RGB inputs consider offline color keying/dithering.
 * Also see e.g. Image component.
 */
 
namespace esphome::epaper_spi {
 
// The Rec.601 luma helpers and the RGB565 mono lookup live in the shared display utilities, so other
// drivers (e.g. it8951 in its 1 bit per pixel mode) can use them too.
using display::color_to_mono;
using display::rec601_luma;
using display::Rgb565ToMono;
 
static constexpr uint8_t COLORCONV_GRAY_THRESHOLD = 50;
 
constexpr uint8_t color_to_gray4(Color color) {
  const uint8_t level = (uint8_t) ((rec601_luma(color) + 32u) >> 6);  // quantize 0..255 to 0..3, rounded
  return level > 3 ? 3 : level;
}
 
template<typename NATIVE_COLOR>
constexpr NATIVE_COLOR color_to_bwyr(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white, NATIVE_COLOR hw_yellow,
                                     NATIVE_COLOR hw_red) {
  // --- Step 1: Check for Grayscale (Black or White) ---
  // We define "grayscale" as a color where the min and max components
  // are close to each other.
 
  const auto [min_rgb, max_rgb] = std::minmax({color.r, color.g, color.b});
 
  if ((max_rgb - min_rgb) < COLORCONV_GRAY_THRESHOLD) {
    // It's a shade of gray. Map to BLACK or WHITE.
    return color_to_mono(color) ? hw_white : hw_black;
  }
 
  // --- Step 2: Check for Primary/Secondary Colors ---
  // If it's not gray, it's a color. We check which components are
  // "on" (over 128) vs "off". This divides the RGB cube into 8 corners.
  const bool r_on = (color.r > 128);
  const bool g_on = (color.g > 128);
  const bool b_on = (color.b > 128);
 
  if (r_on) {
    if (!b_on) {
      return g_on ? hw_yellow : hw_red;
    }
 
    // At least red+blue high (but not gray) -> White
    return hw_white;
  } else {
    return (b_on && g_on) ? hw_white : hw_black;
  }
}
 
template<typename NATIVE_COLOR>
constexpr NATIVE_COLOR color_to_bwr(Color color, NATIVE_COLOR hw_black, NATIVE_COLOR hw_white, NATIVE_COLOR hw_red) {
  return color_to_bwyr<NATIVE_COLOR>(color, hw_black, hw_white, /*hw_yellow=*/hw_white, hw_red);
}
 
template<typename NATIVE_COLOR>
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) {
  const auto [min_rgb, max_rgb] = std::minmax({color.r, color.g, color.b});
 
  if ((max_rgb - min_rgb) < COLORCONV_GRAY_THRESHOLD) {
    return color_to_mono(color) ? hw_white : hw_black;
  }
 
  const bool r_on = (color.r > 128);
  const bool g_on = (color.g > 128);
  const bool b_on = (color.b > 128);
 
  if (r_on && g_on && !b_on) {
    return hw_yellow;
  }
  if (r_on && !g_on && !b_on) {
    return hw_red;
  }
  if (!r_on && g_on && !b_on) {
    return hw_green;
  }
  if (!r_on && !g_on && b_on) {
    return hw_blue;
  }
  // Handle "impure" colors (cyan, magenta) by folding into the closest primary.
  if (!r_on && g_on && b_on) {
    return hw_green;  // cyan
  }
  if (r_on && !g_on) {
    return hw_red;  // magenta
  }
  if (r_on) {
    // All high (but not gray) -> white
    return hw_white;
  }
  // !r_on && !g_on && !b_on
  // All low (but not gray) -> black
  return hw_black;
}
 
template<typename NATIVE_COLOR>
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) {
  const auto [min_rgb, max_rgb] = std::minmax({color.r, color.g, color.b});
 
  if ((max_rgb - min_rgb) < COLORCONV_GRAY_THRESHOLD) {
    return color_to_mono(color) ? hw_white : hw_black;
  }
 
  const bool r_on = (color.r > 128);
  const bool g_on = (color.g > 128);
  const bool b_on = (color.b > 128);
 
  if (r_on && !b_on) {
    // Between red and yellow: split the gradient in three instead of two, since this panel has a
    // dedicated orange ink. Named orange (e.g. 0xFFA500) has g close to the midpoint, so the
    // plain g_on (>128) threshold used by color_to_bwyrgb can't tell it apart from yellow.
    if (color.g > 170) {
      return hw_yellow;
    }
    if (color.g > 85) {
      return hw_orange;
    }
    return hw_red;
  }
  if (!r_on && g_on && !b_on) {
    return hw_green;
  }
  if (!r_on && !g_on && b_on) {
    return hw_blue;
  }
  // Handle "impure" colors (cyan, magenta) by folding into the closest primary.
  if (!r_on && g_on && b_on) {
    return hw_green;  // cyan
  }
  if (r_on && !g_on) {
    return hw_red;  // magenta
  }
  if (r_on) {
    // All high (but not gray) -> white
    return hw_white;
  }
  // !r_on && !g_on && !b_on
  // All low (but not gray) -> black
  return hw_black;
}
 
}  // namespace esphome::epaper_spi