Pixel Snapper

Recover the underlying low-resolution pixel grid from images that look like pixel art but are stored at high resolution with anti-aliased/smudged edges (e.g. a 1024×1024 AI-generated character that conceptually has ~100×100 chunky pixels).

scripts/pixel-snapper.mjs is a Node port of an MIT-licensed Rust implementation (see references/credits.md), dimensionally identical to upstream. scripts/pixel-snapper-sheet.mjs is a known-layout spritesheet helper: crops frames, snaps them together as one strip so every frame shares a single pixel grid, reassembles.

Discover, Don't Resize

Naive downscale (Lanczos/bilinear/nearest) averages neighbors → blur or aliasing. Snapping instead discovers where the conceptual pixel boundaries already exist and snaps to them. Output resolution is a property of the input, not a parameter.

Before running, ask:

• Is this genuinely upscaled/AI-faked pixel art, or a photo / continuous-tone illustration? (Snapping only fits the former.)
• Palette complexity? Bright cartoony art tolerates --k-colors 256; pre-quantized retro palettes may want a smaller k (16, 32, 64).
• Native snapped output, or a nearest-neighbour upscale for inspection? Usually you want both.
• Are the cells actually square? The snapper assumes one shared cell pitch for both axes.

Core principles: output resolution is discovered, not specified · k_colors is the only user-facing knob (other tunables live in DEFAULT_SNAP_CONFIG) · always inspect the output by eye — dimensions are a sanity check, not a quality check · keep the source PNG so you can re-snap with a different k_colors later · key the background out before snapping — a wide flat matte gives the walker nothing but its own edges to lock onto, and the recovered "grid" collapses to a handful of pixels · snapping needs resolution to find the grid — feed it a large source (≥~512px across the subject; a lone character ~1024²). Undersized inputs (256²) blur the grid away or trip the 64×64 fallback; the fix is to regenerate larger, not to upscale a small source first.