spritefusion-pixel-snapper 1.0.0

# Sprite Fusion Pixel Snapper

<p align="left">
  <img src="./static/repo_od.png" alt="Sprite Fusion Pixel Snapper is the repository of the day" width="320">
</p>

- **Online version**: https://spritefusion.com/pixel-snapper
- **Desktop version**: https://www.spritefusion.com/pixel-snapper#desktop-edition

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

<img src="./static/hero.png" alt="Pixel Snapper" style="width: 100%; image-rendering: pixelated;">

## 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.

<img src="./static/details.png" alt="Details" style="width: 100%; image-rendering: pixelated;">

<p align="center"><em>Pixel Snapper preserves as much details as possible like dithering.</em></p>

<br>

## 💻 Use it with CLI

Requires [Rust](https://www.rust-lang.org/) installed on your machine.

```bash
cargo install spritefusion-pixel-snapper
```

Process one image:

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

The command accepts an optional k-colors argument:

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

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

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

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

```bash
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:

```bash
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

```bash
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)

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

Build the WASM module:

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

Then use the WASM module in your project:

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

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

## Acknowledgments

Pixel Snapper is a [Sprite Fusion](https://www.spritefusion.com/pixel-art-generator) project. Sprite Fusion is a tool to generate TRUE pixel art sprites and animations for game development.

<img src="./static/spritefusion-generator.webp" alt="Sprite Fusion Pixel Art Generator" style="width: 100%;">

## License

MIT License [Hugo Duprez](https://www.hugoduprez.com/)