---
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.