feat!: add auto tone compression as default

Analyzes image histogram (2nd/98th percentile) and remaps the actual
used luminance range to the display's capabilities, maximizing contrast.
Full-range images behave like strength=1.0; narrow-range images get
more contrast than fixed linear compression.

BREAKING CHANGE: tone_compression default changed from 1.0 to "auto".

Author: g4bri3lDev

packages/python/README.md

@@ -118,19 +118,22 @@ Note: The `serpentine` parameter only affects error diffusion algorithms (Floyd-
 
 E-paper displays can't reproduce the full luminance range of digital images. Pure white on a display is much darker than (255, 255, 255), and pure black is lighter than (0, 0, 0). Without tone compression, dithering tries to represent unreachable brightness levels, causing large accumulated errors and noisy output.
 
-Tone compression remaps image luminance from [0, 1] to the display's actual [black, white] range before dithering, producing smoother results. Based on [`fast_compress_dynamic_range()`](https://github.com/aitjcize/esp32-photoframe) from esp32-photoframe by aitjcize. It is enabled by default (`tone_compression=1.0`) and only applies when using measured `ColorPalette` instances:
+Tone compression remaps image luminance to the display's actual range before dithering. Based on [`fast_compress_dynamic_range()`](https://github.com/aitjcize/esp32-photoframe) from esp32-photoframe by aitjcize. It is enabled by default (`tone_compression="auto"`) and only applies when using measured `ColorPalette` instances:
+
+- **`"auto"`** (default): Analyzes the image histogram and remaps its actual luminance range to the display range. Maximizes contrast by stretching only the used range.
+- **`0.0-1.0`**: Fixed linear compression strength. `1.0` maps the full [0,1] range to the display range. `0.0` disables compression.
 
 ```python
 from epaper_dithering import dither_image, SPECTRA_7_3_6COLOR, DitherMode
 
-# Default: full tone compression (recommended)
+# Default: auto tone compression (recommended)
 result = dither_image(img, SPECTRA_7_3_6COLOR, DitherMode.FLOYD_STEINBERG)
 
+# Fixed linear compression
+result = dither_image(img, SPECTRA_7_3_6COLOR, DitherMode.FLOYD_STEINBERG, tone_compression=1.0)
+
 # Disable tone compression
 result = dither_image(img, SPECTRA_7_3_6COLOR, DitherMode.FLOYD_STEINBERG, tone_compression=0.0)
-
-# Partial compression (blend between original and compressed)
-result = dither_image(img, SPECTRA_7_3_6COLOR, DitherMode.FLOYD_STEINBERG, tone_compression=0.5)
 ```
 
 Note: `tone_compression` has no effect when using theoretical `ColorScheme` palettes (e.g., `ColorScheme.BWR`), since their black/white values already span the full range.

packages/python/src/epaper_dithering/algorithms.py

@@ -14,7 +14,7 @@
     precompute_palette_lab,
 )
 from .palettes import ColorPalette, ColorScheme
-from .tone_map import compress_dynamic_range
+from .tone_map import auto_compress_dynamic_range, compress_dynamic_range
 
 
 @dataclass(frozen=True)
@@ -140,7 +140,7 @@ def error_diffusion_dither(
     color_scheme: ColorScheme | ColorPalette,
     kernel: ErrorDiffusionKernel,
     serpentine: bool = True,
-    tone_compression: float = 1.0,
+    tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Generic error diffusion dithering with any kernel.
 
@@ -191,8 +191,11 @@ def error_diffusion_dither(
     palette_linear = srgb_to_linear(np.array(palette_srgb, dtype=np.float32))
 
     # Compress dynamic range for measured palettes
-    if isinstance(color_scheme, ColorPalette) and tone_compression > 0:
-        pixels_linear = compress_dynamic_range(pixels_linear, palette_linear, tone_compression)
+    if isinstance(color_scheme, ColorPalette) and tone_compression != 0:
+        if tone_compression == "auto":
+            pixels_linear = auto_compress_dynamic_range(pixels_linear, palette_linear)
+        else:
+            pixels_linear = compress_dynamic_range(pixels_linear, palette_linear, tone_compression)
 
     # Pre-compute palette LAB components for scalar per-pixel matching
     palette_L, palette_a, palette_b, palette_C = precompute_palette_lab(palette_linear)
@@ -271,7 +274,7 @@ def error_diffusion_dither(
 
 def floyd_steinberg_dither(
     image: Image.Image, color_scheme: ColorScheme | ColorPalette,
-    serpentine: bool = True, tone_compression: float = 1.0,
+    serpentine: bool = True, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply Floyd-Steinberg error diffusion dithering.
 
@@ -295,7 +298,7 @@ def floyd_steinberg_dither(
 
 def burkes_dither(
     image: Image.Image, color_scheme: ColorScheme | ColorPalette,
-    serpentine: bool = True, tone_compression: float = 1.0,
+    serpentine: bool = True, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply Burkes error diffusion dithering.
 
@@ -317,7 +320,7 @@ def burkes_dither(
 
 def sierra_dither(
     image: Image.Image, color_scheme: ColorScheme | ColorPalette,
-    serpentine: bool = True, tone_compression: float = 1.0,
+    serpentine: bool = True, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply Sierra error diffusion dithering.
 
@@ -342,7 +345,7 @@ def sierra_dither(
 
 def sierra_lite_dither(
     image: Image.Image, color_scheme: ColorScheme | ColorPalette,
-    serpentine: bool = True, tone_compression: float = 1.0,
+    serpentine: bool = True, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply Sierra Lite error diffusion dithering.
 
@@ -366,7 +369,7 @@ def sierra_lite_dither(
 
 def atkinson_dither(
     image: Image.Image, color_scheme: ColorScheme | ColorPalette,
-    serpentine: bool = True, tone_compression: float = 1.0,
+    serpentine: bool = True, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply Atkinson error diffusion dithering.
 
@@ -391,7 +394,7 @@ def atkinson_dither(
 
 def stucki_dither(
     image: Image.Image, color_scheme: ColorScheme | ColorPalette,
-    serpentine: bool = True, tone_compression: float = 1.0,
+    serpentine: bool = True, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply Stucki error diffusion dithering.
 
@@ -416,7 +419,7 @@ def stucki_dither(
 
 def jarvis_judice_ninke_dither(
     image: Image.Image, color_scheme: ColorScheme | ColorPalette,
-    serpentine: bool = True, tone_compression: float = 1.0,
+    serpentine: bool = True, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply Jarvis-Judice-Ninke error diffusion dithering.
 
@@ -445,7 +448,7 @@ def jarvis_judice_ninke_dither(
 
 
 def direct_palette_map(
-    image: Image.Image, color_scheme: ColorScheme | ColorPalette, tone_compression: float = 1.0,
+    image: Image.Image, color_scheme: ColorScheme | ColorPalette, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Map image colors directly to palette without dithering.
 
@@ -478,8 +481,11 @@ def direct_palette_map(
     palette_linear = srgb_to_linear(np.array(palette_srgb, dtype=np.float32))
 
     # Compress dynamic range for measured palettes
-    if isinstance(color_scheme, ColorPalette) and tone_compression > 0:
-        pixels_linear = compress_dynamic_range(pixels_linear, palette_linear, tone_compression)
+    if isinstance(color_scheme, ColorPalette) and tone_compression != 0:
+        if tone_compression == "auto":
+            pixels_linear = auto_compress_dynamic_range(pixels_linear, palette_linear)
+        else:
+            pixels_linear = compress_dynamic_range(pixels_linear, palette_linear, tone_compression)
 
     # Find closest palette color for ALL pixels at once using LAB
     output_pixels = find_closest_palette_color_lab(pixels_linear, palette_linear)
@@ -494,7 +500,7 @@ def direct_palette_map(
 
 
 def ordered_dither(
-    image: Image.Image, color_scheme: ColorScheme | ColorPalette, tone_compression: float = 1.0,
+    image: Image.Image, color_scheme: ColorScheme | ColorPalette, tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply ordered (Bayer) dithering with full vectorization.
 
@@ -545,8 +551,11 @@ def ordered_dither(
     palette_linear = srgb_to_linear(np.array(palette_srgb, dtype=np.float32))
 
     # Compress dynamic range for measured palettes
-    if isinstance(color_scheme, ColorPalette) and tone_compression > 0:
-        pixels_linear = compress_dynamic_range(pixels_linear, palette_linear, tone_compression)
+    if isinstance(color_scheme, ColorPalette) and tone_compression != 0:
+        if tone_compression == "auto":
+            pixels_linear = auto_compress_dynamic_range(pixels_linear, palette_linear)
+        else:
+            pixels_linear = compress_dynamic_range(pixels_linear, palette_linear, tone_compression)
 
     # ===== VECTORIZED ORDERED DITHERING =====
 

packages/python/src/epaper_dithering/core.py

@@ -18,7 +18,7 @@ def dither_image(
         color_scheme: ColorScheme | ColorPalette,
         mode: DitherMode = DitherMode.BURKES,
         serpentine: bool = True,
-        tone_compression: float = 1.0,
+        tone_compression: float | str = "auto",
 ) -> Image.Image:
     """Apply dithering to image for e-paper display.
 
@@ -29,9 +29,10 @@ def dither_image(
         serpentine: Use serpentine scanning for error diffusion (default: True).
             Alternates scan direction each row to reduce directional artifacts.
             Only applies to error diffusion algorithms, ignored for NONE and ORDERED.
-        tone_compression: Dynamic range compression strength (default: 1.0).
-            Remaps image luminance to the display's actual range before dithering.
-            0.0 = disabled, 1.0 = full compression. Only applies to measured ColorPalette.
+        tone_compression: Dynamic range compression (default: "auto").
+            "auto" = analyze image histogram and fit to display range.
+            0.0 = disabled, 0.0-1.0 = fixed linear compression strength.
+            Only applies to measured ColorPalette.
 
     Returns:
         Dithered palette image matching color scheme

packages/python/src/epaper_dithering/tone_map.py

@@ -84,3 +84,73 @@ def compress_dynamic_range(
         result[near_black, 2] = black_level
 
     return np.clip(result, 0.0, 1.0)
+
+
+def auto_compress_dynamic_range(
+    pixels_linear: np.ndarray,
+    palette_linear: np.ndarray,
+) -> np.ndarray:
+    """Auto-levels dynamic range compression fitted to display capabilities.
+
+    Analyzes the image's actual luminance distribution and remaps it to the
+    display's [black_Y, white_Y] range. Uses 2nd/98th percentiles to ignore
+    outliers, maximizing contrast within the display's capabilities.
+
+    For full-range images this is equivalent to compress_dynamic_range(..., 1.0).
+    For narrow-range images (e.g., all midtones) this preserves more contrast
+    by stretching the used range to fill the display range.
+
+    Args:
+        pixels_linear: Image in linear RGB, shape (H, W, 3), values in [0, 1].
+        palette_linear: Palette in linear RGB, shape (N, 3). Row 0 = black, row 1 = white.
+
+    Returns:
+        Modified pixels_linear array with compressed dynamic range.
+    """
+    # Display black/white luminance from measured palette
+    black_Y = (_LUM_R * palette_linear[0, 0]
+               + _LUM_G * palette_linear[0, 1]
+               + _LUM_B * palette_linear[0, 2])
+    white_Y = (_LUM_R * palette_linear[1, 0]
+               + _LUM_G * palette_linear[1, 1]
+               + _LUM_B * palette_linear[1, 2])
+    display_range = white_Y - black_Y
+
+    if display_range <= 0:
+        return pixels_linear
+
+    # Per-pixel luminance
+    Y = (_LUM_R * pixels_linear[:, :, 0]
+         + _LUM_G * pixels_linear[:, :, 1]
+         + _LUM_B * pixels_linear[:, :, 2])
+
+    # Image luminance percentiles (ignore 2% outliers at each end)
+    p_low = float(np.percentile(Y, 2))
+    p_high = float(np.percentile(Y, 98))
+    image_range = p_high - p_low
+
+    if image_range < 1e-6:
+        # Uniform image: fall back to standard linear compression
+        return compress_dynamic_range(pixels_linear, palette_linear, 1.0)
+
+    # Remap: [p_low, p_high] → [black_Y, white_Y]
+    normalized_Y = (Y - p_low) / image_range
+    target_Y = black_Y + normalized_Y * display_range
+
+    # Scale RGB proportionally to preserve hue
+    safe_Y = np.where(Y > 1e-6, Y, 1.0)
+    scale = np.where(Y > 1e-6, target_Y / safe_Y, 0.0)
+
+    result = pixels_linear.copy()
+    result[:, :, 0] *= scale
+    result[:, :, 1] *= scale
+    result[:, :, 2] *= scale
+
+    # Near-black pixels: set to display black luminance
+    near_black = Y <= 1e-6
+    if np.any(near_black):
+        result[near_black, 0] = black_Y
+        result[near_black, 1] = black_Y
+        result[near_black, 2] = black_Y
+
+    return np.clip(result, 0.0, 1.0)

packages/python/tests/test_color_matching.py

@@ -7,7 +7,7 @@
 from epaper_dithering import ColorScheme, DitherMode, dither_image
 from epaper_dithering.color_space import srgb_to_linear
 from epaper_dithering.color_space_lab import rgb_to_lab
-from epaper_dithering.tone_map import compress_dynamic_range
+from epaper_dithering.tone_map import auto_compress_dynamic_range, compress_dynamic_range
 
 
 class TestLABConversion:
@@ -177,3 +177,76 @@ def test_near_black_pixels_get_display_black(self):
                         + 0.0721750 * palette_linear[0, 2])
         # Near-black pixels should be set to approximately display black luminance
         assert result.mean() == pytest.approx(black_Y, abs=0.01)
+
+
+class TestAutoCompressDynamicRange:
+    """Unit tests for auto (percentile-based) dynamic range compression."""
+
+    def _make_palette_linear(self, black_srgb, white_srgb):
+        """Helper: convert black/white sRGB tuples to linear palette array."""
+        palette_srgb = np.array([black_srgb, white_srgb], dtype=np.float32)
+        return srgb_to_linear(palette_srgb)
+
+    def _luminance(self, pixels):
+        """Compute per-pixel luminance."""
+        return (0.2126729 * pixels[:, :, 0]
+                + 0.7151522 * pixels[:, :, 1]
+                + 0.0721750 * pixels[:, :, 2])
+
+    def test_full_range_gradient_matches_linear(self):
+        """Full-range gradient should produce similar result to linear compression."""
+        palette_linear = self._make_palette_linear([30, 30, 30], [200, 200, 200])
+        pixels = np.linspace(0.0, 1.0, 100).reshape(10, 10, 1).repeat(3, axis=2).astype(np.float32)
+
+        auto_result = auto_compress_dynamic_range(pixels.copy(), palette_linear)
+        linear_result = compress_dynamic_range(pixels.copy(), palette_linear, 1.0)
+
+        # For a full-range gradient, auto should be close to linear 1.0
+        np.testing.assert_allclose(auto_result, linear_result, atol=0.05)
+
+    def test_narrow_range_has_more_contrast(self):
+        """Narrow-range image should have more contrast with auto than fixed 1.0."""
+        palette_linear = self._make_palette_linear([30, 30, 30], [200, 200, 200])
+        # Image using only 30-70% of luminance range
+        pixels = np.linspace(0.3, 0.7, 100).reshape(10, 10, 1).repeat(3, axis=2).astype(np.float32)
+
+        auto_result = auto_compress_dynamic_range(pixels.copy(), palette_linear)
+        linear_result = compress_dynamic_range(pixels.copy(), palette_linear, 1.0)
+
+        # Auto should stretch to use more of the display range
+        auto_Y = self._luminance(auto_result)
+        linear_Y = self._luminance(linear_result)
+        auto_range = float(auto_Y.max() - auto_Y.min())
+        linear_range = float(linear_Y.max() - linear_Y.min())
+
+        assert auto_range > linear_range, \
+            f"Auto range {auto_range:.4f} should exceed linear range {linear_range:.4f}"
+
+    def test_uniform_image_falls_back(self):
+        """Uniform image should fall back to linear compression."""
+        palette_linear = self._make_palette_linear([30, 30, 30], [200, 200, 200])
+        pixels = np.full((5, 5, 3), 0.5, dtype=np.float32)
+
+        result = auto_compress_dynamic_range(pixels, palette_linear)
+        expected = compress_dynamic_range(pixels.copy(), palette_linear, 1.0)
+        np.testing.assert_allclose(result, expected, atol=1e-5)
+
+    def test_output_luminance_within_display_range(self):
+        """Auto-compressed output luminance should stay within display range (with tolerance)."""
+        palette_linear = self._make_palette_linear([30, 30, 30], [200, 200, 200])
+        black_Y = float(0.2126729 * palette_linear[0, 0]
+                        + 0.7151522 * palette_linear[0, 1]
+                        + 0.0721750 * palette_linear[0, 2])
+        white_Y = float(0.2126729 * palette_linear[1, 0]
+                        + 0.7151522 * palette_linear[1, 1]
+                        + 0.0721750 * palette_linear[1, 2])
+
+        pixels = np.linspace(0.0, 1.0, 100).reshape(10, 10, 1).repeat(3, axis=2).astype(np.float32)
+        result = auto_compress_dynamic_range(pixels, palette_linear)
+        result_Y = self._luminance(result)
+
+        # p2/p98 percentile-based: the 2% outliers at each end may exceed the range slightly
+        p2 = float(np.percentile(result_Y, 2))
+        p98 = float(np.percentile(result_Y, 98))
+        assert p2 >= black_Y - 0.01, f"p2 luminance {p2:.4f} should be near black_Y {black_Y:.4f}"
+        assert p98 <= white_Y + 0.01, f"p98 luminance {p98:.4f} should be near white_Y {white_Y:.4f}"

packages/python/tests/test_dithering.py

@@ -218,9 +218,23 @@ def test_tone_compression_skipped_for_color_scheme(self):
         # These should produce identical output since ColorScheme bypasses compression
         result_tc0 = dither_image(img, ColorScheme.MONO, DitherMode.NONE, tone_compression=0.0)
         result_tc1 = dither_image(img, ColorScheme.MONO, DitherMode.NONE, tone_compression=1.0)
+        result_auto = dither_image(img, ColorScheme.MONO, DitherMode.NONE, tone_compression="auto")
 
         assert np.array_equal(np.array(result_tc0), np.array(result_tc1)), \
             "Tone compression should have no effect on theoretical ColorScheme"
+        assert np.array_equal(np.array(result_tc0), np.array(result_auto)), \
+            "Auto tone compression should have no effect on theoretical ColorScheme"
+
+    @pytest.mark.parametrize("mode", list(DitherMode))
+    def test_auto_tone_compression_all_modes(self, mode):
+        """Auto tone compression (default) should produce valid output for all modes."""
+        from epaper_dithering import SPECTRA_7_3_6COLOR
+
+        img = Image.new("RGB", (10, 10), (128, 128, 128))
+        result = dither_image(img, SPECTRA_7_3_6COLOR, mode)
+
+        assert result.mode == 'P'
+        assert result.size == (10, 10)
 
     def test_tone_compression_changes_measured_output(self):
         """Tone compression should change the output for measured palettes."""