---
name: comfyui_build_grid
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: impure
signature: "def comfyui_build_grid(image_paths: list, *, cols: int | None = None, cell: int = 512, out_path: str | None = None, labels: list | None = None) -> dict"
description: "Monta un grid / contact-sheet PIL de N imagenes para comparacion visual (p.ej. el output de comfyui_batch_generate con varios seeds). Cada celda conserva el aspect ratio (thumbnail centrado sobre fondo oscuro); rejilla casi cuadrada por defecto (cols=ceil(sqrt(N))). Rotulos opcionales por celda. Usa PIL (Pillow) del venv del registry. Devuelve {ok, out_path, rows, cols, error}. Impura: lee N imagenes y escribe un PNG."
tags: [comfyui, ml, grid, montage, pil, image]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: image_paths
    desc: "lista de rutas a las imagenes a montar, en orden de lectura (izq->der, arriba->abajo)."
  - name: cols
    desc: "numero de columnas; si None usa ceil(sqrt(N)) para una rejilla casi cuadrada."
  - name: cell
    desc: "lado en pixeles de cada celda cuadrada; la imagen se reduce para caber conservando proporcion (default 512)."
  - name: out_path
    desc: "ruta del PNG de salida; si None escribe 'comfy_grid.png' en el dir de la primera imagen."
  - name: labels
    desc: "rotulos opcionales, uno por imagen (mismo orden); reservan una franja bajo cada celda."
output: "dict con ok (bool), out_path (str, ruta del PNG generado), rows (int, filas), cols (int, columnas), error (str, vacio si OK)."
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/ml/comfyui_build_grid.py"
---

## Ejemplo

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

imgs = [
    os.path.expanduser("~/ComfyUI/output/comfy_00001_.png"),
    os.path.expanduser("~/ComfyUI/output/comfy_00002_.png"),
    os.path.expanduser("~/ComfyUI/output/comfy_00003_.png"),
    os.path.expanduser("~/ComfyUI/output/comfy_00004_.png"),
]
res = comfyui_build_grid(imgs, cols=2, cell=512, out_path="/tmp/seeds_grid.png",
                         labels=["seed 1", "seed 2", "seed 3", "seed 4"])
# {'ok': True, 'out_path': '/tmp/seeds_grid.png', 'rows': 2, 'cols': 2, 'error': ''}
```

## Cuando usarla

Tras un barrido de seeds con `comfyui_batch_generate` + `comfyui_fetch_output_image`:
en vez de abrir N PNGs uno a uno, montas un unico contact-sheet para elegir de un
vistazo la mejor variante (o comparar steps/cfg/sampler distintos). Tambien sirve
para documentar un report con una rejilla de resultados. Es post-proceso local
puro de imagen: no toca el servidor ComfyUI.

## Gotchas

- Si alguna ruta de `image_paths` no existe, devuelve `ok=False` con la lista de
  faltantes (estricto): no monta una rejilla parcial silenciosamente. Filtra las
  rutas validas antes si quieres tolerar ausencias.
- Cada imagen se reduce a `cell` px conservando proporcion (thumbnail); imagenes de
  distinto tamano quedan centradas en su celda con relleno, no estiradas.
- `labels` se dibuja con la fuente por defecto de PIL (pequeña, sin TTF externo);
  para rotulos grandes habria que pasar una fuente — no soportado hoy (KISS).
- Escribe el PNG en disco: si `out_path` apunta a un directorio inexistente lo crea;
  si no tiene permiso devuelve `ok=False` con el error.
- N grande con `cell` alto produce un canvas enorme (rows*cols*cell^2 px): para
  decenas de imagenes baja `cell` (p.ej. 256) para no agotar memoria.