Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-Krea2-Pixel-Art-Refiner

ComfyUI Extension: ComfyUI-Krea2-Pixel-Art-Refiner

Repo Name

ComfyUI-Krea2-Pixel-Art-Refiner

Author
envy-ai (Account age: 826 days)
Nodes
View all nodes(1)
Latest Updated
2026-11-08
Github Stars
0.04K

How to Install ComfyUI-Krea2-Pixel-Art-Refiner

Install this extension via the ComfyUI Manager by searching for ComfyUI-Krea2-Pixel-Art-Refiner
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-Krea2-Pixel-Art-Refiner in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

ComfyUI-Krea2-Pixel-Art-Refiner Description

ComfyUI-Krea2-Pixel-Art-Refiner cleans generated pixel art by reducing palettes, restoring pixel grids, sharing colors across frames, and merging repeated animation poses into consistent sprites.

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:

NodeWhere to find itMain purpose
Perceptual Palette Reduceimage/colorReduce an image to an automatically selected palette.
Pixel Grid Collapseimage/transformClean up a known, evenly spaced pixel grid.
Krea 2 Pixel Art Refinerimage/krea2Combine palette reduction and grid collapse with straightforward controls.
MiniMax H3 Pixel Art Refinerimage/minimaxAdd reference palettes, shared batch palettes, uneven grids, and grid alignment controls.
MiniMax H3 Pixel Art Autorefinerimage/minimaxDetect a pixel mesh automatically, including separate regions in directional sprite sheets.
Pixel Art Animation Pose Compositorimage/animationCombine 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:

  1. It selects the color perceptually closest to the cell’s center pixel in OKLab.
  2. 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:

  1. Reduces the image to the requested palette.
  2. Looks for edges and closes small gaps in them.
  3. Detects horizontal and vertical lines.
  4. Estimates the underlying pixel spacing.
  5. Repairs misleading small cells and fills missing boundaries.
  6. 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.

SettingDefaultWhat it does
colors24Maximum 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_width sets the number of cells across the image.
  • logical_height sets 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 × 1024 input with a 64 × 64 grid: valid.
  • 1000 × 1000 input with a 64 × 64 grid: 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.

InputDefaultHow to use it
image—Supply a ComfyUI image or image batch.
width64Intended number of logical pixels across the image.
height64Intended number of logical pixels down the image.
colors24Maximum palette size, selected separately for each image.
color_reduction_firstOnReduce colors before collapsing cells. Turn off to reverse the order.
scale_to_originalOnExpand 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_original On returns the cleaned artwork at the source dimensions.
  • scale_to_original Off returns the logical 64 × 64 image.

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.

InputDefaultWhat it does
image—Accepts an image, image batch, or video-frame batch.
width64Logical grid width.
height64Logical grid height.
colors24Maximum generated or reduced palette size.
color_reduction_firstOnChoose whether palette reduction happens before grid collapse.
scale_to_originalOnExpand the logical grid to the input dimensions.
allow_uneven_gridOffAllow slightly different cell sizes when dimensions do not divide evenly.
shared_paletteOffGenerate one palette for the entire input batch.
x_offset0.0Move the grid right by a fraction of one logical pixel.
y_offset0.0Move the grid down by a fraction of one logical pixel.
auto_offsetOffDetect grid alignment separately for each image, overriding manual offsets.
align_palette_lightnessOnCompensate for a batch-wide lightness difference when matching a supplied palette.
preserve_generated_backgroundOnPreserve the first image’s upper-left RGB color when using a supplied palette.
palette_imageOptionalSupply 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 colors unique 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.

InputDefaultWhat it does
image—Accepts an image, image batch, or video-frame batch.
width64Full-frame logical width in manual mode; a detection hint and fallback width otherwise.
height64Full-frame logical height in manual mode; a detection hint and fallback height otherwise.
colors24Maximum generated or reduced palette size.
scale_to_originalOnFit the collapsed frame inside the source dimensions and pad it.
shared_paletteOnGenerate one palette across the input batch.
manual_resolutionOffBypass mesh detection and divide the whole frame into the requested grid.
direction_count1Number of fixed regions arranged across the frame, each with independently detected X and Y grids.
align_palette_lightnessOnApply shared lightness compensation while matching a supplied palette.
preserve_generated_backgroundOnPreserve the first frame’s upper-left color during supplied-palette matching.
palette_imageOptionalSupply 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_original On, 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.

InputDefaultWhat it does
images—Ordered animation frames, all at the same resolution.
pose_count0Automatically detect the cycle length, or enter a positive pose count.
transition_threshold7.0Full-frame mean RGB difference needed to start a new hold, measured in 8-bit levels.
remove_outliersOnRemove anomalous frames before cycle detection and compositing.

How poses are grouped

The compositor:

  1. Rounds RGB channels to 8-bit values.
  2. Measures the average absolute RGB difference between consecutive frames.
  3. Starts a new hold when that difference reaches transition_threshold.
  4. Removes a single transition frame when it separates two strongly matching pieces of the same hold.
  5. Optionally removes anomalous frames from each hold.
  6. Assigns holds to poses in repeating cycle order.
  7. 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:

  1. Choosing the lowest Rec.709 luma—the darker candidate.
  2. 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.044 to 1.978.
  • Actual transitions ranged from 13.182 to 29.786.
  • The default threshold of 7.0 separated 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

  1. Send the decoded image to Krea 2 Pixel Art Refiner.
  2. Set width and height to the intended logical resolution.
  3. Start with colors=24.
  4. Check whether outlines and small details survive.
  5. Compare processing orders if necessary.
  6. Turn off scale_to_original if you want the logical-resolution output.
VAE Decode → Krea 2 Pixel Art Refiner → Save Image

For animation frames needing consistent colors

  1. Send the frame batch to MiniMax H3 Pixel Art Refiner.
  2. Set the logical grid.
  3. Enable shared_palette, or connect palette_image.
  4. Adjust grid offsets if block boundaries do not align.
  5. 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.

  1. Check the input image dimensions.
  2. Divide the source width by the logical width.
  3. Divide the source height by the logical height.
  4. Both results must be whole numbers.
  5. Choose compatible dimensions, or use MiniMax H3 Pixel Art Refiner with allow_uneven_grid enabled.

For example, 1024 ÷ 64 = 16, so that axis is compatible.

Outlines look broken or small features disappear

  1. Confirm that the logical resolution matches the intended artwork.
  2. Increase width and height if the current cells are combining distinct features.
  3. Increase colors if important shades are being merged.
  4. Compare color_reduction_first On and Off.
  5. If cell boundaries appear misplaced, try manual offsets or auto_offset in the MiniMax H3 refiner.

A smaller logical grid necessarily retains less spatial detail.

Colors vary between animation frames

  1. Use a MiniMax node that supports shared palettes.
  2. Enable shared_palette, or supply palette_image.
  3. When matching a supplied palette, keep align_palette_lightness enabled if batch-wide brightness compensation is useful.
  4. 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

  1. Check preserve_generated_background.
  2. Disable it if you need strict supplied-palette matching.
  3. 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

  1. Set width and height closer to the expected full-frame logical resolution.
  2. Check direction_count for horizontally arranged directional sheets.
  3. For batches, inspect the first frame: it determines all detected meshes.
  4. Enable manual_resolution if 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

  1. Check whether auto_offset is enabled.
  2. Turn it off to use x_offset and y_offset.
  3. Try 0.5 on one axis to compare a half-cell shift.
  4. Inspect the outer edges, where offset processing wraps.

The compositor cannot detect the pose count

  1. Confirm that the frames are in animation order.
  2. Provide at least two complete cycles for automatic detection.
  3. Check that transitions are being separated appropriately.
  4. Enter a positive pose_count if the cycle length is known or automatic matching remains ambiguous.
  5. 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.

  1. Increase transition_threshold gradually.
  2. Check that real pose changes still create separate holds.
  3. Leave remove_outliers enabled while comparing results.

The compositor merges different poses

The threshold may be too high for subtle pose changes.

  1. Lower transition_threshold gradually.
  2. Check whether the desired transitions now create separate holds.
  3. 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

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:

ComfyUI-Krea2-Pixel-Art-Refiner Related Nodes

RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

ComfyUI-Krea2-Pixel-Art-Refiner detailed guide | ComfyUI