Un servizio per tutte le sezioni

Mappa autonoma o incorporata: https://maps.weathersicily.it/ombra/. Parametri facoltativi: lat, lon, zoom, time (ISO con fuso orario). Esempio:

<iframe title="Sole e ombra" loading="lazy"
 src="https://maps.weathersicily.it/ombra/?lat=38.117&lon=13.356&zoom=16"
 style="width:100%;height:700px;border:0"></iframe>

Edifici e alberi singoli senza perdita del contorno

import {BuildingShadows} from
 'https://maps.weathersicily.it/ombra/buildings.js?v=4';
const objects = new BuildingShadows(map, progress => {
  // Comunicare caricamento incompleto/errori e la qualità delle fonti.
});
await objects.update(); // dopo map.load, e a ogni moveend
objects.setTime(new Date(), true); // true = visibile
// Aggiungere anche ShadeGPU per montagne e superfici/vegetazione.
// Per evitare duplicazioni: client.surface(bounds, {landscape:true}).

Proiezione interattiva MapLibre

import {WeatherSicilyShade} from
 'https://maps.weathersicily.it/ombra/sdk.js?v=5';
import {ShadeGPU} from
 'https://maps.weathersicily.it/ombra/gpu.js?v=3';
const client = new WeatherSicilyShade();
const projection = new ShadeGPU(map);
// Solo al cambio di inquadratura, dopo map.load:
await projection.setSurface(await client.surface([13.35,38.11,13.36,38.12]));
// Al cambio di ora: nessuna richiesta al server.
projection.setTime(new Date(), true);
// Mostrare la qualità restituita da surface e gestire richieste superate.
// Per dispositivi senza WebGL compatibile usare scene come ripiego.

Modulo compatibile senza proiezione GPU

import {WeatherSicilyShade} from
 'https://maps.weathersicily.it/ombra/sdk.js?v=5';
const shade = new WeatherSicilyShade();
const data = await shade.scene([13.35, 38.11, 13.36, 38.12], new Date());
shade.paint(map, data);
const point = await shade.point(38.117, 13.356, new Date());
// Mostrare sempre data.quality e i limiti delle fonti.
// La risposta scene è legata all’ora richiesta; scartare risposte superate.
// Gestire errore e HTTP 429; non sovrapporre richieste continue.
shade.remove(map);

API JSON

Base: https://maps.weathersicily.it/ombra/api.php

• ?endpoint=health: versione e dataset presenti.
• ?endpoint=surface&bbox=ovest,sud,est,nord: quote e maschera terraferma in PNG RG16, estensione metrica, dimensioni, contesto e qualità; indipendente dall’orario.
• ?endpoint=scene&bbox=ovest,sud,est,nord&time=2026-06-21T15:00:00Z: PNG trasparente incorporato, limiti georeferenziati, posizione del Sole e qualità.
• ?endpoint=point&lat=38.117&lon=13.356&time=2026-06-21T15:00:00Z: stato geometrico e profilo giornaliero in passi da 10 minuti.

Gli orari API sono UTC; la giornata del profilo è quella italiana, con gestione dell’ora legale. Stati: notte, ombra, sole_potenziale. Un dato mancante produce un errore esplicito, mai “sole”.

Le richieste sono limitate alla Sicilia e a due calcoli simultanei. Gli errori 429 vanno ritentati dopo alcuni secondi; 400 indica parametri non validi, 422 un punto senza dati o fuori terraferma, 503 un’indisponibilità temporanea. CORS abilitato per Weather Sicily e i suoi sottodomini. Fonti e limiti.