Add pre-region color quantization that enforces max_colors before region detection #103

New issue

Closed

opened 2026-07-29 16:41:53 +00:00 by Mark · 0 comments

Mark commented

2026-07-29 16:41:53 +00:00

Owner

Goal

Add a pre-digitize color quantization step that enforces max_colors before the region detector/classifier runs. Currently, max_colors is only honored by PhysicalOptimizer (stage 4), which means the region detector over-segments photographic inputs into 30+ color fragments even when max_colors=4 is requested.

Approach

Add a color quantizer module in src/raster/color_quantizer.py using k-means or median-cut quantization.
Integrate the quantizer into src/raster/raster_converter.py so it runs before region detection.
The quantizer must accept a max_colors parameter (default 8) and reduce the input image to that many colors.

Acceptance Criteria

New color_quantizer.py with a quantize(image, max_colors) function
RasterConverter calls quantizer before region detection
A photo with 1000+ unique colors is reduced to exactly max_colors colors before stitching
Existing tests still pass (no regression on geometric/graphic inputs)
No new lint errors

Files touched

src/raster/color_quantizer.py (new)
src/raster/raster_converter.py (modify)

Decomposed from Mark/easystitch#101

## Goal Add a pre-digitize color quantization step that enforces `max_colors` *before* the region detector/classifier runs. Currently, `max_colors` is only honored by `PhysicalOptimizer` (stage 4), which means the region detector over-segments photographic inputs into 30+ color fragments even when `max_colors=4` is requested. ## Approach 1. Add a color quantizer module in `src/raster/color_quantizer.py` using k-means or median-cut quantization. 2. Integrate the quantizer into `src/raster/raster_converter.py` so it runs before region detection. 3. The quantizer must accept a `max_colors` parameter (default 8) and reduce the input image to that many colors. ## Acceptance Criteria - [ ] New `color_quantizer.py` with a quantize(image, max_colors) function - [ ] RasterConverter calls quantizer before region detection - [ ] A photo with 1000+ unique colors is reduced to exactly `max_colors` colors before stitching - [ ] Existing tests still pass (no regression on geometric/graphic inputs) - [ ] No new lint errors ## Files touched - `src/raster/color_quantizer.py` (new) - `src/raster/raster_converter.py` (modify) --- _Decomposed from [Mark/easystitch#101](https://forgejo.tail018ac4.ts.net/Mark/easystitch/issues/101)_