ComfyUI-PixelArt-Unfaker

ComfyUI Pixel Art Unfaker

A custom node for ComfyUI that transforms "fake" or blurry AI-generated pixel art into true, crisp pixel art: one pixel per art pixel, aligned to the grid, with a limited palette and a transparent background.

Based on the algorithm from unfake.js and inspired by the early adaptation ComfyUI-Unfake-Pixels.

Features

• Exact Target Resolution: Get exactly 32x32, 64x64, 48x32... Works with any input size, even when the "big pixels" of the AI image are not a whole number of real pixels, without stretching or half-pixels.
• Grid Alignment: The sampling grid is snapped to the edges of the art, so every output pixel reads the center of an art pixel.
• Edge-Aware Scale Detection: Leave the target size at 0 to auto-detect the pixel size of clean, upscaled pixel art.
• Smart Background Removal: Detects the background color from the image border and removes only the regions connected to it, so similar colors inside the sprite are kept.
• Color Quantization: Reduces the palette (median cut + k-means). Transparent pixels never waste palette slots.
• Similar Color Merging: Merges the near-identical shades that AI noise creates, so flat areas come out flat instead of speckled.
• Optional Stray Pixel Cleanup: Removes isolated noise pixels without introducing new colors (off by default).
• Batch Support: Process animation frames in one go. The pixel size detected on the first frame is reused for the rest.
• Ready-to-save outputs: Real-size image (with alpha), a nearest-neighbor upscaled copy, the transparency mask and a JSON manifest with the detected grid and palette.

Installation

ComfyUI Manager: search for Pixel Art Unfaker and install.

Manual:

cd ComfyUI/custom_nodes/
git clone https://github.com/CalaKuad1/ComfyUI-PixelArt-Unfaker.git
cd ComfyUI-PixelArt-Unfaker
pip install -r requirements.txt

(Windows portable: ..\..\..\python_embeded\python.exe -m pip install -r requirements.txt)

Restart ComfyUI. The node is in image/postprocessing as Unfake Pixel Art (AI to Real).

Quick start (example workflow)

1. In ComfyUI open Workflow → Browse Templates, choose ComfyUI-PixelArt-Unfaker → unfake_pixel_art_basic. (Or drag example_workflows/unfake_pixel_art_basic.json onto the canvas.)
2. Copy example_workflows/unfake_example_input.jpg into ComfyUI/input/, or load your own image in Load Image.
3. Press Run (called Queue in older ComfyUI versions). You get the real 32x32 sprite and a 16x upscaled copy in ComfyUI/output/pixelart/.

It also works right after a KSampler / VAE Decode: plug the decoded image into the node.

Tips

• Which target size? Count the "big pixels" across the AI image (or guess: most AI pixel art is drawn as 32, 48, 64 or 128 pixels wide) and use that as target_width. Set target_height to 0 to keep the aspect ratio.
• Leftover background around the sprite: raise background_tolerance (20–40 for noisy / JPEG images).
• Speckled / blotchy areas: raise merge_similar_colors (30–40). If subtle shading disappears, lower it.
• Still noisy: try downscale_method = dominant.
• cleanup_jaggies is off by default because it can remove intentional 1-pixel details (eyes, highlights). Turn it on only if there are lone stray pixels left.
• No target size at all: set both targets to 0 (auto-detect) or set manual_scale_factor to the size of one art pixel. Auto-detection works on integer upscales; for AI images, a target size is more reliable.

How it works

1. Background removal: the background color is estimated from the image border and the regions connected to the border are made transparent.
2. Grid size: taken from the target size, from manual_scale_factor, or auto-detected from the spacing of the edges in the image.
3. Grid alignment: the grid is shifted so its lines fall on the edges of the art.
4. Downscale: one output pixel per grid cell (nearest or dominant color).
5. Quantization: the opaque pixels are reduced to at most max_colors colors, then near-identical colors are merged.
6. Cleanup (optional): isolated stray pixels are replaced with the color of their neighbors.

Node Parameters

| Parameter | Description | |---|---| | target_width / target_height | Exact output size in art pixels. One of them 0 = keep aspect ratio. Both 0 = use manual_scale_factor or auto-detect. | | manual_scale_factor | Size of one art pixel in input pixels (e.g. 16 turns 1024 into 64). 0 = auto-detect. | | remove_background | Make the border-connected background transparent. | | background_tolerance | Max per-channel difference (0–255) from the background color. | | max_colors | Maximum palette size. 0 = keep all colors. | | cleanup_jaggies | Replace isolated stray pixels with their neighbors' color. Off by default. | | downscale_method | nearest: center pixel of each cell (cleanest in most cases). dominant: most common color of each cell (for very noisy images). | | scale_detection_method, ea_* | Tuning for auto-detection (tile grid, minimum edge distance, edge strength). | | upscale_preview_factor | Upscale for the node preview and the upscaled_image output (capped at 4096px). | | fit_mode | When the aspect ratio differs from the target: crop (fill and cut), pad (fit with transparent borders) or stretch. | | merge_similar_colors | Merge palette colors closer than this RGB distance (default 24). Removes noise shades; 0 = off. |

Outputs

| Output | Description | |---|---| | pixel_art_image | Real-size pixel art. RGBA when the background is removed or padding is added, RGB otherwise. | | manifest | JSON with the pixel size, grid offset, output size and palette (hex). | | mask | Transparent area in ComfyUI convention (1 = transparent, same as Load Image). | | upscaled_image | Nearest-neighbor upscaled copy, ready to save or preview. |

Changelog

1.1.0

• Example workflow and example image (Browse Templates).
• Exact target sizes without stretching, new fit_mode (crop / pad / stretch).
• Batch support, new mask and upscaled_image outputs, JSON manifest.
• Better grid alignment, background removal and dominant downscale on noisy AI images.
• Quantization ignores transparent pixels; new merge_similar_colors removes noise shades.
• cleanup_jaggies is now off by default and never adds new colors.
• No more scikit-learn dependency; much faster processing.

1.0.0

• First release.

Credits & Acknowledgements

• jenissimo for the original unfake.js library and algorithm.
• tauraloke for ComfyUI-Unfake-Pixels, the foundational inspiration for bringing this into ComfyUI.

License

MIT License