proper-pixel-art: recovering true pixel grids from noisy AI output
Fixes AI pixel art images, video, or sprite web uploads
At a glance
- What is it?
- A Python tool that takes a high-resolution, grid-misaligned pixel-art-style image and returns a clean true-resolution asset. The mesh-fitting approach is the interesting part, and the documentation is honest about where it breaks.
- Who is it for?
- Adopt proper-pixel-art if you are producing pixel-art-style assets with a generative model and need them at true pixel resolution without redrawing, and if your images are already approximately grid-aligned. Do not adopt it if your source is heavily compressed, rescaled with interpolation, or the object is round and low quality; the README labels the round Stardew pumpkin case adversarial for exactly that reason.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap between what image models draw and what engines need
Generative models produce images that look like pixel art at a glance and are not pixel art. The README describes the failure mode directly: such images often have a non-uniform grid and random artifacts, so standard downsampling fails. A naive nearest-neighbour downscale assumes a regular lattice. If the model drew a 12-pixel-wide bat in one region and a 13-pixel-wide bat in another, one global scale factor will smear one of them. The manual alternative is redrawing the asset pixel by pixel, which is slow and does not scale to a sprite sheet.
The intended user is a game developer or generative-art practitioner who already has a source image, either from a model such as the gpt-image-2 example named in the README, or from a low-quality web upload such as the Google Images screenshot of a Pokemon asset used as a sample. The tool does not generate art. It recovers a grid from art that already exists.
Mesh fitting is the mechanism, not downscaling
The README states that a mesh is computed, where each cell corresponds to one pixel. That is the whole architecture in one sentence, and it is worth taking seriously. Rather than picking a single integer scale factor and resampling, the tool estimates a deformable grid over the image, then reads one colour per cell. The repository's example folders show the intermediate state: each sample directory contains the noisy source, a mesh image, and the result, so the fit can be inspected before the output is trusted.
This is why the tool can handle a non-uniform grid at all. A global downsample has one degree of freedom. A mesh has many, which is also its weakness: more parameters means more ways to fit noise. The README is upfront that the algorithm performs well for images that are already approximately aligned to a grid, and that the round pumpkin from a low-quality screenshot is treated as an adversarial example. A curved edge crossing a deformable grid gives the fitter no strong straight-line signal to lock onto.
Videos and GIFs go through the same pipeline. The README lists them as supported without describing how temporal consistency is handled across frames, so whether the mesh is refit per frame or carried forward is not something I can confirm from the supplied material.
Install paths and the CLI surface
Two installs exist. pip install proper-pixel-art gives the CLI and Python API; pip install "proper-pixel-art[web]" adds the local web UI. The uv equivalents are uv add proper-pixel-art and uv add proper-pixel-art --extra web. From source it is a clone followed by uv sync --extra web. There is also a no-install route: uvx --from "proper-pixel-art" ppa for the CLI and uvx --from "proper-pixel-art[web]" ppa-web for the UI.
The CLI signature given in the README is ppa <input_path> -o <output_path> -c <num_colors> -s <result_scale> [-t]. Four arguments carry real weight. -c sets the palette size, which is the main quality lever: too many colours and residual anti-aliasing survives, too few and distinct shades collapse. -s controls the result scale, so the output can be emitted larger than true resolution for inspection. -t is a flag whose meaning the README excerpt does not spell out, so check the full help text before relying on it.
ppa-web opens http://127.0.0.1:7860. The same interface is hosted on Hugging Face Spaces, which is the fastest way to judge whether the algorithm suits your inputs before installing anything. A configuration file is documented as a usage mode, but the excerpt cuts off before the keys, so I cannot list them here.
The adversarial case is the honest part of the README
Most project READMEs show only wins. This one includes a pumpkin screenshot from Stardew Valley and labels it adversarial because the source is both low quality and the object is round. That is a useful disclosure, and it maps to a real boundary. If your source has been through JPEG compression, upscaling with bilinear or bicubic interpolation, or a screenshot at non-integer device pixel ratio, the grid signal is weakened before the tool ever sees it. Round or organic shapes compound the problem because they offer few long straight edges for the mesh to align against.
The wrong tool for this job is a clean pixel-art PNG you already have at native resolution. Running it through a grid-recovery pass adds a chance of error and buys nothing. It is also the wrong tool when the source is not pixel-art-styled at all: a photograph of a real object, which the README addresses in a separate section titled Real Images To Pixel Art, is a different problem with different expectations. And if your output must be pixel-perfect against a reference sprite, an automated fit is not a substitute for a human pass, because the mesh optimises a global fit and can be locally wrong by one cell at an edge.
Where it sits against plain downscaling and against pixelisation filters
The obvious alternative is Pillow's resize with Image.NEAREST at an integer factor, or ImageMagick's -sample. Those are exact, dependency-light and fast, and they work when the source grid is uniform. The difference in approach is that they assume the grid rather than estimating it. Once the assumption holds, proper-pixel-art has no advantage. Once it fails, no amount of nearest-neighbour resampling recovers it, because the error is in the geometry, not the interpolation.
The other family of alternatives is pixelisation filters, the kind that quantise colours and snap edges to a grid in one pass. Those typically operate on photographs to make them look like pixel art, which is the inverse of this tool's job. They also tend to hard-code a target cell size rather than infer one. proper-pixel-art's distinguishing claim is that it infers the cell geometry from the image via the mesh, and the mesh image in each example folder is the evidence you can check for yourself. If the mesh looks wrong, the result will be wrong, and the failure is visible before you commit to the output.
Maintenance, packaging and the MIT licence
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are retained. That is the standard reading, not legal advice; confirm the LICENSE file in the repository matches the badge before shipping anything commercially. The README does not state any restriction on generated output, so the licence question is about the code, not about assets you process with it.
On release cadence, the repository shows v1.7.0, v1.7.1 and v1.7.2 within roughly a week in July 2026, with a last push in September 2026. Three patch releases that close together usually mean bug fixes after a feature release, so pinning a minor version is reasonable if you are embedding the library. The package is on PyPI with a CI workflow and a published Python version range badge, and it is not archived. It is also on Hugging Face Spaces, which means the web UI can be tried without a local install. The upgrade cost is low for the CLI, but if you depend on the Python API, note that the README excerpt does not document its signatures, so treat that surface as the least stable part of the contract.
Editorial conclusion
Adopt proper-pixel-art if you are producing pixel-art-style assets with a generative model and need them at true pixel resolution without redrawing, and if your images are already approximately grid-aligned. Do not adopt it if your source is heavily compressed, rescaled with interpolation, or the object is round and low quality; the README labels the round Stardew pumpkin case adversarial for exactly that reason. Before committing, run ppa on two or three of your own worst inputs rather than the bundled examples, and check the mesh output, since the mesh is where a bad fit becomes visible. Verify the licence file in the repository matches the MIT badge before shipping the output commercially.
Community notes