Repixelizer

Repixelizer is a standalone Python CLI that turns "fake pixel art" into true grid-aligned pixel art for icons and sprites.

It does not rely on a single resize pass. Instead it:

infers the source image's implied pixel lattice,
initializes a target grid at that resolution,
runs a continuous UV optimization stage in premultiplied RGBA space,
projects the result onto a real pixel grid with discrete cleanup,
optionally constrains the output to a palette, and
writes diagnostics and baseline comparisons.

Installation

python -m venv .venv
.venv\Scripts\python -m pip install -e .[dev]

Usage

repixelize input.png --out output.png
repixelize input.png --out output.png --target-size 120 --diagnostics-dir diagnostics
repixelize compare input.png --out output.png --diagnostics-dir diagnostics

Palette modes

off: keep the full-color RGBA output.
fit: derive or adapt to a useful palette and write palette diagnostics.
strict: require a supplied palette file and stay inside it exactly.

Palette files can be .gpl, .txt, or .json.

Diagnostics

When --diagnostics-dir is supplied, Repixelizer writes:

run.json: chosen size, phase, score breakdown, timings, and settings
lattice-overlay.png: inferred lattice drawn over the source
comparison.png: source, optimized output, and nearest-neighbor preview
alpha-preview.png: source/result alpha
noise-heatmap.png: local noise and isolated-pixel hotspots
cluster-preview.png: coarse material/color clustering
compare mode extras:
- compare.json
- compare.csv
- compare-sheet.png

Architecture

repixelizer.inference: lattice and target-size inference
repixelizer.continuous: PyTorch UV-field optimization
repixelizer.discrete: local-search cleanup on the final grid
repixelizer.baselines: naive and error-diffusion baselines
repixelizer.diagnostics: machine-readable and visual debug outputs

Current scope

Version 0.1.0 is single-image only. It is aimed at icons, emblems, and simple sprites first, with automatic resolution inference and no manual masks.

2.1 KiB Raw Blame History