# DESIGN — Fractal mosaic Python engine (Tower)

## Goal

Headless RST collage generator for the Tower mosaik inbox, adapted from Seth Benton’s Fractal-Mosaics (GPL).

## Pipeline

1. Load tile pool; cache mean RGB + HSV histogram (CBIR prefilter).
2. Resize master to profile `master_max`.
3. For each tile size (largest first), scan uncovered centers.
4. Rank tiles by histogram/mean distance (**selection only — no recolor**).
5. Estimate rotation/scale via log-polar phase correlation; snap to discrete rot/scale candidates.
6. Place with edge alpha blend if RMS and overlap pass thresholds.
7. Write PNG.

## Profiles

See `src/fractal_mosaic/profiles.py`: `wenig`, `mittel`, `dicht`.

## Coverage

Profiles target ~99% canvas coverage via denser RST passes + residual fill, while
keeping Fractal RST (rotation / scale / translate) — not a classic grid mosaic.
Pool images may be reused heavily when the library is small.

## Tile size (readability)

Piece sizes stay in a recognizable absolute range while `master_max` is high so
the canvas holds many pieces. Relative density ladder (largest tile / master):
wenig ≈1.75%, mittel ≈1.3%, dicht ≈1.0%. `max_placements` scales with
`(master_max / mean_tile)^2` so each profile can still hit ~99% coverage.
Scales never enlarge above 1.0.

## Non-goals (v1)

- Faithful bit-identical MATLAB port
- Color transfer / hue variants
- GPU acceleration