Keep README focused on phase-field
This commit is contained in:
parent
4c28aee273
commit
32f6055ca4
4 changed files with 94 additions and 179 deletions
56
README.md
56
README.md
|
|
@ -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.
|
||||
|
||||

|
||||
|
||||
## 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 |
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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),
|
||||
|
|
|
|||
Loading…
Reference in a new issue