⚠️ COPYRIGHT NOTICE & DISCLAIMER ⚠️ The core algorithm files (perfect_pixel.py and perfect_pixel_noCV2.py) in this repository are strictly the intellectual property of [theamusing]. Currently, the original repository does not have an explicit open-source license. This repository is created entirely out of respect for the author's brilliant work and solely to provide a ComfyUI wrapper interface for the community. I claim no ownership over the underlying grid-detection and pixel-refinement algorithms. If the original author wishes for this wrapper to be taken down, I will comply immediately.

Original Repository: https://github.com/theamusing/perfectPixel

A ComfyUI custom node that refines and quantizes messy AI-generated pixel art into clean, perfect, and grid-aligned pixels.

This is a perfect node wrapper for the theamusing/perfectPixel algorithm in ComfyUI. It is specifically designed to fix "pseudo-pixel" issues in AI-generated pixel art, such as blurry edges, misaligned grids, and color noise.

✨ Features

Auto Grid Detection: Automatically calculates the original grid of the pixel art using FFT and gradient detection.
Majority/Center Sampling: Eliminates gradients and color noise, restoring the purest pixel blocks.
Dual Backend: Supports automatic switching between a high-performance OpenCV backend and a lightweight pure NumPy backend.
Nearest Scaling: Automatically uses nearest-neighbor interpolation to losslessly upscale the processed result back to high-definition.

🖼️ Showcase

Before (AI-Generated Pseudo-Pixels)	After (Refined by Perfect Pixel)

⚙️ Installation

Navigate to your ComfyUI custom_nodes directory.
Run the command: git clone https://github.com/AchengOoO/ComfyUI-PerfectPixel.git
Enter the cloned folder and run pip install -r requirements.txt to install the OpenCV dependencies.
Restart ComfyUI.

🤝 Credits

Core algorithm is created by theamusing/perfectPixel.

🛠️ Usage

After loading the node in ComfyUI, follow these steps to connect and configure it:

Add the Node: Double-click the canvas and search for PerfectPixel, or find it in the right-click menu under image/postprocessing.
Connect the Image: Connect your AI-generated pixel art (with noise or blurry edges) to the image input.
Configure Parameters:
- sampling:
  - Majority Cluster (Recommended): Uses K-Means clustering to perfectly eliminate noise and transitional colors within the grid.
  - Center Sample: Directly extracts the center pixel of the grid. This is the fastest method.
- export_scale: The default value is 4. Since the algorithm extracts a very small, pure pixel grid (e.g., 64x64), this parameter automatically uses "Nearest-Neighbor" interpolation to losslessly scale it back to a high-definition image (e.g., 256x256), ensuring razor-sharp edges.
- backend: It is highly recommended to manually select the OpenCV Backend to enable C++ underlying acceleration. If OpenCV is not installed in your environment, you can choose the Lightweight Backend.