Release Notes
=============

.. This file is generated by doc/generate_release_notes.py from
   CHANGELOG.md. Do not edit it by hand.

1.5.0 (2026-06-07)
------------------

This is a feature release focused on scripted/headless operation, release infrastructure, documentation, and several GUI and integration robustness fixes.

orGUI now has two startup modes. The default graphical user interface is still the normal interactive application for inspecting images, setting reference reflections, adjusting ROIs, and visually checking the experiment geometry. The new command line interface is selected with ``--cli``, ``--nogui``, or ``--headless`` and is intended for scripting, batch jobs, and cluster use. In CLI mode users can run a Python startup script with ``-i`` / ``--input`` and work with the preloaded ``app``, ``orgui``, and ``ub`` objects instead of clicking through the GUI.

Scientific and analysis-impacting fixes:

- Masked pixels are now excluded from rocking-scan counters and the same mask handling is applied to the static background image and correction arrays used in rocking integration. Results from workflows that combine rocking integration with masks, static background subtraction, or correction arrays should be checked against the new behavior.
- Fixes for NumPy 2.x compatibility.
- Reference reflection tables with image numbers outside the currently loaded scan no longer crash the GUI. Invalid image numbers are reported as warnings and the reflection table is updated more defensively.

CLI and scripting highlights:

- ``orGUI --cli`` / ``--nogui`` / ``--headless`` start the headless path, and ``-i`` / ``--input`` runs a Python startup script with ``app``, ``orgui``, and ``ub`` already available.
- ``--keep-running`` keeps the application alive after a startup script and can drop into the embedded shell for interactive inspection.
- ``--cpus``, ``--logfile``, ``--errorlog``, and HDF5 file-locking options make batch and cluster runs easier to control.
- CLI runs now print progress and errors to the terminal or selected log files, so batch jobs can finish or fail without waiting for a hidden dialog.
- Batch-oriented helpers were added for static and rocking ROI workflows, including support for multiple manually defined static rocking scans.

Documentation:

- The orGUI documentation is now available on Read the Docs: <https://orgui.readthedocs.io/>.
- End-user release notes are available in this changelog and on the Read the Docs release-notes page: <https://orgui.readthedocs.io/en/latest/release_notes.html>.

Other user-visible changes:

- Log files can be written for normal and error output.
- Backend load errors are more verbose.
- CHESS QM2/id4b backend examples now include the z motor in the scanned motor list, and QM2 log files can be parsed for more accurate timestamps.
- ``NUMEXPR_MAX_THREADS`` defaults to 1 when not already set, avoiding oversubscription during parallel or cluster runs.

Thanks to Finn Schröter (Finnjek) for the NumPy 2.x miscut fix and Bragg reflection image-number crash fix.

1.5.0-rc.1 (2026-05-15)
-----------------------

Release candidate for v1.5.0. The full user-facing release notes are included in the final `1.5.0 <#150-2026-06-07>`_ section above.

1.4.1 (2026-03-27)
------------------

This is a bugfix and maintenance release.

*The last version to support python <=3.10 and NumPy 1.x.*

Two ***critical bugs*** were fixed that affect physics calculations:

- Allowed Bragg reflections close to the search bounds (usually high Q) were sometimes not found. This bug was present in all previous versions <v1.4.0.
- The complex phase of the Fourier components rho_G of the electron density along z was incorrectly calculated (zDensity_G). This bug was present in all previous versions <v1.4.0.

pyFAI versions 2025.12.0, 2025.12.1 and 2026.2.0 cause a software crash when selecting a detector in the machine parameters.

1.4.0 (2026-01-20)
------------------

This is a feature release with lots of additional bug fixes.

- Added a new dialog which automatically calculates the position of the Bragg peak, which helps to improve the U matrix the most and adds it to the list of reference reflections.
- Added a Bragg peak search, which searches for the center of mass in a small section of multiple images. This can be used to quickly find the image and position of a Bragg peak. To be used when an estimate of the Bragg position is already given (such as with the new Bragg peak dialog)
- Auxilliary counters (potential, temperature, ...) are now also integrated in all integration functions.
- A static background image can now be subtracted from the detector images. This can be used to subtract static sample environment scattering such as water or air (beamline background) scattering.
- Multiple scans can be concatenated and treated as a single scan. This is done to avoid high-intensity sample positions which would lead to damage to the detector (Thanks to Finn!).
- Positions of Bragg reflections can now be integrated as rocking scans. This enables fast conventional single crystal X-ray difffraction analysis of Bragg reflection structure factor. Strain with respect to the reference lattice can be added for epitaxially grown thin films.
- 2D ROI size can now be dynamically adjusted. Currently, the ROI size can be corected for
- Peak size increase due to scattered beam - detector inclination
- Peak size increase due to the illuminated sample size. Currently, the sample is approximated as a cuboid (size to be set in Advanced ROI options dialog) and its outlines are projected onto the detector.
- The orGUI hdf5 data base can now be compressed using `hdf5plugin <https://github.com/silx-kit/hdf5plugin>`_. This compression is not visible to the user, but reduces the file size by a factor of 2x - 3x. Calculation speed loss is possible and depends on the OS, available libraries , etc. See `Issue #16 <https://github.com/tifuchs/orGUI/issues/16>`_ for an overview. Opening compressed data bases with external software requires the user to install and import `hdf5plugin <https://github.com/silx-kit/hdf5plugin>`_.

1.3.0 (2025-07-22)
------------------

This is a feature release with major improvements and bugfixes (\> 40 commits), while still preserving mostly backward compatibility. One potential incompatibility is the file format of saved rocking scans, which had to be changed for more efficient saving of the data (see the Changed section).

- Simplisitic rocking scan integration feature is now available. Conventional rocking scans (\$phi\$- or \$omega\$-scans) and reflectivity rocking scans are supported.

- New tab in main GUI called \``Rocking scan integrate\``:
- Select rocking scan in database, which was previously ROI integrated, right click and select show as rocking scan to display the data in the new tab.
- 1D ROIs can be added in the Modify ROIs area. These are set relative to the calculated position of the reflection. They are shown in the graph as vertical lines.
- ROI positons can be modified by drag+drop. ROIs which are selected as anchor are fixed when using the Fit between anchors feature.
- Fit between anchors linearly interpolates between ROI anchor positions
- Lorentz and footprint corections can be applied.
- Saving/Loading of ROI locations

This process is very manual at the moment, but will be improved in the future.

- Image integration is now thread-parallel and jit compiled while releasing the gil in numba nopython nogil mode, leading to a speedup of up to 10x (depending on available thread count).

- Refactored CTR calculation code, which is now split internally into the following modules:

- CTRcalc: Main entry point for the CTR calculation, the end user should only use this top level API. API should be completely backward compatible.
- CTRutil: reading of constants (form factors etc.), Fit functionality such as FitMixins, Parameter class, ...
- CTRuc: fundamental structure factor calculation of simple unit cells and water models
- CTRfilm: Code to construct coherent thin films on a substrate. Includes interfacial models such as Skellam interfacial roughness

Thanks to Finn for the rocking extraction script, changing the default scan name, fixing the reflections view bug and the maintenance of the ID31 backend.

1.2.0 (2024-12-03)
------------------

Release that adds 3 major improvements:

1.  Rocking scan integration is now properly supported with fast calculation speed and visulalization of the ROIs
2.  Backends can now be loaded as standalone python file. No reinstalling of orGUI is required to add new backends.
3.  hdf5 file handling has been improved to enable reloading of changed hdf5 files

In addition, there are many more smaller improvements and changes. See the detailed changelog.

1.1.2 (2024-11-04)
------------------

Bugfix version that fixes a bug that prevents installing orGUI on certain systems. Full install target advertised on pypi is now available. More minor bug fixes, see Fixed list.

1.1.1 (2024-08-07)
------------------

Version that fixes a critical bug in the config file reading when a poni file is given.

1.1.0 (2024-08-05)
------------------

This is a release, that reworks the configuration widgets. It is aimed to correctly show all configuration options in the GUI, which were previously only available through the config file.

orGUI now also has a proper logo.

- Enable optional loading of atomic coordinates and lattice from `ASE <https://wiki.fysik.dtu.dk/ase/>`_ supported files. These include:
- Cif files
- VASP / CONTCAR files
- many more ... see `files supported by ASE <https://wiki.fysik.dtu.dk/ase/ase/io/io.html>`_

1.0.1 (2024-07-31)
------------------

First release version on PyPi, project availabe under `orGUI <https://pypi.org/project/orGUI/>`_. This version aimes to fix some minor issues from the first release and provides a minimal documentation in form of a README and a diffractometer image showing the geometry.

1.0.0 (2024-06-29)
------------------

- First public release on Zenodo with the DOI <https://doi.org/10.5281/zenodo.12592486>.
- Added MIT License
- Merged with *datautils*
- Backends
- datautils.xrayutils.id31_tools -\> orgui.backend.beamline.id31_tools
- datautils.xrayutils.P212_tools -\> orgui.backend.beamline.P212_tools
- datautils.xrayutils.ID31DiffractLinTilt -\> orgui.backend.beamline.ID31DiffractLinTilt
- datautils.xrayutils.fio_reader -\> orgui.backend.beamline.fio_reader
- Physics / Diffraction caculations
- datautils.util -\> orgui.datautils.util
- datautils.xrayutils.unitcells -\> orgui.datautils.xrayutils.unitcells (and .bul files therein)
- datautils.xrayutils.test -\> orgui.datautils.xrayutils.test (and datautils test code therein)
- datautils.xrayutils.CTRcalc -\> orgui.datautils.xrayutils.CTRcalc
- datautils.xrayutils.\_CTRcalc_accel -\> orgui.datautils.xrayutils.\_CTRcalc_accel
- datautils.xrayutils.CTRopt -\> orgui.datautils.xrayutils.CTRopt
- datautils.xrayutils.CTRplotutil -\> orgui.datautils.xrayutils.CTRplotutil
- datautils.xrayutils.DetectorCalibration -\> orgui.datautils.xrayutils.DetectorCalibration
- datautils.xrayutils.element_data -\> orgui.datautils.xrayutils.element_data
- datautils.xrayutils.HKLVlieg -\> orgui.datautils.xrayutils.HKLVlieg
- datautils.xrayutils.ReciprocalNavigation -\> orgui.datautils.xrayutils.ReciprocalNavigation
- *orGUI* is now a standalone package, that has only publicly available dependencies.

0.9-alpha (2024-06-29)
----------------------

- Last inoffical version before merge with the internal dependency *datautils*.
- Last version under *All rights reserved*.