132 lines
7.7 KiB
Markdown
132 lines
7.7 KiB
Markdown
|
|
|
|
## User Manual - FlightMonitor
|
|
|
|
**Version 1.0**
|
|
|
|
### Table of Contents
|
|
1. Introduction
|
|
2. Installation and Requirements
|
|
3. User Interface Overview
|
|
4. Core Features
|
|
* 4.1. Live Monitoring
|
|
* 4.2. Historical Data Download
|
|
* 4.3. Area Profile Management
|
|
* 4.4. Session Data Logging
|
|
5. Map Interaction
|
|
6. Practical Use Cases
|
|
7. Frequently Asked Questions (FAQ)
|
|
8. Troubleshooting
|
|
|
|
---
|
|
|
|
### 1. Introduction
|
|
|
|
Welcome to **FlightMonitor**, an advanced desktop application for air traffic monitoring and analysis. FlightMonitor is designed for aviation enthusiasts, hobbyists, and developers who need a powerful and flexible tool to visualize and record flight data from sources like the OpenSky Network.
|
|
|
|
This manual will guide you through all the application's features, from initial setup to using its most advanced capabilities.
|
|
|
|
### 2. Installation and Requirements
|
|
|
|
FlightMonitor is a Python-based application. To run it, ensure you have the following requirements installed in your environment:
|
|
* Python 3.8 or higher
|
|
* The Python libraries specified in the `requirements.txt` file, including: `requests`, `Pillow`, `mercantile`, `pyproj`.
|
|
|
|
For an optimal experience, it is recommended to use OpenSky Network API credentials to increase the query rate limits. Credentials can be entered in the `data/config.py` file.
|
|
|
|
### 3. User Interface Overview
|
|
|
|
The FlightMonitor interface is divided into two main, resizable columns:
|
|
|
|
* **Left Column (Control Panel):**
|
|
* **Area Profiles & BBox:** Allows you to define the geographical area of interest (Bounding Box) and to save/load area configurations as "Profiles".
|
|
* **Data Logging Session:** Contains controls to enable and configure the saving of raw and summary data for the monitoring session.
|
|
* **Function Notebook:** A tabbed panel to select the operating mode (Live Monitor, Historical Download, Playback).
|
|
* **Log & Status Area:** Displays detailed application logs and a summary status via a colored semaphore.
|
|
|
|
* **Right Column (Display Area):**
|
|
* **Views Notebook:** A tabbed panel containing the **Map View** and other future views (e.g., Table View).
|
|
* **Map Tools & Info Panels:** Provides tools to interact with the map (zoom, pan) and displays detailed information about the map itself (coordinates, scale) and the selected aircraft.
|
|
|
|
### 4. Core Features
|
|
|
|
#### 4.1. Live Monitoring
|
|
|
|
This is the primary mode for viewing real-time air traffic.
|
|
|
|
**How to use:**
|
|
1. Select the **"Live Monitor"** tab in the left column.
|
|
2. Define an area of interest in the "Area Profiles & BBox" panel by entering the minimum and maximum latitude and longitude coordinates, or by selecting a saved profile.
|
|
3. (Optional) Enable data logging in the "Data Logging Session" section.
|
|
4. Press the **"Start Live"** button.
|
|
|
|
The map will populate with aircraft within the specified area. Their positions will be updated with each query cycle. To end monitoring, press **"Stop Live"**.
|
|
|
|
#### 4.2. Historical Data Download
|
|
|
|
This mode allows you to download flight data for a past period. **Note:** this requires valid OpenSky credentials.
|
|
|
|
**How to use:**
|
|
1. Select the **"Historical Download"** tab.
|
|
2. Define the area of interest in the "Area Profiles & BBox" panel.
|
|
3. In the "Download Parameters" panel, enter the start and end dates and times (in UTC).
|
|
4. Set the **API Scan Rate** (how often to query the API, in seconds) and the **Sampling Interval** (the time gap between the data points to be downloaded).
|
|
5. Press **"Start Download"**.
|
|
|
|
The application will begin downloading the data slice by slice, showing progress on the map and the virtual clock.
|
|
|
|
#### 4.3. Area Profile Management
|
|
|
|
To avoid manually entering coordinates every time, you can save areas as profiles.
|
|
|
|
* **Save a Profile:** Enter the desired coordinates and press **"Save"**. You will be prompted to enter a name for the profile.
|
|
* **Load a Profile:** Select a profile from the dropdown menu. The coordinates will be loaded automatically.
|
|
* **Delete a Profile:** Select a profile and press **"Delete"**. The "Default Zone" profile cannot be deleted.
|
|
|
|
#### 4.4. Session Data Logging
|
|
|
|
This powerful feature allows you to save the data from a monitoring session for future analysis.
|
|
|
|
**How to use:**
|
|
1. Before starting a session (Live or Historical), check the **"Enable Raw Data Logging"** box.
|
|
2. The "Save to" field will be populated with a default directory (`Atc_download`). You can change this by pressing **"Browse..."**.
|
|
3. Start the monitoring. Two files will be created in the specified folder:
|
|
* `atc-<timestamp>.txt`: Contains the raw JSON data received from the provider, one line per query.
|
|
* `atc-<timestamp>_report.txt`: Contains a session summary, including the BBox and a table with the aircraft count for each fetch.
|
|
4. The table in the UI will populate in real-time with the summary data.
|
|
5. The **"Open Folder"** button directly opens the save location in your system's file explorer.
|
|
|
|
### 5. Map Interaction
|
|
|
|
* **Pan:** Click and drag the mouse on the map. Alternatively, use the pan buttons in the "Map Tools" panel.
|
|
* **Zoom:** Use the mouse wheel. Alternatively, use the `+` and `-` buttons in the "Map Tools" panel.
|
|
* **Select Aircraft:** Left-click on an aircraft icon. Its details will appear in the "Selected Flight Details" panel.
|
|
* **Context Menu:** Right-click on the map to open a menu that allows you to:
|
|
* Recenter the map at that point.
|
|
* Define a new Bounding Box around that point.
|
|
|
|
### 6. Practical Use Cases
|
|
|
|
* **Monitor traffic over your city:** Enter the coordinates of a 100x100 km BBox around your city, save it as a "Home" profile, and start live monitoring.
|
|
* **Record a specific event:** If you know an interesting aircraft will pass through a certain area at a specific time, you can start live monitoring with raw data logging enabled to capture all the details of its trajectory.
|
|
* **Analyze a past anomaly:** Use the "Historical Download" mode to download data for an area and time period where an anomaly occurred (e.g., a go-around) to analyze its dynamics.
|
|
|
|
### 7. Frequently Asked Questions (FAQ)
|
|
|
|
* **Q: Why don't I see any aircraft on the map in Live mode?**
|
|
* **A:** Check that your Bounding Box is correct and not too small. Verify that your internet connection is active. If you are using anonymous mode, you may have to wait 10-15 seconds for the first update. Check the status panel for any error messages from the API.
|
|
|
|
* **Q: Historical download isn't working. Why?**
|
|
* **A:** Historical mode requires valid OpenSky Network API credentials to be correctly entered in the `data/config.py` file. Anonymous access does not allow downloading historical data.
|
|
|
|
* **Q: Can I change the map's appearance?**
|
|
* **A:** Currently, the application uses OpenStreetMap as the tile provider. Future versions may allow selecting other map styles.
|
|
|
|
* **Q: Where are the log files saved?**
|
|
* **A:** By default, in the `Atc_download` subfolder within the application's main directory. You can change this path using the "Browse..." button.
|
|
|
|
### 8. Troubleshooting
|
|
|
|
* **The application won't start:** Ensure that all requirements listed in Section 2 are installed correctly. Run the application from a terminal to see any startup error messages.
|
|
* **The map only shows gray squares:** This indicates that the map tiles cannot be loaded. Check your internet connection. If the problem persists, the tile cache may be corrupt. Try deleting the `flightmonitor_tile_cache` folder.
|
|
* **I see errors in the Log panel:** Error messages like "RATE_LIMITED" or "API_ERROR" indicate temporary issues with the API service. The application will attempt to reconnect automatically. If the error is "PERMANENT_FAILURE", check your API credentials. |