GEE Area Explorer es una herramienta diseñada para validar la disponibilidad de imágenes satelitales en Google Earth Engine (GEE) según criterios espaciales y temporales. Está construida para integrarse como un paso de pre-validación en pipelines de datos, evitando cómputos innecesarios sobre colecciones masivas.
- Visión General del Sistema
- Arquitectura de Software
- Descripción Detallada de Módulos
- Base de Datos de Colecciones
- Instalación y Configuración
- Guía de Uso (Tutorial Completo)
- Mantenimiento del Sistema
- Solución de Problemas
Al interactuar con Google Earth Engine mediante programación, surgen desafíos comunes como la gestión de la disponibilidad de datos y la optimización de consultas para evitar errores de timeout. Intentar acceder a una colección deprecada, privada o realizar un filtrado espacial sobre millones de imágenes puede detener un flujo de trabajo automatizado.
GEE Area Explorer aborda estos problemas mediante:
- Validación API-First: Utiliza la API REST de GEE (
ee.data) para verificar la existencia y metadatos de las colecciones sin instanciar objetos pesados en el servidor de cómputo. - Inventario Local: Mantiene un registro JSON persistente de las colecciones validadas, actuando como una caché para acelerar las consultas.
- Búsqueda Optimizada: Implementa estrategias de filtrado (ej.
limit) previas a la materialización de resultados para prevenir el desbordamiento de memoria en el cliente. - Despliegue Contenerizado: Se distribuye como un contenedor Docker, encapsulando el entorno de ejecución y sus dependencias (Python, GDAL) para garantizar la portabilidad y consistencia.
El sistema está construido en Python 3.12 bajo una arquitectura modular. La interacción se realiza exclusivamente a través de la línea de comandos (CLI), permitiendo su ejecución en servidores o entornos automatizados.
gee_area_explorer/
├── config/
│ └── colecciones_gee.json # [PERSISTENCIA] Base de datos JSON con metadatos de colecciones.
├── src/
│ └── gee_toolkit/ # [NÚCLEO] Paquete Python principal.
│ ├── __init__.py # Inicializador del paquete.
│ ├── api_utils.py # [UTILIDAD] Decoradores para manejo de excepciones GEE.
│ ├── auth_utils.py # [SEGURIDAD] Gestión de credenciales y sesiones.
│ ├── analysis.py # [LÓGICA] Algoritmos de intersección espacial y filtrado.
│ ├── catalog.py # [LÓGICA] Gestión del ciclo de vida del catálogo.
│ ├── config.py # [CONFIG] Carga de variables de entorno.
│ └── geo_utils.py # [UTILIDAD] Lectura y transformación de GeoJSON.
├── scripts/
│ ├── gee_search.py # [CLI] Punto de entrada para búsquedas interactivas.
│ ├── maintain_catalog.py # [CLI] Herramienta de mantenimiento del catálogo.
│ ├── generate_docs.py # [DOCS] Generador de documentación Markdown.
│ └── test_integral.py # [TEST] Script de validación de integración.
├── docker/
│ ├── Dockerfile # Definición de la imagen del sistema.
│ └── docker-entrypoint.sh # Script de arranque del contenedor.
├── data/
│ └── geojson/ # [INPUT] Directorio para archivos de área de interés.
├── output/ # [OUTPUT] Directorio para reportes generados.
└── requirements.txt # Dependencias de Python.
A continuación se detalla la responsabilidad y funcionamiento de los módulos críticos en src/gee_toolkit.
Este script es el punto de entrada principal. Actúa como el orquestador que conecta al usuario con el motor del toolkit.
Responsabilidades y Flujos:
- Gestión de Entrada: Soporta modo interactivo (menús) y modo directo (vía argumentos).
- Menú Principal (Opciones):
- Opción 1: Análisis Rápido: Ejecuta una búsqueda pre-configurada de Sentinel-2 sobre el área de ejemplo (Ñuñoa) para validar que el sistema responde correctamente.
- Opción 2: Búsqueda Personalizada: El flujo más robusto. Permite:
- Selección de Colección: Mediante sub-menú (filtrado por nombre, navegación por categorías, búsqueda por nivel de procesamiento o ingreso directo de ID).
- Selección de Área: Escaneo automático de
data/geojson/permitiendo elegir el archivo por número. - Parámetros: Definición de fechas (con sugerencias automáticas basadas en la colección) y límite de nubes.
- Opción 3: Auditoría de Niveles: Muestra un resumen técnico de todos los niveles de procesamiento (L1C, L2A, TOA, etc.) presentes en el catálogo actual.
- Opción 4: Exportación por Nivel: Permite filtrar colecciones por un nivel específico y exportar ese listado a un archivo CSV en
output/.
- Coordinación de Búsqueda: Utiliza la clase
CatalogoGEEpara filtrar datos y llama aanalizar_cobertura_temporalpara ejecutar la lógica espacial. - Formateo de Resultados: Presenta un resumen legible en consola antes de escribir el reporte CSV final.
La clase CatalogoGEE gestiona el ciclo de vida del catálogo de metadatos (colecciones_gee.json).
Funciones Clave:
-
buscar_coleccion_api(collection_id): Verifica el estado de un activo en GEE antes de su uso. Su estrategia consiste en:- Consultar
ee.data.getAsset(id)para una validación ligera, retornandoNonesi el activo no existe o es inaccesible (404/403). - Analizar las propiedades del activo para descartarlo si está marcado como
deprecated. - Omitir la inspección profunda de imágenes para colecciones masivas (ej. Landsat), previniendo timeouts.
- Consultar
-
limpiar_invalidas(): Itera sobre el catálogo local y elimina las entradas correspondientes a activos que ya no son accesibles en GEE. -
descubrir_colecciones(providers): Funciona como un crawler que explora carpetas públicas de GEE (ej.projects/earthengine-public/assets/COPERNICUS) para identificar nuevasImageCollection.
Este módulo ejecuta las consultas espaciales y temporales contra GEE.
Funciones Clave:
-
buscar_imagenes_por_espacio(id, geometry, dates, ...): Ejecuta la consulta principal aplicando filtros en un orden optimizado:- Aplica
filterBounds(geometry)para delegar el filtrado espacial al backend de GEE. - Aplica
filterDate(start, end)para acotar temporalmente la búsqueda. - Aplica
limit(limit)antes de materializar la lista de resultados para prevenir errores de memoria.
- Aplica
-
analizar_cobertura_temporal(...): Orquesta el proceso de búsqueda, genera estadísticas agregadas (ej. imágenes por año) y exporta los resultados a un archivo CSV.
Provee decoradores para aumentar la resiliencia de la aplicación.
@retry_api_call:
Envuelve las llamadas a la API de GEE. En caso de errores transitorios (503 Service Unavailable, Timeout), puede reintentar la operación o fallar de forma controlada (raise_on_failure=False), lo cual es útil para procesos batch.
El archivo config/colecciones_gee.json funciona como una base de datos documental que almacena los metadatos de los activos GEE.
Estructura del Esquema JSON:
{
"_metadata": { "version": "2.2.0", "last_updated": "..." },
"categoria_id": {
"nombre": "Nombre de la Categoría",
"colecciones": {
"ID_GEE": {
"nombre": "Título del Dataset",
"nivel": "Nivel de Procesamiento",
"resolucion": "Resolución Nominal",
"temporal": "Rango de Fechas",
"bandas_principales": [],
"last_verified": "Timestamp"
}
}
}
}| Categoría | Descripción | Cantidad Aprox. |
|---|---|---|
opticas_alta_res |
Sentinel-2, Landsat (4-9), MODIS (Reflectancia) | ~100 |
clima |
ERA5, CHIRPS, GPM, GLDAS, WorldClim | ~300 |
vegetacion |
Índices derivados (NDVI, EVI, LAI, FPAR) | ~35 |
elevacion |
DEMs globales y locales (SRTM, ALOS, ArcticDEM) | ~3 |
sar |
Radar de Apertura Sintética (Sentinel-1, PALSAR) | ~7 |
landcover |
Mapas de cobertura (WorldCover, NLCD, Dynamic World) | ~15 |
agua |
Cuerpos de agua, recurrencia, salinidad, temperatura | ~30 |
atmosfera |
Gases traza (Sentinel-5P: NO2, CO, O3, CH4) | ~90 |
fuego |
Detección de puntos de calor y áreas quemadas | ~20 |
poblacion |
Population density and human settlements | ~15 |
Para la lista completa y detallada de todas las colecciones, consulte el Catálogo de Colecciones Completo.
- Docker y Docker Compose.
- Una cuenta de Google con acceso a Google Earth Engine.
- Un Project ID de Google Cloud Platform (GCP) habilitado para la API de GEE.
Clone el repositorio en su máquina local:
git clone https://github.com/chachr81/gee_area_explorer.git
cd gee_area_explorerCopie el archivo de ejemplo y defina su ID de proyecto:
cp .env.example .envEdite .env:
GEE_PROJECT=su-id-de-proyecto-gcpEste comando construye la imagen Docker localmente, instalando todas las dependencias.
docker-compose build cliAutorice al contenedor para usar sus credenciales de GEE. Este paso se realiza una única vez.
docker-compose run --rm cli earthengine authenticateSiga las instrucciones en la terminal: abra la URL, autorice el acceso y pegue el código de verificación. Las credenciales se guardarán en un volumen Docker (gee-credentials).
Modo diseñado para exploración y pruebas rápidas.
- Prepare su Área de Interés:
Copie su archivo GeoJSON en la carpeta
data/geojson/. - Inicie la Herramienta:
docker-compose run --rm cli
- Navegación por Menú: El menú le guiará para seleccionar una colección, un archivo de área y los parámetros de la búsqueda.
- Resultados:
La herramienta procesará la consulta y guardará un archivo CSV en el directorio
output/.
Diseñado para integrar la herramienta en flujos de trabajo automatizados.
Sintaxis General:
docker-compose run --rm cli python scripts/gee_search.py [RUTA_GEOJSON]Este comando ejecutará el análisis sobre el GeoJSON especificado usando parámetros por defecto.
Ejecuta una serie de pruebas de conexión y validación de colecciones.
docker-compose run --rm cli python scripts/test_integral.pyVerifica cada activo del catálogo contra la API de GEE y elimina las entradas inválidas.
docker-compose --profile ops run --rm maintenance python scripts/maintain_catalog.py --revalidate --clean- "Credential path not found": Indica un fallo de autenticación. Ejecute de nuevo el paso 4 de la instalación.
- "Collection query aborted after accumulating over 5000 elements": La arquitectura actual está diseñada para prevenir este error. Si ocurre, asegúrese de tener la última versión del código.
- Permisos de Escritura en Linux: Los archivos generados en
output/pertenecen al usuariorootdel contenedor. Cambie su propiedad consudo chown -R $USER:$USER output/.
Nota sobre la contribución: Este proyecto fue refactorizado y documentado con la asistencia de Gemini CLI (modelo Gemini 3 Pro). Licencia MIT.