spritefusion-pixel-snapper 1.0.0

Fix AI-generated pixel art by detecting and snapping it to its implicit grid.
Documentation

Sprite Fusion Pixel Snapper

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

Why ?

Current AI image models can't understand grid-based pixel art.

  • Pixel are inconsistent in size and position.
  • The grid resolution can drift over time.
  • Colors are not tied to a strict palette.

With Pixel Snapper:

  • ✅ Pixel are snapped to a perfect grid.
  • ✅ The grid resolution is consistent and can be scaled to pixel resolution.
  • ✅ Colors are tied to a strict, quantized palette. You can also use a custom palette.

Perfect for

  • AI generated pixel art that needs to be snapped to a grid.
  • Procedural 2D art that doesn't fit a grid like tilemaps or isometric maps.
  • 2D game assets and 3D textures that need to be perfectly scalable.

💻 Use it with CLI

Requires Rust installed on your machine.

cargo install spritefusion-pixel-snapper

Process one image:

spritefusion-pixel-snapper input.png output.png

The command accepts an optional k-colors argument:

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

Use a directory as the input path to process a batch.

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

Override the auto-detected pixel size with --pixel-size:

spritefusion-pixel-snapper input.png output.png --pixel-size 8
spritefusion-pixel-snapper sprites/batch_inputs sprites/batch_outputs 16 --pixel-size 8

This is useful when the auto-detection doesn't match the expected grid size. The value must be between 1 and half the smallest image dimension.

Constrain the output to a fixed palette with --palette, passing comma-separated hex colors:

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

Run spritefusion-pixel-snapper --help to see every option.

Build from source

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

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

🌐 Use it on the Web (WASM)

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

Build the WASM module:

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

Then use the WASM module in your project:

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");

Pass null for any optional argument you want to leave on its default behavior.

Acknowledgments

Pixel Snapper is a Sprite Fusion project. Sprite Fusion is a tool to generate TRUE pixel art sprites and animations for game development.

License

MIT License Hugo Duprez