A desktop GUI for the
mlgidBASE
GIWAXS analysis pipeline.
Convert, detect, fit, match, edit and track, with the same algorithms and visual control.
Demo · Install · Features · Getting started · Changelog · Issues
mlgidGUI is the new name of mlgidLAB, from version 1.0. It is the same application, with the package and the command renamed to
mlgidgui. If you have mlgidLAB installed,Help → Update now…moves you over and keeps your files and settings; seeCHANGELOG.mdfor the details.
mlgidGUI drives the full pygid → mlgidDETECT → pygidFIT → mlgidMATCH
workflow in one PySide6 window: convert raw detector images to NeXus, then
detect / fit / match, review and edit peaks, track them across a
scan, and export.
Three short clips, one per stage of the workflow.
Open a raw 2D detector image, load the pyFAI PONI calibration and the detector mask, set the angle of incidence, attach sample metadata from a YAML file and convert to a q-space map.
mlgidgui_demo_conversion_captioned.mp4
Detect diffraction peaks with the ML model, 2D-fit a strong peak by hand, fit every detected peak and inspect the radial and angular profiles, then match the fitted peaks against a CIF library and review the identified phases.
mlgidgui_demo_pipeline_captioned.mp4
Open a completed scan, track each peak across its frames, interpolate the gaps (every missing frame is fitted and re-matched), play the scan and follow the matched phases as they grow and decay.
mlgidgui_demo_tracking_captioned.mp4
Recorded against v1.0.0.
Requires Python ≥ 3.11 (Linux / macOS / Windows). A fresh conda
environment is recommended: the [pipeline] extra pulls a large ML
stack (PyTorch + the in-house mlgid packages), so keep it isolated.
# create + activate an isolated environment
conda create -n mlgidgui python=3.12 -y
conda activate mlgidgui
# full pipeline (detection / fitting / matching + raw conversion)
pip install "mlgidgui[pipeline]"
mlgidguiOn Windows you can skip all of this: download the installer from the releases page and run it (no Python needed, includes the full pipeline). It is not code-signed, so SmartScreen asks once: More info, then Run anyway. Details in docs/getting_started.md.
No conda? Any Python ≥ 3.11 virtual environment works
(python -m venv mlgidgui && source mlgidgui/bin/activate).
Drop [pipeline] for view-only mode (browse and edit existing NeXus
results, in-GUI pyFAI calibration; Run buttons disabled). Full per-OS
install, a first-file walkthrough, and shortcuts are in
docs/getting_started.md.
| Open and view | NeXus or raw HDF5 by auto-detection, several files at once. Cartesian (q_xy / q_z) or polar view, frame playback, colormap, log/linear contrast, live cursor readout. Multi-GB stacks load lazily. |
| Convert | Raw detector images to NeXus, in batch, with an embedded pyFAI calibration dialog for PONI and mask. |
| Detect, fit, match | Run each stage from the Pipeline dock with every mlgidBASE parameter exposed, at frame, entry or all-entries scope. A workflow rail above the image shows what each stage has produced for the current frame. |
| Edit peaks | Manual boxes, Add to fitted (2D pygidfit or 1D), multi-select of detected or fitted peaks (Ctrl+click, Ctrl+A) on the image or in the tables, copy and paste (Ctrl+C / Ctrl+V, Ctrl+Shift+V for a frame range), batch 2D fit, bulk delete, full undo and redo. |
| Label fast | Quick select commits each hand-drawn box as you draw the next one, as a detected peak, a fitted one, or both. Each fit is stored under its detected peak's id, so a peak has one fit and deleting the detection takes the fit with it (both switchable in Settings). |
| Inspect | Sortable Detected / Fitted / Matched tables with click-sync to the image, live radial and angular profile fits, overlay filters. |
| Track | Follow peaks across the frames of a scan, fill the gaps, and view the matched phases and their amplitudes over time. |
| Edit the file | The Structure tab edits every group, field, attribute and link of the open NeXus/HDF5 file in place, with undo, copy and paste between files, and a check for anything that would stop the viewer or the pipeline from reading it. Nothing touches the file on disk until you save. |
| Export | Figures (matplotlib) and peaks as CSV. |
- Getting started: install, first run, shortcuts, troubleshooting.
- Backend compatibility: pipeline version policy and how to verify a backend bump.
- Example data: the
example.zipdataset is hosted once on the v0.1.0a9 release and reused for every version, so later releases carry no attachments. - Changelog: release highlights.
For contributor-facing architecture and module reference docs please contact me.
The citation for mlgidGUI will be listed here once the paper about it is published.
Looking for the version described in the JOSS paper? The paper (doi:10.21105/joss.08499) describes the original mlgidGUI annotation tool. Its code is in this repository at tag 0.5.1, archived at doi:10.5281/zenodo.17426687. If you use that tool, cite that paper.
mlgidGUI was called mlgidLAB until version 1.0. A previous annotation tool
from the same group also carried the name mlgidGUI (versions 0.3.8.6 to
0.6.2). Its full history is part of this repository: see tag
0.6.2 for its last
release. The former standalone repository mlgidGUI-legacy is archived.
MIT, see LICENSE. The optional [pipeline] extra pulls in
GPL-3.0 mlgidMATCH as a separate, optional dependency the GUI calls
(aggregation, not a derived work).
Nico Lerch, [email protected]. Issues and feedback via GitHub issues.