SXXXXXXX_FlightMonitor/doc/Italian-manual.md

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.