菜单
Recover the true low-resolution pixel grid from upscaled or AI-generated fake pixel art PNGs. Use for snap-to-grid cleanup, native-resolution sprite assets, palette-quantized game art, and known-layout spritesheets. Bundles self-contained uv Python scripts.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| name | pixel-snapper |
| description | Recover the true low-resolution pixel grid from upscaled or AI-generated fake pixel art PNGs. Use for snap-to-grid cleanup, native-resolution sprite assets, palette-quantized game art, and known-layout spritesheets. Bundles self-contained uv Python scripts. |
| metadata | {"short-description":"Recover native pixel grids from fake pixel art."} |
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.py is a Python port of an MIT-licensed Rust implementation (see references/credits.md), dimensionally identical to upstream, run as a uv self-contained script. scripts/pixel_snapper_sheet.py is a known-layout spritesheet helper: crops frames, snaps them together as one strip so every frame shares a single pixel grid, reassembles.
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:
--k-colors 256; pre-quantized retro palettes may want a smaller k (16, 32, 64).Core principles: output resolution is discovered, not specified · k_colors is the only user-facing knob (other tunables live in the Config dataclass) · 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 · 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.
Use when the user has AI-generated "pixel art" (gpt-image, retro-diffusion, etc.) and wants a cleaner/smaller/palette-quantized version, needs a high-res mockup converted to a true pixel-art asset, wants to recover an upscaled retro asset's grid, or mentions "snap to pixel grid", "fake pixel art", "downsample to native res", or the Hugo-Dz repo.
Skip for: photographs / continuous-tone / vector art (no grid to recover); already-native pixel art (would just round-trip, possibly losing detail); spritesheet layout recovery where rows/cols are unknown (probe first — pixel_snapper_sheet.py expects known --cols/--rows).
Self-contained via PEP 723 (numpy + pillow); uv installs deps on first run and caches:
uv run .claude/skills/pixel-snapper/scripts/pixel_snapper.py input.png output.png --k-colors 256
After chmod +x, the shebang #!/usr/bin/env -S uv run --script lets you call it directly:
.claude/skills/pixel-snapper/scripts/pixel_snapper.py input.png output.png --k-colors 256
Output is one snapped PNG at the discovered native resolution. For inspection, follow up with an integer nearest-neighbour upscale via ffmpeg:
ffmpeg -y -i snapped.png -vf "scale=iw*8:ih*8:flags=neighbor" snapped-x8.png
For a known-layout spritesheet, snap every frame to one shared pixel grid:
uv run .claude/skills/pixel-snapper/scripts/pixel_snapper_sheet.py \
sheet.png sheet-snapped.png --cols 6 --rows 1 --k-colors 256
See references/usage-examples.md for batch processing and verification recipes.
k_colors — start 256 for AI renders; for quantized retro art try 16, 32, 64 ascending until detail survives without noise.iw*8 nearest-neighbour upscale.k_colors (halve/double); non-square cells (snapper picks the smaller pitch → may need pre-resize); exactly 64×64 output = step-detection fallback fired (input may lack detectable pixel structure).experiments/, never directly into public/assets/. Promote only after visual approval.DO NOT treat snapping as a mandatory cleanup step for every asset — use it only when the input has a recoverable pixel grid.
k_colors=16 on vibrant AI renders — crushes detail. Default to 256 for AI sources; drop only if output looks noisy.--width/--height by design. Snap first (recover native), then nearest-neighbour upscale to a multiple; don't snap-and-resize in one step.public/assets/ — save to experiments/<timestamp>-pixel-snapper-<subject>/, promote after review.Don't run the same parameters on every input.
k_colors to palette complexity — a 16-color NES-style file doesn't need 256; an AI render with smooth shading may lose definition at 16.k_colors (logos low, character medium, tile high).k_colors and re-run from source.references/algorithm.md — pipeline walkthrough (quantize → profile → step-size → walk → resample)references/credits.md — MIT license + attributionreferences/usage-examples.md — invocation patterns + inspection recipesThe snapper does one thing well: recover a hidden pixel grid. It's not a general downscaler, asset cleaner, or palette converter for arbitrary art. When the input fits — upscaled/AI-faked pixel art — it produces what a human pixel artist would have drawn. When it doesn't, no parameter tuning will save you; use a different tool.
Use the `vg generate` CLI to search, inspect, run, and manage 1200+ generative model endpoints. Trigger when the user asks to "generate an image", "make a video", "search models", "run a model", "fetch schema", "check pricing", "upload an asset", "queue async job", "track request", or any direct interaction with the model endpoint catalog. This is the foundational skill. Every other media skill in this repo executes its work through `vg generate` commands. Use `--json` whenever the output will be parsed by an agent.
Build 3D browser apps AND games with Three.js (r150+, ES modules): scene setup, geometries, materials, lighting, animation, GLTF models, physics (Rapier/cannon-es/arcade), character controllers, follow/third-person cameras, fixed-timestep loops, post-processing, and performance/debugging. Use for 'create a three.js scene/app/showcase', any 3D web content, and turning a scene into a game — 'add physics to my three.js game', 'third-person/character controller', 'follow camera', 'jump and gravity', 'collide with / pick up objects', 'structure my 3d game'. Trigger: threejs, three.js, 3D scene, WebGL scene, GLTF/GLB, OrbitControls, Rapier, cannon-es, 3D game, third-person controller. For 2D games use `phaser`; for engine-agnostic feel/balance/level craft use the game-craft skills.
Turn a character anchor into an engine-loadable animated spritesheet by generating ONE labeled pose-board image (a grid of the same character in the frames of an action) and slicing it. Works for any action — idle, run, jump, attack, hurt, crouch, death, roll. Generates a per-frame-labeled pose board on a flat chroma matte, recovers/slices the frames, keys + despills, snaps to crisp native pixels, normalizes with headroom, and packs spritesheet.png + a manifest. Triggers: 'sprite animation', 'animated spritesheet', 'attack animation', 'walk/run cycle', 'animate this character', 'game sprite animation', 'sprite pose sheet'.
Interview the user relentlessly about the game they want to make until the idea is build-ready, resolving each branch of the design tree one question at a time. Use when the user has a fuzzy or one-line game idea and wants to flesh it out before building: 'grill me about my game', 'help me figure out what game to make', 'stress-test my game idea', 'interview me about the game', 'I want to make a game but I'm not sure what'. Not for when the user already knows what they want built — go straight to game-playbook.
Build and ship Three.js apps on Capacitor iOS with Vite and Swift Package Manager: GLTF loading, assets_index animation UI, OrbitControls mouse/touch mappings, and iOS sync/run troubleshooting.
Build 2D browser games with Phaser 4: scene lifecycle, sprites, Arcade/Matter physics, tilemaps, WebGL rendering, filters, lighting, shaders, DynamicTexture/RenderTexture, SpriteGPULayer, TilemapGPULayer, and Phaser 3 to 4 migration. Trigger: phaser, phaser 4, phaser v4, create phaser game, add phaser scene, phaser sprite, phaser physics, phaser tilemap, phaser arcade, phaser webgl renderer, phaser filters, phaser SpriteGPULayer, phaser TilemapGPULayer, migrate phaser 3 to 4.