Skip to main content

ai2pixelart

Turn AI-generated pseudo pixel art (wobbly grids, mixed-color cells, way too many shades) into pixel-perfect, palette-clean pixel art — without losing the single-pixel details that carry the design.

Original AI pseudo-pixel-art vs. a naive downscale-and-median baseline vs. ai2pixelart's Neural Robust output, on three samples, each with a zoomed-in detail

Left: AI-generated pseudo-pixel-art. Middle: a naive "downscale + median" baseline — muddy and off-grid. Right: ai2pixelart's Neural Robust output. Each cell zooms the boxed detail so the difference is visible.

Setup

pip install ai2pixelart              # classical cleaner only (no GPU, no torch)
pip install "ai2pixelart[neural]"    # + run the trained networks
pip install "ai2pixelart[gen]"       # + full data-engine / training stack

Or with conda for development:

conda env create -f environment.yml   # creates env "ai2pixelart"
conda activate ai2pixelart
pip install -e ".[dev]"

The classical "Simple" approach needs no GPU; the neural approaches need the neural extra and download their weights from the Hugging Face Hub (arnekummerow/ai2pixelart) automatically on first use (cached thereafter — ai2pixelart models download pre-fetches them for offline use).

Usage

ai2pixelart clean input.png -o out.png --preview-scale 8         # classical
ai2pixelart clean input.png -o out.png --approach robust         # neural
ai2pixelart clean input.png -o out.png --palette "#1e2234,#5ea740,#f0f0f0"
ai2pixelart clean my_images/ -o out_dir/ --approach robust       # batch a folder
ai2pixelart inspect my_images/            # no-ground-truth quality table
ai2pixelart viewer my_images/             # interactive web workspace, port 8412

Neural inference uses the GPU automatically when one is available and falls back to CPU otherwise; force it either way with --device cpu / --device cuda (the tiny net is CPU-bound in practice, so the GPU mainly helps on large images or batches).

--approach is simple (classical, the default) or a neural model — a name under runs/ (robust, detail) or a path to a .safetensors/.ckpt file. Run ai2pixelart --help to see the full command tree (clean, viewer, inspect, eval, demo, plus data … and train … for the pipeline).

How it works

The classical pipeline ("Simple") detects the fake-pixel grid, extracts a palette, and votes each cell's color — deterministic, no GPU. The neural presets run the same grid/palette proposal, then a small U-Net assigns each cell a palette entry; it is structurally incapable of off-palette colors and carries learned priors (recovering pure 1-px details, collapsing shaded backgrounds) that no local method can. It was trained on pairs corrupted by the diffusion stack itself, so inverting AI rendering artifacts is exactly what it learned.

Two checkpoints are maintained: Neural Robust (recommended default) and Neural Detail (best 1-px retention on very fine grids, the fallback when Robust over-corrects).

Limitations

  • Fake-pixel pitch below ~2 px is undetectable by construction — set the pitch manually or use the granularity control.
  • One global grid per image: locally varying pitch is out of scope.
  • Colors missing from a forced palette cannot be assigned well by any method.

Documentation

  • docs/APPROACH.md — the method: classical pipeline, neural design, training-data philosophy, when to use which preset.
  • docs/VIEWER.md — the interactive workspace viewer.
  • docs/IMPLEMENTATION.md — module layout, data engine, retraining recipes, server API.
  • docs/DEVLOG.md — the full iteration history: what was tried, measured, rejected, and what's left as future work.

License

The pixel art you make with ai2pixelart is yours — sell it, ship it in a commercial game, whatever you like. The noncommercial terms restrict the tool, not its output. Concretely:

  • ✅ Use it (even at a company) to produce pixel art, and use that art commercially.

  • ✅ Modify and share the code and models for any noncommercial purpose, keeping the credit notice.

  • ❌ Commercialize the tool itself — selling it, or offering its functionality as a paid/subscription/ad-supported product, service, platform, or API — needs a separate license.

  • Source code — PolyForm Noncommercial License 1.0.0 + output carve-out.

  • Trained model weights — CC BY-NC 4.0 + output carve-out.

Credit: ai2pixelart © 2026 Arne Kummerow. These are source-available, not OSI "open source." To build something commercial on the tool, get in touch about a commercial license.

Metadata

Release files for ai2pixelart 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai2pixelart 0.1.2
File Size Uploaded Provenance Actions
ai2pixelart-0.1.2.tar.gz 99.8 kB Without provenance Details for ai2pixelart-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai2pixelart 0.1.2
File Interpreter ABI Platform Actions
ai2pixelart-0.1.2-py3-none-any.whl Python 3 none any Details for ai2pixelart-0.1.2-py3-none-any.whl

Total release size: 190.9 kB

Release files / ai2pixelart-0.1.2.tar.gz

Download URL ai2pixelart-0.1.2.tar.gz
Size 99.8 kB
Tags Source
SHA-256 checksum
How to use checksums
bd82ac962c5e91b5bf7032921fc801728341a6f698a0b3dcb0331a465ea29858
BLAKE2b-256 checksum
How to use checksums
6b3bb321351b310cad87b43bd4984bf366025a1242a749d2606d5b6bb743ab2a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.15

Release files / ai2pixelart-0.1.2-py3-none-any.whl

Download URL ai2pixelart-0.1.2-py3-none-any.whl
Size 91.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e8ac3971c99060242c42328bb8637f2a79cd90eeb1571af70630ea720e252036
BLAKE2b-256 checksum
How to use checksums
033bf1cf1ff2b094c6fb354ca99dbb76df1c6a94fa9e448ec4fc565860f048cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.15

Security for ai2pixelart 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page