VALLONGOL/SXXXXXXX_GUI_g_reconverter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1b843908af
SXXXXXXX_GUI_g_reconverter/doc/English-manual.md
VALLONGOL fae8702e73 first commit
2025-05-12 11:46:21 +02:00

18 KiB
Raw Blame History

User Manual (English)

Title: User Manual - g_reconvert.exe GUI Wrapper

Version: 1.0

Date: July 27, 2024

1. Introduction

Welcome to the user manual for the g_reconvert.exe GUI Wrapper. This tool is designed to provide a simple and intuitive Graphical User Interface (GUI) for the powerful command-line executable g_reconvert.exe. The wrapper streamlines the process of configuring and launching conversions, eliminating the need to manually remember and type complex command-line parameters.

This manual will guide you through installation (if applicable), the user interface, parameter configuration, running conversions, profile management, and provide an overview of how the g_reconvert.exe executable and the wrapper itself function.

2. Prerequisites

To use this tool, you must have the following prerequisites installed on your system:

  • Python: A compatible version of Python (typically Python 3.x).
  • Python Libraries: The tkinter, subprocess, threading, queue, json, os, datetime, sys, and ttk libraries. These are generally included in a standard Python installation or can be installed via pip (pip install tkinter). Standard libraries like subprocess, threading, queue, json, os, datetime, sys are built-in. The ttk library is part of tkinter.
  • g_reconvert.exe Executable: The g_reconvert.exe executable file for your operating system. The GUI tool requires you to specify the path to this executable.
  • Input Files: The .rec files that you wish to convert.

3. Installation (If Applicable)

If the tool was provided to you as a Python script (.py), no formal installation is required. Simply ensure you have Python and the necessary libraries installed. You can run the application by executing the Python script.

If the tool was provided to you as an executable (e.g., built with PyInstaller), no additional steps are needed beyond obtaining the executable file.

4. User Interface

The main window of the g_reconvert.exe GUI Wrapper is organized as follows:

  • Title Bar: Displays the application title ("g_reconvert.exe Interface").
  • Menu Bar: Contains options for file management and settings (explained in Section 5).
  • g_reconvert.exe Path: A label at the top displays the currently configured path to the g_reconvert.exe executable. This value is automatically saved and loaded.
  • Tabs (Notebook): The central area is organized into tabs to logically group the various g_reconvert.exe parameters:
    • Input/Output Files: Configuration of the input file and output destination directory.
    • Main Processing Options: Primary options for the conversion process.
    • Advanced Config & Numerics: Advanced settings and numerical parameters.
    • Video Options: Parameters related to video processing.
    • Execution Control (// flags): Flags to control execution behavior and verbosity levels.
  • "Run g_reconvert.exe" Button: A large button in the center below the tabs to initiate the conversion process. It will turn gray and become disabled while the process is running.
  • Console Output: A scrollable text area at the bottom of the window that displays the real-time output (stdout and stderr) of the g_reconvert.exe executable during execution. Messages of different types (INFO, WARNING, ERROR, CMD, SUCCESS) are color-coded for better readability.
  • Status Bar: A bar at the very bottom of the window displaying the current application status and informational messages.

5. Using the Menu Bar

The menu bar provides the following options:

  • File:
    • Set g_reconvert.exe Path: Opens a dialog to select the g_reconvert.exe executable file. This is the only way to change the executable path after the initial loading. The set path is automatically saved to the default profile.
    • Load Profile: Opens a dialog to select and load a saved parameter configuration from a JSON file.
    • Save Profile: Opens a dialog to save the current parameter configuration to a JSON file.
    • Save as Default Profile: Saves the current parameter configuration to the default profile file (default_launch_profile.json), which will be automatically loaded upon the next application startup.
    • Open GUI Log File: Opens the GUI's internal log file (gui_execution_log.txt) using the system's default application. This log records events and messages from the GUI itself.
    • Exit: Closes the application. If a g_reconvert.exe process is running, it will ask for confirmation before terminating.

6. Parameter Configuration

The tabs organize the g_reconvert.exe parameters. The main widgets within each tab are described below:

  • Input/Output Files:

    • Source Binary File (.rec):* Text field and "Browse..." button to select the input .rec file. This field is mandatory.
    • Output Directory: Text field and "Browse..." button to select the folder where the output files will be saved. This field is mandatory unless the "Analyze Only" option is selected.
    • Informational note about input and output file requirements.

  • Main Processing Options: Contains various checkboxes and fields to control the primary conversion process. Widgets are arranged across multiple columns to make the interface more compact.

    • Analyze Only (/a): Select to only analyze the file without generating output.
    • Don't Save Signal (/nosign): Select to prevent saving signal data.
    • Use FW Header (/hfw): Use the firmware header for synchronization.
    • Fix DSP Geopos Bug (/$pbug): Apply a fix for a potential DSP geopositioning bug.
    • Sync Signal Flows w/ Header (/h): Synchronize signal flows with the header.
    • Extract Only SW Data (/sw): Extract only software data.
    • Extract Only DSP Data (/dsp): Extract only DSP data.
    • Stop on Discontinuity (/ss): Stop processing if data discontinuity is detected.
    • Dry Run (/dryrun): Perform a simulation without actually converting the data.
    • Start Save from STBY (/z): Begin saving data from the standby state.
    • Fix SATA File Date (/d): Apply a fix to the SATA file date.
    • Examine Some Data (/x): Perform a preliminary examination of some data.
    • Post Process History (/p) / Level: Checkbox to enable post-processing. If selected, the "Level:" field becomes active to specify the post-processing level (typically 1).
    • Concatenate REC files (/n): Text field to specify the number of .rec files to concatenate during conversion. The default value is 3.
    • Output Format (/f): Text field to specify the desired output format.

  • Advanced Config & Numerics: Contains advanced options and numerical parameters.

    • JSON Config File (/j): Text field and "..." button to select an external JSON configuration file.
    • g_reconvert Log File (/l): Label displaying the path to the log file that will be generated by g_reconvert.exe. This path is automatically determined based on the input file and selected output directory.
    • Max Batches (/m): Text field to specify the maximum number of batches to process.
    • PRI Number (/r): Text field to specify a PRI number.
    • RBIN Number (/c): Text field to specify an RBIN number.

  • Video Options: Contains parameters related to video processing.

    • Output to Rec Results (/vout): Output video to recording results.
    • Show Video (/vshow): Display the video during processing (default: Selected).
    • Save Video (/vsave): Save the processed video (default: Selected).
    • Fix Frame Rate (/vframe): Apply a fix to the video frame rate.
    • Add AVI Subtitles (/vst): Add subtitles to AVI files.
    • GPS: Save Track (/gps): Save the GPS track (default: Selected).
    • HR: Fix Debug Data (/fixhr): Apply a fix to heart rate debug data.
    • SAR: Save Only SAR (/sar): Save only SAR data.

  • Execution Control (// flags): Contains flags that influence execution behavior and verbosity.

    • Verbose Output (//v): Increase the level of detail in the output.
    • Quiet Mode (//q): Reduce the output to a minimum. Note: "Verbose Output" and "Quiet Mode" are mutually exclusive.
    • Debug Messages (//d): Enable debug messages in the output.
    • Silently Overwrite Output (//o): Overwrite existing output files without prompting for confirmation (default: Selected).
    • Mask Warnings (//w): Hide warning messages in the output.
    • Mask Errors (//e): Hide error messages in the output.

7. Running a Conversion

Once you have configured the desired parameters:

  1. Ensure that the path to g_reconvert.exe is correctly set (shown at the top). If not, use "File -> Set g_reconvert.exe Path".
  2. Select the Source Binary File (.rec) and the Output Directory.
  3. Click the "Run g_reconvert.exe" button.

The Console Output area will display the command line being executed and the real-time output from the g_reconvert.exe process. The Status Bar will indicate that the process is running. Once the process completes, the Status Bar will update, and the "Run" button will be re-enabled.

8. Profile Management

Profile management allows you to quickly save and reuse parameter configurations:

  • Saving a Profile: Configure the parameters as desired and select "File -> Save Profile". Choose a name and location for your JSON profile file.
  • Loading a Profile: Select "File -> Load Profile" and choose a previously saved JSON profile file. The settings stored in that profile will be applied to the interface.
  • Saving as Default Profile: After setting the options you use most frequently (including the g_reconvert.exe path), select "File -> Save as Default Profile". These settings will be loaded automatically each time you start the application.

9. How the Tool Works Internally

The GUI wrapper tool functions as follows:

  • Main (GUI) Thread: Handles the user interface, widgets, and responsiveness. It is responsible for processing events (button clicks, file selections, etc.).
  • Worker (Process Execution) Thread: When you click "Run," a separate thread is created. This thread is responsible for constructing the command line for g_reconvert.exe based on the GUI state and launching the subprocess using subprocess.Popen.
  • Queue: A queue.Queue object serves as a safe communication channel between the worker thread and the main thread. The worker thread reads output from the subprocess's stdout (line by line) and puts each line (along with an indication of the message type, if determinable) into the queue. When the subprocess finishes, the worker thread puts a special signal (None) into the queue.
  • Polling (Main Thread): The main thread uses Tkinter's after method to periodically check (every 100 milliseconds in the current implementation) if there are new messages in the queue. If it finds messages, it retrieves them from the queue and updates the Console Output area in the GUI. When it finds the end-of-process signal (None), it stops polling and re-enables the "Run" button.

This multi-threading approach prevents the main thread from freezing while g_reconvert.exe is running, keeping the GUI responsive.

10. About the g_reconvert.exe Executable

This tool is a wrapper for the command-line executable g_reconvert.exe. The exact behavior of g_reconvert.exe and the precise meaning of each flag depend on its implementation. The GUI tool is based on the command line shown in the provided batch file example.

In general, g_reconvert.exe appears to be designed to:

  • Convert binary files (with a .rec extension in this case) into an output format (.out).
  • Support the concatenation of multiple consecutive input files (via /n).
  • Offer various processing options, data extraction (SW, DSP), error handling (/ss), execution control (/dryrun, /z), data correction (/$pbug, /d, /x), and advanced configurations (/j, /m, /r, /c).
  • Include specific functionalities for processing video and GPS data (/vshow, /vsave, /gps, /vframe, /vst, /fixhr, /sar).
  • Provide options to control output verbosity (//v, //q, //d) and output file handling (//o).
  • Write a detailed log file (/l).
  • May generate additional or support files in a specified base directory (//b).

For exact details on the behavior of g_reconvert.exe and its flags, you should consult the official documentation or help of the executable itself (if available by running g_reconvert.exe /? or similar). The GUI tool provides an interface to set these flags in a more user-friendly manner.

11. In-depth Use Cases

Here are some examples of how you can use the tool for common conversion scenarios:

  • Use Case 1: Basic Conversion with Concatenation

    • Objective: Convert one .rec file and the subsequent 2 files, saving the output and log to a specific folder.
    • Steps:
      1. Ensure the g_reconvert.exe path is set.
      2. In the "Input/Output Files" tab, select the first .rec file in the "Source Binary File" field.
      3. Select an output destination folder in the "Output Directory" field.
      4. In the "Main Processing Options" tab, ensure "Concatenate REC files (/n):" is set to 3 (default value).
      5. Keep "Post Process History (/p)" selected (if needed) and set the level (default 1).
      6. In the "Video Options" tab, keep "Show Video (/vshow)", "Save Video (/vsave)", and "GPS: Save Track (/gps)" selected as in the batch.
      7. In the "Execution Control" tab, keep "Silently Overwrite Output (//o)" selected.
      8. Click "Run g_reconvert.exe".
    • Result: The tool will construct a command line similar to your batch file, create the output folder (if it doesn't exist), and execute g_reconvert.exe. You will see the output in real-time, and upon completion, you will find the .out file, the .log file, and any other generated files in the selected output folder.

  • Use Case 2: Analysis Without Output

    • Objective: Perform a quick analysis of a .rec file to check its structure or identify issues, without generating output files.
    • Steps:
      1. Ensure the g_reconvert.exe path is set.
      2. In the "Input/Output Files" tab, select the .rec file in the "Source Binary File" field.
      3. Leave the "Output Directory" field empty.
      4. In the "Main Processing Options" tab, select "Analyze Only (/a)". This will instruct the tool and g_reconvert.exe not to require an output directory.
      5. Click "Run g_reconvert.exe".
    • Result: g_reconvert.exe will be executed with the /a flag. The output in the console will show the analysis results. No output files will be generated.

  • Use Case 3: Saving and Loading a Specific Configuration

    • Objective: Save a non-standard parameter configuration for future reuse.
    • Steps:
      1. Set all desired parameters in the various tabs (e.g., a specific output format, a maximum batch count, disable video saving, enable debug messages).
      2. Select "File -> Save Profile". Choose a descriptive name (e.g., "Video Debug Config.json") and a location to save your JSON profile file.
      3. To reuse this configuration, start the tool and select "File -> Load Profile", then choose the saved profile file.
    • Result: The GUI will load all previously saved settings, including the executable path, selected files and directories, and all flags and values.

  • Use Case 4: Setting a Default Configuration for Future Starts

    • Objective: Have the tool always start with your preferred settings (including the g_reconvert.exe path).
    • Steps:
      1. Set the g_reconvert.exe path via "File -> Set g_reconvert.exe Path".
      2. Configure all other desired parameters (e.g., your most frequent output folder, standard processing flags, typical concatenation number).
      3. Select "File -> Save as Default Profile".
    • Result: The current settings will be saved to the default_launch_profile.json file (in the same directory as the tool's script/executable). Whenever you start the application, these settings will be loaded automatically.

12. Troubleshooting

  • GUI Freezing: If the GUI freezes and becomes unresponsive, it's likely that g_reconvert.exe was not launched correctly in a separate thread or there's an issue with the thread communication. Check the Console Output area for any error messages upon startup. Restarting the application might resolve temporary issues.
  • Console Output Errors: The Console Output area will display any errors or warnings generated by g_reconvert.exe. Pay attention to messages in red (ERROR) and orange (WARNING). Also, check the g_reconvert.exe generated log file (whose path is shown in the "Advanced Config & Numerics" tab) for more detailed information.
  • Files Not Found: Ensure that the paths to the input .rec file and the g_reconvert.exe executable are correct. The GUI tool checks for the existence of the input file and the executable before launching the process.
  • Output Folder Issues: If the conversion fails due to writing issues, verify that the selected output destination folder exists and that the user running the application has write permissions to that folder. The tool attempts to create the folder if it doesn't exist, but permission issues might occur.
  • Profile Issues: Profile files are in JSON format. If a profile file is corrupted or manually edited incorrectly, it might not load correctly. If you encounter issues with a specific profile, try loading a different one or saving a new profile.

13. Final Notes

This tool is a wrapper and relies on the correct functioning of the g_reconvert.exe executable. If you encounter conversion issues specific to the data or flags, the problem likely lies within g_reconvert.exe itself, and you might need to consult its official documentation or its developer (if available by running g_reconvert.exe /? or similar). The GUI tool provides an interface to set these flags in a more user-friendly manner.

This manual covers the functionalities of the GUI wrapper based on the current code version and known flags. Future updates to g_reconvert.exe or the wrapper might introduce new features or changes.