203 lines
6.4 KiB
Markdown
203 lines
6.4 KiB
Markdown
# Repixelizer Spec
|
|
|
|
## Summary
|
|
|
|
Repixelizer is a Python tool with a CLI and web GUI for converting "fake pixel art" into true grid-aligned pixel art. The target use cases are single-image icons, emblems, logos, and simple sprites, especially images that already resemble pixel art but fail to obey a consistent pixel lattice.
|
|
|
|
The project exists because generated imagery often creates appealing pixel-like local patterns while violating the actual constraints of pixel art:
|
|
- inconsistent subpixel alignment
|
|
- locally plausible but globally incoherent clusters
|
|
- noisy highlights and outlines
|
|
- fake micro-detail that collapses when downsampled
|
|
|
|
Repixelizer treats this as a lattice-inference and reconstruction problem.
|
|
|
|
## Goals
|
|
|
|
- Recover an implied target pixel grid from a fake-pixel-art source image.
|
|
- Produce a true discrete-grid output image that looks authored, not merely resized.
|
|
- Preserve alpha, silhouette clarity, and strong interior structure.
|
|
- Support palette-free output by default, with optional palette-constrained modes.
|
|
- Provide diagnostics and baseline comparisons so results are inspectable and measurable.
|
|
|
|
## Non-goals for v1
|
|
|
|
- full sprite-sheet or animation consistency
|
|
- manual painting or mask authoring as a required workflow
|
|
- a native desktop app
|
|
- generalized photo-to-pixel-art stylization
|
|
- a learned model trained on a large dataset
|
|
|
|
## Primary users
|
|
|
|
- artists or developers trying to salvage generated fake pixel art
|
|
- tool builders experimenting with constrained repixelization
|
|
- game/UI developers creating icons, emblems, badges, and simple sprites
|
|
|
|
## Input and output contract
|
|
|
|
### Input
|
|
|
|
- one RGBA image file
|
|
- optional explicit target size override
|
|
- optional palette file
|
|
- optional diagnostics directory
|
|
- optional solver/device settings
|
|
|
|
### Output
|
|
|
|
- one final RGBA PNG
|
|
- optional palette-constrained output behavior
|
|
- optional diagnostics bundle containing JSON and visual artifacts
|
|
|
|
## Product behavior
|
|
|
|
### Canonical mode
|
|
|
|
The canonical workflow should be fully automatic:
|
|
|
|
1. load the source image
|
|
2. infer lattice size from autocorrelation candidates, unless the caller pins it
|
|
3. render a diagnostic edge preview
|
|
4. build the solver's hierarchical flatness signal from the source
|
|
5. run the `phase-field` reconstruction over the inferred lattice
|
|
6. sample real source pixels from the final source-position field
|
|
7. snap alpha to the final discrete mask
|
|
8. optionally quantize to a palette
|
|
9. write output and diagnostics
|
|
|
|
No manual masks or user-authored region hints are assumed in v1.
|
|
|
|
This is the canonical machine in the repo. Comparison mode just runs that same
|
|
`phase-field` result next to the baselines.
|
|
|
|
### CLI shape
|
|
|
|
Primary commands:
|
|
|
|
```powershell
|
|
repixelize input.png --out output.png
|
|
repixelize compare input.png --out output.png
|
|
```
|
|
|
|
Supported flags:
|
|
- `--target-size`
|
|
- `--target-width`
|
|
- `--target-height`
|
|
- `--palette`
|
|
- `--palette-mode off|fit|strict`
|
|
- `--diagnostics-dir`
|
|
- `--seed`
|
|
- `--steps`
|
|
- `--device cpu|cuda`
|
|
|
|
### Palette behavior
|
|
|
|
- `off`: produce unconstrained RGBA output
|
|
- `fit`: adapt to a useful palette derived from or compatible with the result
|
|
- `strict`: stay strictly inside a supplied palette
|
|
|
|
Palette constraints are optional because many generated fake-pixel-art images do not originate from a coherent palette.
|
|
|
|
## Technical design
|
|
|
|
### 1. Lattice inference
|
|
|
|
The tool must estimate the resolution of the fake lattice being mimicked.
|
|
|
|
Requirements:
|
|
- infer candidate target sizes from autocorrelation hints
|
|
- use canonical cell centers for each candidate
|
|
- score candidates using coherence-oriented metrics and source-derived periodicity priors
|
|
- expose the top-ranked alternatives in diagnostics
|
|
- if `--target-size`, `--target-width`, or `--target-height` is provided, skip automatic inference
|
|
|
|
Scoring goals:
|
|
- low isolated-pixel rate
|
|
- high cluster continuity
|
|
- strong alpha-edge crispness
|
|
- straighter outlines
|
|
- lower local color chatter
|
|
- reasonable agreement with source-derived periodicity priors
|
|
|
|
### 2. Diagnostic analysis and solver signal
|
|
|
|
The pipeline keeps two source-derived views separate:
|
|
|
|
- a diagnostic edge preview for GUI and run inspection
|
|
- a hierarchical flatness signal that actually steers the solver
|
|
|
|
The live solver signal is built from multiscale luminance gradient and curvature energy. It rewards calm local source regions while leaving edge preview as a gauge, not a hidden steering wheel.
|
|
|
|
### 3. Phase-field reconstruction
|
|
|
|
The solver represents each output pixel as one live source-space sample position initialized at a fixed lattice center.
|
|
|
|
Requirements:
|
|
- operate in premultiplied RGBA space
|
|
- initialize from canonical fixed lattice centers
|
|
- let each sample choose from a small local candidate window
|
|
- blend toward the locally preferred flatter source position
|
|
- relax row and column springs so the sample field stays coherent
|
|
- nearest-sample the original source pixels for final output
|
|
|
|
The current implementation is explicit NumPy local search plus spring relaxation.
|
|
|
|
### 4. Discrete projection and cleanup
|
|
|
|
After the phase-field stage, the result must be treated as a true pixel grid.
|
|
|
|
The discrete stage should:
|
|
- preserve source-sampled RGBA values
|
|
- snap alpha to an opaque/transparent mask
|
|
- keep structural repair in the solver
|
|
|
|
Cleanup is intentionally small 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
|
|
- all baselines
|
|
- metric collection
|
|
- a visual contact sheet
|
|
|
|
The project should treat these baselines as the minimum bar for usefulness.
|
|
|
|
## Diagnostics
|
|
|
|
Diagnostics should be machine-readable and human-readable.
|
|
|
|
Required artifacts:
|
|
- `run.json`
|
|
- `lattice-overlay.png`
|
|
- `comparison.png`
|
|
- `alpha-preview.png`
|
|
- `noise-heatmap.png`
|
|
|
|
Compare mode should additionally write:
|
|
- `compare.json`
|
|
- `compare.csv`
|
|
- `compare-sheet.png`
|
|
|
|
## Acceptance criteria
|
|
|
|
The tool is successful for v1 if it can:
|
|
- infer sensible target sizes on curated synthetic cases
|
|
- preserve transparency and silhouette quality
|
|
- produce outputs that are visibly more grid-coherent than simple resize baselines
|
|
- avoid obvious isolated-pixel explosions
|
|
- generate diagnostics that explain how and why a run behaved the way it did
|
|
|
|
## Future expansion
|
|
|
|
The design should leave room for:
|
|
- manual region hints or lock zones
|
|
- multi-frame consistency for sprite sheets
|
|
- more advanced warping or lattice-field models
|
|
- learned priors or ranking models for candidate outputs
|