ComfyUI-Krea2-Pixel-Art-Refiner Introduction
ComfyUI-Krea2-Pixel-Art-Refiner is a collection of six ComfyUI nodes for cleaning up generated pixel art and consolidating noisy animation frames into clearer, more consistent poses.
AI-generated pixel art can look convincing from a distance while containing uneven blocks, stray colors, or small variations between frames. This extension helps you turn that pixel-art appearance into a more controlled pixel grid and palette.
You can use it to:
- Simplify colors: Reduce unwanted color variations to a limited palette.
- Clean up pixel blocks: Give each logical pixel cell one representative color.
- Recover a pixel grid: Detect a pixel mesh when the source does not follow a perfectly uniform grid.
- Maintain animation consistency: Share palettes across frames and, with the Autorefiner, reuse the first frame’s detected meshes.
- Match a reference palette: Use the colors from a supplied image.
- Combine repeated animation poses: Consolidate noisy held frames from repeated cycles into one image per pose.
The extension includes these nodes:
| Node | Where to find it | Main purpose |
|---|---|---|
| Perceptual Palette Reduce | image/color | Reduce an image to an automatically selected palette. |
| Pixel Grid Collapse | image/transform | Clean up a known, evenly spaced pixel grid. |
| Krea 2 Pixel Art Refiner | image/krea2 | Combine palette reduction and grid collapse with straightforward controls. |
| MiniMax H3 Pixel Art Refiner | image/minimax | Add reference palettes, shared batch palettes, uneven grids, and grid alignment controls. |
| MiniMax H3 Pixel Art Autorefiner | image/minimax | Detect a pixel mesh automatically, including separate regions in directional sprite sheets. |
| Pixel Art Animation Pose Compositor | image/animation | Combine repeated held poses into a clean, ordered image batch. |
These are image-processing nodes, not separate image-generation models. You work with images or decoded video frames inside ComfyUI.
How ComfyUI-Krea2-Pixel-Art-Refiner Works
1. It simplifies colors according to visual similarity
The palette-reduction tools use weighted OKLab clustering.
In everyday terms, this means grouping similar colors using a color space designed to better reflect how people perceive differences. Think of sorting a large box of nearly identical paint shades into a smaller set of useful swatches.
For example, a generated sprite may contain many slightly different blues in an area intended to be one flat blue. Reducing the palette can bring those variations together.
The colors setting controls the maximum palette size:
- A smaller value creates a more restricted look, but may remove subtle shading.
- A larger value retains more color detail, but may leave more unwanted variation.
- The default is 24 colors.
Unless you enable a shared palette or supply a palette image in a supporting node, palette selection is performed separately for each image.
2. It turns each logical pixel cell into one color
A logical pixel is one intended pixel in your final artwork, even if it occupies a large block in the source image.
For example, a 1024 × 1024 image representing a 64 × 64 sprite has logical cells measuring 16 × 16 source pixels.
Instead of averaging everything inside a cell—which could create a muddy intermediate color—the extension selects the most frequent exact 8-bit RGB color.
If several colors are equally frequent:
- It selects the color perceptually closest to the cell’s center pixel in OKLab.
- If that still leaves a tie, it selects the first matching pixel in raster order: left to right, then top to bottom.
This gives the grid-collapse nodes a consistent, deterministic way to resolve ambiguous cells.
3. You can choose whether palette reduction or grid cleanup happens first
The Krea 2 and MiniMax H3 refiners expose color_reduction_first.
- On: Similar colors are grouped before each cell chooses its winning color. This can help when one intended color is split into many small variations.
- Off: Each cell chooses its representative color first, and palette reduction happens afterward.
These operations can produce different results. If outlines or small highlights look wrong, comparing the two orders is a useful adjustment.
4. Automatic refinement detects boundaries instead of assuming a perfect grid
The MiniMax H3 Pixel Art Autorefiner looks for the horizontal and vertical boundaries between apparent pixels.
Its process is similar to laying tracing paper over an image, finding repeated block edges, and using those edges to rebuild the artwork.
It:
- Reduces the image to the requested palette.
- Looks for edges and closes small gaps in them.
- Detects horizontal and vertical lines.
- Estimates the underlying pixel spacing.
- Repairs misleading small cells and fills missing boundaries.
- Collapses each detected cell to one color.
The requested width and height help guide detection and provide a fallback. They are not a guarantee that automatic detection will produce exactly that resolution.
The mesh detector is adapted from Proper Pixel Art. The extension does not use that project’s palette quantizer.
5. Animation cleanup works with repeated evidence
The Pixel Art Animation Pose Compositor treats repeated animation cycles as multiple observations of the same poses.
For example, if a character performs the same six-pose walk cycle several times, each occurrence may contain slightly different noise. The compositor groups matching holds and chooses the most frequent exact RGB value at every pixel.
This is not an in-betweening tool. It produces one composited image per pose, rather than preserving every original frame or its timing.
ComfyUI-Krea2-Pixel-Art-Refiner Features
Perceptual Palette Reduce
Category: image/color
Use this node when you want to simplify colors without changing the image’s pixel grid.
| Setting | Default | What it does |
|---|---|---|
colors | 24 | Maximum palette size, from 2 to 256. |
Each image in a batch receives its own automatically selected palette.
Example: Try a lower value for a deliberately limited sprite palette. Increase it if distinct highlights, shadows, or material colors are being merged.
This node does not, by itself, make uneven pixel blocks line up.
Pixel Grid Collapse
Category: image/transform
Use this node when you already know the intended logical resolution and want to clean up the cells without adding automatic palette reduction.
logical_widthsets the number of cells across the image.logical_heightsets the number of cells down the image.- Each cell receives its most frequent RGB color, using the tie-breaking rules described above.
- The result is expanded back to the input dimensions.
Important: The source dimensions must divide evenly by the logical dimensions.
For example:
1024 × 1024input with a64 × 64grid: valid.1000 × 1000input with a64 × 64grid: not evenly divisible.
Krea 2 Pixel Art Refiner
Category: image/krea2
This is the author’s original focused refiner. It combines palette reduction and grid cleanup in one node.
| Input | Default | How to use it |
|---|---|---|
image | — | Supply a ComfyUI image or image batch. |
width | 64 | Intended number of logical pixels across the image. |
height | 64 | Intended number of logical pixels down the image. |
colors | 24 | Maximum palette size, selected separately for each image. |
color_reduction_first | On | Reduce colors before collapsing cells. Turn off to reverse the order. |
scale_to_original | On | Expand the collapsed grid back to the original image dimensions. |
The source width and height must be evenly divisible by width and height.
Example: With a 1024 × 1024 source and a 64 × 64 logical grid:
scale_to_originalOn returns the cleaned artwork at the source dimensions.scale_to_originalOff returns the logical64 × 64image.
Choose this node when your grid is known and you do not need batch-wide palette controls or automatic alignment.
MiniMax H3 Pixel Art Refiner
Category: image/minimax
This refiner adds controls for batches, video frames, reference palettes, and grids that need alignment adjustments.
| Input | Default | What it does |
|---|---|---|
image | — | Accepts an image, image batch, or video-frame batch. |
width | 64 | Logical grid width. |
height | 64 | Logical grid height. |
colors | 24 | Maximum generated or reduced palette size. |
color_reduction_first | On | Choose whether palette reduction happens before grid collapse. |
scale_to_original | On | Expand the logical grid to the input dimensions. |
allow_uneven_grid | Off | Allow slightly different cell sizes when dimensions do not divide evenly. |
shared_palette | Off | Generate one palette for the entire input batch. |
x_offset | 0.0 | Move the grid right by a fraction of one logical pixel. |
y_offset | 0.0 | Move the grid down by a fraction of one logical pixel. |
auto_offset | Off | Detect grid alignment separately for each image, overriding manual offsets. |
align_palette_lightness | On | Compensate for a batch-wide lightness difference when matching a supplied palette. |
preserve_generated_background | On | Preserve the first image’s upper-left RGB color when using a supplied palette. |
palette_image | Optional | Supply an image whose RGB colors become the shared palette. |
Aligning the grid
Offsets range from 0.0 to 1.0.
For example, x_offset=0.5 moves the grid right by half a logical pixel. This can help when the intended block boundaries fall between the default grid lines.
Offset processing wraps at the outer edges.
With auto_offset enabled, the node searches for the strongest repeating edge alignment independently along the X and Y axes for each image. Flat margins contribute little evidence. If an axis has no detectable repetition, its offset falls back to zero.
Sharing a palette across frames
Enable shared_palette when you want all frames to use one generated palette rather than independently selected palettes.
This helps address a common animation problem: a shirt, outline, or shadow receiving slightly different colors from frame to frame.
It does not consolidate poses or lock the grid phase across frames; those are separate concerns.
Using a palette image
Connect palette_image to constrain matching to colors from a reference image.
- If it contains no more than
colorsunique RGB values, those exact colors are retained. - If it contains more, the palette is perceptually reduced first.
- The supplied palette is used across the batch.
A palette image should contain the colors you actually want available. Extra colors in that image also become palette candidates.
Matching lightness without changing the reference colors
align_palette_lightness estimates one shared OKLab lightness adjustment for the whole batch.
That adjustment is used only during matching. The emitted colors remain exact RGB values from the supplied palette, except for the preserved background when that option is enabled.
Using one adjustment across the batch avoids introducing separate per-frame lightness corrections.
Preserving the generated background
With preserve_generated_background enabled, the first input image’s upper-left RGB color is retained rather than forced into the supplied palette. It is also excluded from lightness-offset estimation.
Disable this setting when you need every output color to belong to the supplied palette.
MiniMax H3 Pixel Art Autorefiner
Category: image/minimax
Use the Autorefiner when the apparent pixel grid is irregular or you want the node to detect it.
| Input | Default | What it does |
|---|---|---|
image | — | Accepts an image, image batch, or video-frame batch. |
width | 64 | Full-frame logical width in manual mode; a detection hint and fallback width otherwise. |
height | 64 | Full-frame logical height in manual mode; a detection hint and fallback height otherwise. |
colors | 24 | Maximum generated or reduced palette size. |
scale_to_original | On | Fit the collapsed frame inside the source dimensions and pad it. |
shared_palette | On | Generate one palette across the input batch. |
manual_resolution | Off | Bypass mesh detection and divide the whole frame into the requested grid. |
direction_count | 1 | Number of fixed regions arranged across the frame, each with independently detected X and Y grids. |
align_palette_lightness | On | Apply shared lightness compensation while matching a supplied palette. |
preserve_generated_background | On | Preserve the first frame’s upper-left color during supplied-palette matching. |
palette_image | Optional | Supply the palette used for every frame. |
How automatic detection uses the requested resolution
The detector looks for a fundamental pixel spacing rather than assuming every observed gap is one pixel wide. This helps prevent a missing boundary from turning two or three intended pixels into one oversized cell.
It also:
- Prefers the spacing implied by the requested resolution when both median and clipped-mean landmark errors are within 20%.
- Can accept clearly larger source pixels.
- Joins pairs of short cells that together resemble one requested pixel.
- Merges other misleading short cells.
- Subdivides remaining gaps locally, allowing variation in pixel spacing.
The requested resolution also limits the smallest allowed pitch and maximum detected grid size.
Directional sprite sheets
Set direction_count to detect separate grids in fixed regions across the image. For example, use 4 for a four-direction sheet arranged horizontally.
width always refers to the complete frame, not one direction region.
For a 2048 × 512 four-view sheet with 16 × 16 source-pixel blocks, the documented manual settings are:
width = 128
height = 32
manual_resolution = On
In automatic mode, each region is enlarged two times internally before edge detection.
Stable meshes across a batch
For image batches, the Autorefiner detects every region’s mesh from the first frame. It then reuses those exact meshes and fixed region bounds for all later frames.
This keeps the processing grid stable instead of redetecting it independently on each frame. Choose a first frame that clearly shows the intended pixel structure.
Unlike the separate Proper Pixel Art tool, this extension does not combine edge evidence from sampled animation frames.
Output sizing and background behavior
The Autorefiner treats the upper-left color as transparent during its reconstruction, then composites the result on white.
- With
scale_to_originalOn, it fits and pads the complete collapsed frame to the source dimensions. - With it Off, independently collapsed regions are padded to a common height and joined horizontally.
Do not expect an alpha-transparent output from this node. Preserving a color during palette matching is separate from the Autorefiner’s final white-background compositing.
Pixel Art Animation Pose Compositor
Category: image/animation
Use this node for ordered animation frames containing held poses and repeated cycles.
A hold is a run of consecutive frames showing approximately the same pose. Several holds in different cycles can belong to the same final pose.
| Input | Default | What it does |
|---|---|---|
images | — | Ordered animation frames, all at the same resolution. |
pose_count | 0 | Automatically detect the cycle length, or enter a positive pose count. |
transition_threshold | 7.0 | Full-frame mean RGB difference needed to start a new hold, measured in 8-bit levels. |
remove_outliers | On | Remove anomalous frames before cycle detection and compositing. |
How poses are grouped
The compositor:
- Rounds RGB channels to 8-bit values.
- Measures the average absolute RGB difference between consecutive frames.
- Starts a new hold when that difference reaches
transition_threshold. - Removes a single transition frame when it separates two strongly matching pieces of the same hold.
- Optionally removes anomalous frames from each hold.
- Assigns holds to poses in repeating cycle order.
- Composites all frames belonging to each pose.
With six poses, holds 1, 7, and 13 contribute to pose 1; holds 2, 8, and 14 contribute to pose 2; and so on.
Automatic pose counting
With pose_count=0, the node compares representative frames from each hold and searches for the shortest unambiguous repeating cycle.
Autodetection requires at least two complete cycles. It can skip an unmatched opening fragment and accepts trailing partial cycles when they follow the detected order.
If the repeating pattern is ambiguous, it asks you to provide an explicit pose count rather than combining unrelated poses.
With an explicit pose count, the input still needs at least one complete cycle. Trailing partial cycles can contribute to the corresponding poses.
Compositing and background cleanup
At each pixel, the compositor selects the most frequent exact RGB value across matching frames.
Ties are resolved by:
- Choosing the lowest Rec.709 luma—the darker candidate.
- Choosing the lowest packed RGB value if brightness is also tied.
Outlier removal compares frames with the hold’s medoid, meaning its most representative existing frame. It recalculates its tolerance after each pass and always retains at least one frame per hold.
Finally, the node floods inward from all image borders through pixels close to the upper-left background color. Border-connected pixels within a 10% RMS RGB distance are replaced with the exact background color. Enclosed near-background pixels are preserved.
The output is an IMAGE batch in animation pose order.
Understanding the transition threshold
In the author’s original 56-frame test:
- Differences within a pose ranged from
0.044to1.978. - Actual transitions ranged from
13.182to29.786. - The default threshold of
7.0separated those groups.
These figures describe that test, not a universal range for all animations. Your artwork may need a different threshold.
Using ComfyUI-Krea2-Pixel-Art-Refiner in a Workflow
For a single image with a known grid
- Send the decoded image to Krea 2 Pixel Art Refiner.
- Set
widthandheightto the intended logical resolution. - Start with
colors=24. - Check whether outlines and small details survive.
- Compare processing orders if necessary.
- Turn off
scale_to_originalif you want the logical-resolution output.
VAE Decode → Krea 2 Pixel Art Refiner → Save Image
For animation frames needing consistent colors
- Send the frame batch to MiniMax H3 Pixel Art Refiner.
- Set the logical grid.
- Enable
shared_palette, or connectpalette_image. - Adjust grid offsets if block boundaries do not align.
- Pass the refined batch to your video-creation node.
VAE Decode → MiniMax H3 Pixel Art Refiner → Create Video
For an irregular grid or repeated animation cycles
Use the Autorefiner when the grid needs detection. Add the Pose Compositor when you also want to consolidate repeated held poses.
VAE Decode
→ MiniMax H3 Pixel Art Autorefiner
→ Pixel Art Animation Pose Compositor
→ Create Video
The compositor reduces the frame batch to one image per pose. Set the playback timing in your downstream animation workflow accordingly.
Troubleshooting ComfyUI-Krea2-Pixel-Art-Refiner
The node reports that the dimensions do not divide evenly
This applies to Pixel Grid Collapse and Krea 2 Pixel Art Refiner.
- Check the input image dimensions.
- Divide the source width by the logical width.
- Divide the source height by the logical height.
- Both results must be whole numbers.
- Choose compatible dimensions, or use MiniMax H3 Pixel Art Refiner with
allow_uneven_gridenabled.
For example, 1024 ÷ 64 = 16, so that axis is compatible.
Outlines look broken or small features disappear
- Confirm that the logical resolution matches the intended artwork.
- Increase
widthandheightif the current cells are combining distinct features. - Increase
colorsif important shades are being merged. - Compare
color_reduction_firstOn and Off. - If cell boundaries appear misplaced, try manual offsets or
auto_offsetin the MiniMax H3 refiner.
A smaller logical grid necessarily retains less spatial detail.
Colors vary between animation frames
- Use a MiniMax node that supports shared palettes.
- Enable
shared_palette, or supplypalette_image. - When matching a supplied palette, keep
align_palette_lightnessenabled if batch-wide brightness compensation is useful. - If the issue is pose noise rather than palette variation, consider the Pose Compositor.
A shared palette standardizes available colors; it does not guarantee identical color placement in every frame.
The output contains a color outside my supplied palette
- Check
preserve_generated_background. - Disable it if you need strict supplied-palette matching.
- If using the Autorefiner, remember that its final compositing step uses white.
For strict palette output without the Autorefiner’s white compositing behavior, use MiniMax H3 Pixel Art Refiner with background preservation disabled.
Automatic grid detection produces unexpected cell sizes
- Set
widthandheightcloser to the expected full-frame logical resolution. - Check
direction_countfor horizontally arranged directional sheets. - For batches, inspect the first frame: it determines all detected meshes.
- Enable
manual_resolutionif you know the exact grid and want to bypass detection.
Automatic detection uses the requested resolution as guidance, so its result can differ from the entered dimensions.
Manual offsets seem to do nothing
- Check whether
auto_offsetis enabled. - Turn it off to use
x_offsetandy_offset. - Try
0.5on one axis to compare a half-cell shift. - Inspect the outer edges, where offset processing wraps.
The compositor cannot detect the pose count
- Confirm that the frames are in animation order.
- Provide at least two complete cycles for automatic detection.
- Check that transitions are being separated appropriately.
- Enter a positive
pose_countif the cycle length is known or automatic matching remains ambiguous. - With an explicit count, ensure there is at least one complete cycle.
The compositor splits one hold into several holds
The transition threshold may be too low for the noise in your frames.
- Increase
transition_thresholdgradually. - Check that real pose changes still create separate holds.
- Leave
remove_outliersenabled while comparing results.
The compositor merges different poses
The threshold may be too high for subtle pose changes.
- Lower
transition_thresholdgradually. - Check whether the desired transitions now create separate holds.
- Verify the expected pose count after hold detection improves.
The difference is measured over the whole image. A small moving detail against a large static background can produce a small average difference.
Frequently asked questions
Which node should I start with?
Use Krea 2 Pixel Art Refiner for a known, evenly divisible grid. Use MiniMax H3 Pixel Art Refiner for palette sharing and alignment controls. Use Autorefiner when you need mesh detection.
Do I have to use every node?
No. Palette reduction, grid collapse, combined refinement, and pose compositing can be used separately as needed.
Does reducing the palette guarantee exactly the requested number of colors?
No. colors is a maximum. Later grid collapse can leave fewer colors, and background-handling options can affect the final set.
Does scale_to_original add detail?
No. It changes the output size, not the amount of logical pixel detail. The Autorefiner also fits and pads its reconstructed output.
Can I use a video directly?
The documented node inputs are ComfyUI images and image batches, including video-frame batches. Decode the video into frames upstream and use a downstream node to create a video.
Does the Pose Compositor preserve the original animation timing?
It outputs one image per pose, not the original sequence of held frames. Playback timing must be handled downstream.
Is the Proper Pixel Art web demo the same as this extension?
No. It is a separate project related to the Autorefiner’s mesh-detection approach. Its settings, palette methods, and animation processing differ.
Learn More about ComfyUI-Krea2-Pixel-Art-Refiner
-
ComfyUI-Krea2-Pixel-Art-Refiner repository
The primary reference for the extension, its nodes, and the author’s documentation. -
Proper Pixel Art documentation and examples
Helpful for understanding why noisy pixel-art-style images need grid recovery rather than ordinary downscaling. Its illustrated examples show detected edges, meshes, and reconstructed artwork. -
Proper Pixel Art browser demo
A separate browser-based tool for exploring pixel-art cleanup. Use it as a visual learning resource, not as a preview of identical extension behavior.
The image below comes from Proper Pixel Art, not from a demonstrated run of this ComfyUI extension. It illustrates the idea of detecting a mesh around intended pixel cells:
Illustrative pixel mesh from the separate Proper Pixel Art project (https://raw.githubusercontent.com/KennethJAllen/proper-pixel-art/main/assets/bat/mesh.png)
For a deeper explanation of the edge-detection techniques behind mesh recovery:
- OpenCV: Canny edge detection (https://docs.opencv.org/4.x/da/d22/tutorial_py_canny.html)
- OpenCV: Morphological operations, including closing small edge gaps (https://docs.opencv.org/4.x/d9/d61/tutorial_py_morphological_ops.html)
- OpenCV: Hough line detection (https://docs.opencv.org/4.x/d3/de6/tutorial_js_houghlines.html)
