_       __ _
  _ __ (_)_  __/ _(_)_  __
 | '_ \| \ \/ / |_| \ \/ /
 | |_) | |>  <|  _| |>  <
 | .__/|_/_/\_\_| |_/_/\_\
 |_|

Clean up AI-generated pixel art.
Snap to grid. Remove AA fuzz. Reduce to a palette. Remove backgrounds.

Download · Features · CLI Reference · How It Works

---

AI image generators produce "pixel art" riddled with mixels (mixed-resolution pixels), anti-aliasing artifacts, and colors that don't snap to any grid. pixfix takes that messy output and produces clean, uniform pixel art — while preserving the vibrancy and character of the original.

Available as a native desktop app (macOS, Windows, Linux) and a CLI tool for scripting and automation.

---

Features

Desktop App Side-by-side original / processed preview Live settings — tweak parameters, see results instantly Grid detection diagnostics and color histograms 3000+ palettes via Lospec, or load custom .hex files Sprite sheet auto-splitter with GIF animation export Batch processing — drag in a folder, process everything Full keyboard navigation

Processing Pipeline Auto-detect pixel grid size and phase offset Snap mode — enforces clean grid at original resolution Multiple downscale modes (center-weighted, majority-vote, center-pixel) OKLAB color quantization — perceptually accurate palette matching Anti-aliasing removal via triangle inequality in OKLAB space Background removal — flood-fill or global replacement Output resize — upscale for game engines (2x, 3x...)

---

Install

Desktop App

Download the latest release for your platform:

Platform	Download
macOS (Apple Silicon)	.dmg
macOS (Intel)	.dmg
Windows	.msi · .exe installer
Linux	.deb · .AppImage

CLI

# From source (requires Rust 1.70+)
git clone https://github.com/lovelaced/normalize-pixelart.git
cd normalize-pixelart
cargo build --release

# Binary at target/release/normalize-pixelart

Pre-built CLI binaries for all platforms are also available on the Releases page.

---

Desktop App

Keyboard Shortcuts

Key	Action
O	Open image
S	Save processed image
Space	Reprocess with current settings
R	Reset settings to defaults
Tab	Switch tabs
Esc	Back to Preview

Tabs

Tab	What it does
Preview	Side-by-side original vs. processed
Settings	All pipeline parameters with live preview
Diagnostics	Grid detection scores, color histogram
Batch	Process multiple images at once
Sheet	Split sprite sheets, normalize tiles, export GIFs

---

CLI Quick Start

# Auto-detect grid, normalize
normalize-pixelart process input.png output.png

# Force grid size, snap to PICO-8 palette
normalize-pixelart process input.png output.png --grid-size 4 --palette pico-8

# Remove background
normalize-pixelart process input.png output.png --grid-size 4 --remove-bg

# Batch process a folder
normalize-pixelart batch sprites/ output/ --grid-size 4 --palette sweetie-16

# Auto-split an AI sprite sheet
normalize-pixelart sheet ai_sheet.png --output-dir sprites/

# Interactive terminal editor (Sixel/halfblock preview)
normalize-pixelart tui input.png

---

How It Works

Input Image
    │
    ▼
┌─────────────────┐
│  Grid Detection  │  Find NxN pixel grid size and phase offset
└────────┬────────┘
         ▼
┌─────────────────┐
│   AA Removal     │  Remove anti-aliasing artifacts (optional)
└────────┬────────┘
         ▼
┌─────────────────┐
│ Grid Normalize   │  Snap/downscale pixels to the detected grid
└────────┬────────┘
         ▼
┌─────────────────┐
│   Quantize       │  Snap colors to a palette (optional)
└────────┬────────┘
         ▼
┌─────────────────┐
│  Background Rm   │  Remove solid backgrounds (optional)
└────────┬────────┘
         ▼
┌─────────────────┐
│  Final Resize    │  Scale to output dimensions if needed
└────────┬────────┘
         ▼
    Output Image

Grid Detection

For each candidate grid size (2..max), measures edge alignment — the ratio of color gradients at grid boundaries vs. non-boundary positions. The correct grid size maximizes this ratio because all real color transitions align to its grid lines. Phase detection scans all possible offsets to find where the grid starts, even when --grid-size is manually set.

Snap Mode (Default)

For each NxN block, finds the dominant color via center-weighted majority voting and paints every pixel in the block with that single color. Eliminates mixels and stray pixels while preserving dithering patterns across blocks (adjacent blocks can still have different colors). The output stays at the original resolution.

Color Quantization (OKLAB)

All color operations use OKLAB color space, which is perceptually uniform — Euclidean distance in OKLAB closely matches how humans see color differences. K-means clustering produces vibrant, meaningful centroids instead of muddy averages. Palette snapping picks the perceptually closest match.

Anti-Aliasing Removal

For each pixel, examines its 8-connected neighbors. If the pixel lies "between" the two most dominant neighbor colors in OKLAB space (triangle inequality test), it's identified as an AA artifact and snapped to the closer neighbor. Off by default — AI art has intentional edge detail that this can destroy.

---

CLI Reference

process — Normalize a single image

normalize-pixelart process [OPTIONS] <INPUT> [OUTPUT]

Output defaults to <input>_normalized.png.

All options

Grid

Flag	Description
--grid-size <N>	Override auto-detected grid size
--grid-phase <X,Y>	Override grid phase offset
--no-grid-detect	Skip grid detection (requires --grid-size)
--max-grid-candidate <N>	Max grid size to test (default: 32)

Downscale

Mode	Description
snap	Default. Clean grid at original resolution. Best for AI art.
center-weighted	Reduce to logical resolution, center pixels weighted more.
majority-vote	Reduce to logical resolution, most common color wins.
center-pixel	Reduce to logical resolution, center pixel only. Fastest.

Color

Flag	Description
--palette <NAME>	Built-in palette (pico-8, sweetie-16, endesga-32, endesga-64, gameboy, nes)
--palette-file <PATH>	Custom .hex palette file
--lospec <SLUG>	Fetch palette from Lospec by slug
--colors <N>	Auto-extract N colors via k-means
--no-quantize	Skip quantization

Background

Flag	Description
--remove-bg	Enable background removal
--bg-color <HEX>	Explicit background color
--bg-threshold <0-1>	Border detection threshold (default: 0.4)
--bg-tolerance <N>	Color tolerance in OKLAB (default: 0.05)
--no-flood-fill	Global replacement instead of flood-fill

Output

Flag	Description
--target-width <N>	Output width
--target-height <N>	Output height
--aa-threshold <0-1>	Enable AA removal (off by default)
--overwrite	Overwrite existing output

batch — Process multiple images

normalize-pixelart batch [OPTIONS] <INPUT> <OUTPUT_DIR>

INPUT can be a directory or glob pattern. All process flags available.

sheet — Sprite sheet processing

normalize-pixelart sheet [OPTIONS] <INPUT> [OUTPUT]

Fixed grid — specify --tile-width and --tile-height for known layouts. Auto-split — omit tile dimensions to auto-detect sprite boundaries.

Sheet options

Flag	Description
--tile-width <N> / --tile-height <N>	Fixed tile size (omit for auto-split)
--spacing <N>	Gap between tiles (default: 0)
--margin <N>	Sheet border (default: 0)
--separator-threshold <0-1>	Auto-split separator detection (default: 0.90)
--min-sprite-size <N>	Filter small artifacts (default: 8)
--pad <N>	Output padding per sprite (default: 0)
--output-dir <PATH>	Save individual tiles
--no-normalize	Split/reassemble only

tui — Interactive terminal editor

normalize-pixelart tui [INPUT]

Terminal UI with live image preview (Sixel/halfblock). Requires the tui feature (default).

palette — Palette utilities

normalize-pixelart palette list                        # Show built-in palettes
normalize-pixelart palette fetch endesga-32            # Download from Lospec
normalize-pixelart palette extract input.png -o p.hex  # Extract from image

---

Config File

Save settings in .normalize-pixelart.toml — CLI arguments override config values.

Example config

[grid]
size = 4
max_candidate = 16

[aa]
threshold = 0.3

[quantize]
palette = "pico-8"

[background]
enabled = true
color = "FF00FF"
flood_fill = true

[output]
overwrite = false

---

Performance — parallelized via rayon. Grid detection, AA removal, batch mode, and sprite sheet tiles all process in parallel. A 1024x1024 image typically completes in under 1 second.

MIT License