Startup And Configuration¶

This page describes the normal graphical user interface (GUI) startup path and the configuration file used to initialize orGUI. It is intended for users who already know the beamline, detector calibration, sample lattice, and scan file format they want to use.

Start orGUI with a configuration file from a terminal:

orGUI examples/config_minimal

The same configuration can also be loaded from the GUI with Config -> Load config.

Configuration File Overview¶

The config file is an INI-style text file. Section names are written in square brackets, and values are written as key = value pairs. Relative file paths, such as ./poni_files/P3_100_calib.poni, are resolved relative to the directory containing the config file.

The main sections are:

[Machine]: X-ray source, detector geometry, detector size, pixel size, and optionally a pyFAI .poni calibration file.
[Lattice]: Crystal lattice and, optionally, a crystal/unit-cell file containing the atomic basis used for structure-factor based Bragg reflection and CTR calculations.
[Diffractometer]: Sample and instrument angles used to connect detector pixels to reciprocal space.
[backend]: Optional scan-loading backend selection. This can point to a backend Python file or select a registered beamtime/backend id.
[Settings]: GUI startup behavior and output database compression.
[Mask]: Optional invalid/dead-pixel mask. Nonzero pixels are treated as invalid.
[Mask.PixelRepair]: Optional conservative repair settings for tiny masked defects during ROI summing. Repair is disabled when this section is missing or enabled = False.

Full Configuration Example¶

This example combines the commonly used settings from the bundled example files. It uses a pyFAI PONI file for detector geometry, a CIF file for the crystal unit cell, a backend file for scan loading, and explicit GUI settings.

[Machine]
# Detector calibration from pyFAI.
# When this is set, the PONI file supplies the detector geometry and
# wavelength used by orGUI.
poni = ./poni_files/P3_100_calib.poni

# Fallback detector/source values. These are useful when no PONI file is
# given. If a PONI file is given, the loaded PONI geometry takes precedence.
# Energy is in keV.
E = 77.0
# Sample-detector distance is in m.
SDD = 0.78
# Detector pixel size is in m.
pixelsize = 172e-6
# Detector size is in pixels.
sizex = 1475
sizey = 1679
# Direct-beam position is in detector pixels.
cpx = 731.0
cpy = 1587.856

[Lattice]
# Crystal/unit-cell file used for structure-factor based Bragg reflection
# and CTR calculations. CIF files require ASE support.
crystal = ./crystal_files/Pt_mp-126_symmetrized.cif

# Refraction correction parameter. This is usually delta in n = 1 - delta.
# Set to 0 if no refraction correction should be applied.
refractionindex = 1.1415e-06

# Optional lattice override. If these values are present, they replace the
# lattice constants read from the crystal file while preserving relative
# atomic coordinates.
# Lengths are in Angstrom; angles are in degrees.
# a1 = 3.9242
# a2 = 3.9242
# a3 = 3.9242
# alpha1 = 90.0
# alpha2 = 90.0
# alpha3 = 90.0

[Diffractometer]
# Rotates the diffractometer around the beam direction, in degrees.
azimuthal_reference = 90

# Polarization correction settings.
polarization_axis = 0
polarization_factor = 1

# User-facing diffractometer angles are in degrees.
mu = 0.1
chi = 0
phi = 0

[backend]
# Either load a backend file...
file = ./backend/P212_backend.py

# ...or select a registered backend/beamtime id instead.
# beamtime = id31_default

[Settings]
# Automatically load all images to create max/sum images when opening a scan.
autoload = True

# Output database compression. Raw is the most portable option.
# Other filters require the corresponding HDF5/plugin support.
compression = Raw

[Mask]
# Optional invalid/dead-pixel mask. Path may be absolute or relative to this
# config file. Masks are loaded with FabIO, so EDF, NumPy .npy, and other
# FabIO-readable 2D image formats are supported.
mask = ./masks/dead_pixels.edf

[Mask.PixelRepair]
# Optional conservative repair of tiny masked defects during ROI summing.
# Missing section or enabled=False disables repair.
enabled = False
max_component_pixels = 4
max_span = 3
radius = 2
min_valid_neighbors = 6
use_pyfai_gaps = True
gap_size_px = 6

Machine Section¶

The simplest detector setup gives the detector distance, pixel size, detector shape, and direct-beam pixel position directly in the config file. These values are enough for basic detector geometry when no PONI file is used.

If poni is set, orGUI loads detector geometry from that pyFAI file. In that case, the PONI file provides the detector geometry and wavelength used by the loaded detector model. The explicit E, SDD, pixelsize, sizex, sizey, cpx, and cpy entries remain useful documentation and fallback values, but the PONI calibration is the active geometry.

Common units in this section:

E: keV
SDD: m
pixelsize: m
sizex / sizey: pixels
cpx / cpy: pixels

Lattice Section¶

The [Lattice] section defines the crystal lattice and, optionally, the atomic basis. There are two common levels of detail:

Lattice constants only: orGUI can show all integer Bragg positions for that lattice, but it does not know which reflections are forbidden by the basis.
Crystal/unit-cell file: orGUI reads atomic coordinates and can calculate structure-factor based Bragg reflections and available CTRs.

Lattice constants use Angstrom and degrees:

[Lattice]
a1 = 2.7740
a2 = 2.7740
a3 = 6.7960
alpha1 = 90.0
alpha2 = 90.0
alpha3 = 120.0
refractionindex = 1.1415e-06

For structure-factor based calculations, add crystal = ...:

[Lattice]
crystal = ./crystal_files/Pt_mp-126_symmetrized.cif
refractionindex = 1.1415e-06

If both crystal and explicit lattice constants are present, orGUI keeps the relative atomic coordinates from the crystal file and overrides the lattice constants with the values in the config.

Diffractometer Section¶

The [Diffractometer] section sets the instrument orientation used by the detector-to-reciprocal-space transform. These values are user-facing GUI/config values and are written in degrees.

[Diffractometer]
azimuthal_reference = 90
polarization_axis = 0
polarization_factor = 1
mu = 0.1
chi = 0
phi = 0

azimuthal_reference rotates the diffractometer around the beam direction. mu is the angle of incidence. chi and phi set the sample orientation circles. The polarization settings are used when polarization correction is enabled during integration.

Backend Section¶

The backend tells orGUI how to read scan metadata and image locations for a beamline or file format. A config can either load a backend Python file:

[backend]
file = ./backend/P212_backend.py

or select a registered backend id:

[backend]
beamtime = id31_default

When beamtime is used, orGUI selects that backend in the scan-data panel and disables backend auto-detection. If neither option is set, the GUI can still use the backend selector and auto detect controls in the Scan data dock.

Settings Section¶

autoload controls whether orGUI automatically loads all images to create a maximum and summed image when a scan is opened. This is convenient for interactive browsing, but can be slow for large scans.

compression selects the compression filter for new output database files. Raw is always the safest portable choice. Other choices, such as Blosc-lz4-Shuffle-5, require matching HDF5/plugin support in the runtime environment.

Mask Sections¶

The optional [Mask] section configures an invalid/dead-pixel detector mask. The mask file is loaded with FabIO, matching the image-format handling used by the pyFAI/silx mask tooling. EDF, NumPy .npy, and other FabIO-readable 2D image formats are supported.

Mask values are interpreted as a boolean invalid-pixel mask:

zero or False: valid detector pixel
nonzero or True: invalid detector pixel

Relative mask paths are resolved relative to the config file:

[Mask]
mask = ./masks/dead_pixels.edf

If [Mask] is missing, or mask is omitted, no config mask is loaded. The GUI mask editor can still be used interactively.

Pixel Repair Settings¶

[Mask.PixelRepair] enables conservative repair of tiny masked defects during ROI summing. It is optional. Missing [Mask.PixelRepair] or enabled = False disables repair.

Pixel repair requires the C++ ROI backend. If repair is enabled in the config but the C++ backend is unavailable, orGUI logs a warning and continues without repair.

[Mask.PixelRepair]
enabled = True
max_component_pixels = 4
max_span = 3
radius = 2
min_valid_neighbors = 6
use_pyfai_gaps = True
gap_size_px = 6

enabled: Enables repair when set to True. Repair is only applied in C++ ROI summing paths and only for eligible masked defects.
max_component_pixels: Maximum connected masked component size, in pixels, that may be repaired. Larger connected masked regions remain masked.
max_span: Maximum row span or column span, in pixels, for a repairable component. This rejects elongated defects even when the total component size is small.
radius: Local search radius, in pixels, used to find original-valid neighboring pixels for interpolation.
min_valid_neighbors: Minimum number of original-valid neighboring pixels required inside radius. The neighbors must also be distributed on enough sides of the defect; a one-sided neighborhood is rejected.
use_pyfai_gaps: When True, analytical detector gaps from pyFAI are excluded from repair. orGUI asks the pyFAI detector for its analytical mask and reduces full-row and full-column masked stripes to [start, stop) gap intervals.
gap_size_px: Fallback detector-gap width, in pixels, for the module-metadata path. This is used only when pyFAI cannot provide a useful analytical gap mask, detector module positions are known, and the detector metadata do not provide the gap width. It is not a mask dilation radius.

For the repair algorithm and the exact accounting rules for repaired pixels, see Pixel Repair Algorithm.

Crystal File Options¶

The crystal key in [Lattice] can refer to different ways of describing the same basic information: a lattice and, when available, the atomic basis of a crystal unit cell.

CIF Files¶

CIF support uses the ASE package. A simple reference looks like:

[Lattice]
crystal = ./crystal_files/Pt_mp-126_symmetrized.cif
refractionindex = 1.1415e-06

CIF is a good choice when the structure is available from crystallographic databases or other structure-building tools.

orGUI `.bul` Files¶

.bul files are orGUI-specific unit-cell files. They are also compatible with bulk files from the surface diffraction modeling software ANA-ROD. The ESRF ANA-ROD page describes ANA, AVE, and ROD as surface-diffraction programs originally written by Elias Vlieg and later maintained at ESRF.

Example config reference:

[Lattice]
crystal = ./crystal_files/Pt100.bul
refractionindex = 1.1415e-06

Minimal .bul content:

// Pt(100) larger unit cell for compatibility
return
3.9242 3.9242 3.9242 90.0000 90.0000 90.0000
Pt     0.00000     0.00000     -1.00000  0.4353  0.4353  1.0000
Pt     0.50000     0.50000     -1.00000  0.4353  0.4353  1.0000

Bundled .bul files can also be referenced by name, for example:

[Lattice]
crystal = Pt100

orGUI `.xtal` Files¶

.xtal files are orGUI-specific crystal model files. When used for GUI orientation and reflection calculations, orGUI reads the bulk unit cell from the file.