Metadata-Version: 2.4
Name: edcal
Version: 1.0.1
Summary: GUI software for energy and q calibration of energy-dispersive X-ray detectors, built on Algodif.
Author-email: Nghia Vo <nvo@bnl.gov>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/algodif/edcal
Project-URL: Source, https://github.com/algodif/edcal.git
Keywords: EDXD,EDRXD,Energy-dispersive X-ray diffraction,Detector calibration,Energy calibration,Q calibration,GeRM detector
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: algodif>=1.1.0
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: h5py
Requires-Dist: joblib
Requires-Dist: PySide6
Requires-Dist: pyqtgraph
Dynamic: license-file

# EDCal
#### (**E**)nergy-(**D**)ispersive X-ray detector (**Cal**)ibration GUI

---

*Python GUI software for energy and q calibration of energy-dispersive X-ray 
detectors, built on [Algodif](https://github.com/algodif/algodif), PySide6 and 
pyqtgraph.*

---

Features
========

The GUI has two main tabs, switchable at any time:
1. Q calibration.
2. Energy calibration.

Each tab keeps its own data, results and status bar. The colour theme is
shared.  Plots: mouse wheel to zoom, drag to pan, the 'A' button (bottom-left of a
plot) to show the full view. The **Reset** button in the *Image display* group
resets the contrast and zooms out the plots of the current tab.

Q calibration
-------------

![img](https://github.com/algodif/edcal/raw/main/figs/q_calib_gui.png)

Workflow (based on the q_calibration_*.py scripts in [Algodif examples](https://github.com/algodif/algodif/tree/main/examples)):
1. Load data (image, HDF, or GeRM dat file; multiple files are averaged).
2. Reference pattern: select a calibrant shipped with algodif (Al2O3, CeO2,
   Cr2O3, LaB6, Si) and/or input d-spacings manually. Choose how the q-step
   (q per pixel) is obtained:
    - Constant q-step: same for all strips (can be estimated from two
      peaks in the Processing tab).
    - GeRM geometry, q-step per strip: estimated from the detector
      geometry, two-theta and the energy step. The reference pattern
      then varies between strips.
    - GeRM geometry, energy matching: peaks are matched in energy
      space using energies estimated from the geometry.
3. Single-strip calibration: preprocess, detect/edit peaks, locate them
   with sub-pixel accuracy, match to reference q-values, and fit.
4. Multiple-strip calibration: calibrate groups of strips with their own
   parameters, check and correct the image to a uniform q-grid.
5. Data correction: correct new data with the calibrated coefficients.



Energy calibration
------------------
![img](https://github.com/algodif/edcal/raw/main/figs/energy_calib_gui.png)

Workflow (based on the calibrate_energy_*.py scripts in [Algodif examples](https://github.com/algodif/algodif/tree/main/examples)):
1. Load data (image, HDF, or GeRM dat file; multiple files are averaged,
   e.g. measurements of different calibrants).
2. Reference spectrum: fluorescence lines of the calibrants from the
   xraydb database and/or manual lines (keV), broadened on the energy
   grid given by the energy step (keV per pixel).
3. Single-strip calibration: preprocess, detect/edit peaks, locate them
   with sub-pixel accuracy, match to reference energies, and fit. Add
   the results of calibrated strips and save them (JSON, CSV).
4. Multiple-strip calibration: calibrate groups of strips with their own
   parameters, check and correct the image to a uniform energy grid,
   and save the coefficients and energy maps.
5. Data correction: correct new data with the calibrated coefficients.

Design
======

The software is structured based on the RUI (Rendering-Utilities-Interactions)
concept, a user-friendly adaptation of the MVC design pattern:
- `edcal/lib/utilities.py`: constants and helper methods without GUI 
  dependencies.
- `edcal/lib/rendering.py`: themes, plot helpers, and window layouts.
- `edcal/lib/interactions.py`: user actions, calculations, and the 
  application controller.
- `edcal/main.py`: application entry.

Installation
============

Install [Miniconda, Anaconda or Miniforge](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html), then 
open a Linux terminal or the Miniconda/Anaconda PowerShell prompt and use the 
following commands for installation.

Using pip:
```commandline
pip install edcal
```
Using conda:
```commandline
conda install -c algotom -c conda-forge edcal
```
Once installed, launch EDCal with
```commandline
edcal
```
---
Installing from source:
- Create a conda environment
  ```commandline
  conda create -n edcal python=3.11
  conda activate edcal
  ```
- Clone the source (git needs to be installed)
  ```commandline
  git clone https://github.com/algotom/edcal.git
  ```
- Navigate to the cloned directory (having the pyproject.toml file)
  ```commandline
  pip install .
  ```
- Or run without installing, from the cloned directory, in an environment 
  having the packages in requirements.txt:
  ```commandline
  python -m edcal.main
  ```

Building a conda package from the recipe:
```commandline
conda install conda-build
conda build -c algotom -c conda-forge recipe
```

Generating the executable application
-------------------------------------

- Install the packages in requirements.txt, PyInstaller, and Pillow (to 
  convert the PNG icon) in your environment.
- From the repository root, run:
  ```commandline
  python build_exe_app.py
  ```
- The application is generated in the **build_app/EDCal** folder. To move 
  the app to a different place, move the entire folder.
