# Python MLog Tool

Python desktop and CLI tool for parsing Firmament `mlog` binary files, exporting each bus to CSV, and plotting signals in a Qt GUI.

## Features

- Parse binary `mlog` files into structured bus data.
- Export each bus group to an individual CSV file.
- Inspect and compare signals in a `PySide6 + PyQtGraph` desktop GUI.
- View parsed parameter groups directly in the GUI.
- Build a platform-native single-file executable with `PyInstaller`.

## Project Layout

```text
python_mlog_tool/
├── README.md
├── pyproject.toml
├── mlog_tool_qt.spec
├── scripts/
│   ├── build_qt_exe.sh
│   └── build_qt_exe.ps1
├── examples/
│   └── example_usage.py
├── src/
│   ├── qt_gui_entry.py
│   └── mlog_tool/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       ├── constants.py
│       ├── exporters.py
│       ├── models.py
│       ├── parser.py
│       ├── plotting.py
│       ├── qt_gui.py
│       ├── qt_plot_widget.py
│       ├── services.py
│       └── utils.py
└── tests/
    └── test_parser.py
```

## MATLAB Mapping

- `mlog_parser(logfile)` -> `MLogParser.parse(log_path)`
- `generate_MAT(...)` -> `CsvExporter.export_all(parsed_log, output_dir)`
- `get_param_val(...)` -> `ParsedLog.get_parameter(group_name, param_name)`

## Install

Install the base dependencies into the local virtual environment:

```bash
uv pip install --python ./.venv/bin/python -e .
```

Install the Qt GUI dependencies:

```bash
uv pip install --python ./.venv/bin/python ".[qt]"
```

Install the packaging dependency:

```bash
uv pip install --python ./.venv/bin/python ".[bundle]"
```

## Quick Start

Parse a sample log and open the Qt GUI:

```bash
PYTHONPATH=src ./.venv/bin/python -m mlog_tool parse ../mlog16.bin
PYTHONPATH=src ./.venv/bin/python -m mlog_tool.qt_gui
```

## Run From Source

CLI:

```bash
PYTHONPATH=src ./.venv/bin/python -m mlog_tool parse ../mlog16.bin
PYTHONPATH=src ./.venv/bin/python -m mlog_tool export ../mlog16.bin ./csv_output
```

Qt GUI:

```bash
PYTHONPATH=src ./.venv/bin/python -m mlog_tool.qt_gui
```

## Build Executable

Build the Qt GUI into a single executable:

Linux:

```bash
./scripts/build_qt_exe.sh
```

Windows PowerShell:

```powershell
.\scripts\build_qt_exe.ps1
```

Output:

```text
dist/mlog-tool-qt
dist/mlog-tool-qt-v<version>-linux-<arch>
dist/mlog-tool-qt.exe
dist/mlog-tool-qt-v<version>-windows-<arch>.exe
```

Run it with:

```bash
./dist/mlog-tool-qt
```

Windows:

```powershell
.\dist\mlog-tool-qt.exe
```

On first launch, PyInstaller will unpack its runtime files into a temporary directory automatically.

The build script also creates a versioned copy that is convenient for release delivery.

## Notes

- The Qt GUI parses the selected log immediately after opening the file.
- The generated CSV files are organized one bus per file.
- The left panel is split into `Parameters` and `Buses`.
- Parameter details are viewed in the lower-right table and are not plottable.
- Cursor mode supports left-click freeze and right-click release directly on the plot.
- `src/qt_gui_entry.py` exists only as a PyInstaller-friendly GUI entry point for the onefile build.

## Release Checklist

1. Update `project.version` in `pyproject.toml`.
2. Rebuild with `./scripts/build_qt_exe.sh` on Linux or `.\scripts\build_qt_exe.ps1` on Windows.
3. Deliver the versioned file from `dist/`.
4. Keep the unversioned `dist/mlog-tool-qt` as the latest local convenience build.