Skip to content
mlgid-projectPublic

About

mlgidGUI: graphical interface for the mlgidBASE GIWAXS analysis pipeline (formerly mlgidLAB)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

mlgidGUI

CI Latest release Python 3.11 or newer MIT license

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; see CHANGELOG.md for 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.

See it in action

Three short clips, one per stage of the workflow.

1. Convert raw detector images

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

2. Detect, fit and match

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

3. Track peaks across a scan

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.

Install & launch

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]"
mlgidgui

On 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.

What you can do

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.

Documentation

  • Getting started: install, first run, shortcuts, troubleshooting.
  • Backend compatibility: pipeline version policy and how to verify a backend bump.
  • Example data: the example.zip dataset 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.

Citing

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.

Name

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.

License

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).

Contact

Nico Lerch, [email protected]. Issues and feedback via GitHub issues.

About

mlgidGUI: graphical interface for the mlgidBASE GIWAXS analysis pipeline (formerly mlgidLAB)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages