fn_registry/python/functions/datascience/estimate_image_depth.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
estimate_image_depth	function	py	datascience	1.0.0	impure	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	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.	img-to-3d datascience depth depth-estimation monocular transformers depth-anything gpu ml computer-vision				false	error_go_core		name desc image_path 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 desc model_name 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 desc device '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 desc use_cache 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.	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.	false			python/functions/datascience/estimate_image_depth.py

Ejemplo

# 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):

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