architecture

Arquitectura

Resumen de la estructura del proyecto, flujo de datos y diseño del engine.

Estructura del Proyecto

agribound/
├── agribound/                     # Librería core
│   ├── config.py                  # Dataclass AgriboundConfig
│   ├── engines/                   # Engines de detección
│   │   ├── base.py               # Registry de engines + clase base abstracta
│   │   └── delineate_anything.py # Engine YOLO de segmentación de instancias
│   ├── io/                        # Utilidades de I/O
│   │   ├── crs.py                # Detección de CRS y proyección UTM
│   │   └── raster.py            # Lectura y tiling de rasters
│   ├── postprocess/              # Post-procesamiento de geometrías
│   │   ├── filter.py            # Filtrado por área
│   │   └── simplify.py          # Simplificación Douglas-Peucker
│   └── composites/               # Composición de escenas
│       └── base.py              # Lógica de composite multi-escena
├── model/                         # Framework de experimentación
│   ├── cli.py                    # Entry point CLI (run / sweep / compare)
│   ├── experiment_config.py      # Dataclasses ExperimentConfig + PostProcessParams
│   ├── framework.py             # Orquestación del ExperimentRunner
│   ├── postprocess.py           # Pipeline de post-procesamiento configurable
│   ├── data.py                  # Descarga de Sentinel-2 via Planetary Computer
│   ├── evaluate.py             # Métricas de evaluación proyectadas en UTM
│   ├── registry.py             # Integración con GitLab Model Registry
│   ├── train.py                # Runner de experimentos legacy
│   └── config.py              # Config legacy (grid hardcodeado)
├── experiments/                  # Configs YAML de experimentos
├── scripts/                     # Scripts utilitarios
│   └── convert_bounds.py       # Convertir bounds.json → reference GeoJSON + AoI WKT
├── data/input/                  # Datos de entrada
├── outputs/                     # Resultados de experimentos
├── docs/                        # Documentación
├── Dockerfile                   # Build multi-stage
├── docker-compose.yml           # Stack de desarrollo local
├── .gitlab-ci.yml              # Pipeline CI
└── pyproject.toml              # Definición del package

Flujo de Datos

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  YAML Config │────▶│ ExperimentRunner  │────▶│  Output GeoJSON │
└──────────────┘     └──────────────────┘     └─────────────────┘
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
             ┌──────────┐ ┌───────┐ ┌──────────┐
             │ Download  │ │Engine │ │Postprocess│
             │ Imagery   │ │       │ │          │
             └──────────┘ └───────┘ └──────────┘
                    │         │         │
                    ▼         ▼         ▼
             Sentinel-2   YOLO      Simplify →
             via STAC     inference  Filter →
                                    Buffer →
                                    Merge

Carga de config — El YAML se parsea en un ExperimentConfig y se valida.
Descarga de imágenes — Las escenas Sentinel-2 se obtienen de Planetary Computer via STAC, se componen en un GeoTIFF y se cachean localmente.
Inferencia del engine — El engine configurado (actualmente delineate-anything) corre la detección sobre el GeoTIFF, produciendo polígonos crudos.
Post-procesamiento — Los polígonos crudos pasan por un pipeline configurable: split espectral, simplificación, filtrado por área, buffer, merge, remoción de huecos.
Evaluación — Los polígonos predichos se comparan contra la referencia en proyección UTM, calculando coverage, precision e IoU.
Tracking — Los parámetros, métricas y artifacts se loguean en MLflow.

Diseño de Engines

Los engines siguen un patrón de registry definido en agribound/engines/base.py.

Agregar un Nuevo Engine

Crear un archivo nuevo en agribound/engines/ (ej. my_engine.py).
Implementar la clase del engine con un método delineate().
Registrarlo en ENGINE_REGISTRY en agribound/engines/base.py.

El engine recibe un AgriboundConfig y un path al GeoTIFF de entrada, y retorna un GeoDataFrame con los polígonos detectados.

Capas de Configuración

Hay dos dataclasses de configuración:

Clase	Ubicación	Propósito
`ExperimentConfig`	`model/experiment_config.py`	Nivel experimento: AoI, referencia, parámetros de sweep, elección de engine
`AgriboundConfig`	`agribound/config.py`	Nivel engine: source, paths, device, thresholds

ExperimentConfig.to_agribound_config() conecta ambas — construye un AgriboundConfig a partir de los settings del experimento más el path de la imagen descargada.

Caching

Las imágenes descargadas se cachean en outputs/.agribound_cache/delineate_anything_work/input/. Las claves del cache se derivan de los parámetros de la escena (fecha, ubicación, n_scenes). Re-ejecutar un experimento con los mismos parámetros de imagen se saltea la descarga.

Docker

El Dockerfile usa un build multi-stage:

Stage base — instala el environment conda con GDAL y dependencias geoespaciales, luego pip install -e .
Stage runtime — imagen Debian slim con solo las librerías de runtime, copia el env conda y el source de la app.

Esto mantiene la imagen final más chica asegurando que todas las dependencias nativas (GDAL, PROJ, GEOS) estén disponibles.

Arquitectura

Estructura del Proyecto​

Flujo de Datos​

Diseño de Engines​

Agregar un Nuevo Engine​

Capas de Configuración​

Caching​

Docker​