Sprite Fusion Pixel Snapper: A Rust CLI and WASM Tool to Fix AI-Generated Pixel Art

The Problem with AI-Generated Pixel Art

Current AI image models are trained on photographic and painterly datasets. When prompted to generate pixel art, they produce images that resemble pixel art visually but fail at the technical level. The README identifies three specific failure modes: pixels are inconsistent in size and position, the implicit grid resolution drifts across the image, and colors are not tied to a strict palette.

These failures make AI-generated pixel art unusable for tilemaps, isometric game maps, or any context that requires a consistent pixel grid. Sprite Fusion Pixel Snapper addresses all three. It detects the implicit grid, snaps every pixel to that grid, and quantizes the colors to a fixed palette. The README notes that the tool preserves detail including dithering during this process.

Who Uses It and What It Handles

The README lists three use cases. The first is AI-generated pixel art that needs grid correction. The second is procedural 2D art that does not naturally align to a grid, such as tilemaps or isometric maps produced by generative tools. The third is 2D game assets and 3D textures that must scale consistently.

The tool is a project under Sprite Fusion, which the README describes as a tool to generate pixel art sprites and animations for game development. Pixel Snapper is positioned as a cleanup step after AI or procedural generation, not as a generator itself.

Installing Pixel Snapper via Homebrew or Cargo

There are two CLI install paths. On macOS with Homebrew:

brew install Hugo-Dz/tap/spritefusion-pixel-snapper

With Cargo (requires Rust installed):

cargo install spritefusion-pixel-snapper

The Cargo route installs from crates.io and produces a standalone native binary. To build from source instead:

git clone https://github.com/Hugo-Dz/spritefusion-pixel-snapper.git
cd spritefusion-pixel-snapper
cargo build --release

The built binary will be at `target/release/spritefusion-pixel-snapper`.

The basic usage pattern is:

spritefusion-pixel-snapper <INPUT> <OUTPUT> [COLOR_COUNT] [OPTIONS]

The `INPUT` can be a PNG or JPEG file, or a directory for batch processing. The `OUTPUT` is a PNG file or a directory for batch output. `COLOR_COUNT` defaults to 16 if omitted. Run `spritefusion-pixel-snapper --help` to see all options.

Running the CLI: Single Files, Batches, and Custom Palettes

To quantize a single image to a 16-color palette:

spritefusion-pixel-snapper input.png output.png 16

To process an entire directory as a batch:

spritefusion-pixel-snapper sprites/batch_inputs sprites/batch_outputs 16

If the auto-detected pixel size is wrong, override it with `--pixel-size`. The value must be between 1 and half the smallest image dimension:

spritefusion-pixel-snapper input.png output.png --pixel-size 8

To constrain the output to a specific palette, pass comma-separated six-digit hex colors with `--palette`:

spritefusion-pixel-snapper input.png output.png --palette "0d2b45,203c56,544e68,8d697a,d08159,ffaa5e,ffd4a3,ffecd6"

All four options compose. A batch run with a fixed pixel size and fixed palette:

spritefusion-pixel-snapper sprites/batch_inputs sprites/batch_outputs 16 --pixel-size 8

The auto-detection is the main draw for most users. It reads the implicit grid without requiring you to know the intended pixel size in advance.

Building and Using the WASM Module

Pixel Snapper also compiles to WebAssembly for use in browser projects. Clone the repository, then build the WASM module with wasm-pack:

wasm-pack build --target web --out-dir pkg --release

The output goes to the `pkg/` directory. Import and use it in JavaScript:

import init, { process_image } from "./pkg/spritefusion_pixel_snapper.js";

await init();

const outputBytes = process_image(inputBytes, 16);

The `process_image` function takes the image as a byte array, an optional color count, an optional pixel size override, and an optional palette hex string. Pass `null` for any argument you want to leave at its default. To apply a custom palette:

const recoloredBytes = process_image(inputBytes, null, null, "0f0f1b,ffecd6,ff4d6d,29adff");

The Cargo.toml shows that the native build uses Rayon for parallel processing, while the WASM build swaps it out for WASM-compatible random number generators via wasm-bindgen and getrandom with the `js` feature.

How the Pixel Snap and Color Quantization Work

The Cargo.toml describes the tool's purpose as detecting and snapping an image to its implicit grid, which tells you what the core algorithm does. The tool reads the image, identifies where pixel boundaries fall by looking for repeating patterns, and then rounds each sample to the nearest grid position. Colors in the resulting image are then reduced to the target palette size using quantization.

The native CLI build depends on Rayon for parallel processing, which means it uses all available CPU cores when processing a batch directory. The WASM build replaces the Rayon dependency with WASM-compatible random number generators via wasm-bindgen and getrandom with the `js` feature flag, since browser environments do not support Rayon's thread-based parallelism.

The `--palette` flag accepts comma-separated six-digit hex colors without a hash prefix. When you pass a palette, the quantization step maps each output color to the closest entry in your list rather than computing an optimal palette from the image data. This is the mechanism for matching a specific game engine's indexed color format. The default color count of 16 suits most pixel art that uses a limited palette, but AI-generated images often need fewer than 16 to look clean.

The README notes that the tool preserves dithering during the snap process. Dithering uses alternating pixels of two colors to simulate a third, and it is a technique common in retro pixel art. Losing dithering during grid correction would visually degrade the output, so preserving it is a meaningful design choice for game asset workflows.

Limitations and Cases Where Pixel Snapper Is the Wrong Tool

The tool assumes the input has an implicit pixel grid to detect. Images that are purely photographic, vector-rendered, or painted without any grid structure will produce incorrect results because the detection algorithm will find a grid that does not correspond to intended pixel boundaries.

The `--pixel-size` constraint documented in the README, that the value must be between 1 and half the smallest image dimension, means that very small sprites impose a strict ceiling on how small the pixel size override can be. The README does not document what happens when auto-detection fails on an unusual input, which leaves behavior undefined for edge cases.

The color count option reduces the palette but does not allow specifying which colors to remove. If the output palette must match a specific game engine's indexed format, the `--palette` flag is more reliable than the count-based quantization.

Comparison with Manual Pixel Art Correction and Project Status

The manual alternative is to correct AI-generated pixel art in a dedicated pixel art editor such as Aseprite. Aseprite is a paid desktop application specifically designed for pixel art editing and animation. The difference in approach is that Aseprite requires a human to manually identify the grid, realign pixels, and reduce the palette through the editor's tools. Pixel Snapper automates the grid detection and color quantization steps but produces a single fixed output. Aseprite allows iterative manual refinement with full visibility into each pixel.

The last push was on 2026-07-16. There are no GitHub releases. The Cargo.toml lists version 1.0.0. The project is MIT-licensed. An online version is available at spritefusion.com/pixel-snapper and a desktop edition is documented on the same site.

Editorial conclusion

Sprite Fusion Pixel Snapper is the right tool when you have AI-generated images that look like pixel art but have inconsistent pixel sizes, drifting grid alignment, or unquantized colors. It is not useful for photographs, vector art, or any image that is not grid-based. The auto-detection of pixel size works for most inputs, but the README notes that `--pixel-size` must be between 1 and half the smallest image dimension, so very small sprites may hit that floor quickly. For web integration, build the WASM module with wasm-pack and call `process_image` directly from JavaScript.

Frequently asked questions

Official sources

1. Hugo-Dz/spritefusion-pixel-snapper on GitHub
2. Issues
3. License: MIT
4. Project website
5. README