## Manuale Utente - FlightMonitor

**Versione 1.0**

### Indice
1.  Introduzione
2.  Installazione e Requisiti
3.  Panoramica dell'Interfaccia Utente
4.  Funzionalità Principali
    *   4.1. Monitoraggio Live
    *   4.2. Download Dati Storici
    *   4.3. Gestione dei Profili di Area
    *   4.4. Logging dei Dati di Sessione
5.  Interazione con la Mappa
6.  Casi d'Uso Pratici
7.  Domande Frequenti (FAQ)
8.  Risoluzione dei Problemi

---

### 1. Introduzione

Benvenuti a **FlightMonitor**, un'applicazione desktop avanzata per il monitoraggio e l'analisi del traffico aereo. FlightMonitor è stato progettato per appassionati di aviazione, hobbisti e sviluppatori che necessitano di uno strumento potente e flessibile per visualizzare e registrare dati di volo da fonti come OpenSky Network.

Questo manuale vi guiderà attraverso tutte le funzionalità dell'applicazione, dalla configurazione iniziale all'uso delle sue capacità più avanzate.

### 2. Installazione e Requisiti

FlightMonitor è un'applicazione basata su Python. Per eseguirla, assicuratevi di avere i seguenti requisiti installati nel vostro ambiente:
*   Python 3.8 o superiore
*   Le librerie Python specificate nel file `requirements.txt`, tra cui: `requests`, `Pillow`, `mercantile`, `pyproj`.

Per un'esperienza ottimale, si raccomanda di utilizzare le credenziali API di OpenSky Network per aumentare i limiti di interrogazione. Le credenziali possono essere inserite nel file `data/config.py`.

### 3. Panoramica dell'Interfaccia Utente

L'interfaccia di FlightMonitor è suddivisa in due colonne principali, ridimensionabili a piacere:

*   **Colonna Sinistra (Pannello di Controllo):**
    *   **Area Profiles & BBox:** Permette di definire l'area geografica di interesse (Bounding Box) e di salvare/caricare configurazioni di aree come "Profili".
    *   **Data Logging Session:** Contiene i controlli per abilitare e configurare il salvataggio dei dati grezzi e di riepilogo della sessione di monitoraggio.
    *   **Function Notebook:** Un pannello a schede per selezionare la modalità operativa (Live Monitor, Historical Download, Playback).
    *   **Log & Status Area:** Mostra i log dettagliati dell'applicazione e uno stato sintetico tramite un semaforo colorato.

*   **Colonna Destra (Area di Visualizzazione):**
    *   **Views Notebook:** Un pannello a schede che contiene la **Map View** e altre viste future (es. Table View).
    *   **Map Tools & Info Panels:** Fornisce strumenti per interagire con la mappa (zoom, pan) e visualizza informazioni dettagliate sulla mappa stessa (coordinate, scala) e sul velivolo selezionato.

### 4. Funzionalità Principali

#### 4.1. Monitoraggio Live

Questa è la modalità principale per visualizzare il traffico aereo in tempo reale.

**Come si usa:**
1.  Selezionare la tab **"Live Monitor"** nella colonna di sinistra.
2.  Definire un'area di interesse nel pannello "Area Profiles & BBox" inserendo le coordinate di latitudine e longitudine minime e massime, oppure selezionando un profilo salvato.
3.  (Opzionale) Abilitare il logging dei dati nella sezione "Data Logging Session".
4.  Premere il pulsante **"Start Live"**.

La mappa si popolerà con gli aerei presenti nell'area specificata. Le loro posizioni verranno aggiornate a ogni ciclo di interrogazione. Per terminare il monitoraggio, premere **"Stop Live"**.

#### 4.2. Download Dati Storici

Questa modalità permette di scaricare dati di volo per un periodo passato. **Nota:** richiede credenziali OpenSky valide.

**Come si usa:**
1.  Selezionare la tab **"Historical Download"**.
2.  Definire l'area di interesse nel pannello "Area Profiles & BBox".
3.  Nel pannello "Download Parameters", inserire le date e gli orari di inizio e fine (in UTC).
4.  Impostare l'**API Scan Rate** (quanto spesso interrogare l'API, in secondi) e il **Sampling Interval** (l'intervallo tra i punti dati da scaricare).
5.  Premere **"Start Download"**.

L'applicazione inizierà a scaricare i dati "fetta per fetta", mostrando l'avanzamento sulla mappa e sull'orologio virtuale.

#### 4.3. Gestione dei Profili di Area

Per evitare di inserire manualmente le coordinate ogni volta, è possibile salvare le aree come profili.

*   **Salvare un Profilo:** Inserire le coordinate desiderate e premere **"Save"**. Verrà chiesto di inserire un nome per il profilo.
*   **Caricare un Profilo:** Selezionare un profilo dal menu a tendina. Le coordinate verranno caricate automaticamente.
*   **Cancellare un Profilo:** Selezionare un profilo e premere **"Delete"**. Non è possibile cancellare il profilo "Default Zone".

#### 4.4. Logging dei Dati di Sessione

Questa potente funzionalità permette di salvare i dati di una sessione di monitoraggio per analisi future.

**Come si usa:**
1.  Prima di avviare una sessione (Live o Storica), spuntare la casella **"Enable Raw Data Logging"**.
2.  Il campo "Save to" si popolerà con una directory di default (`Atc_download`). È possibile cambiarla premendo **"Browse..."**.
3.  Avviare il monitoraggio. Verranno creati due file nella cartella specificata:
    *   `atc-<timestamp>.txt`: Contiene i dati JSON grezzi ricevuti dal provider, una riga per ogni interrogazione.
    *   `atc-<timestamp>_report.txt`: Contiene un riepilogo della sessione, inclusi BBox e una tabella con il conteggio degli aerei per ogni fetch.
4.  La tabella nella UI si popolerà in tempo reale con i dati di riepilogo.
5.  Il pulsante **"Open Folder"** apre direttamente la cartella di salvataggio nel file explorer del sistema.

### 5. Interazione con la Mappa

*   **Pan (Spostamento):** Cliccare e trascinare il mouse sulla mappa. In alternativa, usare i pulsanti di pan nel pannello "Map Tools".
*   **Zoom:** Usare la rotellina del mouse. In alternativa, usare i pulsanti `+` e `-` nel pannello "Map Tools".
*   **Selezione Aereo:** Cliccare con il tasto sinistro su un'icona di un aereo. I suoi dettagli appariranno nel pannello "Selected Flight Details".
*   **Menu Contestuale:** Cliccare con il tasto destro sulla mappa per aprire un menu che permette di:
    *   Ricentrare la mappa in quel punto.
    *   Definire una nuova Bounding Box attorno a quel punto.

### 6. Casi d'Uso Pratici

*   **Monitorare il traffico sopra casa:** Inserire le coordinate di una BBox di circa 100x100 km attorno alla propria città, salvarla come profilo "Casa" e avviare il monitoraggio live.
*   **Registrare un evento specifico:** Se si sa che un aereo interessante passerà in una certa area a un certo orario, si può avviare il monitoraggio live con il logging dei dati grezzi abilitato per catturare tutti i dettagli della sua traiettoria.
*   **Analizzare un'anomalia passata:** Usare la modalità "Historical Download" per scaricare i dati di un'area e di un periodo in cui si è verificato un evento anomalo (es. un go-around) per analizzarne la dinamica.

### 7. Domande Frequenti (FAQ)

*   **D: Perché non vedo aerei sulla mappa in modalità Live?**
    *   **R:** Controlla che la tua Bounding Box sia corretta e non troppo piccola. Verifica che la tua connessione internet sia attiva. Se stai usando la modalità anonima, potresti dover attendere 10-15 secondi per il primo aggiornamento. Controlla il pannello di stato per eventuali messaggi di errore dall'API.

*   **D: Il download storico non funziona. Perché?**
    *   **R:** La modalità storica richiede credenziali API di OpenSky Network valide e correttamente inserite nel file `data/config.py`. L'accesso anonimo non permette di scaricare dati storici.

*   **D: Posso cambiare l'aspetto della mappa?**
    *   **R:** Attualmente, l'applicazione usa OpenStreetMap come fornitore di tile. Future versioni potrebbero permettere di selezionare altri stili di mappa.

*   **D: Dove vengono salvati i file di log?**
    *   **R:** Per default, nella sottocartella `Atc_download` all'interno della cartella principale dell'applicazione. È possibile cambiare questo percorso tramite il pulsante "Browse...".

### 8. Risoluzione dei Problemi

*   **L'applicazione non si avvia:** Assicurati che tutti i requisiti elencati nella Sezione 2 siano installati correttamente. Esegui l'applicazione da un terminale per visualizzare eventuali messaggi di errore all'avvio.
*   **La mappa mostra solo quadrati grigi:** Questo indica che i "tile" della mappa non possono essere caricati. Controlla la tua connessione internet. Se il problema persiste, la cache dei tile potrebbe essere corrotta. Prova a cancellare la cartella `flightmonitor_tile_cache`.
*   **Vedo errori nel pannello di Log:** Messaggi di errore come "RATE_LIMITED" o "API_ERROR" indicano problemi temporanei con il servizio API. L'applicazione tenterà di riconnettersi automaticamente. Se l'errore è "PERMANENT_FAILURE", controlla le tue credenziali API.

