Restore canonical pipeline docs

This commit is contained in:
Meta Vens 2026-04-26 12:34:44 +01:00
commit 4c28aee273
4 changed files with 35 additions and 14 deletions

View file

@ -33,9 +33,14 @@ If you want to support the official hosted deployment and help us scale the poor
## Example
This closeup from the badge fixture is the whole pitch in miniature: same ugly source patch, same target grid, one output that finally quits bluffing.
This badge sheet is the whole pitch in one image: same source mess, same
target grid, same cheap Lanczos baseline, and one canonical `phase-field`
result that finally commits to the lattice.
![Repixelizer badge closeup](docs/readme-assets/guard-right-crop-source-final.png)
Each panel also carries the same sword-guard inset, so the nasty little taper
problem has nowhere to hide.
![Repixelizer example comparison](docs/readme-assets/badge-example-sheet.png)
## Current Status
@ -53,13 +58,13 @@ What exists now:
What changed recently:
- the old tray-based optimizer is gone
- `phase-field` is now the default optimizer path
- `phase-field` is now the canonical and only reconstruction path
- `source_structure` is reported alongside `source_fidelity`, because the old metric was happily calling better-looking images worse
- the tracked sword-tip blemish on the AI badge has its own focused fixture in `tests/fixtures/real/ai-badge-tip-focus.json`
Current read on the engine:
- `phase-field` is the release path. It currently produces the best-looking badge result in the repo, especially on internal linework, even though it still widens the tracked sword-tip stroke a bit too much.
- `phase-field` is the machine. It currently produces the best-looking badge result in the repo, especially on internal linework, even though it still widens the tracked sword-tip stroke a bit too much.
Current weak spots:
@ -164,6 +169,19 @@ Run the focused test suite with:
.venv\Scripts\python -m pytest -q
```
## Regenerating README Assets
The README images are generated from repo-tracked fixtures, not from random
artifacts left lying around:
```powershell
.venv\Scripts\python scripts\generate_readme_previews.py --vector-input tests\fixtures\real\ai-badge-vector.png --ai-input tests\fixtures\real\ai-badge-cleaned.png --out-sheet docs\readme-assets\badge-example-sheet.png --out-guard-crop docs\readme-assets\guard-right-crop-comparison.png --scratch-dir artifacts\readme-build --device auto
```
That regenerates the main README sheet, the standalone sword-guard closeup
strip, and scratch outputs under `artifacts/readme-build/` so you can inspect
the actual low-res results used to build the docs sample.
## Diagnostic Closeups
For docs or regression notes, you can generate reproducible source/output closeups from output-grid cell coordinates with:

View file

@ -15,7 +15,7 @@ intent.
Repixelizer now has one live reconstruction engine:
- `phase-field`: the default optimizer in `src/repixelizer/phase_field.py`
- `phase-field`: the canonical reconstruction engine in `src/repixelizer/phase_field.py`
The live pipeline is:
@ -24,7 +24,7 @@ The live pipeline is:
## What is working
- lattice size and phase inference are still shared and still CUDA-capable
- `phase-field` is now the main optimizer path and produces the best-looking badge result in the repo so far
- `phase-field` is the only canonical reconstruction path and produces the best-looking badge result in the repo so far
- compare mode, benchmark mode, diagnostics writing, and tuning all still work after the optimizer cutover
- the repo now reports both:
- `source_fidelity`: agreement with the inferred lattice portrait

View file

@ -52,14 +52,14 @@ Repixelizer treats this as lattice inference plus reconstruction rather than a r
## Product behavior
### Default mode
### Canonical mode
The default workflow should be fully automatic:
The canonical workflow should be fully automatic:
1. load the source image
2. infer lattice size and phase
3. analyze source structure
4. optimize a displacement field over the inferred lattice
4. run the `phase-field` reconstruction over the inferred lattice
5. project that result to a real pixel grid
6. clean up obvious discrete-grid artifacts
7. optionally quantize to a palette
@ -67,6 +67,9 @@ The default workflow should be fully automatic:
No manual masks or user-authored region hints are assumed in v1.
This is the only canonical reconstruction pipeline in the repo. Comparison mode
adds baselines, not alternate reconstruction engines.
### CLI shape
Primary commands:
@ -158,7 +161,7 @@ The project must ship comparison baselines:
- resize plus error diffusion
`compare` mode should run:
- the optimized solver
- the same `phase-field` pipeline
- both baselines
- metric collection
- a visual contact sheet

View file

@ -64,25 +64,25 @@ def _parse_args() -> argparse.Namespace:
"--engine-target-width",
type=int,
default=126,
help="Pinned target width for the engine-vs-engine badge comparison.",
help="Pinned target width for the canonical badge comparison.",
)
parser.add_argument(
"--engine-target-height",
type=int,
default=126,
help="Pinned target height for the engine-vs-engine badge comparison.",
help="Pinned target height for the canonical badge comparison.",
)
parser.add_argument(
"--engine-phase-x",
type=float,
default=0.0,
help="Pinned lattice phase X for the engine-vs-engine badge comparison.",
help="Pinned lattice phase X for the canonical badge comparison.",
)
parser.add_argument(
"--engine-phase-y",
type=float,
default=-0.2,
help="Pinned lattice phase Y for the engine-vs-engine badge comparison.",
help="Pinned lattice phase Y for the canonical badge comparison.",
)
parser.add_argument("--steps", type=int, default=48, help="Optimizer step budget for both runs.")
parser.add_argument("--device", default="cpu", choices=("auto", "cpu", "cuda"), help="Torch device for generation.")