Proper Pixel Art
Fixes AI pixel art or sprite web uploads
Last verified:
What is Proper Pixel Art?
Proper Pixel Art is a Python tool that converts noisy, high-resolution pixel-art-style images into true pixel-resolution usable assets. It is specifically designed to handle images produced by generative AI models like GPT-4o, which typically have high noise, inconsistent grid spacing, and random artifacts that make standard downsampling ineffective. The tool can also clean up clean screenshots or low-quality web uploads of sprites.
The tool works by computing a pixel mesh, detecting edges using Canny edge detection, finding grid lines via probabilistic Hough transform, and then quantizing colors to produce a clean pixel art image. Users can specify the number of colors in the output (typically 8, 16, 32, or 64 work well), the pixel size for upscaling, and whether to output with a transparent background. The tool is available as both a CLI tool and as a Python library.
This tool is ideal for game developers, pixel artists, and anyone working with AI-generated pixel art who needs clean, usable sprite assets. It handles challenging cases like round objects and low-quality source images, making it robust for real-world use cases where manual pixel-by-pixel recreation would be time-consuming.
Proper Pixel Art pricing
Pricing model: Freemium
Free and open source under MIT license. Available via pip3 install proper-pixel-art or by cloning the GitHub repository. No paid tiers or commercial licensing required.
Proper Pixel Art pros
- Converts AI-generated pixel art into usable game assets
- Handles noisy, high-resolution input images effectively
- Works with GPT-4o image generator outputs
- Automatically detects and corrects inconsistent grid spacing
- Removes random artifacts from source images
- Supports transparent background output
- Customizable number of output colors (8, 16, 32, 64)
- Available as both CLI and Python library
- Upscaling option with configurable pixel size
- Robust performance on round objects and challenging images
- Works with low-quality web sprite uploads
- MIT license for open use
- Visualizes intermediate steps for debugging
- No manual pixel-by-pixel recreation needed
- Produces faithful results to original image intent
- 213 GitHub stars showing community adoption
Proper Pixel Art cons
- Requires Python and virtual environment setup
- Number of colors parameter needs manual tuning
- May require multiple runs if colors don't look right
- Only supports Python (no web interface)
- Requires PIL/Pillow dependency
- Uses uv for dependency management (extra tool to install)
- No GUI - command line only for most users
- Output sensitive to color count parameter choice
- May not work well on images not approximately grid-aligned
Frequently asked questions about Proper Pixel Art
What does Proper Pixel Art do?
Proper Pixel Art converts noisy, high-resolution pixel-art-style images from generative models like GPT-4o or low-quality web sprite uploads into true pixel-resolution usable assets. It automatically detects the pixel grid, removes noise and artifacts, and produces clean pixel art suitable for game development.
How do I install Proper Pixel Art?
You can install it via pip3 install proper-pixel-art in a virtual environment, or clone the repository with git clone [email protected]:KennethJAllen/proper-pixel-art.git and run uv sync to set up the environment.
What input images work best?
The tool works best with images that are already approximately aligned to a grid. It handles GPT-4o generated pixel art, screenshots of pixel art, and low-quality web sprite uploads. It even works on challenging cases like round objects from Stardew Valley assets.
How do I choose the number of colors?
Try 8, 16, 32, or 64 colors as these typically work well. The result is sensitive to the color count, so you may need to re-run the script with different values if the colors don't look right. Start with 16 (the default) and adjust from there.
Can I get a transparent background?
Yes, use the -t or --transparent flag in the CLI, or set transparent_background=True in the Python API. This floods each corner of the result with transparent alpha.
What is the CLI command syntax?
The basic syntax is: uv run ppa -i <input_path> -o <output_path> -c <num_colors> -p <pixel_size> [-t]. For example: uv run ppa -i assets/blob/blob.png -o . -c 16 -p 20 -t
How does the algorithm work?
The algorithm trims edges and zeros out pixels with >50% alpha, upscales by 2x using nearest neighbor, detects edges with Canny, closes gaps with morphological closing, uses probabilistic Hough transform to find grid lines, clusters nearby lines, computes grid spacing via median, quantizes to the specified number of colors, and selects the most common color in each mesh cell.
Can I use this with real images?
Yes, you can first request a pixelated version of a real image from GPT-4o, then use Proper Pixel Art to get the true pixel-resolution version. This two-step process converts real photos into clean pixel art.
Is there a web interface?
No, Proper Pixel Art is a command-line tool and Python library only. There is no web-based interface. You need to install Python and run it locally or on a server.
What if results aren't what I want?
Try adjusting the number of colors parameter (-c flag), as the output is sensitive to this value. You can also try different upsample_factor values to help detect lines, or enable intermediate_dir to visualize each step of the algorithm for debugging.