Toolkit Meteo

Dashboard locale per analisi e visualizzazioni meteo

Accesso rapido a strumenti per generare mappe PNG, esplorare report temporali e analizzare la frequenza degli eventi rari o estremi.

Mappa PNG

Crea una mappa meteo in PNG con overlay di eventi rari/estremi e frame temporali configurabili.

PNG Frame slider Overlay eventi

Report dinamico

Visualizza serie temporali di temperatura, vento, umidita e stati meteo direttamente nel browser.

Grafici Configurabile Locale

Simulazione scenario

Simula anni di dati per confrontare meteo base, hail/fog ed eventi estremi per profilo climatico.

Distribuzioni Eventi Profili

README

Documentazione completa del progetto (contenuto di README.md).

# Meteo Generator

Libreria **TypeScript/JavaScript** per la simulazione di condizioni meteo, tempo simulato (giorno/notte), stagioni, fasi lunari e traduzioni localizzate.

## Installazione

```bash
npm install meteo-generator
```

## Funzionalità Principali

- **Simulazione del tempo** (accelera o rallenta secondi, minuti, ore, giorni, mesi, anni) tramite il parametro `rate`.
- **Modalità tempo**: realtime (default) o manuale per simulazioni controllate.
- **Profili climatici** (moderate, dry, rainy, desert, polar, mediterranean, tropical, continental, alpine) che modulano probabilità meteo e temperature.
- **Supporto altitudine** con coordinate 3D (x, y, z) e calcolo temperatura basato su lapse rate atmosferico.
- **Sistema temperatura avanzato** con smoothing, componenti stagionali, giornaliere e di rumore.
- **Temperatura percepita** con wind chill (freddo) e heat index (caldo umido).
- **Sistema atmosferico completo**:
  - Vento (velocità, raffiche, direzione cardinale)
  - Umidità relativa (%)
  - Pressione atmosferica (hPa) con trend (rising/steady/falling)
  - Copertura nuvolosa (%)
  - Intensità precipitazioni (mm/h)
  - Visibilità (km) e condizioni di nebbia
  - Indice UV basato su ora, stagione, nuvole e altitudine
- **Eventi meteo estremi** pseudo-casuali (ondate di calore, gelate improvvise, grandinate, tempeste di sabbia, blizzard).
- **Stagioni e meteo** generati su base pseudo-casuale, con possibilità di definire un *seed* costante.
- **Fasi lunari** e **fasi del giorno** (mattino, pomeriggio, sera, notte).
- **Supporto multilingua** (it_IT, en_US, es_ES) tramite la classe `Lang`.
- **Getter dedicati** che restituiscono separatamente le chiavi tecniche (`weatherKey`, `weatherSeasonKey` ecc.) e le rispettive label tradotte (`weather`, `weatherSeason` ecc.).
- **Riepilogo completo** dei dati meteo tramite `meteo.recap`.
- **Forecast** per generare serie future (ore/giorni) con parametri riproducibili.

---

## Costanti / Domini delle Chiavi Tecniche

La classe `Meteo` espone diverse **chiavi tecniche** (nomi costanti) che utilizza per gestire la logica interna e che possono essere lette dai getter (es. `weatherKey`, `dayStatusKey`, ecc.). Di seguito un elenco dei principali domini (ogni chiave ha poi la relativa label localizzata):

Le **costanti numeriche** della simulazione (soglie, fattori e parametri) sono centralizzate in `METEO_CONST`:

```ts
import Meteo, { METEO_CONST } from "meteo-generator";
```

1. **Stagioni** (`SEASONS`):
   - `WINTER`
   - `SPRING`
   - `SUMMER`
   - `AUTUMN`

2. **Condizioni Meteo** (`WEATHER`):
   - `SUNNY`
   - `CLOUDY`
   - `LIGHT_RAIN`
   - `MODERATE_RAIN`
   - `HEAVY_RAIN`
   - `LIGHT_SNOW`
   - `HEAVY_SNOW`
   - `THUNDERSTORM`

3. **Elementi Giorno/Notte/Luna** (`ELEMENTS`):
   - `DAY`
   - `NIGHT`
   - `SUN`
   - `MOON`
   - `NA` (per indicare “non applicabile” in alcuni contesti)

4. **Fasi del Giorno** (`PHASE_DAY`):
   - `MORNING`
   - `AFTERNOON`
   - `EVENING`
   - `NIGHT`

5. **Fasi Lunari** (`PHASE_MOON`):
   - `NEW_MOON`
   - `WAXING_CRESCENT`
   - `FIRST_QUARTER`
   - `WAXING_GIBBOUS`
   - `FULL_MOON`
   - `WANING_GIBBOUS`
   - `LAST_QUARTER`
   - `WANING_CRESCENT`

6. **Profili Climatici** (`CLIMATE_PROFILES`):
   - `moderate` - Clima equilibrato (default)
   - `dry` - Più sole, meno pioggia
   - `rainy` - Più pioggia e nuvole
   - `desert` - Prevalentemente soleggiato, pioggia rarissima
   - `polar` - Freddo intenso, più neve
   - `mediterranean` - Estati calde e secche, inverni miti
   - `tropical` - Caldo umido, piogge frequenti e temporali
   - `continental` - Forte escursione stagionale, inverni freddi e neve
   - `alpine` - Freddo di quota, neve frequente e venti sostenuti

7. **Punti Cardinali** (direzione vento):
   - `N` - Nord
   - `NE` - Nord-Est
   - `E` - Est
   - `SE` - Sud-Est
   - `S` - Sud
   - `SW` - Sud-Ovest
   - `W` - Ovest
   - `NW` - Nord-Ovest

8. **Tendenza Pressione** (`pressureTrend`):
   - `rising` - In aumento
   - `steady` - Stabile
   - `falling` - In diminuzione

Questi domini ti consentono di scrivere logica personalizzata in base alle chiavi tecniche (che rimangono sempre fisse), a prescindere dalla localizzazione.

---

## Utilizzo di Base

### Importazione

In TypeScript/ES6:

```ts
import Meteo from "meteo-generator";
import Lang from "meteo-generator/lang"; // Se vuoi accedere esplicitamente a "Lang"
```

In JavaScript (CommonJS):

```js
const Meteo = require("meteo-generator").default;
const Lang = require("meteo-generator/lang").default;
```

### Creazione di un'istanza

```ts
const meteo = new Meteo({
  startYear: 2025,      // Anno iniziale della simulazione
  startMonth: 6,        // Mese iniziale (1-12, opzionale)
  rate: 48,             // Velocità a cui avanza il tempo simulato
  seed: "example-seed", // Seed per il generatore pseudocasuale
  temperatureType: "celsius", // o "fahrenheit"
  position: { x: 0, y: 0, z: 1500 }, // Posizione 3D (z = altitudine in metri)
  climateProfile: "moderate", // "moderate", "dry", "rainy", "desert", "polar", "mediterranean", "tropical", "continental", "alpine"
  timeMode: "realtime", // "realtime" o "manual"
  timestampMs: null,    // Timestamp manuale in millisecondi (solo se timeMode = "manual")
});
```

### Getter Principali

Una volta istanziato, puoi accedere alle informazioni simulate:

```ts
// Tempo e data simulati
console.log(meteo.hour);     // Ora virtuale (0-23)
console.log(meteo.day);      // Giorno (1-30)
console.log(meteo.month);    // Mese (1-12)
console.log(meteo.year);     // Anno

// Condizioni meteo
console.log(meteo.weatherKey);   // Chiave tecnica, es: "SUNNY", "CLOUDY", ...
console.log(meteo.weather);      // Label localizzata, es: "sunny", "nuvoloso", ...

// Stagione
console.log(meteo.weatherSeasonKey);   // Chiave tecnica, es: "WINTER", "SPRING"
console.log(meteo.weatherSeason);      // Label localizzata, es: "Winter", "Primavera"

// Giorno o notte
console.log(meteo.dayStatusKey);      // "DAY" o "NIGHT"
console.log(meteo.dayStatus);         // Label localizzata, es: "Day", "Night"

// Temperatura
console.log(meteo.temperature);       // Valore in °C (numerico)
console.log(meteo.temperatureString); // Stringa con °C o °F, es: "24°C", "75°F"
console.log(meteo.perceivedTemperature); // Temperatura percepita (wind chill/heat index)

// Dati atmosferici
console.log(meteo.windSpeed);         // Velocità vento in km/h
console.log(meteo.windGustSpeed);     // Raffiche di vento in km/h
console.log(meteo.windDirectionCardinal); // Direzione cardinale (N, NE, E, SE, S, SW, W, NW)
console.log(meteo.humidity);          // Umidità relativa (0-100%)
console.log(meteo.pressure);          // Pressione atmosferica (hPa)
console.log(meteo.pressureTrend);     // Tendenza: "rising", "steady", "falling"
console.log(meteo.cloudCover);        // Copertura nuvolosa (0-100%)
console.log(meteo.precipitationIntensity); // Intensità precipitazioni (mm/h)
console.log(meteo.visibility);        // Visibilità in km
console.log(meteo.uvIndex);           // Indice UV (0-11+)
```

### Recap Completo

La proprietà `meteo.recap` restituisce un **oggetto** con **tutti** i principali dati simulati (date, stagioni, meteo, dayStatus, fasi solari/lunari, ecc.), **incluse** sia le chiavi tecniche sia le label localizzate. Esempio:

```ts
console.log(meteo.recap);
/*
{
  date: "25/03/2025",
  time: "12:05:00",
  datetime: "12:05:00  25/03/2025",
  second: 0,
  minute: 5,
  hour: 12,
  day: 25,
  month: 3,
  year: 2025,
  yearOffset: 0,
  weatherSeasonKey: "SPRING",
  weatherSeasonLabel: "Spring",
  weatherKey: "SUNNY",
  weatherLabel: "sunny",
  climateProfile: "moderate",
  temperatureType: "celsius",
  temperatureValue: 24,          // in °C numerici
  temperatureString: "24°C",
  dayStatusKey: "DAY",
  dayStatusLabel: "Day",
  sunOrMoonKey: "SUN",
  sunOrMoonLabel: "Sun",
  sunPhaseKey: "AFTERNOON",
  sunPhaseLabel: "Afternoon",
  moonPhaseIndex: 3,
  moonPhaseKey: "WAXING_GIBBOUS",
  moonPhaseLabel: "N/A",         // se è giorno, "N/A"
  dayPhaseKey: "AFTERNOON",
  dayPhaseLabel: "Afternoon"
}
*/
```

- `meteo.recapString` restituisce gli stessi valori in un’unica stringa multilinea.
- `meteo.json` restituisce un JSON stringificato.

### Profili Climatici

I profili climatici modulano le probabilità di ogni condizione meteo e i parametri termici:

- **moderate**: clima equilibrato (default)
- **dry**: più sole, meno pioggia, temperature più alte
- **rainy**: più pioggia e nuvole, temperature più basse
- **desert**: prevalentemente soleggiato, pioggia rarissima, grandi escursioni termiche
- **polar**: freddo intenso, più neve che pioggia, escursioni ridotte
- **mediterranean**: estati calde e secche, inverni miti e piogge moderate
- **tropical**: caldo umido, piogge frequenti e temporali
- **continental**: forte escursione stagionale, estati calde e inverni freddi
- **alpine**: freddo di quota, neve frequente e venti sostenuti

```ts
meteo.setClimateProfile("desert");
console.log(meteo.weatherKey); // Più probabilità di "SUNNY"
```

### Modalità Tempo Manuale

Puoi controllare manualmente il timestamp invece di usare l'orologio di sistema:

```ts
// Imposta un timestamp specifico
meteo.setManualTimestamp(1640995200000); // timestamp in millisecondi
// oppure
meteo.setManualTimestampSeconds(1640995200); // timestamp in secondi

// Torna al tempo reale
meteo.useRealtimeTimestamp();
```

### Aggiungere tempo simulato

In modalità manuale (o quando vuoi forzare il passaggio a manuale), puoi avanzare il tempo virtuale:

```ts
meteo.addSeconds(30);
meteo.addMinutes(15);
meteo.addHours(3);
meteo.addDays(1);
meteo.addMonths(1);
meteo.addYears(1);
```

Le unità sono **virtuali** e rispettano il `rate` impostato.

### Altitudine e Temperatura

L'altitudine (coordinata z) influenza la temperatura con un lapse rate atmosferico di 6.5°C per 1000 metri:

```ts
const meteoMountain = new Meteo({
  position: { x: 0, y: 0, z: 2000 }, // 2000 metri di altitudine
  climateProfile: "moderate"
});

console.log(meteoMountain.temperature); // Circa 13°C più bassa rispetto a z=0
```

Inoltre, a temperature ≤ 0°C, la pioggia si trasforma automaticamente in neve.

### Dati Atmosferici Avanzati

La libreria simula un sistema atmosferico completo con smoothing e transizioni realistiche:

#### Vento
```ts
console.log(meteo.windSpeed);              // 12.5 (km/h)
console.log(meteo.windGustSpeed);          // 18.3 (km/h)
console.log(meteo.windDirection);          // 245 (gradi, 0=Nord)
console.log(meteo.windDirectionCardinal);  // "SW"
```

Il vento è influenzato dal profilo climatico e varia con smoothing per evitare cambi bruschi.

#### Temperatura Percepita
```ts
console.log(meteo.temperature);            // 5°C
console.log(meteo.perceivedTemperature);   // 2°C (wind chill con vento)

// Con caldo e umidità
console.log(meteo.temperature);            // 32°C
console.log(meteo.perceivedTemperature);   // 38°C (heat index)
```

La temperatura percepita usa wind chill quando fa freddo e c'è vento, o heat index quando fa caldo con umidità elevata.

#### Pressione Atmosferica
```ts
console.log(meteo.pressure);        // 1013 (hPa)
console.log(meteo.pressureTrend);   // "falling" | "steady" | "rising"
```

La pressione varia tra 980-1030 hPa e tende a essere più bassa con maltempo.

#### Umidità, Nuvole e Precipitazioni
```ts
console.log(meteo.humidity);                  // 75 (%)
console.log(meteo.cloudCover);                // 85 (%)
console.log(meteo.precipitationIntensity);    // 4.2 (mm/h)
```

#### Visibilità e UV
```ts
console.log(meteo.visibility);    // 8.5 (km, ridotta con nebbia/pioggia)
console.log(meteo.uvIndex);       // 7 (0-11+, varia con ora/stagione/nuvole/altitudine)
```

#### Condizioni Speciali
```ts
console.log(meteo.isFoggy);       // true/false
console.log(meteo.isHailing);     // true/false (grandine)
```

#### Eventi Meteo Estremi
```ts
console.log(meteo.extremeEventKey);   // "HEAT_WAVE" | "SUDDEN_FROST" | ...
console.log(meteo.extremeEvent);      // Label localizzata
```

Gli eventi estremi sono **deterministici** rispetto al seed e al tempo simulato.

### Override di Alcuni Parametri al Volo (`getMeteo`)

Puoi generare una **nuova** istanza di `Meteo` basandoti sull'istanza corrente e sovrascrivere alcuni parametri (come posizione, velocità, seed, ecc.):

```ts
const newMeteo = meteo.getMeteo({
  rate: 1,          // per questa nuova istanza
  seed: "otherSeed",
  temperatureType: "fahrenheit",
  position: { x: 100, y: 200, z: 500 },
  climateProfile: "rainy"
});

console.log(newMeteo.recap);
```

Questo metodo **non** modifica l'istanza originale, ma ne crea una nuova con i parametri combinati.

### Forecast (serie temporali)

Puoi generare una serie futura di riepiloghi con step configurabili:

```ts
const nextHours = meteo.getForecastHours(24, 1); // 24 step orari
const nextDays = meteo.getForecastDays(7, 1);    // 7 step giornalieri
```

È disponibile anche l'API generica:

```ts
const forecast = meteo.getForecast({
  hours: 12,
  stepHours: 3,
  includeCurrent: false,
  seed: "custom-seed",
});
```

### Localizzazione

Per cambiare lingua o aggiungere traduzioni personalizzate, puoi usare la classe `Lang`. Ad esempio:

```ts
Lang.setLang("it_IT");
// Oppure aggiungere dizionari personalizzati
Lang.addLang("it_IT", {
  "METEO.WEATHER": {
    SUNNY: "soleggiato",
    CLOUDY: "nuvoloso",
    // etc...
  }
});
```

Le label localizzate (come `meteo.weather`) si aggiorneranno di conseguenza.

### Esempio Completo

```ts
import Meteo from "meteo-generator";
import Lang from "meteo-generator/lang";

Lang.setLang("it_IT");

const meteo = new Meteo({
  startYear: 2025,
  startMonth: 6,
  rate: 48,
  seed: "example-seed",
  temperatureType: "celsius",
  position: { x: 0, y: 0, z: 1200 }, // 1200m altitudine
  climateProfile: "moderate",
});

// Stampa ogni 2 secondi il recap
setInterval(() => {
  console.log(meteo.recapString);
}, 2000);
```

### Uso in Browser

La libreria può essere usata anche nel browser tramite bundle IIFE:

```html
<script src="node_modules/meteo-generator/dist/meteo.browser.js"></script>
<script>
  const meteo = new MeteoLib.default({
    startYear: 2025,
    climateProfile: "rainy",
    position: { x: 0, y: 0, z: 500 }
  });

console.log(meteo.recap);
</script>
```

---

## Contributi

Puoi contribuire segnalando bug o proponendo nuove funzionalità attraverso la sezione Issues del repository.

## Licenza

Distribuito sotto licenza [MIT](./LICENSE).

---

**Buona simulazione con Meteo Generator!**