Documentación
Guía de uso, funcionalidades, fuentes de datos, arquitectura y licencias de código abierto de Vigía.
Resumen
Vigía es una plataforma de código abierto para la transformación de condiciones de vulnerabilidad social frente a amenazas naturales en cuatro municipios del Valle del Cauca, Colombia: Sevilla, Caicedonia, Zarzal y Roldanillo. Cruza fenómenos naturales de deslizamiento, inundación e incendio forestal con la población y la infraestructura crítica expuestas, combinando índices de amenaza estáticos con pronósticos y monitoreo en vivo de fuentes abiertas, y ese cruce se completa con el Índice de Vulnerabilidad Social (IVS) de la capa de Demografía, que mide la condición social previa de la población, no el peligro del lugar. Todo se consulta en un único mapa multicapa que abre directamente al entrar a Vigía.
La aplicación no mantiene una base de datos propia: cada vista es una capa de agregación en tiempo real sobre servicios geoespaciales públicos (ArcGIS, WMS, WMTS, APIs REST), descrito en detalle en Arquitectura y Fuentes de datos.
Índices de amenaza y créditos
Los índices de susceptibilidad a deslizamientos e incendios forestales que sostienen esta plataforma fueron desarrollados por RED LabOT, la Red de Laboratorios de Observación de la Tierra de las Américas.
NASA Lifelines
Vigía forma parte de la comunidad de NASA Lifelines, una iniciativa de la División de Ciencias de la Tierra de la NASA y la firma DevGlobal que impulsa el uso de datos satelitales para fortalecer la acción humanitaria.
Guía de uso
Cuatro pasos para pasar de abrir Vigía a entender el riesgo de tu vereda, con una captura de pantalla real de cada uno. Cada paso trae además una nota técnica más corta, por si quieres saber exactamente de dónde sale cada número.
Cuando abres Vigía, ya estás viendo el mapa con la capa de Riesgo compuesto activa. En el riel lateral están todas las capas: Deslizamientos, Inundaciones, Incendios, Precipitación, Sismología, Riesgo compuesto y, aparte, Clima, Demografía e Hidrantes. Toca una para encenderla o apagarla; puedes tener hasta tres activas a la vez para compararlas en el mismo mapa. Clima es un reporte del tiempo, no una amenaza.
Todo ocurre en un único lienzo MapLibre GL. Cada capa se define en lib/laboratorio/layers.ts con sus controles propios (por ejemplo, "Humedad del suelo (SMAP)" o "Fallas geológicas (SGC)"). Cuando dos capas activas se superponen visualmente aparece un aviso y se puede ajustar la opacidad de cada una. Clima, Demografía e Hidrantes no se combinan con otras capas porque comparten el mapa de una forma incompatible con los modelos de amenaza.
En la barra superior puedes filtrar por municipio (Sevilla, Caicedonia, Zarzal o Roldanillo) y cambiar entre la vista plana (2D) y la vista con relieve (3D). Cuando tengas el mapa como lo quieres, toca "Compartir vista": se copia un enlace que abre Vigía exactamente con las mismas capas, el mismo municipio y la misma zona del mapa.
El estado de la vista (capas, municipio, 2D/3D, zoom y centro) se refleja en la URL con los parámetros layers, municipio, is3D, zoom y center, y también se guarda en localStorage para recordarlo en la próxima visita. Un enlace compartido tiene prioridad sobre lo guardado.
Activa "Demografía" para ver cuántas personas viven en Sevilla, Caicedonia, Zarzal y Roldanillo, separadas por año, por pueblo o campo y por sexo, junto con el Índice de Vulnerabilidad Social (IVS) por manzana en el casco urbano. Activa "Hidrantes" y, con tu ubicación o tocando un punto del casco urbano de Sevilla, el mapa resalta el hidrante más cercano con la distancia y la ruta más corta por calles; las instituciones educativas, de salud y de gobierno cercanas aparecen como polígonos con la forma real de cada edificio.
Los números de población vienen de las proyecciones del DANE (2019–2026). El IVS combina 4 dimensiones del censo (vivienda, servicios públicos, educación y trabajo) con el nivel de amenaza vigente de cada zona; en el casco urbano se calcula por manzana y en el campo se usa el promedio municipal, como una capa plana y opcional para no fingir una precisión que el dato no tiene. La ruta al hidrante se calcula con OSRM sobre la red vial real y las instituciones se dibujan siempre como polígonos para no confundirlas con los hidrantes ni con el radio de cobertura de 100/150 m.
Toca cualquier vereda del mapa para ver una ficha con su nombre, el municipio, la población estimada y la infraestructura crítica cercana. Con la capa de "Riesgo compuesto" activa, el color de cada vereda indica la amenaza más severa entre deslizamientos, inundaciones e incendios. Si en algún momento quieres un resumen de qué es Vigía y cómo se usa, el botón "i" de la barra superior abre la ventana "Acerca de", con los créditos y la versión beta.
El nivel de riesgo compuesto es el mayor entre las amenazas normalizadas (la amenaza más alta gobierna, siguiendo la doctrina de la OMM/GDACS), mientras que el puntaje de 0 a 1 es un promedio ponderado al estilo del Índice de Riesgo INFORM. La ficha de cada vereda se arma con los mismos datos que ya se ven en el mapa; no usa generación de lenguaje ni la puerta de enlace de IA de la app.
Otros detalles útiles
Funcionalidades
Qué hace cada módulo de la plataforma.
Fuentes de datos
Vigía no tiene una base de datos propia: cada vista consulta directamente estos servicios públicos, en su mayoría abiertos y sin necesidad de autenticación.
Índices de amenaza
Capas estáticas publicadas en ArcGIS Online por RED LabOT y la Secretaría de Infraestructura del Valle del Cauca: abiertas, sin autenticación.
Pronósticos y monitoreo en vivo
Servicios internacionales gratuitos de agencias científicas y ambientales, sin necesidad de clave salvo donde se indica.
Demografía y límites administrativos
Fuentes gubernamentales y de datos abiertos usadas para población, veredas y cascos urbanos.
Infraestructura
Puntos de interés comunitarios, con la misma filosofía de datos abiertos que el resto de la plataforma.
Sismología
Actividad sísmica en vivo de la Red Sismológica Nacional de Colombia (SGC) como fuente principal, con el catálogo global del USGS como verificación y el catálogo histórico oficial del SGC, más un resumen opcional de reportes comunitarios de daños en Sevilla. Los sismos no se pueden pronosticar: estas fuentes mejoran la detección en vivo, no la predicción.
Riesgo compuesto (multiamenaza)
Sin fuente externa propia: esta categoría solo combina, en el servidor, los cinco modelos de amenaza que ya alimentan las categorías anteriores.
Metodología: modelo propio de amenaza por deslizamiento
Cálculo propio, no un índice oficialEl color del mapa de deslizamientos ya no proviene de una capa publicada por un tercero, sino de un modelo que esta misma app calcula en el servidor. Sigue, de forma simplificada, la estructura de NASA LHASA v1 (Stanley & Kirschbaum, 2017): un factor estático de susceptibilidad del terreno combinado con un disparador dinámico de lluvia reciente. Esta sección documenta paso a paso qué dato entra en cada cálculo y exactamente cómo se procesa, para que el resultado sea auditable en vez de una caja negra.
Caché por factor
Cada insumo del modelo se cachea de forma independiente, según qué tan rápido cambia, solo la primera solicitud dentro de cada ventana de caché paga el costo completo de recalcular los ~55 centroides.
- Elevación / pendiente
- 30 días, el terreno no cambia
- Red vial (Overpass)
- 6 horas, mismo caché que el resto de capas de OpenStreetMap
- Fallas geológicas (SGC)
- 30 días, la cartografía geológica no cambia
- Inventario de movimientos en masa (SGC)
- 30 días, es un inventario histórico estático
- Lluvia / disparador
- 1 hora, los días más recientes se revisan con nuevas observaciones
Qué no es este modelo
- No es una calibración validada contra deslizamientos ocurridos en la zona, los pesos y umbrales (0.35/0.15/0.2/0.3, 0.6/0.4, 45°, 1 km, 2 km, 2 km, razón de saturación 2) son elegidos por criterio propio siguiendo la estructura de LHASA v1, no ajustados con datos locales.
- LHASA v1 usa cinco predictores estáticos; este modelo reproduce tres de ellos (pendiente, vías y fallas geológicas) y suma un cuarto factor propio (movimientos en masa históricos) que LHASA v1 no incluye. Cobertura de suelo (ESA WorldCover), el único predictor de LHASA que sigue faltando, se evaluó pero se descartó: solo existe como archivo raster satelital (COG/GeoTIFF) sin una API de consulta por punto viable desde una función serverless. Geología/fallas y el inventario histórico se habían descartado por el mismo motivo hasta encontrar sus respectivas capas del SGC, que resultaron ser la excepción: vectores pequeños y directamente consultables, no rásteres.
- El inventario de movimientos históricos solo tiene 55 puntos en toda la zona de estudio y sin fecha de ocurrencia confiable, es evidencia real de inestabilidad pasada, pero disperso y no exhaustivo. Que una vereda quede lejos de los 55 puntos conocidos no significa que nunca haya tenido un movimiento en masa, solo que ninguno quedó registrado en este inventario.
- Se calcula en el centroide de cada vereda, no en una grilla densa, una sola pendiente y distancia a vía representan a toda la vereda, a diferencia de los ~11.721 puntos que sí tenía la capa de RED LabOT dentro de su área de cobertura.
Metodología: modelo propio de amenaza por inundación
Cálculo propio, no un índice oficialLa capa "Modelo propio de inundación" del mapa de inundaciones extiende la zonificación oficial de RED LabOT que solo cubre el área zonificada de Sevilla y Caicedonia, a los cuatro municipios, incluidos Zarzal y Roldanillo, calculando un puntaje propio por vereda. La zonificación oficial no se descarta: es, al contrario, el insumo de mayor peso del modelo, donde tiene cobertura.
Caché por factor
- Zonificación oficial de inundación
- 1 hora, mismo caché que la capa pública original
- Hidrografía (quebradas y ríos)
- 30 días, el curso de un cauce cambia muy lentamente
- Pendiente / planicie
- reutilizada, es el mismo valor ya cacheado por el modelo de deslizamiento
Qué no es este modelo
- No es un modelo hidráulico ni hidrológico, no simula caudal, láminas de agua ni tiempos de llegada de una creciente. Es una susceptibilidad relativa por vereda, del mismo tipo que la zonificación oficial que extiende, no un pronóstico de inundación (para eso está el pronóstico de caudal en vivo de GEOGLOWS, ya en el mismo mapa).
- La capa de hidrografía usada para el factor de cercanía a cauces solo tiene 19 trazas con nombre, es una aproximación a la red de drenaje real, no un mapa completo de todo arroyo o canal menor.
- Los pesos y umbrales (0.5/0.3/0.2, 1 km, 8°) son elegidos por criterio propio, siguiendo la misma lógica de factores-por-distancia-e-inclinación del modelo de deslizamiento, no ajustados con datos locales de inundaciones ocurridas.
- Cada traza de cauce de la capa de hidrografía trae también un identificador (rivid) que coincide con el esquema de tramos que ya usa el pronóstico de GEOGLOWS en este mapa, un posible factor dinámico futuro (p. ej. ponderar por el período de retorno en vivo del tramo más cercano), señalado aquí pero no implementado: a diferencia de cada otro insumo de este modelo, que es una sola consulta cacheada, eso implicaría decenas de consultas individuales por tramo en cada solicitud.
Metodología: modelo propio de amenaza por incendios forestales
Cálculo propio, no un índice oficialEl color del mapa de incendios ya no proviene de la zonificación oficial (PBOT 2014, `AmenazaIncendios`), a diferencia de las capas de zonificación que sí siguen aportando al modelo de deslizamiento y de inundación, esa capa es una digitalización estática de un plan de uso del suelo de 2014, sin ningún modelo computacional detrás que replicar. En su lugar, esta sección documenta el modelo propio que esta misma app calcula: pendiente y cercanía a vías (reutilizadas del modelo de deslizamiento), recurrencia histórica de NASA FIRMS y el Índice Meteorológico de Incendio (FWI) de hoy, calculado con las ecuaciones estándar del Sistema Canadiense de Índices Forestales de Incendio (Van Wagner, 1987), el mismo sistema detrás de la capa de pronóstico FWI de Copernicus GWIS/EFFIS ya disponible en el mapa, pero calculado aquí de forma independiente a partir de datos meteorológicos crudos.
Caché por factor
- Pendiente / vía (reutilizadas)
- reutilizada, mismo caché ya pagado por el modelo de deslizamiento
- Recurrencia histórica (NASA FIRMS)
- 6 horas, una ventana pasada de detecciones no cambia una vez publicada
- Meteorología / FWI
- 1 hora, los días más recientes se revisan con nuevas observaciones
Qué no es este modelo
- No es una calibración validada contra incendios ocurridos en la zona, los pesos y umbrales (0.25/0.15/0.6, 0.6/0.4, 45°, 1 km, 2 km, 3 detecciones, FWI = 30, 60 días de arranque) son elegidos por criterio propio siguiendo la misma estructura de factor estático + disparador dinámico que el modelo de deslizamiento, no ajustados con datos locales de incendios ocurridos.
- Las ecuaciones del FWI en sí no son una invención de esta app, son el sistema estándar publicado por el Servicio Forestal de Canadá (Van Wagner, 1987), transcritas ecuación por ecuación desde la implementación de referencia en R (paquete cffdrs). Lo que sí es propio de esta app es calcularlas aquí, en vez de leerlas de la capa WMS de GWIS/EFFIS (que no permite extraer un valor por punto), y los 60 días de arranque elegidos para esta latitud ecuatorial, para los que el sistema no publica un valor de referencia.
- La ventana de recurrencia histórica (150 días, las cuatro fuentes FIRMS) es una muestra de detecciones activas recientes, no un catálogo completo de todo incendio ocurrido alguna vez en la zona, un incendio anterior a esa ventana, o demasiado pequeño/breve para cualquiera de los sensores satelitales de FIRMS, no cuenta hacia este factor.
- Se calcula en el centroide de cada vereda, no en una grilla densa, un solo valor de FWI y un solo conteo de recurrencia representan a toda la vereda.
Metodología: riesgo compuesto (multiamenaza)
Cálculo propio, no un índice oficialLa capa "Riesgo compuesto" combina las cinco amenazas que esta app ya modela por vereda deslizamientos, inundaciones (modelo propio), incendios forestales (modelo propio), precipitación y sismología, en una sola evaluación, siguiendo dos enfoques ya usados en la práctica internacional en vez de inventar uno nuevo: la doctrina de la OMM/GDACS de que "la amenaza más alta gobierna" para el nivel de alerta, y la composición ponderada al estilo del Índice de Riesgo INFORM para un puntaje continuo de referencia. El resultado se traduce además al marco de acción Informar/Prepararse/Actuar que ya usa IDEAM en Colombia.
Caché por insumo
Este módulo no introduce nuevas fuentes externas, cada insumo hereda el caché que ya tenía en su propia categoría.
- Deslizamientos e inundaciones
- reutilizada, mismo caché que cada modelo individual (vía aggregateVeredas)
- Incendios forestales (cruce por centroide)
- 1 hora, mismo caché que la capa AmenazaIncendios original
- Precipitación (Open-Meteo, 7 días)
- 3 horas, mismo caché que /api/precipitacion/amenaza
- Sismología (USGS en vivo / SGC histórico)
- 5 min / 1 día, mismo caché que /api/sismologia/eventos
Qué no es este modelo
- No incluye el pronóstico de caudal en vivo de GEOGLOWS. Ese pronóstico es por tramo de río, no por vereda, y cruzarlo con ~55 veredas exigiría decenas de consultas de identificación de tramo en vivo por solicitud, una integración pesada y frágil fuera del alcance de esta primera versión. La amenaza "inundaciones" en el riesgo compuesto es, en cambio, el modelo propio de inundación por vereda (zonificación + cercanía a cauce + planicie del terreno) que ya representa esa amenaza en las otras tres categorías.
- No usa un modelo de lenguaje ni la puerta de enlace de IA de esta app. El reporte narrativo es texto de plantilla determinista, relleno con los mismos números que ya se muestran en el mapa y el panel, nunca generación libre.
- Los pesos iguales de 25% por amenaza y los umbrales de nivel (0.2/0.4/0.6/0.8) son una elección de diseño razonable, no una calibración validada contra eventos multiamenaza ocurridos en la zona, igual que cada modelo individual que combina.
- Precipitación no tiene un puntaje continuo propio publicado, así que su contribución al puntaje compuesto es una aproximación ordinal (índice de nivel entre los niveles totales), a diferencia de deslizamientos, inundaciones e incendios, que sí aportan una medida continua nativa de su propio modelo.
Marco teórico
De la "gestión del riesgo" a la transformación estructural. Esta sección explica por qué el panel de Demografía habla de vulnerabilidad social en vez de desastres naturales, y qué implica esa diferencia para leer el Índice de Vulnerabilidad Social (IVS) que calcula esta plataforma.
1. Crítica a la categoría "desastre natural"
La categoría "desastre natural" naturaliza lo que en realidad es producto histórico: presenta como inevitable una pérdida que resulta de decisiones concretas sobre dónde se permite construir, qué vivienda se ofrece a quién y qué servicios públicos se mantienen durante décadas. También individualiza la responsabilidad: culpa a quien "vive en un lugar peligroso" en vez de preguntar por qué vive ahí. Esta plataforma no predice desastres naturales porque, en ese sentido, no existen: existen fenómenos naturales una crecida, un sismo, un deslizamiento, y existen condiciones sociales previas que convierten ese fenómeno en catástrofe para una población específica y no para otra.
2. Riesgo como decisión, no como fenómeno
La teoría de sistemas de Niklas Luhmann distingue riesgo de peligro: el riesgo es contingencia atribuible a una decisión; el peligro es contingencia del entorno. Quien "decide" producir el daño no es la crecida ni el sismo, sino quienes permiten asentamientos en zonas expuestas sin infraestructura adecuada, no garantizan vivienda digna para la población de menores ingresos, o mantienen servicios públicos precarios durante años. Un IVS alto en Sevilla, Caicedonia, Zarzal o Roldanillo no describe un "riesgo natural" de ese lugar: describe el resultado acumulado de decisiones (o de su ausencia) sobre ese lugar.
3. Vulnerabilidad como relación social, no como atributo
La vulnerabilidad no es un atributo inherente de una persona o de un lugar: resulta de relaciones de producción que concentran la tierra buena en pocas manos y empujan a otros hacia laderas inestables, que mercantilizan la vivienda hasta volver inaccesible el suelo seguro, y que precarizan el trabajo hasta volver imposible invertir en mejorar una casa. Un mismo aguacero (tesis) sobre una misma ladera no produce el mismo resultado en dos hogares con vulnerabilidad social distinta (antítesis), lo que llamamos "desastre" es esa exposición diferencial a la pérdida, no una síntesis natural.
4. Qué implica esto para decidir
El IVS por sí solo no prioriza nada, cruzado con el riesgo físico compuesto que ya calcula esta plataforma, sí señala dónde invertir primero. Cuatro frentes concretos, en orden decreciente de urgencia cuando el IVS y el riesgo físico coinciden en un mismo lugar:
- Municipios con IVS combinado alto. Donde el IVS coincide con un riesgo compuesto alto o muy alto: inversión pública extraordinaria en infraestructura básica, mejoramiento integral de vivienda y regularización de tenencia de la tierra, antes que reasentamiento forzoso.
- Control urbano preventivo. En manzanas o veredas donde la exposición física ya es alta, restringir nuevos asentamientos sin infraestructura adecuada y exigir estándares de construcción realistas para la capacidad económica local.
- Universalización de servicios. Acueducto y alcantarillado como derecho, no como mercancía, es la dimensión con mayor peso individual (25%) en el IVS precisamente porque su ausencia es la más directamente atribuible a decisión pública, no a geografía.
- Cobertura educativa y dependencia económica. Donde Educación o Trabajo dominan el IVS de un municipio, la respuesta no es un mapa: es transporte escolar subsidiado y programas de formalización laboral, el dato solo señala dónde falta esa inversión.
5. Límites de este índice
Ningún índice cuantitativo captura la totalidad de una experiencia vivida. Los datos del IVS provienen del Censo Nacional de Población y Vivienda 2018 del DANE, tienen un rezago de varios años y no incluyen la dimensión de Salud, que esta plataforma excluye explícitamente en vez de inventarla, por falta de un dato municipal 2018 confiable para estos 4 municipios (ver la explicación completa en el panel de Demografía). Georeferenciar la vulnerabilidad puede estigmatizar un territorio si se usa sin este contexto. El compromiso de esta plataforma es que el dato se use para exigir transformación de condiciones, no para etiquetar poblaciones como "en riesgo", la vulnerabilidad mide ausencia de derechos, no ausencia de capacidad humana.
Referencias teóricas
- Luhmann, N. (1993). Risk: A Sociological Theory. Walter de Gruyter.
- Wisner, B., Blaikie, P., Cannon, T. y Davis, I. (2004). At Risk: Natural Hazards, People's Vulnerability and Disasters (2.ª ed.). Routledge.
- Maskovsky, J. (2001). Beyond Disaster Relief: Toward an Anthropology of Emergency. Journal of Latin American and Caribbean Anthropology.
Arquitectura
Cómo está construida la plataforma, de la interfaz al dato.
Framework y renderizado
Next.js 16 (App Router) con React 19 y TypeScript. Las páginas son Server Components por defecto; los mapas y controles interactivos se marcan "use client" solo donde necesitan estado o efectos del navegador.
Acceso a datos, sin base de datos propia
Cada fuente externa tiene un módulo server-only en lib/<amenaza>/client.ts que llama directamente a su API/WMS/WMTS pública. No hay capa de persistencia: la app es una capa de agregación en vivo sobre servicios públicos ya existentes.
Rutas de API y hooks de datos
Cada módulo servidor se expone mediante una ruta en app/api/**/route.ts, que envuelve el resultado en un sobre JSON consistente ({ data } o { error }) con manejo de errores. Los componentes cliente consumen esas rutas con hooks de SWR (lib/**/use-*.ts) para caché y revalidación en el navegador.
Estrategia de caché
El caché de fetch de Next (next: { revalidate }) se ajusta por fuente según qué tan rápido cambia: FIRMS cada 15 min, capas de ArcGIS cada hora, límites administrativos cada semana, y las proyecciones del DANE no hacen ninguna llamada de red, se leen de un JSON estático versionado en el repositorio.
Mapas
MapLibre GL, vía react-map-gl, importado dinámicamente con next/dynamic({ ssr: false }) para evitar que el renderizado en servidor choque con las dependencias de window/document del motor de mapas. Un único lienzo con capas combinables (hasta tres a la vez) y vista 3D: cada capa aporta fuentes GeoJSON, capas de símbolos/círculos, teselas vectoriales y overlays raster o WMS según la forma de su fuente, todo compuesto en un único WebGL canvas.
Estilos y sistema de diseño
Tailwind CSS v4 con tokens de diseño definidos en app/globals.css (escalas de color en oklch por amenaza/categoría), componentes de shadcn/ui sobre primitivas de Base UI, y next-themes para el tema claro/oscuro/sistema.
Estado compartible de la vista
El estado del mapa (capas activas, municipio, vista 2D/3D, zoom y centro) se serializa en la URL con los parámetros layers, municipio, is3D, zoom y center, y se guarda además en localStorage (lib/laboratorio/layers.ts). Así "Compartir vista" produce un enlace reproducible, y una visita sin enlace ni estado guardado abre con la capa de Riesgo compuesto. La documentación abre en una pestaña normal del navegador porque es contenido extenso pensado para desplazarse, imprimirse o guardarse como marcador.
Exportación a PDF
Los botones "Exportar como PDF" de los reportes de Riesgo compuesto y Demografía usan html2canvas-pro para capturar el panel como imagen (se eligió sobre el html2canvas original, sin mantenimiento, porque este último no soporta las funciones de color CSS modernas lab()/oklch(), que usan los tokens de Tailwind v4) y jsPDF para componer el documento final.
Despliegue
Vercel. Vercel Analytics solo se activa en producción (process.env.NODE_ENV === 'production').
Licencia y uso del código
El repositorio de Vigía es público para que cualquiera pueda leer su código, auditarlo y aprender de él, creado por Alejandro Pino (SIG · Director Técnico). La plataforma en sí, el sitio que estás usando, es de uso público y gratuito. El código fuente, en cambio, todavía no tiene una licencia de código abierto: las dependencias que trae la app sí la tienen y se listan a continuación, agrupadas por su propia licencia.