Improve EPUB cover image quality with pre-scaling and Atkinson dithering (#116)

## Summary * **What is the goal of this PR?** Replace simple threshold-based grayscale quantization with ordered dithering using a 4x4 Bayer matrix. This eliminates color banding artifacts and produces smoother gradients on e-ink display. * **What changes are included?** - Add 4x4 Bayer dithering matrix for 16-level threshold patterns - Modify `grayscaleTo2Bit()` function to accept pixel coordinates and apply position-based dithering - Replace simple `grayscale >> 6` threshold with ordered dithering algorithm that produces smoother gradients ## Additional Context * Bayer matrix approach: The 4x4 Bayer matrix creates a repeating pattern that distributes quantization error spatially, effectively simulating 16 levels of gray using only 4 actual color levels (black, dark gray, light gray, white). * Cache invalidation: Existing cached `cover.bmp` files will need to be deleted to see the improved rendering, as the converter only runs when the cache is missing.
2025-12-28 08:38:14 +09:00
parent e3d0201365
commit f96b6ab29c
5 changed files with 727 additions and 68 deletions
--- a/lib/GfxRenderer/Bitmap.cpp
+++ b/lib/GfxRenderer/Bitmap.cpp
@@ -3,6 +3,126 @@
 #include <cstdlib>
 #include <cstring>

+// ============================================================================
+// IMAGE PROCESSING OPTIONS - Toggle these to test different configurations
+// ============================================================================
+// Note: For cover images, dithering is done in JpegToBmpConverter.cpp
+// This file handles BMP reading - use simple quantization to avoid double-dithering
+constexpr bool USE_FLOYD_STEINBERG = false;  // Disabled - dithering done at JPEG conversion
+constexpr bool USE_NOISE_DITHERING = false;  // Hash-based noise dithering
+// Brightness adjustments:
+constexpr bool USE_BRIGHTNESS = false;    // true: apply brightness/gamma adjustments
+constexpr int BRIGHTNESS_BOOST = 20;      // Brightness offset (0-50), only if USE_BRIGHTNESS=true
+constexpr bool GAMMA_CORRECTION = false;  // Gamma curve, only if USE_BRIGHTNESS=true
+// ============================================================================
+
+// Integer approximation of gamma correction (brightens midtones)
+static inline int applyGamma(int gray) {
+  if (!GAMMA_CORRECTION) return gray;
+  const int product = gray * 255;
+  int x = gray;
+  if (x > 0) {
+    x = (x + product / x) >> 1;
+    x = (x + product / x) >> 1;
+  }
+  return x > 255 ? 255 : x;
+}
+
+// Simple quantization without dithering - just divide into 4 levels
+static inline uint8_t quantizeSimple(int gray) {
+  if (USE_BRIGHTNESS) {
+    gray += BRIGHTNESS_BOOST;
+    if (gray > 255) gray = 255;
+    gray = applyGamma(gray);
+  }
+  return static_cast<uint8_t>(gray >> 6);
+}
+
+// Hash-based noise dithering - survives downsampling without moiré artifacts
+static inline uint8_t quantizeNoise(int gray, int x, int y) {
+  if (USE_BRIGHTNESS) {
+    gray += BRIGHTNESS_BOOST;
+    if (gray > 255) gray = 255;
+    gray = applyGamma(gray);
+  }
+
+  uint32_t hash = static_cast<uint32_t>(x) * 374761393u + static_cast<uint32_t>(y) * 668265263u;
+  hash = (hash ^ (hash >> 13)) * 1274126177u;
+  const int threshold = static_cast<int>(hash >> 24);
+
+  const int scaled = gray * 3;
+  if (scaled < 255) {
+    return (scaled + threshold >= 255) ? 1 : 0;
+  } else if (scaled < 510) {
+    return ((scaled - 255) + threshold >= 255) ? 2 : 1;
+  } else {
+    return ((scaled - 510) + threshold >= 255) ? 3 : 2;
+  }
+}
+
+// Main quantization function
+static inline uint8_t quantize(int gray, int x, int y) {
+  if (USE_NOISE_DITHERING) {
+    return quantizeNoise(gray, x, y);
+  } else {
+    return quantizeSimple(gray);
+  }
+}
+
+// Floyd-Steinberg quantization with error diffusion and serpentine scanning
+// Returns 2-bit value (0-3) and updates error buffers
+static inline uint8_t quantizeFloydSteinberg(int gray, int x, int width, int16_t* errorCurRow, int16_t* errorNextRow,
+                                             bool reverseDir) {
+  // Add accumulated error to this pixel
+  int adjusted = gray + errorCurRow[x + 1];
+
+  // Clamp to valid range
+  if (adjusted < 0) adjusted = 0;
+  if (adjusted > 255) adjusted = 255;
+
+  // Quantize to 4 levels (0, 85, 170, 255)
+  uint8_t quantized;
+  int quantizedValue;
+  if (adjusted < 43) {
+    quantized = 0;
+    quantizedValue = 0;
+  } else if (adjusted < 128) {
+    quantized = 1;
+    quantizedValue = 85;
+  } else if (adjusted < 213) {
+    quantized = 2;
+    quantizedValue = 170;
+  } else {
+    quantized = 3;
+    quantizedValue = 255;
+  }
+
+  // Calculate error
+  int error = adjusted - quantizedValue;
+
+  // Distribute error to neighbors (serpentine: direction-aware)
+  if (!reverseDir) {
+    // Left to right
+    errorCurRow[x + 2] += (error * 7) >> 4;   // Right: 7/16
+    errorNextRow[x] += (error * 3) >> 4;      // Bottom-left: 3/16
+    errorNextRow[x + 1] += (error * 5) >> 4;  // Bottom: 5/16
+    errorNextRow[x + 2] += (error) >> 4;      // Bottom-right: 1/16
+  } else {
+    // Right to left (mirrored)
+    errorCurRow[x] += (error * 7) >> 4;       // Left: 7/16
+    errorNextRow[x + 2] += (error * 3) >> 4;  // Bottom-right: 3/16
+    errorNextRow[x + 1] += (error * 5) >> 4;  // Bottom: 5/16
+    errorNextRow[x] += (error) >> 4;          // Bottom-left: 1/16
+  }
+
+  return quantized;
+}
+
+Bitmap::~Bitmap() {
+  delete[] errorCurRow;
+  delete[] errorNextRow;
+}
+
 uint16_t Bitmap::readLE16(File& f) {
  const int c0 = f.read();
  const int c1 = f.read();
@@ -46,6 +166,8 @@ const char* Bitmap::errorToString(BmpReaderError err) {
      return "UnsupportedCompression (expected BI_RGB or BI_BITFIELDS for 32bpp)";
    case BmpReaderError::BadDimensions:
      return "BadDimensions";
+    case BmpReaderError::ImageTooLarge:
+      return "ImageTooLarge (max 2048x3072)";
    case BmpReaderError::PaletteTooLarge:
      return "PaletteTooLarge";

@@ -99,6 +221,13 @@ BmpReaderError Bitmap::parseHeaders() {

  if (width <= 0 || height <= 0) return BmpReaderError::BadDimensions;

+  // Safety limits to prevent memory issues on ESP32
+  constexpr int MAX_IMAGE_WIDTH = 2048;
+  constexpr int MAX_IMAGE_HEIGHT = 3072;
+  if (width > MAX_IMAGE_WIDTH || height > MAX_IMAGE_HEIGHT) {
+    return BmpReaderError::ImageTooLarge;
+  }
+
  // Pre-calculate Row Bytes to avoid doing this every row
  rowBytes = (width * bpp + 31) / 32 * 4;

@@ -115,21 +244,56 @@ BmpReaderError Bitmap::parseHeaders() {
    return BmpReaderError::SeekPixelDataFailed;
  }

+  // Allocate Floyd-Steinberg error buffers if enabled
+  if (USE_FLOYD_STEINBERG) {
+    delete[] errorCurRow;
+    delete[] errorNextRow;
+    errorCurRow = new int16_t[width + 2]();  // +2 for boundary handling
+    errorNextRow = new int16_t[width + 2]();
+    lastRowY = -1;
+  }
+
  return BmpReaderError::Ok;
 }

 // packed 2bpp output, 0 = black, 1 = dark gray, 2 = light gray, 3 = white
-BmpReaderError Bitmap::readRow(uint8_t* data, uint8_t* rowBuffer) const {
+BmpReaderError Bitmap::readRow(uint8_t* data, uint8_t* rowBuffer, int rowY) const {
  // Note: rowBuffer should be pre-allocated by the caller to size 'rowBytes'
  if (file.read(rowBuffer, rowBytes) != rowBytes) return BmpReaderError::ShortReadRow;

+  // Handle Floyd-Steinberg error buffer progression
+  const bool useFS = USE_FLOYD_STEINBERG && errorCurRow && errorNextRow;
+  if (useFS) {
+    // Check if we need to advance to next row (or reset if jumping)
+    if (rowY != lastRowY + 1 && rowY != 0) {
+      // Non-sequential row access - reset error buffers
+      memset(errorCurRow, 0, (width + 2) * sizeof(int16_t));
+      memset(errorNextRow, 0, (width + 2) * sizeof(int16_t));
+    } else if (rowY > 0) {
+      // Sequential access - swap buffers
+      int16_t* temp = errorCurRow;
+      errorCurRow = errorNextRow;
+      errorNextRow = temp;
+      memset(errorNextRow, 0, (width + 2) * sizeof(int16_t));
+    }
+    lastRowY = rowY;
+  }
+
  uint8_t* outPtr = data;
  uint8_t currentOutByte = 0;
  int bitShift = 6;
+  int currentX = 0;

  // Helper lambda to pack 2bpp color into the output stream
  auto packPixel = [&](const uint8_t lum) {
-    uint8_t color = (lum >> 6);  // Simple 2-bit reduction: 0-255 -> 0-3
+    uint8_t color;
+    if (useFS) {
+      // Floyd-Steinberg error diffusion
+      color = quantizeFloydSteinberg(lum, currentX, width, errorCurRow, errorNextRow, false);
+    } else {
+      // Simple quantization or noise dithering
+      color = quantize(lum, currentX, rowY);
+    }
    currentOutByte |= (color << bitShift);
    if (bitShift == 0) {
      *outPtr++ = currentOutByte;
@@ -138,6 +302,7 @@ BmpReaderError Bitmap::readRow(uint8_t* data, uint8_t* rowBuffer) const {
    } else {
      bitShift -= 2;
    }
+    currentX++;
  };

  uint8_t lum;
@@ -196,5 +361,12 @@ BmpReaderError Bitmap::rewindToData() const {
    return BmpReaderError::SeekPixelDataFailed;
  }

+  // Reset Floyd-Steinberg error buffers when rewinding
+  if (USE_FLOYD_STEINBERG && errorCurRow && errorNextRow) {
+    memset(errorCurRow, 0, (width + 2) * sizeof(int16_t));
+    memset(errorNextRow, 0, (width + 2) * sizeof(int16_t));
+    lastRowY = -1;
+  }
+
  return BmpReaderError::Ok;
 }
--- a/lib/GfxRenderer/Bitmap.h
+++ b/lib/GfxRenderer/Bitmap.h
@@ -15,6 +15,7 @@ enum class BmpReaderError : uint8_t {
  UnsupportedCompression,

  BadDimensions,
+  ImageTooLarge,
  PaletteTooLarge,

  SeekPixelDataFailed,
@@ -28,8 +29,9 @@ class Bitmap {
  static const char* errorToString(BmpReaderError err);

  explicit Bitmap(File& file) : file(file) {}
+  ~Bitmap();
  BmpReaderError parseHeaders();
-  BmpReaderError readRow(uint8_t* data, uint8_t* rowBuffer) const;
+  BmpReaderError readRow(uint8_t* data, uint8_t* rowBuffer, int rowY) const;
  BmpReaderError rewindToData() const;
  int getWidth() const { return width; }
  int getHeight() const { return height; }
@@ -49,4 +51,9 @@ class Bitmap {
  uint16_t bpp = 0;
  int rowBytes = 0;
  uint8_t paletteLum[256] = {};
+
+  // Floyd-Steinberg dithering state (mutable for const methods)
+  mutable int16_t* errorCurRow = nullptr;
+  mutable int16_t* errorNextRow = nullptr;
+  mutable int lastRowY = -1;  // Track row progression for error propagation
 };
--- a/lib/GfxRenderer/GfxRenderer.cpp
+++ b/lib/GfxRenderer/GfxRenderer.cpp
@@ -132,7 +132,9 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
    isScaled = true;
  }

-  const uint8_t outputRowSize = (bitmap.getWidth() + 3) / 4;
+  // Calculate output row size (2 bits per pixel, packed into bytes)
+  // IMPORTANT: Use int, not uint8_t, to avoid overflow for images > 1020 pixels wide
+  const int outputRowSize = (bitmap.getWidth() + 3) / 4;
  auto* outputRow = static_cast<uint8_t*>(malloc(outputRowSize));
  auto* rowBytes = static_cast<uint8_t*>(malloc(bitmap.getRowBytes()));

@@ -154,7 +156,7 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
      break;
    }

-    if (bitmap.readRow(outputRow, rowBytes) != BmpReaderError::Ok) {
+    if (bitmap.readRow(outputRow, rowBytes, bmpY) != BmpReaderError::Ok) {
      Serial.printf("[%lu] [GFX] Failed to read row %d from bitmap\n", millis(), bmpY);
      free(outputRow);
      free(rowBytes);