Keep README focused on phase-field

This commit is contained in:
Meta Vens 2026-04-26 12:46:47 +01:00
commit 32f6055ca4
4 changed files with 94 additions and 179 deletions

View file

@ -2,9 +2,15 @@
Repixelizer is a Python tool for images that are doing a pixel art impression instead of actually respecting the grid.
It is aimed at the annoying middle ground: sprites, emblems, and logos that look locally pixelated but fall apart the second you ask them to commit to one lattice like grown-ups.
It is aimed at the annoying middle ground: sprites, emblems, and logos that
look locally pixelated but fall apart the second you ask them to commit to one
lattice like grown-ups.
Instead of pretending this is a resize problem, Repixelizer treats it as lattice inference plus local structure preservation: infer the implied grid, choose real output cells, and snap them back onto a coherent pixel lattice while preserving the source's local adjacency patterns.
Instead of pretending this is a resize problem, Repixelizer treats it as
lattice inference plus `phase-field` reconstruction: infer the ruler, scout the
edges, give every output cell a tiny shove vector, nudge those shoves until the
cells settle into quieter paint while staying in order, then sample once and go
home.
## GUI First
@ -13,7 +19,7 @@ The web GUI is the main way to use this thing unless you enjoy raw flags for spo
It gives you:
- drag-and-drop input
- live pipeline feedback while lattice search, rerank, and solving run
- live phase-field feedback while lattice search, rerank, and solving run
- synchronized input/output inspection zoom for close comparison
- a built-in output editor for single-pixel cleanup with eyedropper and pencil tools
@ -33,39 +39,53 @@ If you want to support the official hosted deployment and help us scale the poor
## Example
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.
This badge sheet is the whole pitch in one image: same ugly fake-pixel source,
same target grid, same cheap Lanczos baseline, and one `phase-field` result
that finally commits to the lattice.
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)
## How It Works
Repixelizer does one thing:
`source image -> lattice inference -> edge scout -> fixed lattice centers ->
projected displacement-field optimization -> nearest source sample -> cleanup /
diagnostics`
In plainer language:
1. infer the target lattice size and phase
2. build one edge scout map over the source
3. nail down fixed lattice centers
4. run the `phase-field` solve by optimizing one `(dx, dy)` shove vector per
output cell
5. sample the source once from the final displaced cell positions
6. clean up the discrete result, optionally fit a palette, and write
diagnostics
That is the machine described in `docs/lean-optimizer-algorithm-map.md`.
Comparison mode just runs that same `phase-field` result next to the baselines.
## Current Status
This repo is past the "pile of hopeful heuristics" stage and into "real machine, still experimental."
This repo is past the "pile of hopeful heuristics" stage and into "real
machine, still experimental."
What exists now:
- a web GUI with drag-and-drop, live diagnostics, comparison tools, and pixel cleanup
- lattice inference with CUDA support
- a lean displacement-field optimizer in `src/repixelizer/phase_field.py`
- the `phase-field` reconstruction engine in `src/repixelizer/phase_field.py`
- automatic diagnostics, comparisons, and benchmark runs
- a tuning harness for offline parameter sweeps
- metrics that finally care about visible structure instead of only pleasing the lattice accountant
What changed recently:
- the old tray-based optimizer is gone
- `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 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:
- `phase-field` still needs better along-stroke versus across-stroke behavior near tapered contours
@ -175,7 +195,7 @@ 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
.venv\Scripts\python scripts\generate_readme_previews.py --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

Binary file not shown.

Before

Width:  |  Height:  |  Size: 395 KiB

After

Width:  |  Height:  |  Size: 197 KiB

Before After
Before After

View file

@ -67,8 +67,8 @@ The canonical 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.
This is the canonical machine in the repo. Comparison mode just runs that same
`phase-field` result next to the baselines.
### CLI shape
@ -157,12 +157,13 @@ This stage is intentionally heuristic and local in v1.
### 5. Baselines and comparison mode
The project must ship comparison baselines:
- Lanczos downscale
- naive resize
- resize plus error diffusion
`compare` mode should run:
- the same `phase-field` pipeline
- both baselines
- all baselines
- metric collection
- a visual contact sheet

View file

@ -9,7 +9,7 @@ import numpy as np
from PIL import Image, ImageDraw
from repixelizer.baselines import lanczos_resize_baseline
from repixelizer.io import load_rgba, nearest_resize, save_rgba
from repixelizer.io import load_rgba, save_rgba
from repixelizer.pipeline import run_pipeline
@ -20,14 +20,9 @@ class RenderedPanel:
def _parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description="Regenerate the README comparison sheets and closeups from repo fixtures.")
parser = argparse.ArgumentParser(description="Regenerate the README comparison sheet and closeups from repo fixtures.")
parser.add_argument(
"--vector-input",
default="tests/fixtures/real/ai-badge-vector.png",
help="High-resolution non-pixel badge source.",
)
parser.add_argument(
"--ai-input",
"--input",
default="tests/fixtures/real/ai-badge-cleaned.png",
help="Cleaned AI fake-pixel badge source.",
)
@ -46,12 +41,6 @@ def _parse_args() -> argparse.Namespace:
default="artifacts/readme-build",
help="Directory for intermediate low-res outputs and diagnostics.",
)
parser.add_argument(
"--vector-target-size",
type=int,
default=128,
help="Target size for the non-pixel source repixelization run.",
)
parser.add_argument(
"--guard-cell-bbox",
nargs=4,
@ -61,25 +50,25 @@ def _parse_args() -> argparse.Namespace:
help="Sword-guard crop bounds in output-grid cell coordinates for the AI row.",
)
parser.add_argument(
"--engine-target-width",
"--target-width",
type=int,
default=126,
help="Pinned target width for the canonical badge comparison.",
)
parser.add_argument(
"--engine-target-height",
"--target-height",
type=int,
default=126,
help="Pinned target height for the canonical badge comparison.",
)
parser.add_argument(
"--engine-phase-x",
"--phase-x",
type=float,
default=0.0,
help="Pinned lattice phase X for the canonical badge comparison.",
)
parser.add_argument(
"--engine-phase-y",
"--phase-y",
type=float,
default=-0.2,
help="Pinned lattice phase Y for the canonical badge comparison.",
@ -276,94 +265,40 @@ def main() -> None:
scratch_dir = Path(args.scratch_dir)
scratch_dir.mkdir(parents=True, exist_ok=True)
vector_input = Path(args.vector_input)
ai_input = Path(args.ai_input)
source_input = Path(args.input)
out_sheet = Path(args.out_sheet)
out_guard_crop = Path(args.out_guard_crop)
out_sheet.parent.mkdir(parents=True, exist_ok=True)
out_guard_crop.parent.mkdir(parents=True, exist_ok=True)
vector_phase_field_result = run_pipeline(
vector_input,
scratch_dir / "badge-vector-phase-field.png",
target_width=args.vector_target_size,
target_height=args.vector_target_size,
phase_x=0.0,
phase_y=0.0,
diagnostics_dir=scratch_dir / "vector-phase-field-diag",
steps=args.steps,
device=args.device,
enable_phase_rerank=False,
)
ai_result = run_pipeline(
ai_input,
scratch_dir / "badge-ai-repixelized.png",
diagnostics_dir=scratch_dir / "ai-diag",
steps=args.steps,
device=args.device,
)
phase_field_engine_result = run_pipeline(
ai_input,
phase_field_result = run_pipeline(
source_input,
scratch_dir / "badge-ai-phase-field-pinned.png",
target_width=args.engine_target_width,
target_height=args.engine_target_height,
phase_x=args.engine_phase_x,
phase_y=args.engine_phase_y,
diagnostics_dir=scratch_dir / "engine-phase-field-diag",
target_width=args.target_width,
target_height=args.target_height,
phase_x=args.phase_x,
phase_y=args.phase_y,
diagnostics_dir=scratch_dir / "phase-field-diag",
steps=args.steps,
device=args.device,
enable_phase_rerank=False,
)
vector_source = load_rgba(vector_input)
ai_source = load_rgba(ai_input)
vector_lanczos = lanczos_resize_baseline(vector_source, width=args.vector_target_size, height=args.vector_target_size)
ai_lanczos = lanczos_resize_baseline(
ai_source,
width=ai_result.inference.target_width,
height=ai_result.inference.target_height,
)
source_rgba = load_rgba(source_input)
lanczos = lanczos_resize_baseline(source_rgba, width=args.target_width, height=args.target_height)
save_rgba(scratch_dir / "badge-vector-lanczos.png", vector_lanczos)
save_rgba(scratch_dir / "badge-ai-lanczos.png", ai_lanczos)
save_rgba(scratch_dir / "badge-ai-lanczos.png", lanczos)
panel_width = 320
panel_height = 360
row_gap = 18
col_gap = 18
margin = 24
row_title_height = 22
vector_panels = [
panels = [
_render_panel(
"Source",
rgba=vector_source,
pixelated=False,
panel_width=panel_width,
panel_height=panel_height,
subtitle="Glossy badge art",
),
_render_panel(
"Lanczos",
rgba=vector_lanczos,
pixelated=True,
panel_width=panel_width,
panel_height=panel_height,
subtitle=f"{args.vector_target_size}x{args.vector_target_size} naive baseline",
),
_render_panel(
"Phase-field",
rgba=vector_phase_field_result.output_rgba,
pixelated=True,
panel_width=panel_width,
panel_height=panel_height,
subtitle=f"{args.vector_target_size}x{args.vector_target_size} pinned lattice",
),
]
ai_panels = [
_render_panel(
"Source",
rgba=ai_source,
rgba=source_rgba,
pixelated=False,
panel_width=panel_width,
panel_height=panel_height,
@ -371,104 +306,69 @@ def main() -> None:
),
_render_panel(
"Lanczos",
rgba=ai_lanczos,
rgba=lanczos,
pixelated=True,
panel_width=panel_width,
panel_height=panel_height,
subtitle=f"{args.engine_target_width}x{args.engine_target_height} naive baseline",
subtitle=f"{args.target_width}x{args.target_height} baseline",
),
_render_panel(
"Phase-field",
rgba=phase_field_engine_result.output_rgba,
rgba=phase_field_result.output_rgba,
pixelated=True,
panel_width=panel_width,
panel_height=panel_height,
subtitle=f"{args.engine_target_width}x{args.engine_target_height} pinned lattice",
subtitle=f"{args.target_width}x{args.target_height} pinned lattice",
),
]
guard_bbox = _cell_bbox_to_source_bbox(
tuple(args.guard_cell_bbox),
source_width=ai_source.shape[1],
source_height=ai_source.shape[0],
target_width=ai_result.inference.target_width,
target_height=ai_result.inference.target_height,
source_width=source_rgba.shape[1],
source_height=source_rgba.shape[0],
target_width=args.target_width,
target_height=args.target_height,
)
vector_guard_bbox = _cell_bbox_to_source_bbox(
tuple(args.guard_cell_bbox),
source_width=vector_source.shape[1],
source_height=vector_source.shape[0],
target_width=args.vector_target_size,
target_height=args.vector_target_size,
)
vector_guard_inset_bbox = _shrink_bbox_bottom_right(vector_guard_bbox, scale_x=0.5, scale_y=0.5)
vector_lanczos_preview = nearest_resize(vector_lanczos, width=vector_source.shape[1], height=vector_source.shape[0])
vector_phase_field_preview = nearest_resize(
vector_phase_field_result.output_rgba,
width=vector_source.shape[1],
height=vector_source.shape[0],
)
for panel in vector_panels:
guard_cell_inset_bbox = _shrink_bbox_bottom_right(tuple(args.guard_cell_bbox), scale_x=0.5, scale_y=0.5)
guard_inset_bbox = _shrink_bbox_bottom_right(guard_bbox, scale_x=0.5, scale_y=0.5)
for panel in panels:
_draw_source_bbox(
panel,
vector_guard_inset_bbox,
source_width=vector_source.shape[1],
source_height=vector_source.shape[0],
)
vector_crops = [
_crop_rgba(vector_source, vector_guard_inset_bbox),
_crop_rgba(vector_lanczos_preview, vector_guard_inset_bbox),
_crop_rgba(vector_phase_field_preview, vector_guard_inset_bbox),
]
for panel, crop in zip(vector_panels, vector_crops, strict=True):
_add_pip_inset(panel, _build_pip_inset(crop, width=139, height=103), margin_x=4, margin_y=4)
ai_guard_cell_inset_bbox = _shrink_bbox_bottom_right(tuple(args.guard_cell_bbox), scale_x=0.5, scale_y=0.5)
ai_guard_inset_bbox = _shrink_bbox_bottom_right(guard_bbox, scale_x=0.5, scale_y=0.5)
for panel in ai_panels:
_draw_source_bbox(
panel,
ai_guard_inset_bbox,
source_width=ai_source.shape[1],
source_height=ai_source.shape[0],
guard_inset_bbox,
source_width=source_rgba.shape[1],
source_height=source_rgba.shape[0],
)
guard_strip = _build_guard_strip(
_crop_rgba(ai_source, guard_bbox),
_crop_rgba(ai_lanczos, tuple(args.guard_cell_bbox)),
_crop_rgba(phase_field_engine_result.output_rgba, tuple(args.guard_cell_bbox)),
_crop_rgba(source_rgba, guard_bbox),
_crop_rgba(lanczos, tuple(args.guard_cell_bbox)),
_crop_rgba(phase_field_result.output_rgba, tuple(args.guard_cell_bbox)),
title=None,
)
guard_strip.save(out_guard_crop)
ai_crops = [
_crop_rgba(ai_source, ai_guard_inset_bbox),
_crop_rgba(ai_lanczos, ai_guard_cell_inset_bbox),
_crop_rgba(phase_field_engine_result.output_rgba, ai_guard_cell_inset_bbox),
inset_crops = [
_crop_rgba(source_rgba, guard_inset_bbox),
_crop_rgba(lanczos, guard_cell_inset_bbox),
_crop_rgba(phase_field_result.output_rgba, guard_cell_inset_bbox),
]
for panel, crop in zip(ai_panels, ai_crops, strict=True):
for panel, crop in zip(panels, inset_crops, strict=True):
_add_pip_inset(panel, _build_pip_inset(crop, width=139, height=103), margin_x=4, margin_y=4)
width = margin * 2 + panel_width * 3 + col_gap * 2
height = margin * 2 + row_title_height * 2 + panel_height * 2 + row_gap
height = margin * 2 + row_title_height + panel_height
canvas = Image.new("RGBA", (width, height), (11, 11, 13, 255))
draw = ImageDraw.Draw(canvas)
draw.text((margin, margin - 2), "Non-pixel source -> 128x128 pinned lattice", fill=(255, 255, 255, 255))
draw.text(
(margin, margin + row_title_height + panel_height + row_gap - 2),
f"AI fake pixel art -> {args.engine_target_width}x{args.engine_target_height} pinned lattice @ ({args.engine_phase_x:.1f}, {args.engine_phase_y:.1f})",
(margin, margin - 2),
f"AI fake pixel art -> {args.target_width}x{args.target_height} pinned lattice @ ({args.phase_x:.1f}, {args.phase_y:.1f})",
fill=(255, 255, 255, 255),
)
row1_y = margin + row_title_height
row2_y = row1_y + panel_height + row_gap + row_title_height
x = margin
for panel in vector_panels:
for panel in panels:
canvas.alpha_composite(panel.image, (x, row1_y))
x += panel_width + col_gap
x = margin
for panel in ai_panels:
canvas.alpha_composite(panel.image, (x, row2_y))
x += panel_width + col_gap
out_sheet.parent.mkdir(parents=True, exist_ok=True)
canvas.save(out_sheet)
@ -476,20 +376,14 @@ def main() -> None:
_save_summary(
scratch_dir / "readme-preview-summary.json",
{
"vector_input": str(vector_input),
"ai_input": str(ai_input),
"vector_target_size": args.vector_target_size,
"ai_inferred_width": ai_result.inference.target_width,
"ai_inferred_height": ai_result.inference.target_height,
"input": str(source_input),
"guard_cell_bbox": list(args.guard_cell_bbox),
"vector_guard_source_bbox": list(vector_guard_bbox),
"vector_guard_inset_source_bbox": list(vector_guard_inset_bbox),
"guard_source_bbox": list(guard_bbox),
"ai_guard_inset_source_bbox": list(ai_guard_inset_bbox),
"engine_target_width": args.engine_target_width,
"engine_target_height": args.engine_target_height,
"engine_phase_x": args.engine_phase_x,
"engine_phase_y": args.engine_phase_y,
"guard_inset_source_bbox": list(guard_inset_bbox),
"target_width": args.target_width,
"target_height": args.target_height,
"phase_x": args.phase_x,
"phase_y": args.phase_y,
"out_sheet": str(out_sheet),
"out_guard_crop": str(out_guard_crop),
"scratch_dir": str(scratch_dir),