---
name: comfyui_build_item_icon_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_item_icon_workflow(item: str, *, style: str = \"game icon, clean, centered\", checkpoint: str = \"IMG_dreamshaper_8.safetensors\", size: int = 512, transparent: bool = True, seed: int = 0, lora: str | None = None, lora_strength: float = 1.0, rembg_model: str = \"u2net\", negative: str | None = None, steps: int = 28, cfg: float = 7.0, sampler_name: str = \"dpmpp_2m\", scheduler: str = \"karras\", filename_prefix: str = \"item_icon\") -> dict"
description: "Construye el dict (API format) del workflow de UN icono de item de inventario 2D (espada, pocion, anillo, libro, escudo, gema): sujeto unico centrado, fondo limpio uniforme, estilo consistente entre items, encuadre cuadrado. Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_pixelart/sprite_sheet/seamless_tile_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, icon, item, inventory, rembg, workflow]
uses_functions: [comfyui_build_txt2img_workflow_py_ml, comfyui_inject_lora_py_ml]
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: item
    desc: "Nombre del item (ej. 'health potion', 'iron sword', 'gold ring'). Se inserta en un prompt scaffold de icono. No puede estar vacio."
  - name: style
    desc: "Descriptor de estilo que mantiene consistentes los items de un set (ej. 'game icon, clean, centered', 'hand-painted RPG icon', 'flat vector icon'). Pasa el MISMO style + checkpoint + lora a todos los items para coherencia visual. keyword-only."
  - name: checkpoint
    desc: "Checkpoint del servidor. 'IMG_dreamshaper_8.safetensors' (SD1.5, holgado en 8GB lowvram) por defecto; 'IMG_juggernaut_xl_v11.safetensors' para SDXL (mas VRAM, subir size). keyword-only."
  - name: size
    desc: "Lado del cuadrado en px (width = height = size). 512 SD1.5 por defecto. keyword-only."
  - name: transparent
    desc: "Si True inyecta Image Rembg y el PNG sale con alpha (fondo recortado). False = item opaco sobre fondo plano, recortable luego por el caller. keyword-only."
  - name: seed
    desc: "Semilla del KSampler. keyword-only."
  - name: lora
    desc: "LoRA de estilo opcional en models/loras (ej. 'SD15_detail_tweaker.safetensors', 'SD15_isometric_game_assets.safetensors'). None = sin LoRA. keyword-only."
  - name: lora_strength
    desc: "Fuerza del LoRA sobre model y clip. Se clampa a [0.0, 2.0]. keyword-only."
  - name: rembg_model
    desc: "Modelo Rembg ('u2net' general, 'isnet-anime' para anime). Solo se usa si transparent=True. keyword-only."
  - name: negative
    desc: "Prompt negativo. None usa el negativo por defecto pensado para iconos (un objeto, fondo limpio, sin texto/foto). keyword-only."
  - name: steps
    desc: "Pasos del KSampler. keyword-only."
  - name: cfg
    desc: "CFG del KSampler. keyword-only."
  - name: sampler_name
    desc: "Sampler del KSampler. keyword-only."
  - name: scheduler
    desc: "Scheduler del KSampler. keyword-only."
  - name: filename_prefix
    desc: "Prefijo del PNG en output/. keyword-only."
output: "dict en API format listo para comfyui_submit_workflow: base txt2img cuadrada con prompt scaffold de icono ('a {item}, game inventory icon, {style}, centered, single object, plain background, ...') + LoRA de estilo opcional + Image Rembg (si transparent). UN icono; set de items -> llamar por item con mismo style/checkpoint/lora."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; item + 'game inventory icon' + 'centered' en prompt; SaveImage <- Rembg; transparency True", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge size: width==height==768 (cuadrado)", "edge style en prompt", "edge lora: LoraLoader presente con strength", "error item vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_item_icon_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_item_icon_workflow.py"
---

## Ejemplo

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

# Un icono de pocion con fondo transparente (alpha), listo para submit.
wf = comfyui_build_item_icon_workflow(
    "health potion",
    style="hand-painted RPG icon, glowing red liquid",
    transparent=True,
    seed=42,
)
# Set coherente: misma firma de estilo para cada item del inventario.
#   for it in ["iron sword", "gold ring", "ancient book", "wooden shield"]:
#       wf = comfyui_build_item_icon_workflow(it, style="hand-painted RPG icon",
#                                             lora="SD15_detail_tweaker.safetensors", seed=42)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# Contact-sheet del set: montar los PNG resultantes con comfyui_build_grid.
```

O lanzable directo con: `./fn run comfyui_build_item_icon_workflow` (imprime nodos + class_types del ejemplo).

## Cuando usarla

Cuando necesites iconos de items de inventario para un juego (RPG, roguelike,
crafting) con look consistente entre items: armas, pociones, anillos, libros,
escudos, gemas, comida. Pasa el MISMO `style` + `checkpoint` + (`lora`) a todos
los items del set para que combinen visualmente; varía solo `item`. `transparent`
recorta el fondo (alpha) listo para el motor. Para un atlas/contact-sheet, genera
cada icono y monta los PNG con `comfyui_build_grid`.

## Gotchas

- **El recorte usa Rembg, NO luma-to-alpha**: un item es un sujeto solido con
  silueta definida, rembg lo recorta limpio. `comfyui_matting_luma_to_alpha` es
  para translucidos sobre negro (humo/fuego/magia) y aplanaria el item — no la
  uses para iconos.
- **Coherencia del set = mismos parametros**: si cambias `style`/`checkpoint`/
  `lora`/`seed` entre items, el set deja de combinar. Fija esos y varía solo `item`.
- **SDXL pide mas VRAM y resolucion**: con `checkpoint="IMG_juggernaut_xl_v11.safetensors"`
  sube `size` a 768/1024; con IMG_dreamshaper_8 (SD1.5) deja 512 (holgado en 8GB lowvram).
- Si el modelo mete varios objetos o texto, el negativo por defecto ya empuja a
  "single object / plain background / no text"; refuerza `style` con "single item,
  isolated" si insiste.
- `transparent=False` deja el item opaco sobre fondo plano: util si prefieres
  recortar fuera del workflow o el motor compone sobre un slot solido.
- Es una funcion **pura**: solo arma el dict. La generacion real (GPU) la hacen
  `comfyui_submit_workflow` + `comfyui_wait_result` + `comfyui_fetch_output_image`.
