CLI tool
Hugo-Dz/spritefusion-pixel-snapper avatar
Hugo-Dz/spritefusion-pixel-snapper

Sprite Fusion Pixel Snapper: a Rust CLI and WASM tool that snaps AI pixel art to a grid

A tool to snap pixels to a perfect grid. Designed to fix messy and inconsistent pixel art generated by AI.

3,534 stars228 forksRustMIT

At a glance

What is it?
Pixel Snapper detects the implicit grid in inconsistent pixel art and re-snaps it, then quantizes colors to a palette. Here is how the CLI and WASM builds work, and where the tool stops.
Who is it for?
Adopt Pixel Snapper if you generate pixel art with AI models or procedural code and need a consistent grid and palette before importing into a game engine. Skip it if your art is already grid-aligned and palette-quantized, or if you need a GUI editor with per-pixel brush control.
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 26 days ago.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Hugo-Dz/spritefusion-pixel-snapper3,534 ★ · +324
Star history
Repository2026-09-282026-11-15
Hugo-Dz/spritefusion-pixel-snapper3.2k3.5k

324 Stars in the last 48 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The grid problem Pixel Snapper was built to fix

AI image models do not produce grid-aligned pixel art. The README states the failure directly: pixels are inconsistent in size and position, the grid resolution can drift across the image, and colors are not tied to a strict palette. A sprite that looks fine at thumbnail size falls apart when a game engine tries to scale it, because there is no single pixel size to scale by.

Pixel Snapper is aimed at that specific gap. It takes a PNG or JPEG, detects the implicit grid the image was drawn on, snaps content to that grid, and quantizes the result to a fixed number of colors. The README lists three use cases: AI-generated pixel art, procedural 2D art such as tilemaps and isometric maps that does not fit a grid, and 2D game assets or 3D textures that need to scale cleanly.

The audience is therefore narrow and technical: developers and artists who already have an image and need it conformed to a grid, not people drawing pixel art from scratch. The README notes that dithering is preserved where possible, which matters because naive downscaling destroys it.

How the snapping and quantization pipeline is structured

The repository is a single Rust crate with two build targets. Cargo.toml declares crate-type as both cdylib and rlib, plus a binary named spritefusion-pixel-snapper at src/main.rs. That arrangement is what lets the same core code ship as a native CLI and as a WASM module for the browser.

Dependencies are deliberately small. The image crate is pulled in with default-features disabled and only the png and jpeg features enabled, so the tool reads and writes those two formats and nothing else. Randomness comes from rand with small_rng, rand_distr and rand_chacha, which suggests the color quantization step uses a randomized method rather than a deterministic median cut. Parallelism is native-only: rayon is declared under cfg(not(target_arch = "wasm32")), so batch processing over a directory can use multiple cores on the command line but not in the browser build. For WASM, wasm-bindgen and getrandom with the js feature are the only additions.

The public WASM surface is a single function, process_image, exported from the generated pkg directory. Everything else is internal. That is a clean boundary, though it also means there is no incremental API: each call takes bytes and returns bytes.

Installing the CLI and running a first conversion

Two install paths are documented. Homebrew installs a prebuilt binary from the project's tap, and Cargo builds from source, which requires a Rust toolchain. The Cargo route produces a standalone native binary.

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

Alternatively, with Rust already installed:

bash
cargo install spritefusion-pixel-snapper

The positional signature is documented as spritefusion-pixel-snapper <INPUT> <OUTPUT> [COLOR_COUNT] [OPTIONS]. INPUT can be a single PNG or JPEG, or a directory for batch processing; OUTPUT is a file or a directory. COLOR_COUNT defaults to 16. To quantize one image to a 16-color palette:

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

If the auto-detected grid is wrong, override it. The README states the value must be between 1 and half the smallest image dimension:

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

To constrain output to a fixed palette, pass comma-separated six-digit hex colors. The README example uses eight colors:

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

Run spritefusion-pixel-snapper --help for the full option list. After a run you should have a PNG at the output path whose pixels sit on a uniform grid and whose color count is at or below the requested number.

Batch runs and the WASM build for browser use

Batch mode is the same command with directories in place of files. The README shows a directory input and a separate output directory, with the pixel size override applying to the whole batch:

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

Because rayon is a native-only dependency, this is the path that can use multiple cores. The README does not state how many files can be processed at once or how output filenames are derived, so a first batch run is worth inspecting before pointing it at a large asset folder.

The WASM build targets the web. Clone the repository, then build the module with wasm-pack:

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

Note that --out-dir pkg matches the import path used in the README's JavaScript example, which imports from ./pkg/spritefusion_pixel_snapper.js. The exported function takes input bytes and up to three optional arguments. Passing null leaves an argument on its default behavior:

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

await init();

// process_image(inputBytes, kColors?, pixelSizeOverride?, paletteHex?)
const outputBytes = process_image(inputBytes, 16);

// With a custom palette
const recoloredBytes = process_image(inputBytes, null, null, "0f0f1b,ffecd6,ff4d6d,29adff");

The README does not document the return type beyond outputBytes, nor how errors surface if the input is not a valid PNG or JPEG. That is a gap worth checking against the source before wiring this into a web app.

Where Pixel Snapper is the wrong tool

The most obvious limitation is input format. The image crate is configured with only the png and jpeg features, so GIF, WebP, BMP and animated formats are out of scope. If your AI pipeline emits WebP, you convert first.

The second limitation is the auto-detection itself. The README presents --pixel-size as an override for when detection is wrong, which implies detection can be wrong, but it does not describe how the grid is detected or what conditions cause it to fail. Images with mixed pixel sizes, gradients, anti-aliased edges, or non-integer upscaling are the likely trouble cases, and none of them are addressed in the documentation. Treat the automatic path as a convenience and the override as the reliable one.

The third limitation is scope. This is not an editor. There is no brush, no layer model, no undo, and no way to correct a single bad pixel after the fact. The tool is a one-shot transform: input bytes in, snapped bytes out. If your workflow needs selective repair, you are looking at a different class of software.

Finally, palette constraint is all-or-nothing. Passing --palette forces every output pixel into that exact set. There is no documented weighting, no dithering strength control, and no way to exclude a region. The README notes dithering is preserved where possible, but it does not say what governs that decision.

How this compares to Aseprite and ImageMagick

The nearest general-purpose alternative is ImageMagick, which can also quantize colors and resize images from the command line. The difference is what each tool is told. ImageMagick needs you to specify the target geometry, for example a resize factor, because it has no concept of an implicit pixel grid. Pixel Snapper's premise is the opposite: you supply an image at whatever scale the model produced and the tool infers the grid, with --pixel-size as the manual escape hatch. That inference is the whole product.

Aseprite sits on the other side of the line. It is an editor with a full drawing and palette workflow, and it can be scripted, but it is designed around a human placing pixels. Pixel Snapper is designed around a machine having already placed them badly. For a single sprite you care about, opening it in an editor and fixing the grid by hand may take less time than tuning flags. For a directory of hundreds of AI-generated sprites, the batch mode is the reason the tool exists.

The honest framing: Pixel Snapper is narrower than both. It does one transform. That narrowness is a feature when you are processing assets in bulk and a liability when you need to make a judgement call about one image.

Licence, maintenance and what a fork would cost

The project is MIT licensed, with the copyright attributed to Hugo Duprez. MIT permits commercial use, modification and redistribution provided the licence text and copyright notice are retained. That is permissive enough for shipping inside a game pipeline. This is not legal advice; if you redistribute a modified binary, read the LICENSE file in the repository rather than relying on a summary.

The last push to the default branch was on 2026-07-16, which is under six months before today, so the repository is not stale by that measure. The repository is not archived. The repository has no published GitHub releases, so there is no published changelog to read; version 1.0.0 in Cargo.toml is the only version signal available.

Upgrade cost is low by construction. The dependency set is small and pinned to well-known crates: image 0.24, rand 0.8, rand_distr 0.4, rand_chacha 0.3, rayon 1.10, wasm-bindgen 0.2, getrandom 0.2. The main upgrade risk is the image crate, whose 0.24 line is older than current releases; moving past it would touch the decode and encode paths. Because the crate is dual-target, any change has to be validated twice, once natively and once through wasm-pack. A fork is realistic for a small team: the surface is one binary, one library, and one exported WASM function.

Editorial conclusion

Adopt Pixel Snapper if you generate pixel art with AI models or procedural code and need a consistent grid and palette before importing into a game engine. Skip it if your art is already grid-aligned and palette-quantized, or if you need a GUI editor with per-pixel brush control. Verify first that auto-detected pixel size matches your intended base resolution by running the CLI with --pixel-size set explicitly and comparing the output against the source, since the README does not document how detection fails.

Frequently asked questions

How do I install Sprite Fusion Pixel Snapper?

The README documents two routes: brew install Hugo-Dz/tap/spritefusion-pixel-snapper for a prebuilt binary, or cargo install spritefusion-pixel-snapper if you have a Rust toolchain. Building from source with cargo build --release places the binary at target/release/spritefusion-pixel-snapper.

Does Sprite Fusion Pixel Snapper work in the browser?

Yes. The crate declares cdylib as a crate type and the README documents building a WASM module with wasm-pack build --target web --out-dir pkg --release, then calling the exported process_image function from JavaScript.

What image formats does Sprite Fusion Pixel Snapper accept?

The README states the input is a PNG or JPEG image, or a directory of them for batch processing. Cargo.toml confirms this by enabling only the png and jpeg features on the image crate.

How do I control the number of colors in the output?

Pass a color count as the third positional argument, which defaults to 16, or pass --palette with comma-separated six-digit hex colors to constrain the output to a fixed set. The README shows both forms.

Can I override the pixel size that Sprite Fusion Pixel Snapper detects?

Yes, with --pixel-size. The README states the value must be between 1 and half the smallest image dimension, and shows it applied to both single-image and batch commands.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/hugo-dz-spritefusion-pixel-snapper.svg)](https://hysenlabs.com/projects/hugo-dz-spritefusion-pixel-snapper)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/hugo-dz-spritefusion-pixel-snapper.svg)](https://hysenlabs.com/projects/hugo-dz-spritefusion-pixel-snapper)

Was this useful?