fn_registry/python/functions/ml/comfyui_simplify_mesh.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_simplify_mesh	function	py	ml	1.0.0	impure	def comfyui_simplify_mesh(in_path: str, *, target_faces: int = 80000, weld: bool = True, out_path: str | None = None) -> dict	Decima (simplifica) una malla 3D GLB/OBJ/PLY a target_faces conservando su apariencia. Post-proceso de las mallas densas de Hunyuan3D/ComfyUI (60 MB / ~1.67 M caras). Suelda los vertices duplicados ANTES del quadric edge collapse (pymeshlab) — las mallas cube-soup de VoxelToMeshBasic no decimar sin soldar primero. Conserva vertex colors (ColorVisuals, los interpola pymeshlab a traves del collapse) o textura+UV (TextureVisuals, reproyecta UV por vertice mas cercano con scipy y readjunta la imagen). Impura: lee y escribe en disco con trimesh + pymeshlab + scipy.	comfyui 3d mesh hunyuan3d decimation simplify pymeshlab trimesh ml				false	error_go_core		name desc in_path Ruta de la malla de entrada (.glb/.obj/.ply/.gltf/.stl/.off). Si es un GLB Scene con varias geometrias, se concatenan en una sola malla. name desc target_faces Numero de caras objetivo tras la decimacion. Si es >= a las caras soldadas, no decima (decimate_status lo indica). keyword-only. Default 80000. name desc weld Si True (default), suelda vertices duplicados (meshing_remove_duplicate_vertices) antes del collapse. CLAVE para las mallas cube-soup de VoxelToMeshBasic: sin el, el quadric edge collapse devuelve las caras intactas. keyword-only. name desc out_path Ruta de salida. Si None, escribe '<in>_simplified.glb' junto al original (NO sobrescribe el original). keyword-only.	dict {ok, in_faces, out_faces, in_mb, out_mb, out_path, welded_faces, decimate_status, appearance, error}. in/out_faces = caras antes/despues; in/out_mb = tamano de archivo en MB; welded_faces = caras tras soldar; decimate_status = 'ok' o 'skipped_target_ge_welded(N)'; appearance = 'vertex_color'|'texture'|'none'. Si falla, ok=False y error explica (dependencia ausente, archivo no existe, carga o export).	false			python/functions/ml/comfyui_simplify_mesh.py

Ejemplo

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

# Decima la malla densa de un personaje (964k caras, 34.7 MB) a 80k caras,
# conservando los vertex colors. No toca el original.
res = comfyui_simplify_mesh(
    os.path.expanduser("~/ComfyUI/output/character_3d_00001_.glb"),
    target_faces=80000,
    out_path="/tmp/character_simplified.glb",
)
# res == {"ok": True, "in_faces": 964332, "out_faces": 80000,
#         "in_mb": 34.718, "out_mb": 1.429, "appearance": "vertex_color",
#         "decimate_status": "ok", "out_path": "/tmp/character_simplified.glb", ...}

Lanzar con el python del venv del registry (import de arriba o heredoc). ./fn run directo no aplica: la firma usa * (keyword-only), no soportado por el runner de fn run.

Cuando usarla

Cuando una malla 3D de ComfyUI/Hunyuan3D sale demasiado densa (decenas de MB, millones de caras) y necesitas una version ligera para visor web, repo, deploy o texturizado posterior. Es el post-proceso de los .glb que baja comfyui_fetch_output_mesh. Para hacerla ademas estanca, encadena con comfyui_make_watertight. Si la malla ya es ligera (caras <= target_faces) no hace nada destructivo: el campo decimate_status lo refleja.

Gotchas

• Impura: lee in_path y escribe out_path en disco. Nunca sobrescribe el original salvo que pases out_path apuntando a el.
• weld=True es imprescindible para las mallas cube-soup de VoxelToMeshBasic (4 vertices por cara sin compartir aristas). Con weld=False sobre una cube-soup el quadric edge collapse no reduce caras. Solo pon weld=False si sabes que la malla ya tiene topologia soldada y quieres preservarla exacta.
• Vertex colors: pymeshlab los interpola a traves del collapse y se readjuntan fielmente (verificado). Textura+UV: la reproyeccion de UV es por vertice mas cercano (scipy cKDTree), aproximada — fiel para mallas densas, puede mostrar ligero corrimiento en bordes de isla UV; la imagen de textura se readjunta sin recortar. La via de raiz para malla texturizada estanca es generar con VoxelToMesh algorithm='surface net' (ver report 0088), no este post-proceso.
• El voxel-remesh de comfyui_make_watertight descarta la apariencia; si quieres malla ligera Y con color, decima con esta funcion y NO la pases por watertight voxel (o reproyecta el color despues).
• Requiere trimesh + pymeshlab + scipy en el venv del registry (cd python && uv add trimesh pymeshlab scipy). Sin ellas devuelve ok=False con el detalle.