shade-engine

Precalcular mapas de sombra por fecha y hora explota: cada día del año por cada cuarto de hora son miles de rásteres por ciudad. shade-engine guarda algo mejor: para cada metro cuadrado de la ciudad, el ángulo de elevación que tapa el cielo en cada una de 64 direcciones de brújula - la huella del horizonte de ese píxel, barrida una sola vez desde el modelo de superficie LiDAR con el observador a pie de calle. Cualquier consulta de sombra se reduce entonces a una comparación: ¿está el sol, calculado para el instante pedido con una librería astronómica, por debajo del horizonte de ese píxel hacia su azimut? Un build offline por ciudad, consultas de milisegundos, válido para cualquier fecha - pasada o futura.

La entrada es PNOA, el programa abierto de LiDAR aéreo de España: para la mayor ciudad desplegada hasta ahora, 90 teselas y 738 millones de puntos clasificados. La pipeline los agrega en un modelo de superficie (con edificios y copas), un modelo de terreno y un ráster de cobertura, y después barre el horizonte por píxel y sector. Los artefactos se publican como Cloud Optimized GeoTIFF: rásteres tileados internamente cuyo layout permite a la API responder una pregunta de un píxel descomprimiendo kilobytes, no gigabytes. Los puntos bajo copa de árbol se tratan explícitamente: el horizonte calculado a pie de calle no puede ver la copa que tiene encima, así que una máscara de copa dedicada (vegetación de más de 2,5 m, filtrada de ruido) lo corrige.

La construcción del horizonte es una marcha de rayos. Para cada uno de los 64 sectores de brújula, el barrido avanza desde cada píxel hasta 500 m llevando el máximo acumulado de atan((altura del bloqueador - altura del observador) / distancia), con el observador a 1,6 m; lo que sobrevive es el ángulo que tapa el cielo en esa dirección. Bien vectorizado, el recorrido son unos pocos cortes de array por dirección en vez de un bucle por píxel, y una ciudad de 56 km² - 56 millones de píxeles por 64 sectores - se construye en una noche. Los ángulos se guardan cuantizados a 8 bits (pasos de 0,35°), lo que deja el cubo de horizonte de una ciudad entera en unos pocos gigabytes.

El mapa de arriba no renderiza sombra bajo demanda. Un paso de la pipeline compara el ráster completo de la ciudad contra la posición del sol de 83 instantes preestablecidos y empaqueta cada resultado en dos ficheros PMTiles - sombra de edificios y sombra de arbolado, conmutables por separado - más dos capas estáticas para las copas y la huella LiDAR de los edificios. Cada fichero es una pirámide completa de teselas, indexada para que el navegador pida cualquier tesela con peticiones HTTP de rango. Los interiores de edificio van transparentes: el overlay muestra solo la sombra a pie de calle. La sombra de un instante fijo es inmutable, así que los ficheros se cachean para siempre y el servidor web solo sirve bytes; el motor nunca se consulta al visualizar. El mapa base es un extract autoalojado de OpenStreetMap en el mismo formato: toda la demo funciona sin servicios de tiles externos y sin API keys.

83 instantes suenan a muchos hasta que ves que solo abarcan siete fechas. La trayectoria del sol sobre una ciudad se repite allí donde se repite su declinación, y la declinación es simétrica alrededor de los solsticios: el recorrido del sol a mediados de agosto calca casi exactamente el de principios de mayo. Así que la pipeline renderiza siete fechas canónicas - los solsticios, un equinoccio y cuatro peldaños intermedios - y publica una escalera que proyecta cada día del año sobre su gemelo de declinación, con unos 4° de error en el peor día. El slider de fecha de la consola de arriba es esa escalera en acción: elige cualquier día y se resuelve a su gemelo renderizado, con tiles y API coincidiendo píxel a píxel.

Las zonas de aparcamiento en calle viven en PostGIS como geometrías de línea a lo largo del bordillo. El endpoint nearby encuentra las zonas dentro de un radio (medido en metros en el CRS proyectado local, nunca en grados), muestrea cada zona cada 10 metros contra el ráster de horizonte y agrega: la fracción de la zona en sombra ahora y - avanzando el sol - hasta cuándo sigue en sombra. Ese es el número que un conductor quiere de verdad, y es el que colorea las líneas del mapa de ámbar (al sol) a verde (en sombra).

shade-engine calcula geometría, no meteorología: un día nublado no tiene línea de sombra que perseguir, y el motor no dice nada de temperatura ni de radiación. Necesita una campaña LiDAR aérea pública que aún se parezca a la ciudad: una torre nueva o una hilera de árboles talada son invisibles hasta el siguiente vuelo. Y su presupuesto de precisión (1 m en planta, preguntas a pie de calle) es la herramienta equivocada para ingeniería de fachadas o producción fotovoltaica de un tejado concreto: eso pide un CAD solar, no un ráster de horizonte a escala de ciudad. Donde brilla es en la pregunta para la que nació: en qué lado de la calle aparcar, en cualquier ciudad cubierta, para cualquier fecha, en milisegundos.

La API pública sale con rate limiting, CORS acotado a este sitio y cabeceras de caché que dicen la verdad: una consulta con instante explícito es inmutable y cacheable un día, una consulta de "ahora" no se cachea nunca. El repositorio es además un cuaderno de aprendizaje: cada concepto geoespacial que toca el motor (elección de CRS, clases LiDAR, interior de un COG, geometría solar, distorsión de Web Mercator) tiene una nota corta explicando qué es y qué trampa esconde.