🎨PixelArt Palette Converter

This is the flagship node of the ComfyUI PixelArt Detector pack: take any image, drop it onto a retro palette, and make the result actually look like it was drawn for a 1989 console instead of just "tinted with a color filter." A naive palette swap maps every pixel to its nearest palette color, which produces posterized noise and muddy bands. The Converter gets around that the way real games did - with color reduction, dithering, and cleanup, and it gives you knobs for all three.

What's under the hood

The node is based on Astropulse's pixeldetector code. The pipeline is: optionally resize → optionally reduce colors (with a choice of clustering algorithms) → swap to the target palette → optionally clean up rare colors → optionally dither. Resizing is smart about order: if your input is smaller than the target, it upscales before pixelizing; if it's bigger, it downscales after quantization. Set both W and H to 0 and resize is skipped entirely.

The palette swap itself uses Pillow's Image.quantize, which maps each pixel to the nearest color in the target palette - and the dither options (floyd-steinberg, or ordered bayer-2/4/8/16) fake intermediate shades with checkerboard patterns so gradients don't band.

The inputs that matter

This node has a lot of inputs, but you can ignore most of them at first. The ones you'll actually set:

• palette - the embedded pick: NES or GAMEBOY. If you want the 50+ lospec palettes, that's the paletteList input from the Palette Loader or Palette Generator instead.
• paletteList (optional) - a LIST of palettes. When it has more than one entry, the node renders a comparison grid of your image under every palette. Great for picking.
• pixelize - the swap algorithm. Image.quantize is the fast default; Grid.pixelate scans pixel-by-pixel and is slow; NP.quantize is a NumPy-based variant that's also slower.
• reduce_colors_before_palette_swap - off by default. Flip it on to cut the image to reduce_colors_max_colors before the palette swap, which gives the final result far less banding. This is the biggest quality lever in the node.
• reduce_colors_method - which clustering does the reduction. Image.quantize (fast), OpenCV.kmeans (slow but picks good centers, with RANDOM_CENTERS vs the more consistent PP_CENTERS), or the pyclustering kmeans/kmedians.
• dither - none or one of the ordered/Floyd-Steinberg options. A little bayer dither is what sells the "Game Boy photo" look.
• cleanup_colors + cleanup_pixels_threshold - after swapping, deletes colors that cover less than the threshold fraction of the image. Good values are 0.01–0.05; lower threshold = more colors kept.

There's also image_quantize_reduce_method (MAXCOVERAGE is the author's recommendation for pixel art) and a pile of OpenCV/pyclustering tuning knobs. Leave those alone until you're chasing a specific look.

Output is a single IMAGE list - wire it to a Preview or Save node. Hook reduce_colors_before_palette_swap on, set the palette, pick a small bayer dither, and you're 80% of the way to a convincing conversion.

Installing the pack

This node ships in dimtoneff/ComfyUI-PixelArt-Detector. Install via ComfyUI Manager (search "ComfyUI PixelArt Detector") or:

cd ComfyUI/custom_nodes
git clone https://github.com/dimtoneff/ComfyUI-PixelArt-Detector

Restart ComfyUI. On first load it auto-installs opencv-python, scipy, pyclustering, Pillow and numpy. pyclustering is the fragile one - it has no wheels for newer Pythons, so the pack pulls a prebuilt wheel from the author's releases at startup. On x86_64 it just works; on Apple Silicon or unusual Python builds it may fail and you'll need to install it manually.

Gotchas

• Bayer dither on a huge image is slow - it's per-pixel math. Downscale first.
• Grid.pixelate with scan size 1 is brutally slow - it's pixel-by-pixel. The author says increasing the size speeds it up but kills quality; the other two methods are better defaults.
• The embedded NES/GAMEBOY palettes only appear if you don't feed a paletteList. Wire a Loader in and the dropdown is ignored.
• Old nodes embedded in workflows won't update in place - delete and re-add from the Image/PixelArt menu.
• The opencv_settings and cleanup string widgets are just help text. Ignore them; the real toggles are the booleans below them.