API

Application Entry Point

Module descripiton

orgui.main.positive_int(value)

Argparse type: require a strictly positive integer.

orgui.main.writable_file(path: str)

Argparse type: ensure the file can be created or written.

Main GUI

class orgui.app.orGUI.orGUI(configfile, parent=None)

Bases: QMainWindow

get_rocking_coordinates(H_0=None, H_1=None, maxValue=None, step_width=None, **kwargs)

Calculate detector coordinates along a reciprocal-space line.

The trajectory is the line \(\vec{H}_0 + s\vec{H}_1\) in reciprocal space, where \(\vec{H}_0\) is a reciprocal-space origin vector, \(\vec{H}_1\) is a direction vector, and \(s\) is a scalar trajectory coordinate.

Parameters:

• H_0 (numpy.ndarray) – Starting reciprocal-space vector in r.l.u. Shape (3,).

• H_1 (numpy.ndarray) – Reciprocal-space direction vector in r.l.u. Shape (3,).

• maxValue (float) – Maximum scalar \(s\) value sampled along \(\vec{H}_0 + s\vec{H}_1\).

• step_width (float) – Step width in scalar s units.

Returns:

Reflection dictionary with detector pixel coordinates, masks, and trajectory values.

Return type:

dict

Note

CLI-capable. Missing arguments are read from GUI widgets.

get_Bragg_rocking_coordinates(strainVec=None, **kwargs)

Calculate detector coordinates for Bragg rocking reflections.

Parameters:

strainVec (numpy.ndarray) – Optional fractional strain applied component-wise to the direct lattice constants a before calculating Bragg coordinates. This scales each lattice constant as a_strained = a * (1 + strainVec) and does not represent a full strain tensor. If omitted, GUI spin boxes are read and interpreted as percent strain.

Returns:

Reflection dictionary with hkl values in r.l.u., detector pixel coordinates, angles in rad, and masks.

Return type:

dict

Note

CLI-capable for th scans when state is already configured.

intkeys_rocking(refldict, **kwargs)

Build center ROI slice coordinates for rocking-scan integration.

This converts detector coordinates from refldict into rectangular center-ROI slice tuples. The slice tuple order is detector (x, y)/(horizontal, vertical). NumPy images are indexed as image[y_slice, x_slice], so integration code applies these slices as key[::-1]. Coordinates and ROI extents are clipped to the detector bounds.

Parameters:

• refldict (dict) – Reflection dictionary produced by a rocking coordinate helper. For CTR-style rocking scans, it represents points sampled along the reciprocal-space line \(\vec{H}_0 + s\vec{H}_1\). The selected intersection must provide xy_<intersect> detector coordinates in pixels, and normally mask_<intersect> detector-valid flags.

• vsize (int) – Optional vertical base ROI size in pixels. Defaults to the GUI value and, by default, may be adjusted by advanced ROI options such as detector inclination and projected sample size.

• hsize (int) – Optional horizontal base ROI size in pixels. Defaults to the GUI value and, by default, may be adjusted by advanced ROI options such as detector inclination and projected sample size.

• size_exact (numpy.ndarray) – Optional per-point ROI sizes in pixels with columns (hsize, vsize). If provided, advanced ROI size calculation is skipped and these exact per-point sizes are used.

• mask (bool) – Whether to apply mask_<intersect> before creating slices. Defaults to True.

• autovsize (bool) – Whether to derive vertical ROI size from the median vertical spacing between neighboring detector coordinates. Defaults to the GUI setting.

• autohsize (bool) – Whether to derive horizontal ROI size from the median horizontal spacing between neighboring detector coordinates. Defaults to the GUI setting.

• intersect (int) – Detector-intersection index to use, usually 1 or 2. Defaults to the GUI-selected intersection.

Returns:

Dictionary containing center as a list of (x_slice, y_slice) ROI coordinates, effective vsize and hsize in pixels, and size_exact when corrected per-point sizes were used.

Return type:

dict

Note

CLI-capable. Defaults are read from GUI ROI controls.

intbkgkeys_rocking(refldict, **kwargs)

Build center and background ROI slice coordinates.

This extends intkeys_rocking() by adding left, right, top, and bottom background ROIs around each center ROI. Slice tuple order stays in detector (x, y)/(horizontal, vertical) coordinates. NumPy images are indexed as image[y_slice, x_slice], so integration code applies these slices as key[::-1].

Parameters:

• refldict (dict) – Reflection dictionary produced by a rocking coordinate helper. For CTR-style rocking scans, it represents points sampled along the reciprocal-space line \(\vec{H}_0 + s\vec{H}_1\). The selected intersection must provide xy_<intersect> detector coordinates in pixels, and normally mask_<intersect> detector-valid flags.

• left (int) – Optional left-background width in detector pixels. Defaults to the GUI value.

• right (int) – Optional right-background width in detector pixels. Defaults to the GUI value.

• top (int) – Optional top-background height in detector pixels. Defaults to the GUI value.

• bottom (int) – Optional bottom-background height in detector pixels. Defaults to the GUI value.

• kwargs – Center-ROI options forwarded to intkeys_rocking(), including vsize, hsize, size_exact, mask, autovsize, autohsize, and intersect.

Returns:

Dictionary containing center, left, right, top, and bottom lists of (x_slice, y_slice) ROI coordinates, effective center-ROI vsize and hsize in pixels, and size_exact when corrected per-point sizes were used.

Return type:

dict

Note

CLI-capable. Defaults are read from GUI ROI controls.

rocking_extraction()

Start CTR-style rocking extraction along a reciprocal-space line.

\(\vec{H}_0\) and \(\vec{H}_1\) are reciprocal-space vectors in r.l.u. read from the rocking-scan controls. They define the reciprocal-space line \(\vec{H}_0 + s\vec{H}_1\) whose detector intersections are integrated. This function uses configuration from the UI elements, including the line vectors, intersection selection, ROI sizes, background sizes, masks, and correction options.

Returns:

Status dictionary describing success, cancellation, or error.

Return type:

dict

Note

CLI-capable when scan, database, and ROI state are preconfigured.

rocking_Bragg_extraction()

Integrate rocking-scan ROIs centered on Bragg peak coordinates.

Bragg peak detector coordinates are calculated from the current crystal, UB, detector, strain, and th-scan state. The valid Bragg coordinates are converted to center and background ROIs, then integrated across the rocking scan.

Returns:

Status dictionary describing success, cancellation, or error.

Return type:

dict

Note

CLI-capable when scan, database, and ROI state are preconfigured.

rocking_static_extraction(xy, hsize, vsize)

Integrate fixed detector-pixel ROIs through a rocking scan.

This path is for ROIs defined directly in detector pixel coordinates rather than from reciprocal-space line or Bragg-coordinate searches. Each input coordinate is treated as a fixed ROI center for every image in the scan. The provided ROI sizes are passed as exact per-ROI sizes, so automatic ROI sizing and advanced ROI size corrections are disabled.

Parameters:

• xy (numpy.ndarray) – ROI center coordinates in detector pixels. Shape (N, 2) for multiple ROIs, with columns (x, y).

• hsize (numpy.ndarray) – Horizontal ROI sizes in pixels, one value per ROI.

• vsize (numpy.ndarray) – Vertical ROI sizes in pixels, one value per ROI.

Returns:

Status dictionary from the rocking integration.

Return type:

dict

Note

CLI-capable when scan and database state are preconfigured.

rocking_integrate(xylist, rois, hkl_del_gam, refldict, name)

Integrate rocking-scan images over prepared ROIs.

For CTR-style rocking scans, refldict may contain \(\vec{H}_0\) and \(\vec{H}_1\) reciprocal-space vectors in r.l.u.; together they define the line \(\vec{H}_0 + s\vec{H}_1\) that is recorded in the output trajectory.

Parameters:

• xylist (numpy.ndarray) – ROI center coordinates in detector pixels.

• rois (dict) – Center and background ROI slice definitions.

• hkl_del_gam (numpy.ndarray) – Per-point hkl, detector-angle, and pixel metadata.

• refldict (dict) – Reflection metadata used to describe the saved trajectory.

• name (str) – Dataset name stem for saved integrated data.

Returns:

Status dictionary describing success, cancellation, or error.

Return type:

dict

Note

CLI-capable. Progress reporting is routed through logger_utils.

updatePlotItems(recalculate=True)

Refresh displayed ROI and reflection overlays.

Parameters:

recalculate (bool) – Recalculate CTR coordinates before updating reflection markers.

Note

CLI-capable, but it mutates Qt plot widgets.

onShowBragg(visible)

GUI/CLI hint: toggle Bragg reflection overlays on the plot.

onShowROI(visible)

GUI/CLI hint: toggle ROI display and refresh ROI graphics.

onShowCTRreflections(visible)

GUI/CLI hint: toggle CTR reflection overlays on the plot.

calcBraggRefl()

Calculate and display available Bragg reflections for the scan.

Note

CLI-capable for th scans, but it updates GUI reflection state.

saveBraggRefl()

Save calculated Bragg reflection coordinates selected in the GUI.

Note

GUI-only. This path opens confirmation and file-save dialogs.

calculateAvailableCTR()

Calculate CTR coordinates available to the current th scan.

Returns:

Array columns containing H, K, and detector-side information.

Return type:

numpy.ndarray

Note

CLI-safe when a compatible scan and UB state are loaded.

getReflections()

Return selected reference reflections for UB calculation.

The reference reflections are taken from the reflection selector. For each selected reflection, the detector pixel coordinate is converted to surface detector angles delta and gamma in rad, and the image number is converted to omega in rad. The returned angle rows use the Vlieg six-circle order [alpha, delta, gamma, omega, chi, phi]. In this GUI workflow, alpha is the current fixed incidence angle stored as self.ubcalc.mu.

Returns:

Tuple (hkls, angles). hkls has columns [h, k, l] in r.l.u. angles has columns [alpha, delta, gamma, omega, chi, phi] in rad.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

Note

CLI-safe when reference-selection state is already populated.

searchPixelCoordHKL(hkl)

Find detector coordinates and image numbers for a reflection.

This calculates the two possible diffractometer solutions for hkl with QUBCalculator.calcReflection(), which uses HKLVlieg.VliegAngles.anglesZmode(). The angle calculation follows the six-circle geometry described by Lohmeier & Vlieg, J. Appl. Cryst. 26, 706-716 (1993), https://doi.org/10.1107/S0021889893004868.

Scan-axis mapping:

• mu scans: the image number is selected from the solution alpha angle.

• th scans: the image number is selected from -omega because the scan axis stores theta with the opposite sign convention used internally for omega.

Parameters:

hkl (numpy.ndarray) – Reciprocal-space coordinate in r.l.u. Shape (3,).

Returns:

Reflection dictionary from calcReflection with added imageno_1/imageno_2 entries when the candidate angle falls within the active scan range, and selectable_1/selectable_2 flags indicating whether xy_1/xy_2 lie on the detector. The angles_1 and angles_2 rows use [alpha, delta, gamma, omega, chi, phi] in rad; xy_1 and xy_2 are detector pixel coordinates as (x, y).

Return type:

dict

Note

CLI-capable for active mu and th scans. Unsupported scan axes are reported through logging and return None.

onSearchHKLforStaticROI(hkl)

GUI/CLI hint: search an hkl and prompt for a static ROI location.

newXyHKLConverter()

Create a pixel-to-hkl converter bound to the active image state.

Returns:

Callable accepting x and y detector pixel coordinates.

Return type:

callable

Note

CLI-safe. The returned callable reads current scan and UB state.

getMuOm(imageno=None)

Return mu and omega for an image or the whole active scan.

Parameters:

imageno – Optional image index. If omitted, arrays for the full scan are returned where available.

Returns:

mu and omega angles in rad.

Return type:

tuple

Note

CLI-safe when a scan is loaded.

omegaToImageNo(omega)

Map an omega angle to the nearest image index.

Parameters:

omega (float) – Omega angle in rad.

Returns:

Nearest image index.

Return type:

int

Note

CLI-safe when a scan is loaded.

imageNoToOmega(imageno)

Return omega for an image index.

Parameters:

imageno (int) – Image index in the active scan.

Returns:

Omega angle in rad, 0.0 when no scan is loaded or None if the image number is higher than the length of the scan.

Note

CLI-safe.

imageNoToAxis(imageno)

Return the scan-axis value for an image index.

Parameters:

imageno (int) – Image index in the active scan.

Returns:

Scan-axis value in the scan’s stored units, usually deg.

Note

CLI-safe.

axisToImageNo(axisval)

Map a scan-axis value to the nearest image index.

Parameters:

axisval (float) – Scan-axis value in the scan’s stored units, usually deg.

Returns:

Nearest image index.

Return type:

int

Note

CLI-safe when a scan is loaded.

loadAll()

Load all scan images and compute summed and maximum images.

Returns:

None. Results are stored on self.allimgsum and self.allimgmax.

Note

CLI-capable. Progress reporting is routed through logger_utils.

plotImage(key=0)

Plot one raw image from the active scan.

Parameters:

key (int) – Image index in the active scan.

Note

CLI-capable, but it mutates Qt plot and reflection widgets.

updateReflections()

Update CTR reflection markers for the current image.

Note

CLI-capable, but it mutates Qt plot widgets.

updateROI(**kwargs)

Update visible ROI graphics for the current scan mode.

Note

CLI-capable, but it mutates Qt ROI widgets and reads GUI controls.

getStaticROIparams(xy, **kwargs)

Calculate hkl, detector angles, and pixel metadata for fixed ROIs.

Parameters:

xy – ROI center coordinates in detector pixels.

Returns:

Array containing hkl in r.l.u., detector angles in rad, trajectory coordinate, pixel coordinates, and detector mask flag.

Return type:

numpy.ndarray

Note

CLI-safe when scan and UB state are loaded.

getROIloc(imageno=None, H_0=None, H_1=None, **kwargs)

Calculate detector ROI locations for a reciprocal-space line.

When \(\vec{H}_0\) and \(\vec{H}_1\) are provided, they define the line \(\vec{H}_0 + s\vec{H}_1\) in reciprocal space. The returned arrays describe the two possible detector intersections of that line with the Ewald sphere.

Parameters:

• imageno (int) – Optional image index. If omitted, locations are calculated over the scan where applicable.

• H_0 (numpy.ndarray) – Starting reciprocal-space vector in r.l.u. Shape (3,) or (N, 3).

• H_1 (numpy.ndarray) – Reciprocal-space direction vector in r.l.u. Shape (3,) or (N, 3).

Returns:

Two arrays for the two possible detector intersections.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

Note

CLI-capable. Missing coordinates are read from GUI controls.

plotROI(loc, roi)

Set a visible ROI object around a detector-pixel location.

Parameters:

• loc – ROI center in detector pixels.

• roi – ROI widget to update.

Note

CLI-capable, but it mutates Qt ROI widgets.

integrateROI()

Integrate the active ROI workflow and save data to the database.

The active tab in self.scanSelector.scanstab selects the integration workflow:

• hklscan (tab id 0): integrate stationary-scan ROIs whose detector coordinates are calculated from the reciprocal-space line \(\vec{H}_0 + s\vec{H}_1\). \(\vec{H}_0\) and \(\vec{H}_1\) are numpy vector values in r.l.u. read from the ROI controls, and the two Ewald-sphere intersections are integrated as separate S1/S2 trajectories.

• fixed (tab id 1): integrate a stationary detector-pixel ROI from the xy_static controls. The same pixel coordinates are used through the scan, while the corresponding reciprocal-space coordinates and diffractometer angles are recorded for each image.

• rocking hklscan (tab id 2): delegate to rocking_extraction(), which integrates multiple rocking-scan ROIs whose coordinates are sampled along \(\vec{H}_0 + s\vec{H}_1\).

• rocking Bragg (tab id 3): delegate to rocking_Bragg_extraction(), which calculates Bragg peak coordinates from the current crystal, detector, UB, strain, and scan state before integrating valid rocking-scan ROIs.

All modes use the current UI/database state for scan selection, ROI sizes, masks, background settings, and correction factors. The resulting intensities and metadata are written to the active Nexus database file.

Returns:

Status dictionary describing success, cancellation, or error.

Return type:

dict

Note

CLI-capable when scan, database, and ROI state are preconfigured.

intkey(coords)

Create a center ROI key from detector pixel coordinates.

The returned key represents the clipped horizontal and vertical bounds of the center ROI around coords.

ROI sizes are read from the current hsize and vsize controls. In non-fixed scan modes, advanced ROI options may replace those nominal sizes with detector-inclination or projected-sample-size corrected bounds before clipping to the detector.

Parameters:

coords (numpy.ndarray) – ROI center coordinates (x, y) in detector pixels.

Returns:

ROI key (x_bounds, y_bounds) clipped to the detector extent.

Return type:

tuple[slice, slice]

Note

CLI-capable. ROI dimensions are read from GUI controls.

bkgkeys(coords)

Create background ROI keys around a center ROI.

Background keys are derived from the center ROI key returned by intkey(). The left and right background ROIs extend horizontally beside the center ROI and keep the same vertical bounds. The top and bottom background ROIs extend vertically above and below the center ROI and keep the same horizontal bounds.

Background widths and heights are read from the current left, right, top, and bottom controls. All bounds are clipped to the detector extent.

Parameters:

coords (numpy.ndarray) – Center ROI coordinates (x, y) in detector pixels.

Returns:

Left, right, top, and bottom background ROI keys.

Return type:

tuple[tuple[slice, slice], tuple[slice, slice], tuple[slice, slice], tuple[slice, slice]]

Note

CLI-capable. Background sizes are read from GUI controls.

closeEvent(event)

GUI/CLI hint: close the database before the main window closes.

class orgui.app.orGUI.Plot2DHKL(xyHKLConverter, parent=None, backend=None)

Bases: PlotWindow

keyPressEvent(event)

GUI-only: emit delete-key signal for plot interactions.

setXyHKLconverter(xyHKLConverter)

Set the pixel-to-hkl converter used by the plot readout.

Note

CLI-capable, but normally used by GUI plot setup.

getProfileToolbar()

Profile tools attached to this plot

See silx.gui.plot.Profile.ProfileToolBar

getProfileWindow()

Return the profile plot window.

Note

CLI-capable, but normally used by GUI profile tools.

getProfilePlot()

Return plot window used to display profile curve.

Returns:

Plot1D

class orgui.app.orGUI.QImportScanCreator(defaultMuTh, parent=None)

Bases: QDialog

onScanAxisChanged(index)

GUI-only: update fixed-angle fields for the selected scan axis.

class orgui.app.orGUI.QPlotDeleteWindow(curveList, hidden, parent=None)

Bases: QDialog

deleteClicked()

GUI-only: accept the dialog with a delete-curves action.

hideClicked()

GUI-only: accept the dialog with a hide-curves action.

checkOrUncheckAll()

GUI-only: mirror the select-all checkbox to all curve checkboxes.

class orgui.app.orGUI.QScanCreator(defaultMuTh, parent=None)

Bases: QDialog

onScanAxisChanged(index)

GUI-only: update fixed-angle fields for the selected scan axis.

class orgui.app.orGUI.QDiffractometerImageDialog(parent=None)

Bases: QDialog

class orgui.app.orGUI.AboutDialog(version, msg='', parent=None)

Bases: QDialog

class orgui.app.orGUI.UncaughtHook(*args, **kwargs)

Bases: QObject

set_orgui(orgui)

Attach the main window used for fatal-error recovery.

Note

GUI-only. The recovery path can show modal dialogs.

exception_hook(exc_type, exc_value, exc_traceback)

Handle uncaught exceptions through the GUI fatal-error path.

Note

GUI-only. This path may show modal dialogs and terminate the process.

orgui.app.orGUI.main(configfile)

Start a standalone GUI application for a config file.

Parameters:

configfile – Path to the orGUI configuration file.

Note

GUI-only. CLI startup is handled by orgui.main.

Backend API

class orgui.backend.scans.Scan(hdffilepath_orNode=None, scanno=None)

Bases: ABC

Base class for every backend.

All methods in this class must be populated for a working backend.

property auxillary_counters

Optional: provide a list of counters or motor names, that should be copied into the orGUI data base for further processing.

e.g. return [‘exposure_time’, ‘elapsed_time’,’time’, ‘srcur’, ‘mondio’, ‘epoch’]

after each integration, orGUI will search for these counter names in the Scan object and copy the entries into the database.

abstractmethod get_raw_img(i)

This should return a populated image class such as h5_Image (see below)

Only the image data is required as numpy array, accessible as h5_image.img

class orgui.backend.scans.SimulationScan(detshape, axismin, axismax, points, axis='th', fixed=0.0)

Bases: Scan

get_raw_img(i)

This should return a populated image class such as h5_Image (see below)

Only the image data is required as numpy array, accessible as h5_image.img