fractal-mosaics/README.md

# Fractal Mosaics (Tower fork)

Fork of [s-ben/Fractal-Mosaics](https://github.com/s-ben/Fractal-Mosaics) adapted for the Tower **mosaik** drop-inbox.

Upstream implements a rotation / scale / translation invariant photomosaic algorithm (log-polar registration + CBIR prefilter + large-first placement). Original code is MATLAB (GPL-3.0). This repository keeps the unpacked MATLAB sources under `reference/upstream-matlab/` and ships a **Python CLI** for headless use on Arch/Linux.

## Credit

- Original author: Seth Benton — https://github.com/s-ben/Fractal-Mosaics  
- Algorithm write-up: https://s-ben.github.io/Fractal-Mosaics/  
- License: GNU GPL v3 (see `LICENSE` and `reference/upstream-matlab/gpl_license.txt`)

## Python CLI (Tower)

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[cli]'

fractal-mosaic \
  --master path/to/target.jpg \
  --tiles path/to/tile_pool/ \
  --output out.png \
  --profile mittel
```

Profiles: `wenig` (fast, larger tiles), `mittel`, `dicht` (more placements, slower).

**Constraints for Tower v1:** geometric transforms + edge alpha only — **no tile recoloring**.

## Layout

| Path | Role |
|------|------|
| `reference/upstream-matlab/` | Unpacked `.m` files from upstream package |
| `reference/package/` | Original `FractalMosaics_package.tar.gz` |
| `src/fractal_mosaic/` | Python engine + CLI |
| docs site (`index.html`, …) | Upstream gh-pages documentation (preserved) |