perfect-pixel

The algorithm refines AI-generated pixel art through a three-step process:

1. Grid Detection: Detects grid size from the FFT (Fast Fourier Transform) magnitude of the original image and generates initial grids.
2. Edge Refinement: Detects edges using Sobel operators and refines the grids by aligning them to those edges.
3. Sampling: Uses the refined grids to sample the original image and produce the final scaled, pixel-perfect image.

Perfect Pixel offers two installation options depending on your environment and performance needs:

1. OpenCV Backend (Recommended): Provides better performance. Requires opencv-python and numpy.
2. Lightweight Backend: Use this if you cannot or do not want to use cv2. Requires only numpy.

Install the recommended fast version using the [opencv] extra:

# Recommended: Fast version with OpenCV support
pip install perfect-pixel[opencv]

# Numpy version: Lightweight (NumPy only)
pip install perfect-pixel

On Windows, ComfyUI often uses an embedded Python environment. Installing packages via your system's pip will not make them available to ComfyUI. You must use the specific Python executable used by ComfyUI.

Step 1: Find the ComfyUI Python executable

Start ComfyUI and check the terminal startup log. Look for the line starting with ** Python executable:.

Step 2: Install using that executable

Open a terminal and use the path found in Step 1 to run pip commands.

Example for Windows portable builds:

G:\ComfyUI\ComfyUI_windows_portable\python_embeded\python.exe -m pip install -U pip
G:\ComfyUI\ComfyUI_windows_portable\python_embeded\python.exe -m pip install "perfect-pixel[opencv]"

General Command Template:

[path_to_your_ComfyUI_python]\python.exe -m pip install "perfect-pixel[opencv]"

When calling get_perfect_pixel, you can specify how pixels are sampled from the detected grid cells using the sample_method parameter:

1. "center": The simplest method. It calculates the geometric center of each grid cell and samples the pixel at that coordinate. This is fast but may not represent the cell's color well if the center pixel is an outlier.
2. "median": Calculates the median color of all pixels within the cell. This is robust against noise and outliers.
3. "majority": The most advanced method. It uses K-means clustering (with $K=2$) on the pixels within the cell and selects the cluster center that contains the most pixels. This is highly effective for capturing the dominant color in a cell.

The library uses two main strategies to estimate the underlying grid scale of an image:

• FFT-based estimation (estimate_grid_fft): Uses Fast Fourier Transform to find periodic patterns in the image frequency domain. This is generally the first attempt.
• Gradient-based estimation (estimate_grid_gradient): If FFT fails or produces inconsistent results, the system falls back to analyzing the magnitude of Sobel gradients to find periodic peaks in edge density.

If both methods fail, the function returns None, None and the original image is returned by the main entrypoint.

When scaling an image to a new grid, the get_perfect_pixel function uses one of three sampling strategies to determine the color of the new pixels:

1. "center": Samples the color from the geometric center of the grid cell. This is the fastest method.
2. "median": Calculates the median color of all pixels within the grid cell. This is robust to outliers.
3. "majority": Uses an iterative approach to find the most representative color (mode-like) within the cell. This is generally the most accurate for preserving textures but is more computationally intensive.

The get_perfect_pixel function automatically detects the optimal grid size from a pixel-style image and returns a refined, perfectly aligned version.

Input should be an RGB image. The function returns the refined width, refined height, and the refined image itself.

import cv2
from perfect_pixel import get_perfect_pixel

bgr = cv2.imread("images/avatar.png", cv2.IMREAD_COLOR)
rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)

w, h, out = get_perfect_pixel(rgb)

The node requires the following Python packages:

• numpy (Required)
• opencv-python (Optional, but required if using the OpenCV Backend for better performance)

To install them manually in a standard environment:

pip install numpy
pip install opencv-python

The Perfect Pixel (Grid Restore) node provides the following parameters:

• sampling: The sampling method used when restoring pixel grids.
• export_scale: The scaling factor applied to the output image.
• backend: Determines the implementation used for processing:
  • Auto: Automatically selects the best available backend.
  • OpenCV Backend: Uses OpenCV for higher performance.
  • Lightweight Backend: Uses a NumPy-only implementation (no OpenCV required).