pixelkiln
esc
↑↓ move↵ open/ or ⌘ K from any page
Start building
Set up ComfyUI

Recover a native pixel grid

File size is not pixel-art resolution. Keep these three measurements separate:

  1. The generation canvas is the raster SDXL produces, such as 1024×1024.
  2. The native art grid has one stored pixel for each editable pixel-art cell.
  3. The display size is an integer-scaled view of the native art.

Pixel Art XL can draw convincing pixel-shaped texture without producing a consistent one-pixel grid. Our 1024×1024 test image carried an implied 8px cell and resolved to 128×128 native art. Its 1344×768 wide version resolved to 168×96. Nearest-neighbor scaling preserved those fake cells but did not fix them.

Retro Diffusion's MIT-licensed Pixel Art Fixer detects the implied grid and reconstructs one output pixel per cell. Both benchmark sources returned the high-confidence fast:ac+rl(S) decision. The checked-in native-grid boundary benchmark includes the source PNGs, native reconstructions, dimensions, hashes, and pinned fixer revision.

Treat the native PNG as the canonical asset. Edit and compose it at 1×. Scale it only for display, using integer dimensions and nearest-neighbor rendering. A 2048px file made from a 1024px pseudo-pixel source is not higher-quality pixel art, even when every source pixel becomes an exact 2×2 block.

The open fixer is deterministic image processing. Its maintainers also offer a hosted neural fixer for damaged inputs where a reliable grid no longer exists. PixelKiln does not yet call the hosted service. The local refine command uses the open fixer's Python API and records its revision and detector result.

Install the refiner

Keep the refiner separate from Comfy Desktop's Python environment. These are the commands used for the checked-in benchmark:

uv venv .pixelkiln/pixelfixer --python 3.12
uv pip install \
  --python .pixelkiln/pixelfixer/bin/python \
  "git+https://github.com/Retro-Diffusion/pixel-art-fixer.git@ef376e57e1c272633ca2dbf5f29ec3fcf6596465#subdirectory=python"

.pixelkiln/ is ignored by the repository. It is local tooling, not a project artifact. If uv is unavailable, create a Python 3.12 virtual environment and install the same pinned Git URL with that environment's pip. On Windows, pass the environment's Scripts/python.exe path to --fixer-python.

For a manifest project, declare the policy on the style as shown below and run pixelkiln refine --style <id>. Use path mode only for an isolated experiment or input outside a manifest:

PALETTE="#141b1e,#23312a,#384d4f,#526a8d,#709fcf,#865c45,#c6a766,#f1bb70"

pixelkiln refine \
  --from working-canvas.png \
  --out art/mountain-native.png \
  --palette "$PALETTE" \
  --fixer-python .pixelkiln/pixelfixer/bin/python

pixelkiln refine approve \
  --from art/mountain-native.pixelkiln.json \
  --reviewer "Your Name"

pixelkiln refine check --from art/mountain-native.pixelkiln.json

The default requires the fixer's high-confidence result and writes nothing when the detected dimensions disagree with the reconstructed PNG. It preserves alpha, uses nearest-color redmean distance, and never dithers. The companion starts with review status pending. Approval becomes stale when the source, output, palette metadata, fixer revision, audit, or approval record changes. The pinned fixer's API accepts images with a minimum 16px side and at most four million source pixels. Crop or split a larger working canvas before refinement.

Quality-first resolution policy

Use 48×48 through 128×128 as the default native range for an independently generated component with this tested stack. This is an operating range, not an adapter restriction: ComfyUI may work on a 1024px canvas internally, and a wide or tall asset may exceed one native axis when review supports it. Do not grow both native dimensions merely because the machine can render them. This matches the Aseprite Diffusion author's published working range of 48–128px, centered on a 64px native target, and our current 128px recovery.

Start with a 16–32 color project palette. Add colors only when they improve readable depth, material, or lighting. After grid recovery, review the asset at 1× and an integer zoom for silhouette, clusters, contours, single-pixel noise, palette separation, and seams. High-confidence grid detection only proves structure; it is not an aesthetic approval.

Test a proposed graph and prompt pattern on at least two different scene families. One prompt can clean up one subject and damage another. Generate a small candidate set, reject any image that misses required objects, and keep the prompt and workflow only when the final native files improve consistently.

Stop increasing resolution when clusters become soft, gradients replace intentional ramps, or important forms stop reading at 1×. Keep the smaller result when it is clearer. See the quality gates for the human review checklist.

PixelKiln's committed ComfyUI examples also have an automated regression baseline. npm run test:quality checks that their dimensions, palettes, alpha, edge structure, isolated-pixel noise, and bound refinement records have not drifted. Use pixelkiln quality snapshot to establish the same guard for a project's reviewed assets. Passing it does not make an image good; it only proves that measured traits have not regressed from the accepted reference.