Fast, zero-dependency image pixelation library. Works in browser and Node.js.

Most pixel art you find online is broken — scaled up with blurry interpolation, anti-aliased edges, and misaligned grids. snap() automatically detects the original pixel grid and rebuilds it with perfectly uniform cells.

As of 1.2.0, repeated snap() runs stay stable on already-clean images and square canvases no longer drift into mismatched X/Y grids.

Recent regression examples:

Before (blurry, misaligned)	After (clean, uniform)	After + Grid overlay

How it works:

1. K-means++ color quantization — reduces noise to make grid edges detectable
2. Edge profile analysis — scans horizontal & vertical color boundaries
3. Periodicity detection — recovers the repeating cell size even when visible boundaries are sparse
4. Lattice regularization — rebuilds a globally uniform grid instead of letting local cut drift accumulate
5. Majority-vote resampling — picks the dominant color per cell
6. Uniform re-rendering — every cell gets the exact same pixel size

No manual resolution input needed. The grid is auto-detected.

Input quality note

snap() works best when the source image really came from a low-resolution square grid that was later scaled up.

ChatGPT-generated "pixel art" often bakes the inconsistency into the source image itself: some cells are already wider, taller, softer, or slightly off-axis before snap() ever sees them. In those cases snap() can regularize the output and force it back onto a square lattice, but it cannot perfectly recover information that was never on a clean grid to begin with, so quality is not guaranteed.

If you are generating new source images specifically for snap(), prefer Nano Banana or any workflow that preserves a true square low-res lattice from the start.

import { snap } from 'fast-pixelizer'

const result = snap(imageData)
// → { data, width, height, detectedResolution, colCuts, rowCuts }

	Original	clean	detail
32×32
64×64

clean — picks the most frequent color in each cell. Sharp, graphic pixel art look.

detail — averages all colors in each cell. Smoother gradients, more texture.

import { pixelate } from 'fast-pixelizer'

const result = pixelate(imageData, { resolution: 32 })

npm install fast-pixelizer

The input accepts a browser ImageData, a node-canvas image data object, or any plain { data: Uint8ClampedArray, width: number, height: number }.

import { pixelate, snap } from 'fast-pixelizer'

const canvas = document.querySelector('canvas')
const ctx = canvas.getContext('2d')
ctx.drawImage(myImage, 0, 0)

const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height)

// Generate pixel art
const result = pixelate(imageData, { resolution: 32 })

// Or repair existing pixel art
const repaired = snap(imageData)

// Draw back
const out = new ImageData(result.data, result.width, result.height)
ctx.putImageData(out, 0, 0)

import sharp from 'sharp'
import { pixelate, snap } from 'fast-pixelizer'

const { data, info } = await sharp('./photo.png')
  .ensureAlpha()
  .raw()
  .toBuffer({ resolveWithObject: true })

const input = {
  data: new Uint8ClampedArray(data.buffer),
  width: info.width,
  height: info.height,
}

// Generate pixel art
const result = pixelate(input, { resolution: 32 })

// Or repair existing pixel art
const repaired = snap(input, { colorVariety: 64 })

await sharp(Buffer.from(result.data), {
  raw: { width: result.width, height: result.height, channels: 4 },
})
  .png()
  .toFile('./output.png')

Detects the pixel grid in existing pixel art and re-snaps it to a clean, uniform grid.

interface SnapResult {
  data: Uint8ClampedArray
  width: number
  height: number
  detectedResolution: number // auto-detected grid size
  colCuts: number[] // column boundaries (for grid overlay)
  rowCuts: number[] // row boundaries (for grid overlay)
}

interface ImageLike {
  data: Uint8ClampedArray
  width: number
  height: number
}

Compatible with the browser's built-in ImageData, node-canvas, and raw pixel buffers.

interface PixelateResult {
  data: Uint8ClampedArray
  width: number
  height: number
}

// Snap: auto-detect grid and repair
snap(img)
snap(img, { colorVariety: 64, output: 'resized' })

// Pixelate: generate pixel art
pixelate(img, { resolution: 32 })
pixelate(img, { resolution: 64, mode: 'detail', output: 'resized' })

Clone the repo and run the library against the sample image to see the output yourself:

git clone https://github.com/handsupmin/fast-pixelizer.git
cd fast-pixelizer
npm install
npm run examples

Output images will be written to examples/. Replace docs/original.png with any image to try your own.

• pixelate: pre-allocated Uint16Array(32768) bucket table — no Map, no per-call heap allocations.
• snap: K-means++ quantization + periodicity-guided grid recovery. Heavier than pixelate but still fast enough for real-time use.
• Cell boundaries use Math.round to eliminate pixel gaps and overlaps between adjacent cells.
• Both functions iterate in row-major order for CPU cache locality.
• Zero runtime dependencies.

For large images, run inside a Worker to keep the main thread unblocked:

// pixelate.worker.ts
import { pixelate, snap } from 'fast-pixelizer'

self.onmessage = (e) => {
  const { input, options, mode } = e.data
  const result = mode === 'snap' ? snap(input, options) : pixelate(input, options)
  self.postMessage(result, [result.data.buffer]) // transfer buffer, no copy
}

// main thread
const worker = new Worker(new URL('./pixelate.worker.ts', import.meta.url), { type: 'module' })
worker.postMessage({ input, options, mode: 'snap' }, [input.data.buffer])
worker.onmessage = (e) => console.log(e.data) // SnapResult or PixelateResult

Contributions are welcome! See CONTRIBUTING.md.

MIT