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,87 @@
+---
+name: estimate_image_depth
+kind: function
+lang: py
+domain: datascience
+version: "1.0.0"
+purity: impure
+signature: "def estimate_image_depth(image_path: str, model_name: str = 'depth-anything/Depth-Anything-V2-Small-hf', device: str = 'auto', use_cache: bool = True) -> dict"
+description: "Estima un mapa de profundidad monocular a partir de una sola imagen con Depth-Anything-V2 (transformers, GPU si hay). Devuelve el depth normalizado a [0,1] (1=mas cerca) y la PIL.Image original. Paso 1 del flujo img->3D (grupo img-to-3d): su salida alimenta depth_to_relief_glb."
+tags: [img-to-3d, datascience, depth, depth-estimation, monocular, transformers, depth-anything, gpu, ml, computer-vision]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: []
+params:
+  - name: image_path
+    desc: "Ruta a la imagen de entrada. Cualquier formato que PIL.Image.open abra (jpg, png, webp...). Si no existe o no es imagen valida, se devuelve status error."
+  - name: model_name
+    desc: "Id de modelo HuggingFace de depth-estimation. Default 'depth-anything/Depth-Anything-V2-Small-hf' (rapido). Variantes: ...-Base-hf, ...-Large-hf (mas precision, mas VRAM)."
+  - name: device
+    desc: "'auto' (GPU0 si torch.cuda.is_available() else CPU), 'cpu', o indice/cadena cuda explicita ('cuda:0', '0'). Forma 'cuda:N' no parseable cae a GPU0; un indice entero inexistente ('99') falla en inferencia y vuelve como status error."
+  - name: use_cache
+    desc: "True (default) reutiliza el pipeline cacheado por (model_name, device) a nivel de proceso (evita recargar pesos en cada llamada). False construye uno nuevo y no toca la cache."
+output: "dict. Exito: {status:'ok', depth: ndarray HxW float32 en [0,1] (1=mas cerca de la camara), image: PIL.Image RGB original, height:int, width:int, model:str, device:str}. Error: {status:'error', error:str} (no lanza). El demo CLI (__main__) imprime un resumen JSON sin el ndarray ni la imagen."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/datascience/estimate_image_depth.py"
+---
+
+## Ejemplo
+
+```python
+# Requiere un venv con torch + transformers + pillow (p.ej. el de apps/img_to_3d_webapp/backend/.venv).
+# Import PLANO al modulo: el paquete datascience.__init__ arrastra deps de otros dominios
+# (bs4, duckdb...) que no estan en ese venv. Ver Gotchas.
+import sys
+sys.path.insert(0, "python/functions/datascience")
+from estimate_image_depth import estimate_image_depth
+
+res = estimate_image_depth("apps/img_to_3d_webapp/samples/cats.jpg")  # device='auto' -> GPU si hay
+print(res["status"])                       # ok
+print(res["height"], res["width"])         # p.ej. 1024 768
+print(res["depth"].min(), res["depth"].max())  # 0.0 1.0 (normalizado)
+# res["depth"] (ndarray) + res["image"] (PIL) alimentan depth_to_relief_glb.
+```
+
+Lanzable como demo (imprime resumen JSON, sin serializar el ndarray):
+
+```bash
+./fn run estimate_image_depth_py_datascience apps/img_to_3d_webapp/samples/cats.jpg
+# {"status": "ok", "height": ..., "width": ..., "depth_min": 0.0, "depth_max": 1.0, ...}
+```
+
+## Cuando usarla
+
+Cuando necesites un mapa de profundidad de una imagen 2D y NO tengas sensor de profundidad:
+reconstruccion de relieve 3D (paso 1 de img->glb), efectos de paralaje, segmentacion por capas,
+ordenacion de objetos por cercania. Es el primer paso del grupo `img-to-3d`: su `depth` + `image`
+se pasan directamente a `depth_to_relief_glb_py_datascience` para generar el .glb. Para una sola
+imagen monocular; no hace SLAM, multi-vista ni metrica absoluta (la profundidad es relativa).
+
+## Gotchas
+
+- **Impura**: carga un modelo HuggingFace (la primera vez DESCARGA pesos a `~/.cache/huggingface/`,
+  cientos de MB segun la variante) y corre inferencia en GPU/CPU. Requiere red en la primera carga.
+- **Estado de proceso**: `_PIPE_CACHE` cachea el pipeline por (model_name, device) a nivel de
+  modulo para no recargar pesos en cada llamada. Es estado mutable compartido del proceso. Pasa
+  `use_cache=False` para construir uno aislado (no lo cachea ni lo lee). La cache persiste mientras
+  viva el interprete; en un servicio de larga duracion ocupa VRAM hasta que el proceso muere.
+- **Deps pesadas**: requiere `torch`, `transformers` y `pillow` instalados. No estan en el venv del
+  registry; viven en el venv de la app `img_to_3d_webapp` (torch 2.5.1+cu124). `torch`/`transformers`
+  se importan dentro de la funcion, asi que el modulo se puede importar para introspeccion sin ellas.
+- **device**: 'auto' usa GPU0 si `torch.cuda.is_available()`. El resolver es tolerante con la
+  forma `'cuda:N'`: si `N` no es parseable junto a 'cuda', cae a GPU0 (p.ej. `'cuda:99'` -> GPU0,
+  NO error). En cambio un indice ENTERO inexistente (`'99'`) se pasa tal cual a transformers y
+  falla en inferencia con `CUDA error: invalid device ordinal`, devuelto como `{status:'error'}`.
+- La profundidad es **relativa y normalizada a [0,1]**, no metrica. 1 = mas cerca de la camara
+  (Depth-Anything devuelve disparidad). No comparable entre imagenes distintas.
+- Nunca lanza: errores (ruta invalida, modelo no disponible, OOM de GPU) vuelven como
+  `{status:'error', error:str}`.
+- **Import plano**: importa el modulo directo (`sys.path` a `python/functions/datascience` +
+  `from estimate_image_depth import estimate_image_depth`), NO `from datascience import ...`. El
+  `datascience.__init__` carga todo el dominio (scrapers con bs4, duckdb...) que no esta en el venv
+  de vision; el import del paquete fallaria por esas deps ajenas a esta funcion.