132 lines
8.6 KiB
Markdown
132 lines
8.6 KiB
Markdown
## 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.
|
|
|