From 4c28aee273355e64821a7b2c34e8382b6d4dde1c Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 26 Apr 2026 12:34:44 +0100 Subject: [PATCH] Restore canonical pipeline docs --- README.md | 26 ++++++++++++++++++++++---- docs/implementation-plan.md | 4 ++-- docs/spec.md | 11 +++++++---- scripts/generate_readme_previews.py | 8 ++++---- 4 files changed, 35 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 9429f28..d257b5d 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md index e09fa03..6fc9db6 100644 --- a/docs/implementation-plan.md +++ b/docs/implementation-plan.md @@ -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 diff --git a/docs/spec.md b/docs/spec.md index 79c6871..0c8b59a 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -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 diff --git a/scripts/generate_readme_previews.py b/scripts/generate_readme_previews.py index 1c8d3be..536b96c 100644 --- a/scripts/generate_readme_previews.py +++ b/scripts/generate_readme_previews.py @@ -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.")