fn_registry/python/functions/pipelines/comfyui_pixelart_real_oneshot.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
comfyui_pixelart_real_oneshot	pipeline	py	pipelines	1.0.0	impure	def comfyui_pixelart_real_oneshot(subject: str, *, size: int = 64, colors: int = 16, engine: str = "pixeloe", palette=None, server: str = "127.0.0.1:8188", dest_dir: str = "~/ComfyUI/output", seed: int = 0, negative: str | None = None, mode: str = "contrast", patch_size: int = 16, thickness: int = 2, fill_frame: bool = True, upscale_preview: int = 512, keep_base: bool = True, comfy_python: str | None = None, wait_timeout: float = 300.0, filename_prefix: str = "pixelart_real", **gen_kwargs) -> dict	Pipeline one-shot prompt de texto -> sprite pixel-art REAL (grid duro + paleta limitada) en disco. Materializa el metodo ganador del report 0215: generar a alta-res con SDXL + LoRA SDXL_pixel-art, downscale contrast-aware con PixelOE (engine=pixeloe, sprites) o nearest (tiles), y cuantizacion dura con comfyui_pixelize_image (16 colores libres o paleta fija pico-8/nes/game-boy). Sweet-spot 64px personajes, 32px iconos. Fallback automatico pixeloe->nearest. Compone build_pixelart + submit + wait + fetch + pixeloe_downscale + pixelize_image. Impuro: HTTP + disco.	comfyui gamedev-2d pixelart pipelines sprite launcher	comfyui_build_pixelart_workflow_py_ml comfyui_submit_workflow_py_ml comfyui_wait_result_py_ml comfyui_fetch_output_image_py_ml pixeloe_downscale_py_ml comfyui_pixelize_image_py_ml			false	error_py_core	comfyui_build_pixelart_workflow_py_ml comfyui_submit_workflow_py_ml comfyui_wait_result_py_ml comfyui_fetch_output_image_py_ml pixeloe_downscale_py_ml comfyui_pixelize_image_py_ml	name desc subject Prompt positivo (lo que se quiere ver: 'pixel art knight, full body, side view'). No puede estar vacio. name desc size Lado del grid final en pixeles. 64 personajes/sprites, 32 iconos/objetos simples. keyword-only. name desc colors Numero de colores de la paleta libre (MEDIANCUT) cuando palette es None. keyword-only. name desc engine 'pixeloe' (downscale contrast-aware, sujetos con silueta) o 'nearest' (downscale simple, tiles/texturas). Fallback automatico a nearest si pixeloe falla. keyword-only. name desc palette None (paleta libre a `colors`), nombre builtin ('pico-8', 'nes', 'game-boy') o lista de hex. Una paleta fija ignora `colors`. keyword-only. name desc server host:port del servidor ComfyUI (sin esquema). keyword-only. name desc dest_dir Directorio donde guardar los PNG (se expande ~). keyword-only. name desc seed Semilla del KSampler. keyword-only. name desc negative Prompt negativo; None usa el default de build_pixelart (evita blur/gradientes/anti-alias). keyword-only. name desc mode Modo de downscale de PixelOE ('contrast' SOTA, 'k-centroid', 'nearest', 'center', 'bicubic'); solo con engine='pixeloe'. keyword-only. name desc patch_size Tamano de patch de PixelOE (default 16). keyword-only. name desc thickness Grosor del outline expansion de PixelOE (default 2). keyword-only. name desc fill_frame Si True anade un hint de encuadre al subject para que el sujeto llene el frame (mejor detalle por pixel tras el downscale). keyword-only. name desc upscale_preview Si > 0 escribe ademas un PNG re-escalado nearest a ese lado (preview con pixeles duros, p.ej. 512). 0 lo desactiva. keyword-only. name desc keep_base Si True conserva el PNG base de alta resolucion; si False lo borra tras pixelizar. keyword-only. name desc comfy_python Ruta al interprete de ComfyUI (con la lib pixeloe); None autodetecta. keyword-only. name desc wait_timeout Segundos maximos esperando al server. keyword-only. name desc filename_prefix Prefijo de los archivos de salida. keyword-only. name desc gen_kwargs Params extra para comfyui_build_pixelart_workflow (width, height, ckpt_name, lora_strength, use_lcm, steps, cfg, ...). keyword-only (**gen_kwargs).	dict {ok, out_path, out_path_upscaled, base_path, size, colors_final, engine_used, prompt_id, error}. out_path = PNG final size x size; out_path_upscaled = preview re-escalado; engine_used refleja el fallback (pixeloe->nearest). Si falla, ok=False y error explica en que paso. No-throw.	false			python/functions/pipelines/comfyui_pixelart_real_oneshot.py

Ejemplo

# Personaje 64px, 16 colores, motor pixeloe (sprites con silueta).
./fn run comfyui_pixelart_real_oneshot "pixel art knight, full body, side view, game sprite"

import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from pipelines.comfyui_pixelart_real_oneshot import comfyui_pixelart_real_oneshot

# (a) Personaje 64px, paleta libre 16 colores, PixelOE contrast.
res = comfyui_pixelart_real_oneshot(
    "pixel art knight, full body, side view, game sprite",
    size=64, colors=16, engine="pixeloe", seed=42,
    dest_dir="~/ComfyUI/output",
)
print(res["out_path"], res["colors_final"], res["engine_used"])  # ~16 colores, pixeloe

# (b) Icono 32px de un item.
res = comfyui_pixelart_real_oneshot(
    "pixel art sword icon, single object",
    size=32, colors=16, engine="pixeloe", seed=7,
)

# (c) Tile sin silueta -> nearest (mas barato) + paleta fija PICO-8.
res = comfyui_pixelart_real_oneshot(
    "pixel art grass texture tile, top down, seamless",
    size=64, engine="nearest", palette="pico-8", fill_frame=False,
)

Cuando usarla

Cuando quieres pixel-art de verdad (grid duro + paleta limitada, verificable por conteo de colores), no la salida cruda de la difusion (que parece pixelada pero tiene decenas de miles de colores y bordes con anti-aliasing). Una sola llamada hace generar -> downscale -> cuantizar. Usa engine="pixeloe" para personajes/criaturas/iconos con silueta (conserva el contorno) y engine="nearest" para tiles/texturas/fondos sin contorno (mas barato, CPU puro). 64px es el sweet-spot de personajes; 32px solo para iconos/objetos simples.

Gotchas

• Impuro: requiere el servidor ComfyUI vivo en server (default 127.0.0.1:8188) y los modelos instalados (SDXL Juggernaut + LoRA SDXL_pixel-art + SDXL_lcm-lora). Si esta caido, falla en submit con ok=False y el error de conexion (nunca lanza).
• engine="pixeloe" necesita la lib pixeloe, que vive en el venv de ComfyUI (no en el del registry). pixeloe_downscale hace el puente de interprete automaticamente; si no la encuentra, el pipeline cae a nearest y lo reporta en engine_used + error (no aborta).
• El nodo PixelOEPixelize+ de ComfyUI_essentials estaba roto por un import obsoleto (pixeloe.pixelize -> ahora pixeloe.legacy.pixelize); por eso el pipeline usa la lib directa via pixeloe_downscale, no el nodo del server.
• dest_dir es un directorio (se crea si no existe). Los nombres de salida son <prefix>_<size>px_<engine>_<paleta|qN>.png y ..._up.png (preview).
• Una paleta fija (pico-8/nes/game-boy/lista hex) ignora colors y puede dar menos colores que colors si el sujeto no cubre toda la paleta.
• Encuadre: si el sujeto ocupa poca area del frame, a 64/32px queda diminuto. fill_frame=True (default) empuja al sujeto a llenar el frame; aun asi, para sprites conviene un subject que pida "full body, centered".
• No reintenta el sampler: para mejor toma, varia seed.

Capability growth log

• v1.0.0 (2026-06-28) — pipeline inicial. Materializa el metodo ganador del report 0215 (PixelOE contrast downscale -> cuantizacion dura). Compone build_pixelart + submit + wait + fetch + pixeloe_downscale + pixelize_image (issue 0087).