Your AI Pixel Art Is Almost Perfect—Here's How to Actually Fix the Grid
You've got an AI-generated pixel art image that looks right at a glance, but something's off. The pixels aren't quite square. The grid is inconsistent. Maybe you don't even know how many pixels wide the image is supposed to be. Standard scaling tools won't save you here, because they assume a clean, uniform grid that your image doesn't have. Perfect Pixel is a small Python tool built to solve exactly this problem: it detects the grid in a pixel-style image and snaps everything back into perfect alignment.
What It Does
Perfect Pixel is a Python library that takes a pixel-style image—typically AI-generated—and refines it into a properly aligned grid. The core problem it addresses is that AI image generators produce images that look like pixel art but don't actually conform to a clean pixel grid. Sizes are inconsistent, grids aren't square, and the result is an image that falls apart the moment you try to scale or edit it.
The tool automatically detects the grid size from the image itself, then realigns the pixels to that grid. There are two implementations of the same algorithm: an OpenCV-backed version (perfect_pixel.py) that's faster, and a lightweight NumPy-only version (perfect_pixel_noCV2.py) for environments where you can't or don't want to install OpenCV. There's also a ComfyUI custom node for those working in that ecosystem, and the core algorithm is left untouched in that integration—it just provides a friendlier interface.
Why It's Cool
It solves a problem most tools ignore. Most image processing tools assume your grid is already correct. Perfect Pixel starts from the assumption that it isn't, and figures out the grid for you. That's a meaningfully different approach, and it's the right one for AI-generated content.
The dual-backend design is a thoughtful touch. Shipping both an OpenCV version and a NumPy-only version means you're not locked out if you're working in a constrained environment—a serverless function, a minimal Docker image, or some other setup where adding OpenCV is a hassle. The README is upfront about the tradeoff: OpenCV is recommended for performance, but NumPy gets the job done.
A ComfyUI node exists. If you're already generating images in ComfyUI, you don't have to leave your workflow to fix them. The integration doesn't mess with the core algorithm, which is reassuring—it's a thin interface layer, not a fork.
The README walks you through the whole pipeline. It doesn't just say "give it a pixel image." It explains that you first need to generate a pixel-style image (with Stable Diffusion, ChatGPT, Gemini, or whatever you prefer), gives you a sample prompt for doing so, and then shows you how to refine the output. That's the kind of practical guidance that saves you from staring at an error message wondering what went wrong.
How to Try It
Getting started is straightforward. Install via pip—the OpenCV version if you want speed, the plain version if you want minimal dependencies:
# Recommended: Fast version with OpenCV support
pip install perfect-pixel[opencv]
# Numpy version: Lightweight (NumPy only)
pip install perfect-pixel
Then run it on an image:
import cv2
from perfect_pixel import get_perfect_pixel
bgr = cv2.imread("images/avatar.png", cv2.IMREAD_COLOR)
rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
w, h, out = get_perfect_pixel(rgb)
The function returns the detected width, height, and the refined output image. The README recommends starting with an image between 512 and 1024 pixels—large enough to have a detectable grid, small enough to process quickly.
If you want to see it in action before installing anything, there's a web demo you can try in your browser. And if you're a ComfyUI user, the repo includes instructions for the custom node.
You can find the full source and examples at github.com/theamusing/perfectpixel.
Final Thoughts
Perfect Pixel is a focused tool for a specific problem, and that's its strength. It doesn't try to be a full image editor or a general-purpose upscaler. It detects grids and fixes misaligned pixel art—and from the looks of the README, it does that one thing well. If you're working with AI-generated pixel art and you've hit the wall of "this looks right but won't scale," this is worth a look. The dual-backend approach and ComfyUI integration suggest the author has thought about real-world usage, not just the happy path.