Metadata-Version: 2.4
Name: mlgidGUI
Version: 0.6.1
Summary: A GUI program for GIWAXS images analysis and annotation
Author-email: Constantin Völter <constantin.voelter@gmail.com>, Vladimir Starostin <v.starostin.m@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/mlgid-project/mlgidGUI
Keywords: xray,python,giwaxs,scientific-analysis
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.12.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: appdirs>=1.4.4
Requires-Dist: h5py>=3.14.0
Requires-Dist: networkx>=3.5
Requires-Dist: numpy>=2.2.6
Requires-Dist: opencv-python-headless>=4.12.0.88
Requires-Dist: packaging>=25.0
Requires-Dist: pathvalidate>=3.3.1
Requires-Dist: periodictable>=2.0.2
Requires-Dist: pillow>=11.3.0
Requires-Dist: PyQt5>=5.15.11
Requires-Dist: pyqtgraph>=0.13.0
Requires-Dist: qdarkgraystyle>=2.0.0
Requires-Dist: QDarkStyle>=3.2.3
Requires-Dist: requests>=2.32.4
Requires-Dist: scipy>=1.16.1
Requires-Dist: tifffile>=2025.6.11
Requires-Dist: typing_extensions>=4.14.1
Requires-Dist: transliterate>=1.10.2
Requires-Dist: xmlobj>=1.2.2
Requires-Dist: xrayutilities>=1.7.10
Dynamic: license-file

# _mlgidGUI_
![Logo of mlgidGUI](docs%2Fimages%2Fmlgid_logo.png)
## Project summary

_mlgidGUI_ is a graphical tool for the analysis and annotation of 2D scattering data e.g. Grazing-Incidence Wide-Angle X-ray Scattering (GIWAXS).
The resulting datasets can be used for training and testing ML models or further manual analysis. 
_mlgidGUI_ is well suited for the annotation of 2D diffraction images with radial symmetry.
In particular, it focuses on grazing-incidence wide-angle scattering data analysis and its specific needs.

## Installation

### Recommended: Precompiled AppImage or EXE
Readily compiled packages for the x64 architecture with Windows and Unix are available at the releases page:
[https://github.com/mlgid-project/mlgidGUI/releases](https://github.com/mlgid-project/mlgidGUI/releases)

To run the program on Windows simply double click on the file and ignore the security warnings.


Follow these instructions to run the AppImage: [https://docs.appimage.org/introduction/quickstart.html](https://docs.appimage.org/introduction/quickstart.html)

### Alternative: Installation with conda
* Install miniconda
[https://www.anaconda.com/download/success#miniconda](https://www.anaconda.com/download/success#miniconda)
* Create environment
`conda create -n mlgidGUI python=3.12 pip`
* Activate environment
`conda activate mlgidGUI`

Clone with git:

`git clone https://github.com/mlgid-project/mlgidGUI.git`

`cd ./mlgidGUI`

`pip install ./`

`python3 main.py`


### Alternative: Installation from PyPI

`pip install mlgidGUI`
* Apply a Patch to pyqtgraph

`pip install git+https://github.com/pyqtgraph/pyqtgraph.git@6eb0bf1a928c3e8fef332bbebe8a9da3be0ab19a`

## Usage

Import images or HDF5 files into the program, select an image in the Project Manager and begin labeling.
To add annotations, hold `Ctrl + Alt`, then click, hold, and drag the mouse over the image, similar to using a shape-drawing tool.
The key combination `Ctrl + H` can be used to hide the annotations. The annotated data  can be exported as PASCAL-VOC 
dataset or as an HDF5 file.

- We added a CIF file, a GIWAXS image, and an HDF5 file in the `docs\example_files` folder to provide the user with examples.
- For a short demonstration of the program usage, please refer to the [Workflow section](./docs/WORKFLOW.md).
- For a detailed guidance, please refer to the [Documentation section](./docs/DOCUMENTATION.md)


## Papers

This project is part of our broader efforts to improve and automate GIWAXS analysis. Below is a list of related papers.

### ML-based peak detection and structure refinement

_Tracking perovskite crystallization via deep learning-based feature detection on 2D X-ray scattering data_

V. Starostin, V. Munteanu, A. Greco, E. Kneschaurek, A. Pleli, F. Bertram, A. Gerlach, A. Hinderhofer, and F. Schreiber. npj Comput Mater 8, 101 (2022) [https://doi.org/10.1038/s41524-022-00778-8](https://doi.org/10.1038/s41524-022-00778-8)

### Deployment at synchrotron facilities for real-time analysis

_End-to-end deep learning pipeline for real-time processing of
surface scattering data at synchrotron facilities_

V. Starostin, L. Pithan, A. Greco, V. Munteanu, A. Gerlach, A. Hinderhofer, and F. Schreiber. Synchrotron Radiation News, 35:4, 21-27 (2022) [https://doi.org/10.1080/08940886.2022.2112499](https://doi.org/10.1080/08940886.2022.2112499)

### Benchmarking peak detection

_Benchmarking deep learning for automated peak detection on GIWAXS data_

C. Völter, V. Starostin, D. Lapkin, V. Munteanu, M. Romodin, M. Hylinski, A. Gerlach, A. Hinderhofer, F. Schreiber. Journal of Applied Crystallography (2025) accepted [https://doi.org/10.1107/S1600576725000974](https://doi.org/10.1107/S1600576725000974)

