- Python 75.1%
- TypeScript 7.8%
- JavaScript 7.5%
- HTML 6.4%
- CSS 2.9%
- Other 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| docs | ||
| examples/corpus | ||
| src/repixelizer | ||
| tests | ||
| .gitignore | ||
| pyproject.toml | ||
| README.md | ||
Repixelizer
Repixelizer is a standalone Python CLI 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.
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.
Real Example
This input was not chosen because it was easy. It has glossy shading, chunky highlights, and enough large-scale structure to confuse size inference in ways that are frankly a little rude.
The cleanest result here came from forcing --target-size 128:
Automatic lattice inference on this badge is much less wrong than it used to be, but this is still a good example of the kind of image where a manual target size can help.
Current Status
This is already a serious experimental baseline, not a toy prototype:
- CUDA-backed inference and solver paths are wired up
- round-trip corpus benchmarking is built in
- soft and crisp corruption profiles are supported
- diagnostics and baseline comparisons are written automatically
- a black-box tuning harness exists for longer offline parameter sweeps
The current pipeline is especially strong on benchmarked sprite and emblem inputs where local fake-pixel texture is meaningful but the global grid is inconsistent.
Quickstart
python -m venv .venv
.venv\Scripts\python -m pip install -e .[dev]
Run the optimizer:
repixelize input.png --out output.png
repixelize input.png --out output.png --diagnostics-dir diagnostics --device auto
Run the optimizer plus baselines:
repixelize compare input.png --out output.png --diagnostics-dir diagnostics
Corpus And Benchmarks
Prepare a local Creative Commons corpus:
repixelize prepare-corpus --corpus-dir examples/corpus
Run the round-trip benchmark:
repixelize benchmark --corpus-dir examples/corpus --out-dir artifacts/benchmark
Useful benchmark flags:
--profile softor--profile crisp--case <name>repeated for a focused slice--limit <n>for the firstnmatching cases--infer-sizeto test automatic size inference--keep-existingif you explicitly want to preserve an old output directory
By default the benchmark clears its output directory before each run so the artifacts folder stays readable.
Tuning
Repixelizer includes a black-box tuning loop for longer offline searches over solver weights:
repixelize tune --corpus-dir examples/corpus --out-dir artifacts/tuning --profile soft --limit 8
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.
Repository Hygiene
This repo is set up to be safe for local experimentation:
- 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
That keeps benchmark assets, attribution exports, and tuning runs from polluting upstream history while still keeping the code, docs, and corpus layout tracked.
Repo Layout
src/repixelizer: core packagetests: focused regression testsdocs/spec.md: product and technical specdocs/implementation-plan.md: working roadmapexamples/corpus/README.md: local corpus layout and attribution workflow
Core modules:
inference.py: target size and phase inferencecontinuous.py: source-aware lattice snapping and local discrete refinementmetrics.py: fidelity, adjacency, and motif metricsbenchmark.py: corpus benchmark runnertuning.py: black-box hyperparameter search harnesssynthetic.py: facsimile generation for tests and benchmarks
Validation
Run the focused test suite with:
.venv\Scripts\python -m pytest -q
Notes
- 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.