# **User Manual - Radar Data Reader & Processor (v2.0)**

## **1. Introduction: A Complete Workflow**

Welcome to the Radar Data Reader & Processor. This tool is designed to guide you through a complete workflow for radar data analysis, transforming raw flight recordings into structured, analysis-ready data.

The application is organized to follow a logical, three-phase path:

1.  **Phase 1: Flight Analysis**: Start with an entire folder of `.rec` files to automatically identify and summarize the flight's significant operational segments.
2.  **Phase 2: Segment Export**: Once the segments of interest are identified, this phase extracts them, creating raw data files (`.out`, video, etc.) for each one.
3.  **Phase 3: Data Processing**: The final step is to batch-process the exported segments to extract the desired numerical values into standard formats (CSV, JSON) using custom profiles.

This manual will guide you through each phase.

## **2. Initial Setup (Mandatory Step)**

Before using the application, it is **critical** to specify the location of the `g_reconvert.exe` executable, which the application depends on.

1.  Launch the application.
2.  Navigate to the **"4. REC to OUT Converter"** tab.
3.  Click the **"g_reconverter Advanced Config..."** button.
4.  In the window that opens, the first field is **"Executable Path"**. Click **"Browse..."** and select the exact location of your `g_reconvert.exe` file.
5.  Click **"Save & Close"**. The configuration will be saved for future use.

**Without this step, the main features of the application will not work.**

---

# **Guide to the Main Workflow**

This section describes the most common and powerful use case for the application.

## **3. Phase 1 & 2: Flight Analysis and Segment Export (Tab `1. Flight Analyzer`)**

This is your command center for starting a new analysis. Here, you will identify and export the key moments of the flight.

**Goal**: To turn a folder full of `.rec` files into a list of operational segments and generate the raw data for the ones you are interested in.

**Steps:**
1.  **Select Flight Folder**: Click **"Browse..."** next to "Recordings Folder" and select the folder containing the complete sequence of `.rec` files for the flight.
2.  **Name the Flight**: Enter a unique identifier for the flight in the "Flight Name" field (e.g., `FlightTest_May25`). This name will be used to create a dedicated workspace folder (`flight_workspace/FlightTest_May25`) where all results will be saved.
3.  **Start Preliminary Analysis**: Click **"Start Flight Analysis"**. The application will run `g_reconvert.exe` in the background to analyze all files, generate a text report, and create a full-mission video. This process may take several minutes.
4.  **View Results**: Upon completion, the "Flight Summary & Segments" table will be populated with a summary of all operational segments found, showing modes, durations, and reference files.
5.  **Export Segments of Interest**:
    *   Select one or more segments from the table that you wish to analyze in detail.
    *   Click **"Export Selected Segment(s)"**.
    *   The application will create a subfolder for each selected segment within the flight's workspace. Each subfolder will contain an `.out` file with the raw data for that segment, along with other ancillary files (segment video, GPS track, etc.).

**Outcome of this phase**: You now have a well-organized workspace folder with a flight summary and subfolders containing raw data ready for extraction.

## **4. Phase 3: Data Extraction from Segments (Tab `2. Segment Processor`)**

Now that you have your exported segments, it's time to extract the numerical data you need.

**Goal**: To batch-process the `.out` files from the exported segments to generate CSV or JSON files based on custom profiles.

**Steps:**
1.  **Load Exported Segments**: Click **"Load Exported Segments from Current Flight"**. The table will be populated with the segments found in the current flight's workspace.
    *   Segments ready for processing will have a **"Ready"** status (in green).
    *   Segments you saw in the previous tab but have not yet exported will have a **"Not Exported"** status (in gray) and will not be selectable.
2.  **Configure the Output**:
    *   **Output Directory**: Choose a **dedicated** destination folder for your final data files (e.g., `C:/Final_Analysis/FlightTest_May25`).
    *   **Formats and Profiles**: Enable CSV and/or JSON export by checking the corresponding boxes and select an **Export Profile** for each. (See Section 6 for creating profiles).
    *   **Folder Structure**: Check **"Create a separate folder for each segment's analysis"** if you want each analysis file (e.g., `segment_A.csv`) to be saved in its own subfolder. Leave it unchecked to have all analysis files in the same directory.
3.  **Select and Start**:
    *   Select the "Ready" segments you want to process from the table.
    *   Click **"Process Selected Segments"**.
4.  **View the Results**: The application will process each segment, generating the CSV/JSON files in the output directory you specified. You can monitor the progress from the progress bar and the console.

**Outcome of this phase**: You have obtained clean, structured data files, ready to be imported into MATLAB, Python, Excel, or other analysis tools.

---

# **Supporting and Advanced Features**

## **5. Single `.out` File Analysis (Tab `3. Single OUT Processor`)**

Use this tab when you have a single `.out` file you want to analyze quickly, outside of a full flight analysis workflow. The functionality is identical to Phase 3 but applied to a single file.

## **6. Creating and Managing Export Profiles**

The Profile Editor (`File -> Manage Export Profiles...`) is the heart of data extraction customization.

*   **Left Panel (Profiles)**: Create new profiles (e.g., "Thermal_Analysis", "Tracking_Performance") or delete old ones.
*   **Center Panel (Available Fields)**: Browse the tree of all data structures and fields the application can read. Fields marked with `(Enum)` can be translated into human-readable text. Select a field and click **`>>`** to add it to the current profile.
*   **Right Panel (Selected Fields for Profile)**:
    *   View and reorder the fields of the selected profile using the **Up/Down** buttons.
    *   **"Translate" Column**: This is a powerful feature. By clicking the checkbox in this column, you can decide whether an `(Enum)` field should be exported as its raw numerical value (e.g., `15`) or its text representation (e.g., `STT_MASTER_MODE`), making your CSV files instantly readable.

## **7. Manual Conversion (Tab `4. REC to OUT Converter`)**

This tab provides a simple frontend for `g_reconvert.exe`, useful for quick conversions or for testing specific parameter combinations without going through the entire analysis workflow.

## **8. Troubleshooting and Frequently Asked Questions (FAQ)**

*   **Q: The application starts, but no functions seem to work. What should I do?**
    *   **A**: You have almost certainly not set the path to `g_reconvert.exe`. Carefully follow the steps in the "Initial Setup" section.

*   **Q: Why does exporting a segment seem to fail or crash?**
    *   **A**: `g_reconvert.exe` can be sensitive to its input parameters. The current export logic relies on specifying the number of `.rec` files to process. If the problem persists, ensure the `.rec` files are not corrupted.

*   **Q: When I start an analysis, a second window of my application opens. Is this normal?**
    *   **A**: This is a known behavior when running an application packaged with PyInstaller. While the current code should prevent this issue using `multiprocessing.freeze_support()`, if it occurs, it indicates that the new process was not handled correctly.

*   **Q: Can I add a data field that I don't see in the "Available Fields" tree?**
    *   **A**: Yes, but it requires modifying the source code. You will need to define the new C-style data structure in the `radar_data_reader/core/structures` package and teach the `struct_parser.py` how to read it from the binary file.