---
name: comfyui_mesh_cleanup_oneshot
kind: pipeline
lang: py
domain: pipelines
version: "1.0.0"
purity: impure
signature: "def comfyui_mesh_cleanup_oneshot(in_path: str, *, target_faces: int = 80000, watertight: bool = True, method: str = \"repair\", out_path: str | None = None) -> dict"
description: "Pipeline de limpieza de mallas 3D en una sola llamada: decima a un presupuesto de caras (comfyui_simplify_mesh) y, opcionalmente, la hace estanca (comfyui_make_watertight). Capitaliza el 'Golden 3' del report 0088 (80k caras + estanca a la vez) para las mallas densas no estancas que produce el pipeline Hunyuan3D de ComfyUI. Promocion de secuencia (issue 0087). Impuro: lee y escribe archivos en disco; requiere trimesh + pymeshlab + scipy."
tags: [comfyui, pipelines, mesh, cleanup, watertight, launcher]
uses_functions: [comfyui_simplify_mesh_py_ml, comfyui_make_watertight_py_ml]
uses_types: []
returns: []
returns_optional: false
error_type: error_py_core
imports: [comfyui_simplify_mesh_py_ml, comfyui_make_watertight_py_ml]
params:
  - name: in_path
    desc: "Ruta de la malla de entrada (.glb/.obj/.ply/.gltf/.stl/.off)."
  - name: target_faces
    desc: "Caras objetivo del paso de decimacion (comfyui_simplify_mesh). keyword-only."
  - name: watertight
    desc: "Si True (default) aplica comfyui_make_watertight tras decimar; si False solo decima. keyword-only."
  - name: method
    desc: "Metodo de make_watertight cuando watertight=True. 'repair' (default) conserva las caras decimadas pero no garantiza estanqueidad en mallas muy rotas; 'voxel' garantiza is_watertight=True via voxeliza+fill+marching cubes, a costa de re-mallar (cambia el conteo de caras y descarta apariencia). keyword-only."
  - name: out_path
    desc: "Ruta de salida final. Si None, se deriva de in_path ('<in>_cleaned.glb'). keyword-only."
output: "dict {ok, in_path, out_path, in_faces, simplified_faces, final_faces, watertight_requested, is_watertight, method, steps, error}. steps = resultados crudos de cada funcion compuesta. Si algun paso falla, ok=False y error explica en cual."
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/pipelines/comfyui_mesh_cleanup_oneshot.py"
---

## Ejemplo

```bash
# Limpia la malla densa de ComfyUI: decima a 80k caras y la hace estanca.
./fn run comfyui_mesh_cleanup_oneshot ~/ComfyUI/output/3d_mesh_00002_.glb
```

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

res = comfyui_mesh_cleanup_oneshot(
    os.path.expanduser("~/ComfyUI/output/3d_mesh_00002_.glb"),
    target_faces=80000,
    watertight=True,
)
# res["ok"] == True
# res["in_faces"]  >> res["final_faces"]   # decimada
# res["is_watertight"]  # True/False segun method y la malla
print(res["in_faces"], "->", res["final_faces"], "watertight:", res["is_watertight"])
```

## Cuando usarla

Justo después de generar una malla 3D con ComfyUI/Hunyuan3D
(`comfyui_image_to_3d_oneshot`, `comfyui_text_to_3d_oneshot`), cuando el GLB sale
denso (decenas de MB, >1M caras) y/o no estanco. En una llamada la dejas lista
para web (ligera) o impresión 3D (cerrada). Es la promoción del patrón
"simplify → make_watertight" que se repetía a mano (reports 0088/0091).

## Gotchas

- Impuro: lee y **escribe** archivos en disco. Con `watertight=True` deja también
  un intermedio `<out>_simplified.glb` junto al final.
- Necesita `trimesh` + `pymeshlab` + `scipy` (decimación). Con `method="voxel"`
  además `scikit-image` (marching cubes). Si falta una, el paso correspondiente
  devuelve `ok=False` con el comando `uv add` a ejecutar.
- **`method="repair"` (default) NO garantiza estanqueidad** en mallas muy rotas:
  cierra huecos pequeños y conserva las caras decimadas. El output reporta
  `is_watertight` real — compruébalo. Si necesitas estanqueidad GARANTIZADA usa
  `method="voxel"` (re-malla: cambia el conteo de caras y descarta UV/colores).
- El `target_faces` aplica al paso de decimación. Con `method="voxel"` el conteo
  final lo fija el voxel-remesh (mira `final_faces`), no `target_faces`.
- El pipeline NO falla si la malla no queda estanca con `repair`: devuelve `ok=True`
  con `is_watertight=False`. Decide en el caller si reintentar con `method="voxel"`.
- No toca el servidor ComfyUI: opera sobre archivos GLB ya en disco.

## Capability growth log

- v1.0.0 (2026-06-24) — pipeline inicial. Compone `comfyui_simplify_mesh` +
  `comfyui_make_watertight` (issue 0087, capitaliza report 0088).