2026-04-21 16:10:55 +01:00
# Repixelizer
2026-04-26 05:45:33 +01:00
Repixelizer is a Python tool for images that are doing a pixel art impression instead of actually respecting the grid.
2026-04-21 16:10:55 +01:00
2026-04-26 12:46:47 +01:00
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.
2026-04-21 22:34:35 +01:00
2026-04-29 11:43:17 +01:00
Repixelizer treats fake pixel art as lattice inference plus `phase-field`
reconstruction: infer the ruler, preview the edges, let every output cell
search a tiny local window for quieter paint, relax the whole sheet back into a
coherent lattice, then sample once and go home.
2026-04-21 22:34:35 +01:00
2026-06-03 02:59:32 +01:00
## Eve Surface First
2026-04-21 22:34:35 +01:00
2026-06-03 02:59:32 +01:00
The web GUI is the current browser lowering for Repixelizer. The canonical
presentation target is an Eve surface: the same upload, comparison, cleanup,
queue, and artifact flow should lower to browser, Kotlin Android Eve, native
Eve, TUI, or future room clients without becoming five apps in a coat.
2026-04-21 22:34:35 +01:00
2026-06-03 02:59:32 +01:00
The current browser lowering gives you:
2026-04-21 22:34:35 +01:00
2026-04-26 05:45:33 +01:00
- drag-and-drop input
2026-04-29 11:24:31 +01:00
- live phase-field feedback while autocorr inference, rerank, and solving run
2026-04-26 05:45:33 +01:00
- synchronized input/output inspection zoom for close comparison
- a built-in output editor for single-pixel cleanup with eyedropper and pencil tools
2026-04-21 22:34:35 +01:00
2026-04-26 05:45:33 +01:00
Run it from the repo checkout:
```powershell
.\scripts\run_gui.ps1
```
If you want to bypass the PowerShell wrapper and call Python directly:
```powershell
.\.venv\Scripts\python scripts\run_gui.py
```
If you want to support the official hosted deployment and help us scale the poor little server when people start leaning on it, join the [GameCult Patreon ](https://www.patreon.com/GameCult ). At `$10` per subscriber, the math gets a lot less tragic.
## Example
2026-04-26 13:57:09 +01:00
This sheet carries two cases: the ugly fake-pixel badge and a dense
higher-resolution landscape. The badge row shows the core salvage story. The
2026-04-29 11:34:24 +01:00
landscape row shows how the same automatic path handles a much larger source.
2026-04-26 05:45:33 +01:00
2026-04-26 13:57:09 +01:00
Each row carries its own inset, so the tiny details have nowhere to hide.
2026-04-26 12:34:44 +01:00

2026-04-24 01:10:40 +01:00
2026-04-26 12:46:47 +01:00
## How It Works
Repixelizer does one thing:
2026-04-29 11:24:31 +01:00
`source image -> lattice inference -> diagnostic edge preview -> fixed lattice centers ->
hierarchical flatness signal -> explicit local search + lattice relaxation ->
nearest source sample -> cleanup / diagnostics`
2026-04-26 12:46:47 +01:00
In plainer language:
2026-04-28 14:55:35 +01:00
1. infer the target lattice size
2026-04-29 11:24:31 +01:00
2. build one diagnostic edge preview over the source
2026-04-26 12:46:47 +01:00
3. nail down fixed lattice centers
2026-04-29 11:24:31 +01:00
4. run the `phase-field` solve by letting each cell search a tiny local window,
move toward the flattest nearby source position, and relax back into a
coherent lattice
5. sample the source once from the final cell positions
2026-04-26 12:46:47 +01:00
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.
2026-06-02 18:57:25 +01:00
For hosted service state, queue visibility, and the future CultCache/CultMesh/Eve
2026-06-03 03:22:39 +01:00
operator surface, see `docs/verse-service-contract.md` . The read-only Odin
advertisement fixture/export is documented in
`docs/repixelizer-witness-contract.md` .
2026-06-02 18:57:25 +01:00
2026-04-21 21:56:25 +01:00
## Current Status
2026-04-21 16:10:55 +01:00
2026-04-26 12:46:47 +01:00
This repo is past the "pile of hopeful heuristics" stage and into "real
machine, still experimental."
2026-04-24 00:03:05 +01:00
What exists now:
2026-04-26 05:45:33 +01:00
- a web GUI with drag-and-drop, live diagnostics, comparison tools, and pixel cleanup
2026-04-24 00:03:05 +01:00
- lattice inference with CUDA support
2026-04-26 12:46:47 +01:00
- the `phase-field` reconstruction engine in `src/repixelizer/phase_field.py`
2026-04-24 00:03:05 +01:00
- automatic diagnostics, comparisons, and benchmark runs
2026-05-31 00:41:18 +01:00
- spritesheet CLI mode that detects separated regions, chooses one shared texel density for the sheet, and repixelizes each region independently
2026-04-24 00:03:05 +01:00
- a tuning harness for offline parameter sweeps
2026-04-29 11:43:17 +01:00
- `source_fidelity` and `source_structure` metrics for lattice agreement and visible structure
2026-04-29 11:24:31 +01:00
- a shippable explicit local-search solver config, with tuning notes in `docs/solver-tuning-lessons-2026-04-29.md`
2026-04-24 00:03:05 +01:00
Current weak spots:
2026-04-29 11:24:31 +01:00
- `phase-field` is usable, not final; signal knobs still need a disciplined follow-up pass around the current motion basin
- lattice selection is still low-confidence on some ugly generated inputs, so visual inspection and pinned-size iteration remain important workflows
2026-04-22 14:11:16 +01:00
2026-04-21 16:15:05 +01:00
## Quickstart
2026-04-21 16:10:55 +01:00
```powershell
python -m venv .venv
.venv\Scripts\python -m pip install -e .[dev]
```
2026-06-03 02:59:32 +01:00
Launch the current browser lowering:
2026-04-26 05:45:33 +01:00
```powershell
.\scripts\run_gui.ps1
```
Run the optimizer from the CLI:
2026-04-21 16:10:55 +01:00
```powershell
repixelize input.png --out output.png
2026-04-21 21:56:25 +01:00
repixelize input.png --out output.png --diagnostics-dir diagnostics --device auto
2026-04-28 14:55:35 +01:00
repixelize input.png --out output.png --target-width 126 --target-height 126 --device cuda
2026-04-21 16:15:05 +01:00
```
Run the optimizer plus baselines:
```powershell
2026-04-21 16:10:55 +01:00
repixelize compare input.png --out output.png --diagnostics-dir diagnostics
```
2026-05-30 23:53:04 +01:00
Run a spritesheet as separate sprite regions:
```powershell
repixelize spritesheet sheet.png --out output.png --sprite-count 6 --target-width 32 --target-height 32
2026-05-31 02:14:03 +01:00
repixelize spritesheet sheet.png --out output.png --sheet-columns 3 --sheet-rows 2 --export-sprites-dir sprites
2026-05-30 23:53:04 +01:00
repixelize spritesheet sheet.png --out output.png --diagnostics-dir diagnostics
```
When `--sprite-count` is omitted, Repixelizer detects large separated foreground
2026-05-31 00:41:18 +01:00
regions. By default, automatic spritesheet mode infers each crop once, chooses a
robust shared texel density for the sheet, and pins each crop to that density
before reconstruction. Pinned target dimensions apply per sprite, not to the
whole sheet. Add `--strip-background` when the sheet has an opaque
edge-connected backdrop that should become transparent before cropping.
2026-05-31 02:14:03 +01:00
Use `--sheet-columns` and `--sheet-rows` for fixed-layout character sheets; grid
mode exports full cells and does not let disconnected limbs, weapons, shadows,
or effects become separate sprites.
2026-05-30 23:53:04 +01:00
2026-04-21 21:56:25 +01:00
## Corpus And Benchmarks
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
Prepare a local Creative Commons corpus:
2026-04-21 16:15:05 +01:00
```powershell
2026-04-21 21:56:25 +01:00
repixelize prepare-corpus --corpus-dir examples/corpus
2026-04-21 16:15:05 +01:00
```
2026-04-21 21:56:25 +01:00
Run the round-trip benchmark:
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
```powershell
repixelize benchmark --corpus-dir examples/corpus --out-dir artifacts/benchmark
```
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
Useful benchmark flags:
2026-04-21 16:10:55 +01:00
2026-04-21 21:56:25 +01:00
- `--profile soft` or `--profile crisp`
- `--case <name>` repeated for a focused slice
- `--limit <n>` for the first `n` matching cases
- `--infer-size` to test automatic size inference
- `--keep-existing` if you explicitly want to preserve an old output directory
2026-04-21 16:10:55 +01:00
2026-04-21 21:56:25 +01:00
By default the benchmark clears its output directory before each run so the artifacts folder stays readable.
2026-04-21 16:10:55 +01:00
2026-04-21 21:56:25 +01:00
## Tuning
2026-04-21 16:10:55 +01:00
2026-04-21 21:56:25 +01:00
Repixelizer includes a black-box tuning loop for longer offline searches over solver weights:
2026-04-21 16:10:55 +01:00
2026-04-21 21:56:25 +01:00
```powershell
repixelize tune --corpus-dir examples/corpus --out-dir artifacts/tuning --profile soft --limit 8
```
2026-04-21 16:10:55 +01:00
2026-04-21 21:56:25 +01:00
This is intentionally a search-based tuner, not gradient descent. The objective depends on discrete argmins, thresholding, and benchmark comparisons, so it is better treated as a repeatable black-box optimization problem.
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
## Repository Hygiene
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
This repo is set up to be safe for local experimentation:
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
- generated outputs under `artifacts/` are ignored
- local corpus payloads under `examples/corpus/originals/` are ignored
- archived raw sprite sheets under `examples/corpus/source-sheets/` are ignored
- generated corpus metadata files are ignored
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
That keeps benchmark assets, attribution exports, and tuning runs from polluting upstream history while still keeping the code, docs, and corpus layout tracked.
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
## Repo Layout
2026-04-21 16:10:55 +01:00
2026-04-21 21:56:25 +01:00
- `src/repixelizer` : core package
- `tests` : focused regression tests
- `docs/spec.md` : product and technical spec
- `docs/implementation-plan.md` : working roadmap
2026-04-29 11:43:17 +01:00
- `docs/lean-optimizer-algorithm-map.md` : map of the live phase-field solver
2026-04-21 21:56:25 +01:00
- `examples/corpus/README.md` : local corpus layout and attribution workflow
2026-04-21 16:15:05 +01:00
2026-04-21 21:56:25 +01:00
Core modules:
2026-04-21 16:15:05 +01:00
2026-04-28 14:55:35 +01:00
- `inference.py` : target size inference
2026-05-31 00:41:18 +01:00
- `spritesheet.py` : spritesheet region detection, shared-density sizing, and per-region pipeline orchestration
2026-04-29 11:43:17 +01:00
- `phase_field.py` : explicit local-search phase-field solver
2026-04-21 21:56:25 +01:00
- `metrics.py` : fidelity, adjacency, and motif metrics
- `benchmark.py` : corpus benchmark runner
- `tuning.py` : black-box hyperparameter search harness
- `synthetic.py` : facsimile generation for tests and benchmarks
2026-04-21 16:15:05 +01:00
## Validation
2026-04-21 21:56:25 +01:00
Run the focused test suite with:
2026-04-21 16:15:05 +01:00
```powershell
.venv\Scripts\python -m pytest -q
```
2026-04-21 16:10:55 +01:00
2026-04-26 12:34:44 +01:00
## Regenerating README Assets
The README images are generated from repo-tracked fixtures, not from random
2026-04-29 11:34:24 +01:00
artifacts left lying around:
2026-04-26 12:34:44 +01:00
```powershell
2026-04-26 13:57:09 +01:00
.venv\Scripts\python scripts\generate_readme_previews.py --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
2026-04-26 12:34:44 +01:00
```
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.
2026-04-22 10:46:46 +01:00
## Diagnostic Closeups
For docs or regression notes, you can generate reproducible source/output closeups from output-grid cell coordinates with:
```powershell
.venv\Scripts\python scripts\render_focus_crop.py --input tests\fixtures\real\ai-badge-cleaned.png --out docs\readme-assets\guard-right-crop-source-final.png --cell-bbox 73 20 107 44 --panels source,final --scale 16 --steps 48 --device cpu
```
If you want the full internal state sheet instead of the docs-facing comparison:
```powershell
2026-04-24 00:03:05 +01:00
.venv\Scripts\python scripts\render_focus_crop.py --input tests\fixtures\real\ai-badge-cleaned.png --out docs\readme-assets\guard-right-crop-states.png --cell-bbox 73 20 107 44 --panels source,initial,final --scale 16 --steps 48 --device cpu
2026-04-22 10:46:46 +01:00
```
Notes:
- `--cell-bbox` is in output-grid coordinates, not source-image pixels.
- The script maps that region back to the matching source crop automatically.
- `--device cpu` is the polite choice for docs generation if you do not want to stress the GPU for a tiny crop.
2026-04-21 21:56:25 +01:00
## Notes
2026-04-21 16:10:55 +01:00
2026-04-21 21:56:25 +01:00
- The local corpus is optional; the codebase is still usable without it.
- The benchmark and tuning commands are designed for iterative local work, not for shipping generated artifacts in git.
- Palette enforcement is optional and can be left off for unconstrained recovery runs.