---
name: comfyui_build_textured_3d_multiview_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_textured_3d_multiview_workflow(image_name: str, *, ckpt: str = \"hunyuan3d-dit-v2-mv.safetensors\", views: int = 6, octree: int = 384, max_faces: int = 50000, upscale_model: str = \"4x_foolhardy_Remacri.pth\") -> dict"
description: "Construye el dict (API format) del pipeline imagen->malla 3D texturizada PBR multi-vista de ComfyUI via el wrapper Hunyuan3DWrapper (kijai). Cadena: LoadImage -> Hy3DModelLoader -> Hy3DGenerateMesh -> Hy3DVAEDecode(octree) -> Hy3DPostprocessMesh(max_faces) -> Hy3DMeshUVWrap -> Hy3DCameraConfig(4 o 6 vistas) + Hy3DRenderMultiView + Hy3DDelightImage -> Hy3DSampleMultiView -> [UpscaleModelLoader+ImageUpscaleWithModel(Remacri)+ImageResize+] -> Hy3DBakeFromMultiview -> Hy3DMeshVerticeInpaintTexture -> Hy3DApplyTexture -> Hy3DExportMesh(glb). Portado del report 0082 (cobertura de atlas 32.93% con 6 vistas + Remacri + octree 384). Pura, sin red ni I/O."
tags: [comfyui, ml, img-to-3d, texture, multiview, hunyuan3d, workflow]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: image_name
    desc: "Nombre del archivo de imagen de referencia tal como lo ve el servidor ComfyUI en su carpeta input/ (subido con POST /upload/image)."
  - name: ckpt
    desc: "Checkpoint del modelo de forma Hunyuan3D para Hy3DModelLoader. Por defecto el variante multi-vista hunyuan3d-dit-v2-mv. keyword-only."
  - name: views
    desc: "Numero de vistas de camara: 4 (front/left/back/right) o 6 (anade top/bottom, rellena concavidades). Otro valor lanza ValueError. keyword-only."
  - name: octree
    desc: "octree_resolution del Hy3DVAEDecode (mas alto = malla mas fina, mas VRAM; 384 en el report 0082). keyword-only."
  - name: max_faces
    desc: "max_facenum del Hy3DPostprocessMesh (decimacion; 50000 en el report 0082). keyword-only."
  - name: upscale_model
    desc: "Modelo de upscale ESRGAN en upscale_models/ para mejorar las vistas antes del bake (factor dominante de cobertura). Cadena vacia desactiva el upscale. keyword-only."
output: "dict en API format listo para comfyui_submit_workflow. node_ids '1'..'19'; los nodos de upscale ('13'..'15') solo presentes si upscale_model esta activo. El SaveGLB-equivalente Hy3DExportMesh produce un .glb texturizado en output/3D/."
tested: true
tests: ["estructura completa shape+paint+upscale (18 class_types)", "params imagen/ckpt/octree/max_faces reflejados", "6 vistas configuran 6 azimuths/elevations", "4 vistas configuran 4 azimuths", "sin upscale omite nodos Remacri y el bake toma del sample", "views invalido lanza ValueError", "determinismo: misma entrada -> mismo dict (builder puro)"]
test_file_path: "python/functions/ml/tests/test_comfyui_build_textured_3d_multiview_workflow.py"
file_path: "python/functions/ml/comfyui_build_textured_3d_multiview_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_textured_3d_multiview_workflow import (
    comfyui_build_textured_3d_multiview_workflow,
)

wf = comfyui_build_textured_3d_multiview_workflow(
    "tex_src_character.png", views=6, octree=384, max_faces=50000,
    upscale_model="4x_foolhardy_Remacri.pth",
)
# wf["9"]["class_type"] == "Hy3DCameraConfig"  (6 vistas)
# wf["19"]["class_type"] == "Hy3DExportMesh"   (.glb texturizado)
# OJO: en 8GB ejecutar en 2 fases (ver Gotchas), no de una pasada
```

O lanzable directo con: `./fn run comfyui_build_textured_3d_multiview_workflow` (imprime el JSON del workflow de ejemplo).

## Cuando usarla

Cuando quieras una malla 3D **con textura** desde una sola imagen, con mejor
cobertura de atlas que el image-to-3D nativo (que da geometria sin pintar). Es el
builder del pipeline de texturizado multi-vista del report 0082: 6 vistas de
camara + delight + sample multi-vista + upscale Remacri de las vistas + bake sobre
el UV. Para geometria sin textura usa `comfyui_build_image_to_3d_workflow`
(nodos nativos, mas ligero).

## Gotchas

- **Ejecutar en 2 fases en 8GB**: el grafo es monolitico (shape + paint en un
  dict) por claridad, pero el grafo entero da OOM en 8GB (confirmado reports
  0075/0081/0082). El camino valido es: ejecutar la fase shape (nodos 1-5 ->
  Hy3DExportMesh del shape), liberar VRAM con `POST /free`, y luego la fase paint
  arrancando desde `Hy3DLoadMesh` del .glb del shape. La separacion + el /free los
  orquesta el pipeline impuro que consuma este builder; este dict es la referencia
  de cableado completo.
- Requiere el custom node **ComfyUI-Hunyuan3DWrapper** (kijai) + `custom_rasterizer`
  CUDA compilado, **ComfyUI_essentials** (para `ImageResize+`) y el modelo
  `4x_foolhardy_Remacri.pth` en `upscale_models/`. Si falta algo, ComfyUI rechaza
  el workflow con HTTP 400 (esta funcion es pura y no valida contra el servidor).
- `ckpt` por defecto es el variante multi-vista (`-mv`). El report 0082 uso
  `hy3dgen/hunyuan3d-dit-v2-0-fp16.safetensors`; ajusta `ckpt` al nombre real que
  el servidor enumere en Hy3DModelLoader.
- `upscale_model=""` desactiva el upscale: el bake toma las vistas directas del
  Hy3DSampleMultiView. Pierde la mejora dominante de cobertura (el report midio
  20.81% -> 32.93% al cablear Remacri en serie).
- Render bonito del GLB no disponible headless; verificar con `Load3D`/`Preview3D`
  en la UI de ComfyUI o el visor de `apps/img_to_3d_webapp`.
