自动转化为真像素节点

True Pixel

简体中文 · English

A ComfyUI node pair that converts pseudo pixel art produced by diffusion models into true pixel art.

Processing runs in three steps. The node first estimates the pixel block size of the image, then divides the image into a grid of that size, and finally selects one color for each cell. Every output pixel aligns exactly to the grid, with sharp boundaries and none of the transition colors left by anti-aliasing or the noise left by the diffusion process.

The problem

A pixel-art LoRA usually produces an image one to two thousand pixels wide, where each apparent "pixel" is a block of real pixels scaled up. Inspection at full resolution reveals three defects: transition colors along block edges from anti-aliasing, residual noise inside each block from the diffusion process, and block boundaries that drift by half a cell in some regions. Downscaling such an image produces a blurry thumbnail rather than clean pixel art.

This node resamples the image along the grid and removes all three defects at once.

Result

Three columns, top row full image and bottom row a magnified detail. The left column is the original 2560 px generation, the middle column a plain bilinear downscale to 128 px, and the right column the output of this node. The detector reports a block size of 20 px, which divides the image into a 128 × 128 grid.

Nodes

Ruivo Pixel Grid Detect

Detection only. The image passes through unchanged. Use it to inspect the grid before wiring the block size into Ruivo Pixel Snap.

| Output | Meaning | | --- | --- | | block_size | pixel block edge length | | offset_x, offset_y | grid phase, the origin of the first cell | | confidence | prominence score; below 1.6 the evidence is insufficient | | report | human-readable summary including the cell count |

Ruivo Pixel Snap

Resamples along the grid and returns the pixel image.

| Parameter | Default | Meaning | | --- | --- | --- | | image | | input image | | block_size | 0 | block edge length; 0 enables detection | | reduce | mode | per-cell reduction, see below | | merge | 3 | color merge threshold; differences at or below this value are merged, 0 disables | | output_scale | 1 | 1 returns the small image, N upscales by N with nearest neighbor | | palette | 0 | palette size cap, 0 means unlimited | | offset_x, offset_y | -1 | grid phase, -1 computes it automatically |

Reduction modes:

| Value | Method | When to use | | --- | --- | --- | | mode | most frequent color in the cell | default, closest to how pixel art is drawn by hand | | median | per-channel median | more reliable when noise is heavy | | mean | arithmetic mean | preserves the original tonality, edges soften slightly | | center | center half of the cell only | use when anti-aliasing along cell edges is severe |

merge suppresses false colors introduced by diffusion noise. The default of 3 produces no visible change while cutting the color count by roughly an order of magnitude. Hand-drawn pixel art typically uses 32 to 64 colors. To enforce a strict palette, set palette to the target size; values below 16 visibly damage detail in eyes and hair.

Installation

Place the folder inside the custom_nodes directory of ComfyUI and restart. The nodes appear under the image/pixel category.

The only dependencies are numpy and Pillow, both already present in a ComfyUI environment.

How detection works

For a candidate period s and grid phase, the image is divided into s × s cells, and two quantities are measured:

• Intra-cell standard deviation: the color spread inside a single cell. When the grid is correct every cell falls inside a uniform region, so this value approaches the noise floor.
• Neighboring cell difference: the mean difference between cells that are adjacent horizontally or vertically. When the grid is correct adjacent cells belong to different colors, so this value is large.

The ratio of the two peaks at the correct period. The ratio rules out both failure modes at once. When s is too small, a large share of adjacent cell pairs fall inside one real block and the difference is diluted. When s is too large, cells absorb their neighbors and the intra-cell deviation rises.

The ratio alone is not sufficient. Occasional periods score slightly high by chance, so a second filter measures prominence: the ratio of a candidate compared with the median ratio of its neighboring periods. A real period stands out as an isolated spike.

On a batch of 2560 px LoRA outputs, correct periods score between 2.1 and 3.4, while noise periods sit near 1.1.

Limitations

A real grid must exist. If the block size varies across the image, or the image has been scaled by a non-integer factor, rotated, or perspective-warped, detection fails. Ruivo Pixel Snap then raises an error stating that the confidence is insufficient rather than proceeding with a wrong block size. Setting block_size manually bypasses detection, though cells that fail to align will still mix colors.

Detecting a 2560 px image takes roughly two to four seconds over a search range of 4 to 128. If the block size is known to be small, lowering max_block on Ruivo Pixel Grid Detect shortens the search.

License

MIT