fn_registry/docs/capabilities/img-to-3d.md

group, description

group	description
img-to-3d	Convertir una imagen 2D en un modelo 3D: estimacion de profundidad monocular (Depth-Anything-V2) + reconstruccion de una malla de relieve texturizada exportada a glTF binario (.glb).

img-to-3d — Capability Group

Cluster de funciones Python (dominio datascience) para el flujo imagen 2D → modelo 3D. A partir de una sola foto se estima un mapa de profundidad monocular con un modelo de vision y se reconstruye una malla de relieve (heightmap) texturizada con la imagen original, exportada como .glb cargable por cualquier visor glTF (three.js useGLTF/GLTFLoader, Babylon, model-viewer).

Promovido desde la app img_to_3d_webapp (su backend incrustaba estas dos funciones; ver su backend/depth.py). El flujo canonico es de dos pasos encadenados:

estimate_image_depth (imagen -> depth+image) -> depth_to_relief_glb (depth+image -> .glb)

Funciones

ID	Firma corta	Que hace
estimate_image_depth_py_datascience	estimate_image_depth(image_path, model_name?, device?, use_cache?) -> dict	Estima profundidad monocular con Depth-Anything-V2 (GPU/CPU). Devuelve depth ndarray [0,1] + image PIL. Paso 1.
depth_to_relief_glb_py_datascience	depth_to_relief_glb(image, depth, out_glb_path, z_scale?, max_dim?) -> dict	Convierte depth+image en una malla de relieve texturizada y la exporta a .glb. Paso 2.
build_relief_glb_from_image_py_pipelines	build_relief_glb_from_image(image_path, out_glb_path, model_name?, device?, z_scale?, max_dim?) -> dict	Pipeline one-shot: compone los dos pasos en una sola llamada (imagen -> .glb). Salida JSON-serializable, apta para fn run.

Las tres son impuras (cargan modelo / GPU / escriben archivo), devuelven dict con status (ok/error) y nunca lanzan: los fallos vuelven como {status:'error', error:str}. El pipeline ademas marca stage (estimate/relief) en el error.

Ejemplo canonico (end-to-end imagen → glb)

# Requiere un venv con torch + transformers + trimesh + pillow + numpy.
# Import PLANO: el paquete datascience.__init__ arrastra deps de otros dominios (bs4, duckdb...)
# ausentes en el venv de vision. Ver "Fronteras / gotchas".
import sys
sys.path.insert(0, "python/functions/datascience")
from estimate_image_depth import estimate_image_depth
from depth_to_relief_glb import depth_to_relief_glb

IMG = "apps/img_to_3d_webapp/samples/cats.jpg"
OUT = "/tmp/cats_relief.glb"

est = estimate_image_depth(IMG)               # device='auto' -> GPU si hay
assert est["status"] == "ok"
# est["depth"]: ndarray HxW float32 [0,1] (1=mas cerca)  |  est["image"]: PIL.Image RGB

res = depth_to_relief_glb(est["image"], est["depth"], OUT, z_scale=0.35, max_dim=220)
assert res["status"] == "ok"
print(res["glb_path"], res["vertices"], res["faces"])   # /tmp/cats_relief.glb 36300 71832
# OUT es un glTF binario valido: trimesh.load(OUT) devuelve una Scene texturizada.

O en una sola llamada con el pipeline (recomendado para fn run / Launcher TUI):

./fn run build_relief_glb_from_image_py_pipelines apps/img_to_3d_webapp/samples/cats.jpg /tmp/cats_relief.glb
# {"status": "ok", "glb_path": "/tmp/cats_relief.glb", "vertices": 36300, "faces": 71832, ...}

Fronteras

• Es relieve 2.5D, no reconstruccion volumetrica. Deforma un plano segun la profundidad (heightmap); no recupera caras ocultas ni el volumen trasero del objeto. Para 3D real multivista/fotogrametria, NSP/Gaussian Splatting, esto NO aplica.
• Profundidad relativa, no metrica. Depth-Anything devuelve disparidad normalizada a [0,1]; no comparable entre imagenes ni en unidades del mundo real.
• No cubre el render/visualizacion. Producir el .glb es el limite del grupo. Cargarlo y subirlo a GPU (OpenGL) en una app C++/ImGui es el grupo mesh-3d (gltf_load_mesh_cpp_gfx carga justamente este tipo de .glb). img-to-3d produce; mesh-3d consume/renderiza.
• Deps pesadas y de dos mundos. Requiere torch+transformers (vision) y trimesh (mesh), que hoy viven en el venv de img_to_3d_webapp, NO en el venv del registry. Ademas el datascience.__init__ arrastra deps de scrapers (bs4...) que no estan en el venv de vision, por eso el import es plano (al modulo) y no via el paquete. fn run de estas funciones exige un venv que combine ambos mundos (torch + transformers + trimesh + las deps del dominio datascience). Ver gotchas en cada .md.

Prerequisitos

• GPU NVIDIA + CUDA recomendada (corre en CPU pero lento). Primera ejecucion descarga los pesos del modelo a ~/.cache/huggingface/ (cientos de MB segun la variante).
• Paquetes: torch, transformers, trimesh, pillow, numpy.