Quality profiles

A style can declare the derived art it is willing to ship:

{
  "styles": {
    "environment": {
      "generator": "map",
      "outDir": "assets/generated/environment",
      "quality": {
        "outDir": "assets/final/environment",
        "palette": ["#141b1e", "#23312a", "#526a8d", "#709fcf", "#f1bb70"],
        "minGridConfidence": "high",
        "minTransparency": 0.2,
        "fixerPython": ".pixelkiln/pixelfixer/bin/python"
      }
    }
  }
}

Field	Type/default	Meaning
outDir	string, required	Manifest-relative root for refined PNGs and their .pixelkiln.json quality records.
palette	2–256 unique hex colors	Closed final palette. PixelKiln applies it without dithering after native-grid recovery.
minGridConfidence	high	Lowest accepted Pixel Art Fixer result: high, medium, or low.
minTransparency	number 0–1	Optional minimum transparent share for isolated assets. Omit it for opaque scenes.
fixerRevision	tested pinned revision	Exact Pixel Art Fixer revision recorded in the quality companion.
fixerPython	PIXELKILN_PIXEL_FIXER_PYTHON, then python3	Manifest-relative Python executable containing Pixel Art Fixer. An absolute path is also accepted.
fps	integer 1–60, 12 for frames	Playback rate stored with a ComfyUI frame set and used by its review preview.

The raw provider output remains under the style's normal outDir. The quality output keeps the asset's relative category and filename under quality.outDir and always uses PNG. A ComfyUI frame set writes role-stable names such as walk-frame-00.png and one shared walk.pixelkiln.json record. PixelKiln reads asset.source for an ordinary asset; otherwise it requires intact downloaded PNG bytes from the lockfile.

Quality settings do not participate in the provider spec hash. Changing the palette, threshold, fixer revision, interpreter, or final output directory never schedules paid generation. The interpreter is execution configuration, so changing only fixerPython does not invalidate already-refined output.

Run the profile as a batch, review its PNGs, and record approval per result:

pixelkiln refine --style environment
pixelkiln refine approve \
  --from assets/final/environment/mountain.pixelkiln.json \
  --reviewer "Your Name"
pixelkiln refine check --style environment

plan reports raw and quality state separately. plan --check, pack, and mount fail until each selected profile output is current and approved. Pack and mount use the approved derived PNG and retain its quality record in their provenance. A stale generation spec blocks the gate even when an approval for the old raw bytes still exists. Repeating refine preserves pending and approved records; use --force only when you intend to rebuild current output and reset approval. pack includes every approved frame. A mounted frame-set asset must declare outputRole, because one fixed cell cannot hold an animation implicitly.

Quality profiles support single-image map, 1dir, and pixflux styles plus atomic ComfyUI frames. The frame record binds every source and output, one palette, fps, ordered roles, and each frame's detected step and phase. A grid disagreement rejects the whole set. The schema rejects tiles and provider animation, whose output contracts differ. See Quality gates for the release workflow.