

## 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.