像素化 / Pixelate

A mosaic filter is a lie. It smears your image into big squares and hands back a same-size JPEG that'll look terrible in an actual game. 像素化 / Pixelate is the honest version: it outputs a genuinely small image with controlled color counts and hard, aliased edges - a sprite you can drop straight into an engine. Pure numpy/PIL, no model, no weights.

The headline feature is the third mode. AI image models love producing "pixel art" at 1024×1024 with a fake grid, anti-aliased edges, and thousands of colors - which is to say, not pixel art at all. The auto grid-detection mode finds the actual pixel grid hidden in the image and reconstructs the true pixel art underneath.

Three modes, three jobs

• 按目标宽度 (target width) - photo or illustration → pixel art. Give it the output width (16/32/48/64 are the classic sprite sizes); height follows the aspect ratio.
• 按像素块大小 (pixel block size) - every N×N source pixels become one output pixel. The precise choice when you know your downscale factor.
• 自动检测网格 (auto-detect grid) - the fake-pixel-art restorer. It scores candidate grids with within-cell variance (not edge diffs, which anti-aliased AI output destroys), kills harmonic octave errors, and checks that the winning period is phase-sensitive - a genuine pixel grid is, a repeating pattern in the content isn't.

The detection is genuinely good on clean upscaled images (27/27 in the README's test, zero octave errors) and roughly two-thirds on heavily blurred "AI pixel" inputs - when it fails, the info output tells you the confidence and you fall back to mode two.

Inputs that matter

• mode / target_width / pixel_size - the three-way choice above.
• downsample - dominant (the block's most common color, never invents new ones) is the pixel-art pick. median resists noise, mean softens edges, center is the sharpest but noisiest.
• palette - the style lever. Adaptive k-means in CIELAB space (quality) or median cut (speed), or fixed retro palettes: PICO-8 16-color, Game Boy 4-green, 1-bit black & white, and 4/8/16-level greys.
• palette_size - 8–16 for that strong retro look, 32–64 to keep detail.
• dither - Bayer (regular dot pattern, very retro, tiles well), Floyd-Steinberg (smoothest), or off. Hand-drawn style usually wants none.
• output_scale - the one that will bite you. 1 = true pixel size, and that's what you export. Anything above 1 is nearest-neighbor upscaling just so you can see the result in the ComfyUI preview - export before you forget and get a 32× sprite inflated to 512.

Outputs: image, plus mask (the pixelated alpha if you fed one in) and info (detected grid size, phase, and confidence).

The workflow that makes sense of it

The intended pairing is matting → pixelate. Wire a Lucida/FeyNobg alpha into the optional mask input and it downsamples the alpha on the same grid and binarizes it to a hard edge - which is exactly what a sprite's transparency needs. If you're pixelating a cutout, always feed the mask; a soft matte edge does not survive palette quantization gracefully.