## 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-.txt`: Contiene i dati JSON grezzi ricevuti dal provider, una riga per ogni interrogazione. * `atc-_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.