SXXXXXXX_RadarDataReader/doc/English-manual.md

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.