Summary

Proper Pixel Art addresses the challenge of converting noisy, high-resolution images, often generated by AI models or sourced from low-quality web uploads, into clean, true-resolution pixel art assets. It targets developers and artists seeking to create usable game assets or stylized graphics from imperfect inputs, offering a programmatic solution that avoids manual pixel-by-pixel recreation.

How It Works

The core approach reconstructs the pixel grid of input images using a multi-stage image processing pipeline. It begins by cleaning the input (edge trimming, alpha handling) and then upscales the image to aid in edge detection via Canny algorithms. A probabilistic Hough transform identifies dominant horizontal and vertical lines to define a pixel grid. After clustering these lines and determining grid spacing, the image is quantized to a limited color palette. Finally, the most common color within each identified grid cell is sampled to render the final, true-resolution pixel art. This method overcomes limitations of naive downsampling by explicitly reconstructing the underlying pixel structure.

Quick Start & Requirements

Installation involves cloning the repository and synchronizing dependencies using uv:

git clone git@github.com:KennethJAllen/proper-pixel-art.git
cd proper-pixel-art
# Ensure uv is installed
uv sync

Usage is available via CLI:

uv run ppa -i <input_path> -o <output_path> -c <num_colors> -s <result_scale> [-t]

Key parameters include input/output paths, number of colors (-c, default 16), and result scale (-s, default 1). A Python API is also provided using PIL:

from PIL import Image
from proper_pixel_art.pixelate import pixelate
image = Image.open('input.png')
result = pixelate(image, num_colors=16)
result.save('output.png')

Dependencies include Python and Pillow. No specific hardware (e.g., GPU) requirements are listed.

Highlighted Details

• Specifically designed to handle artifacts common in AI-generated pixel art (e.g., GPT-4o outputs), such as non-uniform grids and noise.
• Employs Canny edge detection and Hough line transforms to robustly identify pixel boundaries and reconstruct the grid.
• Offers control over output color count and pixel scaling, allowing customization of the final asset.
• Can be integrated into workflows for converting real-world images to pixel art via an intermediate LLM-generated pixelated version.

Licensing & Compatibility

The provided README does not specify a software license. Users should verify licensing terms before adoption, particularly for commercial or closed-source integration.

Limitations & Caveats

The quality of the output is sensitive to the chosen number of colors (-c), potentially requiring iterative tuning. The algorithm performs best on images that are already roughly aligned to a grid. The effectiveness of the initial upscaling step (-u parameter) versus parameter tuning for grid detection warrants further investigation.