feat(infra): auto-commit con 56 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-21 14:22:55 +02:00
parent c1071a82b3
commit 32c7336bf6
56 changed files with 5307 additions and 100 deletions
@@ -0,0 +1,83 @@
+---
+name: depth_to_relief_glb
+kind: function
+lang: py
+domain: datascience
+version: "1.0.0"
+purity: impure
+signature: "def depth_to_relief_glb(image: Image.Image, depth: np.ndarray, out_glb_path: str, z_scale: float = 0.35, max_dim: int = 220) -> dict"
+description: "Construye una malla de relieve (heightmap) texturizada a partir de un mapa de profundidad + la imagen original y la exporta como glTF binario (.glb). El depth se vuelve el eje Z de un grid regular de vertices y la imagen se mapea como textura UV. Paso 2 del flujo img->3D (grupo img-to-3d): consume la salida de estimate_image_depth."
+tags: [img-to-3d, datascience, mesh, glb, gltf, relief, heightmap, trimesh, 3d, texture]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: image
+    desc: "PIL.Image RGB usada como textura de la malla. Tipicamente la 'image' devuelta por estimate_image_depth (la imagen original)."
+  - name: depth
+    desc: "ndarray HxW float32 en [0,1] (1=mas cerca). Tipicamente el 'depth' devuelto por estimate_image_depth. Si ndim != 2 se devuelve status error."
+  - name: out_glb_path
+    desc: "Ruta de salida del .glb. El directorio padre debe existir (si no, la exportacion de trimesh falla -> status error)."
+  - name: z_scale
+    desc: "Amplitud del relieve como fraccion del lado de la malla (default 0.35). Mayor = relieve mas pronunciado/exagerado."
+  - name: max_dim
+    desc: "Lado maximo del grid tras downsample bilineal (default 220, ~48k vertices / ~96k caras). Controla resolucion de la malla vs tamano del .glb. Imagenes mayores se reducen; menores se dejan igual."
+output: "dict. Exito: {status:'ok', glb_path:str, vertices:int, faces:int, height:int, width:int}. Error: {status:'error', error:str} (depth con forma invalida, directorio de salida inexistente, fallo de trimesh.export). No lanza."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/datascience/depth_to_relief_glb.py"
+---
+
+## Ejemplo
+
+```python
+# Requiere un venv con torch + transformers + trimesh + pillow (el de apps/img_to_3d_webapp/backend/.venv).
+# Import PLANO a los modulos (el paquete datascience.__init__ arrastra deps de otros dominios).
+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
+
+est = estimate_image_depth("apps/img_to_3d_webapp/samples/cats.jpg")
+assert est["status"] == "ok"
+
+res = depth_to_relief_glb(est["image"], est["depth"], "/tmp/cats_relief.glb", z_scale=0.35, max_dim=220)
+print(res["status"], res["vertices"], res["faces"])   # ok 48400 96114
+print(res["glb_path"])                                 # /tmp/cats_relief.glb (cargable con useGLTF/GLTFLoader)
+```
+
+Lanzable end-to-end (el demo CLI encadena estimate_image_depth internamente):
+
+```bash
+./fn run depth_to_relief_glb_py_datascience apps/img_to_3d_webapp/samples/cats.jpg /tmp/cats_relief.glb
+# {"status": "ok", "glb_path": "/tmp/cats_relief.glb", "vertices": ..., "faces": ..., ...}
+```
+
+## Cuando usarla
+
+Tras `estimate_image_depth`, cuando quieras un modelo 3D real (no solo el mapa de profundidad):
+visualizar una foto en relieve navegable, exportar a un visor web (three.js `useGLTF`/`GLTFLoader`,
+Babylon, model-viewer) o a cualquier herramienta que lea glTF. Es el paso 2 (final) del grupo
+`img-to-3d`. Usa `max_dim` para equilibrar detalle vs peso del .glb y `z_scale` para exagerar o
+suavizar el relieve.
+
+## Gotchas
+
+- **Impura**: escribe el archivo .glb en `out_glb_path`. El directorio padre debe existir o
+  `trimesh.export` falla (vuelve como status error, no crash).
+- **Dep**: requiere `trimesh` (4.5.x) + `pillow` + `numpy`. `trimesh` se importa dentro de la
+  funcion. No esta en el venv del registry; vive en el venv de la app `img_to_3d_webapp`.
+- **No es reconstruccion real de geometria**: es un heightmap (relieve 2.5D). Solo deforma un
+  plano segun la profundidad; no recupera las caras ocultas ni el volumen trasero del objeto.
+- El downsample a `max_dim` usa interpolacion bilineal sobre el depth cuantizado a uint8 (0-255)
+  para reescalar; introduce una ligera perdida de precision en la profundidad de la malla.
+- UV con V invertido (`1 - v`) por convencion glTF; la textura es la imagen convertida a RGB.
+- `process=False` en Trimesh: no se hace merge de vertices ni limpieza, para preservar la
+  correspondencia 1:1 vertice<->pixel (necesaria para el mapeo UV del grid).
+- **Import plano**: importa el modulo directo, NO `from datascience import ...` (el `__init__` del
+  paquete arrastra deps de otros dominios ausentes en el venv de vision). Ver misma gotcha en
+  `estimate_image_depth`.