From 777d88765be3770b702cdd86fbbb649b8d5fdf32 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 9 Sep 2026 17:10:11 -0400
Subject: [PATCH 01/33] refactor: collect correction factors into one
 corrections package

---
 orgui/app/AGENTS.md                           |   23 +
 orgui/app/integration_corrections.py          |  149 +--
 orgui/app/orGUI.py                            |   37 +-
 orgui/app/peak1Dintegr.py                     |   22 +-
 .../app/test/test_integration_corrections.py  |    7 +-
 .../test_integration_corrections_dialog.py    |    7 +-
 orgui/datautils/xrayutils/AGENTS.md           |   10 +
 orgui/datautils/xrayutils/beamprofile.py      | 1029 +---------------
 .../xrayutils/corrections/__init__.py         |   73 ++
 .../xrayutils/corrections/beamprofile.py      | 1049 +++++++++++++++++
 .../xrayutils/corrections/detector.py         |   89 ++
 .../xrayutils/corrections/geometry.py         |  219 ++++
 .../xrayutils/corrections/normalization.py    |  103 ++
 orgui/datautils/xrayutils/corrections/roi.py  |   93 ++
 .../xrayutils/geometrycorrections.py          |  201 +---
 ...ile.py => test_corrections_beamprofile.py} |    8 +-
 ...ctions.py => test_corrections_geometry.py} |    4 +-
 .../test/test_corrections_package.py          |  143 +++
 orgui/reconstruction_job.py                   |   34 +-
 19 files changed, 1959 insertions(+), 1341 deletions(-)
 create mode 100644 orgui/datautils/xrayutils/corrections/__init__.py
 create mode 100644 orgui/datautils/xrayutils/corrections/beamprofile.py
 create mode 100644 orgui/datautils/xrayutils/corrections/detector.py
 create mode 100644 orgui/datautils/xrayutils/corrections/geometry.py
 create mode 100644 orgui/datautils/xrayutils/corrections/normalization.py
 create mode 100644 orgui/datautils/xrayutils/corrections/roi.py
 rename orgui/datautils/xrayutils/test/{test_beamprofile.py => test_corrections_beamprofile.py} (98%)
 rename orgui/datautils/xrayutils/test/{test_geometrycorrections.py => test_corrections_geometry.py} (96%)
 create mode 100644 orgui/datautils/xrayutils/test/test_corrections_package.py

diff --git a/orgui/app/AGENTS.md b/orgui/app/AGENTS.md
index 5ffe761..2094e65 100644
--- a/orgui/app/AGENTS.md
+++ b/orgui/app/AGENTS.md
@@ -12,11 +12,34 @@ This directory contains GUI components and user workflows:
 - `ReconstructionDialog.py`: GUI front-end for the out-of-core reciprocal-space
   reconstruction pipeline (`orgui/reconstruction_job.py`,
   `reconstruction_cli.py`, `reconstruction_cluster.py`).
+- `integration_corrections.py`: the adapter between the integration workflow
+  and `orgui/datautils/xrayutils/corrections/`. It reads which corrections
+  were switched on and what a loaded scan calls its counters, and assembles
+  the factor bundle stored beside the intensity.
 - Dialogs and tests under this directory cover user-facing behavior and GUI
   regressions.
 
 Use the repository root instructions together with this file.
 
+## Corrections Belong In datautils
+
+`datautils` holds self-consistent physics modules. Never let UI or UI state
+code leak into it: no widget, no configuration object, and no scan object may
+appear in `orgui/datautils/`. A correction factor is defined once, in
+`orgui/datautils/xrayutils/corrections/`, as a function of numbers.
+
+What belongs on this side of the boundary instead:
+
+- reading checkbox and dialog state, and turning it into arguments;
+- resolving a beamline scan's counter names into values (see also
+  `orgui/backend/scans.py`, which owns scan-object conventions);
+- assembling the named factors into the bundle that is saved.
+
+When a new correction is needed, add the physics to `corrections/` and call it
+from here. Do not compute a factor inline in `orGUI.py` or `peak1Dintegr.py`:
+the rocking integration, the stationary integration and the reconstruction
+must share one definition or they silently drift onto different scales.
+
 ## GUI And Shared-Code Boundary
 
 CLI/headless mode still creates a Qt application and an `orGUI` main-window
diff --git a/orgui/app/integration_corrections.py b/orgui/app/integration_corrections.py
index ccf90bf..dcd51b2 100644
--- a/orgui/app/integration_corrections.py
+++ b/orgui/app/integration_corrections.py
@@ -21,7 +21,15 @@
 # THE SOFTWARE.
 #
 # ###########################################################################*/
-r"""Per-image correction factors of a stationary-scan integration.
+r"""Adapter between the integration workflow and the correction physics.
+
+Every correction factor itself lives in
+:mod:`orgui.datautils.xrayutils.corrections`, which takes numbers and returns
+numbers and knows nothing about scans, configurations or widgets. What is
+left here is the translation in the other direction: turning *which
+corrections were switched on* and *what a loaded scan calls its counters*
+into arguments for those functions, and assembling the result into the bundle
+that is stored beside the integrated intensity.
 
 The normalization and numerical active-area factor are intensity divisors:
 
@@ -33,16 +41,14 @@
 
 ``C_flux_on_sample`` is retained as a diagnostic component of
 ``C_illum_area``. It must not be divided out separately: the numerical active
-area already contains the same beam/sample overlap integral. Stationary
-integration has no rod-interception factor; rocking scans retain theirs in
-:mod:`orgui.app.peak1Dintegr`.
+area already contains the same beam/sample overlap integral. Which angular
+factors a stationary measurement applies -- and that it has no
+rod-interception factor, unlike a rocking scan -- follows the z-axis table of
+:mod:`~orgui.datautils.xrayutils.corrections.geometry`.
 
-The geometrical factors come from
-:mod:`orgui.datautils.xrayutils.geometrycorrections`, the footprint factors
-from :mod:`orgui.datautils.xrayutils.beamprofile`, and the exposure and
-monitor normalization mirrors the reciprocal-space reconstruction
-(:mod:`orgui.reconstruction_job`), so a stationary integration and a
-reconstruction of the same scan are normalized identically.
+The exposure and monitor normalization mirrors the reciprocal-space
+reconstruction (:mod:`orgui.reconstruction_job`), so a stationary integration
+and a reconstruction of the same scan are normalized identically.
 
 This module holds no Qt state and reads only public scan attributes, so it is
 safe in CLI and batch use.
@@ -50,7 +56,14 @@
 
 import numpy as np
 
-from ..datautils.xrayutils import geometrycorrections
+from ..datautils.xrayutils.corrections import geometry
+from ..datautils.xrayutils.corrections.normalization import (
+    normalization_divisor as _divisor_from_counters,
+)
+from ..datautils.xrayutils.corrections.roi import (  # noqa: F401
+    CorrectionFactors,
+    roi_mean_correction,
+)
 
 __all__ = [
     "CorrectionFactors",
@@ -63,63 +76,6 @@
 ]
 
 
-class CorrectionFactors(dict):
-    """Per-image correction divisors, plus the names of what was applied.
-
-    A plain dict of ``name -> array`` with two conveniences: :attr:`applied`
-    lists the corrections that actually contributed, and :meth:`divisor`
-    multiplies a chosen subset together.
-    """
-
-    def __init__(self, factors, applied):
-        super().__init__(factors)
-        #: Names of the corrections that contributed, in application order.
-        self.applied = tuple(applied)
-
-    def divisor(self, *names):
-        """Product of the named factors, or 1.0 when none are present.
-
-        :param names: Factor names to multiply. Missing names are skipped,
-            so a caller can ask for a correction that was not enabled.
-        :rtype: numpy.ndarray or float
-        """
-        product = 1.0
-        for name in names:
-            if name in self:
-                product = product * self[name]
-        return product
-
-
-def roi_mean_correction(correction_sum, pixel_count):
-    """Mean per-pixel correction over one ROI.
-
-    The ROI summing accumulates the correction array over the same pixels it
-    sums the counts over, giving ``correction_sum`` and the number of valid
-    pixels ``pixel_count``. An ROI-summed intensity is corrected by the
-    *mean* of the correction across those pixels.
-
-    The nominal ROI area must not enter here: the integrated intensity is
-    already rescaled from the valid pixels to the nominal ROI area when the
-    background is subtracted. Multiplying by the area a second time scaled
-    every corrected intensity by the size of its ROI, and because the
-    projected ROI size varies over the detector, two measurements of one rod
-    taken on different parts of it were scaled apart.
-
-    :param correction_sum: Summed correction array over the ROI.
-    :param pixel_count: Number of valid pixels contributing to that sum.
-    :returns: The mean correction, and 0 where no pixel was valid.
-    :rtype: numpy.ndarray
-    """
-    correction_sum = np.asarray(correction_sum, dtype=np.float64)
-    pixel_count = np.asarray(pixel_count, dtype=np.float64)
-    return np.divide(
-        correction_sum,
-        pixel_count,
-        out=np.zeros_like(correction_sum),
-        where=pixel_count > 0,
-    )
-
-
 def monitor_counter_candidates(scan):
     """Counter names of ``scan`` usable as a monitor normalization.
 
@@ -152,8 +108,11 @@ def monitor_counter_candidates(scan):
 def normalization_divisor(scan, normalize_exposure, monitor_corrections, size):
     """Exposure and monitor divisor for every image of a scan.
 
-    Mirrors the reciprocal-space reconstruction, which divides each frame by
-    its exposure time and by every configured monitor counter.
+    Pulls the counters off the scan object and hands them to
+    :func:`~orgui.datautils.xrayutils.corrections.normalization.normalization_divisor`,
+    which owns the arithmetic and the validation. Mirrors the reciprocal-space
+    reconstruction, which divides each frame by its exposure time and by every
+    configured monitor counter.
 
     :param scan: Scan object providing ``exposure_time`` and the monitor
         counters by attribute.
@@ -167,44 +126,22 @@ def normalization_divisor(scan, normalize_exposure, monitor_corrections, size):
     :raises ValueError: If a counter is missing, or has a non-positive or
         non-finite value that would make the normalization undefined.
     """
-    divisor = np.ones(int(size), dtype=np.float64)
-    applied = []
-
+    exposure = None
     if normalize_exposure:
+        # A scan backend that reports no exposure time is not an error; the
+        # reconstruction records the normalization as unavailable rather than
+        # failing the job, and this follows it.
         exposure = getattr(scan, "exposure_time", None)
-        if exposure is None:
-            # Matches the reconstruction, which records the normalization as
-            # unavailable rather than failing the job.
-            pass
-        else:
-            values = _broadcast(exposure, size, "exposure_time")
-            if np.any(values <= 0) or not np.all(np.isfinite(values)):
-                raise ValueError("Exposure time must be finite and positive")
-            divisor *= values
-            applied.append("exposure")
 
+    monitors = {}
     for name in monitor_corrections:
         if not hasattr(scan, name):
             raise ValueError(f"Active scan has no monitor counter named {name!r}")
-        values = _broadcast(getattr(scan, name), size, name)
-        if np.any(values == 0) or not np.all(np.isfinite(values)):
-            raise ValueError(f"Monitor {name} must be finite and nonzero")
-        divisor *= values
-        applied.append(f"monitor:{name}")
-
-    return divisor, applied
+        monitors[name] = getattr(scan, name)
 
-
-def _broadcast(value, size, name):
-    """Broadcast a scalar or per-image counter to ``size`` values."""
-    array = np.atleast_1d(np.asarray(value, dtype=np.float64)).ravel()
-    if array.size == 1:
-        return np.full(int(size), array[0], dtype=np.float64)
-    if array.size != int(size):
-        raise ValueError(
-            f"Counter {name!r} has {array.size:d} values for {int(size):d} images"
-        )
-    return array
+    return _divisor_from_counters(
+        size, exposure_time=exposure, monitors=monitors
+    )
 
 
 def stationary_correction_factors(
@@ -224,13 +161,13 @@ def stationary_correction_factors(
     :param delta: In-plane detector angle per image, in radian.
     :param gamma: Out-of-plane detector angle per image, in radian.
     :param bool use_lorentz: Add ``C_Lorentz`` -- the *stationary-mode*
-        factor :math:`1/\sin\gamma`, not the rocking-scan one. Stationary
-        integration has no rod-interception factor.
+        factor :math:`1/\sin\gamma`, not the rocking-scan one.
+        Stationary integration has no rod-interception factor.
     :param bool use_footprint: Add the ``C_illum_area`` divisor and its
         diagnostic numerator ``C_flux_on_sample``.
     :param beam_profile: A
-        :class:`~orgui.datautils.xrayutils.beamprofile.BeamProfile`, required
-        when ``use_footprint`` is set.
+        :class:`~orgui.datautils.xrayutils.corrections.beamprofile.BeamProfile`,
+        required when ``use_footprint`` is set.
     :param float sample_size: Sample size along the beam in meters, required
         when ``use_footprint`` is set.
     :param normalization: Optional per-image exposure and monitor divisor
@@ -268,7 +205,7 @@ def stationary_correction_factors(
 
     if use_lorentz:
         factors["C_Lorentz"] = np.broadcast_to(
-            geometrycorrections.lorentz_stationary(gamma), alpha.shape
+            geometry.lorentz_factor(geometry.STATIONARY, gamma=gamma), alpha.shape
         ).copy()
         applied.append("lorentz")
 
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index 855fe62..6ec5bef 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -63,6 +63,7 @@
 from . import qutils, ROIutils, autoBraggWorkflow
 from .QScanSelector import QScanSelector
 from . import integration_corrections
+from ..datautils.xrayutils.corrections import detector as detector_corrections
 from .QReflectionSelector import QReflectionSelector, QReflectionAnglesDialog
 from .QUBCalculator import QUBCalculator
 from .peak1Dintegr import RockingPeakIntegrator
@@ -1583,11 +1584,19 @@ def rocking_integrate(self, xylist, rois, hkl_del_gam, refldict, name):
             or self.scanSelector.usePolarizationBox.isChecked()
         )
 
-        C_arr = np.ones(dc.detector.shape, dtype=np.float64)
-        if self.scanSelector.useSolidAngleBox.isChecked():
-            C_arr /= dc.solidAngleArray()
-        if self.scanSelector.usePolarizationBox.isChecked():
-            C_arr /= dc.polarizationArray()
+        # One definition of the per-pixel factors, shared with the rocking
+        # integration and the reciprocal-space reconstruction. It returns None
+        # when neither correction is enabled, so that the reconstruction can
+        # skip its multiplication; here the array of ones is required, because
+        # the branch below that rebuilds it runs only under HAS_ACCEL and the
+        # NumPy-only path would otherwise be handed None.
+        C_arr = detector_corrections.pixel_factors(
+            dc,
+            solid_angle=self.scanSelector.useSolidAngleBox.isChecked(),
+            polarization=self.scanSelector.usePolarizationBox.isChecked(),
+        )
+        if C_arr is None:
+            C_arr = np.ones(dc.detector.shape, dtype=np.float64)
 
         def fill_counters(image, pixelavail, key, bkgkey):
             """CLI-safe: sum one center ROI and its background ROIs."""
@@ -5745,11 +5754,19 @@ def integrateROI(self):
             or self.scanSelector.usePolarizationBox.isChecked()
         )
 
-        C_arr = np.ones(dc.detector.shape, dtype=np.float64)
-        if self.scanSelector.useSolidAngleBox.isChecked():
-            C_arr /= dc.solidAngleArray()
-        if self.scanSelector.usePolarizationBox.isChecked():
-            C_arr /= dc.polarizationArray()
+        # One definition of the per-pixel factors, shared with the rocking
+        # integration and the reciprocal-space reconstruction. It returns None
+        # when neither correction is enabled, so that the reconstruction can
+        # skip its multiplication; here the array of ones is required, because
+        # the branch below that rebuilds it runs only under HAS_ACCEL and the
+        # NumPy-only path would otherwise be handed None.
+        C_arr = detector_corrections.pixel_factors(
+            dc,
+            solid_angle=self.scanSelector.useSolidAngleBox.isChecked(),
+            polarization=self.scanSelector.usePolarizationBox.isChecked(),
+        )
+        if C_arr is None:
+            C_arr = np.ones(dc.detector.shape, dtype=np.float64)
 
         hkl_del_gam_s1, hkl_del_gam_s2 = self.getROIloc()
 
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 86a2703..61530c8 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -57,7 +57,7 @@
 from .config_data import ConfigData
 from .. import resources
 from .. import logger_utils
-from ..datautils.xrayutils import beamprofile, geometrycorrections
+from ..datautils.xrayutils.corrections import beamprofile, geometry
 
 import numpy as np
 from scipy import interpolate as interp
@@ -1337,19 +1337,19 @@ def integrate(self):
             # The two take different Lorentz factors from the z-axis table,
             # and neither is the stationary-scan factor.
             if curves["axisname"] == "mu":
-                C_Lor = geometrycorrections.lorentz_factor(
-                    geometrycorrections.REFLECTIVITY_ROCKING, alpha=alpha
+                C_Lor = geometry.lorentz_factor(
+                    geometry.REFLECTIVITY_ROCKING, alpha=alpha
                 )
             elif curves["axisname"] == "th":
-                C_Lor = geometrycorrections.lorentz_factor(
-                    geometrycorrections.ROCKING,
+                C_Lor = geometry.lorentz_factor(
+                    geometry.ROCKING,
                     alpha=alpha,
                     delta=delta,
                     gamma=gamma,
                 )
             else:
                 raise NotImplementedError()
-            C_rod = geometrycorrections.rod_interception(gamma)
+            C_rod = geometry.rod_interception(gamma)
         else:
             C_Lor = 1.0
             C_rod = 1.0
@@ -2165,7 +2165,7 @@ def _width(label, default):
 
 #: Analytical beam shapes, in the order they appear in the dialog. The first
 #: is the default and reproduces the Gaussian correction orGUI has always
-#: applied; see :mod:`orgui.datautils.xrayutils.beamprofile`.
+#: applied; see :mod:`orgui.datautils.xrayutils.corrections.beamprofile`.
 BEAM_SHAPES = (
     _BeamShape(
         "Gaussian",
@@ -2214,7 +2214,7 @@ class IntegrationCorrectionsDialog(qt.QDialog):
 
     The incident beam is described either by an analytical shape from
     :data:`BEAM_SHAPES` or by a beam profile measured at the beamline. Both
-    are evaluated by :mod:`orgui.datautils.xrayutils.beamprofile`, which
+    are evaluated by :mod:`orgui.datautils.xrayutils.corrections.beamprofile`, which
     evaluates the illuminated surface integral over the projected sample
     footprint. The intercepted-flux fraction is available as a diagnostic
     numerator but is not applied as a second correction. Only a measured
@@ -2573,7 +2573,7 @@ def measuredProfile(self):
 
         :returns: The tabulated profile, referenced to the sample center
             chosen in the dialog.
-        :rtype: orgui.datautils.xrayutils.beamprofile.MeasuredBeamProfile
+        :rtype: orgui.datautils.xrayutils.corrections.beamprofile.MeasuredBeamProfile
         :raises ValueError: If no profile file has been loaded.
         """
         if self._profile_z is None:
@@ -2592,7 +2592,7 @@ def measuredProfile(self):
     def analyticalProfile(self):
         """Return the analytical beam profile described by the dialog.
 
-        :rtype: orgui.datautils.xrayutils.beamprofile.BeamProfile
+        :rtype: orgui.datautils.xrayutils.corrections.beamprofile.BeamProfile
         :raises ValueError: If the shape rejects the entered parameters.
         """
         shape = self.currentShape()
@@ -2610,7 +2610,7 @@ def beamProfile(self):
         """Return the incident-beam profile selected in the dialog.
 
         :returns: An analytical or measured beam profile, in meters.
-        :rtype: orgui.datautils.xrayutils.beamprofile.BeamProfile
+        :rtype: orgui.datautils.xrayutils.corrections.beamprofile.BeamProfile
         :raises ValueError: If the measured profile is selected but no
             profile file has been loaded, or if the analytical parameters
             do not describe a usable profile.
diff --git a/orgui/app/test/test_integration_corrections.py b/orgui/app/test/test_integration_corrections.py
index 752fda9..226bcdb 100644
--- a/orgui/app/test/test_integration_corrections.py
+++ b/orgui/app/test/test_integration_corrections.py
@@ -11,8 +11,11 @@
 import pytest
 
 from orgui.app import integration_corrections as ic
-from orgui.datautils.xrayutils import geometrycorrections as gc
-from orgui.datautils.xrayutils.beamprofile import gaussian_profile, top_hat_profile
+from orgui.datautils.xrayutils.corrections import geometry as gc
+from orgui.datautils.xrayutils.corrections.beamprofile import (
+    gaussian_profile,
+    top_hat_profile,
+)
 
 roi_sum = pytest.importorskip("orgui.app._roi_sum_accel")
 
diff --git a/orgui/app/test/test_integration_corrections_dialog.py b/orgui/app/test/test_integration_corrections_dialog.py
index c7145bc..c395aff 100644
--- a/orgui/app/test/test_integration_corrections_dialog.py
+++ b/orgui/app/test/test_integration_corrections_dialog.py
@@ -3,8 +3,9 @@
 :class:`orgui.app.peak1Dintegr.IntegrationCorrectionsDialog` owns the user
 side of the numerical active-area correction: it converts the
 millimeter and micrometer values shown to the user into the meters
-:mod:`orgui.datautils.xrayutils.beamprofile` works in, and decides whether an
-integration runs against an analytical beam shape or a measured profile.
+:mod:`orgui.datautils.xrayutils.corrections.beamprofile` works in, and
+decides whether an integration runs against an analytical beam shape or a
+measured profile.
 
 These tests pin that boundary. They construct the dialog directly, without
 showing it, so no user interaction is involved and no plot widget is built.
@@ -15,7 +16,7 @@
 from silx.gui import qt
 
 from orgui.app.peak1Dintegr import BEAM_SHAPES, IntegrationCorrectionsDialog
-from orgui.datautils.xrayutils.beamprofile import (
+from orgui.datautils.xrayutils.corrections.beamprofile import (
     DistributionBeamProfile,
     GaussianBeamProfile,
     MeasuredBeamProfile,
diff --git a/orgui/datautils/xrayutils/AGENTS.md b/orgui/datautils/xrayutils/AGENTS.md
index e57db94..317c00b 100644
--- a/orgui/datautils/xrayutils/AGENTS.md
+++ b/orgui/datautils/xrayutils/AGENTS.md
@@ -22,6 +22,16 @@ This directory contains the highest-risk scientific code:
   and `reconstruction_cluster.py` (outside this directory, no nested
   `AGENTS.md` of their own) build on it and follow the same conventions as
   this file.
+- `corrections/`: every factor between detector counts and a structure factor
+  -- `geometry.py` (z-axis Lorentz/rod-interception/area table),
+  `beamprofile.py`, `activearea.py`, `detector.py` (per-pixel solid angle and
+  polarization), `normalization.py` (counting time and monitor), `roi.py`,
+  and `measurement.py` (which factors each scan mode applies, and the
+  reduction to `|F_hkl|^2` and absolute reflectivity). The rocking
+  integration, the stationary integration and the reconstruction all correct
+  their data through this package, so a factor must be defined here once
+  rather than per caller. `geometrycorrections.py` and `beamprofile.py` at
+  this level are released aliases that re-export it; do not add code to them.
 - `cpp/`: native C++ kernels (`CTRcalc_cpp.cpp`,
   `reciprocal_reconstruction_cpp.cpp`) backing performance-critical CTR and
   reconstruction paths.
diff --git a/orgui/datautils/xrayutils/beamprofile.py b/orgui/datautils/xrayutils/beamprofile.py
index abb5937..604c787 100644
--- a/orgui/datautils/xrayutils/beamprofile.py
+++ b/orgui/datautils/xrayutils/beamprofile.py
@@ -21,55 +21,34 @@
 # THE SOFTWARE.
 #
 # ###########################################################################*/
-r"""Incident-beam profiles for numerical footprint corrections.
+"""Backwards-compatible alias of the beam profiles.
 
-Two related quantities are evaluated at incidence angle :math:`\alpha` on a
-sample of length :math:`L` along the beam:
+Re-exports :mod:`orgui.datautils.xrayutils.corrections.beamprofile`.
 
-``C_flux_on_sample``
-    the fraction of the total incident flux that actually strikes the sample.
-    This is the overlap integral used below and is stored as a diagnostic; it
-    is not an additional intensity divisor.
-
-``C_illum_area``
-    the numerical active surface area, referenced to a sample fully bathed in
-    a beam of the profile's peak intensity. This is the footprint divisor
-    applied to an integrated intensity.
-
-Both follow from the normalized vertical beam profile :math:`p(z)`, with
-:math:`\int p(z)\,\mathrm{d}z = 1`, where :math:`z` runs perpendicular to the
-beam in the scattering plane. With the projected sample size
-
-.. math:: h(\alpha) = L \sin\alpha
-
-and the sample centered at :math:`z_0` in the beam,
-
-.. math::
-
-    C_\mathrm{flux} = \int_{z_0 - h/2}^{z_0 + h/2} p(z)\,\mathrm{d}z
-    \qquad
-    C_\mathrm{area} = \frac{C_\mathrm{flux}}{p_\mathrm{max}\, h}
-
-:math:`C_\mathrm{area}` is the mean of :math:`p(z)/p_\mathrm{max}` over the
-projected sample footprint. It is the one-dimensional form of Vlieg's
-numerically illuminated area, so it already contains the overlap integral
-:math:`C_\mathrm{flux}`. Multiplying the two would count beam overspill twice.
-It tends to 1 when the sample is small compared with a centered beam and falls
-off as :math:`1/\sin\alpha` once the beam is fully on the sample.
-
-For a Gaussian :math:`p` both integrals have the closed form orGUI used before
-this module existed, reproduced exactly by :class:`GaussianBeamProfile`.
-:class:`MeasuredBeamProfile` evaluates the same two definitions by numerical
-integration of a tabulated profile, so an asymmetric or multiply-peaked beam
-measured at the beamline can be used instead of the Gaussian idealization.
-
-All lengths in this module are in **meters**, all angles in **radians**.
+The beam profiles moved into the
+:mod:`orgui.datautils.xrayutils.corrections` package, which collects every
+factor between detector counts and a structure factor. This module was
+released under its own name, so it stays importable and re-exports the same
+objects. New code should import from
+:mod:`orgui.datautils.xrayutils.corrections.beamprofile`.
 """
 
-from abc import ABC, abstractmethod
-
-import numpy as np
-from scipy import optimize, special, stats
+from .corrections.beamprofile import (  # noqa: F401
+    BeamProfile,
+    DistributionBeamProfile,
+    GaussianBeamProfile,
+    MeasuredBeamProfile,
+    gaussian_profile,
+    generalized_normal_profile,
+    profile_from_height_scan,
+    read_profile_file,
+    skew_normal_profile,
+    smoothed_top_hat_profile,
+    top_hat_profile,
+    trapezoid_profile,
+    triangular_profile,
+    trim_to_illuminated_edge,
+)
 
 __all__ = [
     "BeamProfile",
@@ -87,963 +66,3 @@
     "triangular_profile",
     "trim_to_illuminated_edge",
 ]
-
-#: Quantile at which a distribution's plotted and searched range is cut.
-_TAIL = 1e-6
-
-#: Half-width of that range in interquartile ranges, used as a second bound.
-#: A heavy-tailed distribution puts its ``_TAIL`` quantile absurdly far out
-#: -- a Cauchy profile of 0.3 mm FWHM reaches its at about 40 m -- which
-#: would leave the peak unresolved by any practical number of samples. The
-#: interquartile range stays finite for every distribution, and 4 of them
-#: cover a Gaussian to 5.4 sigma, so the quantile bound still wins for
-#: light-tailed and bounded profiles and nothing changes for them.
-_RANGE_IQR = 4.0
-
-#: Number of samples used to locate maxima and half-maximum crossings.
-_SCAN_POINTS = 4001
-
-if hasattr(np, "trapezoid"):  # ToDo remove for orGUI release >1.5
-    _trapz_impl = np.trapezoid  # numpy >= 2.0
-else:
-    _trapz_impl = np.trapz  # noqa: NPY201  # numpy < 2.0
-
-#: Conversion of a Gaussian FWHM to its standard deviation.
-_FWHM_TO_SIGMA = 1.0 / (2.0 * np.sqrt(2.0 * np.log(2.0)))
-
-
-class BeamProfile(ABC):
-    """Vertical intensity profile of the incident beam.
-
-    Subclasses provide the applied active-area factor and its intercepted-flux
-    diagnostic for arbitrarily shaped arrays of incidence angles.
-    """
-
-    @abstractmethod
-    def flux_on_sample(self, alpha, L):
-        """Fraction of the incident flux intercepted by the sample.
-
-        :param alpha: Incidence angle(s) in radian, any array shape.
-            Expected in ``(0, pi/2]``.
-        :param float L: Sample size along the beam, in meters.
-        :returns: ``C_flux_on_sample``, broadcast to the shape of ``alpha``.
-        :rtype: numpy.ndarray
-        """
-
-    @abstractmethod
-    def illuminated_area_fraction(self, alpha, L):
-        """Illuminated fraction of the projected sample footprint.
-
-        :param alpha: Incidence angle(s) in radian, any array shape.
-        :param float L: Sample size along the beam, in meters.
-        :returns: ``C_illum_area``, broadcast to the shape of ``alpha``.
-        :rtype: numpy.ndarray
-        """
-
-    def corrections(self, alpha, L):
-        """Return the intercepted flux and numerical active area.
-
-        :param alpha: Incidence angle(s) in radian, any array shape.
-        :param float L: Sample size along the beam, in meters.
-        :returns: ``(C_flux_on_sample, C_illum_area)``. Only
-            ``C_illum_area`` is an integrated-intensity divisor;
-            ``C_flux_on_sample`` is its diagnostic numerator.
-        :rtype: tuple
-        """
-        return self.flux_on_sample(alpha, L), self.illuminated_area_fraction(alpha, L)
-
-    @abstractmethod
-    def profile_curve(self, n=512):
-        """Sample the profile for display.
-
-        :param int n: Requested number of samples. A tabulated profile
-            returns its own points and ignores this.
-        :returns: ``(z, p)`` with ``z`` relative to the sample center in
-            meters and ``p`` the normalized profile in 1/meter.
-        :rtype: tuple of numpy.ndarray
-        """
-
-    @property
-    @abstractmethod
-    def centroid_position(self):
-        """Center of mass relative to the sample center, in meters.
-
-        ``0.0`` when the sample is centered on the centroid, and ``nan``
-        for a profile whose first moment does not converge.
-
-        :rtype: float
-        """
-
-
-def _half_maximum_width(z, p, pmax):
-    """Width between the outermost crossings of ``pmax / 2``.
-
-    Uses the outermost crossings so that a profile with several maxima
-    reports its full extent rather than the width of a single sub-peak.
-
-    :param z: Sample positions, increasing.
-    :param p: Profile values at ``z``.
-    :param float pmax: Peak value the half maximum is taken from.
-    :returns: The full width at half maximum, in the units of ``z``.
-    :rtype: float
-    """
-    half = pmax / 2.0
-    above = np.flatnonzero(p >= half)
-    if above.size == 0:
-        return float("nan")
-    lo, hi = int(above[0]), int(above[-1])
-    if lo == 0:
-        left = z[lo]
-    else:
-        left = np.interp(half, [p[lo - 1], p[lo]], [z[lo - 1], z[lo]])
-    if hi == z.size - 1:
-        right = z[hi]
-    else:
-        right = np.interp(half, [p[hi + 1], p[hi]], [z[hi + 1], z[hi]])
-    return float(right - left)
-
-
-class _CenteredProfile(BeamProfile):
-    """Shared centering and correction evaluation for profiles with a CDF.
-
-    Both corrections follow from the cumulative integral of the profile and
-    from its peak density, so a subclass only has to supply
-    ``_cumulative(x)`` and ``_density_at(x)`` -- both in coordinates relative
-    to the sample center -- together with ``_pmax`` and the ``_tiny``
-    threshold below which the ``alpha -> 0`` limit is used.
-    """
-
-    def _set_center(self, center, offset, centroid, peak_position, median):
-        """Resolve the requested centering into :attr:`sample_center`.
-
-        :param str center: ``"centroid"``, ``"peak"`` or ``"median"``.
-        :param float offset: Extra displacement of the sample center.
-        :param float centroid: Center of mass of the profile.
-        :param float peak_position: Position of the maximum density.
-        :param float median: Position at which half the flux has passed.
-        :raises ValueError: If ``center`` is unknown, or names a reference
-            point this profile does not have (a heavy-tailed distribution
-            has no finite centroid).
-        """
-        try:
-            reference = {
-                "centroid": centroid,
-                "peak": peak_position,
-                "median": median,
-            }[center]
-        except KeyError:
-            raise ValueError(
-                f"center must be 'centroid', 'peak' or 'median', got {center!r}"
-            ) from None
-        if not np.isfinite(reference):
-            raise ValueError(
-                f"the {center} of this beam profile is not finite, so the "
-                "sample cannot be centered on it. Heavy-tailed profiles have "
-                "no center of mass; center on 'median' or 'peak' instead."
-            )
-        self.centroid = float(centroid)
-        self.peak_position = float(peak_position)
-        self.median = float(median)
-        self.center = center
-        self.offset = float(offset)
-        #: Position of the sample center in the profile's own coordinate.
-        self.sample_center = float(reference) + self.offset
-
-    @property
-    def centroid_position(self):
-        """Center of mass relative to the sample center, in meters."""
-        return float(self.centroid - self.sample_center)
-
-    def _flux(self, h):
-        """``C_flux_on_sample`` for a projected sample size ``h``."""
-        return self._cumulative(h / 2.0) - self._cumulative(-h / 2.0)
-
-    def flux_on_sample(self, alpha, L):
-        """Fraction of the incident flux intercepted by the sample.
-
-        Integrates the profile over the projected sample size
-        ``h = L sin(alpha)``, centered on the sample center.
-        """
-        return self._flux(L * np.sin(np.asarray(alpha, dtype=float)))
-
-    def illuminated_area_fraction(self, alpha, L):
-        """Illuminated fraction of the projected sample footprint.
-
-        ``C_flux_on_sample / (p_max * h)``, continued to its limit
-        ``p(0) / p_max`` as ``h -> 0``.
-        """
-        h = L * np.sin(np.asarray(alpha, dtype=float))
-        flux = self._flux(h)
-        limit = self._density_at(0.0) / self._pmax
-        denom = self._pmax * h
-        return np.where(
-            np.abs(h) > self._tiny,
-            flux / np.where(denom == 0.0, 1.0, denom),
-            limit,
-        )
-
-
-class GaussianBeamProfile(BeamProfile):
-    """Analytical Gaussian beam profile.
-
-    Reproduces orGUI's original closed-form footprint correction exactly; it
-    is the reference against which :class:`MeasuredBeamProfile` is validated.
-
-    :param float fwhm: Full width at half maximum of the vertical beam
-        profile, in meters.
-    :raises ValueError: If ``fwhm`` is not positive.
-    """
-
-    def __init__(self, fwhm):
-        fwhm = float(fwhm)
-        if not fwhm > 0:
-            raise ValueError(f"beam FWHM must be positive, got {fwhm:g}")
-        self.fwhm = fwhm
-        self.sigma = fwhm * _FWHM_TO_SIGMA
-
-    def flux_on_sample(self, alpha, L):
-        """Fraction of the incident flux intercepted by the sample.
-
-        Evaluates ``erf(h / (2 sqrt(2) sigma))`` with ``h = L sin(alpha)``.
-        """
-        arg = ((L * np.sin(alpha)) / (np.sqrt(2) * self.sigma)) * 0.5
-        return (1 / 2) * (special.erf(arg) - special.erf(-arg))
-
-    def illuminated_area_fraction(self, alpha, L):
-        """Illuminated fraction of the projected sample footprint."""
-        return (np.sqrt(2 * np.pi) * self.sigma * self.flux_on_sample(alpha, L)) / (
-            L * np.sin(alpha)
-        )
-
-    def profile_curve(self, n=512):
-        """Sample the Gaussian over +- 4 sigma around the sample center."""
-        z = np.linspace(-4.0 * self.sigma, 4.0 * self.sigma, int(n))
-        return z, np.exp(-0.5 * (z / self.sigma) ** 2) / (
-            np.sqrt(2 * np.pi) * self.sigma
-        )
-
-    @property
-    def centroid_position(self):
-        """A Gaussian is symmetric, so its centroid is the sample center."""
-        return 0.0
-
-    def __repr__(self):
-        return f"GaussianBeamProfile(fwhm={self.fwhm:g} m)"
-
-
-class MeasuredBeamProfile(_CenteredProfile):
-    """Tabulated beam profile integrated numerically.
-
-    The profile is treated as piecewise linear between the supplied sample
-    points and as exactly zero outside their range, so its cumulative
-    integral -- and with it ``C_flux_on_sample`` -- is evaluated in closed
-    form on each interval instead of being re-sampled onto an auxiliary grid.
-
-    A measured profile carries no absolute position information, so it is
-    re-referenced to the point of the beam that the center of the sample is
-    aligned to; see ``center``. For a symmetric profile every choice
-    coincides, and the results then reduce to :class:`GaussianBeamProfile`.
-
-    :param z: Positions perpendicular to the beam in the scattering plane,
-        in meters. Must be strictly monotonic; the direction is preserved
-        (increasing ``z`` upward, as in a sample height scan).
-    :param intensity: Beam intensity at ``z``, in arbitrary units. It is
-        normalized internally, so any scale or monitor normalization is fine.
-    :param str center: Which point of the profile the center of the sample
-        sits on: ``"centroid"`` (center of mass, the default), ``"peak"``
-        (maximum intensity), or ``"median"`` (the half-cut position an
-        edge-scan alignment converges to).
-    :param float offset: Additional displacement of the sample center from
-        the ``center`` reference, in meters. Positive moves the sample
-        center toward larger ``z``.
-    :raises ValueError: If ``z`` is not strictly monotonic, if fewer than
-        two points are given, if any value is not finite, or if the profile
-        does not have a positive integral.
-    """
-
-    def __init__(self, z, intensity, center="centroid", offset=0.0):
-        z = np.asarray(z, dtype=float).ravel()
-        intensity = np.asarray(intensity, dtype=float).ravel()
-        if z.size != intensity.size:
-            raise ValueError(
-                "z and intensity must have the same length, got "
-                f"{z.size:d} and {intensity.size:d}"
-            )
-        if z.size < 2:
-            raise ValueError("a beam profile needs at least two points")
-        if not np.all(np.isfinite(z)) or not np.all(np.isfinite(intensity)):
-            raise ValueError("beam profile contains non-finite values")
-
-        dz = np.diff(z)
-        if np.all(dz < 0):
-            z, intensity = z[::-1], intensity[::-1]
-            dz = np.diff(z)
-        if not np.all(dz > 0):
-            raise ValueError("z must be strictly monotonic")
-
-        norm = _trapz_impl(intensity, z)
-        if not norm > 0:
-            raise ValueError(
-                f"beam profile must have a positive integral, got {norm:g}. A "
-                "height scan differentiated with the wrong sign gives a "
-                "negative one."
-            )
-
-        p = intensity / norm
-        # Exact cumulative integral of the piecewise-linear profile at the
-        # sample points; interior positions are handled in _cumulative().
-        cum = np.concatenate(([0.0], np.cumsum(0.5 * (p[:-1] + p[1:]) * dz)))
-        cum[-1] = 1.0
-
-        self._z_raw = z
-        self._p = p
-        self._cum = cum
-        self._pmax = float(p.max())
-        # Guard for the alpha -> 0 limit, scaled to the profile's support so
-        # that it stays meaningful whatever length scale the caller works on.
-        self._tiny = 1e-9 * float(z[-1] - z[0])
-
-        centroid = float(_trapz_impl(z * p, z))
-        self._set_center(
-            center,
-            offset,
-            centroid,
-            float(z[np.argmax(p)]),
-            float(np.interp(0.5, cum, z)),
-        )
-        self.rms_width = float(
-            np.sqrt(max(float(_trapz_impl((z - centroid) ** 2 * p, z)), 0.0))
-        )
-
-    def profile_curve(self, n=512):
-        """Return the tabulated points; ``n`` is ignored."""
-        return self.z, self._p
-
-    @property
-    def z(self):
-        """Profile positions relative to the sample center, in meters."""
-        return self._z_raw - self.sample_center
-
-    @property
-    def density(self):
-        """Normalized profile ``p(z)`` in 1/meter, matching :attr:`z`."""
-        return self._p
-
-    @property
-    def support(self):
-        """``(z_min, z_max)`` of the profile relative to the sample center."""
-        return (
-            float(self._z_raw[0] - self.sample_center),
-            float(self._z_raw[-1] - self.sample_center),
-        )
-
-    @property
-    def fwhm(self):
-        """Full width at half maximum of the profile, in meters.
-
-        Measured between the outermost crossings of half the peak value, so
-        a profile with several maxima reports its full extent rather than
-        the width of a single sub-peak.
-        """
-        return _half_maximum_width(self._z_raw, self._p, self._pmax)
-
-    def _density_at(self, x):
-        """Normalized profile at ``x``, relative to the sample center."""
-        return np.interp(
-            np.asarray(x, dtype=float) + self.sample_center, self._z_raw, self._p
-        )
-
-    def _cumulative(self, x):
-        """Integral of the normalized profile from ``-inf`` up to ``x``.
-
-        ``x`` is given relative to the sample center. Outside the tabulated
-        range the profile is taken to be zero, so the result saturates at 0
-        and 1.
-        """
-        z, p, cum = self._z_raw, self._p, self._cum
-        x = np.clip(np.asarray(x, dtype=float) + self.sample_center, z[0], z[-1])
-        i = np.clip(np.searchsorted(z, x, side="right") - 1, 0, z.size - 2)
-        d = z[i + 1] - z[i]
-        t = (x - z[i]) / d
-        # Exact integral of one linear segment over [z[i], x].
-        return cum[i] + d * t * (p[i] + 0.5 * t * (p[i + 1] - p[i]))
-
-    def __repr__(self):
-        return (
-            f"MeasuredBeamProfile({self._z_raw.size:d} points, "
-            f"fwhm={self.fwhm:g} m, center={self.center!r})"
-        )
-
-
-class DistributionBeamProfile(_CenteredProfile):
-    """Beam profile given by an analytical probability distribution.
-
-    Both corrections need only the cumulative distribution and the peak
-    density, so any continuous distribution with a ``cdf``, a ``pdf`` and a
-    ``ppf`` can describe the beam -- in particular any frozen
-    :mod:`scipy.stats` distribution. The named constructors in this module
-    (:func:`top_hat_profile`, :func:`trapezoid_profile`,
-    :func:`smoothed_top_hat_profile`, :func:`generalized_normal_profile`,
-    :func:`skew_normal_profile`) wrap the shapes that describe real beams,
-    in physical parameters rather than raw distribution arguments.
-
-    :class:`GaussianBeamProfile` is the same model evaluated in closed form;
-    passing ``scipy.stats.norm`` here reproduces it to machine precision.
-
-    ``scipy.stats`` exposes no mode, so the peak is located once at
-    construction by scanning the distribution's central range and refining
-    the best sample. A plateau, as in a top hat, resolves to its midpoint.
-
-    :param dist: A frozen continuous distribution, e.g.
-        ``scipy.stats.norm(scale=1e-5)``.
-    :param str center: Which point of the profile the center of the sample
-        sits on: ``"centroid"`` (mean, the default), ``"peak"`` (mode) or
-        ``"median"``. All three coincide for a symmetric distribution.
-    :param float offset: Additional displacement of the sample center from
-        the ``center`` reference, in meters.
-    :raises TypeError: If ``dist`` is not a frozen distribution.
-    :raises ValueError: If the distribution has no finite central range, or
-        no finite positive maximum density -- a beam profile with an
-        unbounded peak has no active-area reference and cannot be used.
-    """
-
-    def __init__(self, dist, center="centroid", offset=0.0):
-        for name in ("cdf", "pdf", "ppf"):
-            if not callable(getattr(dist, name, None)):
-                raise TypeError(
-                    "dist must be a frozen continuous distribution with cdf, "
-                    f"pdf and ppf methods, got {dist!r}. Freeze a scipy.stats "
-                    "distribution first, e.g. scipy.stats.norm(scale=1e-5)."
-                )
-        if isinstance(dist, stats.rv_continuous):
-            # An unfrozen distribution answers every call with its standard
-            # form, which here would silently describe a beam one meter wide.
-            raise TypeError(
-                f"dist must be frozen, got the distribution family {dist!r}. "
-                "Supply its parameters, e.g. scipy.stats.norm(scale=1e-5) "
-                "rather than scipy.stats.norm."
-            )
-        lo, hi = self._central_range(dist)
-
-        self._dist = dist
-        self._lo = lo
-        self._hi = hi
-        peak_position, pmax = self._locate_peak(dist, lo, hi)
-        if not np.isfinite(pmax) or pmax <= 0:
-            raise ValueError(
-                f"the distribution has no finite positive maximum density "
-                f"(got {pmax:g}); the illuminated-area correction has no "
-                "reference intensity for such a profile."
-            )
-        self._reject_unbounded_density(dist, pmax)
-        self._pmax = pmax
-        self._tiny = 1e-9 * (hi - lo)
-
-        self._set_center(
-            center, offset, self._finite_moment(dist.mean), peak_position, dist.ppf(0.5)
-        )
-        self.rms_width = self._finite_moment(dist.std)
-
-    @staticmethod
-    def _central_range(dist):
-        """Range over which the profile is scanned and displayed.
-
-        The narrower of the ``_TAIL`` quantile range and ``_RANGE_IQR``
-        interquartile ranges around the median. This bounds only where the
-        peak is looked for, the width is measured and the preview is drawn;
-        the corrections always integrate the full distribution, so a
-        heavy-tailed profile still reports the flux that misses the sample.
-
-        :returns: ``(lo, hi)``.
-        :rtype: tuple of float
-        :raises ValueError: If the distribution is not localized.
-        """
-        lo = float(dist.ppf(_TAIL))
-        hi = float(dist.ppf(1.0 - _TAIL))
-        median = float(dist.ppf(0.5))
-        iqr = float(dist.ppf(0.75)) - float(dist.ppf(0.25))
-        if np.isfinite(iqr) and iqr > 0:
-            lo = max(lo, median - _RANGE_IQR * iqr)
-            hi = min(hi, median + _RANGE_IQR * iqr)
-        if not (np.isfinite(lo) and np.isfinite(hi) and hi > lo):
-            raise ValueError(
-                f"the distribution has no finite central range, got {lo:g} to "
-                f"{hi:g}. A beam profile must be localized."
-            )
-        return lo, hi
-
-    @staticmethod
-    def _reject_unbounded_density(dist, pmax):
-        """Refuse a distribution whose density diverges at an end.
-
-        The peak is searched between finite quantiles, so a density that
-        runs to infinity -- as a gamma distribution with shape below one
-        does at zero -- still yields a large but finite maximum there, and
-        that value would depend on nothing but the chosen cut. Probing a
-        much deeper quantile catches it: for a bounded density the value
-        stops growing, for a divergent one it does not.
-
-        :raises ValueError: If the density is still growing at either end.
-        """
-        for quantile in (_TAIL * 1e-3, 1.0 - _TAIL * 1e-3):
-            edge = float(dist.ppf(quantile))
-            if not np.isfinite(edge):
-                continue
-            density = float(dist.pdf(edge))
-            if not np.isfinite(density) or density > pmax * 1.01:
-                raise ValueError(
-                    "the density of this distribution diverges, so its "
-                    "maximum depends only on where the tail is cut and the "
-                    "illuminated-area correction has no reference intensity. "
-                    "Use a distribution with a bounded peak."
-                )
-
-    @staticmethod
-    def _finite_moment(func):
-        """Evaluate a distribution moment, returning ``nan`` if it diverges."""
-        try:
-            value = float(func())
-        except (ValueError, TypeError, ZeroDivisionError):
-            return float("nan")
-        return value if np.isfinite(value) else float("nan")
-
-    @staticmethod
-    def _locate_peak(dist, lo, hi):
-        """Find the position and value of the maximum density.
-
-        Scans the central range first so that a plateau or a second maximum
-        cannot be missed, then refines a single interior maximum. The
-        plateau of a top hat resolves to its midpoint.
-
-        :returns: ``(peak_position, peak_density)``.
-        :rtype: tuple of float
-        """
-        z = np.linspace(lo, hi, _SCAN_POINTS)
-        p = np.asarray(dist.pdf(z), dtype=float)
-        p = np.where(np.isfinite(p), p, -np.inf)
-        pmax = float(p.max())
-        if not np.isfinite(pmax) or pmax <= 0:
-            return float("nan"), pmax
-        # A flat top has no single argmax; take the middle of the plateau.
-        flat = np.flatnonzero(p >= pmax * (1.0 - 1e-12))
-        if flat.size > 1:
-            return float(0.5 * (z[flat[0]] + z[flat[-1]])), pmax
-        best = int(flat[0])
-        if best == 0 or best == z.size - 1:
-            return float(z[best]), pmax
-        refined = optimize.minimize_scalar(
-            lambda x: -float(dist.pdf(x)),
-            bounds=(z[best - 1], z[best + 1]),
-            method="bounded",
-            options={"xatol": (hi - lo) * 1e-12},
-        )
-        position = float(refined.x)
-        density = float(dist.pdf(position))
-        return (position, density) if density >= pmax else (float(z[best]), pmax)
-
-    def _cumulative(self, x):
-        """Integral of the profile up to ``x``, relative to the sample center."""
-        return self._dist.cdf(np.asarray(x, dtype=float) + self.sample_center)
-
-    def _density_at(self, x):
-        """Profile density at ``x``, relative to the sample center."""
-        return self._dist.pdf(np.asarray(x, dtype=float) + self.sample_center)
-
-    def profile_curve(self, n=512):
-        """Sample the distribution over its central range."""
-        z = np.linspace(self._lo, self._hi, int(n))
-        return z - self.sample_center, np.asarray(self._dist.pdf(z), dtype=float)
-
-    @property
-    def support(self):
-        """``(z_min, z_max)`` of the plotted range, relative to the center."""
-        return (
-            float(self._lo - self.sample_center),
-            float(self._hi - self.sample_center),
-        )
-
-    @property
-    def fwhm(self):
-        """Full width at half maximum of the distribution, in meters."""
-        z = np.linspace(self._lo, self._hi, _SCAN_POINTS)
-        return _half_maximum_width(
-            z, np.asarray(self._dist.pdf(z), dtype=float), self._pmax
-        )
-
-    def __repr__(self):
-        return (
-            f"DistributionBeamProfile({self._dist!r}, "
-            f"fwhm={self.fwhm:g} m, center={self.center!r})"
-        )
-
-
-class _SmoothedTopHat:
-    """Top hat of full ``width`` convolved with a Gaussian of ``sigma``.
-
-    The frozen-distribution interface :class:`DistributionBeamProfile`
-    needs, implemented in closed form. This is the beam a pair of defining
-    slits produces once the finite source size blurs the slit edges, so the
-    profile is flat in the middle with error-function flanks.
-
-    :param float width: Full width of the top hat, in meters.
-    :param float sigma: Standard deviation of the edge blur, in meters.
-    """
-
-    def __init__(self, width, sigma):
-        width = float(width)
-        sigma = float(sigma)
-        if not width > 0:
-            raise ValueError(f"width must be positive, got {width:g}")
-        if not sigma > 0:
-            raise ValueError(f"edge sigma must be positive, got {sigma:g}")
-        self.width = width
-        self.sigma = sigma
-        self._a = -0.5 * width
-        self._b = 0.5 * width
-
-    def pdf(self, x):
-        """Density: the difference of two shifted normal CDFs."""
-        x = np.asarray(x, dtype=float)
-        return (
-            special.ndtr((x - self._a) / self.sigma)
-            - special.ndtr((x - self._b) / self.sigma)
-        ) / self.width
-
-    def cdf(self, x):
-        """Cumulative distribution, the antiderivative of :meth:`pdf`."""
-        x = np.asarray(x, dtype=float)
-
-        def term(edge):
-            u = (x - edge) / self.sigma
-            return (x - edge) * special.ndtr(u) + self.sigma * np.exp(
-                -0.5 * u**2
-            ) / np.sqrt(2 * np.pi)
-
-        return (term(self._a) - term(self._b)) / self.width
-
-    def ppf(self, q):
-        """Quantile function, inverted numerically from :meth:`cdf`."""
-        q = float(q)
-        if q <= 0.0 or q >= 1.0:
-            raise ValueError(f"quantile must be in (0, 1), got {q:g}")
-        span = 0.5 * self.width + 12.0 * self.sigma
-        return float(optimize.brentq(lambda x: self.cdf(x) - q, -span, span))
-
-    def mean(self):
-        """The profile is symmetric about zero."""
-        return 0.0
-
-    def std(self):
-        """Quadrature sum of the top-hat and blur widths."""
-        return float(np.sqrt(self.width**2 / 12.0 + self.sigma**2))
-
-    def __repr__(self):
-        return f"_SmoothedTopHat(width={self.width:g}, sigma={self.sigma:g})"
-
-
-def gaussian_profile(fwhm, center="centroid", offset=0.0):
-    """Gaussian beam profile that supports centering and an offset.
-
-    Numerically the same model as :class:`GaussianBeamProfile`, which
-    evaluates it in closed form but always sits centered on the sample. Use
-    this one when the sample is displaced from the beam center.
-
-    :param float fwhm: Full width at half maximum, in meters.
-    :param str center: Centering, see :class:`DistributionBeamProfile`.
-    :param float offset: Sample-center displacement, in meters.
-    :rtype: DistributionBeamProfile
-    :raises ValueError: If ``fwhm`` is not positive.
-    """
-    fwhm = float(fwhm)
-    if not fwhm > 0:
-        raise ValueError(f"fwhm must be positive, got {fwhm:g}")
-    return DistributionBeamProfile(
-        stats.norm(loc=0.0, scale=fwhm * _FWHM_TO_SIGMA), center=center, offset=offset
-    )
-
-
-def top_hat_profile(width, center="centroid", offset=0.0):
-    """Beam profile of uniform intensity over ``width``.
-
-    The slit-limited beam. With this profile ``C_flux_on_sample`` is
-    ``L sin(alpha) / width`` until the sample intercepts the whole beam,
-    the linear correction of Gibaud, Vignaud & Sinha (1993),
-    *Acta Cryst.* A49, 642, equation (12), and ``C_illum_area`` stays at 1
-    over the same range.
-
-    :param float width: Full width of the beam, in meters.
-    :param str center: Centering, see :class:`DistributionBeamProfile`.
-    :param float offset: Sample-center displacement, in meters.
-    :rtype: DistributionBeamProfile
-    :raises ValueError: If ``width`` is not positive.
-    """
-    width = float(width)
-    if not width > 0:
-        raise ValueError(f"width must be positive, got {width:g}")
-    return DistributionBeamProfile(
-        stats.uniform(loc=-0.5 * width, scale=width), center=center, offset=offset
-    )
-
-
-def trapezoid_profile(full_width, flat_width, center="centroid", offset=0.0):
-    """Beam profile of a trapezoid with symmetric flanks.
-
-    Two slits of different apertures convolve to a trapezoid whose flat top
-    is the smaller aperture and whose base is the larger one; matched slits
-    give the triangle of :func:`triangular_profile`.
-
-    :param float full_width: Width at the base, in meters.
-    :param float flat_width: Width of the flat top, in meters, between 0 and
-        ``full_width``.
-    :param str center: Centering, see :class:`DistributionBeamProfile`.
-    :param float offset: Sample-center displacement, in meters.
-    :rtype: DistributionBeamProfile
-    :raises ValueError: If the widths are not positive and ordered.
-    """
-    full_width = float(full_width)
-    flat_width = float(flat_width)
-    if not full_width > 0:
-        raise ValueError(f"full_width must be positive, got {full_width:g}")
-    if not 0.0 <= flat_width <= full_width:
-        raise ValueError(
-            f"flat_width must be between 0 and full_width, got {flat_width:g} "
-            f"with full_width {full_width:g}"
-        )
-    ramp = 0.5 * (1.0 - flat_width / full_width)
-    return DistributionBeamProfile(
-        stats.trapezoid(ramp, 1.0 - ramp, loc=-0.5 * full_width, scale=full_width),
-        center=center,
-        offset=offset,
-    )
-
-
-def triangular_profile(full_width, center="centroid", offset=0.0):
-    """Beam profile of a symmetric triangle, from two matched slits.
-
-    :param float full_width: Width at the base, in meters.
-    :param str center: Centering, see :class:`DistributionBeamProfile`.
-    :param float offset: Sample-center displacement, in meters.
-    :rtype: DistributionBeamProfile
-    """
-    return trapezoid_profile(full_width, 0.0, center=center, offset=offset)
-
-
-def smoothed_top_hat_profile(width, edge_sigma, center="centroid", offset=0.0):
-    """Beam profile of a top hat with error-function flanks.
-
-    A slit-defined beam whose edges are blurred by the finite source size:
-    flat in the middle, with flanks of standard deviation ``edge_sigma``.
-
-    :param float width: Full width of the flat part before blurring, in
-        meters.
-    :param float edge_sigma: Standard deviation of the edge blur, in meters.
-    :param str center: Centering, see :class:`DistributionBeamProfile`.
-    :param float offset: Sample-center displacement, in meters.
-    :rtype: DistributionBeamProfile
-    """
-    return DistributionBeamProfile(
-        _SmoothedTopHat(width, edge_sigma), center=center, offset=offset
-    )
-
-
-def generalized_normal_profile(fwhm, flatness, center="centroid", offset=0.0):
-    """Beam profile interpolating between a peaked, Gaussian and flat beam.
-
-    The generalized normal density is proportional to
-    ``exp(-|z / scale| ** flatness)``: ``flatness = 1`` gives an exponential
-    cusp, ``flatness = 2`` is exactly Gaussian, and large values approach a
-    top hat. It is the one-parameter family for a focused beam that is
-    neither Gaussian nor flat.
-
-    :param float fwhm: Full width at half maximum, in meters.
-    :param float flatness: Shape exponent, positive.
-    :param str center: Centering, see :class:`DistributionBeamProfile`.
-    :param float offset: Sample-center displacement, in meters.
-    :rtype: DistributionBeamProfile
-    :raises ValueError: If ``fwhm`` or ``flatness`` is not positive.
-    """
-    fwhm = float(fwhm)
-    flatness = float(flatness)
-    if not fwhm > 0:
-        raise ValueError(f"fwhm must be positive, got {fwhm:g}")
-    if not flatness > 0:
-        raise ValueError(f"flatness must be positive, got {flatness:g}")
-    # exp(-(w/2 / scale)**flatness) = 1/2 at the half maximum.
-    scale = 0.5 * fwhm / np.log(2.0) ** (1.0 / flatness)
-    return DistributionBeamProfile(
-        stats.gennorm(flatness, loc=0.0, scale=scale), center=center, offset=offset
-    )
-
-
-def skew_normal_profile(fwhm, skew, center="centroid", offset=0.0):
-    """Asymmetric beam profile with a Gaussian core.
-
-    The skew-normal density, scaled so that its full width at half maximum
-    is ``fwhm``. ``skew = 0`` is Gaussian; positive values put the tail
-    toward larger ``z``.
-
-    :param float fwhm: Full width at half maximum, in meters.
-    :param float skew: Shape parameter; 0 is symmetric.
-    :param str center: Centering, see :class:`DistributionBeamProfile`.
-    :param float offset: Sample-center displacement, in meters.
-    :rtype: DistributionBeamProfile
-    :raises ValueError: If ``fwhm`` is not positive.
-    """
-    fwhm = float(fwhm)
-    if not fwhm > 0:
-        raise ValueError(f"fwhm must be positive, got {fwhm:g}")
-    skew = float(skew)
-    # The skew normal has no closed-form FWHM; measure it once at unit
-    # scale and rescale, since the family is a location-scale family.
-    unit = stats.skewnorm(skew)
-    z = np.linspace(unit.ppf(_TAIL), unit.ppf(1.0 - _TAIL), _SCAN_POINTS)
-    p = unit.pdf(z)
-    unit_fwhm = _half_maximum_width(z, p, float(p.max()))
-    return DistributionBeamProfile(
-        stats.skewnorm(skew, loc=0.0, scale=fwhm / unit_fwhm),
-        center=center,
-        offset=offset,
-    )
-
-
-def profile_from_height_scan(z, intensity, monitor=None):
-    r"""Differentiate a sample height scan into a beam profile.
-
-    In a height (``samz``) scan the sample edge cuts progressively further
-    into the beam, so the transmitted intensity is the beam profile
-    integrated over the part of the beam still passing the sample,
-    :math:`I(z) = I_0 \int_z^\infty p(z')\,\mathrm{d}z'`. The profile is
-    therefore the *negated* derivative of the measured curve,
-
-    .. math:: p(z) \propto -\frac{\mathrm{d}I}{\mathrm{d}z}
-
-    which also removes any constant transmission offset. ``z`` keeps its
-    direction, so the returned profile is the beam profile in the same
-    (upward) coordinate as the scan.
-
-    Only the range over which the edge cuts into the beam is meaningful. A
-    scan that continues until the sample leaves the beam again has a
-    negative derivative there and must be sliced before use, otherwise the
-    result is a profile followed by its mirror image.
-
-    :param z: Height positions of the scan, in meters, strictly monotonic.
-    :param intensity: Transmitted intensity at each ``z``.
-    :param monitor: Optional incident-beam monitor at each ``z``. When
-        given, ``intensity`` is divided by it before differentiation, which
-        removes storage-ring current drift over the scan. The mean monitor
-        value is multiplied back in, so the profile keeps the scale of the
-        raw counts.
-    :returns: ``(z, profile)``, the profile in arbitrary units and of the
-        same length as ``z``.
-    :rtype: tuple of numpy.ndarray
-    :raises ValueError: If the inputs have different lengths, if fewer than
-        two points are given, or if ``monitor`` contains zeros.
-    """
-    z = np.asarray(z, dtype=float).ravel()
-    intensity = np.asarray(intensity, dtype=float).ravel()
-    if z.size != intensity.size:
-        raise ValueError(
-            "z and intensity must have the same length, got "
-            f"{z.size:d} and {intensity.size:d}"
-        )
-    if z.size < 2:
-        raise ValueError("a height scan needs at least two points")
-    if monitor is not None:
-        monitor = np.asarray(monitor, dtype=float).ravel()
-        if monitor.size != z.size:
-            raise ValueError(
-                "monitor must have the same length as z, got "
-                f"{monitor.size:d} and {z.size:d}"
-            )
-        if np.any(monitor == 0):
-            raise ValueError("monitor contains zeros")
-        intensity = intensity / monitor * float(np.mean(monitor))
-    return z, -np.gradient(intensity, z)
-
-
-def trim_to_illuminated_edge(z, profile):
-    """Restrict a differentiated height scan to its single cutting edge.
-
-    A height scan long enough to move the sample fully through the beam
-    contains two edges: the sample cutting in, whose negated derivative is
-    the beam profile, and -- if the beam clears the sample again -- the
-    sample leaving, which appears as a negative excursion. Only the first is
-    a beam profile.
-
-    The returned slice is the run of samples around the maximum over which
-    the profile stays positive, i.e. it is cut at the sign changes flanking
-    the peak. A profile that is positive everywhere is returned unchanged.
-
-    :param z: Positions, strictly monotonic and increasing.
-    :param profile: Profile values at ``z``, as returned by
-        :func:`profile_from_height_scan`.
-    :returns: ``(z, profile)`` restricted to the edge.
-    :rtype: tuple of numpy.ndarray
-    :raises ValueError: If no positive sample exists at all, which means the
-        scan was differentiated with the wrong sign.
-    """
-    z = np.asarray(z, dtype=float).ravel()
-    profile = np.asarray(profile, dtype=float).ravel()
-    if z.size != profile.size:
-        raise ValueError(
-            "z and profile must have the same length, got "
-            f"{z.size:d} and {profile.size:d}"
-        )
-    if not np.any(profile > 0):
-        raise ValueError(
-            "the differentiated height scan has no positive values; it is "
-            "most likely differentiated with the wrong sign"
-        )
-    peak = int(np.argmax(profile))
-    nonpositive = np.flatnonzero(profile <= 0)
-    before = nonpositive[nonpositive < peak]
-    after = nonpositive[nonpositive > peak]
-    start = int(before[-1]) + 1 if before.size else 0
-    stop = int(after[0]) if after.size else z.size
-    return z[start:stop], profile[start:stop]
-
-
-def read_profile_file(
-    path,
-    z_scale=1e-3,
-    height_scan=False,
-    usecols=(0, 1),
-    monitor_col=None,
-    trim=True,
-):
-    """Read a two-column text file into a beam profile.
-
-    The file is read with :func:`numpy.loadtxt`, so ``#`` comments and any
-    common whitespace separator are accepted.
-
-    :param str path: File to read.
-    :param float z_scale: Factor converting the file's position column to
-        meters. The default ``1e-3`` reads millimeters, the usual unit of a
-        diffractometer height scan; use ``1e-6`` for micrometers.
-    :param bool height_scan: If ``True``, the intensity column is a measured
-        height scan and is differentiated by
-        :func:`profile_from_height_scan`. If ``False`` (default), it already
-        is a beam profile.
-    :param usecols: ``(position, intensity)`` column indices.
-    :param monitor_col: Optional column index of a monitor counter, only
-        used together with ``height_scan``.
-    :param bool trim: Restrict a differentiated height scan to its cutting
-        edge with :func:`trim_to_illuminated_edge`. Ignored unless
-        ``height_scan`` is set.
-    :returns: ``(z, profile)`` with ``z`` in meters.
-    :rtype: tuple of numpy.ndarray
-    """
-    cols = tuple(usecols) if monitor_col is None else tuple(usecols) + (monitor_col,)
-    data = np.loadtxt(path, usecols=cols, unpack=True, ndmin=2)
-    z = np.asarray(data[0], dtype=float) * float(z_scale)
-    intensity = np.asarray(data[1], dtype=float)
-    monitor = np.asarray(data[2], dtype=float) if monitor_col is not None else None
-    if not height_scan:
-        return z, intensity
-    if z.size > 1 and z[1] < z[0]:  # keep the edge search on an increasing axis
-        z, intensity = z[::-1], intensity[::-1]
-        monitor = None if monitor is None else monitor[::-1]
-    z, profile = profile_from_height_scan(z, intensity, monitor)
-    if trim:
-        z, profile = trim_to_illuminated_edge(z, profile)
-    return z, profile
diff --git a/orgui/datautils/xrayutils/corrections/__init__.py b/orgui/datautils/xrayutils/corrections/__init__.py
new file mode 100644
index 0000000..4e6e6b6
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/__init__.py
@@ -0,0 +1,73 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+r"""Everything that turns detector counts into a structure factor.
+
+One home for the correction factors of E. Vlieg, *J. Appl. Cryst.* **30**
+(1997) 532, in the two-dimensional-detector form of J. Drnec *et al.*,
+*J. Appl. Cryst.* **47** (2014) 365, so that a rocking scan, a stationary
+area-detector measurement and a reciprocal-space reconstruction of the same
+sample are corrected by the same code rather than by three copies of it.
+
+The split between the modules is by *what a factor depends on*, which is also
+what makes each of them testable on its own:
+
+:mod:`~.geometry`
+    Diffractometer angles only. The z-axis table of the ANA/ROD manual:
+    Lorentz factors, rod interception, the geometric area factor.
+:mod:`~.beamprofile`
+    The vertical profile of the incident beam and its integrals over a
+    finite sample.
+:mod:`~.detector`
+    Per-pixel factors of a detector image: solid angle and polarization.
+:mod:`~.normalization`
+    Counting time and monitor.
+:mod:`~.roi`
+    Reducing per-pixel factors onto a summed region of interest.
+
+Everything here is physics: arrays and scalars in, arrays out. Nothing in
+this package reads a scan object, a configuration file or a GUI widget.
+Resolving *which* corrections an experiment asked for, and pulling counters
+out of a beamline scan, belongs to :mod:`orgui.backend.scans` and to the
+application layer.
+
+For backwards compatibility ``orgui.datautils.xrayutils.geometrycorrections``
+and ``orgui.datautils.xrayutils.beamprofile`` remain importable and re-export
+:mod:`~.geometry` and :mod:`~.beamprofile` unchanged.
+"""
+
+from . import (  # noqa: F401
+    beamprofile,
+    detector,
+    geometry,
+    normalization,
+    roi,
+)
+
+__all__ = [
+    "beamprofile",
+    "detector",
+    "geometry",
+    "normalization",
+    "roi",
+]
diff --git a/orgui/datautils/xrayutils/corrections/beamprofile.py b/orgui/datautils/xrayutils/corrections/beamprofile.py
new file mode 100644
index 0000000..abb5937
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/beamprofile.py
@@ -0,0 +1,1049 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+r"""Incident-beam profiles for numerical footprint corrections.
+
+Two related quantities are evaluated at incidence angle :math:`\alpha` on a
+sample of length :math:`L` along the beam:
+
+``C_flux_on_sample``
+    the fraction of the total incident flux that actually strikes the sample.
+    This is the overlap integral used below and is stored as a diagnostic; it
+    is not an additional intensity divisor.
+
+``C_illum_area``
+    the numerical active surface area, referenced to a sample fully bathed in
+    a beam of the profile's peak intensity. This is the footprint divisor
+    applied to an integrated intensity.
+
+Both follow from the normalized vertical beam profile :math:`p(z)`, with
+:math:`\int p(z)\,\mathrm{d}z = 1`, where :math:`z` runs perpendicular to the
+beam in the scattering plane. With the projected sample size
+
+.. math:: h(\alpha) = L \sin\alpha
+
+and the sample centered at :math:`z_0` in the beam,
+
+.. math::
+
+    C_\mathrm{flux} = \int_{z_0 - h/2}^{z_0 + h/2} p(z)\,\mathrm{d}z
+    \qquad
+    C_\mathrm{area} = \frac{C_\mathrm{flux}}{p_\mathrm{max}\, h}
+
+:math:`C_\mathrm{area}` is the mean of :math:`p(z)/p_\mathrm{max}` over the
+projected sample footprint. It is the one-dimensional form of Vlieg's
+numerically illuminated area, so it already contains the overlap integral
+:math:`C_\mathrm{flux}`. Multiplying the two would count beam overspill twice.
+It tends to 1 when the sample is small compared with a centered beam and falls
+off as :math:`1/\sin\alpha` once the beam is fully on the sample.
+
+For a Gaussian :math:`p` both integrals have the closed form orGUI used before
+this module existed, reproduced exactly by :class:`GaussianBeamProfile`.
+:class:`MeasuredBeamProfile` evaluates the same two definitions by numerical
+integration of a tabulated profile, so an asymmetric or multiply-peaked beam
+measured at the beamline can be used instead of the Gaussian idealization.
+
+All lengths in this module are in **meters**, all angles in **radians**.
+"""
+
+from abc import ABC, abstractmethod
+
+import numpy as np
+from scipy import optimize, special, stats
+
+__all__ = [
+    "BeamProfile",
+    "DistributionBeamProfile",
+    "GaussianBeamProfile",
+    "MeasuredBeamProfile",
+    "gaussian_profile",
+    "generalized_normal_profile",
+    "profile_from_height_scan",
+    "read_profile_file",
+    "skew_normal_profile",
+    "smoothed_top_hat_profile",
+    "top_hat_profile",
+    "trapezoid_profile",
+    "triangular_profile",
+    "trim_to_illuminated_edge",
+]
+
+#: Quantile at which a distribution's plotted and searched range is cut.
+_TAIL = 1e-6
+
+#: Half-width of that range in interquartile ranges, used as a second bound.
+#: A heavy-tailed distribution puts its ``_TAIL`` quantile absurdly far out
+#: -- a Cauchy profile of 0.3 mm FWHM reaches its at about 40 m -- which
+#: would leave the peak unresolved by any practical number of samples. The
+#: interquartile range stays finite for every distribution, and 4 of them
+#: cover a Gaussian to 5.4 sigma, so the quantile bound still wins for
+#: light-tailed and bounded profiles and nothing changes for them.
+_RANGE_IQR = 4.0
+
+#: Number of samples used to locate maxima and half-maximum crossings.
+_SCAN_POINTS = 4001
+
+if hasattr(np, "trapezoid"):  # ToDo remove for orGUI release >1.5
+    _trapz_impl = np.trapezoid  # numpy >= 2.0
+else:
+    _trapz_impl = np.trapz  # noqa: NPY201  # numpy < 2.0
+
+#: Conversion of a Gaussian FWHM to its standard deviation.
+_FWHM_TO_SIGMA = 1.0 / (2.0 * np.sqrt(2.0 * np.log(2.0)))
+
+
+class BeamProfile(ABC):
+    """Vertical intensity profile of the incident beam.
+
+    Subclasses provide the applied active-area factor and its intercepted-flux
+    diagnostic for arbitrarily shaped arrays of incidence angles.
+    """
+
+    @abstractmethod
+    def flux_on_sample(self, alpha, L):
+        """Fraction of the incident flux intercepted by the sample.
+
+        :param alpha: Incidence angle(s) in radian, any array shape.
+            Expected in ``(0, pi/2]``.
+        :param float L: Sample size along the beam, in meters.
+        :returns: ``C_flux_on_sample``, broadcast to the shape of ``alpha``.
+        :rtype: numpy.ndarray
+        """
+
+    @abstractmethod
+    def illuminated_area_fraction(self, alpha, L):
+        """Illuminated fraction of the projected sample footprint.
+
+        :param alpha: Incidence angle(s) in radian, any array shape.
+        :param float L: Sample size along the beam, in meters.
+        :returns: ``C_illum_area``, broadcast to the shape of ``alpha``.
+        :rtype: numpy.ndarray
+        """
+
+    def corrections(self, alpha, L):
+        """Return the intercepted flux and numerical active area.
+
+        :param alpha: Incidence angle(s) in radian, any array shape.
+        :param float L: Sample size along the beam, in meters.
+        :returns: ``(C_flux_on_sample, C_illum_area)``. Only
+            ``C_illum_area`` is an integrated-intensity divisor;
+            ``C_flux_on_sample`` is its diagnostic numerator.
+        :rtype: tuple
+        """
+        return self.flux_on_sample(alpha, L), self.illuminated_area_fraction(alpha, L)
+
+    @abstractmethod
+    def profile_curve(self, n=512):
+        """Sample the profile for display.
+
+        :param int n: Requested number of samples. A tabulated profile
+            returns its own points and ignores this.
+        :returns: ``(z, p)`` with ``z`` relative to the sample center in
+            meters and ``p`` the normalized profile in 1/meter.
+        :rtype: tuple of numpy.ndarray
+        """
+
+    @property
+    @abstractmethod
+    def centroid_position(self):
+        """Center of mass relative to the sample center, in meters.
+
+        ``0.0`` when the sample is centered on the centroid, and ``nan``
+        for a profile whose first moment does not converge.
+
+        :rtype: float
+        """
+
+
+def _half_maximum_width(z, p, pmax):
+    """Width between the outermost crossings of ``pmax / 2``.
+
+    Uses the outermost crossings so that a profile with several maxima
+    reports its full extent rather than the width of a single sub-peak.
+
+    :param z: Sample positions, increasing.
+    :param p: Profile values at ``z``.
+    :param float pmax: Peak value the half maximum is taken from.
+    :returns: The full width at half maximum, in the units of ``z``.
+    :rtype: float
+    """
+    half = pmax / 2.0
+    above = np.flatnonzero(p >= half)
+    if above.size == 0:
+        return float("nan")
+    lo, hi = int(above[0]), int(above[-1])
+    if lo == 0:
+        left = z[lo]
+    else:
+        left = np.interp(half, [p[lo - 1], p[lo]], [z[lo - 1], z[lo]])
+    if hi == z.size - 1:
+        right = z[hi]
+    else:
+        right = np.interp(half, [p[hi + 1], p[hi]], [z[hi + 1], z[hi]])
+    return float(right - left)
+
+
+class _CenteredProfile(BeamProfile):
+    """Shared centering and correction evaluation for profiles with a CDF.
+
+    Both corrections follow from the cumulative integral of the profile and
+    from its peak density, so a subclass only has to supply
+    ``_cumulative(x)`` and ``_density_at(x)`` -- both in coordinates relative
+    to the sample center -- together with ``_pmax`` and the ``_tiny``
+    threshold below which the ``alpha -> 0`` limit is used.
+    """
+
+    def _set_center(self, center, offset, centroid, peak_position, median):
+        """Resolve the requested centering into :attr:`sample_center`.
+
+        :param str center: ``"centroid"``, ``"peak"`` or ``"median"``.
+        :param float offset: Extra displacement of the sample center.
+        :param float centroid: Center of mass of the profile.
+        :param float peak_position: Position of the maximum density.
+        :param float median: Position at which half the flux has passed.
+        :raises ValueError: If ``center`` is unknown, or names a reference
+            point this profile does not have (a heavy-tailed distribution
+            has no finite centroid).
+        """
+        try:
+            reference = {
+                "centroid": centroid,
+                "peak": peak_position,
+                "median": median,
+            }[center]
+        except KeyError:
+            raise ValueError(
+                f"center must be 'centroid', 'peak' or 'median', got {center!r}"
+            ) from None
+        if not np.isfinite(reference):
+            raise ValueError(
+                f"the {center} of this beam profile is not finite, so the "
+                "sample cannot be centered on it. Heavy-tailed profiles have "
+                "no center of mass; center on 'median' or 'peak' instead."
+            )
+        self.centroid = float(centroid)
+        self.peak_position = float(peak_position)
+        self.median = float(median)
+        self.center = center
+        self.offset = float(offset)
+        #: Position of the sample center in the profile's own coordinate.
+        self.sample_center = float(reference) + self.offset
+
+    @property
+    def centroid_position(self):
+        """Center of mass relative to the sample center, in meters."""
+        return float(self.centroid - self.sample_center)
+
+    def _flux(self, h):
+        """``C_flux_on_sample`` for a projected sample size ``h``."""
+        return self._cumulative(h / 2.0) - self._cumulative(-h / 2.0)
+
+    def flux_on_sample(self, alpha, L):
+        """Fraction of the incident flux intercepted by the sample.
+
+        Integrates the profile over the projected sample size
+        ``h = L sin(alpha)``, centered on the sample center.
+        """
+        return self._flux(L * np.sin(np.asarray(alpha, dtype=float)))
+
+    def illuminated_area_fraction(self, alpha, L):
+        """Illuminated fraction of the projected sample footprint.
+
+        ``C_flux_on_sample / (p_max * h)``, continued to its limit
+        ``p(0) / p_max`` as ``h -> 0``.
+        """
+        h = L * np.sin(np.asarray(alpha, dtype=float))
+        flux = self._flux(h)
+        limit = self._density_at(0.0) / self._pmax
+        denom = self._pmax * h
+        return np.where(
+            np.abs(h) > self._tiny,
+            flux / np.where(denom == 0.0, 1.0, denom),
+            limit,
+        )
+
+
+class GaussianBeamProfile(BeamProfile):
+    """Analytical Gaussian beam profile.
+
+    Reproduces orGUI's original closed-form footprint correction exactly; it
+    is the reference against which :class:`MeasuredBeamProfile` is validated.
+
+    :param float fwhm: Full width at half maximum of the vertical beam
+        profile, in meters.
+    :raises ValueError: If ``fwhm`` is not positive.
+    """
+
+    def __init__(self, fwhm):
+        fwhm = float(fwhm)
+        if not fwhm > 0:
+            raise ValueError(f"beam FWHM must be positive, got {fwhm:g}")
+        self.fwhm = fwhm
+        self.sigma = fwhm * _FWHM_TO_SIGMA
+
+    def flux_on_sample(self, alpha, L):
+        """Fraction of the incident flux intercepted by the sample.
+
+        Evaluates ``erf(h / (2 sqrt(2) sigma))`` with ``h = L sin(alpha)``.
+        """
+        arg = ((L * np.sin(alpha)) / (np.sqrt(2) * self.sigma)) * 0.5
+        return (1 / 2) * (special.erf(arg) - special.erf(-arg))
+
+    def illuminated_area_fraction(self, alpha, L):
+        """Illuminated fraction of the projected sample footprint."""
+        return (np.sqrt(2 * np.pi) * self.sigma * self.flux_on_sample(alpha, L)) / (
+            L * np.sin(alpha)
+        )
+
+    def profile_curve(self, n=512):
+        """Sample the Gaussian over +- 4 sigma around the sample center."""
+        z = np.linspace(-4.0 * self.sigma, 4.0 * self.sigma, int(n))
+        return z, np.exp(-0.5 * (z / self.sigma) ** 2) / (
+            np.sqrt(2 * np.pi) * self.sigma
+        )
+
+    @property
+    def centroid_position(self):
+        """A Gaussian is symmetric, so its centroid is the sample center."""
+        return 0.0
+
+    def __repr__(self):
+        return f"GaussianBeamProfile(fwhm={self.fwhm:g} m)"
+
+
+class MeasuredBeamProfile(_CenteredProfile):
+    """Tabulated beam profile integrated numerically.
+
+    The profile is treated as piecewise linear between the supplied sample
+    points and as exactly zero outside their range, so its cumulative
+    integral -- and with it ``C_flux_on_sample`` -- is evaluated in closed
+    form on each interval instead of being re-sampled onto an auxiliary grid.
+
+    A measured profile carries no absolute position information, so it is
+    re-referenced to the point of the beam that the center of the sample is
+    aligned to; see ``center``. For a symmetric profile every choice
+    coincides, and the results then reduce to :class:`GaussianBeamProfile`.
+
+    :param z: Positions perpendicular to the beam in the scattering plane,
+        in meters. Must be strictly monotonic; the direction is preserved
+        (increasing ``z`` upward, as in a sample height scan).
+    :param intensity: Beam intensity at ``z``, in arbitrary units. It is
+        normalized internally, so any scale or monitor normalization is fine.
+    :param str center: Which point of the profile the center of the sample
+        sits on: ``"centroid"`` (center of mass, the default), ``"peak"``
+        (maximum intensity), or ``"median"`` (the half-cut position an
+        edge-scan alignment converges to).
+    :param float offset: Additional displacement of the sample center from
+        the ``center`` reference, in meters. Positive moves the sample
+        center toward larger ``z``.
+    :raises ValueError: If ``z`` is not strictly monotonic, if fewer than
+        two points are given, if any value is not finite, or if the profile
+        does not have a positive integral.
+    """
+
+    def __init__(self, z, intensity, center="centroid", offset=0.0):
+        z = np.asarray(z, dtype=float).ravel()
+        intensity = np.asarray(intensity, dtype=float).ravel()
+        if z.size != intensity.size:
+            raise ValueError(
+                "z and intensity must have the same length, got "
+                f"{z.size:d} and {intensity.size:d}"
+            )
+        if z.size < 2:
+            raise ValueError("a beam profile needs at least two points")
+        if not np.all(np.isfinite(z)) or not np.all(np.isfinite(intensity)):
+            raise ValueError("beam profile contains non-finite values")
+
+        dz = np.diff(z)
+        if np.all(dz < 0):
+            z, intensity = z[::-1], intensity[::-1]
+            dz = np.diff(z)
+        if not np.all(dz > 0):
+            raise ValueError("z must be strictly monotonic")
+
+        norm = _trapz_impl(intensity, z)
+        if not norm > 0:
+            raise ValueError(
+                f"beam profile must have a positive integral, got {norm:g}. A "
+                "height scan differentiated with the wrong sign gives a "
+                "negative one."
+            )
+
+        p = intensity / norm
+        # Exact cumulative integral of the piecewise-linear profile at the
+        # sample points; interior positions are handled in _cumulative().
+        cum = np.concatenate(([0.0], np.cumsum(0.5 * (p[:-1] + p[1:]) * dz)))
+        cum[-1] = 1.0
+
+        self._z_raw = z
+        self._p = p
+        self._cum = cum
+        self._pmax = float(p.max())
+        # Guard for the alpha -> 0 limit, scaled to the profile's support so
+        # that it stays meaningful whatever length scale the caller works on.
+        self._tiny = 1e-9 * float(z[-1] - z[0])
+
+        centroid = float(_trapz_impl(z * p, z))
+        self._set_center(
+            center,
+            offset,
+            centroid,
+            float(z[np.argmax(p)]),
+            float(np.interp(0.5, cum, z)),
+        )
+        self.rms_width = float(
+            np.sqrt(max(float(_trapz_impl((z - centroid) ** 2 * p, z)), 0.0))
+        )
+
+    def profile_curve(self, n=512):
+        """Return the tabulated points; ``n`` is ignored."""
+        return self.z, self._p
+
+    @property
+    def z(self):
+        """Profile positions relative to the sample center, in meters."""
+        return self._z_raw - self.sample_center
+
+    @property
+    def density(self):
+        """Normalized profile ``p(z)`` in 1/meter, matching :attr:`z`."""
+        return self._p
+
+    @property
+    def support(self):
+        """``(z_min, z_max)`` of the profile relative to the sample center."""
+        return (
+            float(self._z_raw[0] - self.sample_center),
+            float(self._z_raw[-1] - self.sample_center),
+        )
+
+    @property
+    def fwhm(self):
+        """Full width at half maximum of the profile, in meters.
+
+        Measured between the outermost crossings of half the peak value, so
+        a profile with several maxima reports its full extent rather than
+        the width of a single sub-peak.
+        """
+        return _half_maximum_width(self._z_raw, self._p, self._pmax)
+
+    def _density_at(self, x):
+        """Normalized profile at ``x``, relative to the sample center."""
+        return np.interp(
+            np.asarray(x, dtype=float) + self.sample_center, self._z_raw, self._p
+        )
+
+    def _cumulative(self, x):
+        """Integral of the normalized profile from ``-inf`` up to ``x``.
+
+        ``x`` is given relative to the sample center. Outside the tabulated
+        range the profile is taken to be zero, so the result saturates at 0
+        and 1.
+        """
+        z, p, cum = self._z_raw, self._p, self._cum
+        x = np.clip(np.asarray(x, dtype=float) + self.sample_center, z[0], z[-1])
+        i = np.clip(np.searchsorted(z, x, side="right") - 1, 0, z.size - 2)
+        d = z[i + 1] - z[i]
+        t = (x - z[i]) / d
+        # Exact integral of one linear segment over [z[i], x].
+        return cum[i] + d * t * (p[i] + 0.5 * t * (p[i + 1] - p[i]))
+
+    def __repr__(self):
+        return (
+            f"MeasuredBeamProfile({self._z_raw.size:d} points, "
+            f"fwhm={self.fwhm:g} m, center={self.center!r})"
+        )
+
+
+class DistributionBeamProfile(_CenteredProfile):
+    """Beam profile given by an analytical probability distribution.
+
+    Both corrections need only the cumulative distribution and the peak
+    density, so any continuous distribution with a ``cdf``, a ``pdf`` and a
+    ``ppf`` can describe the beam -- in particular any frozen
+    :mod:`scipy.stats` distribution. The named constructors in this module
+    (:func:`top_hat_profile`, :func:`trapezoid_profile`,
+    :func:`smoothed_top_hat_profile`, :func:`generalized_normal_profile`,
+    :func:`skew_normal_profile`) wrap the shapes that describe real beams,
+    in physical parameters rather than raw distribution arguments.
+
+    :class:`GaussianBeamProfile` is the same model evaluated in closed form;
+    passing ``scipy.stats.norm`` here reproduces it to machine precision.
+
+    ``scipy.stats`` exposes no mode, so the peak is located once at
+    construction by scanning the distribution's central range and refining
+    the best sample. A plateau, as in a top hat, resolves to its midpoint.
+
+    :param dist: A frozen continuous distribution, e.g.
+        ``scipy.stats.norm(scale=1e-5)``.
+    :param str center: Which point of the profile the center of the sample
+        sits on: ``"centroid"`` (mean, the default), ``"peak"`` (mode) or
+        ``"median"``. All three coincide for a symmetric distribution.
+    :param float offset: Additional displacement of the sample center from
+        the ``center`` reference, in meters.
+    :raises TypeError: If ``dist`` is not a frozen distribution.
+    :raises ValueError: If the distribution has no finite central range, or
+        no finite positive maximum density -- a beam profile with an
+        unbounded peak has no active-area reference and cannot be used.
+    """
+
+    def __init__(self, dist, center="centroid", offset=0.0):
+        for name in ("cdf", "pdf", "ppf"):
+            if not callable(getattr(dist, name, None)):
+                raise TypeError(
+                    "dist must be a frozen continuous distribution with cdf, "
+                    f"pdf and ppf methods, got {dist!r}. Freeze a scipy.stats "
+                    "distribution first, e.g. scipy.stats.norm(scale=1e-5)."
+                )
+        if isinstance(dist, stats.rv_continuous):
+            # An unfrozen distribution answers every call with its standard
+            # form, which here would silently describe a beam one meter wide.
+            raise TypeError(
+                f"dist must be frozen, got the distribution family {dist!r}. "
+                "Supply its parameters, e.g. scipy.stats.norm(scale=1e-5) "
+                "rather than scipy.stats.norm."
+            )
+        lo, hi = self._central_range(dist)
+
+        self._dist = dist
+        self._lo = lo
+        self._hi = hi
+        peak_position, pmax = self._locate_peak(dist, lo, hi)
+        if not np.isfinite(pmax) or pmax <= 0:
+            raise ValueError(
+                f"the distribution has no finite positive maximum density "
+                f"(got {pmax:g}); the illuminated-area correction has no "
+                "reference intensity for such a profile."
+            )
+        self._reject_unbounded_density(dist, pmax)
+        self._pmax = pmax
+        self._tiny = 1e-9 * (hi - lo)
+
+        self._set_center(
+            center, offset, self._finite_moment(dist.mean), peak_position, dist.ppf(0.5)
+        )
+        self.rms_width = self._finite_moment(dist.std)
+
+    @staticmethod
+    def _central_range(dist):
+        """Range over which the profile is scanned and displayed.
+
+        The narrower of the ``_TAIL`` quantile range and ``_RANGE_IQR``
+        interquartile ranges around the median. This bounds only where the
+        peak is looked for, the width is measured and the preview is drawn;
+        the corrections always integrate the full distribution, so a
+        heavy-tailed profile still reports the flux that misses the sample.
+
+        :returns: ``(lo, hi)``.
+        :rtype: tuple of float
+        :raises ValueError: If the distribution is not localized.
+        """
+        lo = float(dist.ppf(_TAIL))
+        hi = float(dist.ppf(1.0 - _TAIL))
+        median = float(dist.ppf(0.5))
+        iqr = float(dist.ppf(0.75)) - float(dist.ppf(0.25))
+        if np.isfinite(iqr) and iqr > 0:
+            lo = max(lo, median - _RANGE_IQR * iqr)
+            hi = min(hi, median + _RANGE_IQR * iqr)
+        if not (np.isfinite(lo) and np.isfinite(hi) and hi > lo):
+            raise ValueError(
+                f"the distribution has no finite central range, got {lo:g} to "
+                f"{hi:g}. A beam profile must be localized."
+            )
+        return lo, hi
+
+    @staticmethod
+    def _reject_unbounded_density(dist, pmax):
+        """Refuse a distribution whose density diverges at an end.
+
+        The peak is searched between finite quantiles, so a density that
+        runs to infinity -- as a gamma distribution with shape below one
+        does at zero -- still yields a large but finite maximum there, and
+        that value would depend on nothing but the chosen cut. Probing a
+        much deeper quantile catches it: for a bounded density the value
+        stops growing, for a divergent one it does not.
+
+        :raises ValueError: If the density is still growing at either end.
+        """
+        for quantile in (_TAIL * 1e-3, 1.0 - _TAIL * 1e-3):
+            edge = float(dist.ppf(quantile))
+            if not np.isfinite(edge):
+                continue
+            density = float(dist.pdf(edge))
+            if not np.isfinite(density) or density > pmax * 1.01:
+                raise ValueError(
+                    "the density of this distribution diverges, so its "
+                    "maximum depends only on where the tail is cut and the "
+                    "illuminated-area correction has no reference intensity. "
+                    "Use a distribution with a bounded peak."
+                )
+
+    @staticmethod
+    def _finite_moment(func):
+        """Evaluate a distribution moment, returning ``nan`` if it diverges."""
+        try:
+            value = float(func())
+        except (ValueError, TypeError, ZeroDivisionError):
+            return float("nan")
+        return value if np.isfinite(value) else float("nan")
+
+    @staticmethod
+    def _locate_peak(dist, lo, hi):
+        """Find the position and value of the maximum density.
+
+        Scans the central range first so that a plateau or a second maximum
+        cannot be missed, then refines a single interior maximum. The
+        plateau of a top hat resolves to its midpoint.
+
+        :returns: ``(peak_position, peak_density)``.
+        :rtype: tuple of float
+        """
+        z = np.linspace(lo, hi, _SCAN_POINTS)
+        p = np.asarray(dist.pdf(z), dtype=float)
+        p = np.where(np.isfinite(p), p, -np.inf)
+        pmax = float(p.max())
+        if not np.isfinite(pmax) or pmax <= 0:
+            return float("nan"), pmax
+        # A flat top has no single argmax; take the middle of the plateau.
+        flat = np.flatnonzero(p >= pmax * (1.0 - 1e-12))
+        if flat.size > 1:
+            return float(0.5 * (z[flat[0]] + z[flat[-1]])), pmax
+        best = int(flat[0])
+        if best == 0 or best == z.size - 1:
+            return float(z[best]), pmax
+        refined = optimize.minimize_scalar(
+            lambda x: -float(dist.pdf(x)),
+            bounds=(z[best - 1], z[best + 1]),
+            method="bounded",
+            options={"xatol": (hi - lo) * 1e-12},
+        )
+        position = float(refined.x)
+        density = float(dist.pdf(position))
+        return (position, density) if density >= pmax else (float(z[best]), pmax)
+
+    def _cumulative(self, x):
+        """Integral of the profile up to ``x``, relative to the sample center."""
+        return self._dist.cdf(np.asarray(x, dtype=float) + self.sample_center)
+
+    def _density_at(self, x):
+        """Profile density at ``x``, relative to the sample center."""
+        return self._dist.pdf(np.asarray(x, dtype=float) + self.sample_center)
+
+    def profile_curve(self, n=512):
+        """Sample the distribution over its central range."""
+        z = np.linspace(self._lo, self._hi, int(n))
+        return z - self.sample_center, np.asarray(self._dist.pdf(z), dtype=float)
+
+    @property
+    def support(self):
+        """``(z_min, z_max)`` of the plotted range, relative to the center."""
+        return (
+            float(self._lo - self.sample_center),
+            float(self._hi - self.sample_center),
+        )
+
+    @property
+    def fwhm(self):
+        """Full width at half maximum of the distribution, in meters."""
+        z = np.linspace(self._lo, self._hi, _SCAN_POINTS)
+        return _half_maximum_width(
+            z, np.asarray(self._dist.pdf(z), dtype=float), self._pmax
+        )
+
+    def __repr__(self):
+        return (
+            f"DistributionBeamProfile({self._dist!r}, "
+            f"fwhm={self.fwhm:g} m, center={self.center!r})"
+        )
+
+
+class _SmoothedTopHat:
+    """Top hat of full ``width`` convolved with a Gaussian of ``sigma``.
+
+    The frozen-distribution interface :class:`DistributionBeamProfile`
+    needs, implemented in closed form. This is the beam a pair of defining
+    slits produces once the finite source size blurs the slit edges, so the
+    profile is flat in the middle with error-function flanks.
+
+    :param float width: Full width of the top hat, in meters.
+    :param float sigma: Standard deviation of the edge blur, in meters.
+    """
+
+    def __init__(self, width, sigma):
+        width = float(width)
+        sigma = float(sigma)
+        if not width > 0:
+            raise ValueError(f"width must be positive, got {width:g}")
+        if not sigma > 0:
+            raise ValueError(f"edge sigma must be positive, got {sigma:g}")
+        self.width = width
+        self.sigma = sigma
+        self._a = -0.5 * width
+        self._b = 0.5 * width
+
+    def pdf(self, x):
+        """Density: the difference of two shifted normal CDFs."""
+        x = np.asarray(x, dtype=float)
+        return (
+            special.ndtr((x - self._a) / self.sigma)
+            - special.ndtr((x - self._b) / self.sigma)
+        ) / self.width
+
+    def cdf(self, x):
+        """Cumulative distribution, the antiderivative of :meth:`pdf`."""
+        x = np.asarray(x, dtype=float)
+
+        def term(edge):
+            u = (x - edge) / self.sigma
+            return (x - edge) * special.ndtr(u) + self.sigma * np.exp(
+                -0.5 * u**2
+            ) / np.sqrt(2 * np.pi)
+
+        return (term(self._a) - term(self._b)) / self.width
+
+    def ppf(self, q):
+        """Quantile function, inverted numerically from :meth:`cdf`."""
+        q = float(q)
+        if q <= 0.0 or q >= 1.0:
+            raise ValueError(f"quantile must be in (0, 1), got {q:g}")
+        span = 0.5 * self.width + 12.0 * self.sigma
+        return float(optimize.brentq(lambda x: self.cdf(x) - q, -span, span))
+
+    def mean(self):
+        """The profile is symmetric about zero."""
+        return 0.0
+
+    def std(self):
+        """Quadrature sum of the top-hat and blur widths."""
+        return float(np.sqrt(self.width**2 / 12.0 + self.sigma**2))
+
+    def __repr__(self):
+        return f"_SmoothedTopHat(width={self.width:g}, sigma={self.sigma:g})"
+
+
+def gaussian_profile(fwhm, center="centroid", offset=0.0):
+    """Gaussian beam profile that supports centering and an offset.
+
+    Numerically the same model as :class:`GaussianBeamProfile`, which
+    evaluates it in closed form but always sits centered on the sample. Use
+    this one when the sample is displaced from the beam center.
+
+    :param float fwhm: Full width at half maximum, in meters.
+    :param str center: Centering, see :class:`DistributionBeamProfile`.
+    :param float offset: Sample-center displacement, in meters.
+    :rtype: DistributionBeamProfile
+    :raises ValueError: If ``fwhm`` is not positive.
+    """
+    fwhm = float(fwhm)
+    if not fwhm > 0:
+        raise ValueError(f"fwhm must be positive, got {fwhm:g}")
+    return DistributionBeamProfile(
+        stats.norm(loc=0.0, scale=fwhm * _FWHM_TO_SIGMA), center=center, offset=offset
+    )
+
+
+def top_hat_profile(width, center="centroid", offset=0.0):
+    """Beam profile of uniform intensity over ``width``.
+
+    The slit-limited beam. With this profile ``C_flux_on_sample`` is
+    ``L sin(alpha) / width`` until the sample intercepts the whole beam,
+    the linear correction of Gibaud, Vignaud & Sinha (1993),
+    *Acta Cryst.* A49, 642, equation (12), and ``C_illum_area`` stays at 1
+    over the same range.
+
+    :param float width: Full width of the beam, in meters.
+    :param str center: Centering, see :class:`DistributionBeamProfile`.
+    :param float offset: Sample-center displacement, in meters.
+    :rtype: DistributionBeamProfile
+    :raises ValueError: If ``width`` is not positive.
+    """
+    width = float(width)
+    if not width > 0:
+        raise ValueError(f"width must be positive, got {width:g}")
+    return DistributionBeamProfile(
+        stats.uniform(loc=-0.5 * width, scale=width), center=center, offset=offset
+    )
+
+
+def trapezoid_profile(full_width, flat_width, center="centroid", offset=0.0):
+    """Beam profile of a trapezoid with symmetric flanks.
+
+    Two slits of different apertures convolve to a trapezoid whose flat top
+    is the smaller aperture and whose base is the larger one; matched slits
+    give the triangle of :func:`triangular_profile`.
+
+    :param float full_width: Width at the base, in meters.
+    :param float flat_width: Width of the flat top, in meters, between 0 and
+        ``full_width``.
+    :param str center: Centering, see :class:`DistributionBeamProfile`.
+    :param float offset: Sample-center displacement, in meters.
+    :rtype: DistributionBeamProfile
+    :raises ValueError: If the widths are not positive and ordered.
+    """
+    full_width = float(full_width)
+    flat_width = float(flat_width)
+    if not full_width > 0:
+        raise ValueError(f"full_width must be positive, got {full_width:g}")
+    if not 0.0 <= flat_width <= full_width:
+        raise ValueError(
+            f"flat_width must be between 0 and full_width, got {flat_width:g} "
+            f"with full_width {full_width:g}"
+        )
+    ramp = 0.5 * (1.0 - flat_width / full_width)
+    return DistributionBeamProfile(
+        stats.trapezoid(ramp, 1.0 - ramp, loc=-0.5 * full_width, scale=full_width),
+        center=center,
+        offset=offset,
+    )
+
+
+def triangular_profile(full_width, center="centroid", offset=0.0):
+    """Beam profile of a symmetric triangle, from two matched slits.
+
+    :param float full_width: Width at the base, in meters.
+    :param str center: Centering, see :class:`DistributionBeamProfile`.
+    :param float offset: Sample-center displacement, in meters.
+    :rtype: DistributionBeamProfile
+    """
+    return trapezoid_profile(full_width, 0.0, center=center, offset=offset)
+
+
+def smoothed_top_hat_profile(width, edge_sigma, center="centroid", offset=0.0):
+    """Beam profile of a top hat with error-function flanks.
+
+    A slit-defined beam whose edges are blurred by the finite source size:
+    flat in the middle, with flanks of standard deviation ``edge_sigma``.
+
+    :param float width: Full width of the flat part before blurring, in
+        meters.
+    :param float edge_sigma: Standard deviation of the edge blur, in meters.
+    :param str center: Centering, see :class:`DistributionBeamProfile`.
+    :param float offset: Sample-center displacement, in meters.
+    :rtype: DistributionBeamProfile
+    """
+    return DistributionBeamProfile(
+        _SmoothedTopHat(width, edge_sigma), center=center, offset=offset
+    )
+
+
+def generalized_normal_profile(fwhm, flatness, center="centroid", offset=0.0):
+    """Beam profile interpolating between a peaked, Gaussian and flat beam.
+
+    The generalized normal density is proportional to
+    ``exp(-|z / scale| ** flatness)``: ``flatness = 1`` gives an exponential
+    cusp, ``flatness = 2`` is exactly Gaussian, and large values approach a
+    top hat. It is the one-parameter family for a focused beam that is
+    neither Gaussian nor flat.
+
+    :param float fwhm: Full width at half maximum, in meters.
+    :param float flatness: Shape exponent, positive.
+    :param str center: Centering, see :class:`DistributionBeamProfile`.
+    :param float offset: Sample-center displacement, in meters.
+    :rtype: DistributionBeamProfile
+    :raises ValueError: If ``fwhm`` or ``flatness`` is not positive.
+    """
+    fwhm = float(fwhm)
+    flatness = float(flatness)
+    if not fwhm > 0:
+        raise ValueError(f"fwhm must be positive, got {fwhm:g}")
+    if not flatness > 0:
+        raise ValueError(f"flatness must be positive, got {flatness:g}")
+    # exp(-(w/2 / scale)**flatness) = 1/2 at the half maximum.
+    scale = 0.5 * fwhm / np.log(2.0) ** (1.0 / flatness)
+    return DistributionBeamProfile(
+        stats.gennorm(flatness, loc=0.0, scale=scale), center=center, offset=offset
+    )
+
+
+def skew_normal_profile(fwhm, skew, center="centroid", offset=0.0):
+    """Asymmetric beam profile with a Gaussian core.
+
+    The skew-normal density, scaled so that its full width at half maximum
+    is ``fwhm``. ``skew = 0`` is Gaussian; positive values put the tail
+    toward larger ``z``.
+
+    :param float fwhm: Full width at half maximum, in meters.
+    :param float skew: Shape parameter; 0 is symmetric.
+    :param str center: Centering, see :class:`DistributionBeamProfile`.
+    :param float offset: Sample-center displacement, in meters.
+    :rtype: DistributionBeamProfile
+    :raises ValueError: If ``fwhm`` is not positive.
+    """
+    fwhm = float(fwhm)
+    if not fwhm > 0:
+        raise ValueError(f"fwhm must be positive, got {fwhm:g}")
+    skew = float(skew)
+    # The skew normal has no closed-form FWHM; measure it once at unit
+    # scale and rescale, since the family is a location-scale family.
+    unit = stats.skewnorm(skew)
+    z = np.linspace(unit.ppf(_TAIL), unit.ppf(1.0 - _TAIL), _SCAN_POINTS)
+    p = unit.pdf(z)
+    unit_fwhm = _half_maximum_width(z, p, float(p.max()))
+    return DistributionBeamProfile(
+        stats.skewnorm(skew, loc=0.0, scale=fwhm / unit_fwhm),
+        center=center,
+        offset=offset,
+    )
+
+
+def profile_from_height_scan(z, intensity, monitor=None):
+    r"""Differentiate a sample height scan into a beam profile.
+
+    In a height (``samz``) scan the sample edge cuts progressively further
+    into the beam, so the transmitted intensity is the beam profile
+    integrated over the part of the beam still passing the sample,
+    :math:`I(z) = I_0 \int_z^\infty p(z')\,\mathrm{d}z'`. The profile is
+    therefore the *negated* derivative of the measured curve,
+
+    .. math:: p(z) \propto -\frac{\mathrm{d}I}{\mathrm{d}z}
+
+    which also removes any constant transmission offset. ``z`` keeps its
+    direction, so the returned profile is the beam profile in the same
+    (upward) coordinate as the scan.
+
+    Only the range over which the edge cuts into the beam is meaningful. A
+    scan that continues until the sample leaves the beam again has a
+    negative derivative there and must be sliced before use, otherwise the
+    result is a profile followed by its mirror image.
+
+    :param z: Height positions of the scan, in meters, strictly monotonic.
+    :param intensity: Transmitted intensity at each ``z``.
+    :param monitor: Optional incident-beam monitor at each ``z``. When
+        given, ``intensity`` is divided by it before differentiation, which
+        removes storage-ring current drift over the scan. The mean monitor
+        value is multiplied back in, so the profile keeps the scale of the
+        raw counts.
+    :returns: ``(z, profile)``, the profile in arbitrary units and of the
+        same length as ``z``.
+    :rtype: tuple of numpy.ndarray
+    :raises ValueError: If the inputs have different lengths, if fewer than
+        two points are given, or if ``monitor`` contains zeros.
+    """
+    z = np.asarray(z, dtype=float).ravel()
+    intensity = np.asarray(intensity, dtype=float).ravel()
+    if z.size != intensity.size:
+        raise ValueError(
+            "z and intensity must have the same length, got "
+            f"{z.size:d} and {intensity.size:d}"
+        )
+    if z.size < 2:
+        raise ValueError("a height scan needs at least two points")
+    if monitor is not None:
+        monitor = np.asarray(monitor, dtype=float).ravel()
+        if monitor.size != z.size:
+            raise ValueError(
+                "monitor must have the same length as z, got "
+                f"{monitor.size:d} and {z.size:d}"
+            )
+        if np.any(monitor == 0):
+            raise ValueError("monitor contains zeros")
+        intensity = intensity / monitor * float(np.mean(monitor))
+    return z, -np.gradient(intensity, z)
+
+
+def trim_to_illuminated_edge(z, profile):
+    """Restrict a differentiated height scan to its single cutting edge.
+
+    A height scan long enough to move the sample fully through the beam
+    contains two edges: the sample cutting in, whose negated derivative is
+    the beam profile, and -- if the beam clears the sample again -- the
+    sample leaving, which appears as a negative excursion. Only the first is
+    a beam profile.
+
+    The returned slice is the run of samples around the maximum over which
+    the profile stays positive, i.e. it is cut at the sign changes flanking
+    the peak. A profile that is positive everywhere is returned unchanged.
+
+    :param z: Positions, strictly monotonic and increasing.
+    :param profile: Profile values at ``z``, as returned by
+        :func:`profile_from_height_scan`.
+    :returns: ``(z, profile)`` restricted to the edge.
+    :rtype: tuple of numpy.ndarray
+    :raises ValueError: If no positive sample exists at all, which means the
+        scan was differentiated with the wrong sign.
+    """
+    z = np.asarray(z, dtype=float).ravel()
+    profile = np.asarray(profile, dtype=float).ravel()
+    if z.size != profile.size:
+        raise ValueError(
+            "z and profile must have the same length, got "
+            f"{z.size:d} and {profile.size:d}"
+        )
+    if not np.any(profile > 0):
+        raise ValueError(
+            "the differentiated height scan has no positive values; it is "
+            "most likely differentiated with the wrong sign"
+        )
+    peak = int(np.argmax(profile))
+    nonpositive = np.flatnonzero(profile <= 0)
+    before = nonpositive[nonpositive < peak]
+    after = nonpositive[nonpositive > peak]
+    start = int(before[-1]) + 1 if before.size else 0
+    stop = int(after[0]) if after.size else z.size
+    return z[start:stop], profile[start:stop]
+
+
+def read_profile_file(
+    path,
+    z_scale=1e-3,
+    height_scan=False,
+    usecols=(0, 1),
+    monitor_col=None,
+    trim=True,
+):
+    """Read a two-column text file into a beam profile.
+
+    The file is read with :func:`numpy.loadtxt`, so ``#`` comments and any
+    common whitespace separator are accepted.
+
+    :param str path: File to read.
+    :param float z_scale: Factor converting the file's position column to
+        meters. The default ``1e-3`` reads millimeters, the usual unit of a
+        diffractometer height scan; use ``1e-6`` for micrometers.
+    :param bool height_scan: If ``True``, the intensity column is a measured
+        height scan and is differentiated by
+        :func:`profile_from_height_scan`. If ``False`` (default), it already
+        is a beam profile.
+    :param usecols: ``(position, intensity)`` column indices.
+    :param monitor_col: Optional column index of a monitor counter, only
+        used together with ``height_scan``.
+    :param bool trim: Restrict a differentiated height scan to its cutting
+        edge with :func:`trim_to_illuminated_edge`. Ignored unless
+        ``height_scan`` is set.
+    :returns: ``(z, profile)`` with ``z`` in meters.
+    :rtype: tuple of numpy.ndarray
+    """
+    cols = tuple(usecols) if monitor_col is None else tuple(usecols) + (monitor_col,)
+    data = np.loadtxt(path, usecols=cols, unpack=True, ndmin=2)
+    z = np.asarray(data[0], dtype=float) * float(z_scale)
+    intensity = np.asarray(data[1], dtype=float)
+    monitor = np.asarray(data[2], dtype=float) if monitor_col is not None else None
+    if not height_scan:
+        return z, intensity
+    if z.size > 1 and z[1] < z[0]:  # keep the edge search on an increasing axis
+        z, intensity = z[::-1], intensity[::-1]
+        monitor = None if monitor is None else monitor[::-1]
+    z, profile = profile_from_height_scan(z, intensity, monitor)
+    if trim:
+        z, profile = trim_to_illuminated_edge(z, profile)
+    return z, profile
diff --git a/orgui/datautils/xrayutils/corrections/detector.py b/orgui/datautils/xrayutils/corrections/detector.py
new file mode 100644
index 0000000..6d5d686
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/detector.py
@@ -0,0 +1,89 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+r"""Per-pixel correction factors of a detector image.
+
+The factors that depend on where a photon landed on the detector rather than
+on the scan: the solid angle each pixel subtends and the polarization factor
+at its scattering angle. Both are properties of the calibrated geometry, so
+they are evaluated once and reused for every frame that shares it.
+
+They are returned as a **multiplicative** factor, the reciprocal of the
+physical quantities, because that is how a corrected intensity is formed:
+
+.. math::
+
+    I_\mathrm{corr} = I \cdot \frac{1}{\Omega\,P}
+
+The rocking integration, the stationary integration and the reciprocal-space
+reconstruction each built this array themselves; this is the one definition
+they share.
+
+.. warning::
+
+    :meth:`~.DetectorCalibration.Detector2D_SXRD.polarizationArray` evaluates
+    the polarization at the **calibrated** detector position. That is correct
+    for a detector whose arm does not move -- every pixel already carries its
+    own scattering angle -- but not for a scan that drives the arm, where it
+    understates the correction badly: 3 % at a scattering angle of 10
+    degrees, 10 % at 18 and 33 % at 30.
+    :meth:`~.DetectorCalibration.Detector2D_SXRD.polarizationAtPoints`
+    follows the arm and is what such a scan needs. This function reproduces
+    the historical, arm-blind behavior; see
+    ``doc/design/ctr_structure_factor_scale.md`` finding F5.
+"""
+
+import numpy as np
+
+__all__ = ["pixel_factors"]
+
+
+def pixel_factors(detector, solid_angle=False, polarization=False, shape=None):
+    r"""Per-pixel multiplicative correction factor of a detector image.
+
+    :param detector: A
+        :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`
+        with its calibrated geometry and polarization set.
+    :param bool solid_angle: Divide by the solid angle each pixel subtends.
+    :param bool polarization: Divide by the polarization factor.
+    :param shape: Detector shape; taken from the detector when omitted.
+    :returns: The factor for every pixel, or ``None`` when neither
+        correction is enabled -- which lets a caller skip the multiplication
+        entirely rather than multiply by an array of ones.
+    :rtype: numpy.ndarray or None
+    """
+    factor = None
+    if solid_angle:
+        factor = 1.0 / np.asarray(
+            detector.solidAngleArray(shape) if shape is not None
+            else detector.solidAngleArray(),
+            dtype=np.float64,
+        )
+    if polarization:
+        values = np.asarray(
+            detector.polarizationArray(shape) if shape is not None
+            else detector.polarizationArray(),
+            dtype=np.float64,
+        )
+        factor = 1.0 / values if factor is None else factor / values
+    return factor
diff --git a/orgui/datautils/xrayutils/corrections/geometry.py b/orgui/datautils/xrayutils/corrections/geometry.py
new file mode 100644
index 0000000..4610612
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/geometry.py
@@ -0,0 +1,219 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+r"""Geometrical correction factors of the z-axis diffractometer.
+
+orGUI applies the correction factors tabulated for the **z-axis geometry** in
+Appendix A of the ANA/ROD manual (E. Vlieg, *ANA -- program for the analysis
+of surface X-ray diffraction data*), which reproduces
+E. Vlieg, *J. Appl. Cryst.* **30** (1997) 532. The z-axis, 5-circle and
+6-circle geometries are special cases of one another; only the z-axis column
+is implemented here, and it is the one orGUI's angle convention matches.
+
+Angles follow :mod:`orgui.datautils.xrayutils.HKLVlieg`:
+
+``alpha``
+    incidence angle of the beam on the surface, in radian. This is the ``mu``
+    circle of the diffractometer, and the angle the footprint corrections of
+    :mod:`orgui.datautils.xrayutils.corrections.beamprofile` depend on.
+``delta``
+    in-plane detector angle, in radian.
+``gamma``
+    out-of-plane detector angle, in radian. In the z-axis geometry this is
+    the exit angle of the diffracted beam from the surface.
+
+The table entries used are, verbatim from the manual:
+
+=========================================  ================================
+Lorentz factor rocking scan                :math:`1/(\sin\delta\,
+                                           \cos\alpha\,\cos\gamma)`
+Lorentz factor stationary mode             :math:`1/\sin\gamma`
+Lorentz factor reflectivity rocking scan   :math:`1/\sin 2\alpha`
+Rod interception (rocking scans only)      :math:`\cos\gamma`
+Area correction (ignoring footprint and    :math:`1/\sin\delta`
+sample size)
+Beam profile and finite sample size        calculated numerically, see
+                                           :mod:`~.beamprofile`
+=========================================  ================================
+
+For rocking scans, the tabulated Lorentz factor and rod interception are
+divided out of the integrated intensity:
+
+.. math:: F^2_{hkl} = \frac{I}{L \cdot C_\mathrm{rod}}
+
+The three Lorentz factors are alternatives, selected by how the intensity was
+measured, not factors to be combined. Vlieg's stationary expression has no
+rod-interception factor:
+
+* a rocking scan about the sample rotation (``th``/``omega``) uses the
+  rocking-scan factor,
+* a rocking scan about the incidence angle (``mu``), which is how a
+  reflectivity curve is measured, uses the reflectivity factor,
+* a scan with the sample stationary, integrated across the rod on an area
+  detector, uses the stationary factor alone.
+
+The area correction :math:`1/\sin\delta` is listed for completeness and is
+**not** applied by orGUI; the numerically evaluated beam-profile and finite
+sample-size corrections of :mod:`~.beamprofile` are used instead.
+"""
+
+import numpy as np
+
+__all__ = [
+    "AREA",
+    "REFLECTIVITY_ROCKING",
+    "ROCKING",
+    "STATIONARY",
+    "area_correction",
+    "lorentz_factor",
+    "lorentz_reflectivity_rocking_scan",
+    "lorentz_rocking_scan",
+    "lorentz_stationary",
+    "rod_interception",
+]
+
+#: Lorentz factor of a rocking scan about the sample rotation.
+ROCKING = "rocking"
+
+#: Lorentz factor of a rocking scan about the incidence angle.
+REFLECTIVITY_ROCKING = "reflectivity_rocking"
+
+#: Lorentz factor of a scan measured with the sample stationary.
+STATIONARY = "stationary"
+
+#: Identifier of the area correction, for provenance strings.
+AREA = "area"
+
+
+def lorentz_rocking_scan(delta, alpha, gamma):
+    r"""Lorentz factor of a rocking scan about the sample rotation.
+
+    :math:`L = 1/(\sin\delta\,\cos\alpha\,\cos\gamma)`, the z-axis
+    "Lorentz factor rocking scan" entry. The absolute value is taken so that
+    integrated intensities stay positive whichever way the scan runs.
+
+    :param delta: In-plane detector angle, in radian.
+    :param alpha: Incidence angle, in radian.
+    :param gamma: Out-of-plane detector angle, in radian.
+    :returns: The Lorentz factor, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    """
+    return np.abs(1.0 / (np.sin(delta) * np.cos(alpha) * np.cos(gamma)))
+
+
+def lorentz_reflectivity_rocking_scan(alpha):
+    r"""Lorentz factor of a reflectivity scan rocked in the incidence angle.
+
+    :math:`L = 1/\sin 2\alpha`, the z-axis "Lorentz factor reflectivity
+    rocking scan" entry.
+
+    :param alpha: Incidence angle, in radian.
+    :returns: The Lorentz factor, broadcast over the input.
+    :rtype: numpy.ndarray
+    """
+    return np.abs(1.0 / np.sin(2.0 * np.asarray(alpha, dtype=float)))
+
+
+def lorentz_stationary(gamma):
+    r"""Lorentz factor of a measurement with the sample stationary.
+
+    :math:`L = 1/\sin\gamma`, the z-axis "Lorentz factor stationary mode"
+    entry. In this geometry :math:`\gamma` is the exit angle of the
+    diffracted beam from the surface, so the factor diverges as the rod
+    approaches the surface plane, where a stationary measurement carries no
+    information about the rod profile.
+
+    :param gamma: Out-of-plane detector angle, in radian.
+    :returns: The Lorentz factor, broadcast over the input.
+    :rtype: numpy.ndarray
+    """
+    return np.abs(1.0 / np.sin(np.asarray(gamma, dtype=float)))
+
+
+def rod_interception(gamma):
+    r"""Rocking-scan rod interception factor, :math:`\cos\gamma`.
+
+    :param gamma: Out-of-plane detector angle, in radian.
+    :returns: The rod interception factor, broadcast over the input.
+    :rtype: numpy.ndarray
+    """
+    return np.cos(np.asarray(gamma, dtype=float))
+
+
+def area_correction(delta):
+    r"""Area correction ignoring footprint and sample size, :math:`1/\sin\delta`.
+
+    Listed in the manual for completeness. orGUI does not apply it: the
+    footprint corrections of :mod:`~.beamprofile` evaluate the beam profile
+    and finite sample size numerically instead, which is the row the manual
+    marks as "calculated numerically in ANA".
+
+    :param delta: In-plane detector angle, in radian.
+    :returns: The area correction, broadcast over the input.
+    :rtype: numpy.ndarray
+    """
+    return np.abs(1.0 / np.sin(np.asarray(delta, dtype=float)))
+
+
+def lorentz_factor(mode, alpha=None, delta=None, gamma=None):
+    r"""Lorentz factor for the given measurement mode.
+
+    Dispatches to the three alternatives of the z-axis table. They are
+    alternatives, not factors to be combined: which one applies is decided by
+    how the intensity was measured.
+
+    :param str mode: :data:`ROCKING`, :data:`REFLECTIVITY_ROCKING` or
+        :data:`STATIONARY`.
+    :param alpha: Incidence angle in radian; required except for
+        :data:`STATIONARY`.
+    :param delta: In-plane detector angle in radian; required for
+        :data:`ROCKING`.
+    :param gamma: Out-of-plane detector angle in radian; required except for
+        :data:`REFLECTIVITY_ROCKING`.
+    :returns: The Lorentz factor, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If ``mode`` is unknown or a required angle is
+        missing.
+    """
+    required = {
+        ROCKING: ("delta", "alpha", "gamma"),
+        REFLECTIVITY_ROCKING: ("alpha",),
+        STATIONARY: ("gamma",),
+    }
+    if mode not in required:
+        raise ValueError(
+            f"unknown Lorentz mode {mode!r}; expected one of "
+            f"{ROCKING!r}, {REFLECTIVITY_ROCKING!r} or {STATIONARY!r}"
+        )
+    given = {"alpha": alpha, "delta": delta, "gamma": gamma}
+    missing = [name for name in required[mode] if given[name] is None]
+    if missing:
+        raise ValueError(
+            f"the {mode!r} Lorentz factor needs {', '.join(required[mode])}; "
+            f"missing {', '.join(missing)}"
+        )
+    if mode == ROCKING:
+        return lorentz_rocking_scan(delta, alpha, gamma)
+    if mode == REFLECTIVITY_ROCKING:
+        return lorentz_reflectivity_rocking_scan(alpha)
+    return lorentz_stationary(gamma)
diff --git a/orgui/datautils/xrayutils/corrections/normalization.py b/orgui/datautils/xrayutils/corrections/normalization.py
new file mode 100644
index 0000000..5181bba
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/normalization.py
@@ -0,0 +1,103 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+r"""Counting time and incident-flux normalization.
+
+Both of Vlieg's integrated-intensity expressions carry :math:`\Phi_0 T`, so a
+frame means nothing until it is divided by its counting time and by whatever
+counter the incident flux is tracked with. Two measurements are only
+comparable -- to each other, and to an absolute scale -- once both have been.
+
+This module is the policy: what a usable counter is, and what the divisor is.
+It takes **values**, not a scan object. Finding the counters in a particular
+beamline's scan is a data-format question and belongs to
+:mod:`orgui.backend.scans` and the application layer, which is why no scan
+attribute name appears here.
+"""
+
+import numpy as np
+
+__all__ = [
+    "broadcast_counter",
+    "normalization_divisor",
+]
+
+
+def broadcast_counter(value, size, name):
+    """Broadcast a scalar or per-frame counter to ``size`` values.
+
+    :param value: A scalar, or one value per frame.
+    :param int size: Number of frames.
+    :param str name: Counter name, used in the error message.
+    :returns: An array of shape ``(size,)``.
+    :rtype: numpy.ndarray
+    :raises ValueError: If the counter has neither one value nor one value
+        per frame.
+    """
+    array = np.atleast_1d(np.asarray(value, dtype=np.float64)).ravel()
+    if array.size == 1:
+        return np.full(int(size), array[0], dtype=np.float64)
+    if array.size != int(size):
+        raise ValueError(
+            f"Counter {name!r} has {array.size:d} values for {int(size):d} images"
+        )
+    return array
+
+
+def normalization_divisor(size, exposure_time=None, monitors=None):
+    """Per-frame divisor from the counting time and the monitor counters.
+
+    :param int size: Number of frames.
+    :param exposure_time: Counting time of every frame, in seconds; a scalar
+        or one value per frame. ``None`` leaves the counting time out, which
+        is what a scan that does not report one gets: the reciprocal-space
+        reconstruction records the normalization as unavailable rather than
+        failing the job, and this follows it.
+    :param monitors: Mapping of counter name to its values, a scalar or one
+        value per frame. Applied in iteration order.
+    :returns: ``(divisor, applied)`` -- an array of shape ``(size,)`` and the
+        names of the normalizations that contributed, as ``"exposure"`` and
+        ``"monitor:<name>"``.
+    :rtype: tuple
+    :raises ValueError: If a counter has a non-positive, zero or non-finite
+        value that would make the normalization undefined, or the wrong
+        number of values.
+    """
+    divisor = np.ones(int(size), dtype=np.float64)
+    applied = []
+
+    if exposure_time is not None:
+        values = broadcast_counter(exposure_time, size, "exposure_time")
+        if np.any(values <= 0) or not np.all(np.isfinite(values)):
+            raise ValueError("Exposure time must be finite and positive")
+        divisor *= values
+        applied.append("exposure")
+
+    for name, value in (monitors or {}).items():
+        values = broadcast_counter(value, size, name)
+        if np.any(values == 0) or not np.all(np.isfinite(values)):
+            raise ValueError(f"Monitor {name} must be finite and nonzero")
+        divisor *= values
+        applied.append(f"monitor:{name}")
+
+    return divisor, applied
diff --git a/orgui/datautils/xrayutils/corrections/roi.py b/orgui/datautils/xrayutils/corrections/roi.py
new file mode 100644
index 0000000..0f96cb7
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/roi.py
@@ -0,0 +1,93 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+"""Reducing per-pixel corrections onto a summed region of interest.
+
+A region of interest is summed pixel by pixel, but its correction factors are
+reported and applied per region. This module holds the bookkeeping that
+bridges the two, and the container the applied factors are carried in.
+"""
+
+import numpy as np
+
+__all__ = [
+    "CorrectionFactors",
+    "roi_mean_correction",
+]
+
+
+class CorrectionFactors(dict):
+    """Per-image correction divisors, plus the names of what was applied.
+
+    A plain dict of ``name -> array`` with two conveniences: :attr:`applied`
+    lists the corrections that actually contributed, and :meth:`divisor`
+    multiplies a chosen subset together.
+    """
+
+    def __init__(self, factors, applied):
+        super().__init__(factors)
+        #: Names of the corrections that contributed, in application order.
+        self.applied = tuple(applied)
+
+    def divisor(self, *names):
+        """Product of the named factors, or 1.0 when none are present.
+
+        :param names: Factor names to multiply. Missing names are skipped,
+            so a caller can ask for a correction that was not enabled.
+        :rtype: numpy.ndarray or float
+        """
+        product = 1.0
+        for name in names:
+            if name in self:
+                product = product * self[name]
+        return product
+
+
+def roi_mean_correction(correction_sum, pixel_count):
+    """Mean per-pixel correction over one region of interest.
+
+    The ROI summing accumulates the correction array over the same pixels it
+    sums the counts over, giving ``correction_sum`` and the number of valid
+    pixels ``pixel_count``. An ROI-summed intensity is corrected by the
+    *mean* of the correction across those pixels.
+
+    The nominal ROI area must not enter here: the integrated intensity is
+    already rescaled from the valid pixels to the nominal ROI area when the
+    background is subtracted. Multiplying by the area a second time scaled
+    every corrected intensity by the size of its ROI, and because the
+    projected ROI size varies over the detector, two measurements of one rod
+    taken on different parts of it were scaled apart.
+
+    :param correction_sum: Summed correction array over the ROI.
+    :param pixel_count: Number of valid pixels contributing to that sum.
+    :returns: The mean correction, and 0 where no pixel was valid.
+    :rtype: numpy.ndarray
+    """
+    correction_sum = np.asarray(correction_sum, dtype=np.float64)
+    pixel_count = np.asarray(pixel_count, dtype=np.float64)
+    return np.divide(
+        correction_sum,
+        pixel_count,
+        out=np.zeros_like(correction_sum),
+        where=pixel_count > 0,
+    )
diff --git a/orgui/datautils/xrayutils/geometrycorrections.py b/orgui/datautils/xrayutils/geometrycorrections.py
index c59b53c..47df40c 100644
--- a/orgui/datautils/xrayutils/geometrycorrections.py
+++ b/orgui/datautils/xrayutils/geometrycorrections.py
@@ -21,63 +21,28 @@
 # THE SOFTWARE.
 #
 # ###########################################################################*/
-r"""Geometrical correction factors of the z-axis diffractometer.
-
-orGUI applies the correction factors tabulated for the **z-axis geometry** in
-Appendix A of the ANA/ROD manual (E. Vlieg, *ANA -- program for the analysis
-of surface X-ray diffraction data*), which reproduces
-E. Vlieg, *J. Appl. Cryst.* **30** (1997) 532. The z-axis, 5-circle and
-6-circle geometries are special cases of one another; only the z-axis column
-is implemented here, and it is the one orGUI's angle convention matches.
-
-Angles follow :mod:`orgui.datautils.xrayutils.HKLVlieg`:
-
-``alpha``
-    incidence angle of the beam on the surface, in radian. This is the ``mu``
-    circle of the diffractometer, and the angle the footprint corrections of
-    :mod:`orgui.datautils.xrayutils.beamprofile` depend on.
-``delta``
-    in-plane detector angle, in radian.
-``gamma``
-    out-of-plane detector angle, in radian. In the z-axis geometry this is
-    the exit angle of the diffracted beam from the surface.
-
-The table entries used are, verbatim from the manual:
-
-=========================================  ================================
-Lorentz factor rocking scan                :math:`1/(\sin\delta\,
-                                           \cos\alpha\,\cos\gamma)`
-Lorentz factor stationary mode             :math:`1/\sin\gamma`
-Lorentz factor reflectivity rocking scan   :math:`1/\sin 2\alpha`
-Rod interception (rocking scans only)      :math:`\cos\gamma`
-Area correction (ignoring footprint and    :math:`1/\sin\delta`
-sample size)
-Beam profile and finite sample size        calculated numerically, see
-                                           :mod:`~.beamprofile`
-=========================================  ================================
-
-For rocking scans, the tabulated Lorentz factor and rod interception are
-divided out of the integrated intensity:
-
-.. math:: F^2_{hkl} = \frac{I}{L \cdot C_\mathrm{rod}}
-
-The three Lorentz factors are alternatives, selected by how the intensity was
-measured, not factors to be combined. Vlieg's stationary expression has no
-rod-interception factor:
-
-* a rocking scan about the sample rotation (``th``/``omega``) uses the
-  rocking-scan factor,
-* a rocking scan about the incidence angle (``mu``), which is how a
-  reflectivity curve is measured, uses the reflectivity factor,
-* a scan with the sample stationary, integrated across the rod on an area
-  detector, uses the stationary factor alone.
-
-The area correction :math:`1/\sin\delta` is listed for completeness and is
-**not** applied by orGUI; the numerically evaluated beam-profile and finite
-sample-size corrections of :mod:`~.beamprofile` are used instead.
+"""Backwards-compatible alias of :mod:`orgui.datautils.xrayutils.corrections.geometry`.
+
+The z-axis geometrical corrections moved into the
+:mod:`orgui.datautils.xrayutils.corrections` package, which collects every
+factor between detector counts and a structure factor. This module was
+released under its own name, so it stays importable and re-exports the same
+objects. New code should import from
+:mod:`orgui.datautils.xrayutils.corrections.geometry`.
 """
 
-import numpy as np
+from .corrections.geometry import (  # noqa: F401
+    AREA,
+    REFLECTIVITY_ROCKING,
+    ROCKING,
+    STATIONARY,
+    area_correction,
+    lorentz_factor,
+    lorentz_reflectivity_rocking_scan,
+    lorentz_rocking_scan,
+    lorentz_stationary,
+    rod_interception,
+)
 
 __all__ = [
     "AREA",
@@ -91,129 +56,3 @@
     "lorentz_stationary",
     "rod_interception",
 ]
-
-#: Lorentz factor of a rocking scan about the sample rotation.
-ROCKING = "rocking"
-
-#: Lorentz factor of a rocking scan about the incidence angle.
-REFLECTIVITY_ROCKING = "reflectivity_rocking"
-
-#: Lorentz factor of a scan measured with the sample stationary.
-STATIONARY = "stationary"
-
-#: Identifier of the area correction, for provenance strings.
-AREA = "area"
-
-
-def lorentz_rocking_scan(delta, alpha, gamma):
-    r"""Lorentz factor of a rocking scan about the sample rotation.
-
-    :math:`L = 1/(\sin\delta\,\cos\alpha\,\cos\gamma)`, the z-axis
-    "Lorentz factor rocking scan" entry. The absolute value is taken so that
-    integrated intensities stay positive whichever way the scan runs.
-
-    :param delta: In-plane detector angle, in radian.
-    :param alpha: Incidence angle, in radian.
-    :param gamma: Out-of-plane detector angle, in radian.
-    :returns: The Lorentz factor, broadcast over the inputs.
-    :rtype: numpy.ndarray
-    """
-    return np.abs(1.0 / (np.sin(delta) * np.cos(alpha) * np.cos(gamma)))
-
-
-def lorentz_reflectivity_rocking_scan(alpha):
-    r"""Lorentz factor of a reflectivity scan rocked in the incidence angle.
-
-    :math:`L = 1/\sin 2\alpha`, the z-axis "Lorentz factor reflectivity
-    rocking scan" entry.
-
-    :param alpha: Incidence angle, in radian.
-    :returns: The Lorentz factor, broadcast over the input.
-    :rtype: numpy.ndarray
-    """
-    return np.abs(1.0 / np.sin(2.0 * np.asarray(alpha, dtype=float)))
-
-
-def lorentz_stationary(gamma):
-    r"""Lorentz factor of a measurement with the sample stationary.
-
-    :math:`L = 1/\sin\gamma`, the z-axis "Lorentz factor stationary mode"
-    entry. In this geometry :math:`\gamma` is the exit angle of the
-    diffracted beam from the surface, so the factor diverges as the rod
-    approaches the surface plane, where a stationary measurement carries no
-    information about the rod profile.
-
-    :param gamma: Out-of-plane detector angle, in radian.
-    :returns: The Lorentz factor, broadcast over the input.
-    :rtype: numpy.ndarray
-    """
-    return np.abs(1.0 / np.sin(np.asarray(gamma, dtype=float)))
-
-
-def rod_interception(gamma):
-    r"""Rocking-scan rod interception factor, :math:`\cos\gamma`.
-
-    :param gamma: Out-of-plane detector angle, in radian.
-    :returns: The rod interception factor, broadcast over the input.
-    :rtype: numpy.ndarray
-    """
-    return np.cos(np.asarray(gamma, dtype=float))
-
-
-def area_correction(delta):
-    r"""Area correction ignoring footprint and sample size, :math:`1/\sin\delta`.
-
-    Listed in the manual for completeness. orGUI does not apply it: the
-    footprint corrections of :mod:`~.beamprofile` evaluate the beam profile
-    and finite sample size numerically instead, which is the row the manual
-    marks as "calculated numerically in ANA".
-
-    :param delta: In-plane detector angle, in radian.
-    :returns: The area correction, broadcast over the input.
-    :rtype: numpy.ndarray
-    """
-    return np.abs(1.0 / np.sin(np.asarray(delta, dtype=float)))
-
-
-def lorentz_factor(mode, alpha=None, delta=None, gamma=None):
-    r"""Lorentz factor for the given measurement mode.
-
-    Dispatches to the three alternatives of the z-axis table. They are
-    alternatives, not factors to be combined: which one applies is decided by
-    how the intensity was measured.
-
-    :param str mode: :data:`ROCKING`, :data:`REFLECTIVITY_ROCKING` or
-        :data:`STATIONARY`.
-    :param alpha: Incidence angle in radian; required except for
-        :data:`STATIONARY`.
-    :param delta: In-plane detector angle in radian; required for
-        :data:`ROCKING`.
-    :param gamma: Out-of-plane detector angle in radian; required except for
-        :data:`REFLECTIVITY_ROCKING`.
-    :returns: The Lorentz factor, broadcast over the inputs.
-    :rtype: numpy.ndarray
-    :raises ValueError: If ``mode`` is unknown or a required angle is
-        missing.
-    """
-    required = {
-        ROCKING: ("delta", "alpha", "gamma"),
-        REFLECTIVITY_ROCKING: ("alpha",),
-        STATIONARY: ("gamma",),
-    }
-    if mode not in required:
-        raise ValueError(
-            f"unknown Lorentz mode {mode!r}; expected one of "
-            f"{ROCKING!r}, {REFLECTIVITY_ROCKING!r} or {STATIONARY!r}"
-        )
-    given = {"alpha": alpha, "delta": delta, "gamma": gamma}
-    missing = [name for name in required[mode] if given[name] is None]
-    if missing:
-        raise ValueError(
-            f"the {mode!r} Lorentz factor needs {', '.join(required[mode])}; "
-            f"missing {', '.join(missing)}"
-        )
-    if mode == ROCKING:
-        return lorentz_rocking_scan(delta, alpha, gamma)
-    if mode == REFLECTIVITY_ROCKING:
-        return lorentz_reflectivity_rocking_scan(alpha)
-    return lorentz_stationary(gamma)
diff --git a/orgui/datautils/xrayutils/test/test_beamprofile.py b/orgui/datautils/xrayutils/test/test_corrections_beamprofile.py
similarity index 98%
rename from orgui/datautils/xrayutils/test/test_beamprofile.py
rename to orgui/datautils/xrayutils/test/test_corrections_beamprofile.py
index 069b281..3fc06ba 100644
--- a/orgui/datautils/xrayutils/test/test_beamprofile.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_beamprofile.py
@@ -1,14 +1,14 @@
 """Regression tests for the incident-beam footprint corrections.
 
 These tests pin the two related quantities defined in
-:mod:`orgui.datautils.xrayutils.beamprofile`: ``C_flux_on_sample`` is the
+:mod:`orgui.datautils.xrayutils.corrections.beamprofile`: ``C_flux_on_sample`` is the
 diagnostic beam/sample overlap, and ``C_illum_area`` is the numerical active
 surface-area divisor that already contains that overlap.
 
 The central requirement is that the numerical
-:class:`~orgui.datautils.xrayutils.beamprofile.MeasuredBeamProfile`
+:class:`~orgui.datautils.xrayutils.corrections.beamprofile.MeasuredBeamProfile`
 evaluates the *same* definitions as the closed-form
-:class:`~orgui.datautils.xrayutils.beamprofile.GaussianBeamProfile` orGUI
+:class:`~orgui.datautils.xrayutils.corrections.beamprofile.GaussianBeamProfile` orGUI
 used before it existed: feeding a sampled Gaussian to the numerical path
 must reproduce the analytical corrections, so switching an existing
 Gaussian analysis to the numerical path changes nothing, and any difference
@@ -20,7 +20,7 @@
 import pytest
 from scipy import stats
 
-from orgui.datautils.xrayutils.beamprofile import (
+from orgui.datautils.xrayutils.corrections.beamprofile import (
     DistributionBeamProfile,
     GaussianBeamProfile,
     MeasuredBeamProfile,
diff --git a/orgui/datautils/xrayutils/test/test_geometrycorrections.py b/orgui/datautils/xrayutils/test/test_corrections_geometry.py
similarity index 96%
rename from orgui/datautils/xrayutils/test/test_geometrycorrections.py
rename to orgui/datautils/xrayutils/test/test_corrections_geometry.py
index a711bc8..66781a5 100644
--- a/orgui/datautils/xrayutils/test/test_geometrycorrections.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_geometry.py
@@ -3,14 +3,14 @@
 These pin the entries of the z-axis column of Appendix A of the ANA/ROD
 manual against literal transcriptions of the formulas, and pin the two
 factors that orGUI's rocking-scan integration already applied before
-:mod:`orgui.datautils.xrayutils.geometrycorrections` existed, so that
+:mod:`orgui.datautils.xrayutils.corrections.geometry` existed, so that
 factoring them out did not change any result.
 """
 
 import numpy as np
 import pytest
 
-from orgui.datautils.xrayutils import geometrycorrections as gc
+from orgui.datautils.xrayutils.corrections import geometry as gc
 
 #: Angles in radian, spanning grazing incidence to a normal scattering angle.
 ALPHA = np.deg2rad(np.array([0.2, 0.5, 1.0, 3.0]))
diff --git a/orgui/datautils/xrayutils/test/test_corrections_package.py b/orgui/datautils/xrayutils/test/test_corrections_package.py
new file mode 100644
index 0000000..4f1aedf
--- /dev/null
+++ b/orgui/datautils/xrayutils/test/test_corrections_package.py
@@ -0,0 +1,143 @@
+"""The corrections package: shared definitions and its released aliases.
+
+:mod:`orgui.datautils.xrayutils.corrections` exists so that the rocking
+integration, the stationary integration and the reciprocal-space
+reconstruction correct their data with the same code rather than three
+copies. These tests pin the two properties that makes true: that the shared
+functions really are what the callers use, and that the module paths released
+before the package existed still work.
+"""
+
+import importlib
+
+import numpy as np
+import pytest
+
+from orgui.datautils.xrayutils import corrections
+from orgui.datautils.xrayutils.corrections import (
+    detector,
+    normalization,
+    roi,
+)
+
+
+class _Detector:
+    """Minimal stand-in for a calibrated detector."""
+
+    def __init__(self, shape=(4, 3)):
+        self._shape = shape
+
+    def solidAngleArray(self):
+        return np.linspace(0.9, 1.0, int(np.prod(self._shape))).reshape(self._shape)
+
+    def polarizationArray(self):
+        return np.linspace(0.8, 1.0, int(np.prod(self._shape))).reshape(self._shape)
+
+
+def test_the_package_exposes_every_correction_module():
+    """A maintainer looking for a correction factor finds them in one place."""
+    assert set(corrections.__all__) == {
+        "beamprofile",
+        "detector",
+        "geometry",
+        "normalization",
+        "roi",
+    }
+    for name in corrections.__all__:
+        assert getattr(corrections, name) is not None
+
+
+@pytest.mark.parametrize(
+    "legacy, moved",
+    [
+        (
+            "orgui.datautils.xrayutils.geometrycorrections",
+            "orgui.datautils.xrayutils.corrections.geometry",
+        ),
+        (
+            "orgui.datautils.xrayutils.beamprofile",
+            "orgui.datautils.xrayutils.corrections.beamprofile",
+        ),
+    ],
+)
+def test_released_module_paths_still_import(legacy, moved):
+    """Both names were released, so both must keep working.
+
+    Not just importable: the objects have to be the same ones, or a caller
+    holding the old path would be testing a different implementation from the
+    one the integration uses.
+    """
+    old = importlib.import_module(legacy)
+    new = importlib.import_module(moved)
+
+    assert old.__all__ == new.__all__
+    for name in old.__all__:
+        assert getattr(old, name) is getattr(new, name)
+
+
+def test_pixel_factors_is_the_reciprocal_of_the_enabled_arrays():
+    """The one definition of the per-pixel divisors.
+
+    ``None`` for nothing enabled is part of the contract: the reciprocal-space
+    reconstruction skips its multiplication entirely on that, rather than
+    walking a full detector of ones.
+    """
+    det = _Detector()
+
+    assert detector.pixel_factors(det) is None
+    np.testing.assert_allclose(
+        detector.pixel_factors(det, solid_angle=True),
+        1.0 / det.solidAngleArray(),
+        rtol=1e-12,
+    )
+    np.testing.assert_allclose(
+        detector.pixel_factors(det, polarization=True),
+        1.0 / det.polarizationArray(),
+        rtol=1e-12,
+    )
+    np.testing.assert_allclose(
+        detector.pixel_factors(det, solid_angle=True, polarization=True),
+        1.0 / (det.solidAngleArray() * det.polarizationArray()),
+        rtol=1e-12,
+    )
+
+
+def test_normalization_takes_values_not_a_scan():
+    """The physics layer never learns a beamline's counter names.
+
+    Pulling counters off a scan object is the application's job; this module
+    only knows what a usable value is.
+    """
+    divisor, applied = normalization.normalization_divisor(
+        3, exposure_time=0.5, monitors={"mon": [100.0, 200.0, 400.0]}
+    )
+
+    np.testing.assert_allclose(divisor, 0.5 * np.array([100.0, 200.0, 400.0]))
+    assert applied == ["exposure", "monitor:mon"]
+
+    none, applied = normalization.normalization_divisor(3)
+    np.testing.assert_allclose(none, np.ones(3))
+    assert applied == []
+
+    with pytest.raises(ValueError, match="finite and positive"):
+        normalization.normalization_divisor(3, exposure_time=0.0)
+    with pytest.raises(ValueError, match="finite and nonzero"):
+        normalization.normalization_divisor(3, monitors={"mon": [1.0, 0.0, 1.0]})
+    with pytest.raises(ValueError, match="has 2 values for 3 images"):
+        normalization.normalization_divisor(3, monitors={"mon": [1.0, 2.0]})
+
+
+def test_correction_factors_bundle_multiplies_the_named_subset():
+    """The container the applied factors are carried and stored in."""
+    factors = roi.CorrectionFactors(
+        {"C_norm": np.full(3, 2.0), "C_Lorentz": np.full(3, 4.0)},
+        ["normalization", "lorentz"],
+    )
+
+    np.testing.assert_allclose(factors.divisor("C_norm"), np.full(3, 2.0))
+    np.testing.assert_allclose(
+        factors.divisor("C_norm", "C_Lorentz"), np.full(3, 8.0)
+    )
+    # A correction that was not enabled is skipped, not an error.
+    np.testing.assert_allclose(factors.divisor("C_illum_area"), 1.0)
+    assert factors.applied == ("normalization", "lorentz")
diff --git a/orgui/reconstruction_job.py b/orgui/reconstruction_job.py
index 58d2094..57ca811 100644
--- a/orgui/reconstruction_job.py
+++ b/orgui/reconstruction_job.py
@@ -25,6 +25,7 @@
 from .app.database import FILTERS, config_data_from_json, config_data_to_json
 from .app.mask_config import create_pixel_repair_plan
 from .backend.scans import ScanReference
+from .datautils.xrayutils.corrections import detector as detector_corrections
 from .datautils.xrayutils.reconstruction import (
     _CHECKPOINT_BYTES_PER_ROW,
     _CheckpointRouter,
@@ -1245,23 +1246,22 @@ def _correction_pipeline(config, scan, assets, provenance):
         if correction.use_mask and "mask" in assets
         else None
     )
-    static_factor = None
-    if correction.use_solid_angle:
-        static_factor = 1.0 / np.asarray(
-            detector.solidAngleArray(), dtype=np.float64
-        )
-        provenance.setdefault("factor_uncertainty", {})[
-            "solid_angle"
-        ] = "deterministic-no-uncertainty"
-    if correction.use_polarization:
-        polarization = np.asarray(detector.polarizationArray(), dtype=np.float64)
-        if static_factor is None:
-            static_factor = 1.0 / polarization
-        else:
-            static_factor /= polarization
-        provenance.setdefault("factor_uncertainty", {})[
-            "polarization"
-        ] = "deterministic-no-uncertainty"
+    # The per-pixel factors are defined once, in the corrections package,
+    # and shared with the direct-space integrations. Only their application
+    # is special here: it is fused into the native pass below.
+    static_factor = detector_corrections.pixel_factors(
+        detector,
+        solid_angle=correction.use_solid_angle,
+        polarization=correction.use_polarization,
+    )
+    for name, enabled in (
+        ("solid_angle", correction.use_solid_angle),
+        ("polarization", correction.use_polarization),
+    ):
+        if enabled:
+            provenance.setdefault("factor_uncertainty", {})[
+                name
+            ] = "deterministic-no-uncertainty"
     if static_factor is not None:
         static_factor = np.ascontiguousarray(static_factor, dtype=np.float64)
         static_factor_squared = np.square(static_factor)

From 4193c80222cafdcf99a6450aab3ed07e7080de8d Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 9 Sep 2026 17:16:14 -0400
Subject: [PATCH 02/33] feat: reduce integrated intensities to |F_hkl|^2 on one
 scale

---
 orgui/app/integration_corrections.py          |  20 +-
 orgui/app/peak1Dintegr.py                     |  25 +-
 orgui/app/test/test_scan_mode_equivalence.py  | 328 ++++++++++
 .../xrayutils/corrections/__init__.py         |  29 +-
 .../xrayutils/corrections/activearea.py       | 190 ++++++
 .../xrayutils/corrections/measurement.py      | 605 ++++++++++++++++++
 .../test/test_corrections_activearea.py       | 129 ++++
 .../test/test_corrections_measurement.py      | 346 ++++++++++
 .../test/test_corrections_package.py          |  51 ++
 9 files changed, 1698 insertions(+), 25 deletions(-)
 create mode 100644 orgui/app/test/test_scan_mode_equivalence.py
 create mode 100644 orgui/datautils/xrayutils/corrections/activearea.py
 create mode 100644 orgui/datautils/xrayutils/corrections/measurement.py
 create mode 100644 orgui/datautils/xrayutils/test/test_corrections_activearea.py
 create mode 100644 orgui/datautils/xrayutils/test/test_corrections_measurement.py

diff --git a/orgui/app/integration_corrections.py b/orgui/app/integration_corrections.py
index dcd51b2..bd9d708 100644
--- a/orgui/app/integration_corrections.py
+++ b/orgui/app/integration_corrections.py
@@ -43,8 +43,9 @@
 ``C_illum_area``. It must not be divided out separately: the numerical active
 area already contains the same beam/sample overlap integral. Which angular
 factors a stationary measurement applies -- and that it has no
-rod-interception factor, unlike a rocking scan -- follows the z-axis table of
-:mod:`~orgui.datautils.xrayutils.corrections.geometry`.
+rod-interception factor, unlike a rocking scan -- is decided by
+:func:`~orgui.datautils.xrayutils.corrections.measurement.mode_components`,
+the one place that mapping exists.
 
 The exposure and monitor normalization mirrors the reciprocal-space
 reconstruction (:mod:`orgui.reconstruction_job`), so a stationary integration
@@ -56,7 +57,7 @@
 
 import numpy as np
 
-from ..datautils.xrayutils.corrections import geometry
+from ..datautils.xrayutils.corrections import measurement
 from ..datautils.xrayutils.corrections.normalization import (
     normalization_divisor as _divisor_from_counters,
 )
@@ -161,8 +162,9 @@ def stationary_correction_factors(
     :param delta: In-plane detector angle per image, in radian.
     :param gamma: Out-of-plane detector angle per image, in radian.
     :param bool use_lorentz: Add ``C_Lorentz`` -- the *stationary-mode*
-        factor :math:`1/\sin\gamma`, not the rocking-scan one.
-        Stationary integration has no rod-interception factor.
+        factor :math:`1/\sin\gamma`, not the rocking-scan one, as
+        :func:`~orgui.datautils.xrayutils.corrections.measurement.mode_components`
+        decides. Stationary integration has no rod-interception factor.
     :param bool use_footprint: Add the ``C_illum_area`` divisor and its
         diagnostic numerator ``C_flux_on_sample``.
     :param beam_profile: A
@@ -204,9 +206,11 @@ def stationary_correction_factors(
         applied.append("footprint")
 
     if use_lorentz:
-        factors["C_Lorentz"] = np.broadcast_to(
-            geometry.lorentz_factor(geometry.STATIONARY, gamma=gamma), alpha.shape
-        ).copy()
+        components = measurement.mode_components(
+            measurement.STATIONARY, alpha=alpha, delta=delta, gamma=gamma
+        )
+        for name, value in components.items():
+            factors[name] = np.broadcast_to(value, alpha.shape).copy()
         applied.append("lorentz")
 
     return CorrectionFactors(factors, applied)
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 61530c8..0a9ee6c 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -57,7 +57,10 @@
 from .config_data import ConfigData
 from .. import resources
 from .. import logger_utils
-from ..datautils.xrayutils.corrections import beamprofile, geometry
+from ..datautils.xrayutils.corrections import beamprofile
+from ..datautils.xrayutils.corrections import (
+    measurement as measurement_corrections,
+)
 
 import numpy as np
 from scipy import interpolate as interp
@@ -1335,21 +1338,19 @@ def integrate(self):
             # A mu scan rocks the incidence angle, which is how a
             # reflectivity curve is measured; a th scan rocks the sample.
             # The two take different Lorentz factors from the z-axis table,
-            # and neither is the stationary-scan factor.
+            # and neither is the stationary-scan factor. Which factors each
+            # mode applies is decided in one place, by mode_components.
             if curves["axisname"] == "mu":
-                C_Lor = geometry.lorentz_factor(
-                    geometry.REFLECTIVITY_ROCKING, alpha=alpha
-                )
+                mode = measurement_corrections.REFLECTIVITY_ROCKING
             elif curves["axisname"] == "th":
-                C_Lor = geometry.lorentz_factor(
-                    geometry.ROCKING,
-                    alpha=alpha,
-                    delta=delta,
-                    gamma=gamma,
-                )
+                mode = measurement_corrections.ROCKING
             else:
                 raise NotImplementedError()
-            C_rod = geometry.rod_interception(gamma)
+            components = measurement_corrections.mode_components(
+                mode, alpha=alpha, delta=delta, gamma=gamma
+            )
+            C_Lor = components["C_Lorentz"]
+            C_rod = components["C_rod"]
         else:
             C_Lor = 1.0
             C_rod = 1.0
diff --git a/orgui/app/test/test_scan_mode_equivalence.py b/orgui/app/test/test_scan_mode_equivalence.py
new file mode 100644
index 0000000..54bb086
--- /dev/null
+++ b/orgui/app/test/test_scan_mode_equivalence.py
@@ -0,0 +1,328 @@
+"""Rocking and stationary integration must give the same structure factor.
+
+`Issue #82 <https://github.com/tifuchs/orGUI/issues/82>`_: once every scaling
+factor and experimental correction is accounted for, a rocking scan and a
+stationary area-detector measurement of the same reflection must yield the
+same :math:`|F_{hkl}|^2`; only the resolution differs.
+
+These tests build simulated data for exactly that comparison. One rod with a
+known :math:`|F_{hkl}|^2(l)` is measured twice -- as a series of rocking scans
+and as a stationary *l* scan -- using
+:func:`orgui.datautils.xrayutils.corrections.measurement.integrated_intensity` as
+the forward model, i.e. Vlieg's equations 42 and 54 written out. The simulated
+counts are then reduced twice: through
+:mod:`orgui.datautils.xrayutils.corrections.measurement`, which must recover the
+input, and through the two correction paths orGUI ships today
+(:func:`orgui.app.peak1Dintegr._compute_rocking_integration` and
+:mod:`orgui.app.integration_corrections`), whose disagreement is pinned to the
+exact factor it is.
+
+Everything that is not under test is left out deliberately. The polarization
+factor and the footprint correction are absent from the simulation because
+both depend only on the incidence and detector angles: they are identical for
+the two modes at the same reflection, cancel from their ratio, and are
+divided out per pixel long before the code under test here. Background
+subtraction and error propagation are covered by ``test_peak1Dintegr.py``; a
+flat background is included only so that the real aggregation code path is
+exercised.
+
+``doc/design/ctr_structure_factor_scale.md`` records the analysis.
+"""
+
+import numpy as np
+import pytest
+
+from orgui.app import integration_corrections as ic
+from orgui.app.peak1Dintegr import _compute_rocking_integration
+from orgui.datautils.xrayutils import HKLVlieg
+from orgui.datautils.xrayutils.corrections import measurement as ii
+
+#: Fixed incidence angle of the simulated z-axis scans, in radian.
+ALPHA_IN = np.deg2rad(0.6)
+
+#: Per-frame counting time and monitor of the two simulated measurements.
+ROCKING_EXPOSURE, ROCKING_MONITOR = 0.4, 3.0
+STATIONARY_EXPOSURE, STATIONARY_MONITOR = 2.0, 7.0
+
+#: Flat background under every simulated rocking frame, in counts.
+BACKGROUND = 50.0
+
+#: Illuminated area (square meter) and flux density (photons / s / m^2).
+ACTIVE_AREA, FLUX_DENSITY = 5.73e-7, 1e16
+
+
+@pytest.fixture(scope="module")
+def rod():
+    """A (1, 0, l) rod of Pt(111) in the z-axis geometry at 17.7 keV.
+
+    :returns: ``(l, alpha, delta, gamma, f2, wavelength, unitcell_area)`` with
+        the angles in radian, ``f2`` the true :math:`|F_{hkl}|^2` in electron
+        units squared, the wavelength in Angstrom and the unit-cell area in
+        square Angstrom.
+    """
+    lattice = HKLVlieg.Lattice([2.7748, 2.7748, 6.7964], [90.0, 90.0, 120.0])
+    ub = HKLVlieg.UBCalculator(lattice, 17.7)
+    ub.defaultU_GID()
+    angles = HKLVlieg.VliegAngles(ub)
+
+    ell = np.linspace(0.4, 3.0, 12)
+    hkl = np.vstack([np.ones_like(ell), np.zeros_like(ell), ell])
+    computed = angles.anglesZmode(hkl, ALPHA_IN, fixed="in")
+    alpha, delta, gamma = computed[:, 0], computed[:, 1], computed[:, 2]
+
+    # A crystal-truncation-rod-like profile: sharp at the bulk Bragg
+    # positions, weak in between, so a scale error that varies along the rod
+    # is visible as a shape change and not only as an offset.
+    f2 = 100.0 / (np.sin(np.pi * ell / 2.0) ** 2 + 0.02)
+    return ell, alpha, delta, gamma, f2, ub.getLambda(), lattice.uc_area
+
+
+def _simulate_stationary(rod):
+    """Counts of a stationary *l* scan of the rod.
+
+    :returns: The per-frame background-subtracted counts, in the units
+        :meth:`orgui.app.orGUI.orGUI.integrateROI` hands to
+        :mod:`orgui.app.integration_corrections`.
+    """
+    _, alpha, delta, gamma, f2, wavelength, uc_area = rod
+    intensity = ii.integrated_intensity(
+        f2,
+        ii.STATIONARY,
+        gamma=gamma,
+        wavelength=wavelength,
+        unitcell_area=uc_area,
+        active_area=ACTIVE_AREA,
+        flux_density=FLUX_DENSITY,
+    )
+    return intensity * STATIONARY_EXPOSURE * STATIONARY_MONITOR
+
+
+def _simulate_rocking(rod, acceptance, axis=None, width=0.06):
+    """Per-frame rocking curves of the rod.
+
+    The rocking profile integrates to one over the rocking angle *in radian*,
+    so the trapezoidal integral of the returned curves over the axis in
+    degrees is the Vlieg integrated intensity times ``180/pi``.
+
+    :param rod: The ``rod`` fixture.
+    :param acceptance: Out-of-plane acceptance of the region of interest per
+        rod point, in radian.
+    :param axis: Rocking axis in degrees; a default symmetric axis is used
+        when omitted.
+    :param float width: Standard deviation of the rocking profile, in degrees.
+    :returns: ``(axis, curves)`` with ``curves`` of shape ``(n_l, n_axis)``.
+    """
+    _, alpha, delta, gamma, f2, wavelength, uc_area = rod
+    if axis is None:
+        axis = np.linspace(-1.0, 1.0, 801)
+    intensity = ii.integrated_intensity(
+        f2,
+        ii.ROCKING,
+        alpha=alpha,
+        delta=delta,
+        gamma=gamma,
+        detector_acceptance=acceptance,
+        wavelength=wavelength,
+        unitcell_area=uc_area,
+        active_area=ACTIVE_AREA,
+        flux_density=FLUX_DENSITY,
+    )
+    profile = np.exp(-0.5 * (axis / width) ** 2) / (width * np.sqrt(2.0 * np.pi))
+    profile = profile * np.rad2deg(1.0)  # unit integral in radian
+    counts = intensity * ROCKING_EXPOSURE * ROCKING_MONITOR
+    return axis, counts[:, None] * profile[None, :] + BACKGROUND
+
+
+def _roi_info(size):
+    """Signal and background windows, in degrees, for every rod point.
+
+    The background window sits ten standard deviations out, where the
+    simulated profile has died away, so ``croibg`` is the signal alone.
+    """
+    return {
+        "sig_1": {"from": np.full(size, -0.5), "to": np.full(size, 0.5)},
+        "bg_1": {"from": np.full(size, -1.0), "to": np.full(size, -0.6)},
+    }
+
+
+def _orgui_rocking_f2(rod, acceptance):
+    """``F2_hkl`` as :mod:`orgui.app.peak1Dintegr` computes it today."""
+    ell, alpha, delta, gamma, _, _, _ = rod
+    axis, curves = _simulate_rocking(rod, acceptance)
+    shape = curves.shape
+    lorentz = np.broadcast_to(
+        (1.0 / (np.sin(delta) * np.cos(alpha) * np.cos(gamma)))[:, None], shape
+    )
+    rod_interception = np.broadcast_to(np.cos(gamma)[:, None], shape)
+    result = _compute_rocking_integration(
+        ell,
+        axis,
+        curves,
+        np.sqrt(np.abs(curves)),
+        _roi_info(ell.size),
+        {},
+        True,
+        False,
+        C_Lor=lorentz,
+        C_rod=rod_interception,
+    )
+    return result["F2_hkl"]
+
+
+def _orgui_stationary_f2(rod):
+    """``F2_hkl`` as :mod:`orgui.app.integration_corrections` computes it."""
+    ell, alpha, delta, gamma, _, _, _ = rod
+    counts = _simulate_stationary(rod)
+    factors = ic.stationary_correction_factors(
+        alpha,
+        delta,
+        gamma,
+        use_lorentz=True,
+        normalization=np.full(
+            ell.size, STATIONARY_EXPOSURE * STATIONARY_MONITOR
+        ),
+    )
+    intensity, errors = ic.apply_stationary_corrections(
+        counts, np.sqrt(counts), factors
+    )
+    return ic.structure_factor(intensity, errors, factors)[0]
+
+
+def test_the_unified_reduction_recovers_one_structure_factor(rod):
+    """Both simulated measurements reduce to the input ``|F|^2``.
+
+    This is what issue #82 asks for, and it holds with the acceptance of the
+    region of interest deliberately different at every point of the rod and
+    the two measurements taken with different counting times and monitors.
+    """
+    ell, alpha, delta, gamma, f2, wavelength, uc_area = rod
+    acceptance = np.deg2rad(0.35) * np.linspace(0.7, 1.6, ell.size)
+    scale = dict(
+        wavelength=wavelength,
+        unitcell_area=uc_area,
+        active_area=ACTIVE_AREA,
+        flux_density=FLUX_DENSITY,
+    )
+
+    axis, curves = _simulate_rocking(rod, acceptance)
+    result = _compute_rocking_integration(
+        ell,
+        axis,
+        curves - BACKGROUND,
+        np.sqrt(np.abs(curves)),
+        _roi_info(ell.size),
+        {},
+        False,
+        False,
+    )
+    f2_rocking = ii.structure_factor_squared(
+        ii.normalized_intensity(
+            result["croibg"],
+            exposure_time=ROCKING_EXPOSURE,
+            monitor=ROCKING_MONITOR,
+            angle_unit="deg",
+        ),
+        ii.ROCKING,
+        alpha=alpha,
+        delta=delta,
+        gamma=gamma,
+        detector_acceptance=acceptance,
+        **scale,
+    )
+    f2_stationary = ii.structure_factor_squared(
+        ii.normalized_intensity(
+            _simulate_stationary(rod),
+            exposure_time=STATIONARY_EXPOSURE,
+            monitor=STATIONARY_MONITOR,
+        ),
+        ii.STATIONARY,
+        gamma=gamma,
+        **scale,
+    )
+
+    np.testing.assert_allclose(f2_stationary, f2, rtol=1e-12)
+    np.testing.assert_allclose(f2_rocking, f2, rtol=1e-6)
+    np.testing.assert_allclose(f2_rocking, f2_stationary, rtol=1e-6)
+
+
+def test_the_stationary_path_recovers_the_rod_up_to_one_constant(rod):
+    """orGUI's stationary path already has the right shape.
+
+    Its Lorentz factor is the published one and its normalization divides by
+    the counting time and the monitor, so what it produces differs from the
+    true ``|F|^2`` by a single number -- the absolute scale of issue #15 --
+    and not by anything that varies along the rod.
+    """
+    f2 = rod[4]
+
+    ratio = _orgui_stationary_f2(rod) / f2
+
+    np.testing.assert_allclose(ratio, ratio[0], rtol=1e-12)
+
+
+def test_rocking_and_stationary_paths_differ_by_the_missing_normalizations(rod):
+    """The gap between the two paths, pinned to the factor it is.
+
+    With the acceptance held constant the two paths differ by exactly
+    ``exposure * monitor * Delta_gamma_in_degrees``: the rocking path applies
+    neither the exposure/monitor normalization nor the out-of-plane
+    acceptance, and integrates the rocking angle in degrees rather than
+    radian. The degree-to-radian factor and the acceptance combine into the
+    acceptance expressed in degrees.
+
+    This test characterizes today's behavior. It must be updated -- to a
+    plain equality -- when the rocking path adopts the unified reduction.
+    """
+    ell = rod[0]
+    acceptance = np.full(ell.size, np.deg2rad(0.35))
+
+    ratio = _orgui_rocking_f2(rod, acceptance) / _orgui_stationary_f2(rod)
+    expected = ROCKING_EXPOSURE * ROCKING_MONITOR * np.rad2deg(acceptance)
+
+    np.testing.assert_allclose(ratio, expected, rtol=1e-6)
+
+
+def test_a_resized_region_of_interest_distorts_the_rocking_rod(rod):
+    """The missing acceptance is not merely an overall scale factor.
+
+    :func:`orgui.app.ROIutils.calc_corrections` sizes regions of interest
+    from the projected sample size and the parallax at each detector
+    position, so their out-of-plane acceptance changes along a scan. Without
+    the ``1/Delta_gamma`` divisor that change is carried straight into
+    ``F2_hkl``, so the same rod measured with a resized region of interest
+    comes out with a different *shape*, not just a different scale.
+    """
+    ell = rod[0]
+    fixed = np.full(ell.size, np.deg2rad(0.35))
+    resized = np.deg2rad(0.35) * np.linspace(0.7, 1.6, ell.size)
+
+    with_fixed = _orgui_rocking_f2(rod, fixed)
+    with_resized = _orgui_rocking_f2(rod, resized)
+
+    carried = with_resized / with_fixed
+    shape_change = carried / carried[0]
+    np.testing.assert_allclose(
+        shape_change, np.linspace(0.7, 1.6, ell.size) / 0.7, rtol=1e-6
+    )
+    assert shape_change.max() / shape_change.min() > 2.0
+
+
+def test_the_stationary_path_assumes_a_slit_independent_active_area(rod):
+    """What orGUI's missing area correction implies about the setup.
+
+    orGUI divides out the numerical beam-profile factor but not Vlieg's
+    :math:`C_\\mathrm{area} = 1/(\\sin\\delta\\cos(\\alpha-\\beta_
+    \\mathrm{in}))`. That is right for an area detector with open post-sample
+    slits, where the illuminated footprint and not the slits defines the
+    active area -- the simulations above, which come out exact. It is wrong
+    for a slit-limited setup, where the active area varies with
+    :math:`\\delta` along the rod and the omission shows up as a
+    rod-dependent shape error.
+    """
+    _, alpha, delta, gamma, f2, _, _ = rod
+    slit_limited = 1.0 / (np.sin(delta) * np.cos(alpha - alpha))
+
+    ratio = _orgui_stationary_f2(rod) * slit_limited / f2
+
+    spread = ratio.max() / ratio.min() - 1.0
+    assert spread > 1e-3, "delta must vary enough along the rod to see this"
diff --git a/orgui/datautils/xrayutils/corrections/__init__.py b/orgui/datautils/xrayutils/corrections/__init__.py
index 4e6e6b6..f530ffd 100644
--- a/orgui/datautils/xrayutils/corrections/__init__.py
+++ b/orgui/datautils/xrayutils/corrections/__init__.py
@@ -23,11 +23,20 @@
 # ###########################################################################*/
 r"""Everything that turns detector counts into a structure factor.
 
-One home for the correction factors of E. Vlieg, *J. Appl. Cryst.* **30**
-(1997) 532, in the two-dimensional-detector form of J. Drnec *et al.*,
-*J. Appl. Cryst.* **47** (2014) 365, so that a rocking scan, a stationary
-area-detector measurement and a reciprocal-space reconstruction of the same
-sample are corrected by the same code rather than by three copies of it.
+One home for the correction factors of
+
+.. math::
+
+    I = \Phi_0 \frac{r_e^2 A \lambda^2}{A_u^2}\,
+        |F_{hkl}|^2 \, P \, \eta \, C_\mathrm{det}
+
+so that a rocking scan, a stationary area-detector measurement, a
+reflectivity curve and a reciprocal-space reconstruction of the same sample
+are corrected by the same code and land on the same scale. The measurement
+equation is E. Vlieg, *J. Appl. Cryst.* **30** (1997) 532, in the
+two-dimensional-detector form of J. Drnec *et al.*,
+*J. Appl. Cryst.* **47** (2014) 365; :mod:`~.measurement` documents it in
+full.
 
 The split between the modules is by *what a factor depends on*, which is also
 what makes each of them testable on its own:
@@ -38,12 +47,18 @@
 :mod:`~.beamprofile`
     The vertical profile of the incident beam and its integrals over a
     finite sample.
+:mod:`~.activearea`
+    The illuminated active surface area :math:`A`, in square meter, in both
+    the slit-limited and the beam-limited case.
 :mod:`~.detector`
     Per-pixel factors of a detector image: solid angle and polarization.
 :mod:`~.normalization`
     Counting time and monitor.
 :mod:`~.roi`
     Reducing per-pixel factors onto a summed region of interest.
+:mod:`~.measurement`
+    Which of the above apply to which kind of scan, and the reduction to
+    :math:`|F_{hkl}|^2` and to absolute reflectivity.
 
 Everything here is physics: arrays and scalars in, arrays out. Nothing in
 this package reads a scan object, a configuration file or a GUI widget.
@@ -57,17 +72,21 @@
 """
 
 from . import (  # noqa: F401
+    activearea,
     beamprofile,
     detector,
     geometry,
+    measurement,
     normalization,
     roi,
 )
 
 __all__ = [
+    "activearea",
     "beamprofile",
     "detector",
     "geometry",
+    "measurement",
     "normalization",
     "roi",
 ]
diff --git a/orgui/datautils/xrayutils/corrections/activearea.py b/orgui/datautils/xrayutils/corrections/activearea.py
new file mode 100644
index 0000000..70664df
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/activearea.py
@@ -0,0 +1,190 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+r"""The illuminated active surface area :math:`A`, in square meter.
+
+:math:`A` is the surface area that actually contributes to the measured
+counts. It multiplies the integrated intensity of every scan mode -- Vlieg
+equation 42 for a rocking scan, 54 for a stationary one, 62 for reflectivity
+-- so it sets the absolute scale of :math:`|F_{hkl}|^2` but cancels from the
+ratio of two modes measured at the same incidence angle.
+
+Which of two limits applies is an experimental question, not a preference:
+
+**Slit limited.** Post-sample slits narrower than the footprint cut the
+visible length along the surface, and the area is Vlieg equation 37,
+:math:`A = s_1 s_2 / (\sin\delta\,\cos(\alpha-\beta_\mathrm{in}))`. It varies
+with the in-plane detector angle and therefore along a rod.
+:func:`slit_limited_area`.
+
+**Beam and sample limited.** With an area detector and open slits -- orGUI's
+usual configuration -- the whole illuminated footprint is seen and the area
+is set by the beam profile and the sample, with no :math:`\delta` dependence.
+:func:`beam_limited_area`.
+
+Only the second is two-dimensional in the sense that matters: the beam's
+*vertical* extent is what the projection onto the surface stretches, and it
+is described in full by a
+:class:`~orgui.datautils.xrayutils.corrections.beamprofile.BeamProfile`. The
+horizontal extent is not projected and enters as a plain width, which is the
+one number needed to turn the dimensionless factor a beam profile returns
+into an absolute area:
+
+.. math::
+
+    A(\alpha) = w \, L \, C_\mathrm{illum}(\alpha, L)
+
+with :math:`w` the horizontal beam width, :math:`L` the sample length along
+the beam and :math:`C_\mathrm{illum}` the profile's
+:meth:`~.beamprofile.BeamProfile.illuminated_area_fraction`, which is already
+the mean of :math:`p(z)/p_\mathrm{max}` over the projected sample footprint.
+
+.. note::
+
+    The familiar closed form :math:`A = w \min(L, h/\sin\alpha)` is exactly
+    this expression for a
+    :func:`~.beamprofile.top_hat_profile` of full width :math:`h`, and only
+    for that profile. A Gaussian of the same width differs from it by up to
+    19 % at grazing incidence and by 6.5 % once the beam is fully on the
+    sample, so the closed form is not a general shortcut and this module does
+    not offer one.
+"""
+
+import numpy as np
+
+from . import geometry
+
+__all__ = [
+    "beam_limited_area",
+    "footprint_length",
+    "slit_limited_area",
+]
+
+
+def footprint_length(alpha, beam_height, sample_length):
+    r"""Illuminated length along the beam, in meter.
+
+    :math:`\min(L, h/\sin\alpha)`, the geometric footprint of a beam of
+    uniform vertical size. It is the length :func:`beam_limited_area` would
+    use for a top-hat beam, and is kept as a separate function because it is
+    the quantity to report when describing an experiment, not because
+    :func:`beam_limited_area` needs it.
+
+    :param alpha: Incidence angle, in radian.
+    :param float beam_height: Vertical beam size, in meter.
+    :param float sample_length: Sample length along the beam, in meter.
+    :returns: The footprint length in meter, broadcast over ``alpha``.
+    :rtype: numpy.ndarray
+    :raises ValueError: If a size is not positive.
+    """
+    alpha = np.asarray(alpha, dtype=np.float64)
+    for name, value in (
+        ("beam_height", beam_height),
+        ("sample_length", sample_length),
+    ):
+        if not float(value) > 0:
+            raise ValueError(f"{name} must be positive, in meter, got {value!r}")
+    sin_alpha = np.sin(alpha)
+    projected = np.divide(
+        float(beam_height),
+        sin_alpha,
+        out=np.full(sin_alpha.shape, np.inf),
+        where=sin_alpha > 0,
+    )
+    return np.minimum(float(sample_length), projected)
+
+
+def beam_limited_area(alpha, beam_width, sample_length, profile):
+    r"""Active area of an open-slit measurement, in square meter.
+
+    :math:`A = w\,L\,C_\mathrm{illum}(\alpha, L)`. The vertical direction
+    comes from the beam profile, which already integrates :math:`p(z)` over
+    the projected sample and normalizes to the peak density; the horizontal
+    direction is the plain beam width, since it is not projected.
+
+    :param alpha: Incidence angle, in radian.
+    :param float beam_width: Horizontal beam size, in meter.
+    :param float sample_length: Sample length along the beam, in meter.
+    :param profile: A
+        :class:`~.beamprofile.BeamProfile` describing the vertical beam
+        profile.
+    :returns: The active area in square meter, broadcast over ``alpha``.
+    :rtype: numpy.ndarray
+    :raises ValueError: If a size is not positive, or no profile is given.
+    """
+    if profile is None:
+        raise ValueError(
+            "the beam-limited area needs a beam profile; a uniform beam of "
+            "full width h is beamprofile.top_hat_profile(h)"
+        )
+    for name, value in (
+        ("beam_width", beam_width),
+        ("sample_length", sample_length),
+    ):
+        if not float(value) > 0:
+            raise ValueError(f"{name} must be positive, in meter, got {value!r}")
+    fraction = profile.illuminated_area_fraction(alpha, float(sample_length))
+    return float(beam_width) * float(sample_length) * np.asarray(fraction)
+
+
+def slit_limited_area(delta, slit_width, slit_height, alpha=None, beta_in=None):
+    r"""Active area seen through post-sample slits, in square meter.
+
+    Vlieg equation 37 with equation 38,
+    :math:`A = s_1 s_2 / (\sin\delta \cos(\alpha - \beta_\mathrm{in}))`. The
+    :math:`1/\sin\delta` is :func:`~.geometry.area_correction`, the row the
+    ANA/ROD z-axis table lists; the remaining cosine is one in the z-axis
+    mode, where the incidence angle is the angle to the surface
+    (:math:`\alpha = \beta_\mathrm{in}`), which is why the table omits it.
+
+    :param delta: In-plane detector angle, in radian.
+    :param float slit_width: Beam size across the scattering plane
+        (Vlieg's :math:`s_1`), in meter.
+    :param float slit_height: Detector slit opening projected onto the
+        surface (Vlieg's :math:`s_2`), in meter.
+    :param alpha: Incidence angle, in radian. Only needed together with
+        ``beta_in``.
+    :param beta_in: Angle of the incident beam to the surface, in radian.
+        ``None`` means the z-axis mode, ``beta_in = alpha``, and the cosine
+        drops out.
+    :returns: The active area in square meter, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If a slit size is not positive, or ``beta_in`` is
+        given without ``alpha``.
+    """
+    for name, value in (
+        ("slit_width", slit_width),
+        ("slit_height", slit_height),
+    ):
+        if not float(value) > 0:
+            raise ValueError(f"{name} must be positive, in meter, got {value!r}")
+    tilt = 1.0
+    if beta_in is not None:
+        if alpha is None:
+            raise ValueError("beta_in needs alpha to form alpha - beta_in")
+        tilt = np.cos(
+            np.asarray(alpha, dtype=np.float64)
+            - np.asarray(beta_in, dtype=np.float64)
+        )
+    projected = geometry.area_correction(delta) / tilt
+    return float(slit_width) * float(slit_height) * projected
diff --git a/orgui/datautils/xrayutils/corrections/measurement.py b/orgui/datautils/xrayutils/corrections/measurement.py
new file mode 100644
index 0000000..c07628d
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/measurement.py
@@ -0,0 +1,605 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+r"""Integrated intensities and structure factors on one common scale.
+
+E. Vlieg, *J. Appl. Cryst.* **30** (1997) 532 writes the integrated intensity
+of a surface reflection as one prefactor times :math:`|F_{hkl}|^2` times a
+product of correction factors. Rocking scans, stationary area-detector
+measurements and reflectivity differ only in *which* correction factors
+appear. Once every factor is divided out, the three modes land on the same
+scale and can be refined as a single data set -- the point of Vlieg's section
+5 and of section 3.4 of J. Drnec *et al.*, *J. Appl. Cryst.* **47** (2014)
+365.
+
+This module implements that reduction as pure functions, in one place, so
+that a rocking scan and a stationary scan of the same rod are guaranteed to
+be normalized identically. It is deliberately independent of how the counts
+were obtained: :mod:`orgui.app.peak1Dintegr` and :mod:`orgui.app.orGUI`
+produce the integrated counts, this module turns them into
+:math:`|F_{hkl}|^2`.
+
+The master equation
+-------------------
+
+With :math:`I` the *normalized* integrated intensity of
+:func:`normalized_intensity` -- counts per second per monitor unit, already
+divided by the polarization factor :math:`P` --
+
+.. math::
+
+    I = \Phi_0 \frac{r_e^2 A \lambda^2}{A_u^2}\,
+        |F_{hkl}|^2 \, \eta \, C_\mathrm{det}
+
+where
+
+``Phi_0``
+    incident flux *density*, photons per second and square meter, so that
+    :math:`\Phi_0 A_0` is the total flux on the sample.
+``r_e``
+    classical electron radius, :data:`CLASSICAL_ELECTRON_RADIUS`, in meter.
+``A``
+    illuminated *active* surface area, in square meter. This is Vlieg's
+    :math:`A = A_0 C_\mathrm{area} C_\mathrm{beam}` (equation 41): the beam
+    cross-section corrected for the projection onto the surface and for the
+    beam profile over a finite sample. See :ref:`active-area` below.
+``lambda``
+    wavelength, in Angstrom.
+``A_u``
+    area of the surface unit cell, in square Angstrom
+    (:attr:`orgui.datautils.xrayutils.HKLVlieg.Lattice.uc_area`).
+``eta``
+    the angle-dependent factor of the measurement mode,
+    :func:`angular_factor`.
+``C_det``
+    in-plane detector acceptance (Vlieg equations 24, 27, 28); ``1`` when the
+    region of interest is wide enough to contain the whole in-plane peak
+    profile. Not modelled here -- pass a measured or fitted value.
+
+:math:`|F_{hkl}|^2` then comes out in electron units squared, the same scale
+a :class:`~orgui.datautils.xrayutils.CTRcalc.SXRDCrystal` calculates in.
+
+The mode-dependent factor
+-------------------------
+
+==============================  ============================================
+Rocking scan (``th``/omega)     :math:`\eta = L_\varphi\, C_\mathrm{rod}\,
+                                \Delta\gamma`
+Reflectivity rocking (``mu``)   :math:`\eta = L_r\, C_\mathrm{rod}\,
+                                \Delta\gamma`
+Stationary area detector        :math:`\eta = L_s`
+Specular reflectivity           :math:`\eta = L_s` with
+                                :math:`\gamma = \alpha`
+==============================  ============================================
+
+with :math:`L_\varphi`, :math:`L_r`, :math:`L_s` and :math:`C_\mathrm{rod}`
+the z-axis entries implemented in :mod:`~.geometry`. This table is the single
+place the choice is made: :func:`mode_components` names the factors a mode
+applies, and both the rocking and the stationary integration ask it rather
+than selecting a Lorentz factor of their own.
+
+Two factors of the rocking expression are easy to lose and are the reason a
+rocking scan and a stationary scan of the same rod do not otherwise agree:
+
+* the rocking angle must be integrated in **radian**. Integrating in degrees
+  scales every rocking structure factor by :math:`180/\pi`.
+* :math:`\Delta\gamma`, the **out-of-plane angular acceptance** of the
+  region of interest, in radian. A rocking scan intercepts a slice of rod
+  whose length is proportional to :math:`\Delta\gamma` (Vlieg equation 20),
+  so its integrated intensity is too; a stationary measurement intercepts the
+  whole rod cross-section and carries no such factor. Because orGUI sizes
+  regions of interest per detector position
+  (:func:`orgui.app.ROIutils.calc_corrections`), :math:`\Delta\gamma` is not
+  even constant within one scan.
+
+.. _active-area:
+
+The active area
+---------------
+
+:math:`A` is whatever surface area actually contributes to the measured
+counts. Which of two limits applies is an experimental question, and
+:mod:`~.activearea` builds both: :func:`~.activearea.slit_limited_area` when
+post-sample slits cut the footprint, :func:`~.activearea.beam_limited_area`
+for the open-slit area-detector case orGUI usually runs in.
+
+Either way :math:`A` is the same for a rocking and for a stationary
+measurement at the same incidence angle, so it cancels from their ratio and
+cannot be the reason the two disagree. It does set the absolute scale.
+"""
+
+import numpy as np
+
+from . import geometry
+
+__all__ = [
+    "CLASSICAL_ELECTRON_RADIUS",
+    "REFLECTIVITY_ROCKING",
+    "ROCKING",
+    "SPECULAR",
+    "STATIONARY",
+    "angular_factor",
+    "integrated_intensity",
+    "mode_components",
+    "normalized_intensity",
+    "reflectivity_from_structure_factor",
+    "scale_factor",
+    "structure_factor_from_reflectivity",
+    "structure_factor_squared",
+]
+
+#: Classical electron radius in meter (CODATA 2018).
+CLASSICAL_ELECTRON_RADIUS = 2.8179403262e-15
+
+#: Rocking scan about the sample rotation; see :func:`angular_factor`.
+ROCKING = geometry.ROCKING
+
+#: Rocking scan about the incidence angle, how a reflectivity curve is
+#: measured; see :func:`angular_factor`.
+REFLECTIVITY_ROCKING = geometry.REFLECTIVITY_ROCKING
+
+#: Stationary measurement on an area detector; see :func:`angular_factor`.
+STATIONARY = geometry.STATIONARY
+
+#: Specular reflectivity: the stationary factor at ``gamma = alpha``.
+SPECULAR = "specular"
+
+#: Modes whose integrated intensity is proportional to the out-of-plane
+#: acceptance of the region of interest, because they intercept a slice of
+#: rod rather than its whole cross-section.
+_ROCKING_MODES = (ROCKING, REFLECTIVITY_ROCKING)
+
+_ANGSTROM = 1e-10
+
+
+def _reflectivity_prefactor(wavelength, unitcell_area):
+    r""":math:`r_e^2\lambda^2/A_u^2`, dimensionless.
+
+    The same combination :func:`scale_factor` builds, without the flux and
+    the area, which is what Vlieg's reflectivity expression (equation 63)
+    needs. Kept separate so the reflectivity functions do not depend on
+    :func:`scale_factor`'s unit defaults being ``1``.
+
+    :param wavelength: X-ray wavelength, in Angstrom.
+    :param unitcell_area: Surface unit-cell area, in square Angstrom.
+    :rtype: numpy.ndarray
+    :raises ValueError: If either argument is not positive.
+    """
+    wavelength = np.asarray(wavelength, dtype=np.float64)
+    unitcell_area = np.asarray(unitcell_area, dtype=np.float64)
+    if np.any(wavelength <= 0):
+        raise ValueError("wavelength must be positive, in Angstrom")
+    if np.any(unitcell_area <= 0):
+        raise ValueError("unitcell_area must be positive, in square Angstrom")
+    lam = wavelength * _ANGSTROM
+    a_u = unitcell_area * _ANGSTROM**2
+    return CLASSICAL_ELECTRON_RADIUS**2 * lam**2 / a_u**2
+
+
+def normalized_intensity(counts, exposure_time=1.0, monitor=1.0, angle_unit=None):
+    r"""Counts brought to per second, per monitor unit, per radian.
+
+    Both Vlieg's rocking-scan expression (equation 42) and his stationary one
+    (equation 54) contain the incident flux and the counting time, so neither
+    an integrated rocking curve nor a stationary frame means anything until
+    it is divided by the counting time and by whatever monitor the flux is
+    tracked with. Doing it in one place is what lets the two modes share a
+    scale.
+
+    :param counts: Background-subtracted integrated counts. For a stationary
+        measurement, the sum over the region of interest of one frame. For a
+        rocking scan, the integral of the per-frame counts over the rocking
+        angle, in counts times ``angle_unit``.
+    :param exposure_time: Counting time of a single frame, in seconds. A
+        rocking scan uses the *per-frame* time, not the sum over the scan:
+        the rocking angle is the integration variable, the time is not.
+    :param monitor: Monitor counter value the flux is normalized against.
+        ``1.0`` leaves the intensity in counts per second.
+    :param str angle_unit: ``None`` for a stationary sum, ``'rad'`` or
+        ``'deg'`` for a rocking-scan integral. ``'deg'`` converts to radian,
+        which is what :func:`angular_factor` and the published equations
+        assume.
+    :returns: The normalized intensity, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If ``angle_unit`` is not ``None``, ``'rad'`` or
+        ``'deg'``, or if a divisor is not finite and non-zero.
+    """
+    counts = np.asarray(counts, dtype=np.float64)
+    exposure_time = np.asarray(exposure_time, dtype=np.float64)
+    monitor = np.asarray(monitor, dtype=np.float64)
+    if np.any(exposure_time <= 0) or not np.all(np.isfinite(exposure_time)):
+        raise ValueError("exposure_time must be finite and positive")
+    if np.any(monitor == 0) or not np.all(np.isfinite(monitor)):
+        raise ValueError("monitor must be finite and non-zero")
+
+    if angle_unit is None:
+        scale = 1.0
+    elif angle_unit == "rad":
+        scale = 1.0
+    elif angle_unit == "deg":
+        scale = np.deg2rad(1.0)
+    else:
+        raise ValueError(
+            f"unknown angle_unit {angle_unit!r}; expected None, 'rad' or 'deg'"
+        )
+    return counts * scale / (exposure_time * monitor)
+
+
+def _resolve_specular(mode, alpha, gamma):
+    """Rewrite :data:`SPECULAR` as the stationary case at ``gamma = alpha``.
+
+    :returns: ``(mode, gamma)`` with the specular mode replaced.
+    :rtype: tuple
+    :raises ValueError: If ``alpha`` is missing, or ``gamma`` contradicts the
+        specular condition.
+    """
+    if mode != SPECULAR:
+        return mode, gamma
+    if alpha is None:
+        raise ValueError("the specular factor needs alpha")
+    if gamma is not None and not np.allclose(gamma, alpha):
+        raise ValueError(
+            "the specular factor is the stationary one at gamma = alpha; "
+            "use STATIONARY for a non-specular exit angle"
+        )
+    return STATIONARY, alpha
+
+
+def mode_components(mode, alpha=None, delta=None, gamma=None):
+    r"""Named angular factors a measurement mode applies.
+
+    The single place the choice of correction factors is tied to the kind of
+    scan. Both the rocking and the stationary integration ask this rather
+    than selecting a Lorentz factor themselves, and they store the returned
+    names beside ``F2_hkl``, so the saved data records which mode produced
+    it.
+
+    Returned keys:
+
+    ``C_Lorentz``
+        :math:`L_\varphi = 1/(\sin\delta\cos\alpha\cos\gamma)` for
+        :data:`ROCKING`, :math:`L_r = 1/\sin 2\alpha` for
+        :data:`REFLECTIVITY_ROCKING`, :math:`L_s = 1/\sin\gamma` for
+        :data:`STATIONARY` and :data:`SPECULAR`.
+    ``C_rod``
+        :math:`\cos\gamma`, the rod interception, for the two rocking modes
+        only. A stationary measurement integrates across the whole rod and
+        has none (Vlieg 1997, before equation 54).
+
+    :param str mode: :data:`ROCKING`, :data:`REFLECTIVITY_ROCKING`,
+        :data:`STATIONARY` or :data:`SPECULAR`.
+    :param alpha: Incidence angle, in radian.
+    :param delta: In-plane detector angle, in radian.
+    :param gamma: Out-of-plane detector angle -- the exit angle in the z-axis
+        geometry -- in radian.
+    :returns: Mapping of factor name to value, broadcast over the inputs.
+    :rtype: dict
+    :raises ValueError: If ``mode`` is unknown or a required angle is
+        missing.
+    """
+    mode, gamma = _resolve_specular(mode, alpha, gamma)
+    if mode == ROCKING:
+        return {
+            "C_Lorentz": geometry.lorentz_factor(
+                geometry.ROCKING, alpha=alpha, delta=delta, gamma=gamma
+            ),
+            "C_rod": geometry.rod_interception(gamma),
+        }
+    if mode == REFLECTIVITY_ROCKING:
+        return {
+            "C_Lorentz": geometry.lorentz_factor(
+                geometry.REFLECTIVITY_ROCKING, alpha=alpha
+            ),
+            "C_rod": geometry.rod_interception(gamma),
+        }
+    if mode == STATIONARY:
+        return {
+            "C_Lorentz": geometry.lorentz_factor(geometry.STATIONARY, gamma=gamma)
+        }
+    raise ValueError(
+        f"unknown mode {mode!r}; expected one of {ROCKING!r}, "
+        f"{REFLECTIVITY_ROCKING!r}, {STATIONARY!r} or {SPECULAR!r}"
+    )
+
+
+def angular_factor(
+    mode, alpha=None, delta=None, gamma=None, detector_acceptance=None
+):
+    r"""Angle-dependent factor :math:`\eta` of the integrated intensity.
+
+    The product of the :func:`mode_components` of the mode and, for the two
+    rocking modes, the out-of-plane acceptance: :data:`ROCKING` gives
+    :math:`L_\varphi\,C_\mathrm{rod}\,\Delta\gamma` (Vlieg equations 16, 20
+    and 23, Drnec equation 3), :data:`STATIONARY` gives
+    :math:`L_s = 1/\sin\gamma` (Vlieg equation 53, Drnec equation 5), and
+    :data:`SPECULAR` is the stationary factor at :math:`\gamma = \alpha`,
+    the case Vlieg treats in his section 3.2.
+
+    :param str mode: :data:`ROCKING`, :data:`REFLECTIVITY_ROCKING`,
+        :data:`STATIONARY` or :data:`SPECULAR`.
+    :param alpha: Incidence angle, in radian. Required for the rocking modes
+        and for :data:`SPECULAR`.
+    :param delta: In-plane detector angle, in radian. Required for
+        :data:`ROCKING`.
+    :param gamma: Out-of-plane detector angle, in radian. Required for
+        :data:`ROCKING`, :data:`REFLECTIVITY_ROCKING` and
+        :data:`STATIONARY`.
+    :param detector_acceptance: Out-of-plane angular acceptance
+        :math:`\Delta\gamma` of the region of interest, in **radian**.
+        Required for the rocking modes, rejected otherwise: a stationary
+        measurement intercepts the whole rod and does not depend on it.
+    :returns: :math:`\eta`, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If ``mode`` is unknown, a required angle is missing,
+        or ``detector_acceptance`` is given for a mode that has none.
+    """
+    resolved, _ = _resolve_specular(mode, alpha, gamma)
+    if resolved in _ROCKING_MODES:
+        if detector_acceptance is None:
+            raise ValueError(
+                "a rocking scan needs the out-of-plane acceptance of its "
+                "region of interest, in radian; its integrated intensity is "
+                "proportional to it (Vlieg 1997, equations 20 and 42)"
+            )
+        acceptance = np.asarray(detector_acceptance, dtype=np.float64)
+        if np.any(acceptance <= 0) or not np.all(np.isfinite(acceptance)):
+            raise ValueError("detector_acceptance must be finite and positive")
+    elif detector_acceptance is not None:
+        raise ValueError(
+            "a stationary measurement intercepts the whole rod cross "
+            "section and has no detector-acceptance factor "
+            "(Vlieg 1997, equation 54)"
+        )
+    else:
+        acceptance = 1.0
+
+    factor = acceptance
+    for value in mode_components(
+        mode, alpha=alpha, delta=delta, gamma=gamma
+    ).values():
+        factor = factor * value
+    return factor
+
+
+def scale_factor(wavelength, unitcell_area, active_area=1.0, flux_density=1.0):
+    r"""Mode-independent prefactor
+    :math:`\Phi_0 r_e^2 A \lambda^2 / A_u^2`, in 1/s.
+
+    Leaving ``flux_density`` and ``active_area`` at ``1`` gives the relative
+    scale factor, which is all that is needed to put different scan modes of
+    one experiment on a *common* scale. Supplying the measured flux density
+    and the illuminated area additionally puts them on the *absolute* one, so
+    that :func:`structure_factor_squared` returns electron units.
+
+    :param wavelength: X-ray wavelength, in Angstrom.
+    :param unitcell_area: Area :math:`A_u` of the surface unit cell, in
+        square Angstrom.
+    :param active_area: Illuminated active surface area :math:`A`, in square
+        meter; see :mod:`~.activearea`.
+    :param flux_density: Incident flux density :math:`\Phi_0`, in photons per
+        second and square meter, so that ``flux_density * A_0`` is the flux
+        on the sample.
+    :returns: The prefactor, in 1/s, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If the wavelength or the unit-cell area is not
+        positive.
+    """
+    wavelength = np.asarray(wavelength, dtype=np.float64)
+    unitcell_area = np.asarray(unitcell_area, dtype=np.float64)
+    if np.any(wavelength <= 0):
+        raise ValueError("wavelength must be positive, in Angstrom")
+    if np.any(unitcell_area <= 0):
+        raise ValueError("unitcell_area must be positive, in square Angstrom")
+    lam = wavelength * _ANGSTROM
+    a_u = unitcell_area * _ANGSTROM**2
+    return (
+        np.asarray(flux_density, dtype=np.float64)
+        * np.asarray(active_area, dtype=np.float64)
+        * CLASSICAL_ELECTRON_RADIUS**2
+        * lam**2
+        / a_u**2
+    )
+
+
+def structure_factor_squared(
+    intensity,
+    mode,
+    alpha=None,
+    delta=None,
+    gamma=None,
+    detector_acceptance=None,
+    wavelength=None,
+    unitcell_area=None,
+    active_area=1.0,
+    flux_density=1.0,
+    detector_efficiency=1.0,
+):
+    r"""Turn a normalized integrated intensity into :math:`|F_{hkl}|^2`.
+
+    Inverts the master equation of this module. ``intensity`` must already be
+    the output of :func:`normalized_intensity` and must already be divided by
+    the polarization factor :math:`P`; everything else is divided out here.
+
+    :param intensity: Normalized integrated intensity, from
+        :func:`normalized_intensity`.
+    :param str mode: :data:`ROCKING`, :data:`STATIONARY` or :data:`SPECULAR`.
+    :param alpha: Incidence angle, in radian.
+    :param delta: In-plane detector angle, in radian.
+    :param gamma: Out-of-plane detector angle, in radian.
+    :param detector_acceptance: Out-of-plane acceptance :math:`\Delta\gamma`
+        of the region of interest, in radian; rocking scans only.
+    :param wavelength: X-ray wavelength, in Angstrom.
+    :param unitcell_area: Surface unit-cell area, in square Angstrom.
+    :param active_area: Illuminated active area, in square meter.
+    :param flux_density: Incident flux density, in photons per second and
+        square meter.
+    :param detector_efficiency: In-plane acceptance :math:`C_\mathrm{det}`,
+        or any further multiplicative correction of the *intensity*.
+    :returns: :math:`|F_{hkl}|^2`, in electron units squared when the flux
+        density and the active area are the measured ones, and on a common
+        but arbitrary scale otherwise.
+    :rtype: numpy.ndarray
+    :raises ValueError: If the mode or the angles are inconsistent, or if the
+        wavelength or unit-cell area is missing.
+    """
+    if wavelength is None or unitcell_area is None:
+        raise ValueError(
+            "wavelength (Angstrom) and unitcell_area (square Angstrom) set the "
+            "scale and must both be given"
+        )
+    eta = angular_factor(
+        mode,
+        alpha=alpha,
+        delta=delta,
+        gamma=gamma,
+        detector_acceptance=detector_acceptance,
+    )
+    scale = scale_factor(wavelength, unitcell_area, active_area, flux_density)
+    return np.asarray(intensity, dtype=np.float64) / (
+        scale * eta * np.asarray(detector_efficiency, dtype=np.float64)
+    )
+
+
+def integrated_intensity(
+    f2,
+    mode,
+    alpha=None,
+    delta=None,
+    gamma=None,
+    detector_acceptance=None,
+    wavelength=None,
+    unitcell_area=None,
+    active_area=1.0,
+    flux_density=1.0,
+    detector_efficiency=1.0,
+):
+    r"""Forward model: the normalized intensity a given :math:`|F_{hkl}|^2`
+    produces.
+
+    The exact inverse of :func:`structure_factor_squared`, kept as a public
+    function because it is how a simulated measurement -- and therefore a
+    regression test of the whole reduction -- is built.
+
+    Arguments and units are those of :func:`structure_factor_squared`, with
+    ``f2`` in electron units squared.
+
+    :returns: The normalized integrated intensity, in the units
+        :func:`normalized_intensity` produces.
+    :rtype: numpy.ndarray
+    """
+    eta = angular_factor(
+        mode,
+        alpha=alpha,
+        delta=delta,
+        gamma=gamma,
+        detector_acceptance=detector_acceptance,
+    )
+    scale = scale_factor(wavelength, unitcell_area, active_area, flux_density)
+    return (
+        np.asarray(f2, dtype=np.float64)
+        * scale
+        * eta
+        * np.asarray(detector_efficiency, dtype=np.float64)
+    )
+
+
+def reflectivity_from_structure_factor(
+    f2, wavelength, unitcell_area, alpha, beta_out=None, polarization=1.0
+):
+    r"""Absolute reflectivity of a rod, from its structure factor.
+
+    Vlieg equation 63,
+
+    .. math::
+
+        R = \frac{r_e^2 \lambda^2 P_r}{A_u^2 \sin\alpha \sin\beta_\mathrm{out}}
+            |F_{hkl}|^2 ,
+
+    the fraction of the incident flux scattered into the rod. For the
+    specular rod :math:`\beta_\mathrm{out} = \alpha` and this is the familiar
+    :math:`1/\sin^2\alpha`: one power from the beam footprint
+    :math:`A_r = A_0/\sin\alpha`, one from the stationary Lorentz factor
+    :math:`1/\sin\beta_\mathrm{out}`.
+
+    Nothing beyond the structure factor is needed, so an absolutely scaled
+    :math:`|F_{hkl}|^2` from any scan mode yields an absolute reflectivity
+    without a separate measurement. This is the kinematic result: it does not
+    hold near a bulk Bragg peak, and below the critical angle refraction and
+    multiple scattering are not described by it.
+
+    Off the specular rod, :math:`R` is the fraction of the incident flux
+    scattered into that rod; it is a well-defined number for a truncation rod
+    integrated across its cross-section, but not for diffuse scattering,
+    where only a differential cross-section is meaningful.
+
+    :param f2: :math:`|F_{hkl}|^2` in electron units squared, on an absolute
+        scale.
+    :param wavelength: X-ray wavelength, in Angstrom.
+    :param unitcell_area: Surface unit-cell area, in square Angstrom.
+    :param alpha: Incidence angle, in radian.
+    :param beta_out: Exit angle, in radian; ``None`` means the specular
+        condition ``beta_out = alpha``.
+    :param polarization: Polarization factor :math:`P_r`; for the specular
+        condition Vlieg equation 59 gives
+        ``p_h * cos(2 alpha)**2 + (1 - p_h)``.
+    :returns: The reflectivity, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If the wavelength or the unit-cell area is not
+        positive.
+    """
+    alpha = np.asarray(alpha, dtype=np.float64)
+    beta_out = alpha if beta_out is None else np.asarray(beta_out, dtype=np.float64)
+    return (
+        np.asarray(f2, dtype=np.float64)
+        * _reflectivity_prefactor(wavelength, unitcell_area)
+        * np.asarray(polarization, dtype=np.float64)
+        / (np.sin(alpha) * np.sin(beta_out))
+    )
+
+
+def structure_factor_from_reflectivity(
+    reflectivity, wavelength, unitcell_area, alpha, beta_out=None, polarization=1.0
+):
+    r"""Inverse of :func:`reflectivity_from_structure_factor`.
+
+    Puts a measured reflectivity curve on the same :math:`|F_{hkl}|^2` scale
+    as the crystal truncation rods, so that a reflectivity and a set of rods
+    can be refined together.
+
+    Arguments and units are those of
+    :func:`reflectivity_from_structure_factor`.
+
+    :returns: :math:`|F_{hkl}|^2` in electron units squared.
+    :rtype: numpy.ndarray
+    """
+    alpha = np.asarray(alpha, dtype=np.float64)
+    beta_out = alpha if beta_out is None else np.asarray(beta_out, dtype=np.float64)
+    return (
+        np.asarray(reflectivity, dtype=np.float64)
+        * np.sin(alpha)
+        * np.sin(beta_out)
+        / (
+            _reflectivity_prefactor(wavelength, unitcell_area)
+            * np.asarray(polarization, dtype=np.float64)
+        )
+    )
diff --git a/orgui/datautils/xrayutils/test/test_corrections_activearea.py b/orgui/datautils/xrayutils/test/test_corrections_activearea.py
new file mode 100644
index 0000000..99b960a
--- /dev/null
+++ b/orgui/datautils/xrayutils/test/test_corrections_activearea.py
@@ -0,0 +1,129 @@
+"""Regression tests for the illuminated active surface area.
+
+:mod:`orgui.datautils.xrayutils.corrections.activearea` builds the area
+:math:`A` that multiplies every integrated-intensity expression of E. Vlieg,
+*J. Appl. Cryst.* **30** (1997) 532, in the two limits an experiment can be
+in. See ``doc/design/ctr_structure_factor_scale.md`` finding F4.
+"""
+
+import numpy as np
+import pytest
+
+from orgui.datautils.xrayutils.corrections import activearea, geometry
+from orgui.datautils.xrayutils.corrections.beamprofile import (
+    gaussian_profile,
+    top_hat_profile,
+)
+
+#: Horizontal beam size, vertical beam size and sample length, in meter.
+W, H, L = 300e-6, 20e-6, 5e-3
+
+
+def test_beam_limited_area_reduces_to_the_closed_form_for_a_top_hat():
+    """``w L C_illum`` is ``w min(L, h/sin alpha)`` for a uniform beam.
+
+    This identity is why the module offers no separate closed form. It also
+    fixes the meaning of ``illuminated_area_fraction``: it is the mean of
+    ``p(z)/p_max`` over the projected sample, so multiplying by the sample
+    length and the beam width is all that turns it into an absolute area.
+    """
+    alpha = np.deg2rad(np.array([0.05, 0.1, 0.23, 0.5, 1.0, 2.0, 5.0, 15.0]))
+
+    from_profile = activearea.beam_limited_area(alpha, W, L, top_hat_profile(H))
+    closed_form = W * activearea.footprint_length(alpha, H, L)
+
+    np.testing.assert_allclose(from_profile, closed_form, rtol=1e-12)
+
+
+def test_a_real_beam_is_not_the_closed_form():
+    """A Gaussian of the same width differs enough to matter.
+
+    The closed form is a top-hat statement, not a general one: taking it for
+    a focused beam is a percent-level error at high incidence and much worse
+    where the beam spills off the sample.
+    """
+    alpha = np.deg2rad(np.array([0.05, 0.23, 2.0, 15.0]))
+
+    gauss = activearea.beam_limited_area(alpha, W, L, gaussian_profile(H))
+    top_hat = activearea.beam_limited_area(alpha, W, L, top_hat_profile(H))
+
+    ratio = gauss / top_hat
+    assert ratio.min() < 0.85, "grazing incidence must show the profile tails"
+    assert ratio.max() > 1.06, "a flooded sample must show the peak density"
+
+
+def test_footprint_length_is_clipped_by_the_sample():
+    """Below the flooding angle the beam sets the length, above it the sample."""
+    flooding = np.arcsin(H / L)
+    alpha = np.array([flooding / 2.0, flooding * 2.0])
+
+    length = activearea.footprint_length(alpha, H, L)
+
+    np.testing.assert_allclose(length[0], L, rtol=1e-12)
+    np.testing.assert_allclose(length[1], H / np.sin(alpha[1]), rtol=1e-12)
+
+
+def test_slit_limited_area_is_the_z_axis_table_entry():
+    """``s1 s2 / sin(delta)``, with the cosine that the z-axis mode drops.
+
+    :func:`~.geometry.area_correction` is the tabulated row; this only turns
+    it into an area and reinstates ``cos(alpha - beta_in)`` for a geometry
+    where the incidence angle is not the angle to the surface.
+    """
+    delta = np.deg2rad(np.array([5.0, 17.0, 40.0]))
+    s1, s2 = 200e-6, 1e-3
+
+    z_axis = activearea.slit_limited_area(delta, s1, s2)
+
+    np.testing.assert_allclose(
+        z_axis, s1 * s2 * geometry.area_correction(delta), rtol=1e-12
+    )
+    # beta_in = alpha is the z-axis mode, so the cosine is one.
+    alpha = np.deg2rad(0.6)
+    np.testing.assert_allclose(
+        activearea.slit_limited_area(delta, s1, s2, alpha=alpha, beta_in=alpha),
+        z_axis,
+        rtol=1e-12,
+    )
+    tilted = activearea.slit_limited_area(
+        delta, s1, s2, alpha=alpha, beta_in=np.deg2rad(10.0)
+    )
+    np.testing.assert_allclose(
+        tilted, z_axis / np.cos(alpha - np.deg2rad(10.0)), rtol=1e-12
+    )
+
+
+def test_the_two_limits_disagree_and_that_is_the_experimental_question():
+    """They are alternatives, not factors, and only one can be right.
+
+    The slit-limited area varies along a rod because it depends on delta;
+    the beam-limited one does not. Which applies is set by the slit
+    settings, and orGUI's open-slit configuration is the second.
+    """
+    delta = np.deg2rad(np.array([16.77, 16.86, 16.95]))
+    alpha = np.deg2rad(np.full(delta.size, 0.6))
+
+    slits = activearea.slit_limited_area(delta, 200e-6, 1e-3)
+    beam = activearea.beam_limited_area(alpha, W, L, top_hat_profile(H))
+
+    assert slits.max() / slits.min() > 1.005
+    np.testing.assert_allclose(beam, beam[0], rtol=1e-12)
+
+
+def test_sizes_must_be_physical():
+    """A zero or negative size is a units mistake, not a value."""
+    alpha = np.deg2rad(1.0)
+    with pytest.raises(ValueError, match="beam_width must be positive"):
+        activearea.beam_limited_area(alpha, 0.0, L, top_hat_profile(H))
+    with pytest.raises(ValueError, match="sample_length must be positive"):
+        activearea.beam_limited_area(alpha, W, -1.0, top_hat_profile(H))
+    with pytest.raises(ValueError, match="needs a beam profile"):
+        activearea.beam_limited_area(alpha, W, L, None)
+    with pytest.raises(ValueError, match="beam_height must be positive"):
+        activearea.footprint_length(alpha, 0.0, L)
+    with pytest.raises(ValueError, match="slit_width must be positive"):
+        activearea.slit_limited_area(np.deg2rad(17.0), 0.0, 1e-3)
+    with pytest.raises(ValueError, match="beta_in needs alpha"):
+        activearea.slit_limited_area(
+            np.deg2rad(17.0), 200e-6, 1e-3, beta_in=np.deg2rad(1.0)
+        )
diff --git a/orgui/datautils/xrayutils/test/test_corrections_measurement.py b/orgui/datautils/xrayutils/test/test_corrections_measurement.py
new file mode 100644
index 0000000..fcd0429
--- /dev/null
+++ b/orgui/datautils/xrayutils/test/test_corrections_measurement.py
@@ -0,0 +1,346 @@
+"""Regression tests for the common structure-factor scale.
+
+:mod:`orgui.datautils.xrayutils.corrections.measurement` reduces an integrated
+intensity to :math:`|F_{hkl}|^2` for any scan mode. Every expectation here is
+written out independently from the published equations -- E. Vlieg,
+*J. Appl. Cryst.* **30** (1997) 532 and J. Drnec *et al.*,
+*J. Appl. Cryst.* **47** (2014) 365 -- rather than by calling the module back,
+so that the tests pin the physics and not the implementation.
+
+See ``doc/design/ctr_structure_factor_scale.md`` for the analysis these tests
+belong to, and `issue #15 <https://github.com/tifuchs/orGUI/issues/15>`_ and
+`issue #82 <https://github.com/tifuchs/orGUI/issues/82>`_ for the requests.
+"""
+
+import numpy as np
+import pytest
+
+from orgui.datautils.xrayutils.corrections import measurement as ii
+
+#: A z-axis trajectory along a rod: fixed incidence, exit angle climbing.
+ALPHA = np.deg2rad(np.full(6, 0.6))
+DELTA = np.deg2rad(np.array([16.77, 16.79, 16.83, 16.89, 16.93, 16.95]))
+GAMMA = np.deg2rad(np.array([1.76, 3.53, 5.31, 8.88, 12.49, 17.38]))
+
+#: Out-of-plane acceptance of a region of interest, in radian.
+DGAMMA = np.deg2rad(0.35)
+
+#: Pt(111) hexagonal surface cell at 17.7 keV.
+WAVELENGTH = 0.70047
+UC_AREA = 2.7748 * 2.7748 * np.sin(np.deg2rad(120.0))
+
+
+def test_normalized_intensity_divides_by_time_and_monitor():
+    """Both published expressions carry ``Phi_0 T``; both must come out."""
+    got = ii.normalized_intensity(
+        np.array([100.0, 200.0]), exposure_time=0.5, monitor=4.0
+    )
+
+    np.testing.assert_allclose(got, np.array([50.0, 100.0]))
+
+
+def test_normalized_intensity_converts_the_rocking_angle_to_radian():
+    """A rocking integral taken in degrees is 180/pi too large.
+
+    :func:`~orgui.app.peak1Dintegr._compute_rocking_integration` integrates
+    over the rocking axis as stored, which is degrees. Vlieg's equation 42
+    and Drnec's equation 2 integrate in radian.
+    """
+    counts_deg = 573.0
+
+    in_deg = ii.normalized_intensity(counts_deg, angle_unit="deg")
+    in_rad = ii.normalized_intensity(counts_deg, angle_unit="rad")
+
+    np.testing.assert_allclose(in_deg, np.deg2rad(counts_deg))
+    np.testing.assert_allclose(in_rad / in_deg, np.rad2deg(1.0))
+
+
+def test_normalized_intensity_rejects_unusable_divisors():
+    """A zero monitor or exposure must fail loudly, not scale by infinity."""
+    with pytest.raises(ValueError, match="finite and positive"):
+        ii.normalized_intensity(1.0, exposure_time=0.0)
+    with pytest.raises(ValueError, match="finite and non-zero"):
+        ii.normalized_intensity(1.0, monitor=0.0)
+    with pytest.raises(ValueError, match="unknown angle_unit"):
+        ii.normalized_intensity(1.0, angle_unit="degrees")
+
+
+def test_rocking_factor_is_the_published_z_axis_expression():
+    """``L_phi * C_rod * Delta_gamma``, Vlieg equations 16, 20, 23 and 42."""
+    expected = (
+        1.0 / (np.sin(DELTA) * np.cos(ALPHA) * np.cos(GAMMA))  # L_phi, eq (16)
+        * np.cos(GAMMA)  # C_rod, eq (23) in the z-axis mode
+        * DGAMMA  # rod length intercepted, eq (20)
+    )
+
+    got = ii.angular_factor(
+        ii.ROCKING,
+        alpha=ALPHA,
+        delta=DELTA,
+        gamma=GAMMA,
+        detector_acceptance=DGAMMA,
+    )
+
+    np.testing.assert_allclose(got, expected, rtol=1e-12)
+
+
+def test_stationary_factor_is_the_published_z_axis_expression():
+    """``L_s = 1/sin(gamma)``, Vlieg equation 53 and Drnec equation 5."""
+    got = ii.angular_factor(ii.STATIONARY, gamma=GAMMA)
+
+    np.testing.assert_allclose(got, 1.0 / np.sin(GAMMA), rtol=1e-12)
+
+
+def test_rocking_intensity_is_linear_in_the_detector_acceptance():
+    """Twice the out-of-plane acceptance intercepts twice as much rod.
+
+    This is the factor that makes a rocking scan disagree with a stationary
+    measurement of the same rod, and it is not constant over a scan whenever
+    the region of interest is resized per detector position.
+    """
+    single = ii.angular_factor(
+        ii.ROCKING, alpha=ALPHA, delta=DELTA, gamma=GAMMA, detector_acceptance=DGAMMA
+    )
+    double = ii.angular_factor(
+        ii.ROCKING,
+        alpha=ALPHA,
+        delta=DELTA,
+        gamma=GAMMA,
+        detector_acceptance=2.0 * DGAMMA,
+    )
+
+    np.testing.assert_allclose(double, 2.0 * single, rtol=1e-12)
+
+
+def test_the_acceptance_belongs_to_rocking_scans_only():
+    """Neither mode may silently accept the other's arguments."""
+    with pytest.raises(ValueError, match="out-of-plane acceptance"):
+        ii.angular_factor(ii.ROCKING, alpha=ALPHA, delta=DELTA, gamma=GAMMA)
+    with pytest.raises(ValueError, match="whole rod cross"):
+        ii.angular_factor(ii.STATIONARY, gamma=GAMMA, detector_acceptance=DGAMMA)
+    with pytest.raises(ValueError, match="unknown mode"):
+        ii.angular_factor("rsm", gamma=GAMMA)
+
+
+def test_specular_is_the_stationary_factor_at_the_specular_condition():
+    """Vlieg section 3.2: reflectivity is the stationary case, gamma = alpha."""
+    alpha = np.deg2rad(np.array([0.4, 1.0, 2.5]))
+
+    specular = ii.angular_factor(ii.SPECULAR, alpha=alpha)
+
+    np.testing.assert_allclose(specular, 1.0 / np.sin(alpha), rtol=1e-12)
+    np.testing.assert_allclose(
+        specular, ii.angular_factor(ii.STATIONARY, gamma=alpha), rtol=1e-12
+    )
+    with pytest.raises(ValueError, match="non-specular exit angle"):
+        ii.angular_factor(ii.SPECULAR, alpha=alpha, gamma=alpha + 0.1)
+
+
+def test_scale_factor_carries_its_documented_units():
+    """``Phi_0 r_e^2 A lambda^2 / A_u^2``, with lengths mixed as documented.
+
+    The wavelength and the unit-cell area are in Angstrom, the area and the
+    flux density in meter; getting that conversion wrong is a factor of
+    1e20 and is exactly the kind of error the module exists to prevent.
+    """
+    r_e = 2.8179403262e-15
+    expected = (
+        1e16 * r_e**2 * 5.73e-7 * (WAVELENGTH * 1e-10) ** 2 / (UC_AREA * 1e-20) ** 2
+    )
+
+    got = ii.scale_factor(
+        WAVELENGTH, UC_AREA, active_area=5.73e-7, flux_density=1e16
+    )
+
+    np.testing.assert_allclose(got, expected, rtol=1e-12)
+    # The prefactor is a rate: counts per second for |F|^2 = 1.
+    assert 1e-4 < got < 1e2
+
+
+def test_scale_factor_rejects_nonphysical_lengths():
+    """A negative wavelength or unit cell is a units mistake, not a value."""
+    with pytest.raises(ValueError, match="wavelength must be positive"):
+        ii.scale_factor(-1.0, UC_AREA)
+    with pytest.raises(ValueError, match="unitcell_area must be positive"):
+        ii.scale_factor(WAVELENGTH, 0.0)
+
+
+def test_structure_factor_round_trips_through_the_forward_model():
+    """The reduction is the exact inverse of the forward model, per mode."""
+    f2 = np.array([273.6, 148.3, 108.2, 98.0, 865.9, 5000.0])
+    common = dict(
+        wavelength=WAVELENGTH,
+        unitcell_area=UC_AREA,
+        active_area=5.73e-7,
+        flux_density=1e16,
+        detector_efficiency=0.93,
+    )
+
+    for kwargs in (
+        dict(mode=ii.ROCKING, alpha=ALPHA, delta=DELTA, gamma=GAMMA,
+             detector_acceptance=DGAMMA),
+        dict(mode=ii.STATIONARY, gamma=GAMMA),
+        dict(mode=ii.SPECULAR, alpha=GAMMA),
+    ):
+        intensity = ii.integrated_intensity(f2, **kwargs, **common)
+        back = ii.structure_factor_squared(intensity, **kwargs, **common)
+        np.testing.assert_allclose(back, f2, rtol=1e-12)
+
+
+def test_structure_factor_needs_the_scale_to_be_stated():
+    """The wavelength and unit-cell area are not optional defaults."""
+    with pytest.raises(ValueError, match="set the scale"):
+        ii.structure_factor_squared(1.0, ii.STATIONARY, gamma=GAMMA)
+
+
+def test_the_two_modes_agree_on_one_structure_factor():
+    """The point of issue #82: one rod, two scan modes, one ``|F|^2``.
+
+    A rocking scan and a stationary measurement of the same reflection are
+    forward-simulated with completely different counting times, monitor
+    values and detector acceptances, then reduced. Only if every
+    mode-dependent factor is right do the two land on the same number.
+    """
+    f2 = np.array([273.6, 148.3, 108.2, 98.0, 865.9, 5000.0])
+    scale = dict(
+        wavelength=WAVELENGTH,
+        unitcell_area=UC_AREA,
+        active_area=5.73e-7,
+        flux_density=1e16,
+    )
+    # Different acceptance at every point, as a resized region of interest
+    # gives; if it were not divided out this test could not pass.
+    acceptance = DGAMMA * np.linspace(0.7, 1.6, GAMMA.size)
+
+    rocking_counts = (
+        ii.integrated_intensity(
+            f2, ii.ROCKING, alpha=ALPHA, delta=DELTA, gamma=GAMMA,
+            detector_acceptance=acceptance, **scale
+        )
+        * 0.4  # per-frame counting time, s
+        * 3.0  # monitor
+        * np.rad2deg(1.0)  # the rocking axis was integrated in degrees
+    )
+    stationary_counts = (
+        ii.integrated_intensity(f2, ii.STATIONARY, gamma=GAMMA, **scale)
+        * 2.0  # counting time, s
+        * 7.0  # monitor
+    )
+
+    f2_rocking = ii.structure_factor_squared(
+        ii.normalized_intensity(
+            rocking_counts, exposure_time=0.4, monitor=3.0, angle_unit="deg"
+        ),
+        ii.ROCKING,
+        alpha=ALPHA,
+        delta=DELTA,
+        gamma=GAMMA,
+        detector_acceptance=acceptance,
+        **scale,
+    )
+    f2_stationary = ii.structure_factor_squared(
+        ii.normalized_intensity(stationary_counts, exposure_time=2.0, monitor=7.0),
+        ii.STATIONARY,
+        gamma=GAMMA,
+        **scale,
+    )
+
+    np.testing.assert_allclose(f2_rocking, f2, rtol=1e-12)
+    np.testing.assert_allclose(f2_stationary, f2, rtol=1e-12)
+
+
+def test_mode_ratio_matches_vlieg_equation_65():
+    """The published ratio of the two integrated intensities.
+
+    Vlieg equation 65 for the z-axis mode,
+    ``I_s / I_phi = T omega_0 sin(delta) cos(beta_in) / (Delta_gamma sin(gamma))``.
+    Written here for intensities already divided by ``T`` and by the rotation
+    speed, the ``T omega_0`` drops out and what remains is a statement about
+    the two angular factors alone.
+    """
+    rocking = ii.angular_factor(
+        ii.ROCKING, alpha=ALPHA, delta=DELTA, gamma=GAMMA, detector_acceptance=DGAMMA
+    )
+    stationary = ii.angular_factor(ii.STATIONARY, gamma=GAMMA)
+
+    expected = np.sin(DELTA) * np.cos(ALPHA) / (np.sin(GAMMA) * DGAMMA)
+
+    np.testing.assert_allclose(stationary / rocking, expected, rtol=1e-12)
+
+
+def test_reflectivity_reproduces_the_fresnel_asymptote():
+    """Vlieg equation 63 against the textbook far-field Fresnel limit.
+
+    For a semi-infinite substrate far from a bulk Bragg peak the truncation
+    rod amplitude is ``|F| = rho_e A_u / q_z``, and the kinematic
+    reflectivity of such a substrate is ``(q_c / 2 q_z)^4`` with
+    ``q_c^2 = 16 pi r_e rho_e``. Any error in the wavelength, unit-cell area
+    or ``sin`` powers of equation 63 breaks this identity, so it validates
+    the absolute scale end to end and not just an algebraic rearrangement.
+    """
+    r_e_ang = ii.CLASSICAL_ELECTRON_RADIUS / 1e-10  # Angstrom
+    rho_e = 5.16  # electrons per cubic Angstrom, close to Pt
+    alpha = np.deg2rad(np.array([0.5, 0.8, 1.2, 2.0, 3.0]))
+    q_z = 4.0 * np.pi * np.sin(alpha) / WAVELENGTH  # 1/Angstrom
+    q_c = np.sqrt(16.0 * np.pi * r_e_ang * rho_e)
+
+    f2 = (rho_e * UC_AREA / q_z) ** 2
+    reflectivity = ii.reflectivity_from_structure_factor(
+        f2, WAVELENGTH, UC_AREA, alpha
+    )
+
+    np.testing.assert_allclose(reflectivity, (q_c / (2.0 * q_z)) ** 4, rtol=1e-12)
+    # Well above the critical angle, where the kinematic result is valid.
+    assert np.all(np.rad2deg(np.arcsin(q_c * WAVELENGTH / (4.0 * np.pi))) < 0.5)
+
+
+def test_reflectivity_round_trips_and_generalizes_off_specular():
+    """The inverse recovers ``|F|^2``, and a non-specular exit angle works."""
+    alpha = np.deg2rad(0.6)
+    beta_out = np.deg2rad(np.array([0.6, 2.0, 8.0]))
+    f2 = np.array([1500.0, 900.0, 120.0])
+
+    reflectivity = ii.reflectivity_from_structure_factor(
+        f2, WAVELENGTH, UC_AREA, alpha, beta_out=beta_out, polarization=0.98
+    )
+    back = ii.structure_factor_from_reflectivity(
+        reflectivity, WAVELENGTH, UC_AREA, alpha, beta_out=beta_out, polarization=0.98
+    )
+
+    np.testing.assert_allclose(back, f2, rtol=1e-12)
+    # At the specular condition the two sines collapse to the familiar
+    # 1/sin^2(alpha) of Vlieg equation 63.
+    specular = ii.reflectivity_from_structure_factor(
+        f2[0], WAVELENGTH, UC_AREA, alpha
+    )
+    prefactor = (
+        ii.CLASSICAL_ELECTRON_RADIUS**2
+        * (WAVELENGTH * 1e-10) ** 2
+        / (UC_AREA * 1e-20) ** 2
+    )
+    np.testing.assert_allclose(
+        specular, prefactor * f2[0] / np.sin(alpha) ** 2, rtol=1e-12
+    )
+
+
+def test_footprint_area_cancels_between_the_modes():
+    """The active area cannot be why two scan modes disagree.
+
+    It enters both expressions identically, so it drops out of their ratio
+    even when it is wrong. That is why it is listed under the absolute scale
+    (issue #15) and not under the mode equivalence (issue #82).
+    """
+    kwargs = dict(wavelength=WAVELENGTH, unitcell_area=UC_AREA, flux_density=1e16)
+    ratios = []
+    for area in (1e-7, 5.73e-7, 2e-6):
+        rocking = ii.integrated_intensity(
+            1.0, ii.ROCKING, alpha=ALPHA, delta=DELTA, gamma=GAMMA,
+            detector_acceptance=DGAMMA, active_area=area, **kwargs
+        )
+        stationary = ii.integrated_intensity(
+            1.0, ii.STATIONARY, gamma=GAMMA, active_area=area, **kwargs
+        )
+        ratios.append(rocking / stationary)
+
+    for ratio in ratios[1:]:
+        np.testing.assert_allclose(ratio, ratios[0], rtol=1e-12)
diff --git a/orgui/datautils/xrayutils/test/test_corrections_package.py b/orgui/datautils/xrayutils/test/test_corrections_package.py
index 4f1aedf..bd940db 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_package.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_package.py
@@ -16,10 +16,16 @@
 from orgui.datautils.xrayutils import corrections
 from orgui.datautils.xrayutils.corrections import (
     detector,
+    geometry,
+    measurement,
     normalization,
     roi,
 )
 
+ALPHA = np.deg2rad(np.array([0.6, 0.6, 0.6]))
+DELTA = np.deg2rad(np.array([16.77, 16.86, 16.95]))
+GAMMA = np.deg2rad(np.array([1.76, 8.88, 17.38]))
+
 
 class _Detector:
     """Minimal stand-in for a calibrated detector."""
@@ -37,9 +43,11 @@ def polarizationArray(self):
 def test_the_package_exposes_every_correction_module():
     """A maintainer looking for a correction factor finds them in one place."""
     assert set(corrections.__all__) == {
+        "activearea",
         "beamprofile",
         "detector",
         "geometry",
+        "measurement",
         "normalization",
         "roi",
     }
@@ -75,6 +83,49 @@ def test_released_module_paths_still_import(legacy, moved):
         assert getattr(old, name) is getattr(new, name)
 
 
+def test_mode_components_is_the_only_place_the_mode_chooses_factors():
+    """Each mode's factors, checked against the z-axis primitives.
+
+    :func:`~.measurement.mode_components` is what both integration paths ask.
+    The primitives it composes stay in :mod:`~.geometry`, so this also pins
+    that the dispatch adds no formula of its own.
+    """
+    rocking = measurement.mode_components(
+        measurement.ROCKING, alpha=ALPHA, delta=DELTA, gamma=GAMMA
+    )
+    np.testing.assert_allclose(
+        rocking["C_Lorentz"],
+        geometry.lorentz_rocking_scan(DELTA, ALPHA, GAMMA),
+        rtol=1e-12,
+    )
+    np.testing.assert_allclose(
+        rocking["C_rod"], geometry.rod_interception(GAMMA), rtol=1e-12
+    )
+
+    reflectivity = measurement.mode_components(
+        measurement.REFLECTIVITY_ROCKING, alpha=ALPHA, delta=DELTA, gamma=GAMMA
+    )
+    np.testing.assert_allclose(
+        reflectivity["C_Lorentz"],
+        geometry.lorentz_reflectivity_rocking_scan(ALPHA),
+        rtol=1e-12,
+    )
+    np.testing.assert_allclose(
+        reflectivity["C_rod"], geometry.rod_interception(GAMMA), rtol=1e-12
+    )
+
+    stationary = measurement.mode_components(measurement.STATIONARY, gamma=GAMMA)
+    np.testing.assert_allclose(
+        stationary["C_Lorentz"], geometry.lorentz_stationary(GAMMA), rtol=1e-12
+    )
+    assert "C_rod" not in stationary, (
+        "a stationary measurement integrates across the whole rod"
+    )
+
+    with pytest.raises(ValueError, match="unknown mode"):
+        measurement.mode_components("rsm", gamma=GAMMA)
+
+
 def test_pixel_factors_is_the_reciprocal_of_the_enabled_arrays():
     """The one definition of the per-pixel divisors.
 

From e25b8df958a00ef110a9af89fd55b2331402abb2 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 9 Sep 2026 17:16:19 -0400
Subject: [PATCH 03/33] docs: record the rocking/stationary structure-factor
 scale analysis

---
 CHANGELOG.md                             |  36 ++
 doc/design/ctr_structure_factor_scale.md | 476 +++++++++++++++++++++++
 doc/source/ctr_structure_factors.rst     |  17 +
 doc/source/image_integration.rst         |  46 +++
 doc/source/release_notes.rst             |   4 +
 5 files changed, 579 insertions(+)
 create mode 100644 doc/design/ctr_structure_factor_scale.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f1f0c23..c956405 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,42 @@ This is the changelog for the software orGUI, written by Timo Fuchs
 
 Scientific and analysis additions:
 
+- **All correction factors collected into one package.** Every factor between
+  detector counts and a structure factor now lives in
+  ``orgui.datautils.xrayutils.corrections``, split by what it depends on:
+  ``geometry`` (the z-axis Lorentz, rod-interception and area table),
+  ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and
+  polarization), ``normalization`` (counting time and monitor), ``roi``, and
+  ``measurement``. The rocking integration, the stationary integration and the
+  reciprocal-space reconstruction previously each carried their own copy of
+  several of these; they now share one definition, so they cannot drift onto
+  different scales. The package is physics only -- numbers in, numbers out --
+  and reads no scan object, configuration or widget; ``orgui.app``
+  ``integration_corrections`` is the adapter that supplies those.
+  ``orgui.datautils.xrayutils.geometrycorrections`` and
+  ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the
+  moved modules. **No calculated value changes.**
+
+- **One structure-factor scale for rocking scans, stationary scans, and
+  reflectivity.** The new public module
+  ``orgui.datautils.xrayutils.corrections.measurement`` reduces an integrated
+  intensity to ``|F_hkl|^2`` for any scan mode, following E. Vlieg,
+  *J. Appl. Cryst.* 30 (1997) 532 and J. Drnec et al.,
+  *J. Appl. Cryst.* 47 (2014) 365. It normalizes counts by exposure time and
+  monitor, converts a rocking integral from degrees to radians, applies the
+  mode-dependent angular factor (rocking scans additionally require the
+  out-of-plane acceptance of the region of interest, stationary measurements
+  reject it), and, given the incident flux density and the illuminated area,
+  puts the result on the absolute electron-unit scale. It also converts
+  between ``|F_hkl|^2`` and absolute reflectivity, so a reflectivity curve and
+  a set of truncation rods can be brought onto one scale. **This is a new API
+  only: no existing integration result changes.** The integration paths do
+  not use it yet, and rocking and stationary integration remain on different
+  scales, differing by exposure time times monitor times the acceptance in
+  degrees; the image-integration documentation now says so explicitly, and
+  ``doc/design/ctr_structure_factor_scale.md`` records the full analysis with
+  the measured size of every correction.
+
 - **Unified CTR fit predictions, lifecycle, and statistics.** CTR optimizer
   predictions, residuals, likelihoods, and diagnostics now use one final
   analytically scaled result path. ``flat_prediction`` supports the common
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
new file mode 100644
index 0000000..8076bfd
--- /dev/null
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -0,0 +1,476 @@
+# One structure-factor scale for rocking scans, stationary scans and reflectivity
+
+> **Status: analysis complete, reduction core and regression tests landed, GUI
+> paths not yet switched over.** This is the review document for
+> [issue #82](https://github.com/tifuchs/orGUI/issues/82) ("Regression tests
+> and validation of equivalence of rocking and stationary scan integration")
+> and for the physics half of
+> [issue #15](https://github.com/tifuchs/orGUI/issues/15) ("Calculate
+> quantitatively exact structure factors").
+>
+> It records why a rocking scan and a stationary scan of the same rod do
+> **not** currently produce the same `F2_hkl` in orGUI, quantifies each reason
+> on simulated data, and states what is still needed for an absolute scale and
+> for absolute reflectivity. Everything below was verified numerically against
+> the code as of this branch, not by inspection alone.
+>
+> Landed with this document:
+> `orgui/datautils/xrayutils/corrections/measurement.py` (the reduction, pure
+> functions, additive - no existing number changes),
+> `orgui/datautils/xrayutils/test/test_corrections_measurement.py` (18 tests
+> against the published equations) and
+> `orgui/app/test/test_scan_mode_equivalence.py` (5 tests that simulate one
+> rod measured both ways and push it through both of orGUI's current paths).
+
+## 1. What the two papers require
+
+E. Vlieg, *J. Appl. Cryst.* **30** (1997) 532 gives the integrated intensity
+for each measurement mode of a six-circle/z-axis diffractometer. J. Drnec
+*et al.*, *J. Appl. Cryst.* **47** (2014) 365 rewrites the same expressions
+for a two-dimensional detector and states the equivalence claim of issue #82
+directly (their section 3.4 and Fig. 8, right: rocking scans at low *l* and a
+stationary scan at high *l* overlap once both are reduced properly).
+
+**Rocking scan** (Vlieg eq. 42/43, Drnec eq. 3):
+
+```
+I_omega = Phi_0 T_omega (r_e^2 A lambda^2 / A_u^2) |F|^2 P L_phi C_rod C_det C_beam Delta_gamma
+```
+
+with `L_phi = 1/(sin(delta) cos(beta_in) cos(gamma))` (eq. 16), `C_rod` the rod
+interception, which reduces to `cos(gamma)` in the z-axis mode (eq. 23), and
+`Delta_gamma` the **out-of-plane angular acceptance of the detector aperture**.
+`I_omega` is the integral of the per-frame counts over the rocking angle **in
+radian**, divided by the per-frame counting time.
+
+**Stationary measurement** (Vlieg eq. 54, Drnec eq. 5):
+
+```
+I_s = Phi_0 T_s (r_e^2 A lambda^2 / A_u^2) |F|^2 P L_s C_det,s C_beam
+```
+
+with `L_s = 1/sin(beta_out)`, in the z-axis mode `1/sin(gamma)`. There is **no**
+rod-interception factor and **no** `Delta_gamma`: a stationary measurement
+intercepts the whole rod cross-section rather than a slice of it.
+
+**Specular reflectivity** (Vlieg section 3.2, eq. 62/63) is the stationary case
+at `gamma = alpha` with a beam-limited active area, `A_r = A_0/sin(alpha)`:
+
+```
+R = I_s / (Phi_0 T A_0 C_beam) = r_e^2 lambda^2 P_r |F|^2 / (A_u^2 sin^2(alpha))
+```
+
+One power of `1/sin(alpha)` is the footprint, the other is `L_s`. Nothing
+beyond `|F|^2` is needed, so **an absolutely scaled `|F|^2` yields an absolute
+reflectivity for free** - see section 6.
+
+Their ratio (Vlieg eq. 64/65) is the identity issue #82 is really about:
+
+```
+I_s / I_omega = T omega_0 sin(delta) cos(beta_in) / (Delta_gamma sin(gamma))
+```
+
+## 2. What orGUI does today
+
+| | rocking (`peak1Dintegr`) | stationary (`orGUI.integrateROI` + `integration_corrections`) | reconstruction (`reconstruction_job`) |
+|---|---|---|---|
+| solid angle | per-pixel array, applied as ROI mean | per-pixel array, applied as ROI mean | per pixel |
+| polarization | per-pixel array, applied as ROI mean | per-pixel array, applied as ROI mean | per pixel |
+| exposure / monitor | **not applied** | `normalization_divisor` | applied |
+| footprint `C_beam` | `beamprofile` `C_illum_area` | `beamprofile` `C_illum_area` | not applied |
+| `C_area` (`1/sin(delta)`) | not applied (documented as deliberate) | not applied (documented as deliberate) | not applied |
+| Lorentz | `1/(sin(delta) cos(alpha) cos(gamma))` | `1/sin(gamma)` | not applied (correct: the voxel binning absorbs it, Drnec section 4) |
+| rod interception | `cos(gamma)` | none (correct) | none |
+| `Delta_gamma` | **not applied** | not applicable (correct) | `Delta_l` not applied |
+| rocking angle unit | **degrees** | n/a | n/a |
+| `C_det` | not modelled | not modelled | not modelled |
+
+The two Lorentz factors, the rod interception and the absence of a stationary
+`C_rod` are all correct and match the ANA/ROD z-axis table. The disagreement
+comes from the three cells in bold.
+
+## 3. Findings
+
+Ranked by how badly they distort the saved numbers.
+
+### F1 - rocking scans carry no exposure-time or monitor normalization
+
+`orgui/app/integration_corrections.py:normalization_divisor` is wired into the
+stationary path only (`orGUI.py:6361`). `peak1Dintegr.py` contains no
+occurrence of `exposure`, `monitor` or `normaliz` at all. Both published
+expressions carry `Phi_0 T`, so a rocking integral and a stationary frame are
+not comparable until both are divided by counting time and monitor.
+
+Worse than the mode mismatch: within a *single* rocking data set, rocking scans
+taken at different *l* with different counting times or a drifting ring current
+are put on different scales. Nothing in the saved data records this.
+
+### F2 - the rocking integral is taken in degrees
+
+`_compute_rocking_integration` trapezoid-integrates `croibg` over `axis`, which
+is the rocking motor position in degrees (`peak1Dintegr.py:235`-`243`). Vlieg
+eq. 42 and Drnec eq. 2 integrate in radian. Factor `180/pi = 57.3`, constant,
+so it is invisible inside one data set and only shows up when comparing to
+another mode or to an absolute scale.
+
+### F3 - no out-of-plane detector acceptance `Delta_gamma` for rocking scans
+
+This is the physically interesting one. A rocking scan intercepts a slice of
+rod of length `Delta_l = C_rod (V_u / lambda A_u) Delta_gamma` (Vlieg eq. 20),
+so its integrated intensity is *proportional to the vertical angular size of
+the region of interest*. A stationary measurement has no such factor.
+
+Before this branch, `Delta_gamma` appeared nowhere in orGUI: `grep -rn
+"acceptance"` over `orgui/` returned nothing, and the integration paths still
+do not compute it. In the point-detector world it was a fixed slit setting and
+disappeared into the overall scale factor. On an area detector with ROIs sized
+per detector position by `orgui/app/ROIutils.py:calc_corrections` (projected
+sample size plus a parallax correction, so it changes with `delta` and
+`gamma`), it is **not constant along a scan**, and the omission changes the
+*shape* of the rod, not just its scale.
+
+`test_a_resized_region_of_interest_distorts_the_rocking_rod` simulates a rod
+measured with the acceptance sweeping from 0.7x to 1.6x of nominal and shows
+the distortion carried straight into `F2_hkl`: a factor 2.3 across the rod.
+
+### F1+F2+F3 combined - the measured gap
+
+`orgui/app/test/test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_differ_by_the_missing_normalizations`
+simulates a Pt(111) `(1, 0, l)` rod at 17.7 keV from a known `|F|^2(l)`, using
+Vlieg eq. 42 and 54 as the forward model, and pushes the result through both of
+orGUI's current paths. The ratio of the two `F2_hkl` is, to seven digits,
+
+```
+F2_rocking / F2_stationary = T_omega * monitor_omega * Delta_gamma_in_degrees
+```
+
+(measured 0.5249999866 against a predicted 0.525). The `180/pi` of F2 and the
+`Delta_gamma` in radian of F3 combine into the acceptance expressed in degrees;
+the counting time and monitor of F1 sit in front. For a realistic setup - a
+100-pixel-tall ROI at 1 m with 172 um pixels is `Delta_gamma ~ 1 degree`, with
+a per-frame time of a few tenths of a second - the two modes land within a
+factor of a few of each other, which is exactly the regime in which the
+discrepancy looks like a plausible scale factor rather than a bug.
+
+### F4 - the active area is a dimensionless fraction, and `C_area` is skipped
+
+`geometrycorrections.area_correction` (`1/sin(delta)`) exists but is
+deliberately not applied; the numerical `beamprofile` factors are used instead.
+`BeamProfile.illuminated_area_fraction` returns
+`C_flux_on_sample / (p_max * L sin(alpha))` - the beam profile integrated over
+the projected sample, normalized to a uniform beam. It is a *fraction*, not an
+area.
+
+This is **not** a mode-equivalence problem: the active area enters both
+expressions identically and cancels from their ratio
+(`test_footprint_area_cancels_between_the_modes`). It is a problem for
+issue #15, and it hides an undocumented assumption:
+
+* With **open post-sample slits and an area detector** - orGUI's usual
+  configuration - the illuminated footprint defines the active area, it has no
+  `delta` dependence, and skipping `C_area` is right.
+  `test_the_stationary_path_recovers_the_rod_up_to_one_constant` confirms the
+  stationary path then recovers the rod shape to machine precision.
+* With **slits narrower than the footprint**,
+  `C_area = 1/(sin(delta) cos(alpha - beta_in))` applies and varies along the
+  rod. On the simulated rod above, `delta` moves from 16.77 to 16.95 degrees
+  between `l = 0.4` and `l = 3.0`, a 1.1 % shape error - small here, much
+  larger between rods at different in-plane momentum transfer.
+
+Neither the assumption nor which case a given data set is in is recorded
+anywhere in the output.
+
+### F5 - the polarization correction is evaluated at the calibrated arm position
+
+`orGUI.py:1590` and `orGUI.py:5752` build the per-pixel correction array once,
+outside the frame loop, from `dc.polarizationArray()`. That is pyFAI's
+detector-frame expression evaluated at the *calibrated* geometry.
+`DetectorCalibration.polarizationAtPoints` exists precisely because that is
+wrong for a moving detector arm, and says so in its own docstring; per-frame
+arm angles are already resolved by `backend/scans.py:scan_arm_angles` and used
+by `getROIloc` and the cursor readout.
+
+Measured at the detector centre for a specular scan whose arm follows
+`gamma = 2 alpha`, horizontally polarized beam:
+
+| 2theta | P (calibrated position) | P (arm-following) | error |
+|---|---|---|---|
+| 1 deg | 1.00000 | 0.99970 | +0.03 % |
+| 4 deg | 1.00000 | 0.99513 | +0.49 % |
+| 10 deg | 1.00000 | 0.96985 | +3.11 % |
+| 18 deg | 1.00000 | 0.90451 | +10.56 % |
+| 30 deg | 1.00000 | 0.75000 | +33.33 % |
+
+For a **fixed** arm the static array is correct - each pixel already carries
+its own scattering angle, and the apparent `alpha` dependence of the ANA
+z-axis expression is only a change of frame. The bug is scoped to scans that
+move the arm, which is exactly the reflectivity case of section 6.
+
+### F6 - solid-angle correction applied to an already-summed ROI
+
+For a ROI-summed intensity, the raw sum over pixels *is* the angular integral
+`Phi_0 T Int Int (dsigma/dOmega) dgamma dpsi`; no solid-angle correction is
+needed. orGUI multiplies the sum by the ROI-mean of `1/solidAngleArray`
+(`integration_corrections.roi_mean_correction`), which introduces a factor
+`Omega_ref / <Omega_ROI>` that varies over the detector - a few tenths of a
+percent for a detector at 1 m, several percent for a close-in detector.
+
+The solid-angle array and an angle-derived `Delta_gamma` describe the same
+geometry. Applying one without the other double-counts. When F3 is implemented,
+decide the pair together: the clean choice is **raw ROI sum plus `Delta_gamma`
+from `surfaceAnglesPoint` at the ROI edges**, with the solid-angle array
+reserved for the per-pixel reconstruction path where it is genuinely required.
+
+### F7 - `C_det` is assumed to be 1 in both modes
+
+Neither path models the in-plane detector acceptance (Vlieg sections 2.4/2.5,
+eq. 27/28). It is close to 1 for a wide ROI and a sharp in-plane profile, but
+it is **not the same** for the two modes when the rod is broad: Drnec's Fig. 18
+shows direct stationary integration underestimating `|F|` at low *l* by up to a
+factor of 2 relative to reciprocal-space integration, for exactly this reason.
+This is the one remaining mechanism that can make the two modes disagree
+*after* F1-F3 are fixed, and it is a modelling problem, not a normalization
+one.
+
+## 4. What landed
+
+### 4.1 One home for the corrections
+
+Before this branch the answer to "which factors apply to this scan" existed in
+four places, "what is the active area" in three, "what is the exposure and
+monitor divisor" in three, and the five-line per-pixel solid-angle and
+polarization block in three verbatim copies. Adding the reduction as one more
+module would have made that five, four, four and three.
+
+Everything now lives in `orgui/datautils/xrayutils/corrections/`, split by
+*what a factor depends on*, which is also what makes each piece testable on
+its own:
+
+| module | depends on |
+|---|---|
+| `geometry.py` | diffractometer angles only (the ANA/ROD z-axis table) |
+| `beamprofile.py` | the vertical profile of the incident beam |
+| `activearea.py` | beam, sample and slits |
+| `detector.py` | the calibrated detector geometry, per pixel |
+| `normalization.py` | counting time and monitor values |
+| `roi.py` | reducing per-pixel factors onto a summed region |
+| `measurement.py` | which of the above a scan mode applies |
+
+The package is physics: numbers in, numbers out. Nothing in it reads a scan
+object, a configuration or a widget. `geometrycorrections.py` and
+`beamprofile.py` at the old level were released under those names and remain
+as re-export aliases; `test_corrections_package.py` checks that the aliases
+hand out the *same objects*, not merely importable ones.
+
+`orgui/app/integration_corrections.py` is now the adapter in the other
+direction -- switch states and scan counter names in, arguments out -- and
+that boundary is written into `orgui/app/AGENTS.md`. The callers were rewired:
+`orGUI.py` builds both of its per-pixel arrays with
+`corrections.detector.pixel_factors`, `reconstruction_job.py` uses the same
+function while keeping its own native-fused application, and
+`peak1Dintegr.py` asks `measurement.mode_components` for its Lorentz and
+rod-interception factors instead of selecting them itself.
+
+### 4.2 The reduction
+
+`corrections/measurement.py` implements
+
+```
+I = Phi_0 (r_e^2 A lambda^2 / A_u^2) |F|^2 eta C_det
+```
+
+* `normalized_intensity(counts, exposure_time, monitor, angle_unit)` - F1 and
+  F2 in one place; `angle_unit="deg"` converts a rocking integral to radian.
+* `mode_components(mode, ...)` - the named factors a mode applies, and the
+  single place that mapping exists. Both integration paths call it.
+* `angular_factor(mode, ...)` - `eta`, the product of those and, for the
+  rocking modes, the acceptance. They require `detector_acceptance` and raise
+  without it (F3); `STATIONARY` *rejects* it.
+* `scale_factor(wavelength, unitcell_area, active_area, flux_density)` - the
+  prefactor, in 1/s. With the defaults it is the relative scale that makes the
+  modes agree; with the measured flux and area it is the absolute one.
+* `structure_factor_squared` / `integrated_intensity` - the reduction and its
+  exact inverse. The inverse is public because it is the forward model the
+  regression tests simulate with.
+* `reflectivity_from_structure_factor` / `structure_factor_from_reflectivity` -
+  Vlieg eq. 63, generalized to a non-specular exit angle.
+
+Units are mixed on purpose and stated at every boundary: wavelength and
+unit-cell area in Angstrom (repository convention, and what `Lattice.uc_area`
+returns), areas and flux density in meter (what the config carries). Getting
+that wrong is a factor of `1e20`, so
+`test_scale_factor_carries_its_documented_units` pins it.
+
+### 4.3 The active area, and a function that should not exist
+
+An earlier draft of this work added
+`active_area_footprint(alpha, w, h, L) = w * min(L, h/sin(alpha))`. It is
+redundant. `BeamProfile.illuminated_area_fraction` is already the mean of
+`p(z)/p_max` over the projected sample, so the absolute area is
+
+```
+A(alpha) = beam_width * sample_length * illuminated_area_fraction(alpha, L)
+```
+
+and the `min()` form is exactly this for a `top_hat_profile`, and only for
+that profile -- verified to `3.3e-16`. Extending the existing one-dimensional
+area machinery to a real area is therefore one multiplication by the beam
+width, which is what `activearea.beam_limited_area` does. The closed form was
+deleted rather than moved, and `test_corrections_activearea.py` pins both the
+identity and the fact that a Gaussian of the same width departs from it by up
+to 19 %, so it does not come back as a "simplification".
+
+`activearea.slit_limited_area` covers the other limit, built on the same
+`geometry.area_correction` the z-axis table lists, so `1/sin(delta)` also has
+one definition.
+
+**No existing number changed.** The move is behavior-preserving: the full
+suite reports the same 80 failures (all from the unbuilt native extension)
+before and after, with 782 passing against 770.
+
+### Test coverage
+
+`test_corrections_measurement.py` writes every expectation out from the papers
+rather than calling the module back - the z-axis Lorentz factors, the linear
+dependence on `Delta_gamma`, the mode ratio of eq. 65, the unit conversions,
+and the round trip through the forward model.
+
+The strongest of them is `test_reflectivity_reproduces_the_fresnel_asymptote`:
+for a semi-infinite substrate far from a bulk Bragg peak the truncation-rod
+amplitude is `|F| = rho_e A_u / q_z`, and feeding that into eq. 63 must
+reproduce the textbook `(q_c / 2 q_z)^4` with `q_c^2 = 16 pi r_e rho_e`. The
+two are algebraically identical, so the test validates the absolute scale, the
+Angstrom/meter conversions and both powers of `sin` end to end. It agrees to
+`rtol = 1e-12`.
+
+`test_scan_mode_equivalence.py` simulates the real thing: a Pt(111) `(1, 0, l)`
+rod, angles from `HKLVlieg.VliegAngles.anglesZmode`, measured as rocking scans
+(different counting time, different monitor, acceptance varying 0.7x to 1.6x
+along the rod, flat background, real `_compute_rocking_integration`
+aggregation) and as a stationary *l* scan (different counting time and monitor,
+real `integration_corrections` chain). Reduced through the new module, both
+recover the input `|F|^2` - the stationary path exactly, the rocking one to
+`1e-6`, limited only by the trapezoidal sampling of the rocking profile.
+
+`test_rocking_and_stationary_paths_differ_by_the_missing_normalizations` is a
+**characterization** test: it asserts today's gap is exactly
+`T * monitor * Delta_gamma_in_degrees`. It must be replaced by a plain equality
+when the GUI paths adopt the reduction. Its docstring says so.
+
+## 5. What is needed to close issue #82
+
+In order:
+
+1. **Normalize rocking scans.** Give `RockingPeakIntegrator.integrate` the same
+   `normalization_divisor` the stationary path uses. The per-frame counting
+   time, not the sum over the scan: the rocking angle is the integration
+   variable, the time is not. (F1)
+2. **Integrate in radian**, or divide by `180/pi` at the end. (F2)
+3. **Divide by `Delta_gamma`.** (F3) The input does not exist yet. The
+   estimator needs care and is the one piece of real design work left:
+   * The natural definition is the `gamma` span of the region of interest,
+     from `DetectorCalibration.surfaceAnglesPoint` at its edges, evaluated with
+     the per-frame arm angles from `scan_arm_angles`.
+   * A rectangular ROI in pixel coordinates is in general *rotated* with
+     respect to the `(gamma, delta)` axes. The corner-to-corner `gamma` span
+     then overestimates the acceptance at the `delta` of the rod. Decide
+     whether to take the span at fixed `delta` through the ROI centre or to
+     integrate the accepted `gamma` range over the in-plane profile.
+   * Settle F6 at the same time: raw ROI sum plus an angle-derived
+     `Delta_gamma`, or solid-angle-corrected sum plus a pixel-derived one, but
+     not a mix.
+4. **Record the mode and its inputs in the saved data**, next to `F2_hkl`: the
+   acceptance, the normalization that was applied, and the active-area
+   assumption of F4. Without them a saved rod cannot be put on a common scale
+   after the fact.
+5. **Then verify on real data.** The overlap region of a rocking scan and a
+   stationary scan on the same rod (Drnec Fig. 8, right) is the acceptance
+   test. Simulation cannot catch F7, an incorrect `Delta_gamma` definition, or
+   a beamline that reports counting time in the wrong place.
+
+## 6. What is needed to close issue #15, and reflectivity
+
+Issue #15 asks for
+`I_sc = (Phi_0 T r_e^2 A_0 lambda^2 / A_u^2) |F|^2 P L_s C_area C_det C_beam`
+with the constants put back. After section 5, what is still missing is only the
+constants:
+
+* `lambda`, `A_u`, `r_e` - already available (`UBCalculator.getLambda`,
+  `Lattice.uc_area`, `measurement.CLASSICAL_ELECTRON_RADIUS`).
+* `Phi_0` and `T` - user input. `T` is in the scan; `Phi_0` needs a flux
+  measurement and a field to put it in.
+* `A` - `active_area_footprint` needs the beam width, beam height and sample
+  length. The footprint dialog already asks for the sample size and the beam
+  profile; it does not ask for the horizontal beam width, and `C_illum_area` is
+  a fraction rather than an area (F4). Multiplying the fraction by
+  `w * min(L, h/sin(alpha))` gives the absolute area.
+* `C_det` - F7, unmodelled.
+
+**Reflectivity comes for free.**
+`R = r_e^2 lambda^2 P_r |F|^2 / (A_u^2 sin(alpha) sin(beta_out))` needs nothing
+beyond an absolutely scaled `|F|^2`, so specular reflectivity and the crystal
+truncation rods can be refined together against one model.
+
+The data container is already in place for this. `CTRplotutil` gives every
+`CTR` a frozen `MeasurementReduction` whose `quantity` is either
+`"structure_factor"` or `"reflectivity"` (the dimensionless R), and a
+`CTRScanGeometry` recording the z-mode scan rule (`fixed="in"/"out"/"eq"` plus
+the fixed angle) - which is exactly `alpha` and `beta_out`. What is missing is
+only the conversion, and that is what
+`measurement.structure_factor_from_reflectivity` now supplies: given
+`Lattice.uc_area` and the wavelength, a reflectivity rod can be turned into an
+`|F|^2` rod and joined to the truncation rods. Today every fitting, scaling,
+averaging and export path in `CTRplotutil` rejects reflectivity explicitly
+(`CTRplotutil.py:1108`, `:1497`), which is the right default while no
+conversion existed; the natural next step is a `CTR` method that performs it
+rather than relaxing those guards.
+
+Three caveats, all now in the module docstrings:
+
+1. It is the **kinematic** result. It fails near a bulk Bragg peak and below
+   the critical angle, where refraction and multiple scattering take over -
+   which is where the interesting part of a reflectivity curve usually is.
+   Compare against the DWBA machinery already in `CTRdwba.py` there.
+2. **A reflectivity scan moves the detector arm**, so F5 bites hardest here:
+   10 % at `2theta = 18` degrees, 33 % at 30 degrees. Fix F5 before trusting an
+   absolute reflectivity.
+3. **Off-specular**, `R` is the fraction of the incident flux scattered into
+   that rod. That is well defined for a truncation rod integrated across its
+   cross-section, but not for diffuse scattering, where only a differential
+   cross-section is meaningful. `reflectivity_from_structure_factor` takes a
+   `beta_out` for the first case and should not be used for the second.
+
+Also note the ANA "reflectivity rocking scan" Lorentz factor `1/sin(2 alpha)`,
+which `peak1Dintegr` already selects for a `mu` scan: that is for rocking
+*through* the specular ridge and is a different measurement from a stationary
+specular scan. Both are legitimate; they are not interchangeable, and only the
+stationary one is what `reflectivity_from_structure_factor` reduces.
+
+## 7. Open questions
+
+* **`Delta_gamma` for a rotated ROI** (section 5.3). The single piece of
+  physics not settled here.
+* **The reciprocal-space reconstruction as a third route.** Drnec section 4
+  shows that voxel binning absorbs the Lorentz factor, so a reconstructed map
+  needs `C_area`, `C_beam`, `P` and `Delta_l` but no Lorentz factor - which is
+  what `reconstruction_job.py` does, minus `Delta_l` and `C_beam`. Landing it
+  on the same absolute scale as the two direct-space modes is a third, larger
+  piece of work and was not analysed here.
+* **`C_det` (F7)** is the only remaining mechanism that can break the mode
+  equivalence after F1-F3, and it is the one that cannot be validated on
+  simulated data. It needs the real-data comparison of section 5.5.
+* **Error propagation through the new factors.** `measurement` reduces
+  intensities; the errors follow the same divisors, but a `Delta_gamma`
+  estimated from the geometry has an uncertainty of its own that nothing
+  currently tracks.
+
+## 8. Reproducing the numbers
+
+```powershell
+pytest orgui/datautils/xrayutils/test/test_corrections_measurement.py
+pytest orgui/app/test/test_scan_mode_equivalence.py
+```
+
+Note that `orgui/app/test/test_roi_sum_accel.py` fails in a checkout where the
+native ROI extension has not been built ("ROI acceleration is disabled"); that
+is unrelated to anything here.
diff --git a/doc/source/ctr_structure_factors.rst b/doc/source/ctr_structure_factors.rst
index 202bbd3..f623493 100644
--- a/doc/source/ctr_structure_factors.rst
+++ b/doc/source/ctr_structure_factors.rst
@@ -121,6 +121,23 @@ ANAROD F export, and symmetry averaging reject reflectivity explicitly. Plot
 panels select labels from the stored quantity and F/R datasets cannot share one
 axis.
 
+Converting between the two quantities is a question of scale, not of data
+handling: Vlieg (1997) equation (63) relates them by
+
+.. math::
+
+   R = \frac{r_e^2\lambda^2 P_r}
+            {A_u^2\,\sin\alpha\,\sin\beta_\mathrm{out}}\,|F_{hkl}|^2 ,
+
+with :math:`A_u` the surface unit-cell area and
+:math:`\alpha`, :math:`\beta_\mathrm{out}` the incidence and exit angles that
+``CTRScanGeometry`` already records.
+:func:`orgui.datautils.xrayutils.corrections.measurement.structure_factor_from_reflectivity`
+and its inverse implement it, so an absolutely scaled reflectivity curve and a
+set of truncation rods can be brought onto one scale before they are combined.
+The relation is kinematical: it does not hold near a bulk Bragg peak, nor below
+the critical angle, where the distorted-wave treatment of :doc:`dwba` applies.
+
 CTR fit predictions and statistics
 ----------------------------------
 
diff --git a/doc/source/image_integration.rst b/doc/source/image_integration.rst
index 35b7202..1f346f5 100644
--- a/doc/source/image_integration.rst
+++ b/doc/source/image_integration.rst
@@ -161,6 +161,52 @@ footprint and sample size". orGUI does not apply it: the footprint corrections
 below evaluate the beam profile and the finite sample size numerically
 instead, which is the row the manual marks as calculated numerically.
 
+.. _comparing-scan-modes:
+
+Comparing Scan Modes
+~~~~~~~~~~~~~~~~~~~~
+
+``F2_hkl`` is proportional to :math:`|F_{hkl}|^2` **within** one integration
+mode, but a rocking scan and a stationary scan of the same rod are not
+currently on the same scale, and the two must not be plotted or fitted
+together without rescaling.
+
+Vlieg's rocking-scan expression (equation 42) contains three factors that the
+stationary expression (equation 54) does not, and that orGUI's rocking
+integration does not divide out:
+
+* the **counting time and monitor**. ``Normalize integrated intensities``
+  applies to stationary integration only; a rocking integration is not
+  normalized.
+* the **unit of the rocking angle**. The rocking curve is integrated over the
+  motor position in degrees, while the published expressions integrate in
+  radian, a factor :math:`180/\pi`.
+* the **out-of-plane angular acceptance** :math:`\Delta\gamma` of the region
+  of interest. A rocking scan intercepts a slice of rod whose length is
+  proportional to :math:`\Delta\gamma`, so its integrated intensity is too; a
+  stationary measurement intercepts the whole rod cross-section and has no
+  such factor. Because ROIs are sized per detector position, this factor is
+  not even constant along one rocking data set, so it changes the *shape* of
+  a rod and not only its scale.
+
+Together,
+
+.. math::
+
+   \frac{F^2_{hkl,\mathrm{rocking}}}{F^2_{hkl,\mathrm{stationary}}}
+   = T\;M\;\Delta\gamma[^\circ]
+
+with :math:`T` the per-frame counting time, :math:`M` the monitor value and
+:math:`\Delta\gamma` the acceptance in degrees.
+
+:mod:`orgui.datautils.xrayutils.corrections.measurement` implements the full
+reduction, for rocking scans, stationary scans and reflectivity, and is the
+supported way to put integrated intensities from different modes on one
+scale --- and, given the incident flux and the illuminated area, on the
+absolute scale of :math:`|F_{hkl}|^2` in electron units. The integration
+paths do not use it yet.
+
+
 Exposure and Monitor Normalization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 5040fcd..6b3f8fe 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -9,6 +9,10 @@ Unreleased (2026-07-19)
 
 Scientific and analysis additions:
 
+- **All correction factors collected into one package.** Every factor between detector counts and a structure factor now lives in ``orgui.datautils.xrayutils.corrections``, split by what it depends on: ``geometry`` (the z-axis Lorentz, rod-interception and area table), ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and polarization), ``normalization`` (counting time and monitor), ``roi``, and ``measurement``. The rocking integration, the stationary integration and the reciprocal-space reconstruction previously each carried their own copy of several of these; they now share one definition, so they cannot drift onto different scales. The package is physics only -- numbers in, numbers out -- and reads no scan object, configuration or widget; ``orgui.app`` ``integration_corrections`` is the adapter that supplies those. ``orgui.datautils.xrayutils.geometrycorrections`` and ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the moved modules. **No calculated value changes.**
+
+- **One structure-factor scale for rocking scans, stationary scans, and reflectivity.** The new public module ``orgui.datautils.xrayutils.corrections.measurement`` reduces an integrated intensity to ``|F_hkl|^2`` for any scan mode, following E. Vlieg, *J. Appl. Cryst.* 30 (1997) 532 and J. Drnec et al., *J. Appl. Cryst.* 47 (2014) 365. It normalizes counts by exposure time and monitor, converts a rocking integral from degrees to radians, applies the mode-dependent angular factor (rocking scans additionally require the out-of-plane acceptance of the region of interest, stationary measurements reject it), and, given the incident flux density and the illuminated area, puts the result on the absolute electron-unit scale. It also converts between ``|F_hkl|^2`` and absolute reflectivity, so a reflectivity curve and a set of truncation rods can be brought onto one scale. **This is a new API only: no existing integration result changes.** The integration paths do not use it yet, and rocking and stationary integration remain on different scales, differing by exposure time times monitor times the acceptance in degrees; the image-integration documentation now says so explicitly, and ``doc/design/ctr_structure_factor_scale.md`` records the full analysis with the measured size of every correction.
+
 - **Unified CTR fit predictions, lifecycle, and statistics.** CTR optimizer predictions, residuals, likelihoods, and diagnostics now use one final analytically scaled result path. ``flat_prediction`` supports the common F/R result contract, while ``flat_Fcalc``, ``Rfactor``, and the new ``Rfactor_R`` enforce quantity-specific diagnostics. ``calculated_CTRs`` now always exposes the latest successful final predictions, independently of resolution broadening. Evaluation requires ``prepareFit()`` after parameter layout changes, supported fixed-model changes refresh automatically, and a failed evaluation cannot leave a stale public result. Fit statistics count eliminated analytical scales in their degrees of freedom, report covariance on the same reduced-chi-square scale as parameter errors, and clear unavailable errors throughout the fitted crystal instead of retaining an older estimate.
 
 - **Preserved signed CTR intensities during amplitude conversion.** ``CTR.convertToF`` now maps every finite intensity through ``sign(I) * sqrt(abs(I))`` instead of discarding negative measurements. Its symmetric uncertainty is half the transformed input interval, remains finite at zero, and uses a stable evaluation at high signal-to-noise. Conversion remains in place, preserves aligned metadata, applies the signed mapping to auxiliary intensity counters, and rejects reflectivity-tagged data and invalid uncertainties explicitly.

From 6959191d8baea660f755b1c8490b41fc9ffa1917 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 9 Sep 2026 18:27:01 -0400
Subject: [PATCH 04/33] feat: estimate the out-of-plane detector acceptance

---
 CHANGELOG.md                                  |  11 +
 doc/design/ctr_structure_factor_scale.md      |  46 ++-
 doc/source/release_notes.rst                  |   2 +
 orgui/datautils/xrayutils/AGENTS.md           |  10 +-
 .../xrayutils/corrections/__init__.py         |   5 +
 .../xrayutils/corrections/acceptance.py       | 255 +++++++++++++++
 .../test/test_corrections_acceptance.py       | 296 ++++++++++++++++++
 .../test/test_corrections_package.py          |   1 +
 8 files changed, 620 insertions(+), 6 deletions(-)
 create mode 100644 orgui/datautils/xrayutils/corrections/acceptance.py
 create mode 100644 orgui/datautils/xrayutils/test/test_corrections_acceptance.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c956405..e9a4bb7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,17 @@ Scientific and analysis additions:
   ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the
   moved modules. **No calculated value changes.**
 
+- **Out-of-plane detector acceptance.**
+  ``orgui.datautils.xrayutils.corrections.acceptance`` estimates
+  ``Delta_gamma``, the angular height of a region of interest as seen from the
+  sample, which a rocking-scan integrated intensity is proportional to (Vlieg
+  equations 20 and 42) and which orGUI previously did not compute at all.
+  Measured edge to edge, at the region's centre column where the rod crosses
+  the aperture, and vectorized over a scan because orGUI resizes regions per
+  detector position. ``gamma_range`` reports the span over the whole region as
+  a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row
+  case. **A new API only: the integration paths do not call it yet.**
+
 - **One structure-factor scale for rocking scans, stationary scans, and
   reflectivity.** The new public module
   ``orgui.datautils.xrayutils.corrections.measurement`` reduces an integrated
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
index 8076bfd..e6ab161 100644
--- a/doc/design/ctr_structure_factor_scale.md
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -121,8 +121,9 @@ so its integrated intensity is *proportional to the vertical angular size of
 the region of interest*. A stationary measurement has no such factor.
 
 Before this branch, `Delta_gamma` appeared nowhere in orGUI: `grep -rn
-"acceptance"` over `orgui/` returned nothing, and the integration paths still
-do not compute it. In the point-detector world it was a fixed slit setting and
+"acceptance"` over `orgui/` returned nothing. It is now estimated by
+`corrections/acceptance.py` (section 4.4), though the integration paths do
+not call it yet. In the point-detector world it was a fixed slit setting and
 disappeared into the overall scale factor. On an area detector with ROIs sized
 per detector position by `orgui/app/ROIutils.py:calc_corrections` (projected
 sample size plus a parallax correction, so it changes with `delta` and
@@ -357,6 +358,47 @@ recover the input `|F|^2` - the stationary path exactly, the rocking one to
 `T * monitor * Delta_gamma_in_degrees`. It must be replaced by a plain equality
 when the GUI paths adopt the reduction. Its docstring says so.
 
+### 4.4 The Delta_gamma estimator
+
+`corrections/acceptance.py` supplies the factor F3 says is missing. It reads
+the exit angle at the top and bottom **edges** of a region of interest with
+`Detector2D_SXRD.surfaceAnglesPoint` and returns the span:
+
+* `out_of_plane_acceptance(detector, row, column, row_size, alpha, ...)` -
+  `Delta_gamma` in radian, evaluated at the region's centre column, which is
+  where the rod crosses the aperture. Vectorized over frames, since orGUI
+  resizes regions along a scan.
+* `gamma_range(...)` - the span over the whole rectangle. It equals the
+  centre-column value when iso-gamma lines run along the detector rows, and
+  exceeds it on a rolled detector, so their ratio is a cheap check on whether
+  the estimate can be trusted.
+* `pixel_acceptance(...)` - the one-row case; the resolution limit, and the
+  natural unit to quote an acceptance in.
+
+Edges, not pixel centres: a region of `n` rows accepts `n` pixels' worth of
+angle, not `n - 1`. Using centres would understate every rocking acceptance
+by one pixel - 1 % on a 100-row region, 10 % on a 10-row one.
+
+Two things fell out of writing the tests that were not obvious beforehand:
+
+* **pyFAI requires both pixel-coordinate arrays to have the same size.** A
+  scalar column with a per-frame `row_size` - exactly what a rocking
+  integration passes - failed inside the extension with
+  `assert pos2.size == size`. The estimator broadcasts the two coordinates
+  before the call.
+* **`Delta_gamma` is nearly invariant under a detector-arm rotation.** Driving
+  the gamma arm shifts the exit angle at the region centre by the full arm
+  angle but leaves the span unchanged to nine digits, because the rotation is
+  about the axis gamma is measured around; a 40-degree delta-arm rotation
+  moves it by one part in `1e5`. This is the opposite of the polarization
+  factor of F5, where ignoring the arm is a 10 % error at 18 degrees. An
+  acceptance computed without arm bookkeeping is still usable.
+
+Measured against a calibrated 172 um detector at 1 m, a 60-row region accepts
+0.5913 degrees, matching `n * pixel / dist` to 2e-3, and shrinks by a few per
+mille towards the detector edge - the obliquity that makes `Delta_gamma` vary
+along a scan in the first place.
+
 ## 5. What is needed to close issue #82
 
 In order:
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 6b3f8fe..f1cf643 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -11,6 +11,8 @@ Scientific and analysis additions:
 
 - **All correction factors collected into one package.** Every factor between detector counts and a structure factor now lives in ``orgui.datautils.xrayutils.corrections``, split by what it depends on: ``geometry`` (the z-axis Lorentz, rod-interception and area table), ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and polarization), ``normalization`` (counting time and monitor), ``roi``, and ``measurement``. The rocking integration, the stationary integration and the reciprocal-space reconstruction previously each carried their own copy of several of these; they now share one definition, so they cannot drift onto different scales. The package is physics only -- numbers in, numbers out -- and reads no scan object, configuration or widget; ``orgui.app`` ``integration_corrections`` is the adapter that supplies those. ``orgui.datautils.xrayutils.geometrycorrections`` and ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the moved modules. **No calculated value changes.**
 
+- **Out-of-plane detector acceptance.** ``orgui.datautils.xrayutils.corrections.acceptance`` estimates ``Delta_gamma``, the angular height of a region of interest as seen from the sample, which a rocking-scan integrated intensity is proportional to (Vlieg equations 20 and 42) and which orGUI previously did not compute at all. Measured edge to edge, at the region's centre column where the rod crosses the aperture, and vectorized over a scan because orGUI resizes regions per detector position. ``gamma_range`` reports the span over the whole region as a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row case. **A new API only: the integration paths do not call it yet.**
+
 - **One structure-factor scale for rocking scans, stationary scans, and reflectivity.** The new public module ``orgui.datautils.xrayutils.corrections.measurement`` reduces an integrated intensity to ``|F_hkl|^2`` for any scan mode, following E. Vlieg, *J. Appl. Cryst.* 30 (1997) 532 and J. Drnec et al., *J. Appl. Cryst.* 47 (2014) 365. It normalizes counts by exposure time and monitor, converts a rocking integral from degrees to radians, applies the mode-dependent angular factor (rocking scans additionally require the out-of-plane acceptance of the region of interest, stationary measurements reject it), and, given the incident flux density and the illuminated area, puts the result on the absolute electron-unit scale. It also converts between ``|F_hkl|^2`` and absolute reflectivity, so a reflectivity curve and a set of truncation rods can be brought onto one scale. **This is a new API only: no existing integration result changes.** The integration paths do not use it yet, and rocking and stationary integration remain on different scales, differing by exposure time times monitor times the acceptance in degrees; the image-integration documentation now says so explicitly, and ``doc/design/ctr_structure_factor_scale.md`` records the full analysis with the measured size of every correction.
 
 - **Unified CTR fit predictions, lifecycle, and statistics.** CTR optimizer predictions, residuals, likelihoods, and diagnostics now use one final analytically scaled result path. ``flat_prediction`` supports the common F/R result contract, while ``flat_Fcalc``, ``Rfactor``, and the new ``Rfactor_R`` enforce quantity-specific diagnostics. ``calculated_CTRs`` now always exposes the latest successful final predictions, independently of resolution broadening. Evaluation requires ``prepareFit()`` after parameter layout changes, supported fixed-model changes refresh automatically, and a failed evaluation cannot leave a stale public result. Fit statistics count eliminated analytical scales in their degrees of freedom, report covariance on the same reduced-chi-square scale as parameter errors, and clear unavailable errors throughout the fitted crystal instead of retaining an older estimate.
diff --git a/orgui/datautils/xrayutils/AGENTS.md b/orgui/datautils/xrayutils/AGENTS.md
index 317c00b..d60cb6a 100644
--- a/orgui/datautils/xrayutils/AGENTS.md
+++ b/orgui/datautils/xrayutils/AGENTS.md
@@ -24,10 +24,12 @@ This directory contains the highest-risk scientific code:
   this file.
 - `corrections/`: every factor between detector counts and a structure factor
   -- `geometry.py` (z-axis Lorentz/rod-interception/area table),
-  `beamprofile.py`, `activearea.py`, `detector.py` (per-pixel solid angle and
-  polarization), `normalization.py` (counting time and monitor), `roi.py`,
-  and `measurement.py` (which factors each scan mode applies, and the
-  reduction to `|F_hkl|^2` and absolute reflectivity). The rocking
+  `beamprofile.py`, `activearea.py`, `acceptance.py` (the out-of-plane
+  `Delta_gamma` a rocking scan is proportional to), `detector.py` (per-pixel
+  solid angle and polarization), `normalization.py` (counting time and
+  monitor), `roi.py`, and `measurement.py` (which factors each scan mode
+  applies, and the reduction to `|F_hkl|^2` and absolute reflectivity). The
+  rocking
   integration, the stationary integration and the reconstruction all correct
   their data through this package, so a factor must be defined here once
   rather than per caller. `geometrycorrections.py` and `beamprofile.py` at
diff --git a/orgui/datautils/xrayutils/corrections/__init__.py b/orgui/datautils/xrayutils/corrections/__init__.py
index f530ffd..03ff0cd 100644
--- a/orgui/datautils/xrayutils/corrections/__init__.py
+++ b/orgui/datautils/xrayutils/corrections/__init__.py
@@ -50,6 +50,9 @@
 :mod:`~.activearea`
     The illuminated active surface area :math:`A`, in square meter, in both
     the slit-limited and the beam-limited case.
+:mod:`~.acceptance`
+    How much of a rod a region of interest accepts: the out-of-plane
+    :math:`\Delta\gamma` a rocking scan is proportional to.
 :mod:`~.detector`
     Per-pixel factors of a detector image: solid angle and polarization.
 :mod:`~.normalization`
@@ -72,6 +75,7 @@
 """
 
 from . import (  # noqa: F401
+    acceptance,
     activearea,
     beamprofile,
     detector,
@@ -82,6 +86,7 @@
 )
 
 __all__ = [
+    "acceptance",
     "activearea",
     "beamprofile",
     "detector",
diff --git a/orgui/datautils/xrayutils/corrections/acceptance.py b/orgui/datautils/xrayutils/corrections/acceptance.py
new file mode 100644
index 0000000..95c23a9
--- /dev/null
+++ b/orgui/datautils/xrayutils/corrections/acceptance.py
@@ -0,0 +1,255 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+r"""How much of a diffraction rod a region of interest accepts.
+
+A rocking scan does not measure a whole rod. It intercepts a slice of one,
+and the slice is as long as the detector aperture is wide in the out-of-plane
+direction: :math:`\Delta l = C_\mathrm{rod}\,(V_u / \lambda A_u)\,\Delta\gamma`
+(E. Vlieg, *J. Appl. Cryst.* **30** (1997) 532, equation 20). Its integrated
+intensity is therefore **proportional to** :math:`\Delta\gamma`, which is why
+:func:`~.measurement.angular_factor` refuses to reduce a rocking scan without
+one. A stationary measurement integrates across the whole rod cross-section
+and has no such factor.
+
+With a point detector :math:`\Delta\gamma` was a slit setting: fixed for a
+whole experiment, and absorbed into the overall scale factor nobody had to
+know. On an area detector it is a property of the *region of interest*, and
+orGUI sizes regions of interest per detector position
+(:func:`orgui.app.ROIutils.calc_corrections` scales them with the projected
+sample size and a parallax correction). It is therefore not constant along a
+scan, and leaving it out changes the shape of a rod, not only its scale.
+
+What this module computes is the angular height of the region of interest as
+seen from the sample, in the surface frame, from the calibrated detector
+geometry. It is a geometric estimate: it assumes the region is centered on
+the rod and that the rod runs along the region's vertical direction. Both
+hold for the regions orGUI places from a calculated reflection position, and
+:func:`gamma_range` measures how well by reporting the span over the whole
+region.
+
+The in-plane counterpart, Vlieg's :math:`C_\mathrm{det}` (his section 2.4),
+is the other half of the detector acceptance and is not implemented yet; a
+region wide enough to contain the whole in-plane peak profile has
+:math:`C_\mathrm{det} = 1`, which is what the reduction assumes.
+
+.. note::
+
+    :math:`\Delta\gamma` is almost invariant under a detector-arm rotation.
+    Driving the :math:`\gamma` arm shifts the exit angle at the region center
+    by the full arm angle, but leaves the span that region subtends unchanged
+    to nine digits, because the rotation is about the axis :math:`\gamma` is
+    measured around; a :math:`\delta`-arm rotation of 40 degrees moves it by
+    one part in :math:`10^5`. So an acceptance computed without the arm is
+    still usable, which is the opposite of the polarization factor, where
+    ignoring the arm is a 10 % error at a scattering angle of 18 degrees (see
+    :mod:`~.detector`). Pass the arm anyway where it is known -- it costs
+    nothing -- but a missing arm is not a reason to distrust an acceptance.
+"""
+
+import numpy as np
+
+__all__ = [
+    "gamma_range",
+    "out_of_plane_acceptance",
+    "pixel_acceptance",
+]
+
+
+def _surface_gamma(detector, row, column, alpha, gamma_arm=None, delta_arm=None):
+    """Surface-frame exit angle at the given detector points, in radian.
+
+    Isolates the one call into
+    :meth:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD.surfaceAnglesPoint`,
+    whose first argument is pyFAI dimension 1 -- the detector **row**, not a
+    horizontal coordinate -- so the ordering is stated once rather than at
+    every call site.
+
+    The two coordinates are broadcast against each other first. pyFAI asserts
+    that they have the same size, so a scan of per-frame region heights at
+    one fixed column -- which is what a rocking integration passes -- would
+    otherwise fail inside the extension with ``pos2.size == size``.
+    """
+    row, column = np.broadcast_arrays(
+        np.asarray(row, dtype=np.float64),
+        np.asarray(column, dtype=np.float64),
+    )
+    gamma, _delta = detector.surfaceAnglesPoint(
+        np.ascontiguousarray(row),
+        np.ascontiguousarray(column),
+        alpha,
+        gamma_arm,
+        delta_arm,
+    )
+    return np.asarray(gamma, dtype=np.float64)
+
+
+def out_of_plane_acceptance(
+    detector,
+    row,
+    column,
+    row_size,
+    alpha,
+    gamma_arm=None,
+    delta_arm=None,
+):
+    r"""Out-of-plane angular acceptance :math:`\Delta\gamma`, in radian.
+
+    The exit-angle span between the top and bottom **edges** of a region of
+    interest, evaluated at its center column. Edges, not pixel centers: a
+    region of ``row_size`` rows accepts photons from ``row - row_size/2`` to
+    ``row + row_size/2``, and using the centers would understate the
+    acceptance by one pixel.
+
+    The center column is the right place to measure it because the region is
+    centered on the rod, and it is the range of :math:`\gamma` over which
+    *the rod* crosses the aperture that sets the intercepted rod length.
+    Where the detector is rotated enough that the rod does not run along the
+    region's columns, this underestimates the span; :func:`gamma_range`
+    reports the span over the whole region so the two can be compared.
+
+    :param detector: A
+        :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`,
+        or anything with the same ``surfaceAnglesPoint`` contract.
+    :param row: Center row of the region, in pixels along pyFAI dimension 1.
+        Scalar or one value per frame.
+    :param column: Center column of the region, in pixels along pyFAI
+        dimension 2. Scalar or one value per frame.
+    :param row_size: Height of the region, in pixels. Scalar or one value per
+        frame -- orGUI resizes regions along a scan, so this is normally an
+        array.
+    :param alpha: Incidence angle of the frame, in radian.
+    :param gamma_arm: Detector arm position, in radian; ``None`` is the
+        calibrated position. Give both arm angles or neither.
+    :param delta_arm: Detector arm position, in radian; ``None`` is the
+        calibrated position.
+    :returns: :math:`\Delta\gamma` in radian, broadcast over the inputs and
+        always positive.
+    :rtype: numpy.ndarray
+    :raises ValueError: If a region height is not positive, or exactly one
+        arm angle is given.
+    """
+    row = np.asarray(row, dtype=np.float64)
+    column = np.asarray(column, dtype=np.float64)
+    row_size = np.asarray(row_size, dtype=np.float64)
+    if np.any(row_size <= 0) or not np.all(np.isfinite(row_size)):
+        raise ValueError(
+            "the region of interest must have a positive height in pixels; "
+            f"got {row_size!r}"
+        )
+    half = row_size / 2.0
+    lower = _surface_gamma(
+        detector, row - half, column, alpha, gamma_arm, delta_arm
+    )
+    upper = _surface_gamma(
+        detector, row + half, column, alpha, gamma_arm, delta_arm
+    )
+    return np.abs(upper - lower)
+
+
+def gamma_range(
+    detector,
+    row,
+    column,
+    row_size,
+    column_size,
+    alpha,
+    gamma_arm=None,
+    delta_arm=None,
+):
+    r"""Exit-angle span over a whole rectangular region, in radian.
+
+    The corner-to-corner :math:`\gamma` extent, as opposed to the
+    center-column extent :func:`out_of_plane_acceptance` returns. The two
+    agree when lines of constant :math:`\gamma` run along the detector rows;
+    they separate when the detector is rotated about the beam, and the ratio
+    is a cheap diagnostic for whether the acceptance estimate can be trusted.
+
+    Evaluated at the four corners: :math:`\gamma` is monotonic in both pixel
+    directions over a region small enough to hold one reflection, so the
+    extremes are corners.
+
+    :param detector: A
+        :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`.
+    :param row: Center row of the region, in pixels.
+    :param column: Center column of the region, in pixels.
+    :param row_size: Height of the region, in pixels.
+    :param column_size: Width of the region, in pixels.
+    :param alpha: Incidence angle of the frame, in radian.
+    :param gamma_arm: Detector arm position, in radian.
+    :param delta_arm: Detector arm position, in radian.
+    :returns: The full span, broadcast over the inputs and always positive.
+    :rtype: numpy.ndarray
+    :raises ValueError: If a region size is not positive.
+    """
+    row = np.asarray(row, dtype=np.float64)
+    column = np.asarray(column, dtype=np.float64)
+    row_size = np.asarray(row_size, dtype=np.float64)
+    column_size = np.asarray(column_size, dtype=np.float64)
+    for name, value in (("height", row_size), ("width", column_size)):
+        if np.any(value <= 0) or not np.all(np.isfinite(value)):
+            raise ValueError(
+                f"the region of interest must have a positive {name} in "
+                f"pixels; got {value!r}"
+            )
+    half_row = row_size / 2.0
+    half_column = column_size / 2.0
+    corners = [
+        _surface_gamma(
+            detector,
+            row + dr * half_row,
+            column + dc * half_column,
+            alpha,
+            gamma_arm,
+            delta_arm,
+        )
+        for dr in (-1.0, 1.0)
+        for dc in (-1.0, 1.0)
+    ]
+    stacked = np.stack(np.broadcast_arrays(*corners))
+    return np.max(stacked, axis=0) - np.min(stacked, axis=0)
+
+
+def pixel_acceptance(detector, row, column, alpha, gamma_arm=None, delta_arm=None):
+    r"""Exit-angle height of a single pixel, in radian.
+
+    The :math:`\gamma` subtended by one pixel row at the given position: the
+    resolution limit of :func:`out_of_plane_acceptance`, and the natural unit
+    to express a region's acceptance in. A region of ``n`` rows on a flat
+    detector viewed near its normal accepts about ``n`` times this; the ratio
+    departs from ``n`` exactly where the detector is oblique, which is the
+    effect that makes the acceptance vary along a scan.
+
+    :param detector: A
+        :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`.
+    :param row: Row of the pixel, in pixels.
+    :param column: Column of the pixel, in pixels.
+    :param alpha: Incidence angle of the frame, in radian.
+    :param gamma_arm: Detector arm position, in radian.
+    :param delta_arm: Detector arm position, in radian.
+    :returns: The angular height of that pixel, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    """
+    return out_of_plane_acceptance(
+        detector, row, column, 1.0, alpha, gamma_arm, delta_arm
+    )
diff --git a/orgui/datautils/xrayutils/test/test_corrections_acceptance.py b/orgui/datautils/xrayutils/test/test_corrections_acceptance.py
new file mode 100644
index 0000000..c8cf5c9
--- /dev/null
+++ b/orgui/datautils/xrayutils/test/test_corrections_acceptance.py
@@ -0,0 +1,296 @@
+"""Regression tests for the out-of-plane detector acceptance.
+
+:mod:`orgui.datautils.xrayutils.corrections.acceptance` estimates the
+:math:`\\Delta\\gamma` that a rocking-scan integrated intensity is
+proportional to (E. Vlieg, *J. Appl. Cryst.* **30** (1997) 532, equations 20
+and 42). See ``doc/design/ctr_structure_factor_scale.md`` finding F3.
+"""
+
+import numpy as np
+import pytest
+
+pyFAI = pytest.importorskip("pyFAI")
+
+from orgui.datautils.xrayutils import DetectorCalibration  # noqa: E402
+from orgui.datautils.xrayutils.corrections import acceptance  # noqa: E402
+
+#: Pixel size and distance of the calibrated test detector, in meter.
+PIXEL, DIST = 172e-6, 1.0
+SHAPE = (619, 487)
+
+
+class _LinearDetector:
+    """A detector whose exit angle is an exact linear function of the row.
+
+    Lets every expectation below be written in closed form, independently of
+    the pyFAI geometry, so a failure points at this module rather than at the
+    detector calibration.
+    """
+
+    #: Radian per row, and per column to make the two directions separable.
+    PER_ROW = 1e-4
+    PER_COLUMN = 3e-5
+
+    def surfaceAnglesPoint(self, x, y, alpha_i, gamma_arm=None, delta_arm=None):
+        # First argument is pyFAI dimension 1, the row.
+        arm = 0.0 if gamma_arm is None else gamma_arm
+        gamma = self.PER_ROW * np.asarray(x) + self.PER_COLUMN * np.asarray(y)
+        return gamma + arm - np.asarray(alpha_i), np.zeros_like(gamma)
+
+
+def _calibrated_detector(rot3=0.0):
+    """A real, calibrated area detector one meter from the sample."""
+    det = DetectorCalibration.Detector2D_SXRD()
+    det.detector = pyFAI.detectors.Detector(
+        pixel1=PIXEL, pixel2=PIXEL, max_shape=SHAPE
+    )
+    det.poni1 = SHAPE[0] * PIXEL / 2.0
+    det.poni2 = SHAPE[1] * PIXEL / 2.0
+    det.rot1 = det.rot2 = 0.0
+    det.rot3 = rot3
+    det.dist = DIST
+    det.set_energy(17.7)
+    det.setAzimuthalReference(np.deg2rad(90.0))
+    det.setPolarization(0.0, 1.0)
+    det.reset()
+    det._cached_array = {}
+    return det
+
+
+def test_acceptance_is_measured_edge_to_edge_not_centre_to_centre():
+    """A region of ``n`` rows accepts ``n`` pixels' worth, not ``n - 1``.
+
+    The aperture is the outer pixel boundaries. Measuring between the centres
+    of the first and last row would understate every rocking acceptance by
+    one pixel, which is a 1 % error on a 100-row region and 10 % on a 10-row
+    one.
+    """
+    det = _LinearDetector()
+
+    for rows in (1.0, 4.0, 64.0):
+        got = acceptance.out_of_plane_acceptance(det, 300.0, 240.0, rows, 0.0)
+        np.testing.assert_allclose(got, rows * det.PER_ROW, rtol=1e-12)
+
+
+def test_acceptance_is_evaluated_at_the_centre_column():
+    """Where the region sits in-plane must not change its rod acceptance.
+
+    The rod crosses the aperture at the region's centre column, so the column
+    the acceptance is read at is the centre one. On a detector whose gamma
+    also varies along a row, reading it anywhere else would leak the in-plane
+    position into an out-of-plane quantity.
+    """
+    det = _LinearDetector()
+
+    at_left = acceptance.out_of_plane_acceptance(det, 300.0, 10.0, 40.0, 0.0)
+    at_right = acceptance.out_of_plane_acceptance(det, 300.0, 470.0, 40.0, 0.0)
+
+    np.testing.assert_allclose(at_left, at_right, rtol=1e-12)
+    np.testing.assert_allclose(at_left, 40.0 * det.PER_ROW, rtol=1e-12)
+
+
+def test_acceptance_is_positive_and_vectorized_over_a_scan():
+    """orGUI resizes regions along a scan, so this is normally an array.
+
+    Both the centre and the size vary per frame, and the result must follow
+    both without a Python loop and without picking up a sign from the
+    direction the rows run in.
+    """
+    det = _LinearDetector()
+    row = np.array([100.0, 300.0, 500.0])
+    size = np.array([20.0, 45.0, 80.0])
+
+    got = acceptance.out_of_plane_acceptance(det, row, 240.0, size, 0.0)
+
+    assert got.shape == (3,)
+    assert np.all(got > 0)
+    np.testing.assert_allclose(got, size * det.PER_ROW, rtol=1e-12)
+
+
+def test_a_zero_or_negative_region_is_rejected():
+    """An empty region accepts no rod, and silently returning 0 would divide."""
+    det = _LinearDetector()
+
+    with pytest.raises(ValueError, match="positive height in pixels"):
+        acceptance.out_of_plane_acceptance(det, 300.0, 240.0, 0.0, 0.0)
+    with pytest.raises(ValueError, match="positive height in pixels"):
+        acceptance.out_of_plane_acceptance(det, 300.0, 240.0, -5.0, 0.0)
+
+
+def test_pixel_acceptance_is_the_one_row_case():
+    """The resolution limit, and the unit a region's acceptance is read in."""
+    det = _LinearDetector()
+
+    one = acceptance.pixel_acceptance(det, 300.0, 240.0, 0.0)
+    many = acceptance.out_of_plane_acceptance(det, 300.0, 240.0, 32.0, 0.0)
+
+    np.testing.assert_allclose(one, det.PER_ROW, rtol=1e-12)
+    np.testing.assert_allclose(many / one, 32.0, rtol=1e-12)
+
+
+def test_gamma_range_matches_the_column_span_when_rows_are_iso_gamma():
+    """With no roll about the beam, the two estimates agree.
+
+    ``gamma_range`` covers the whole rectangle; ``out_of_plane_acceptance``
+    only its centre column. They coincide exactly when lines of constant
+    gamma run along the detector rows, which is what makes their ratio a
+    usable diagnostic.
+    """
+    det = _calibrated_detector(rot3=0.0)
+    row, column, height, width = 300.0, 240.0, 60.0, 40.0
+    alpha = np.deg2rad(0.6)
+
+    column_span = acceptance.out_of_plane_acceptance(
+        det, row, column, height, alpha
+    )
+    full_span = acceptance.gamma_range(
+        det, row, column, height, width, alpha
+    )
+
+    np.testing.assert_allclose(full_span, column_span, rtol=1e-4)
+
+
+def test_gamma_range_exceeds_the_column_span_on_a_rolled_detector():
+    """Rolling the detector tilts the iso-gamma lines off the rows.
+
+    Then the corners reach further in gamma than the centre column does, and
+    the centre-column estimate is the one to trust for a rod-centred region
+    while the ratio warns that the geometry is no longer aligned.
+    """
+    det = _calibrated_detector(rot3=np.deg2rad(20.0))
+    row, column, height, width = 300.0, 240.0, 60.0, 120.0
+    alpha = np.deg2rad(0.6)
+
+    column_span = acceptance.out_of_plane_acceptance(
+        det, row, column, height, alpha
+    )
+    full_span = acceptance.gamma_range(
+        det, row, column, height, width, alpha
+    )
+
+    assert full_span > column_span * 1.2
+
+
+def test_acceptance_scales_with_region_height_on_a_real_detector():
+    """A calibrated detector one meter away, checked against small-angle optics.
+
+    Near the beam centre a flat detector subtends ``pixel / dist`` per row to
+    first order, so a region of ``n`` rows accepts about ``n * pixel / dist``.
+    This pins the units -- radian, not degrees or pixels -- against a number
+    written down from the geometry rather than from the code.
+    """
+    det = _calibrated_detector()
+    alpha = np.deg2rad(0.6)
+    heights = np.array([10.0, 50.0, 200.0])
+
+    got = acceptance.out_of_plane_acceptance(
+        det, SHAPE[0] / 2.0, SHAPE[1] / 2.0, heights, alpha
+    )
+
+    np.testing.assert_allclose(got, heights * PIXEL / DIST, rtol=2e-3)
+    # Linear in the height to the same order.
+    np.testing.assert_allclose(got / heights, got[0] / heights[0], rtol=2e-3)
+
+
+def test_acceptance_shrinks_where_the_detector_is_oblique():
+    """The reason Delta_gamma is not constant along a scan.
+
+    Away from the detector normal the same number of rows subtends less
+    angle. A region that keeps its pixel size therefore accepts a shorter
+    piece of rod as the reflection moves up the detector, and a rocking scan
+    that ignores this reports a rod whose shape follows the detector.
+    """
+    det = _calibrated_detector()
+    alpha = np.deg2rad(0.6)
+    centre = acceptance.out_of_plane_acceptance(
+        det, SHAPE[0] / 2.0, SHAPE[1] / 2.0, 60.0, alpha
+    )
+    edge = acceptance.out_of_plane_acceptance(det, 40.0, SHAPE[1] / 2.0, 60.0, alpha)
+
+    assert edge < centre
+    assert 0.95 < edge / centre < 0.999
+
+
+def test_a_moving_arm_barely_changes_the_acceptance():
+    """Delta_gamma survives a moving arm; the polarization factor does not.
+
+    Driving the gamma arm moves the region to a completely different exit
+    angle -- gamma at the region center shifts by the full arm angle -- but
+    the *span* the region subtends is unchanged, because that rotation is
+    about the very axis gamma is measured around. A delta-arm rotation and an
+    off-center column break the invariance only in the fifth digit.
+
+    This is worth pinning because it is the opposite of the polarization
+    factor, where evaluating at the calibrated position instead of the real
+    one is a 10 % error at a scattering angle of 18 degrees and 33 % at 30
+    (see finding F5). An acceptance estimated with the arm left out is fine;
+    a polarization is not.
+    """
+    det = _calibrated_detector()
+    alpha = np.deg2rad(0.6)
+    row, column = SHAPE[0] / 2.0, SHAPE[1] / 2.0
+    arm = np.deg2rad(25.0)
+
+    at_home = det.surfaceAnglesPoint(np.array([row]), np.array([column]), alpha)[0]
+    at_arm = det.surfaceAnglesPoint(
+        np.array([row]), np.array([column]), alpha, arm, 0.0
+    )[0]
+    np.testing.assert_allclose(at_arm - at_home, arm, atol=1e-9)
+
+    home = acceptance.out_of_plane_acceptance(det, row, column, 60.0, alpha)
+    moved = acceptance.out_of_plane_acceptance(
+        det, row, column, 60.0, alpha, gamma_arm=arm, delta_arm=0.0
+    )
+    np.testing.assert_allclose(moved, home, rtol=1e-9)
+
+    tilted = acceptance.out_of_plane_acceptance(
+        det, row, column, 60.0, alpha, gamma_arm=0.0, delta_arm=np.deg2rad(40.0)
+    )
+    np.testing.assert_allclose(tilted, home, rtol=1e-4)
+    assert not np.isclose(tilted, home, rtol=1e-9)
+
+
+def test_one_arm_angle_alone_is_rejected():
+    """The calibration reference is a rotation, not two independent offsets."""
+    det = _calibrated_detector()
+
+    with pytest.raises(ValueError, match="both gamma_arm and delta_arm"):
+        acceptance.out_of_plane_acceptance(
+            det,
+            SHAPE[0] / 2.0,
+            SHAPE[1] / 2.0,
+            60.0,
+            np.deg2rad(0.6),
+            gamma_arm=np.deg2rad(25.0),
+        )
+
+
+def test_the_acceptance_is_what_the_reduction_asks_for():
+    """It plugs straight into the rocking angular factor.
+
+    ``angular_factor`` refuses a rocking scan without an acceptance and
+    demands radian; this is the function that supplies it, so the two are
+    checked together rather than each against its own convention.
+    """
+    from orgui.datautils.xrayutils.corrections import measurement
+
+    det = _calibrated_detector()
+    alpha = np.deg2rad(0.6)
+    delta, gamma = np.deg2rad(16.8), np.deg2rad(5.3)
+
+    d_gamma = acceptance.out_of_plane_acceptance(
+        det, SHAPE[0] / 2.0, SHAPE[1] / 2.0, 60.0, alpha
+    )
+    eta = measurement.angular_factor(
+        measurement.ROCKING,
+        alpha=alpha,
+        delta=delta,
+        gamma=gamma,
+        detector_acceptance=d_gamma,
+    )
+
+    components = measurement.mode_components(
+        measurement.ROCKING, alpha=alpha, delta=delta, gamma=gamma
+    )
+    expected = components["C_Lorentz"] * components["C_rod"] * d_gamma
+    np.testing.assert_allclose(eta, expected, rtol=1e-12)
diff --git a/orgui/datautils/xrayutils/test/test_corrections_package.py b/orgui/datautils/xrayutils/test/test_corrections_package.py
index bd940db..8116ed4 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_package.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_package.py
@@ -43,6 +43,7 @@ def polarizationArray(self):
 def test_the_package_exposes_every_correction_module():
     """A maintainer looking for a correction factor finds them in one place."""
     assert set(corrections.__all__) == {
+        "acceptance",
         "activearea",
         "beamprofile",
         "detector",

From ecb3bb593fa841f75d8faf19c2eeb453ac4c87a5 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Thu, 10 Sep 2026 10:56:03 -0400
Subject: [PATCH 05/33] docs: settle F6 and add the structure-factor physics
 reference

---
 doc/design/ctr_structure_factor_handover.md   | 271 +++++++
 doc/design/ctr_structure_factor_scale.md      | 159 +++-
 doc/physics/.gitignore                        |  10 +
 doc/physics/ctr_structure_factor_physics.tex  | 745 ++++++++++++++++++
 .../test/test_corrections_acceptance.py       |  53 ++
 5 files changed, 1208 insertions(+), 30 deletions(-)
 create mode 100644 doc/design/ctr_structure_factor_handover.md
 create mode 100644 doc/physics/.gitignore
 create mode 100644 doc/physics/ctr_structure_factor_physics.tex

diff --git a/doc/design/ctr_structure_factor_handover.md b/doc/design/ctr_structure_factor_handover.md
new file mode 100644
index 0000000..bdde295
--- /dev/null
+++ b/doc/design/ctr_structure_factor_handover.md
@@ -0,0 +1,271 @@
+# CTR structure-factor scale: implementation status and handover
+
+> **Status as of 2026-09-09.** Branch `claude/ctr-structure-factor-9633bc`,
+> four commits ahead of `master`, nothing pushed.
+>
+> The physics analysis is complete and quantified, the reduction and the
+> acceptance estimator exist and are tested, and the correction factors have
+> one home. **No saved number has changed yet**: the GUI integration paths do
+> not call any of the new reduction. Issues
+> [#82](https://github.com/tifuchs/orGUI/issues/82) and
+> [#15](https://github.com/tifuchs/orGUI/issues/15) are therefore *analysed and
+> equipped* but not closed.
+>
+> This document is the handover: what exists, how to run it, what to do next,
+> and which of my predictions turned out wrong. The physics itself is in
+> [`ctr_structure_factor_scale.md`](ctr_structure_factor_scale.md) — read that
+> first for *why*; this one is *where things stand*.
+
+## 1. The one-paragraph summary
+
+A rocking scan and a stationary scan of the same rod do not currently produce
+the same `F2_hkl` in orGUI. The ratio is exactly
+`T_omega * monitor_omega * Delta_gamma_in_degrees`, measured to seven digits on
+simulated data. Three things are missing from the rocking path: exposure/monitor
+normalization, integration in radian rather than degrees, and division by the
+out-of-plane detector acceptance. All three now have working implementations in
+`orgui/datautils/xrayutils/corrections/`; none of them is wired in. A fourth,
+F6, affects **both** modes: a ROI sum is already a complete angular integral,
+so the solid-angle correction has to stop being applied to it, or the two
+modes stay apart by `<1/Omega~>` even after the rocking path is fixed.
+
+## 2. What is on the branch
+
+| commit | what it did |
+|---|---|
+| `777d887` | `refactor: collect correction factors into one corrections package` |
+| `4193c80` | `feat: reduce integrated intensities to \|F_hkl\|^2 on one scale` |
+| `e25b8df` | `docs: record the rocking/stationary structure-factor scale analysis` |
+| `6959191` | `feat: estimate the out-of-plane detector acceptance` |
+
+The first three were split out of one working tree at the end, which required
+*staged versions* of four files: `peak1Dintegr.py`, `integration_corrections.py`,
+`corrections/__init__.py` and `test_corrections_package.py` all reference
+`measurement`, which only exists from `4193c80`. In `777d887` they keep the old
+inline Lorentz selection with only the import path updated. Each commit was
+verified green on its own, not just the tip.
+
+### 2.1 The package
+
+```
+orgui/datautils/xrayutils/corrections/
+  geometry.py       219   z-axis Lorentz x3, rod interception, area factor
+  beamprofile.py   1049   beam profile shapes and their integrals
+  activearea.py     190   active area in m^2, slit- and beam-limited
+  acceptance.py     255   Delta_gamma, gamma_range, pixel_acceptance
+  detector.py        89   per-pixel solid angle and polarization
+  normalization.py  103   counting time and monitor, from values
+  roi.py             93   CorrectionFactors, roi_mean_correction
+  measurement.py    605   mode dispatch, master equation, reflectivity
+```
+
+`orgui/datautils/xrayutils/geometrycorrections.py` and `beamprofile.py` remain
+as re-export aliases because both were released under those names.
+`test_corrections_package.py` asserts the aliases hand out the *same objects*,
+not merely that they import.
+
+### 2.2 What is wired, and what is not
+
+| caller | uses the package for | still does its own thing |
+|---|---|---|
+| `orGUI.integrateROI` (stationary) | `pixel_factors`, `mode_components`, `normalization_divisor`, `C_illum_area` | — |
+| `orGUI.rocking_integrate` | `pixel_factors` | — |
+| `peak1Dintegr.integrate` (rocking) | `mode_components` | **no normalization, degrees, no `Delta_gamma`** |
+| `reconstruction_job` | `pixel_factors` | own native-fused application, own normalization loop |
+
+Nothing calls `measurement.structure_factor_squared`,
+`measurement.normalized_intensity`, `measurement.angular_factor`,
+`activearea.*` or `acceptance.*` outside the tests. That is the gap to close.
+
+## 3. Getting a green test run
+
+**A fresh checkout reports ~80 failures.** They are all the unbuilt native
+extension, not the branch. With the extensions built the suite is
+**1120 passed, 3 skipped, 0 failed** (the 3 skips are a missing `arviz`).
+Building also *unlocks* roughly 230 tests that are not collected at all
+without it, so the unbuilt number is not simply "the green ones".
+
+The environment on this machine is Python 3.14.7 (miniforge) with a working
+orGUI already installed in `miniforge3\Lib\site-packages`. **Do not
+`pip install -e .`** — it rebinds `import orgui` for that interpreter and the
+repository owner wants the installed copy left alone. Build out of tree and
+stage instead:
+
+```powershell
+# build dir must be SHORT: a path under the session scratchpad overruns
+# MAX_PATH and meson dies in check_clock_skew with a FileNotFoundError
+$vc = 'C:\Program Files\Microsoft Visual Studio\18\Community\VC\Auxiliary\Build\vcvars64.bat'
+$mf = 'C:\Users\timof\miniforge3'
+$pre = "$mf;$mf\Scripts;$mf\Library\bin"
+cmd /v:on /c "`"$vc`" >nul 2>&1 && set PATH=$pre;!PATH! && meson setup C:\Users\timof\obuild --buildtype=release"
+cmd /v:on /c "`"$vc`" >nul 2>&1 && set PATH=$pre;!PATH! && meson compile -C C:\Users\timof\obuild"
+cmd /v:on /c "`"$vc`" >nul 2>&1 && set PATH=$pre;!PATH! && meson install -C C:\Users\timof\obuild --destdir C:\Users\timof\ostage"
+
+cd C:\Users\timof\ostage\Lib\site-packages
+python -m pytest orgui/app/test orgui/datautils/xrayutils/test -q
+```
+
+Four traps, each of which cost an attempt:
+
+1. `cl` is not on PATH; `vcvars64.bat` is required. It prints a harmless
+   `'vswhere.exe' is not recognized` line and works anyway.
+2. **`%PATH%` expands at parse time.** `vcvars && set PATH=<conda>;%PATH%`
+   silently discards everything vcvars added, and meson then reports
+   `Unknown compiler(s)`. Hence `cmd /v:on` and `!PATH!`.
+3. meson and python are not on cmd's PATH even though they are on the bash
+   shell's. The interpreter is in the miniforge root, the entry points in
+   `Scripts`.
+4. MAX_PATH, as above.
+
+Do **not** copy the built `.pyd` into `orgui/` to make the worktree importable.
+`install_subdir('orgui', ...)` ships whatever is in the source tree, so a stray
+extension is then packaged over every future build — a trap this repository has
+already been bitten by once.
+
+`meson install --destdir` cannot write outside the staging tree, so the
+installed copy is provably untouched; verify by checking that
+`corrections/` is *absent* from `site-packages\orgui\datautils\xrayutils`,
+not by comparing mtimes.
+
+## 4. Rules this work established
+
+Two of these came from the repository owner during the session and are now
+also in the `AGENTS.md` files. They are the constraints a follow-up must keep.
+
+* **`datautils` holds self-consistent physics modules. No UI or UI state may
+  leak in.** No widget, no configuration object, and no *scan object* in
+  `orgui/datautils/`. This is why `corrections/normalization.py` takes
+  exposure and monitor *values* while `app/integration_corrections.py` keeps
+  the `scan`-attribute lookup, and why the `use_lorentz` / `use_footprint`
+  switches stayed on the app side.
+* **One definition per factor.** Before this branch the mode→factor mapping
+  lived in four places, the active area in three, the exposure/monitor divisor
+  in three, and the per-pixel array in three verbatim copies. When adding a
+  correction, put the physics in `corrections/` and call it; do not compute a
+  factor inline in `orGUI.py` or `peak1Dintegr.py`.
+* **Behaviour-preserving moves are verified against a failure-count baseline,
+  not by inspection.** The refactor was checked at 80 failed / 782 passed
+  before and after.
+
+## 5. The next commit, in detail
+
+Wiring the rocking path, plus the F6 solid-angle removal, which also touches
+the stationary path. This **changes saved numbers in both modes**, so it is
+`feat(phys)!` with a `BREAKING CHANGE:` footer per the repository's commit
+convention.
+
+Steps 1-3 are `peak1Dintegr.RockingPeakIntegrator.integrate`; step 4 is that
+plus `orGUI.integrateROI`:
+
+1. Build the exposure/monitor divisor the way the stationary path does, via
+   `integration_corrections.normalization_divisor(scan, ...)`. Use the
+   **per-frame** counting time, not the sum over the scan: the rocking angle is
+   the integration variable, the time is not.
+2. Convert the trapezoid integral from degrees to radian —
+   `measurement.normalized_intensity(..., angle_unit="deg")` does both this and
+   step 1.
+3. Divide by `acceptance.out_of_plane_acceptance(detector, row, column,
+   row_size, alpha, gamma_arm, delta_arm)`. The ROI centre and size per `s`
+   point are already in the database group `integration/`; the arm angles come
+   from `orgui.backend.scans.scan_arm_angles`.
+4. Stop applying the solid-angle correction to ROI sums — **in both modes**,
+   so this touches `orGUI.integrateROI` as well. F6 is resolved this way (see
+   the physics doc): a ROI sum is already a complete angular integral, and
+   leaving the correction in means the modes still differ by `<1/Omega~>` —
+   0.7 % at 1 m, 7 % at 0.3 m — because a rocking scan's solid-angle factor
+   cancels against its acceptance and a stationary scan's has nothing to
+   cancel against. In practice: drop the `solid_angle=` argument at
+   `orGUI.py:1595` and `:5765`, then the `useSolidAngleBox` widget, the
+   `solidAngle` key in `get_integration_options` and the `SOLA` badge.
+   `set_integration_options` ignores keys it has no branch for, so old
+   configuration files still load. The reconstruction path has its own switch
+   (`reconstruction_job.py:1254`) and must keep it.
+5. Store the acceptance, the applied normalization and the active-area
+   assumption next to `F2_hkl`. Without them a saved rod cannot be put on a
+   common scale after the fact.
+
+Then `orgui/app/test/test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_differ_by_the_missing_normalizations`
+**must flip** from a characterization test to a plain equality. Its docstring
+says so. It currently asserts the gap *is* `T * monitor * Delta_gamma_deg`; if
+it starts failing after a wiring change, that is the change working.
+
+**F6 is settled** (physics doc, F6): ROI-summed integration stops applying the
+solid-angle correction, in both modes. Two things fell out of measuring it
+that matter for step 3: `Delta_gamma` does **not** become unnecessary — it is a
+size factor, the solid angle an obliquity factor, and they overlap only in the
+obliquity — and a constant nominal `n * pixel / dist` is **not** a valid
+"pixel-derived" acceptance, being wrong by `1/cos(theta)` (1.2 % at 9 degrees).
+`out_of_plane_acceptance` is still what the rocking path divides by.
+
+## 6. After that
+
+* **Absolute scale (#15)** needs two user inputs that have no config field yet:
+  the incident flux density `Phi_0`, and the horizontal beam width for
+  `activearea.beam_limited_area`. The footprint dialog already asks for the
+  sample size and the beam profile. Everything else — `lambda`, `A_u`, `r_e` —
+  is available.
+* **Reflectivity comes for free** once `|F|^2` is absolute;
+  `measurement.reflectivity_from_structure_factor` is the conversion. But fix
+  **F5** first: a reflectivity scan drives the detector arm, and the
+  polarization is still evaluated at the calibrated position, which is a 10 %
+  error at `2theta = 18` degrees and 33 % at 30.
+* **`C_det` (F7)** is the only mechanism that can still break mode equivalence
+  after the wiring, and it cannot be validated on simulated data. It needs the
+  real-data overlap comparison.
+
+## 7. Predictions that turned out wrong
+
+Recorded because each cost time and none was obvious in advance.
+
+* **`active_area_footprint` should live next to the existing area code.** It
+  should not exist at all. `w * min(L, h/sin(alpha))` is exactly
+  `w * L * illuminated_area_fraction(alpha, L)` for a top-hat profile and only
+  for that profile — verified to `3.3e-16`. A Gaussian of the same width
+  departs by up to 19 %. The function was deleted, not moved.
+* **"The refactor will remove ~100 lines from `orGUI.py`."** It is 27 added,
+  10 removed — net *longer*, because the explanatory comment is worth more
+  than the ten lines saved. Real length reduction there means extracting the
+  `integrateROI` / `rocking_integrate` driver bodies, which is separate work.
+* **"A moving detector arm changes `Delta_gamma`."** It does not. Driving the
+  gamma arm shifts the exit angle at the ROI centre by the full arm angle but
+  leaves the *span* identical to nine digits, because the rotation is about the
+  axis gamma is measured around. A 40-degree delta-arm rotation moves it by one
+  part in `1e5`. This is the opposite of the polarization factor, and it means
+  an acceptance computed without arm bookkeeping is still usable.
+* **"The run-to-run test-count drift is flakiness."** It was the interpreter
+  changing under the session when Python 3.14 was installed mid-work.
+* **`if C_arr is None: C_arr = np.ones(...)` in `orGUI.py` is dead code.** It
+  is load-bearing: the branch that rebuilds `C_arr` sits inside `if HAS_ACCEL:`,
+  so the NumPy-only path would be handed `None`. It is commented as such now.
+* **pyFAI accepts mismatched coordinate array shapes.** It asserts
+  `pos2.size == size`, so a scalar column with a per-frame region height — what
+  the rocking path will pass — dies inside the extension.
+  `acceptance._surface_gamma` broadcasts before the call.
+
+## 8. Deliberately not done
+
+* **The reconstruction's correction pass was not unified.** It is fused into
+  `apply_correction_factors` with a bit-for-bit native/NumPy contract and
+  variance propagation. It shares the *definition* (`pixel_factors`) but keeps
+  its own streaming application; that was the right boundary.
+* **F5 was not fixed while moving the code.** `pixel_factors` reproduces the
+  historical arm-blind behaviour exactly. Changing it is a numerical fix that
+  belongs in its own `phys` commit, not smuggled into a refactor.
+* **`meson.build` was not changed.** Its `exclude_directories: ['__pycache__']`
+  only excludes the top-level directory, so 72 stale `cpython-312.pyc` files
+  are sitting in the installed copy. Inert under 3.14, and the repository owner
+  had previously declined a `meson.build` change for the related stale-`.pyd`
+  problem, so it was left alone and raised separately.
+
+## 9. Reproducing the key numbers
+
+```powershell
+pytest orgui/datautils/xrayutils/test/test_corrections_measurement.py
+pytest orgui/datautils/xrayutils/test/test_corrections_acceptance.py
+pytest orgui/datautils/xrayutils/test/test_corrections_activearea.py
+pytest orgui/datautils/xrayutils/test/test_corrections_package.py
+pytest orgui/app/test/test_scan_mode_equivalence.py
+```
+
+These five do not need the native extension. Everything else in the suite may,
+so use section 3 before concluding anything from a failure.
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
index e6ab161..3b3cb7a 100644
--- a/doc/design/ctr_structure_factor_scale.md
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -217,10 +217,77 @@ needed. orGUI multiplies the sum by the ROI-mean of `1/solidAngleArray`
 percent for a detector at 1 m, several percent for a close-in detector.
 
 The solid-angle array and an angle-derived `Delta_gamma` describe the same
-geometry. Applying one without the other double-counts. When F3 is implemented,
-decide the pair together: the clean choice is **raw ROI sum plus `Delta_gamma`
-from `surfaceAnglesPoint` at the ROI edges**, with the solid-angle array
-reserved for the per-pixel reconstruction path where it is genuinely required.
+geometry. Applying one without the other double-counts, so the pair has to be
+decided together with F3.
+
+**Resolved: ROI-summed integration does not apply a solid-angle correction at
+all, in either mode.** The array stays where it is genuinely required, the
+per-pixel reconstruction path, which forms a differential cross-section rather
+than a sum over an aperture - and which has its own independent switch
+(`reconstruction_job.py:1254`), so this does not touch it.
+
+Three steps to that conclusion:
+
+1. **A stationary ROI sum is a complete integral.** With the reflection inside
+   the region - open post-sample slits and a region sized from the projected
+   sample, orGUI's usual configuration - every photon is counted once, already
+   weighted by the solid angle of the pixel that caught it. There is nothing
+   to correct.
+2. **Closing the slits would not make it the right correction either.** A
+   truncated integral is Vlieg's `C_det` (F7), an aperture-against-profile
+   model. A per-pixel obliquity weight does not repair a cut-off tail, so the
+   conclusion does not rest on the open-slit assumption holding.
+3. **A rocking sum is a complete integral too**, over a `Delta_gamma` slice of
+   the rod. The slice is what `Delta_gamma` accounts for; there is still no
+   per-pixel weighting to undo.
+
+Leaving the correction in and compensating for it in the reduction was
+considered and rejected. It gives the identical `|F|^2` - what is divided out
+is exactly the scalar that was multiplied in - but it needs one more argument
+on the reduction, and it puts the stored intensity column and `F2_hkl` on
+different scales. What it cannot do is stay in *uncompensated*, because the
+two modes do not carry it symmetrically: for a rocking scan the
+omega-integrated counts in pixel row *j* go as that row's gamma height
+`dgamma_j`, so a corrected sum pairs with `Sum_j dgamma_j / Omega~_j` and the
+factor cancels against the acceptance, while a stationary sum has no
+`Delta_gamma` to cancel against and the factor survives into the saved number.
+The two modes would still disagree by `<1/Omega~>` - 0.7 % at 1 m, 7 % for a
+detector at 0.3 m - after F1-F3 were fixed.
+
+Measured on a calibrated 172 um detector with a 60-row region, where
+`Omega~ = solidAngleArray` is `cos^3` of the incidence angle on the detector
+face to `1e-9`, and `nominal = n * pixel / dist`:
+
+| dist | theta | `Delta_gamma_edge`/nominal | exact/nominal | exact/`Delta_gamma_edge` | `1/<Omega~>` |
+|---|---|---|---|---|---|
+| 1.0 m | 2.7 deg | 0.99774 | 1.00112 | 1.003383 | 1.003383 |
+| 0.3 m | 5.6 deg | 0.99039 | 1.00476 | 1.014512 | 1.014509 |
+| 0.3 m | 9.0 deg | 0.97549 | 1.01236 | 1.037795 | 1.037788 |
+
+The last two columns agreeing to `5e-6` is the cancellation. In closed form
+`Delta_gamma_edge = nominal cos^2(theta)` and `Omega~ = cos^3(theta)`, so the
+partner of a corrected sum is `nominal / cos(theta)`.
+
+Two consequences that survive the decision, because they are what would have
+gone wrong under the other one:
+
+* **`Delta_gamma` does not go away.** It is a *size* factor - how many rows of
+  rod the region accepted - while the solid angle is an *obliquity* factor.
+  They overlap only in the obliquity. `acceptance.out_of_plane_acceptance` is
+  still what the rocking path divides by.
+* **A constant nominal `n * pixel / dist` is not the "pixel-derived"
+  acceptance.** It is wrong by `1/cos(theta)`: 0.1 % at 1 m, 1.2 % at 9
+  degrees. `pixel_acceptance` times the row count is the same angle-derived
+  quantity as `out_of_plane_acceptance`, not a cheaper alternative to it.
+
+On the user-facing side, `useSolidAngleBox` (`QScanSelector.py:748`) drives
+nothing else: its only consumers are the two direct-space integration paths
+(`orGUI.py:1595` in `rocking_integrate`, `:5765` in `integrateROI`). Dropping
+the widget, the `solidAngle` key from `get_integration_options` and the `SOLA`
+badge is therefore the whole change. Old configuration files stay loadable
+without a shim - `set_integration_options` is an `if`/`elif` chain over the
+keys that are present, with no `else`, so a stored `solidAngle` entry is
+ignored rather than an error.
 
 ### F7 - `C_det` is assumed to be 1 in both modes
 
@@ -408,24 +475,31 @@ In order:
    time, not the sum over the scan: the rocking angle is the integration
    variable, the time is not. (F1)
 2. **Integrate in radian**, or divide by `180/pi` at the end. (F2)
-3. **Divide by `Delta_gamma`.** (F3) The input does not exist yet. The
-   estimator needs care and is the one piece of real design work left:
-   * The natural definition is the `gamma` span of the region of interest,
-     from `DetectorCalibration.surfaceAnglesPoint` at its edges, evaluated with
-     the per-frame arm angles from `scan_arm_angles`.
-   * A rectangular ROI in pixel coordinates is in general *rotated* with
-     respect to the `(gamma, delta)` axes. The corner-to-corner `gamma` span
-     then overestimates the acceptance at the `delta` of the rod. Decide
-     whether to take the span at fixed `delta` through the ROI centre or to
-     integrate the accepted `gamma` range over the in-plane profile.
-   * Settle F6 at the same time: raw ROI sum plus an angle-derived
-     `Delta_gamma`, or solid-angle-corrected sum plus a pixel-derived one, but
-     not a mix.
-4. **Record the mode and its inputs in the saved data**, next to `F2_hkl`: the
+3. **Divide by `Delta_gamma`.** (F3) The estimator now exists — section 4.4,
+   `corrections/acceptance.py` — so this is a wiring step rather than a design
+   one:
+   * `out_of_plane_acceptance` takes the span at the ROI centre column, which
+     is the resolution of the rotated-ROI question raised when this section was
+     written: the corner-to-corner span overestimates the acceptance at the
+     `delta` of the rod, so it is reported separately by `gamma_range` as a
+     diagnostic rather than used.
+   * Pass the per-frame arm angles from `scan_arm_angles` where they are known.
+     They turn out to matter far less than expected (section 4.4), but they
+     cost nothing.
+   * Stop applying the solid-angle correction first (step 4): `Delta_gamma`
+     and the solid-angle correction each carry the same obliquity, and
+     leaving both in double-counts it.
+4. **Stop applying the solid-angle correction to ROI sums, in both modes.**
+   (F6) A ROI sum is already a complete angular integral. This also touches
+   `orGUI.integrateROI`, and it changes stationary saved numbers by
+   `<1/Omega~>` - 0.7 % at 1 m, 7 % at 0.3 m - so it belongs in the same
+   breaking commit as the rocking wiring, not a later one. The reconstruction
+   path keeps its own solid-angle switch and is unaffected.
+5. **Record the mode and its inputs in the saved data**, next to `F2_hkl`: the
    acceptance, the normalization that was applied, and the active-area
    assumption of F4. Without them a saved rod cannot be put on a common scale
    after the fact.
-5. **Then verify on real data.** The overlap region of a rocking scan and a
+6. **Then verify on real data.** The overlap region of a rocking scan and a
    stationary scan on the same rod (Drnec Fig. 8, right) is the acceptance
    test. Simulation cannot catch F7, an incorrect `Delta_gamma` definition, or
    a beamline that reports counting time in the wrong place.
@@ -441,11 +515,13 @@ constants:
   `Lattice.uc_area`, `measurement.CLASSICAL_ELECTRON_RADIUS`).
 * `Phi_0` and `T` - user input. `T` is in the scan; `Phi_0` needs a flux
   measurement and a field to put it in.
-* `A` - `active_area_footprint` needs the beam width, beam height and sample
-  length. The footprint dialog already asks for the sample size and the beam
-  profile; it does not ask for the horizontal beam width, and `C_illum_area` is
-  a fraction rather than an area (F4). Multiplying the fraction by
-  `w * min(L, h/sin(alpha))` gives the absolute area.
+* `A` - `activearea.beam_limited_area(alpha, beam_width, sample_length,
+  profile)` returns it in square meter, as `w * L * C_illum_area(alpha, L)`
+  (section 4.3; `C_illum_area` alone is a fraction, not an area - F4). Of its
+  inputs only the **horizontal beam width** is missing: the footprint dialog
+  already asks for the sample size and the beam profile, and the profile
+  carries the vertical direction. `activearea.slit_limited_area` covers the
+  narrow-slit case instead.
 * `C_det` - F7, unmodelled.
 
 **Reflectivity comes for free.**
@@ -490,8 +566,18 @@ stationary one is what `reflectivity_from_structure_factor` reduces.
 
 ## 7. Open questions
 
-* **`Delta_gamma` for a rotated ROI** (section 5.3). The single piece of
-  physics not settled here.
+Nothing here now blocks the wiring. The two that used to head this list are
+settled: `Delta_gamma` for a rotated ROI in section 4.4 (the centre-column
+span, with the corner-to-corner span kept as a diagnostic), and the F6
+solid-angle double count in F6 itself (ROI-summed integration stops applying
+it, in both modes).
+
+* **The stored intensity column changes too, not only `F2_hkl`.** Dropping
+  the solid-angle correction moves it by `<1/Omega~>`, so external
+  post-processing scripts reading the intensity column - not just those
+  reading `F2_hkl` - see the break. It is the same factor either way; there
+  is no variant of F6 that leaves the intensity column alone and still puts
+  the modes on one scale.
 * **The reciprocal-space reconstruction as a third route.** Drnec section 4
   shows that voxel binning absorbs the Lorentz factor, so a reconstructed map
   needs `C_area`, `C_beam`, `P` and `Delta_l` but no Lorentz factor - which is
@@ -500,7 +586,7 @@ stationary one is what `reflectivity_from_structure_factor` reduces.
   piece of work and was not analysed here.
 * **`C_det` (F7)** is the only remaining mechanism that can break the mode
   equivalence after F1-F3, and it is the one that cannot be validated on
-  simulated data. It needs the real-data comparison of section 5.5.
+  simulated data. It needs the real-data comparison of section 5, step 6.
 * **Error propagation through the new factors.** `measurement` reduces
   intensities; the errors follow the same divisors, but a `Delta_gamma`
   estimated from the geometry has an uncertainty of its own that nothing
@@ -510,9 +596,22 @@ stationary one is what `reflectivity_from_structure_factor` reduces.
 
 ```powershell
 pytest orgui/datautils/xrayutils/test/test_corrections_measurement.py
+pytest orgui/datautils/xrayutils/test/test_corrections_acceptance.py
 pytest orgui/app/test/test_scan_mode_equivalence.py
 ```
 
-Note that `orgui/app/test/test_roi_sum_accel.py` fails in a checkout where the
-native ROI extension has not been built ("ROI acceleration is disabled"); that
-is unrelated to anything here.
+The F6 cancellation and the table in it are
+`test_corrections_acceptance.py::test_the_solid_angle_correction_and_the_acceptance_carry_one_obliquity`.
+
+None of these needs the native extension. Much of the rest of the suite does,
+and a checkout without it reports around 80 failures that have nothing to do
+with this work — `ctr_structure_factor_handover.md` section 3 has the
+out-of-tree build recipe that turns those into a clean
+1120 passed / 3 skipped run.
+
+## 9. Where the implementation stands
+
+This document is the physics. For the state of the branch — what is wired and
+what is not, the next commit in detail, the build recipe, and the predictions
+made here that turned out wrong — see
+[`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md).
diff --git a/doc/physics/.gitignore b/doc/physics/.gitignore
new file mode 100644
index 0000000..2237298
--- /dev/null
+++ b/doc/physics/.gitignore
@@ -0,0 +1,10 @@
+# LaTeX build artifacts. Drop the *.pdf line if the built document should be
+# shipped in the repository for readers without a TeX installation.
+*.aux
+*.log
+*.out
+*.toc
+*.synctex.gz
+*.fls
+*.fdb_latexmk
+*.pdf
diff --git a/doc/physics/ctr_structure_factor_physics.tex b/doc/physics/ctr_structure_factor_physics.tex
new file mode 100644
index 0000000..d615f22
--- /dev/null
+++ b/doc/physics/ctr_structure_factor_physics.tex
@@ -0,0 +1,745 @@
+% Compile with:  lualatex ctr_structure_factor_physics.tex   (twice, for refs)
+\documentclass[11pt,a4paper]{article}
+
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+\usepackage[margin=27mm]{geometry}
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{booktabs}
+\usepackage{array}
+\usepackage{enumitem}
+\usepackage{xcolor}
+\usepackage[colorlinks=true,linkcolor=blue!45!black,urlcolor=blue!45!black,
+            citecolor=blue!45!black]{hyperref}
+
+\newcommand{\Fhkl}{\left|F_{hkl}\right|^{2}}
+\newcommand{\dgam}{\Delta\gamma}
+\newcommand{\dOm}{\Delta\Omega}
+\newcommand{\Ored}{\widetilde{\Omega}}
+\newcommand{\Crod}{C_{\mathrm{rod}}}
+\newcommand{\Cdet}{C_{\mathrm{det}}}
+\newcommand{\Carea}{C_{\mathrm{area}}}
+\newcommand{\Cbeam}{C_{\mathrm{beam}}}
+\newcommand{\Cillum}{C_{\mathrm{illum}}}
+\newcommand{\bin}{\beta_{\mathrm{in}}}
+\newcommand{\bout}{\beta_{\mathrm{out}}}
+\newcommand{\re}{r_{e}}
+\newcommand{\Au}{A_{u}}
+% Long dotted module paths are unbreakable in \texttt; let them break after
+% a dot, and give TeX a little slack rather than an overfull line.
+\newcommand{\code}[1]{\texttt{\small #1}}
+\newcommand{\dt}{.\allowbreak}
+\setlength{\emergencystretch}{3em}
+
+\newcommand{\unit}[1]{\;\mathrm{#1}}
+\newcommand{\Ang}{\text{\AA}}
+
+\title{Structure factors from area-detector surface diffraction data\\
+       \large The normalizations and integration intervals used by orGUI}
+\author{orGUI --- \code{orgui\dt datautils\dt xrayutils\dt corrections}}
+\date{\today}
+
+\begin{document}
+\maketitle
+
+\begin{abstract}
+\noindent
+This document states, in one place, how orGUI turns detector counts into
+$\Fhkl$: every normalization that is divided out, every integration interval
+that is summed or integrated over, and the unit each quantity carries at the
+boundary where it changes. It covers the two direct-space measurement modes
+--- rocking scans and stationary area-detector scans --- and the conversion to
+and from specular reflectivity. The reciprocal-space reconstruction is a third
+route with a different set of factors and is only contrasted here, not
+derived.
+
+The physics is that of E.~Vlieg, \emph{J.~Appl.~Cryst.} \textbf{30} (1997) 532,
+in the two-dimensional-detector form of J.~Drnec \emph{et al.},
+\emph{J.~Appl.~Cryst.} \textbf{47} (2014) 365. What this document adds is the
+mapping from those expressions onto what the code actually sums, and the
+resolution of two couplings that the published expressions do not address
+because they do not arise with a point detector: the interaction between the
+detector solid-angle correction and the out-of-plane acceptance, and the
+choice of integration variable and its interval.
+\end{abstract}
+
+\tableofcontents
+
+\section{Conventions}
+
+\subsection{Geometry and angles}
+
+orGUI works in the \textbf{z-axis geometry}, with angles as defined in
+\code{orgui\dt datautils\dt xrayutils\dt HKLVlieg}. It is essential to
+separate the \emph{motor positions} of the diffractometer from the
+\emph{scattering angles} of an individual detector pixel, because only the
+latter enter any correction factor:
+
+\begin{center}
+\begin{tabular}{@{}llll@{}}
+\toprule
+Symbol & Meaning & Kind & Varies with \\
+\midrule
+$\alpha$ & incidence angle on the surface & circle (\code{mu})
+  & frame \\
+$\omega$ & sample rotation about the surface normal & circle (\code{th})
+  & frame \\
+$\gamma_{\mathrm{arm}}$, $\delta_{\mathrm{arm}}$
+  & detector arm position & circles & frame \\
+\addlinespace
+$\gamma_p$, $\delta_p$ & laboratory-frame angles of a pixel & derived
+  & pixel, arm \\
+$\gamma$, $\delta$ & \textbf{surface-frame} angles of a pixel & derived
+  & pixel, arm, $\alpha$ \\
+\bottomrule
+\end{tabular}
+\end{center}
+
+\noindent
+$\gamma$ and $\delta$ are \textbf{not} diffractometer circles and are
+\textbf{not} the arm angles. They are per-pixel quantities, computed from
+where a pixel sits \emph{after} the detector has been rotated to the arm
+position of that frame. Within one frame they vary across the detector face;
+between frames they change both because the arm moved and because $\alpha$
+changed. In this geometry $\gamma$ is the exit angle of the diffracted beam
+from the surface, so $\bout = \gamma$ and $\bin = \alpha$.
+
+All angles are in \textbf{radian} everywhere inside
+\code{orgui\dt datautils\dt xrayutils\dt corrections}; degrees appear only at
+the user interface and in raw motor positions read from a scan.
+
+\subsection{From a pixel to its scattering angles}
+\label{sec:pixelangles}
+
+The conversion runs in three steps, all in
+\code{DetectorCalibration\dt Detector2D\_SXRD}.
+
+\paragraph{1. The arm position becomes a detector geometry.} The arm angles
+are given as the true laboratory-frame angles
+$(\gamma_{\mathrm{arm}}, \delta_{\mathrm{arm}})$ the arm reference direction
+points at. The rotation from the \emph{calibrated} arm position to the
+requested one,
+\begin{equation}
+  R_{\mathrm{rel}} = R_{\mathrm{arm}}(\gamma_{\mathrm{arm}},
+                                      \delta_{\mathrm{arm}})\,
+                     R_{\mathrm{arm}}^{\mathrm{ref}\,\top} ,
+\end{equation}
+is folded into the pyFAI \emph{home} geometry
+$[\,d, \mathrm{poni}_1, \mathrm{poni}_2, \mathrm{rot}_1, \mathrm{rot}_2,
+\mathrm{rot}_3\,]$ by \code{paramAtArm}. A moving arm is therefore represented
+as a \emph{modified pyFAI geometry}, not as an angular offset added after the
+fact --- which is what makes the parallax and obliquity of the following step
+come out right at every arm position.
+
+Two conventions here are easy to get wrong. Passing \code{None} for both arm
+angles means \emph{at the calibrated arm position}, which is not the same as
+passing $0.0$ unless the calibration was taken with the motors reading zero.
+And exactly one of the two is rejected rather than defaulted, because the
+calibration reference is a rotation and not a pair of independent offsets.
+
+\paragraph{2. Pixel to laboratory frame.} On that geometry, the pixel position
+gives the scattering angle $2\theta$ and the azimuth $\chi$ --- with parallax
+applied, and $\chi$ offset by the azimuthal reference --- and from those the
+laboratory-frame angles $(\gamma_p, \delta_p)$ of the pixel
+(\code{primBeamPoints}).
+
+\paragraph{3. Laboratory to surface frame.} Tilting into the surface frame of
+a sample at incidence angle $\alpha$ (\code{surfaceAnglesPoint}):
+\begin{align}
+  \gamma &= \arcsin\bigl(\cos\alpha \, \sin\gamma_p
+            - \sin\alpha \, \cos\delta_p \, \cos\gamma_p \bigr) ,
+  \label{eq:gamma}\\[2pt]
+  \delta &= \arcsin\!\left(
+            \frac{\sin\delta_p \, \cos\gamma_p}{\cos\gamma} \right) .
+  \label{eq:delta}
+\end{align}
+At $\alpha = 0$ these collapse to $\gamma = \gamma_p$ and
+$\delta = \delta_p$, as they must: at zero incidence the surface frame is the
+laboratory frame.
+
+\paragraph{Which angles the corrections use.} Every factor in this document
+that names $\gamma$ or $\delta$ means the surface-frame angles of
+Eqs.~\eqref{eq:gamma} and~\eqref{eq:delta}, evaluated \textbf{at the
+reflection position} --- the centre of the region of interest --- for the arm
+position and $\alpha$ of that frame. The integration paths read them from the
+stored per-reflection angles, not from arm motors. Two places in this document
+depend on the distinction directly:
+
+\begin{itemize}[leftmargin=1.4em]
+\item $\dgam$ (Section~\ref{sec:acceptance}) is a \emph{difference} of
+  Eq.~\eqref{eq:gamma} between two pixel rows, which is only meaningful
+  because $\gamma$ varies across the detector face within one frame.
+\item The polarization factor (Section~\ref{sec:notmodelled}) is the one
+  correction still evaluated on the \emph{home} geometry rather than at the
+  frame's arm position, which is why it is wrong for a scan that drives the
+  arm.
+\end{itemize}
+
+\subsection{Units at the boundaries}
+
+Units are deliberately mixed, following the repository convention that
+crystallographic quantities are in \AA ngstrom and instrument quantities in
+meter. Getting this wrong is a factor of $10^{20}$ in the scale factor, so it
+is stated at every function boundary and pinned by
+\code{test\_scale\_factor\_carries\_its\_documented\_units}.
+
+\begin{center}
+\begin{tabular}{@{}lll@{}}
+\toprule
+Quantity & Symbol & Unit \\
+\midrule
+Wavelength                    & $\lambda$ & \AA ngstrom \\
+Surface unit-cell area        & $\Au$     & \AA ngstrom squared \\
+Classical electron radius     & $\re$     & meter ($2.8179403262\times10^{-15}$) \\
+Active illuminated area       & $A$       & square meter \\
+Incident flux density         & $\Phi_0$  & photons per second and square meter \\
+Counting time                 & $T$       & second \\
+All angles                    &           & radian \\
+Structure factor squared      & $\Fhkl$   & electron units squared \\
+\bottomrule
+\end{tabular}
+\end{center}
+
+\noindent
+$\Phi_0$ is a flux \emph{density}: $\Phi_0 A_0$ is the total flux on the
+sample, with $A_0$ the beam cross-section.
+
+\section{What one detector frame contains}
+\label{sec:frame}
+
+A pixel $i$ of one frame of counting time $T$ accumulates
+\begin{equation}
+  N_i = \Phi_0\, T \left(\frac{d\sigma}{d\Omega}\right)_{\!i} \dOm_i ,
+  \label{eq:pixel}
+\end{equation}
+where $\dOm_i$ is the solid angle that pixel subtends at the sample. For a
+flat detector at distance $d$ with square pixels of size $p$, seen at an
+incidence angle $\theta$ on the detector face,
+\begin{equation}
+  \dOm = \frac{p^{2}}{d^{2}}\cos^{3}\theta ,
+  \qquad
+  \delta\gamma = \frac{p}{d}\cos^{2}\theta ,
+  \qquad
+  \delta\psi = \frac{p}{d}\cos\theta ,
+  \label{eq:pixelgeom}
+\end{equation}
+with $\delta\gamma$ the angular height of the pixel in the direction it is
+tilted away from the normal and $\delta\psi$ the angular width perpendicular
+to it; their product is $\dOm$ as it must be. pyFAI's
+\code{solidAngleArray} returns the \emph{normalized} solid angle
+\begin{equation}
+  \Ored = \dOm \Big/ \frac{p^{2}}{d^{2}} = \cos^{3}\theta ,
+\end{equation}
+which equals $1$ at the point of normal incidence and which orGUI verifies
+against $\cos^{3}\theta$ to $10^{-9}$ in
+\code{test\_corrections\_acceptance.py}.
+
+Equation~\eqref{eq:pixel} is the origin of the central result of
+Section~\ref{sec:solidangle}: a \emph{sum} of $N_i$ over a region already
+carries each pixel's own $\dOm_i$, and is therefore already an angular
+integral. Only a quantity that is meant to be a differential cross-section at
+a point needs $\dOm_i$ divided out.
+
+\section{Integration intervals}
+\label{sec:intervals}
+
+This section fixes exactly which counts enter the integrated intensity, for
+each mode. Everything here is a statement about \emph{domains}; the divisors
+follow in Section~\ref{sec:normalizations}.
+
+\subsection{The region of interest, and its background}
+
+Both direct-space modes reduce a frame to a single number by summing a
+rectangular signal region and subtracting a background estimated from
+separate background regions.
+
+\paragraph{Stationary mode} (\code{orGUI.integrateROI}). With $S$ the signal
+region, $B$ the union of the background regions, $n_S$ and $n_B$ the numbers
+of \emph{valid} (unmasked, present) pixels in each, and $n_S^{\mathrm{nom}}$
+the nominal region size in pixels,
+\begin{equation}
+  N \;=\; \Biggl(\underbrace{\sum_{i\in S} N_i}_{\text{signal sum}}
+        \;-\; \frac{n_S}{n_B}\underbrace{\sum_{i\in B} N_i}_{\text{background sum}}
+    \Biggr)\,
+    \frac{n_S^{\mathrm{nom}}}{n_S} .
+  \label{eq:stationary_roi}
+\end{equation}
+The factor $n_S/n_B$ puts the background on a per-pixel basis and scales it to
+the signal region. The trailing $n_S^{\mathrm{nom}}/n_S$ rescales from the
+pixels that were actually valid to the nominal region area, so that masked
+pixels and detector gaps do not reduce the integrated intensity.
+
+That last rescaling is the reason the nominal region area must \emph{not}
+appear again in any correction factor: the ROI-mean bookkeeping of
+\code{corrections.roi.roi\_mean\_correction} divides the summed correction by
+the valid-pixel count and never by the nominal area. Multiplying by the area a
+second time would scale every intensity by the size of its own region, and
+because orGUI resizes regions with detector position
+(\code{ROIutils.calc\_corrections}), two measurements of one rod taken on
+different parts of the detector would be scaled apart.
+
+\paragraph{Rocking mode} (\code{peak1Dintegr}). The same per-frame reduction is
+applied first, giving a curve $N(\omega_k)$ over the frames of the scan, and
+that curve is then integrated over the rocking angle.
+
+\subsection{The rocking integral}
+\label{sec:rockinginterval}
+
+For each output point the integration interval is a closed interval
+$[\omega_{\mathrm{from}}, \omega_{\mathrm{to}}]$, snapped to the nearest
+sampled motor positions and ordered so that the result is positive:
+\begin{equation}
+  \mathcal{I} \;=\; \int_{\omega_{\mathrm{from}}}^{\omega_{\mathrm{to}}}
+                     N(\omega)\, d\omega
+    \;\longrightarrow\;
+    \sum_{k=k_{\mathrm{from}}}^{k_{\mathrm{to}}-1}
+      \tfrac{1}{2}\bigl(N_k + N_{k+1}\bigr)\,(\omega_{k+1}-\omega_k) ,
+\end{equation}
+a trapezoidal rule over a slice that \textbf{includes both endpoints}
+(\code{slice(idx\_from, idx\_to + 1)}), so that the integrated samples, the
+error weights and the reported interval width all describe the same domain.
+The interval width recorded alongside the result is
+$\Delta\omega = |\omega_{k_{\mathrm{to}}} - \omega_{k_{\mathrm{from}}}|$.
+
+Background regions are integrated over their own intervals and then scaled to
+the signal interval by the ratio of interval widths,
+$\Delta\omega_S/\sum_{B}\Delta\omega_B$, before being subtracted. The result
+is deliberately \emph{not} divided by $\Delta\omega_S$: it is an integral, not
+a mean, because that is what Vlieg's expression requires.
+
+\paragraph{The integration variable must be in radian.} The published
+expressions integrate $d\omega$ in radian. The motor axis is in degrees, so
+the integral as computed is larger by $180/\pi = 57.3$. This is a constant, so
+it is invisible within one data set and only appears when a rocking scan is
+compared with a stationary scan, or with an absolute scale.
+
+\subsection{The out-of-plane acceptance $\dgam$}
+\label{sec:acceptance}
+
+A rocking scan does not measure a whole rod. It intercepts a slice whose
+length is (Vlieg eq.~20)
+\begin{equation}
+  \Delta l = \Crod \, \frac{V_u}{\lambda \Au}\, \dgam ,
+\end{equation}
+so its integrated intensity is proportional to $\dgam$, the out-of-plane
+angular acceptance of the region of interest. A stationary measurement
+intercepts the whole rod cross-section and carries no such factor.
+
+With a point detector $\dgam$ was a slit setting: fixed for an experiment and
+absorbed into an overall scale factor. On an area detector it is a property of
+the region, and orGUI sizes regions per detector position, so it varies
+\emph{along a scan} and changes the shape of a rod rather than only its scale.
+
+\code{corrections.acceptance} evaluates it as the exit-angle span between the
+top and bottom \textbf{edges} of the region, at its centre column:
+\begin{equation}
+  \dgam = \Bigl|\,
+    \gamma\bigl(r + \tfrac{n}{2},\, c\bigr) -
+    \gamma\bigl(r - \tfrac{n}{2},\, c\bigr)\Bigr| ,
+  \label{eq:dgamma}
+\end{equation}
+for a region of $n$ rows centred on pixel $(r,c)$, with $\gamma(\cdot)$ the
+surface-frame exit angle of Eq.~\eqref{eq:gamma} evaluated at that pixel and
+at the frame's arm position and $\alpha$. Two choices in
+Eq.~\eqref{eq:dgamma} are deliberate:
+
+\begin{itemize}[leftmargin=1.4em]
+\item \textbf{Edges, not pixel centres.} A region of $n$ rows accepts $n$
+  pixels' worth of angle, not $n-1$. Measuring between the centres of the
+  first and last row understates every acceptance by one pixel: $1\,\%$ on a
+  100-row region, $10\,\%$ on a 10-row one.
+\item \textbf{The centre column.} The region is centred on the rod, and it is
+  the range of $\gamma$ over which \emph{the rod} crosses the aperture that
+  sets the intercepted length. The corner-to-corner span over the whole
+  rectangle is computed separately by \code{gamma\_range}; the two agree when
+  lines of constant $\gamma$ run along the detector rows and separate on a
+  detector rolled about the beam, so their ratio is a cheap diagnostic for
+  whether the estimate can be trusted.
+\end{itemize}
+
+\paragraph{The detector arm barely matters --- for the span.} Driving the
+$\gamma$ arm shifts $\gamma$ at the region centre by the full arm angle, so
+the arm position matters a great deal for \emph{where on the rod} the region
+sits. It leaves the \emph{span} of Eq.~\eqref{eq:dgamma} unchanged to nine
+digits, because that rotation is about the very axis $\gamma$ is measured
+around; a $40^{\circ}$ $\delta$-arm rotation moves it by one part in $10^{5}$.
+So how much rod is accepted is nearly independent of the arm even though which
+part is accepted is not, and an acceptance computed without arm bookkeeping
+remains usable. Pass the arm angles anyway where they are known --- they cost
+nothing. This is the opposite of the polarization factor
+(Section~\ref{sec:notmodelled}), where ignoring the arm is a $10\,\%$ error at
+a scattering angle of $18^{\circ}$.
+
+\section{Normalizations}
+\label{sec:normalizations}
+
+\subsection{Counting time and monitor}
+
+Both published expressions carry $\Phi_0 T$, so neither an integrated rocking
+curve nor a stationary frame means anything until it is divided by its
+counting time and by whatever counter the incident flux is tracked with:
+\begin{equation}
+  I = \frac{\mathcal{N}}{T \prod_j M_j} ,
+\end{equation}
+with $\mathcal{N}$ the background-subtracted integrated counts of
+Section~\ref{sec:intervals} and $M_j$ the monitor counters
+(\code{corrections.normalization.normalization\_divisor}).
+
+For a rocking scan this is the \textbf{per-frame} counting time, not the sum
+over the scan. The rocking angle is the integration variable; the time is not.
+Using the summed time would divide by the number of frames a second time.
+
+Beyond mode equivalence, this matters \emph{within} one data set: rocking
+scans taken at different $l$ with different counting times, or with a drifting
+ring current, are otherwise placed on different scales with nothing in the
+saved data recording it.
+
+\subsection{Polarization}
+
+The polarization factor $P$ is a per-pixel property of the scattering angle.
+It is divided out as the mean of $1/P$ over the region
+(\code{roi\_mean\_correction}) before the reduction; the master equation of
+Section~\ref{sec:master} therefore takes an intensity from which $P$ has
+already been removed.
+
+\subsection{Solid angle: why a summed region takes none}
+\label{sec:solidangle}
+
+This is the one normalization whose \emph{absence} needs an argument, because
+the array is available and applying it looks harmless.
+
+\paragraph{The statement.} A region-summed intensity gets no solid-angle
+correction, in either direct-space mode. The array belongs only to the
+per-pixel reciprocal-space reconstruction, which forms a differential
+cross-section rather than a sum over an aperture.
+
+\paragraph{Why.} From Eq.~\eqref{eq:pixel}, the raw sum over a region is
+\begin{equation}
+  \sum_{i\in S} N_i
+  = \Phi_0 T \sum_{i \in S} \left(\frac{d\sigma}{d\Omega}\right)_{\!i} \dOm_i
+  \;\simeq\; \Phi_0 T \iint_{S} \frac{d\sigma}{d\Omega}\, d\gamma\, d\psi ,
+\end{equation}
+already the complete angular integral over the aperture. Every photon is
+counted once, weighted by the solid angle of the pixel that caught it. There
+is nothing to correct. Three remarks make this robust:
+
+\begin{enumerate}[leftmargin=1.6em]
+\item If the reflection were \emph{not} fully contained --- post-sample slits
+  narrower than the peak --- the missing part is Vlieg's $\Cdet$, an
+  aperture-against-profile model. A per-pixel obliquity weight does not repair
+  a truncated tail, so the conclusion does not depend on the open-slit
+  assumption holding.
+\item A rocking sum is a complete integral too, over a $\dgam$ slice of the
+  rod. The slice is what $\dgam$ accounts for; there is still no per-pixel
+  weighting to undo.
+\item Where a differential cross-section \emph{is} the goal --- binning
+  individual pixels into reciprocal-space voxels --- the correction is
+  required, and the reconstruction path applies it under its own switch.
+\end{enumerate}
+
+\paragraph{What goes wrong if it is applied anyway.} It does not merely add a
+constant. For a rocking scan the $\omega$-integrated counts in pixel row $j$
+go as that row's angular height $\delta\gamma_j$, so
+\begin{equation}
+  \text{raw sum} \;\longleftrightarrow\; \sum_j \delta\gamma_j = \dgam ,
+  \qquad
+  \text{corrected sum} \;\longleftrightarrow\;
+      \sum_j \frac{\delta\gamma_j}{\Ored_j} \simeq \frac{\dgam}{\langle\Ored\rangle} .
+  \label{eq:partners}
+\end{equation}
+The solid-angle factor cancels against the acceptance in the rocking mode ---
+which is exactly why leaving it in \emph{looks} harmless there. A stationary
+sum has no $\dgam$ for it to cancel against, so the factor survives into the
+saved number and the two modes disagree by $\langle 1/\Ored\rangle$: $0.7\,\%$
+for a detector at $1$~m and $7\,\%$ at $0.3$~m.
+
+Table~\ref{tab:f6} measures Eq.~\eqref{eq:partners} on a calibrated
+$172\,\mu$m detector with a 60-row region. The last two columns
+agreeing to $5\times10^{-6}$ is the cancellation.
+
+\begin{table}[htbp]
+\centering
+\begin{tabular}{@{}llrrrr@{}}
+\toprule
+$d$ & $\theta$ & $\dgam/\dgam_{\mathrm{nom}}$ & exact$/\dgam_{\mathrm{nom}}$
+    & exact$/\dgam$ & $1/\langle\Ored\rangle$ \\
+\midrule
+$1.0$~m & $2.7^{\circ}$ & 0.99774 & 1.00112 & 1.003383 & 1.003383 \\
+$0.3$~m & $5.6^{\circ}$ & 0.99039 & 1.00476 & 1.014512 & 1.014509 \\
+$0.3$~m & $9.0^{\circ}$ & 0.97549 & 1.01236 & 1.037795 & 1.037788 \\
+\bottomrule
+\end{tabular}
+\caption{The two partners of Eq.~\eqref{eq:partners}, against the nominal
+$\dgam_{\mathrm{nom}} = n\,p/d$. Here the region is displaced from the point
+of normal incidence along its rows, so by Eq.~\eqref{eq:pixelgeom}
+$\dgam = \dgam_{\mathrm{nom}}\cos^{2}\theta$ against $\Ored = \cos^{3}\theta$
+and the corrected-sum partner is $\dgam_{\mathrm{nom}}/\cos\theta$. That
+decomposition depends on the orientation of the region relative to the normal;
+the ratio in the last two columns does not, since it follows from
+Eq.~\eqref{eq:partners} alone. Pinned by
+\code{test\_the\_solid\_angle\_correction\_and\_the\_acceptance\_carry\_one\_obliquity}.}
+\label{tab:f6}
+\end{table}
+
+\paragraph{Two traps this leaves behind.}
+\begin{itemize}[leftmargin=1.4em]
+\item \textbf{$\dgam$ does not become unnecessary.} It is a \emph{size} factor
+  --- how many rows of rod the region accepted --- while the solid angle is an
+  \emph{obliquity} factor. They overlap only in the obliquity, a fraction of a
+  percent.
+\item \textbf{A constant nominal $n\,p/d$ is not a valid substitute for
+  Eq.~\eqref{eq:dgamma}.} It is wrong by $1/\cos\theta$: $0.1\,\%$ at $1$~m,
+  $1.2\,\%$ at $\theta = 9^{\circ}$. The single-pixel acceptance times the row
+  count is the same angle-derived quantity as Eq.~\eqref{eq:dgamma}, not a
+  cheaper alternative to it.
+\end{itemize}
+
+\subsection{The active area and the beam footprint}
+\label{sec:area}
+
+$A$ is the surface area that actually contributes counts. Vlieg writes it as
+$A = A_0\,\Carea\,\Cbeam$ (his eq.~41). Which of two limits applies is an
+experimental question, and orGUI builds both:
+
+\paragraph{Beam-limited (open slits, orGUI's usual case).}
+\begin{equation}
+  A(\alpha) = w\, L\, \Cillum(\alpha, L) ,
+  \label{eq:beamarea}
+\end{equation}
+with $w$ the horizontal beam width, $L$ the sample length along the beam, and
+$\Cillum$ the profile integrated over the projected sample and normalized to a
+uniform beam,
+\begin{equation}
+  \Cillum(\alpha,L)
+    = \frac{1}{p_{\max}\, h_{\mathrm{proj}}}
+      \int_{-h_{\mathrm{proj}}/2}^{+h_{\mathrm{proj}}/2} p(z)\, dz ,
+  \qquad h_{\mathrm{proj}} = L\sin\alpha .
+\end{equation}
+Note that $\Cillum$ is a dimensionless \emph{fraction}, not an area; the
+horizontal direction is the plain beam width, since it is not projected. For a
+top-hat profile of full height $h$, Eq.~\eqref{eq:beamarea} reduces exactly to
+the familiar closed form
+\begin{equation}
+  A = w \min\!\left(L,\; \frac{h}{\sin\alpha}\right) ,
+\end{equation}
+verified to $3.3\times10^{-16}$. It does \emph{not} reduce to it for any other
+profile --- a Gaussian of the same width departs by up to $19\,\%$ --- which
+is why the closed form is not used.
+
+\paragraph{Slit-limited.} When post-sample slits cut the footprint,
+$\Carea = 1/(\sin\delta\,\cos(\alpha - \bin))$ applies instead (Vlieg eqs.~37
+and~38). Because $\delta$ varies along a rod, this is a \emph{shape} effect,
+not only a scale: on a simulated Pt(111) $(1,0,l)$ rod, $\delta$ moves from
+$16.77^{\circ}$ to $16.95^{\circ}$ between $l = 0.4$ and $l = 3.0$, a
+$1.1\,\%$ error, and much larger between rods at different in-plane momentum
+transfer.
+
+\paragraph{It cannot explain a mode disagreement.} $A$ enters the rocking and
+the stationary expressions identically and cancels from their ratio. It sets
+the absolute scale and nothing else.
+
+\section{The master equation}
+\label{sec:master}
+
+With $I$ the normalized integrated intensity of
+Section~\ref{sec:normalizations} --- counts per second per monitor unit, with
+$P$ already divided out ---
+\begin{equation}
+  \boxed{\;
+  I \;=\; \Phi_0\, \frac{\re^{2} A \lambda^{2}}{\Au^{2}}\;
+          \Fhkl \; \eta \; \Cdet \; }
+  \label{eq:master}
+\end{equation}
+and the mode enters only through the angular factor $\eta$:
+
+\begin{center}
+\begin{tabular}{@{}lll@{}}
+\toprule
+Mode & $\eta$ & Lorentz factor \\
+\midrule
+Rocking scan (\code{th}/$\omega$)      & $L_\varphi\,\Crod\,\dgam$
+  & $L_\varphi = 1/(\sin\delta\,\cos\alpha\,\cos\gamma)$ \\
+Reflectivity rocking (\code{mu})       & $L_r\,\Crod\,\dgam$
+  & $L_r = 1/\sin 2\alpha$ \\
+Stationary area detector               & $L_s$
+  & $L_s = 1/\sin\gamma$ \\
+Specular reflectivity                  & $L_s$ at $\gamma = \alpha$
+  & $L_s = 1/\sin\alpha$ \\
+\bottomrule
+\end{tabular}
+\end{center}
+
+\noindent
+with the rod interception $\Crod = \cos\gamma$. The three Lorentz factors are
+\textbf{alternatives selected by how the intensity was measured}, not factors
+to be combined. Two structural points:
+
+\begin{itemize}[leftmargin=1.4em]
+\item The rocking modes carry $\Crod$ and $\dgam$; the stationary mode carries
+  neither. A stationary measurement integrates across the whole rod
+  cross-section, so there is no interception factor and no acceptance ---
+  \code{angular\_factor} \emph{rejects} an acceptance passed for a stationary
+  mode, rather than ignoring it.
+\item The area correction $1/\sin\delta$ listed in the ANA/ROD z-axis table is
+  \emph{not} applied; the numerically evaluated footprint of
+  Section~\ref{sec:area} is used instead, which is the row the manual marks as
+  calculated numerically.
+\end{itemize}
+
+\subsection{Dimensional check}
+
+The radian in $\dgam$ is what makes the two modes dimensionally distinct, and
+it is worth checking that it lands correctly. Writing $[\cdot]$ for the unit
+of a quantity and taking a unit monitor,
+\begin{align}
+  \text{prefactor:}&\quad
+    \frac{1}{\mathrm{s}\,\mathrm{m}^{2}} \cdot \mathrm{m}^{2}
+    \cdot \mathrm{m}^{2} \cdot \frac{\mathrm{m}^{2}}{\mathrm{m}^{4}}
+    = \frac{1}{\mathrm{s}} , \\
+  \text{stationary:}&\quad
+    [I] = \frac{\text{counts}}{\mathrm{s}} ,
+    \qquad \eta \text{ dimensionless} \quad\checkmark \\
+  \text{rocking:}&\quad
+    [I] = \frac{\text{counts}\cdot\mathrm{rad}}{\mathrm{s}} ,
+    \qquad [\eta] = \mathrm{rad} \quad\checkmark
+\end{align}
+The rocking intensity carries one radian more than the stationary one, and
+$\dgam$ is what absorbs it. Integrating in degrees and omitting $\dgam$ are
+therefore not two independent mistakes but a single unbalanced unit, which is
+why they were measured together as one ratio.
+
+\subsection{Inverting to a structure factor}
+
+\begin{equation}
+  \Fhkl = \frac{I}{S\,\eta\,\Cdet} ,
+  \qquad
+  S = \Phi_0\, A\, \frac{\re^{2}\lambda^{2}}{\Au^{2}} ,
+\end{equation}
+with $S$ the mode-independent prefactor, in $1/\mathrm{s}$
+(\code{measurement.scale\_factor}). Leaving $\Phi_0 = A = 1$ gives the
+\textbf{relative} scale, which is all that is needed to place different scan
+modes of one experiment on a common scale. Supplying the measured flux density
+and illuminated area gives the \textbf{absolute} scale, and $\Fhkl$ then comes
+out in electron units squared --- the same scale on which
+\code{CTRcalc.SXRDCrystal} calculates.
+
+\section{Reflectivity}
+
+Specular reflectivity is the stationary case at $\gamma = \alpha$ with a
+beam-limited active area $A_r = A_0/\sin\alpha$. Vlieg's eq.~63, generalized to
+a non-specular exit angle, is
+\begin{equation}
+  R = \frac{\re^{2}\lambda^{2} P_r}{\Au^{2}\,\sin\alpha\,\sin\bout}\, \Fhkl ,
+  \label{eq:refl}
+\end{equation}
+the fraction of the incident flux scattered into the rod. For the specular rod
+$\bout = \alpha$ and this is the familiar $1/\sin^{2}\alpha$: one power from
+the footprint, one from the stationary Lorentz factor.
+
+Nothing beyond an absolutely scaled $\Fhkl$ is required, so \textbf{an absolute
+reflectivity comes for free} once the scale factor is absolute, and a
+reflectivity curve can be refined together with the truncation rods.
+Equation~\eqref{eq:refl} inverts to put a measured reflectivity onto the
+$\Fhkl$ scale.
+
+Three caveats:
+\begin{enumerate}[leftmargin=1.6em]
+\item It is the \textbf{kinematic} result. It fails near a bulk Bragg peak and
+  below the critical angle, where refraction and multiple scattering dominate
+  --- which is where much of the interesting part of a reflectivity curve
+  lies. Compare against a DWBA treatment there.
+\item A reflectivity scan \textbf{drives the detector arm}, which is where the
+  polarization issue of Section~\ref{sec:notmodelled} bites hardest.
+\item \textbf{Off-specular}, $R$ is well defined for a truncation rod
+  integrated across its cross-section, but not for diffuse scattering, where
+  only a differential cross-section is meaningful.
+\end{enumerate}
+
+Note also that the ANA ``reflectivity rocking scan'' Lorentz factor
+$1/\sin 2\alpha$ describes rocking \emph{through} the specular ridge. That is a
+different measurement from a stationary specular scan; both are legitimate and
+they are not interchangeable.
+
+\section{What is deliberately not modelled}
+\label{sec:notmodelled}
+
+\begin{description}[leftmargin=0pt,style=unboxed]
+\item[$\Cdet$, the in-plane detector acceptance.] Vlieg's sections 2.4--2.5.
+  It is close to $1$ for a region wide enough to contain the whole in-plane
+  peak profile, which is what Eq.~\eqref{eq:master} assumes by taking
+  $\Cdet = 1$. It is \emph{not} the same for the two modes when the rod is
+  broad: Drnec's Fig.~18 shows direct stationary integration underestimating
+  $|F|$ at low $l$ by up to a factor of $2$ for exactly this reason. This is
+  the one remaining mechanism that can make the two modes disagree after
+  everything in this document is applied, and it is a modelling problem rather
+  than a normalization one. It cannot be validated on simulated data --- it
+  needs the overlap region of a rocking and a stationary scan on the same rod.
+
+\item[The polarization at a moving detector arm.] The per-pixel polarization
+  array is built once, outside the frame loop, from the \emph{home} geometry
+  --- step 1 of Section~\ref{sec:pixelangles} is skipped, so it is the array
+  at the calibrated arm position rather than at the frame's. For a fixed arm
+  that is correct: each pixel already carries its own scattering angle, and
+  the apparent $\alpha$ dependence of the z-axis expression is only a change
+  of frame. For a scan that drives the arm it understates the correction:
+  $3\,\%$ at a scattering angle of $10^{\circ}$, $10\,\%$ at $18^{\circ}$ and
+  $33\,\%$ at $30^{\circ}$. A per-pixel evaluation that follows the arm
+  exists and is what such a scan needs. This is the opposite of the acceptance
+  (Section~\ref{sec:acceptance}), whose \emph{span} survives a moving arm
+  unchanged.
+
+\item[Uncertainty of $\dgam$.] Errors follow the same divisors as the
+  intensities, but a $\dgam$ estimated from the calibrated geometry has an
+  uncertainty of its own that is not currently propagated.
+
+\item[The reciprocal-space route.] Voxel binning absorbs the Lorentz factor
+  (Drnec section 4), so a reconstructed map needs $\Carea$, $\Cbeam$, $P$ and
+  a $\Delta l$, but no Lorentz factor --- a different set of factors from
+  either direct-space mode. Placing it on the same absolute scale is separate
+  work.
+\end{description}
+
+\section{Summary}
+
+\begin{center}
+\renewcommand{\arraystretch}{1.18}
+\begin{tabular}{@{}lllcc@{}}
+\toprule
+Factor & Symbol & Where & Rocking & Stationary \\
+\midrule
+Counting time, monitor      & $T$, $M_j$   & \code{normalization} & yes & yes \\
+Integration in radian       & --           & integration path     & yes & n/a \\
+Out-of-plane acceptance     & $\dgam$      & \code{acceptance}    & yes & \textbf{no} \\
+Lorentz                     & $L_\varphi$ / $L_s$ & \code{geometry} & yes & yes \\
+Rod interception            & $\Crod$      & \code{geometry}      & yes & \textbf{no} \\
+Polarization                & $P$          & \code{detector}      & yes & yes \\
+Solid angle                 & $\dOm$       & \code{detector}      & \textbf{no} & \textbf{no} \\
+Active area / footprint     & $A$          & \code{activearea}    & yes & yes \\
+Area correction             & $\Carea$     & \code{geometry}      & slits only & slits only \\
+In-plane acceptance         & $\Cdet$      & ---                  & assumed 1 & assumed 1 \\
+\bottomrule
+\end{tabular}
+\end{center}
+
+\noindent
+The three entries that distinguish the modes are $\dgam$, $\Crod$ and the
+choice of Lorentz factor. Everything else is common, and the two factors
+marked \textbf{no} for both modes are the ones whose absence is a deliberate
+result rather than an omission.
+
+\section*{References}
+\addcontentsline{toc}{section}{References}
+
+\begin{enumerate}[leftmargin=1.6em]
+\item E.~Vlieg, \emph{Integrated intensities using a six-circle surface X-ray
+  diffractometer}, J.~Appl.~Cryst. \textbf{30} (1997) 532--543.
+\item E.~Vlieg, \emph{ANA --- program for the analysis of surface X-ray
+  diffraction data}, Appendix~A (z-axis correction-factor table).
+\item J.~Drnec, T.~Zhou, S.~Pintea, W.~Onderwaater, E.~Vlieg, G.~Renaud and
+  R.~Felici, \emph{Integration techniques for surface X-ray diffraction data
+  obtained with a two-dimensional detector}, J.~Appl.~Cryst. \textbf{47}
+  (2014) 365--377.
+\end{enumerate}
+
+\end{document}
diff --git a/orgui/datautils/xrayutils/test/test_corrections_acceptance.py b/orgui/datautils/xrayutils/test/test_corrections_acceptance.py
index c8cf5c9..c6c3c6b 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_acceptance.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_acceptance.py
@@ -265,6 +265,59 @@ def test_one_arm_angle_alone_is_rejected():
         )
 
 
+def test_the_solid_angle_correction_and_the_acceptance_carry_one_obliquity():
+    """Which acceptance goes with which sum, and why F6 keeps the raw one.
+
+    A rocking scan's omega-integrated counts in pixel row ``j`` go as that
+    row's gamma height ``dgamma_j``. A raw region sum -- which is what a
+    region-of-interest integration produces once F6 stops applying the
+    solid-angle correction -- therefore pairs with ``sum_j dgamma_j``, which
+    is what :func:`out_of_plane_acceptance` returns. A solid-angle corrected
+    sum would instead pair with ``sum_j dgamma_j / Omega~_j``, larger by the
+    region-mean correction that was applied to the counts.
+
+    The two are pinned together because the second is the trap that made F6
+    look optional: the correction cancels against the acceptance in a rocking
+    scan, so leaving it in *looks* harmless there. It is not, because a
+    stationary sum has no acceptance for it to cancel against.
+
+    The third assertion is the other trap: a *constant* nominal ``n * pixel /
+    dist`` is neither partner. On a flat detector
+    ``dgamma = nominal cos^2(theta)`` while ``Omega~ = cos^3(theta)``, so the
+    corrected-sum partner is ``nominal / cos(theta)`` -- above the nominal,
+    where the acceptance itself is below it.
+    """
+    det = _calibrated_detector()
+    alpha = np.deg2rad(0.6)
+    column, rows = SHAPE[1] // 2, 60
+    solid_angle = np.asarray(det.solidAngleArray(SHAPE), dtype=np.float64)
+
+    # Off the beam centre, where the detector is oblique enough to separate
+    # the three candidates.
+    for row in (480, 560):
+        edges = np.arange(row - rows / 2.0, row + rows / 2.0 + 1.0)
+        gamma = np.concatenate(
+            [acceptance._surface_gamma(det, e, column, alpha).ravel() for e in edges]
+        )
+        per_row = np.abs(np.diff(gamma))
+        omega = solid_angle[row - rows // 2:row + rows // 2, column]
+
+        edge_to_edge = acceptance.out_of_plane_acceptance(
+            det, float(row), float(column), float(rows), alpha
+        )
+        corrected_partner = np.sum(per_row / omega)
+
+        # The raw-sum partner is the edge-to-edge span.
+        np.testing.assert_allclose(np.sum(per_row), edge_to_edge, rtol=1e-9)
+        # The corrected-sum partner is that, divided by the mean correction.
+        np.testing.assert_allclose(
+            corrected_partner, edge_to_edge / omega.mean(), rtol=1e-4
+        )
+        # Neither equals the nominal, and they straddle it.
+        nominal = rows * PIXEL / DIST
+        assert edge_to_edge < nominal < corrected_partner
+
+
 def test_the_acceptance_is_what_the_reduction_asks_for():
     """It plugs straight into the rocking angular factor.
 

From 0af9cb7f74a5efa4dca0b2d3cdee23fa9d8a7349 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Thu, 10 Sep 2026 12:18:22 -0400
Subject: [PATCH 06/33] feat(phys)!: put rocking and stationary integration on
 one structure-factor scale

BREAKING CHANGE: F2_hkl changes in both integration modes. Rocking scans gain
the per-frame exposure/monitor normalization, the rocking integral in radian,
and division by the out-of-plane acceptance; both modes divide the detector
solid-angle correction back out of F2_hkl, which still scales the intensity.
Rods integrated with an earlier version are on a different scale and must be
re-integrated before being combined with new ones.
---
 CHANGELOG.md                                  |  52 ++-
 doc/design/ctr_structure_factor_handover.md   | 178 +++++-----
 doc/design/ctr_structure_factor_scale.md      | 130 +++++---
 doc/source/image_integration.rst              |  88 +++--
 doc/source/release_notes.rst                  |   6 +-
 orgui/app/QScanSelector.py                    |  21 +-
 orgui/app/integration_corrections.py          |  31 +-
 orgui/app/orGUI.py                            |  33 +-
 orgui/app/peak1Dintegr.py                     | 314 +++++++++++++++++-
 orgui/app/test/test_peak1Dintegr.py           | 214 +++++++++++-
 orgui/app/test/test_scan_mode_equivalence.py  | 138 ++++++--
 .../xrayutils/corrections/detector.py         |  82 ++++-
 .../test/test_corrections_detector.py         | 136 ++++++++
 13 files changed, 1212 insertions(+), 211 deletions(-)
 create mode 100644 orgui/datautils/xrayutils/test/test_corrections_detector.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e9a4bb7..4d560da 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,45 @@ This is the changelog for the software orGUI, written by Timo Fuchs
 
 Scientific and analysis additions:
 
+- **Rocking and stationary integration now produce the same structure factor.**
+  *This changes saved numbers in both modes.* A rocking scan and a stationary
+  scan of the same rod previously differed by exactly exposure time times
+  monitor times the out-of-plane acceptance in degrees; they now agree. Four
+  corrections changed. The rocking path gained the per-frame exposure and
+  monitor normalization, applied inside the rocking integral so that a varying
+  counting time or a drifting monitor is handled correctly rather than only on
+  average; it now integrates the rocking angle in radian as the published
+  expressions require, rather than in degrees; and it divides by the
+  out-of-plane acceptance of its region of interest, without which a rod
+  measured with regions resized along the scan came out with a distorted
+  *shape* -- a factor 2.3 across a simulated Pt(111) rod -- and not merely a
+  wrong scale. Separately, the detector **solid-angle correction no longer
+  reaches a structure factor** in either mode: summing a region of interest
+  already yields the complete angular integral, with every pixel weighted by
+  the solid angle it subtends, so dividing by that solid angle again
+  double-counted the detector obliquity (0.7 % for a detector at 1 m, 7 % at
+  0.3 m, varying across the detector and therefore a rod shape error). The
+  switch stays, because that correction is the right one for a broad or
+  diffuse feature where a differential cross section is wanted: it still
+  scales the intensity counters, and is now measured over the same regions of
+  interest and divided back out when ``F2_hkl`` is formed, so a structure
+  factor is the same number whether or not it was enabled. Its tooltip and the
+  ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps
+  applying it uncompensated, since that path does form a differential cross
+  section per pixel. For rocking scans the correction is applied when the
+  curves are extracted, so whether to remove it again is read from the
+  configuration stored with the scan; an older database where that cannot be
+  established warns and is left uncompensated. Integrated rocking scans now
+  store a
+  ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit,
+  which normalizations were applied, the acceptance used, whether the
+  solid-angle correction was compensated, and the active-area assumption, so
+  that a saved rod can be placed on a common scale afterwards.
+  Rocking normalization uses the counters stored with the scan, so it requires
+  a backend that declares ``exposure_time`` in ``auxillary_counters``; a
+  missing counter is skipped and recorded rather than failing the integration.
+  Existing configuration files load unchanged.
+
 - **All correction factors collected into one package.** Every factor between
   detector counts and a structure factor now lives in
   ``orgui.datautils.xrayutils.corrections``, split by what it depends on:
@@ -32,7 +71,8 @@ Scientific and analysis additions:
   the aperture, and vectorized over a scan because orGUI resizes regions per
   detector position. ``gamma_range`` reports the span over the whole region as
   a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row
-  case. **A new API only: the integration paths do not call it yet.**
+  case. The rocking integration now divides by it -- see the mode-equivalence
+  entry below.
 
 - **One structure-factor scale for rocking scans, stationary scans, and
   reflectivity.** The new public module
@@ -46,13 +86,11 @@ Scientific and analysis additions:
   reject it), and, given the incident flux density and the illuminated area,
   puts the result on the absolute electron-unit scale. It also converts
   between ``|F_hkl|^2`` and absolute reflectivity, so a reflectivity curve and
-  a set of truncation rods can be brought onto one scale. **This is a new API
-  only: no existing integration result changes.** The integration paths do
-  not use it yet, and rocking and stationary integration remain on different
-  scales, differing by exposure time times monitor times the acceptance in
-  degrees; the image-integration documentation now says so explicitly, and
+  a set of truncation rods can be brought onto one scale.
   ``doc/design/ctr_structure_factor_scale.md`` records the full analysis with
-  the measured size of every correction.
+  the measured size of every correction, and
+  ``doc/physics/ctr_structure_factor_physics.tex`` is a typeset reference for
+  the normalizations and integration intervals.
 
 - **Unified CTR fit predictions, lifecycle, and statistics.** CTR optimizer
   predictions, residuals, likelihoods, and diagnostics now use one final
diff --git a/doc/design/ctr_structure_factor_handover.md b/doc/design/ctr_structure_factor_handover.md
index bdde295..f60df74 100644
--- a/doc/design/ctr_structure_factor_handover.md
+++ b/doc/design/ctr_structure_factor_handover.md
@@ -1,15 +1,17 @@
 # CTR structure-factor scale: implementation status and handover
 
-> **Status as of 2026-09-09.** Branch `claude/ctr-structure-factor-9633bc`,
-> four commits ahead of `master`, nothing pushed.
+> **Status as of 2026-09-10.** Branch `claude/ctr-structure-factor-9633bc`,
+> six commits ahead of `master`, nothing pushed.
 >
-> The physics analysis is complete and quantified, the reduction and the
-> acceptance estimator exist and are tested, and the correction factors have
-> one home. **No saved number has changed yet**: the GUI integration paths do
-> not call any of the new reduction. Issues
-> [#82](https://github.com/tifuchs/orGUI/issues/82) and
-> [#15](https://github.com/tifuchs/orGUI/issues/15) are therefore *analysed and
-> equipped* but not closed.
+> The physics analysis is complete and quantified, and the reduction is now
+> **wired in**: a rocking scan and a stationary scan of the same rod come out
+> with the same `F2_hkl`, asserted by
+> `test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_agree`.
+> This **changed saved numbers in both modes**.
+> [#82](https://github.com/tifuchs/orGUI/issues/82) is closed up to the
+> real-data check of section 6 and `C_det` (F7), the one mechanism simulation
+> cannot test. [#15](https://github.com/tifuchs/orGUI/issues/15) still needs
+> the two absolute-scale inputs of section 6.
 >
 > This document is the handover: what exists, how to run it, what to do next,
 > and which of my predictions turned out wrong. The physics itself is in
@@ -18,16 +20,17 @@
 
 ## 1. The one-paragraph summary
 
-A rocking scan and a stationary scan of the same rod do not currently produce
-the same `F2_hkl` in orGUI. The ratio is exactly
+A rocking scan and a stationary scan of the same rod used to differ by exactly
 `T_omega * monitor_omega * Delta_gamma_in_degrees`, measured to seven digits on
-simulated data. Three things are missing from the rocking path: exposure/monitor
-normalization, integration in radian rather than degrees, and division by the
-out-of-plane detector acceptance. All three now have working implementations in
-`orgui/datautils/xrayutils/corrections/`; none of them is wired in. A fourth,
-F6, affects **both** modes: a ROI sum is already a complete angular integral,
-so the solid-angle correction has to stop being applied to it, or the two
-modes stay apart by `<1/Omega~>` even after the rocking path is fixed.
+simulated data. Three things were missing from the rocking path:
+exposure/monitor normalization, integration in radian rather than degrees, and
+division by the out-of-plane detector acceptance. A fourth, F6, affected
+**both** modes: a ROI sum is already a complete angular integral, so the
+solid-angle correction had to be divided back out of `F2_hkl`. It stays
+applied to the *intensity*, where a broad or diffuse feature needs it. All
+four are now handled, and the two modes agree to `1e-6` on simulated data —
+the residual is the trapezoidal sampling of the rocking profile, not a
+correction factor.
 
 ## 2. What is on the branch
 
@@ -64,18 +67,32 @@ as re-export aliases because both were released under those names.
 `test_corrections_package.py` asserts the aliases hand out the *same objects*,
 not merely that they import.
 
-### 2.2 What is wired, and what is not
+### 2.2 What is wired
 
 | caller | uses the package for | still does its own thing |
 |---|---|---|
-| `orGUI.integrateROI` (stationary) | `pixel_factors`, `mode_components`, `normalization_divisor`, `C_illum_area` | — |
+| `orGUI.integrateROI` (stationary) | `pixel_factors`, `mode_components`, `normalization_divisor`, `C_illum_area`, `roi_mean_inverse_solid_angle` | — |
 | `orGUI.rocking_integrate` | `pixel_factors` | — |
-| `peak1Dintegr.integrate` (rocking) | `mode_components` | **no normalization, degrees, no `Delta_gamma`** |
-| `reconstruction_job` | `pixel_factors` | own native-fused application, own normalization loop |
-
-Nothing calls `measurement.structure_factor_squared`,
-`measurement.normalized_intensity`, `measurement.angular_factor`,
-`activearea.*` or `acceptance.*` outside the tests. That is the gap to close.
+| `peak1Dintegr.integrate` (rocking) | `mode_components`, `normalization_divisor`, `normalized_intensity`, `out_of_plane_acceptance`, `roi_mean_inverse_solid_angle` | — |
+| `reconstruction_job` | `pixel_factors` (solid angle applied, **not** compensated) | own native-fused application, own normalization loop |
+
+Still uncalled outside the tests: `measurement.structure_factor_squared`,
+`measurement.angular_factor` and `activearea.*`. That is deliberate rather
+than a gap — the two integration paths form `F2_hkl` on a *relative* scale by
+dividing out the mode-dependent factors they already hold as
+interval-weighted means, and `structure_factor_squared` additionally divides
+by the absolute prefactor, which needs the issue #15 inputs. `angular_factor`
+rebuilds `eta` from point angles, which is the wrong thing for a path that
+has ROI-weighted means of each component.
+
+The rocking path could not use `normalization_divisor(scan, ...)` as the
+stationary path does: it runs off the database and has no scan object. It
+builds the divisor from the stored `auxillary` counters instead, via
+`_rocking_normalization`, using the same monitor-name setting
+(`reconstruction_monitor_corrections`) the other two paths use. Exposure time
+is only there if the backend declares `exposure_time` in
+`auxillary_counters` — ID31 does, `P212_tools` and the base `Scan` do not, and
+a missing counter is skipped and recorded rather than failing the job.
 
 ## 3. Getting a green test run
 
@@ -147,55 +164,66 @@ also in the `AGENTS.md` files. They are the constraints a follow-up must keep.
   not by inspection.** The refactor was checked at 80 failed / 782 passed
   before and after.
 
-## 5. The next commit, in detail
-
-Wiring the rocking path, plus the F6 solid-angle removal, which also touches
-the stationary path. This **changes saved numbers in both modes**, so it is
-`feat(phys)!` with a `BREAKING CHANGE:` footer per the repository's commit
-convention.
-
-Steps 1-3 are `peak1Dintegr.RockingPeakIntegrator.integrate`; step 4 is that
-plus `orGUI.integrateROI`:
-
-1. Build the exposure/monitor divisor the way the stationary path does, via
-   `integration_corrections.normalization_divisor(scan, ...)`. Use the
-   **per-frame** counting time, not the sum over the scan: the rocking angle is
-   the integration variable, the time is not.
-2. Convert the trapezoid integral from degrees to radian —
-   `measurement.normalized_intensity(..., angle_unit="deg")` does both this and
-   step 1.
-3. Divide by `acceptance.out_of_plane_acceptance(detector, row, column,
-   row_size, alpha, gamma_arm, delta_arm)`. The ROI centre and size per `s`
-   point are already in the database group `integration/`; the arm angles come
-   from `orgui.backend.scans.scan_arm_angles`.
-4. Stop applying the solid-angle correction to ROI sums — **in both modes**,
-   so this touches `orGUI.integrateROI` as well. F6 is resolved this way (see
-   the physics doc): a ROI sum is already a complete angular integral, and
-   leaving the correction in means the modes still differ by `<1/Omega~>` —
-   0.7 % at 1 m, 7 % at 0.3 m — because a rocking scan's solid-angle factor
-   cancels against its acceptance and a stationary scan's has nothing to
-   cancel against. In practice: drop the `solid_angle=` argument at
-   `orGUI.py:1595` and `:5765`, then the `useSolidAngleBox` widget, the
-   `solidAngle` key in `get_integration_options` and the `SOLA` badge.
-   `set_integration_options` ignores keys it has no branch for, so old
-   configuration files still load. The reconstruction path has its own switch
-   (`reconstruction_job.py:1254`) and must keep it.
-5. Store the acceptance, the applied normalization and the active-area
-   assumption next to `F2_hkl`. Without them a saved rod cannot be put on a
-   common scale after the fact.
-
-Then `orgui/app/test/test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_differ_by_the_missing_normalizations`
-**must flip** from a characterization test to a plain equality. Its docstring
-says so. It currently asserts the gap *is* `T * monitor * Delta_gamma_deg`; if
-it starts failing after a wiring change, that is the change working.
-
-**F6 is settled** (physics doc, F6): ROI-summed integration stops applying the
-solid-angle correction, in both modes. Two things fell out of measuring it
-that matter for step 3: `Delta_gamma` does **not** become unnecessary — it is a
-size factor, the solid angle an obliquity factor, and they overlap only in the
-obliquity — and a constant nominal `n * pixel / dist` is **not** a valid
-"pixel-derived" acceptance, being wrong by `1/cos(theta)` (1.2 % at 9 degrees).
-`out_of_plane_acceptance` is still what the rocking path divides by.
+## 5. The wiring commit, as landed
+
+`feat(phys)!` — it changed saved numbers in **both** modes. What it did:
+
+1. **Normalization.** `peak1Dintegr.RockingPeakIntegrator._rocking_normalization`
+   builds the per-frame exposure/monitor divisor from the stored `auxillary`
+   counters (see section 2.2 for why not from a scan object) and it is applied
+   **inside** the rocking integral, not to the finished integral: with a
+   varying counting time or a drifting monitor the quantity Vlieg integrates is
+   `Int N(omega)/(T M) d omega`, and dividing the result by a mean is only
+   equivalent for constant counters. It rides the existing `C_corr` machinery,
+   which already carried `C_illum_area` per `(s, omega)` point, so the error
+   propagation followed for free.
+2. **Radian.** `measurement.normalized_intensity(..., angle_unit="deg")`
+   converts when `F2_hkl` is formed. The stored `croibg` and `int_interval`
+   stay in the unit they were measured in — changing those would change the
+   meaning of two saved columns for no gain.
+3. **Acceptance.** `_rocking_acceptance` calls `out_of_plane_acceptance` with
+   the region centre and vertical size stored per `s` point. Two traps here:
+   the coordinate order (`surfaceAnglesPoint` takes pyFAI dimension 1 first,
+   which is the *row*, and orGUI's `y` is the row while `x` is the column —
+   every call site in the application passes them swapped), and `vsize` being
+   the row extent, which follows from `detvsize, dethsize = detector.shape`
+   at `orGUI.py:1096`. It is evaluated at the calibrated arm position, which
+   costs nothing measurable because the span is arm-invariant to nine digits.
+   With no calibrated detector reachable it warns and leaves `F2_hkl` on the
+   acceptance-blind scale rather than failing the integration.
+4. **Solid angle compensated, not removed.** The switch, its config key and
+   its badge are untouched, and it still scales the intensity — a broad or
+   diffuse feature wants a differential cross-section, and that capability was
+   worth keeping. What changed is that `F2_hkl` divides it back out, via the
+   new `detector.roi_mean_inverse_solid_angle`, measured over the same regions
+   from the calibrated geometry alone (no image, so it runs outside the
+   integration loop). Two things to know: the compensation is approximate at
+   the `1e-6` level, because `pixel_factors` fuses the solid angle with the
+   polarization so the applied mean is `<1/(Omega~ P)>` rather than a product
+   of means; and for a rocking scan the correction was applied at *extraction*
+   time, so whether to compensate is read from the configuration stored with
+   the scan (`configuration/orgui/integration_corrections/json`) rather than
+   from the current switch. An older database where that cannot be read warns
+   and is left uncompensated rather than guessed at.
+
+   A related trap, found by breaking it first: `useSolidAngleBox` is *also*
+   the store the reconstruction persists its own solid-angle setting through
+   (`config_data.py:383`/`:467` map the `solidAngle` integration option onto
+   `CorrectionState.use_solid_angle`, and `ReconstructionDialog` mirrors its
+   checkbox via `scanSelector.get/set_integration_options`). Removing the key
+   would have silently disabled the correction in the one path that must keep
+   it, and that is invisible from either file alone.
+5. **Provenance.** A `reduction` group beside `F2_hkl` records the mode, the
+   angle unit, which normalizations applied, whether the acceptance was
+   applied, whether the solid-angle correction was compensated, the
+   active-area assumption, and the acceptance array itself.
+
+`test_rocking_and_stationary_paths_differ_by_the_missing_normalizations`
+became `test_rocking_and_stationary_paths_agree`, and
+`test_a_resized_region_of_interest_distorts_the_rocking_rod` became
+`..._no_longer_distorts_...`. Both keep the *old* behaviour as a contrast
+assertion via a `reduce=False` switch on the helper, so the factor that used to
+be left behind cannot come back unnoticed.
 
 ## 6. After that
 
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
index 3b3cb7a..8ef1a18 100644
--- a/doc/design/ctr_structure_factor_scale.md
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -1,26 +1,26 @@
 # One structure-factor scale for rocking scans, stationary scans and reflectivity
 
-> **Status: analysis complete, reduction core and regression tests landed, GUI
-> paths not yet switched over.** This is the review document for
+> **Status: analysis complete, reduction landed and wired into both
+> integration paths.** This is the review document for
 > [issue #82](https://github.com/tifuchs/orGUI/issues/82) ("Regression tests
 > and validation of equivalence of rocking and stationary scan integration")
 > and for the physics half of
 > [issue #15](https://github.com/tifuchs/orGUI/issues/15) ("Calculate
 > quantitatively exact structure factors").
 >
-> It records why a rocking scan and a stationary scan of the same rod do
-> **not** currently produce the same `F2_hkl` in orGUI, quantifies each reason
-> on simulated data, and states what is still needed for an absolute scale and
+> It records why a rocking scan and a stationary scan of the same rod did
+> **not** produce the same `F2_hkl` in orGUI, quantifies each reason on
+> simulated data, and states what is still needed for an absolute scale and
 > for absolute reflectivity. Everything below was verified numerically against
-> the code as of this branch, not by inspection alone.
+> the code, not by inspection alone.
 >
-> Landed with this document:
-> `orgui/datautils/xrayutils/corrections/measurement.py` (the reduction, pure
-> functions, additive - no existing number changes),
-> `orgui/datautils/xrayutils/test/test_corrections_measurement.py` (18 tests
-> against the published equations) and
-> `orgui/app/test/test_scan_mode_equivalence.py` (5 tests that simulate one
-> rod measured both ways and push it through both of orGUI's current paths).
+> F1, F2, F3 and F6 are now **applied**, which changed saved numbers in both
+> modes; the two paths agree to `1e-6` on simulated data, limited by the
+> trapezoidal sampling of the rocking profile. F4, F5 and F7 remain open and
+> are described below as they stand. Findings are written in the present tense
+> of the analysis; section 5 says what each one's status is now, and
+> [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
+> section 5 says how each was wired.
 
 ## 1. What the two papers require
 
@@ -70,7 +70,7 @@ Their ratio (Vlieg eq. 64/65) is the identity issue #82 is really about:
 I_s / I_omega = T omega_0 sin(delta) cos(beta_in) / (Delta_gamma sin(gamma))
 ```
 
-## 2. What orGUI does today
+## 2. What orGUI did before this work
 
 | | rocking (`peak1Dintegr`) | stationary (`orGUI.integrateROI` + `integration_corrections`) | reconstruction (`reconstruction_job`) |
 |---|---|---|---|
@@ -220,11 +220,19 @@ The solid-angle array and an angle-derived `Delta_gamma` describe the same
 geometry. Applying one without the other double-counts, so the pair has to be
 decided together with F3.
 
-**Resolved: ROI-summed integration does not apply a solid-angle correction at
-all, in either mode.** The array stays where it is genuinely required, the
-per-pixel reconstruction path, which forms a differential cross-section rather
-than a sum over an aperture - and which has its own independent switch
-(`reconstruction_job.py:1254`), so this does not touch it.
+**Resolved: the solid-angle correction stays available as a switch, scales the
+intensity, and is divided back out when `F2_hkl` is formed.** It is kept
+because it is the right correction for a *broad or diffuse* feature, where a
+differential cross-section rather than an integrated rod intensity is wanted;
+it is removed from the structure factor because a rod is integrated by summing
+a region, which is already the complete angular integral. The per-pixel
+reconstruction keeps applying it without compensation, under its own switch
+(`reconstruction_job.py:1254`).
+
+An earlier revision of this document had the correction dropped from ROI
+integration altogether. That was reversed: it discarded a capability that has
+a real use, and the compensation costs one geometric factor. The physics below
+is unchanged - what changed is where the factor is removed, not whether.
 
 Three steps to that conclusion:
 
@@ -241,11 +249,18 @@ Three steps to that conclusion:
    the rod. The slice is what `Delta_gamma` accounts for; there is still no
    per-pixel weighting to undo.
 
-Leaving the correction in and compensating for it in the reduction was
-considered and rejected. It gives the identical `|F|^2` - what is divided out
-is exactly the scalar that was multiplied in - but it needs one more argument
-on the reduction, and it puts the stored intensity column and `F2_hkl` on
-different scales. What it cannot do is stay in *uncompensated*, because the
+The compensation is
+`detector.roi_mean_inverse_solid_angle`, the mean of `1/Omega~` over the
+nominal region rectangle, evaluated from the calibrated geometry alone so it
+needs no image and can be computed per frame outside the integration loop.
+Two approximations come with that, both far below the effect being removed:
+it is the mean over the *nominal* region rather than over the valid pixels the
+integration accumulated, and because `pixel_factors` fuses the solid angle
+with the polarization into one array, the applied mean is
+`<1/(Omega~ P)>` rather than `<1/Omega~><1/P>`, leaving their covariance over
+the region - second order in the variation across it, of order `1e-6`.
+
+What the correction cannot do is stay in *uncompensated*, because the
 two modes do not carry it symmetrically: for a rocking scan the
 omega-integrated counts in pixel row *j* go as that row's gamma height
 `dgamma_j`, so a corrected sum pairs with `Sum_j dgamma_j / Omega~_j` and the
@@ -280,14 +295,19 @@ gone wrong under the other one:
   degrees. `pixel_acceptance` times the row count is the same angle-derived
   quantity as `out_of_plane_acceptance`, not a cheaper alternative to it.
 
-On the user-facing side, `useSolidAngleBox` (`QScanSelector.py:748`) drives
-nothing else: its only consumers are the two direct-space integration paths
-(`orGUI.py:1595` in `rocking_integrate`, `:5765` in `integrateROI`). Dropping
-the widget, the `solidAngle` key from `get_integration_options` and the `SOLA`
-badge is therefore the whole change. Old configuration files stay loadable
-without a shim - `set_integration_options` is an `if`/`elif` chain over the
-keys that are present, with no `else`, so a stored `solidAngle` entry is
-ignored rather than an error.
+On the user-facing side the switch and its config key are untouched, so
+nothing about existing configurations changes. Note that `useSolidAngleBox`
+is *also* the store the reciprocal-space reconstruction persists its own
+solid-angle setting through: `config_data.py:383`/`:467` map the `solidAngle`
+integration option onto `CorrectionState.use_solid_angle`, and
+`ReconstructionDialog` mirrors its checkbox via
+`scanSelector.get/set_integration_options`. Removing the key would therefore
+have silently disabled the correction in the one path that must keep it - a
+trap worth recording, because it is invisible from either file alone.
+
+What the switch means is now stated in its tooltip and in the `SOLA` badge,
+since "applied to the intensity but not to `F2_hkl`" is not something a user
+can infer from a checkbox.
 
 ### F7 - `C_det` is assumed to be 1 in both modes
 
@@ -466,9 +486,17 @@ Measured against a calibrated 172 um detector at 1 m, a 60-row region accepts
 mille towards the detector edge - the obliquity that makes `Delta_gamma` vary
 along a scan in the first place.
 
-## 5. What is needed to close issue #82
+## 5. Status of each finding
+
+**F1, F2, F3 and F6 are applied.** Steps 1-5 below are done; the wiring of
+each is in [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
+section 5, and the equivalence is asserted by
+`test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_agree`.
+Step 6, the real-data check, is the one that remains, together with F4, F5 and
+F7.
 
-In order:
+Recorded in the order they had to be done, because the ordering was itself a
+result -- F6 had to be settled before F3 could be wired:
 
 1. **Normalize rocking scans.** Give `RockingPeakIntegrator.integrate` the same
    `normalization_divisor` the stationary path uses. The per-frame counting
@@ -486,23 +514,31 @@ In order:
    * Pass the per-frame arm angles from `scan_arm_angles` where they are known.
      They turn out to matter far less than expected (section 4.4), but they
      cost nothing.
-   * Stop applying the solid-angle correction first (step 4): `Delta_gamma`
-     and the solid-angle correction each carry the same obliquity, and
-     leaving both in double-counts it.
-4. **Stop applying the solid-angle correction to ROI sums, in both modes.**
-   (F6) A ROI sum is already a complete angular integral. This also touches
-   `orGUI.integrateROI`, and it changes stationary saved numbers by
-   `<1/Omega~>` - 0.7 % at 1 m, 7 % at 0.3 m - so it belongs in the same
-   breaking commit as the rocking wiring, not a later one. The reconstruction
-   path keeps its own solid-angle switch and is unaffected.
+   * Settle the solid-angle compensation first (step 4): `Delta_gamma` and
+     the solid-angle correction each carry the same obliquity, and leaving
+     both in double-counts it.
+4. **Divide the solid-angle correction back out of `F2_hkl`, in both modes.**
+   (F6) A ROI sum is already a complete angular integral, so the correction
+   must not reach a structure factor - but it stays on the intensity, where a
+   broad or diffuse feature needs it. This also touches `orGUI.integrateROI`,
+   and it changes stationary `F2_hkl` by `<1/Omega~>` whenever the switch was
+   on - 0.7 % at 1 m, 7 % at 0.3 m - so it belongs in the same breaking commit
+   as the rocking wiring, not a later one. The reconstruction path keeps
+   applying it uncompensated and is unaffected.
 5. **Record the mode and its inputs in the saved data**, next to `F2_hkl`: the
    acceptance, the normalization that was applied, and the active-area
    assumption of F4. Without them a saved rod cannot be put on a common scale
    after the fact.
-6. **Then verify on real data.** The overlap region of a rocking scan and a
-   stationary scan on the same rod (Drnec Fig. 8, right) is the acceptance
-   test. Simulation cannot catch F7, an incorrect `Delta_gamma` definition, or
-   a beamline that reports counting time in the wrong place.
+6. **Then verify on real data. Not done — this is the remaining step.** The
+   overlap region of a rocking scan and a stationary scan on the same rod
+   (Drnec Fig. 8, right) is the acceptance test. Simulation cannot catch F7,
+   an incorrect `Delta_gamma` definition, or a beamline that reports counting
+   time in the wrong place. The simulated equivalence test does cover the F6
+   compensation
+   (`test_the_solid_angle_correction_does_not_reach_the_structure_factor`),
+   but it supplies the region mean itself rather than reading a detector, so
+   the geometry evaluation is pinned separately in
+   `test_corrections_detector.py`.
 
 ## 6. What is needed to close issue #15, and reflectivity
 
diff --git a/doc/source/image_integration.rst b/doc/source/image_integration.rst
index 1f346f5..737a033 100644
--- a/doc/source/image_integration.rst
+++ b/doc/source/image_integration.rst
@@ -166,45 +166,69 @@ instead, which is the row the manual marks as calculated numerically.
 Comparing Scan Modes
 ~~~~~~~~~~~~~~~~~~~~
 
-``F2_hkl`` is proportional to :math:`|F_{hkl}|^2` **within** one integration
-mode, but a rocking scan and a stationary scan of the same rod are not
-currently on the same scale, and the two must not be plotted or fitted
-together without rescaling.
+A rocking scan and a stationary scan of the same rod are reduced to the same
+``F2_hkl`` and may be plotted and fitted together. Verified on simulated data
+to a relative :math:`10^{-6}`, the residual being the trapezoidal sampling of
+the rocking profile.
 
 Vlieg's rocking-scan expression (equation 42) contains three factors that the
-stationary expression (equation 54) does not, and that orGUI's rocking
-integration does not divide out:
-
-* the **counting time and monitor**. ``Normalize integrated intensities``
-  applies to stationary integration only; a rocking integration is not
-  normalized.
-* the **unit of the rocking angle**. The rocking curve is integrated over the
-  motor position in degrees, while the published expressions integrate in
-  radian, a factor :math:`180/\pi`.
+stationary expression (equation 54) does not, and all three are applied:
+
+* the **counting time and monitor**, divided out per frame *inside* the
+  rocking integral, so that a varying counting time or a drifting monitor is
+  handled correctly and not merely on average. A rocking integration takes
+  these from the counters stored with the scan, so it needs a beamline backend
+  that lists ``exposure_time`` among its auxiliary counters; a counter that is
+  not there is skipped, and what was applied is recorded with the result.
+* the **unit of the rocking angle**. The published expressions integrate in
+  radian; the motor axis is in degrees, and the factor :math:`180/\pi` is
+  applied when ``F2_hkl`` is formed. The stored ``croibg`` and the integration
+  interval stay in degrees, the unit they were measured in.
 * the **out-of-plane angular acceptance** :math:`\Delta\gamma` of the region
   of interest. A rocking scan intercepts a slice of rod whose length is
   proportional to :math:`\Delta\gamma`, so its integrated intensity is too; a
   stationary measurement intercepts the whole rod cross-section and has no
   such factor. Because ROIs are sized per detector position, this factor is
-  not even constant along one rocking data set, so it changes the *shape* of
-  a rod and not only its scale.
-
-Together,
-
-.. math::
-
-   \frac{F^2_{hkl,\mathrm{rocking}}}{F^2_{hkl,\mathrm{stationary}}}
-   = T\;M\;\Delta\gamma[^\circ]
-
-with :math:`T` the per-frame counting time, :math:`M` the monitor value and
-:math:`\Delta\gamma` the acceptance in degrees.
-
-:mod:`orgui.datautils.xrayutils.corrections.measurement` implements the full
-reduction, for rocking scans, stationary scans and reflectivity, and is the
-supported way to put integrated intensities from different modes on one
-scale --- and, given the incident flux and the illuminated area, on the
-absolute scale of :math:`|F_{hkl}|^2` in electron units. The integration
-paths do not use it yet.
+  not constant along one rocking data set, so leaving it out changed the
+  *shape* of a rod and not only its scale.
+
+The **detector solid-angle correction** is treated separately, and does not
+reach a structure factor. Summing a region of interest already produces the
+complete angular integral, each pixel weighted by the solid angle it subtends,
+so dividing by that solid angle again would double-count the detector
+obliquity -- 0.7 % for a detector at 1 m and 7 % at 0.3 m, varying across the
+detector face, and therefore a rod *shape* error.
+
+The switch remains, because the correction is the right one for a **broad or
+diffuse feature**, where a differential cross section rather than an
+integrated rod intensity is what is wanted. What it does is scoped:
+
+* it scales the **intensity** counters, as before;
+* it is measured over the same regions of interest and **divided back out**
+  when ``F2_hkl`` is formed, so a structure factor is the same number whether
+  or not the switch was on;
+* the **reciprocal-space reconstruction** keeps applying it and does not
+  divide it out, since that path forms a differential cross section per pixel.
+
+For a rocking scan the correction is applied when the curves are extracted, so
+whether to remove it again is read from the configuration stored with the
+scan rather than from the current state of the switch. If that cannot be
+established -- an older database -- the integration warns and leaves it in
+rather than guessing.
+
+Each integrated rocking scan stores a ``reduction`` group beside ``F2_hkl``
+recording the mode, the angle unit, which normalizations were applied, the
+acceptance that was divided out, whether the solid-angle correction was
+compensated and the active-area assumption, so that a saved rod can be placed
+on a common scale after the fact.
+
+What is still **not** on this scale is the absolute one: ``F2_hkl`` is
+proportional to :math:`|F_{hkl}|^2` with one common, arbitrary constant.
+:mod:`orgui.datautils.xrayutils.corrections.measurement` supplies the absolute
+prefactor given the incident flux density and the illuminated area, and
+converts between :math:`|F_{hkl}|^2` and absolute reflectivity.
+``doc/physics/ctr_structure_factor_physics.tex`` is a typeset reference for
+every normalization and integration interval described here.
 
 
 Exposure and Monitor Normalization
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index f1cf643..6d85d19 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -9,11 +9,13 @@ Unreleased (2026-07-19)
 
 Scientific and analysis additions:
 
+- **Rocking and stationary integration now produce the same structure factor.** *This changes saved numbers in both modes.* A rocking scan and a stationary scan of the same rod previously differed by exactly exposure time times monitor times the out-of-plane acceptance in degrees; they now agree. Four corrections changed. The rocking path gained the per-frame exposure and monitor normalization, applied inside the rocking integral so that a varying counting time or a drifting monitor is handled correctly rather than only on average; it now integrates the rocking angle in radian as the published expressions require, rather than in degrees; and it divides by the out-of-plane acceptance of its region of interest, without which a rod measured with regions resized along the scan came out with a distorted *shape* -- a factor 2.3 across a simulated Pt(111) rod -- and not merely a wrong scale. Separately, the detector **solid-angle correction no longer reaches a structure factor** in either mode: summing a region of interest already yields the complete angular integral, with every pixel weighted by the solid angle it subtends, so dividing by that solid angle again double-counted the detector obliquity (0.7 % for a detector at 1 m, 7 % at 0.3 m, varying across the detector and therefore a rod shape error). The switch stays, because that correction is the right one for a broad or diffuse feature where a differential cross section is wanted: it still scales the intensity counters, and is now measured over the same regions of interest and divided back out when ``F2_hkl`` is formed, so a structure factor is the same number whether or not it was enabled. Its tooltip and the ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps applying it uncompensated, since that path does form a differential cross section per pixel. For rocking scans the correction is applied when the curves are extracted, so whether to remove it again is read from the configuration stored with the scan; an older database where that cannot be established warns and is left uncompensated. Integrated rocking scans now store a ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit, which normalizations were applied, the acceptance used, whether the solid-angle correction was compensated, and the active-area assumption, so that a saved rod can be placed on a common scale afterwards. Rocking normalization uses the counters stored with the scan, so it requires a backend that declares ``exposure_time`` in ``auxillary_counters``; a missing counter is skipped and recorded rather than failing the integration. Existing configuration files load unchanged.
+
 - **All correction factors collected into one package.** Every factor between detector counts and a structure factor now lives in ``orgui.datautils.xrayutils.corrections``, split by what it depends on: ``geometry`` (the z-axis Lorentz, rod-interception and area table), ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and polarization), ``normalization`` (counting time and monitor), ``roi``, and ``measurement``. The rocking integration, the stationary integration and the reciprocal-space reconstruction previously each carried their own copy of several of these; they now share one definition, so they cannot drift onto different scales. The package is physics only -- numbers in, numbers out -- and reads no scan object, configuration or widget; ``orgui.app`` ``integration_corrections`` is the adapter that supplies those. ``orgui.datautils.xrayutils.geometrycorrections`` and ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the moved modules. **No calculated value changes.**
 
-- **Out-of-plane detector acceptance.** ``orgui.datautils.xrayutils.corrections.acceptance`` estimates ``Delta_gamma``, the angular height of a region of interest as seen from the sample, which a rocking-scan integrated intensity is proportional to (Vlieg equations 20 and 42) and which orGUI previously did not compute at all. Measured edge to edge, at the region's centre column where the rod crosses the aperture, and vectorized over a scan because orGUI resizes regions per detector position. ``gamma_range`` reports the span over the whole region as a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row case. **A new API only: the integration paths do not call it yet.**
+- **Out-of-plane detector acceptance.** ``orgui.datautils.xrayutils.corrections.acceptance`` estimates ``Delta_gamma``, the angular height of a region of interest as seen from the sample, which a rocking-scan integrated intensity is proportional to (Vlieg equations 20 and 42) and which orGUI previously did not compute at all. Measured edge to edge, at the region's centre column where the rod crosses the aperture, and vectorized over a scan because orGUI resizes regions per detector position. ``gamma_range`` reports the span over the whole region as a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row case. The rocking integration now divides by it -- see the mode-equivalence entry below.
 
-- **One structure-factor scale for rocking scans, stationary scans, and reflectivity.** The new public module ``orgui.datautils.xrayutils.corrections.measurement`` reduces an integrated intensity to ``|F_hkl|^2`` for any scan mode, following E. Vlieg, *J. Appl. Cryst.* 30 (1997) 532 and J. Drnec et al., *J. Appl. Cryst.* 47 (2014) 365. It normalizes counts by exposure time and monitor, converts a rocking integral from degrees to radians, applies the mode-dependent angular factor (rocking scans additionally require the out-of-plane acceptance of the region of interest, stationary measurements reject it), and, given the incident flux density and the illuminated area, puts the result on the absolute electron-unit scale. It also converts between ``|F_hkl|^2`` and absolute reflectivity, so a reflectivity curve and a set of truncation rods can be brought onto one scale. **This is a new API only: no existing integration result changes.** The integration paths do not use it yet, and rocking and stationary integration remain on different scales, differing by exposure time times monitor times the acceptance in degrees; the image-integration documentation now says so explicitly, and ``doc/design/ctr_structure_factor_scale.md`` records the full analysis with the measured size of every correction.
+- **One structure-factor scale for rocking scans, stationary scans, and reflectivity.** The new public module ``orgui.datautils.xrayutils.corrections.measurement`` reduces an integrated intensity to ``|F_hkl|^2`` for any scan mode, following E. Vlieg, *J. Appl. Cryst.* 30 (1997) 532 and J. Drnec et al., *J. Appl. Cryst.* 47 (2014) 365. It normalizes counts by exposure time and monitor, converts a rocking integral from degrees to radians, applies the mode-dependent angular factor (rocking scans additionally require the out-of-plane acceptance of the region of interest, stationary measurements reject it), and, given the incident flux density and the illuminated area, puts the result on the absolute electron-unit scale. It also converts between ``|F_hkl|^2`` and absolute reflectivity, so a reflectivity curve and a set of truncation rods can be brought onto one scale. ``doc/design/ctr_structure_factor_scale.md`` records the full analysis with the measured size of every correction, and ``doc/physics/ctr_structure_factor_physics.tex`` is a typeset reference for the normalizations and integration intervals.
 
 - **Unified CTR fit predictions, lifecycle, and statistics.** CTR optimizer predictions, residuals, likelihoods, and diagnostics now use one final analytically scaled result path. ``flat_prediction`` supports the common F/R result contract, while ``flat_Fcalc``, ``Rfactor``, and the new ``Rfactor_R`` enforce quantity-specific diagnostics. ``calculated_CTRs`` now always exposes the latest successful final predictions, independently of resolution broadening. Evaluation requires ``prepareFit()`` after parameter layout changes, supported fixed-model changes refresh automatically, and a failed evaluation cannot leave a stale public result. Fit statistics count eliminated analytical scales in their degrees of freedom, report covariance on the same reduced-chi-square scale as parameter errors, and clear unavailable errors throughout the fitted crystal instead of retaining an older estimate.
 
diff --git a/orgui/app/QScanSelector.py b/orgui/app/QScanSelector.py
index 0663c34..94df425 100644
--- a/orgui/app/QScanSelector.py
+++ b/orgui/app/QScanSelector.py
@@ -924,7 +924,12 @@ def get_integration_options(self):
     #: corrections button shows.
     CORRECTION_BADGES = (
         ("useMaskBox", "MASK", "#b58900", "Pixel mask applied"),
-        ("useSolidAngleBox", "SOLA", "#268bd2", "Solid angle correction"),
+        (
+            "useSolidAngleBox",
+            "SOLA",
+            "#268bd2",
+            "Solid angle correction (intensity only; divided back out of F2_hkl)",
+        ),
         ("usePolarizationBox", "POL", "#6c71c4", "Polarization correction"),
         (
             "useLorentzBox",
@@ -1903,6 +1908,20 @@ def __init__(self, selector, parent=None):
         )
         self.maskToolBtn.clicked.connect(self._openMaskTool)
         detectorLayout.addWidget(self.maskToolBtn)
+        selector.useSolidAngleBox.setToolTip(
+            "Divide each pixel by the solid angle it subtends, giving an "
+            "intensity proportional to the differential cross section. This "
+            "is what a broad or diffuse feature needs.\n\n"
+            "It does not affect structure factors. A rod is integrated by "
+            "summing a region, which already gives the complete angular "
+            "integral with every pixel weighted by its own solid angle, so "
+            "the correction is measured over the region and divided back out "
+            "when F2_hkl is formed. Leaving it in would double-count the "
+            "detector obliquity: 0.7 % for a detector at 1 m and 7 % at "
+            "0.3 m, varying across the detector.\n\n"
+            "The reciprocal-space reconstruction has its own switch, and does "
+            "need this correction."
+        )
         detectorLayout.addWidget(selector.useSolidAngleBox)
         detectorLayout.addWidget(selector.usePolarizationBox)
         detector.setLayout(detectorLayout)
diff --git a/orgui/app/integration_corrections.py b/orgui/app/integration_corrections.py
index bd9d708..ec68ec5 100644
--- a/orgui/app/integration_corrections.py
+++ b/orgui/app/integration_corrections.py
@@ -154,6 +154,7 @@ def stationary_correction_factors(
     beam_profile=None,
     sample_size=None,
     normalization=None,
+    solid_angle_mean=None,
 ):
     r"""Correction divisors for one stationary-scan trajectory.
 
@@ -174,6 +175,13 @@ def stationary_correction_factors(
         when ``use_footprint`` is set.
     :param normalization: Optional per-image exposure and monitor divisor
         from :func:`normalization_divisor`, stored as ``C_norm``.
+    :param solid_angle_mean: Optional per-image region mean of
+        :math:`1/\widetilde{\Omega}` from
+        :func:`~orgui.datautils.xrayutils.corrections.detector.roi_mean_inverse_solid_angle`,
+        stored as ``C_solid_angle``. Pass it when the solid-angle correction
+        was applied to the intensity, so that :func:`structure_factor` can
+        divide it back out; a region sum is already a complete angular
+        integral and must not carry it (finding F6).
     :returns: The factors, each broadcast to the shape of ``alpha``.
     :rtype: CorrectionFactors
     :raises ValueError: If the footprint correction is requested without a
@@ -189,6 +197,12 @@ def stationary_correction_factors(
         ).copy()
         applied.append("normalization")
 
+    if solid_angle_mean is not None:
+        factors["C_solid_angle"] = np.broadcast_to(
+            np.asarray(solid_angle_mean, dtype=np.float64), alpha.shape
+        ).copy()
+        applied.append("solid_angle")
+
     if use_footprint:
         if beam_profile is None:
             raise ValueError(
@@ -236,16 +250,27 @@ def apply_stationary_corrections(intensity, errors, factors):
 def structure_factor(intensity, errors, factors):
     r"""Form :math:`F^2_{hkl}` from an already corrected intensity.
 
-    :math:`F^2 = I_\mathrm{corr} / L_\mathrm{stationary}`. Unlike a rocking
+    :math:`F^2 = I_\mathrm{corr} /
+    (L_\mathrm{stationary}\,C_\mathrm{solid\,angle})`. Unlike a rocking
     scan, stationary area-detector integration has no rod-interception
     factor.
 
+    ``C_solid_angle`` is present only when the solid-angle correction was
+    applied to the intensity, and dividing by it removes that correction
+    again. A region-summed intensity is already the complete angular
+    integral, with every pixel weighted by the solid angle it subtends, so
+    the correction double-counts the detector obliquity in a structure
+    factor -- while remaining useful on the intensity itself for broad,
+    non-rod features, where a differential cross-section is the goal. See
+    ``doc/design/ctr_structure_factor_scale.md`` finding F6.
+
     :param intensity: Corrected intensity per image.
     :param errors: 1-sigma errors of ``intensity``.
-    :param CorrectionFactors factors: Must contain ``C_Lorentz``.
+    :param CorrectionFactors factors: Must contain ``C_Lorentz``; divides by
+        ``C_solid_angle`` as well when it is present.
     :returns: ``(F2_hkl, F2_hkl_errors)``.
     :rtype: tuple of numpy.ndarray
     :raises KeyError: If the Lorentz factors are absent.
     """
-    divisor = factors["C_Lorentz"]
+    divisor = factors["C_Lorentz"] * factors.divisor("C_solid_angle")
     return np.asarray(intensity) / divisor, np.asarray(errors) / divisor
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index 6ec5bef..f454a37 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -6383,8 +6383,38 @@ def sumImage(i):
                 )
             )
 
+        # The solid-angle correction is useful on the *intensity* -- for broad,
+        # non-rod features a differential cross-section is what is wanted --
+        # but it must not reach a structure factor: a region sum is already the
+        # complete angular integral, each pixel weighted by the solid angle it
+        # subtends. So it is measured here over the same regions and divided
+        # back out when F2_hkl is formed. Finding F6 of
+        # doc/design/ctr_structure_factor_scale.md; the per-pixel
+        # reconstruction keeps it, because that path does form a differential
+        # cross-section.
+        solid_angle_means = (None, None)
+        if self.scanSelector.useSolidAngleBox.isChecked():
+            solid_angle_means = tuple(
+                detector_corrections.roi_mean_inverse_solid_angle(
+                    dc,
+                    row,
+                    column,
+                    # A frame whose region fell off the detector can leave a
+                    # degenerate size behind; it carries no counts either, so
+                    # one pixel keeps the factor defined and harmless.
+                    np.maximum(row_size, 1),
+                    np.maximum(column_size, 1),
+                )
+                for row, column, row_size, column_size in (
+                    (y_coord1_a, x_coord1_a, roi_vsize1_a, roi_hsize1_a),
+                    (y_coord2_a, x_coord2_a, roi_vsize2_a, roi_hsize2_a),
+                )
+            )
+
         correction_factors = []
-        for hkl_del_gam in (hkl_del_gam_1, hkl_del_gam_2):
+        for hkl_del_gam, solid_angle_mean in zip(
+            (hkl_del_gam_1, hkl_del_gam_2), solid_angle_means
+        ):
             correction_factors.append(
                 integration_corrections.stationary_correction_factors(
                     alpha_all,
@@ -6395,6 +6425,7 @@ def sumImage(i):
                     beam_profile=beam_profile,
                     sample_size=sample_size,
                     normalization=normalization,
+                    solid_angle_mean=solid_angle_mean,
                 )
             )
         factors1, factors2 = correction_factors
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 0a9ee6c..8b99d4c 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -31,6 +31,7 @@
 __maintainer__ = "Timo Fuchs"
 __email__ = "tfuchs@cornell.edu"
 
+import json
 import logging
 import sys
 import os
@@ -59,7 +60,10 @@
 from .. import logger_utils
 from ..datautils.xrayutils.corrections import beamprofile
 from ..datautils.xrayutils.corrections import (
+    acceptance as acceptance_corrections,
+    detector as detector_corrections,
     measurement as measurement_corrections,
+    normalization as normalization_corrections,
 )
 
 import numpy as np
@@ -113,6 +117,10 @@ def _compute_rocking_integration(
     C_rod=1.0,
     C_flux_on_sample=1.0,
     C_illum_area=1.0,
+    C_norm=1.0,
+    detector_acceptance=None,
+    solid_angle_mean=None,
+    angle_unit="deg",
     progress_callback=None,
     should_cancel=None,
 ):
@@ -158,6 +166,32 @@ def _compute_rocking_integration(
     :param C_illum_area:
         Scalar ``1.0`` or array of shape ``(n_s, n_pts)``, illuminated-area
         factor.
+    :param C_norm:
+        Scalar ``1.0`` or array of shape ``(n_s, n_pts)``, the per-frame
+        exposure-time and monitor divisor. It is applied **inside** the
+        rocking integral, not to the result: with a varying counting time or a
+        drifting monitor the quantity Vlieg's expression integrates is
+        :math:`\\int N(\\omega)/(T M)\\,d\\omega`, and dividing the finished
+        integral by a mean would only be equivalent for constant counters.
+    :param detector_acceptance:
+        Out-of-plane acceptance :math:`\\Delta\\gamma` of the region of
+        interest per ``s`` point, in **radian**, shape ``(n_s,)``. A rocking
+        scan intercepts a slice of rod proportional to it, so it divides
+        ``F2_hkl``. ``None`` leaves it out, which reproduces the historical,
+        acceptance-blind scale.
+    :param solid_angle_mean:
+        Region mean of :math:`1/\\widetilde{\\Omega}` per ``s`` point, shape
+        ``(n_s,)``, when the solid-angle correction is already inside the
+        curves. It divides ``F2_hkl``, removing it again: a region sum is the
+        complete angular integral already, so the correction double-counts the
+        detector obliquity in a structure factor even though it is what a
+        broad, non-rod feature wants on its intensity. ``None`` when the
+        correction was not applied.
+    :param str angle_unit:
+        Unit of ``axis``, ``'deg'`` or ``'rad'``. The published expressions
+        integrate the rocking angle in radian; ``'deg'`` converts the integral
+        when ``F2_hkl`` is formed, leaving the stored intensities and interval
+        widths in the unit they were measured in.
     :param progress_callback:
         Optional callable invoked with the current ``s`` index after each
         point is processed.
@@ -182,6 +216,7 @@ def _compute_rocking_integration(
                 "raw_cnts": [],
                 "raw_cnts_errors": [],
                 "int_interval": [],
+                "C_norm": [],
                 "C_Lor": [],
                 "C_rod": [],
                 "C_flux_on_sample": [],
@@ -216,6 +251,17 @@ def _compute_rocking_integration(
             cnts_errors = croibg_errors[roi_slice]
 
             C_corr = np.ones(cnts.size, dtype=float)
+            if not np.isscalar(C_norm) or C_norm != 1.0:
+                # Per-frame, so it belongs under the integral sign; see the
+                # C_norm parameter documentation.
+                C_norm_roi = np.broadcast_to(
+                    np.asarray(C_norm, dtype=float), croibg_curves.shape
+                )[i][roi_slice]
+                int_data[roikey]["C_norm"].append(np.mean(C_norm_roi))
+                C_corr = C_corr * C_norm_roi
+            else:
+                int_data[roikey]["C_norm"].append(1.0)
+
             if use_lorentz:
                 int_data[roikey]["C_Lor"].append(np.mean(C_Lor[i][roi_slice]))
                 int_data[roikey]["C_rod"].append(np.mean(C_rod[i][roi_slice]))
@@ -404,8 +450,26 @@ def _compute_rocking_integration(
     result["auxil"] = auxil
 
     if use_lorentz:
-        result["F2_hkl"] = croibg / (C_Lorentz * C_rod_intersect)
-        result["F2_hkl_errors"] = croibg_errors / (C_Lorentz * C_rod_intersect)
+        # The rocking angle is the integration variable and must be in radian
+        # (Vlieg eq. 42, Drnec eq. 2). The exposure and monitor divisor is
+        # already inside croibg, applied per frame above, so only the angle
+        # conversion is left for normalized_intensity to do here.
+        intensity = measurement_corrections.normalized_intensity(
+            croibg, angle_unit=angle_unit
+        )
+        intensity_errors = measurement_corrections.normalized_intensity(
+            croibg_errors, angle_unit=angle_unit
+        )
+        # The mode components are interval-weighted means over the rocking
+        # interval, which is why they are multiplied here rather than asking
+        # measurement.angular_factor to rebuild eta from point angles.
+        denominator = C_Lorentz * C_rod_intersect
+        if detector_acceptance is not None:
+            denominator = denominator * np.asarray(detector_acceptance, dtype=float)
+        if solid_angle_mean is not None:
+            denominator = denominator * np.asarray(solid_angle_mean, dtype=float)
+        result["F2_hkl"] = intensity / denominator
+        result["F2_hkl_errors"] = intensity_errors / denominator
 
     return result
 
@@ -1304,6 +1368,184 @@ def fit_anchors_along_rod(self):
                     roih5grp[roikey]["to"][:] = to_ar
             self.plotRoCurve(self._idx)
 
+    def _rocking_normalization(self, aux, size):
+        """Per-frame exposure and monitor divisor of the rocking scan.
+
+        Unlike the stationary path this cannot ask a live scan object: a
+        rocking integration runs off the database, so the counters are read
+        from the ``auxillary`` group that
+        :meth:`orgui.app.orGUI.orGUI.rocking_integrate` copied there. Which
+        counters count as a monitor is the same setting the stationary
+        integration and the reconstruction use, so all three normalize
+        identically.
+
+        A counter that is simply not there is not an error -- a backend that
+        does not declare ``exposure_time`` in ``auxillary_counters`` never
+        stored one. The names of the factors that did apply are returned so
+        they can be saved beside ``F2_hkl``; without them a rod cannot be put
+        on a common scale after the fact.
+
+        :param dict aux: Auxiliary counters, each of shape ``(n_pts,)``.
+        :param int size: Number of frames of the rocking scan.
+        :returns: ``(divisor, applied)`` with the divisor of shape
+            ``(size,)``.
+        :rtype: tuple
+        """
+        config_target = self.database.config_target
+        monitor_names = tuple(
+            getattr(config_target, "reconstruction_monitor_corrections", ()) or ()
+        )
+
+        exposure = aux.get("exposure_time")
+        if exposure is None:
+            logger.warning(
+                "The rocking scan stores no exposure_time counter, so the "
+                "integrated intensities are not normalized to counting time. "
+                "They are then only comparable to other scans of the same "
+                "duration. The scan backend decides this by declaring "
+                "'exposure_time' in auxillary_counters."
+            )
+
+        monitors = {}
+        for name in monitor_names:
+            if name in aux:
+                monitors[name] = aux[name]
+            else:
+                logger.warning(
+                    "Monitor counter %r is configured but was not stored with "
+                    "this rocking scan; skipping it.",
+                    name,
+                )
+
+        return normalization_corrections.normalization_divisor(
+            size, exposure_time=exposure, monitors=monitors
+        )
+
+    def _rocking_solid_angle_mean(self, scangroup, cnters, x, y):
+        """Region mean of the solid-angle correction that was applied, or None.
+
+        The solid-angle correction is applied to the *intensity* when the
+        rocking curves are extracted, which is useful there: for a broad,
+        non-rod feature a differential cross-section is what is wanted. It
+        must not reach a structure factor, though, because a region sum is
+        already the complete angular integral with every pixel weighted by the
+        solid angle it subtends. So it is measured over the same regions here
+        and divided back out of ``F2_hkl``. See
+        ``doc/design/ctr_structure_factor_scale.md`` finding F6.
+
+        Whether it was applied is a property of the *extraction*, not of the
+        switches in this dialog, so it is read from the configuration snapshot
+        stored with the scan rather than from the current GUI state.
+
+        :param scangroup: The scan group holding the ``configuration`` written
+            when the rocking curves were extracted.
+        :param cnters: The ``rois`` group of the rocking scan.
+        :param x: Region centre column per ``s`` point, in pixels.
+        :param y: Region centre row per ``s`` point, in pixels.
+        :returns: ``(mean, applied)`` -- the per-``s`` mean of
+            :math:`1/\\widetilde{\\Omega}` and whether it will be divided out,
+            or ``(None, False)`` when the correction was not applied or cannot
+            be established.
+        :rtype: tuple
+        """
+        try:
+            raw = scangroup["configuration/orgui/integration_corrections/json"][()]
+            if isinstance(raw, bytes):
+                raw = raw.decode()
+            was_applied = bool(json.loads(str(raw)).get("use_solid_angle", False))
+        except Exception:
+            logger.warning(
+                "Cannot tell from this scan's stored configuration whether the "
+                "solid angle correction was applied when the rocking curves "
+                "were extracted, so it is not divided out of F2_hkl. If it was "
+                "applied, F2_hkl carries the detector obliquity and will not "
+                "agree with a stationary integration of the same rod."
+            )
+            return None, False
+
+        if not was_applied:
+            return None, False
+
+        config_target = self.database.config_target
+        detector = getattr(getattr(config_target, "ubcalc", None), "detectorCal", None)
+        if detector is None:
+            logger.warning(
+                "The solid angle correction was applied to these rocking "
+                "curves, but no calibrated detector is available to measure it "
+                "over the regions of interest, so it is not divided out of "
+                "F2_hkl."
+            )
+            return None, False
+
+        hsize = np.asarray(cnters["hsize"][()], dtype=float)
+        vsize = np.asarray(cnters["vsize"][()], dtype=float)
+        if hsize.ndim > 1:
+            hsize = hsize[:, 0]
+        if vsize.ndim > 1:
+            vsize = vsize[:, 0]
+
+        mean = detector_corrections.roi_mean_inverse_solid_angle(
+            detector,
+            np.asarray(y, dtype=float),
+            np.asarray(x, dtype=float),
+            np.maximum(vsize, 1.0),
+            np.maximum(hsize, 1.0),
+        )
+        return np.asarray(mean, dtype=float), True
+
+    def _rocking_acceptance(self, cnters, x, y):
+        """Out-of-plane acceptance of every region of interest, in radian.
+
+        A rocking scan intercepts a slice of rod proportional to
+        :math:`\\Delta\\gamma` (Vlieg equation 20), so ``F2_hkl`` is only on
+        the same scale as a stationary measurement once it is divided by it.
+
+        The region centre and its vertical size are stored per ``s`` point.
+        Note the coordinate order: ``surfaceAnglesPoint`` takes pyFAI
+        dimension 1 first, which is the detector *row*, and orGUI's ``y`` is
+        the row while ``x`` is the column -- every call site in the
+        application passes them in that swapped order.
+
+        The acceptance is evaluated at the **calibrated** arm position. The
+        span a region subtends is invariant under an arm rotation to nine
+        digits, because that rotation is about the very axis
+        :math:`\\gamma` is measured around, so this costs nothing measurable;
+        see ``doc/design/ctr_structure_factor_scale.md`` section 4.4.
+
+        :param cnters: The ``rois`` group of the rocking scan.
+        :param x: Region centre column per ``s`` point, in pixels.
+        :param y: Region centre row per ``s`` point, in pixels.
+        :returns: ``(acceptance, applied)`` -- the acceptance in radian of
+            shape ``(n_s,)``, or ``(None, False)`` when no calibrated
+            detector is reachable.
+        :rtype: tuple
+        """
+        config_target = self.database.config_target
+        detector = getattr(getattr(config_target, "ubcalc", None), "detectorCal", None)
+        if detector is None:
+            logger.warning(
+                "No calibrated detector is available, so the out-of-plane "
+                "acceptance of the regions of interest cannot be calculated. "
+                "F2_hkl is left on the acceptance-blind scale and will not "
+                "agree with a stationary integration of the same rod."
+            )
+            return None, False
+
+        vsize = cnters["vsize"][()]
+        vsize = np.asarray(vsize, dtype=float)
+        if vsize.ndim > 1:
+            vsize = vsize[:, 0]
+        alpha_pk = np.deg2rad(np.asarray(cnters["alpha_pk"][()], dtype=float))
+
+        acceptance = acceptance_corrections.out_of_plane_acceptance(
+            detector,
+            np.asarray(y, dtype=float),
+            np.asarray(x, dtype=float),
+            vsize,
+            alpha_pk,
+        )
+        return np.asarray(acceptance, dtype=float), True
+
     def integrate(self):
         """Integrate rocking-scan ROIs.
 
@@ -1367,6 +1609,36 @@ def integrate(self):
             C_flux_on_sample = 1.0
             C_illum_area = 1.0
 
+        if cnters["x"].ndim > 1:
+            warnings.warn(
+                "You are using an old data base orGUI v1.3.0-alpha"
+                "X and Y pixel coordinates of rocking scans will be incorrect"
+            )
+            x = cnters["x"][:, 0][
+                ()
+            ]  # may provide fix of database here, if anyone asks
+            y = cnters["y"][:, 0][
+                ()
+            ]  # may provide fix of database here, if anyone asks
+        else:
+            x = cnters["x"][()]
+            y = cnters["y"][()]
+
+        C_norm, normalization_applied = self._rocking_normalization(aux, axis.size)
+        C_norm = np.broadcast_to(C_norm, np.shape(curves["croibg"])).copy()
+
+        # Only F2_hkl is divided by these, so asking for them with the
+        # Lorentz switch off would warn about a detector nothing needs.
+        detector_acceptance, acceptance_applied = None, False
+        solid_angle_mean, solid_angle_compensated = None, False
+        if self.lorentzButton.isChecked():
+            detector_acceptance, acceptance_applied = self._rocking_acceptance(
+                cnters, x, y
+            )
+            solid_angle_mean, solid_angle_compensated = (
+                self._rocking_solid_angle_mean(scangroup, cnters, x, y)
+            )
+
         self.database.nxfile[self._currentRoInfo["name"] + "/integration/"]
         roi_info = h5todict(
             self.database.nxfile, self._currentRoInfo["name"] + "/integration/"
@@ -1389,6 +1661,10 @@ def integrate(self):
             C_rod=C_rod,
             C_flux_on_sample=C_flux_on_sample,
             C_illum_area=C_illum_area,
+            C_norm=C_norm,
+            detector_acceptance=detector_acceptance,
+            solid_angle_mean=solid_angle_mean,
+            angle_unit="deg",
             progress_callback=progress.update,
             should_cancel=progress.wasCanceled,
         )
@@ -1448,21 +1724,6 @@ def integrate(self):
             i += 1
         availname1 = name1 + suffix
 
-        if cnters["x"].ndim > 1:
-            warnings.warn(
-                "You are using an old data base orGUI v1.3.0-alpha"
-                "X and Y pixel coordinates of rocking scans will be incorrect"
-            )
-            x = cnters["x"][:, 0][
-                ()
-            ]  # may provide fix of database here, if anyone asks
-            y = cnters["y"][:, 0][
-                ()
-            ]  # may provide fix of database here, if anyone asks
-        else:
-            x = cnters["x"][()]
-            y = cnters["y"][()]
-
         datas1 = {
             "@NX_class": "NXdata",
             "sixc_angles": {
@@ -1522,6 +1783,25 @@ def integrate(self):
             measurement[availname1]["counters"]["F2_hkl"] = F2_hkl
             measurement[availname1]["counters"]["F2_hkl_errors"] = F2_hkl_errors
             measurement[availname1]["@signal"] = "counters/F2_hkl"
+            # What the reduction actually divided out. A saved rod cannot be
+            # put on a common scale with another scan after the fact without
+            # this, and which factors were available depends on the scan.
+            reduction = {
+                "@NX_class": "NXcollection",
+                "@mode": mode,
+                "@angle_unit": "rad",
+                "@normalization_applied": ",".join(normalization_applied) or "none",
+                "@acceptance_applied": bool(acceptance_applied),
+                "@solid_angle_compensated": bool(solid_angle_compensated),
+                "@active_area_applied": bool(self.footprintButton.isChecked()),
+            }
+            if detector_acceptance is not None:
+                reduction["detector_acceptance"] = detector_acceptance
+                reduction["@detector_acceptance_unit"] = "rad"
+            if self.footprintButton.isChecked():
+                reduction["sample_size"] = L
+                reduction["@sample_size_unit"] = "m"
+            measurement[availname1]["reduction"] = reduction
 
         self.database.add_nxdict(
             measurement,
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index 36b8b37..a36b1e7 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -13,9 +13,15 @@
 saved rocking intensities and uncertainties from regression.
 """
 
+from types import SimpleNamespace
+
 import numpy as np
 
-from orgui.app.peak1Dintegr import _compute_rocking_integration, _trapz_impl
+from orgui.app.peak1Dintegr import (
+    RockingPeakIntegrator,
+    _compute_rocking_integration,
+    _trapz_impl,
+)
 
 
 def _piecewise_curve(axis, regions, background=0.0):
@@ -291,3 +297,209 @@ def test_integrated_error_is_finite_when_raw_signal_integral_is_zero():
     )
 
     assert np.all(np.isfinite(result["croibg_errors"])), result["croibg_errors"]
+
+
+def test_normalization_is_applied_inside_the_rocking_integral():
+    """A varying counting time must be divided out per frame.
+
+    Vlieg's rocking expression integrates ``N(omega)/(T M)`` over the rocking
+    angle, so the divisor belongs under the integral sign. Dividing the
+    finished integral by a mean counting time is only the same thing when the
+    counting time is constant, and a scan whose exposure drifts is exactly the
+    case the normalization exists for.
+
+    The curve is flat at ``10`` and the exposure ramps as ``T = 2 + omega``,
+    which makes both readings closed forms rather than a re-implementation of
+    the code:
+
+    * per frame, as required:
+      ``Int 10/(2+omega) domega = 10 ln(2.4/1.6)`` over ``[-0.4, 0.4]``
+    * divided afterwards by the mean exposure, which must not be what comes
+      out: ``10 * 0.8 / 2 = 4`` exactly, since the mean of ``T`` over a
+      symmetric interval is 2.
+
+    They differ by 1.4 %, so the wrong one cannot pass.
+    """
+    axis = np.linspace(-1.0, 1.0, 401)
+    curve = _piecewise_curve(axis, [(-0.5, 0.5, 10.0)])
+    exposure = 2.0 + axis
+
+    result = _compute_rocking_integration(
+        np.array([0.0]),
+        axis,
+        curve[None, :],
+        np.sqrt(curve)[None, :],
+        _roi_info(0.0, {"sig_1": (-0.4, 0.4)}),
+        {},
+        False,
+        False,
+        C_norm=exposure[None, :],
+        angle_unit="rad",
+    )
+
+    per_frame = 10.0 * np.log(2.4 / 1.6)
+    np.testing.assert_allclose(result["croibg"], per_frame, rtol=1e-5)
+    assert not np.isclose(per_frame, 4.0, rtol=1e-3)
+
+
+def test_the_rocking_integral_is_converted_to_radian_for_f2():
+    """``F2_hkl`` carries the radian integral; the stored intensity does not.
+
+    The published expressions integrate the rocking angle in radian, but the
+    motor axis is in degrees and ``croibg`` is kept in the unit it was
+    measured in, so the ``180/pi`` shows up as the ratio between them.
+    """
+    axis = np.linspace(-1.0, 1.0, 401)
+    curve = _piecewise_curve(axis, [(-0.5, 0.5, 10.0)])
+    ones = np.ones((1, axis.size))
+
+    result = _compute_rocking_integration(
+        np.array([0.0]),
+        axis,
+        curve[None, :],
+        np.sqrt(curve)[None, :],
+        _roi_info(0.0, {"sig_1": (-0.4, 0.4)}),
+        {},
+        True,
+        False,
+        C_Lor=ones,
+        C_rod=ones,
+        angle_unit="deg",
+    )
+
+    np.testing.assert_allclose(
+        result["F2_hkl"] / result["croibg"], np.deg2rad(1.0), rtol=1e-12
+    )
+
+
+def test_the_acceptance_divides_f2_and_only_f2():
+    """``Delta_gamma`` scales the structure factor, not the intensity.
+
+    The intensity column stays the measured integral; the acceptance is part
+    of forming ``F2_hkl``, because it is the rod slice the region intercepted
+    rather than anything about the counts.
+    """
+    axis = np.linspace(-1.0, 1.0, 401)
+    curve = _piecewise_curve(axis, [(-0.5, 0.5, 10.0)])
+    ones = np.ones((1, axis.size))
+    acceptance = np.array([np.deg2rad(0.4)])
+
+    common = dict(
+        C_Lor=ones,
+        C_rod=ones,
+        angle_unit="rad",
+    )
+    args = (
+        np.array([0.0]),
+        axis,
+        curve[None, :],
+        np.sqrt(curve)[None, :],
+        _roi_info(0.0, {"sig_1": (-0.4, 0.4)}),
+        {},
+        True,
+        False,
+    )
+    without = _compute_rocking_integration(*args, **common)
+    with_it = _compute_rocking_integration(
+        *args, detector_acceptance=acceptance, **common
+    )
+
+    np.testing.assert_allclose(with_it["croibg"], without["croibg"], rtol=1e-12)
+    np.testing.assert_allclose(
+        with_it["F2_hkl"] * acceptance, without["F2_hkl"], rtol=1e-12
+    )
+    np.testing.assert_allclose(
+        with_it["F2_hkl_errors"] * acceptance, without["F2_hkl_errors"], rtol=1e-12
+    )
+
+
+class _RowOnlyDetector:
+    """A detector whose exit angle depends only on pyFAI dimension 1.
+
+    ``surfaceAnglesPoint`` takes the *row* first, so a gamma built from its
+    first argument alone is a direct probe of whether the caller got the
+    coordinate order right.
+    """
+
+    PER_ROW = 1e-4
+
+    def surfaceAnglesPoint(self, x, y, alpha_i, gamma_arm=None, delta_arm=None):
+        gamma = self.PER_ROW * np.asarray(x, dtype=float)
+        return gamma, np.zeros_like(gamma)
+
+
+def _stub(detector=None, monitors=()):
+    """Minimal stand-in for the parts of the integrator the helpers touch."""
+    ubcalc = None if detector is None else SimpleNamespace(detectorCal=detector)
+    config_target = SimpleNamespace(
+        ubcalc=ubcalc, reconstruction_monitor_corrections=tuple(monitors)
+    )
+    return SimpleNamespace(database=SimpleNamespace(config_target=config_target))
+
+
+def test_the_acceptance_reads_the_row_from_y_and_the_column_from_x():
+    """orGUI's ``y`` is the detector row, and pyFAI takes the row first.
+
+    ``detvsize, dethsize = detector.shape`` at ``orGUI.py:1096`` fixes ``y``
+    as the row and ``vsize`` as its extent, and every ``surfaceAnglesPoint``
+    call in the application passes the two coordinates swapped. Getting this
+    backwards yields a plausible but wrong acceptance, so it is pinned here:
+    the result must follow ``vsize`` and ``y`` and ignore ``x``.
+    """
+    detector = _RowOnlyDetector()
+    vsize = np.array([10.0, 40.0, 80.0])
+    cnters = {
+        "vsize": vsize,
+        "alpha_pk": np.zeros(3),
+    }
+
+    acceptance, applied = RockingPeakIntegrator._rocking_acceptance(
+        _stub(detector), cnters, x=np.array([5.0, 300.0, 470.0]), y=np.full(3, 250.0)
+    )
+
+    assert applied is True
+    np.testing.assert_allclose(acceptance, vsize * detector.PER_ROW, rtol=1e-12)
+
+
+def test_a_missing_detector_leaves_the_acceptance_out_rather_than_failing():
+    """CLI use without a calibration must not lose the integration."""
+    cnters = {"vsize": np.array([40.0]), "alpha_pk": np.zeros(1)}
+
+    acceptance, applied = RockingPeakIntegrator._rocking_acceptance(
+        _stub(None), cnters, x=np.array([100.0]), y=np.array([200.0])
+    )
+
+    assert acceptance is None
+    assert applied is False
+
+
+def test_the_rocking_normalization_uses_the_stored_counters():
+    """Exposure and the configured monitors multiply into one divisor."""
+    aux = {
+        "exposure_time": np.array([2.0, 4.0]),
+        "mondio": np.array([10.0, 5.0]),
+        "unused": np.array([7.0, 7.0]),
+    }
+
+    divisor, applied = RockingPeakIntegrator._rocking_normalization(
+        _stub(monitors=("mondio",)), aux, 2
+    )
+
+    np.testing.assert_allclose(divisor, [20.0, 20.0], rtol=1e-12)
+    assert applied == ["exposure", "monitor:mondio"]
+
+
+def test_a_missing_exposure_counter_is_skipped_and_recorded():
+    """A backend that declares no exposure_time still integrates.
+
+    ``P212_tools`` and the base ``Scan`` return an empty
+    ``auxillary_counters``, so nothing was stored to normalize by. That is a
+    scale the user has to know about, not a reason to fail the job, and
+    ``applied`` is what records it.
+    """
+    divisor, applied = RockingPeakIntegrator._rocking_normalization(
+        _stub(monitors=("mondio",)), {}, 3
+    )
+
+    np.testing.assert_allclose(divisor, np.ones(3), rtol=1e-12)
+    assert applied == []
diff --git a/orgui/app/test/test_scan_mode_equivalence.py b/orgui/app/test/test_scan_mode_equivalence.py
index 54bb086..175c457 100644
--- a/orgui/app/test/test_scan_mode_equivalence.py
+++ b/orgui/app/test/test_scan_mode_equivalence.py
@@ -145,15 +145,39 @@ def _roi_info(size):
     }
 
 
-def _orgui_rocking_f2(rod, acceptance):
-    """``F2_hkl`` as :mod:`orgui.app.peak1Dintegr` computes it today."""
+def _orgui_rocking_f2(rod, acceptance, reduce=True, solid_angle_mean=None):
+    """``F2_hkl`` as :mod:`orgui.app.peak1Dintegr` computes it.
+
+    :param rod: The ``rod`` fixture.
+    :param acceptance: Out-of-plane acceptance per rod point, in radian. It
+        both shapes the simulated measurement and, when ``reduce`` is set, is
+        divided back out.
+    :param bool reduce: Pass the exposure/monitor divisor, the acceptance and
+        the radian conversion, as :meth:`RockingPeakIntegrator.integrate`
+        does. ``False`` reproduces the historical scale, which is what the
+        distortion test below needs to compare against.
+    """
     ell, alpha, delta, gamma, _, _, _ = rod
     axis, curves = _simulate_rocking(rod, acceptance)
+    if solid_angle_mean is not None:
+        # As the per-pixel correction does when the switch is on: it scales
+        # the counts, region by region.
+        curves = curves * np.asarray(solid_angle_mean)[:, None]
     shape = curves.shape
     lorentz = np.broadcast_to(
         (1.0 / (np.sin(delta) * np.cos(alpha) * np.cos(gamma)))[:, None], shape
     )
     rod_interception = np.broadcast_to(np.cos(gamma)[:, None], shape)
+    extra = {}
+    if reduce:
+        extra = dict(
+            C_norm=np.full(shape, ROCKING_EXPOSURE * ROCKING_MONITOR),
+            detector_acceptance=acceptance,
+            solid_angle_mean=solid_angle_mean,
+            angle_unit="deg",
+        )
+    else:
+        extra = dict(angle_unit="rad")  # no conversion: integrate as measured
     result = _compute_rocking_integration(
         ell,
         axis,
@@ -165,14 +189,23 @@ def _orgui_rocking_f2(rod, acceptance):
         False,
         C_Lor=lorentz,
         C_rod=rod_interception,
+        **extra,
     )
     return result["F2_hkl"]
 
 
-def _orgui_stationary_f2(rod):
-    """``F2_hkl`` as :mod:`orgui.app.integration_corrections` computes it."""
+def _orgui_stationary_f2(rod, solid_angle_mean=None):
+    """``F2_hkl`` as :mod:`orgui.app.integration_corrections` computes it.
+
+    :param solid_angle_mean: When given, the region-mean solid-angle
+        correction is applied to the counts, as the per-pixel array does when
+        the switch is on, and handed to the reduction so that it comes back
+        out of the structure factor.
+    """
     ell, alpha, delta, gamma, _, _, _ = rod
     counts = _simulate_stationary(rod)
+    if solid_angle_mean is not None:
+        counts = counts * np.asarray(solid_angle_mean)
     factors = ic.stationary_correction_factors(
         alpha,
         delta,
@@ -181,6 +214,7 @@ def _orgui_stationary_f2(rod):
         normalization=np.full(
             ell.size, STATIONARY_EXPOSURE * STATIONARY_MONITOR
         ),
+        solid_angle_mean=solid_angle_mean,
     )
     intensity, errors = ic.apply_stationary_corrections(
         counts, np.sqrt(counts), factors
@@ -260,46 +294,64 @@ def test_the_stationary_path_recovers_the_rod_up_to_one_constant(rod):
     np.testing.assert_allclose(ratio, ratio[0], rtol=1e-12)
 
 
-def test_rocking_and_stationary_paths_differ_by_the_missing_normalizations(rod):
-    """The gap between the two paths, pinned to the factor it is.
+def test_rocking_and_stationary_paths_agree(rod):
+    """The two integration paths of orGUI now land on one scale.
 
-    With the acceptance held constant the two paths differ by exactly
-    ``exposure * monitor * Delta_gamma_in_degrees``: the rocking path applies
-    neither the exposure/monitor normalization nor the out-of-plane
-    acceptance, and integrates the rocking angle in degrees rather than
-    radian. The degree-to-radian factor and the acceptance combine into the
-    acceptance expressed in degrees.
+    This is issue #82. The same rod, simulated as a rocking scan and as a
+    stationary scan with *different* counting times and monitors, goes through
+    the two real integration paths and comes out with the same ``F2_hkl``.
 
-    This test characterizes today's behavior. It must be updated -- to a
-    plain equality -- when the rocking path adopts the unified reduction.
+    This test used to characterize the gap between the paths, which was
+    exactly ``exposure * monitor * Delta_gamma_in_degrees`` -- the rocking
+    path applied neither the exposure/monitor normalization nor the
+    out-of-plane acceptance, and integrated the rocking angle in degrees.
+    Those three are the wiring this asserts is in place; the factor they used
+    to leave behind is kept below as the thing that must not come back.
     """
     ell = rod[0]
     acceptance = np.full(ell.size, np.deg2rad(0.35))
 
-    ratio = _orgui_rocking_f2(rod, acceptance) / _orgui_stationary_f2(rod)
-    expected = ROCKING_EXPOSURE * ROCKING_MONITOR * np.rad2deg(acceptance)
+    rocking = _orgui_rocking_f2(rod, acceptance)
+    stationary = _orgui_stationary_f2(rod)
+
+    np.testing.assert_allclose(rocking / stationary, 1.0, rtol=1e-6)
 
-    np.testing.assert_allclose(ratio, expected, rtol=1e-6)
+    # The historical scale, for contrast: without the reduction the rocking
+    # path overshoots by the acceptance expressed in degrees times the
+    # counting time and monitor it never divided out.
+    historical = _orgui_rocking_f2(rod, acceptance, reduce=False)
+    gap = ROCKING_EXPOSURE * ROCKING_MONITOR * np.rad2deg(acceptance)
+    np.testing.assert_allclose(historical / stationary, gap, rtol=1e-6)
 
 
-def test_a_resized_region_of_interest_distorts_the_rocking_rod(rod):
-    """The missing acceptance is not merely an overall scale factor.
+def test_a_resized_region_of_interest_no_longer_distorts_the_rocking_rod(rod):
+    """The acceptance divisor removes a *shape* error, not just a scale one.
 
     :func:`orgui.app.ROIutils.calc_corrections` sizes regions of interest
     from the projected sample size and the parallax at each detector
     position, so their out-of-plane acceptance changes along a scan. Without
     the ``1/Delta_gamma`` divisor that change is carried straight into
-    ``F2_hkl``, so the same rod measured with a resized region of interest
-    comes out with a different *shape*, not just a different scale.
+    ``F2_hkl`` and the same rod comes out with a different shape; with it the
+    rod is independent of how the regions were sized.
+
+    Both halves are asserted, because the second is what makes the first
+    worth having: a factor 2.3 of distortion across this rod, cured.
     """
     ell = rod[0]
     fixed = np.full(ell.size, np.deg2rad(0.35))
     resized = np.deg2rad(0.35) * np.linspace(0.7, 1.6, ell.size)
 
-    with_fixed = _orgui_rocking_f2(rod, fixed)
-    with_resized = _orgui_rocking_f2(rod, resized)
+    # With the reduction: the resized regions give the same rod.
+    np.testing.assert_allclose(
+        _orgui_rocking_f2(rod, resized) / _orgui_rocking_f2(rod, fixed),
+        1.0,
+        rtol=1e-6,
+    )
 
-    carried = with_resized / with_fixed
+    # Without it: the region sizing leaks into the rod shape.
+    carried = _orgui_rocking_f2(rod, resized, reduce=False) / _orgui_rocking_f2(
+        rod, fixed, reduce=False
+    )
     shape_change = carried / carried[0]
     np.testing.assert_allclose(
         shape_change, np.linspace(0.7, 1.6, ell.size) / 0.7, rtol=1e-6
@@ -326,3 +378,41 @@ def test_the_stationary_path_assumes_a_slit_independent_active_area(rod):
 
     spread = ratio.max() / ratio.min() - 1.0
     assert spread > 1e-3, "delta must vary enough along the rod to see this"
+
+
+def test_the_solid_angle_correction_does_not_reach_the_structure_factor(rod):
+    """Switching it on changes the intensity but not ``F2_hkl``, in both modes.
+
+    The detector solid-angle correction stays available because it is the
+    right thing for a broad, non-rod feature, where a differential cross
+    section is what is wanted. For a rod it is not: a region sum is already
+    the complete angular integral, each pixel weighted by the solid angle it
+    subtends. So the reduction divides it back out, and a structure factor is
+    the same number whether or not the switch was on.
+
+    The factor here varies along the rod, as a real one does -- the obliquity
+    grows as the reflection moves up the detector -- so a leftover would show
+    up as a shape error and not merely a scale.
+    """
+    ell = rod[0]
+    acceptance = np.full(ell.size, np.deg2rad(0.35))
+    solid_angle = 1.0 + 0.07 * np.linspace(0.0, 1.0, ell.size)
+
+    np.testing.assert_allclose(
+        _orgui_stationary_f2(rod, solid_angle_mean=solid_angle),
+        _orgui_stationary_f2(rod),
+        rtol=1e-12,
+    )
+    np.testing.assert_allclose(
+        _orgui_rocking_f2(rod, acceptance, solid_angle_mean=solid_angle),
+        _orgui_rocking_f2(rod, acceptance),
+        rtol=1e-12,
+    )
+
+    # And the modes still agree with the correction enabled.
+    np.testing.assert_allclose(
+        _orgui_rocking_f2(rod, acceptance, solid_angle_mean=solid_angle)
+        / _orgui_stationary_f2(rod, solid_angle_mean=solid_angle),
+        1.0,
+        rtol=1e-6,
+    )
diff --git a/orgui/datautils/xrayutils/corrections/detector.py b/orgui/datautils/xrayutils/corrections/detector.py
index 6d5d686..77f45f8 100644
--- a/orgui/datautils/xrayutils/corrections/detector.py
+++ b/orgui/datautils/xrayutils/corrections/detector.py
@@ -55,7 +55,7 @@
 
 import numpy as np
 
-__all__ = ["pixel_factors"]
+__all__ = ["pixel_factors", "roi_mean_inverse_solid_angle"]
 
 
 def pixel_factors(detector, solid_angle=False, polarization=False, shape=None):
@@ -87,3 +87,83 @@ def pixel_factors(detector, solid_angle=False, polarization=False, shape=None):
         )
         factor = 1.0 / values if factor is None else factor / values
     return factor
+
+
+def roi_mean_inverse_solid_angle(
+    detector, row, column, row_size, column_size, shape=None
+):
+    r"""Mean of :math:`1/\widetilde{\Omega}` over a rectangular region.
+
+    The solid-angle content of the per-pixel correction of
+    :func:`pixel_factors`, reduced onto one region of interest. A
+    region-summed intensity that has been divided by the solid angle needs
+    this factor divided back out before it becomes a structure factor: the
+    sum over a region is already the complete angular integral, each pixel
+    weighted by the solid angle it subtends, so the correction double-counts
+    the detector obliquity there. See
+    ``doc/design/ctr_structure_factor_scale.md`` finding F6.
+
+    Evaluated over the **nominal** region rectangle, from the calibrated
+    geometry alone, so it needs no image and can be computed per frame outside
+    an integration loop. That is deliberately not identical to the mean over
+    the *valid* pixels that the integration accumulates: the two differ only
+    where masked pixels correlate with the detector obliquity, and
+    :math:`\widetilde{\Omega}` varies by well under a percent across one
+    region.
+
+    .. note::
+
+        Because :func:`pixel_factors` returns the solid angle and the
+        polarization as one fused array, the applied region mean is
+        :math:`\langle 1/(\widetilde{\Omega}P)\rangle` rather than
+        :math:`\langle 1/\widetilde{\Omega}\rangle\,\langle 1/P\rangle`.
+        Dividing this factor out therefore leaves the covariance of the two
+        over the region, which is second order in their variation across it --
+        of order :math:`10^{-6}` for a region of a hundred pixels at a metre.
+
+    :param detector: A
+        :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`.
+    :param row: Region centre row, in pixels along pyFAI dimension 1. Scalar
+        or one value per frame.
+    :param column: Region centre column, in pixels along pyFAI dimension 2.
+    :param row_size: Region height in pixels.
+    :param column_size: Region width in pixels.
+    :param shape: Detector shape; taken from the detector when omitted.
+    :returns: The mean of the reciprocal normalized solid angle, broadcast
+        over the inputs. A region entirely off the detector contains no pixels
+        and no counts, and yields ``1.0`` so that it neither rescales nor
+        invalidates the zero intensity there.
+    :rtype: numpy.ndarray
+    :raises ValueError: If a region size is not positive.
+    """
+    solid_angle = np.asarray(
+        detector.solidAngleArray(shape) if shape is not None
+        else detector.solidAngleArray(),
+        dtype=np.float64,
+    )
+    row, column, row_size, column_size = np.broadcast_arrays(
+        np.asarray(row, dtype=np.float64),
+        np.asarray(column, dtype=np.float64),
+        np.asarray(row_size, dtype=np.float64),
+        np.asarray(column_size, dtype=np.float64),
+    )
+    for name, value in (("height", row_size), ("width", column_size)):
+        if np.any(value <= 0) or not np.all(np.isfinite(value)):
+            raise ValueError(
+                f"the region of interest must have a positive {name} in "
+                f"pixels; got {value!r}"
+            )
+
+    n_rows, n_columns = solid_angle.shape[0], solid_angle.shape[1]
+    out = np.ones(row.shape, dtype=np.float64)
+    for index in np.ndindex(*row.shape):
+        r0 = int(np.floor(row[index] - row_size[index] / 2.0))
+        r1 = int(np.ceil(row[index] + row_size[index] / 2.0))
+        c0 = int(np.floor(column[index] - column_size[index] / 2.0))
+        c1 = int(np.ceil(column[index] + column_size[index] / 2.0))
+        block = solid_angle[
+            max(r0, 0):min(r1, n_rows), max(c0, 0):min(c1, n_columns)
+        ]
+        if block.size:
+            out[index] = np.mean(1.0 / block)
+    return out
diff --git a/orgui/datautils/xrayutils/test/test_corrections_detector.py b/orgui/datautils/xrayutils/test/test_corrections_detector.py
new file mode 100644
index 0000000..d33a47d
--- /dev/null
+++ b/orgui/datautils/xrayutils/test/test_corrections_detector.py
@@ -0,0 +1,136 @@
+"""Regression tests for the per-pixel detector correction factors.
+
+:mod:`orgui.datautils.xrayutils.corrections.detector` owns the solid-angle and
+polarization arrays and the region reduction of the solid-angle part that a
+structure factor has to divide back out. See
+``doc/design/ctr_structure_factor_scale.md`` finding F6.
+"""
+
+import numpy as np
+import pytest
+
+pyFAI = pytest.importorskip("pyFAI")
+
+from orgui.datautils.xrayutils import DetectorCalibration  # noqa: E402
+from orgui.datautils.xrayutils.corrections import detector as detector_corrections  # noqa: E402
+
+#: Pixel size and distance of the calibrated test detector, in meter.
+PIXEL, DIST = 172e-6, 0.3
+SHAPE = (619, 487)
+
+
+def _calibrated_detector():
+    """A real, calibrated area detector, close in so obliquity is visible."""
+    det = DetectorCalibration.Detector2D_SXRD()
+    det.detector = pyFAI.detectors.Detector(
+        pixel1=PIXEL, pixel2=PIXEL, max_shape=SHAPE
+    )
+    det.poni1 = SHAPE[0] * PIXEL / 2.0
+    det.poni2 = SHAPE[1] * PIXEL / 2.0
+    det.rot1 = det.rot2 = det.rot3 = 0.0
+    det.dist = DIST
+    det.set_energy(17.7)
+    det.setAzimuthalReference(np.deg2rad(90.0))
+    det.setPolarization(0.0, 1.0)
+    det.reset()
+    det._cached_array = {}
+    return det
+
+
+def test_the_region_mean_is_one_at_normal_incidence():
+    """At the point of normal incidence the correction is nearly neutral.
+
+    ``solidAngleArray`` is normalized to that point, so a region centred
+    there cannot introduce a scale of its own beyond its own curvature: the
+    off-centre pixels of a 20-pixel region at 0.3 m still reach
+    :math:`\\theta = 0.33^\\circ`, worth :math:`4\\times10^{-5}`. That
+    residual is the factor being real rather than an artefact, so it is
+    bounded here rather than asserted away.
+    """
+    det = _calibrated_detector()
+
+    got = detector_corrections.roi_mean_inverse_solid_angle(
+        det, SHAPE[0] / 2.0, SHAPE[1] / 2.0, 20.0, 20.0
+    )
+
+    np.testing.assert_allclose(got, 1.0, rtol=1e-4)
+    assert got > 1.0, "the mean of 1/cos^3 over a region is never below one"
+
+
+def test_the_region_mean_follows_the_obliquity():
+    """It is the mean of ``1/cos^3(theta)`` over the region's pixels.
+
+    Written out from the geometry rather than by calling the module back: the
+    normalized solid angle of a flat detector is ``cos^3`` of the incidence
+    angle on its face, which is what makes this factor grow away from the
+    beam centre.
+    """
+    det = _calibrated_detector()
+    row, column, rows, columns = 560.0, 240.0, 60.0, 40.0
+
+    got = detector_corrections.roi_mean_inverse_solid_angle(
+        det, row, column, rows, columns
+    )
+
+    r = np.arange(row - rows / 2, row + rows / 2)
+    c = np.arange(column - columns / 2, column + columns / 2)
+    dr = (r[:, None] + 0.5) * PIXEL - det.poni1
+    dc = (c[None, :] + 0.5) * PIXEL - det.poni2
+    theta = np.arctan(np.hypot(dr, dc) / DIST)
+    expected = np.mean(1.0 / np.cos(theta) ** 3)
+
+    np.testing.assert_allclose(got, expected, rtol=1e-6)
+    assert got > 1.02, "the test region must be oblique enough to matter"
+
+
+def test_the_region_mean_is_vectorized_over_a_scan():
+    """orGUI resizes regions along a scan, so this is normally an array."""
+    det = _calibrated_detector()
+    row = np.array([310.0, 450.0, 560.0])
+    size = np.array([20.0, 40.0, 60.0])
+
+    got = detector_corrections.roi_mean_inverse_solid_angle(
+        det, row, 240.0, size, size
+    )
+
+    assert got.shape == (3,)
+    # Monotonic away from the beam centre, which is what makes it a shape
+    # error rather than a scale error when it is left in.
+    assert got[0] < got[1] < got[2]
+
+
+def test_a_region_off_the_detector_is_neutral():
+    """No pixels means no counts; the factor must not scale or poison them."""
+    det = _calibrated_detector()
+
+    got = detector_corrections.roi_mean_inverse_solid_angle(
+        det, -500.0, -500.0, 20.0, 20.0
+    )
+
+    np.testing.assert_allclose(got, 1.0, rtol=0.0)
+
+
+def test_a_region_partly_off_the_detector_uses_the_pixels_it_has():
+    """Clipped at the detector edge rather than padded or rejected."""
+    det = _calibrated_detector()
+
+    edge = detector_corrections.roi_mean_inverse_solid_angle(
+        det, 5.0, 240.0, 40.0, 40.0
+    )
+
+    assert np.isfinite(edge)
+    assert edge > 1.0
+
+
+def test_a_zero_or_negative_region_is_rejected():
+    """An empty region would divide a structure factor by a meaningless mean."""
+    det = _calibrated_detector()
+
+    with pytest.raises(ValueError, match="positive height"):
+        detector_corrections.roi_mean_inverse_solid_angle(
+            det, 300.0, 240.0, 0.0, 20.0
+        )
+    with pytest.raises(ValueError, match="positive width"):
+        detector_corrections.roi_mean_inverse_solid_angle(
+            det, 300.0, 240.0, 20.0, -5.0
+        )

From 46cab907d4e593603230c98823416ef81747a4bf Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Thu, 10 Sep 2026 14:17:21 -0400
Subject: [PATCH 07/33] fix(phys)!: follow the detector arm in the polarization
 correction

BREAKING CHANGE: intensities and F2_hkl change for scans that drive the
detector arm, and only those. The per-pixel polarization array is built at the
calibrated arm position, which understated the correction by 3 % at a
scattering angle of 10 degrees, 10 % at 18 and 33 % at 30; both integration
paths now apply a per-frame factor that moves it onto the arm position each
frame was measured at. A fixed-arm scan is bit-identical. The reciprocal-space
reconstruction applies the polarization per pixel and is unchanged.
---
 CHANGELOG.md                                  |  23 +++
 doc/design/ctr_structure_factor_handover.md   |  38 +++--
 doc/design/ctr_structure_factor_scale.md      |  48 +++++-
 doc/physics/ctr_structure_factor_physics.tex  |  47 ++++--
 doc/source/image_integration.rst              |  11 ++
 doc/source/release_notes.rst                  |   2 +
 orgui/app/orGUI.py                            | 112 +++++++++++++
 orgui/app/test/test_orGUI_reflections.py      |  58 +++++++
 .../xrayutils/corrections/detector.py         | 153 +++++++++++++++++-
 .../test/test_corrections_detector.py         |  90 ++++++++++-
 10 files changed, 542 insertions(+), 40 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4d560da..901d048 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,29 @@ This is the changelog for the software orGUI, written by Timo Fuchs
 
 Scientific and analysis additions:
 
+- **The polarization correction now follows the detector arm.**
+  *This changes saved numbers for scans that move the detector arm, and only
+  those.* The per-pixel polarization array is built from the calibrated
+  geometry, which is right only while the arm stays there. On a scan that
+  drives the arm -- a reflectivity curve, where it follows twice the incidence
+  angle -- the same pixel looks in a different direction on every frame, and
+  the calibrated-position value understated the correction by 3 % at a
+  scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration
+  paths now apply a per-frame factor,
+  ``corrections.detector.polarization_arm_correction``, that moves the
+  correction onto the arm position each frame was measured at. It is exactly
+  one while the arm sits at its calibrated position, so a fixed-arm scan is
+  bit-identical and needs no switch. The factor is a ratio of two region
+  means rather than a rebuilt per-pixel array, which keeps the cost to a
+  region-sized evaluation per frame; the polarization is not flat across a
+  region at a large scattering angle, so the means matter. The detector solid
+  angle needs no such correction: an arm rotation is a rigid rotation about
+  the sample, so every pixel keeps its distance and its obliquity to its own
+  line of sight, and the solid angle is invariant under it exactly. The
+  reciprocal-space reconstruction applies the polarization per pixel rather
+  than as a region mean and is unchanged; correcting it there would need the
+  array rebuilt per frame.
+
 - **Rocking and stationary integration now produce the same structure factor.**
   *This changes saved numbers in both modes.* A rocking scan and a stationary
   scan of the same rod previously differed by exactly exposure time times
diff --git a/doc/design/ctr_structure_factor_handover.md b/doc/design/ctr_structure_factor_handover.md
index f60df74..78da839 100644
--- a/doc/design/ctr_structure_factor_handover.md
+++ b/doc/design/ctr_structure_factor_handover.md
@@ -1,7 +1,7 @@
 # CTR structure-factor scale: implementation status and handover
 
 > **Status as of 2026-09-10.** Branch `claude/ctr-structure-factor-9633bc`,
-> six commits ahead of `master`, nothing pushed.
+> seven commits ahead of `master`, nothing pushed.
 >
 > The physics analysis is complete and quantified, and the reduction is now
 > **wired in**: a rocking scan and a stationary scan of the same rod come out
@@ -32,6 +32,11 @@ four are now handled, and the two modes agree to `1e-6` on simulated data —
 the residual is the trapezoidal sampling of the rocking profile, not a
 correction factor.
 
+F5, the arm-blind polarization, is fixed too, in its own commit. It is
+independent of mode equivalence — it cancels between the modes at the same
+reflection — but it is up to a 33 % error on a scan that drives the detector
+arm, which is exactly the reflectivity case.
+
 ## 2. What is on the branch
 
 | commit | what it did |
@@ -40,6 +45,9 @@ correction factor.
 | `4193c80` | `feat: reduce integrated intensities to \|F_hkl\|^2 on one scale` |
 | `e25b8df` | `docs: record the rocking/stationary structure-factor scale analysis` |
 | `6959191` | `feat: estimate the out-of-plane detector acceptance` |
+| `ecb3bb5` | `docs: settle F6 and add the structure-factor physics reference` |
+| `0af9cb7` | `feat(phys)!: put rocking and stationary integration on one structure-factor scale` |
+| *(this one)* | `fix(phys)!: follow the detector arm in the polarization correction` |
 
 The first three were split out of one working tree at the end, which required
 *staged versions* of four files: `peak1Dintegr.py`, `integration_corrections.py`,
@@ -56,7 +64,8 @@ orgui/datautils/xrayutils/corrections/
   beamprofile.py   1049   beam profile shapes and their integrals
   activearea.py     190   active area in m^2, slit- and beam-limited
   acceptance.py     255   Delta_gamma, gamma_range, pixel_acceptance
-  detector.py        89   per-pixel solid angle and polarization
+  detector.py       319   per-pixel solid angle and polarization, their
+                          region means, and the polarization arm correction
   normalization.py  103   counting time and monitor, from values
   roi.py             93   CorrectionFactors, roi_mean_correction
   measurement.py    605   mode dispatch, master equation, reflectivity
@@ -71,10 +80,10 @@ not merely that they import.
 
 | caller | uses the package for | still does its own thing |
 |---|---|---|
-| `orGUI.integrateROI` (stationary) | `pixel_factors`, `mode_components`, `normalization_divisor`, `C_illum_area`, `roi_mean_inverse_solid_angle` | — |
-| `orGUI.rocking_integrate` | `pixel_factors` | — |
+| `orGUI.integrateROI` (stationary) | `pixel_factors`, `mode_components`, `normalization_divisor`, `C_illum_area`, `roi_mean_inverse_solid_angle`, `polarization_arm_correction` | — |
+| `orGUI.rocking_integrate` | `pixel_factors`, `polarization_arm_correction` | — |
 | `peak1Dintegr.integrate` (rocking) | `mode_components`, `normalization_divisor`, `normalized_intensity`, `out_of_plane_acceptance`, `roi_mean_inverse_solid_angle` | — |
-| `reconstruction_job` | `pixel_factors` (solid angle applied, **not** compensated) | own native-fused application, own normalization loop |
+| `reconstruction_job` | `pixel_factors` (solid angle applied and **not** compensated; polarization **not** arm-corrected) | own native-fused application, own normalization loop |
 
 Still uncalled outside the tests: `measurement.structure_factor_squared`,
 `measurement.angular_factor` and `activearea.*`. That is deliberate rather
@@ -233,10 +242,12 @@ be left behind cannot come back unnoticed.
   sample size and the beam profile. Everything else — `lambda`, `A_u`, `r_e` —
   is available.
 * **Reflectivity comes for free** once `|F|^2` is absolute;
-  `measurement.reflectivity_from_structure_factor` is the conversion. But fix
-  **F5** first: a reflectivity scan drives the detector arm, and the
-  polarization is still evaluated at the calibrated position, which is a 10 %
-  error at `2theta = 18` degrees and 33 % at 30.
+  `measurement.reflectivity_from_structure_factor` is the conversion. **F5 is
+  now fixed**, which mattered most here: a reflectivity scan drives the arm,
+  and the arm-blind polarization was a 10 % error at `2theta = 18` degrees and
+  33 % at 30. The correction applies to the two direct-space integration
+  paths; the reciprocal-space reconstruction still evaluates the polarization
+  per pixel at the calibrated position.
 * **`C_det` (F7)** is the only mechanism that can still break mode equivalence
   after the wiring, and it cannot be validated on simulated data. It needs the
   real-data overlap comparison.
@@ -277,8 +288,13 @@ Recorded because each cost time and none was obvious in advance.
   variance propagation. It shares the *definition* (`pixel_factors`) but keeps
   its own streaming application; that was the right boundary.
 * **F5 was not fixed while moving the code.** `pixel_factors` reproduces the
-  historical arm-blind behaviour exactly. Changing it is a numerical fix that
-  belongs in its own `phys` commit, not smuggled into a refactor.
+  historical arm-blind behaviour exactly. Changing it was a numerical fix that
+  belonged in its own `phys` commit, not smuggled into a refactor -- and it
+  landed as one. Note what it did *not* need: rebuilding the per-pixel array
+  per frame. Because the integration paths reduce the polarization to a region
+  mean anyway, the fix is a per-frame ratio of two region means, which is
+  exactly 1 at the calibrated arm position and so leaves every fixed-arm scan
+  bit-identical. `pixel_factors` itself is unchanged.
 * **`meson.build` was not changed.** Its `exclude_directories: ['__pycache__']`
   only excludes the top-level directory, so 72 stale `cpython-312.pyc` files
   are sitting in the installed copy. Inert under 3.14, and the repository owner
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
index 8ef1a18..2a0b4ee 100644
--- a/doc/design/ctr_structure_factor_scale.md
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -14,10 +14,10 @@
 > for absolute reflectivity. Everything below was verified numerically against
 > the code, not by inspection alone.
 >
-> F1, F2, F3 and F6 are now **applied**, which changed saved numbers in both
-> modes; the two paths agree to `1e-6` on simulated data, limited by the
-> trapezoidal sampling of the rocking profile. F4, F5 and F7 remain open and
-> are described below as they stand. Findings are written in the present tense
+> F1, F2, F3, F5 and F6 are now **applied**, which changed saved numbers in
+> both modes; the two paths agree to `1e-6` on simulated data, limited by the
+> trapezoidal sampling of the rocking profile. F4 and F7 remain open and are
+> described below as they stand. Findings are written in the present tense
 > of the analysis; section 5 says what each one's status is now, and
 > [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
 > section 5 says how each was wired.
@@ -207,6 +207,36 @@ its own scattering angle, and the apparent `alpha` dependence of the ANA
 z-axis expression is only a change of frame. The bug is scoped to scans that
 move the arm, which is exactly the reflectivity case of section 6.
 
+**Fixed**, as a per-frame multiplicative factor rather than by rebuilding the
+array. `detector.polarization_arm_correction` returns
+`<1/P_arm> / <1/P_home>` over the region of interest, which is what an
+intensity already corrected at the calibrated position has to be multiplied
+by, and both integration paths apply it. Three properties made this the
+proportionate fix rather than a per-frame rebuild of the full array:
+
+* It is **exactly 1** when the arm sits at its calibrated reference, because
+  both evaluations then use the same geometry. A fixed-arm scan is therefore
+  bit-identical, and no switch or special case is needed to keep it that way.
+* It costs a region-sized evaluation per frame instead of a detector-sized
+  one, capped at a 17x17 sample of the region because the polarization is
+  smooth across it. A constant arm is evaluated once and broadcast.
+* It leaves the fused per-pixel array, the native ROI accumulation and the
+  stored `Cfactors_croi` untouched.
+
+Re-measured through the shipped factor, along a specular scan whose arm
+follows `gamma = 2 alpha`, it reproduces the table above: `+0.03 %` at
+`2theta = 1`, `+0.49 %` at 4, `+3.11 %` at 10, `+10.57 %` at 18 and
+`+33.35 %` at 30 degrees.
+
+Two things it does **not** cover. The polarization and the solid angle are
+fused into one array by `pixel_factors`, so the ratio of region means leaves
+their covariance over the region - second order in the variation of both
+across it. And the **reciprocal-space reconstruction** applies the
+polarization per pixel rather than as a region mean, so this factor does not
+apply to it; that path would need the array itself rebuilt per frame, which is
+a detector-sized evaluation per frame and belongs with the rest of the
+reconstruction work in section 7.
+
 ### F6 - solid-angle correction applied to an already-summed ROI
 
 For a ROI-summed intensity, the raw sum over pixels *is* the angular integral
@@ -492,7 +522,7 @@ along a scan in the first place.
 each is in [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
 section 5, and the equivalence is asserted by
 `test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_agree`.
-Step 6, the real-data check, is the one that remains, together with F4, F5 and
+Step 6, the real-data check, is the one that remains, together with F4 and
 F7.
 
 Recorded in the order they had to be done, because the ordering was itself a
@@ -585,9 +615,11 @@ Three caveats, all now in the module docstrings:
    the critical angle, where refraction and multiple scattering take over -
    which is where the interesting part of a reflectivity curve usually is.
    Compare against the DWBA machinery already in `CTRdwba.py` there.
-2. **A reflectivity scan moves the detector arm**, so F5 bites hardest here:
-   10 % at `2theta = 18` degrees, 33 % at 30 degrees. Fix F5 before trusting an
-   absolute reflectivity.
+2. **A reflectivity scan moves the detector arm**, which is where F5 bit
+   hardest: 10 % at `2theta = 18` degrees, 33 % at 30. That is now corrected
+   for the two direct-space integration paths, but *not* for the
+   reciprocal-space reconstruction, which applies the polarization per pixel
+   (see F5).
 3. **Off-specular**, `R` is the fraction of the incident flux scattered into
    that rod. That is well defined for a truncation rod integrated across its
    cross-section, but not for diffuse scattering, where only a differential
diff --git a/doc/physics/ctr_structure_factor_physics.tex b/doc/physics/ctr_structure_factor_physics.tex
index d615f22..04557ed 100644
--- a/doc/physics/ctr_structure_factor_physics.tex
+++ b/doc/physics/ctr_structure_factor_physics.tex
@@ -170,10 +170,10 @@ \subsection{From a pixel to its scattering angles}
 \item $\dgam$ (Section~\ref{sec:acceptance}) is a \emph{difference} of
   Eq.~\eqref{eq:gamma} between two pixel rows, which is only meaningful
   because $\gamma$ varies across the detector face within one frame.
-\item The polarization factor (Section~\ref{sec:notmodelled}) is the one
-  correction still evaluated on the \emph{home} geometry rather than at the
-  frame's arm position, which is why it is wrong for a scan that drives the
-  arm.
+\item The polarization factor (Section~\ref{sec:notmodelled}) is built on the
+  \emph{home} geometry rather than at the frame's arm position, which is why
+  it needs a per-frame correction for a scan that drives the arm --- and why
+  the reconstruction, which cannot use that correction, is still wrong there.
 \end{itemize}
 
 \subsection{Units at the boundaries}
@@ -650,7 +650,9 @@ \section{Reflectivity}
   --- which is where much of the interesting part of a reflectivity curve
   lies. Compare against a DWBA treatment there.
 \item A reflectivity scan \textbf{drives the detector arm}, which is where the
-  polarization issue of Section~\ref{sec:notmodelled} bites hardest.
+  polarization issue of Section~\ref{sec:notmodelled} bit hardest. The two
+  direct-space integration paths correct for it; a reflectivity reduced from a
+  reconstructed map does not.
 \item \textbf{Off-specular}, $R$ is well defined for a truncation rod
   integrated across its cross-section, but not for diffuse scattering, where
   only a differential cross-section is meaningful.
@@ -676,18 +678,28 @@ \section{What is deliberately not modelled}
   than a normalization one. It cannot be validated on simulated data --- it
   needs the overlap region of a rocking and a stationary scan on the same rod.
 
-\item[The polarization at a moving detector arm.] The per-pixel polarization
-  array is built once, outside the frame loop, from the \emph{home} geometry
-  --- step 1 of Section~\ref{sec:pixelangles} is skipped, so it is the array
-  at the calibrated arm position rather than at the frame's. For a fixed arm
-  that is correct: each pixel already carries its own scattering angle, and
-  the apparent $\alpha$ dependence of the z-axis expression is only a change
-  of frame. For a scan that drives the arm it understates the correction:
-  $3\,\%$ at a scattering angle of $10^{\circ}$, $10\,\%$ at $18^{\circ}$ and
-  $33\,\%$ at $30^{\circ}$. A per-pixel evaluation that follows the arm
-  exists and is what such a scan needs. This is the opposite of the acceptance
-  (Section~\ref{sec:acceptance}), whose \emph{span} survives a moving arm
-  unchanged.
+\item[The polarization at a moving detector arm, in the reconstruction.] The
+  per-pixel polarization array is built once, outside the frame loop, from the
+  \emph{home} geometry --- step 1 of Section~\ref{sec:pixelangles} is skipped,
+  so it is the array at the calibrated arm position rather than at the
+  frame's. For a fixed arm that is correct: each pixel already carries its own
+  scattering angle, and the apparent $\alpha$ dependence of the z-axis
+  expression is only a change of frame. For a scan that drives the arm it
+  understates the correction: $3\,\%$ at a scattering angle of $10^{\circ}$,
+  $10\,\%$ at $18^{\circ}$ and $33\,\%$ at $30^{\circ}$. This is the opposite
+  of the acceptance (Section~\ref{sec:acceptance}), whose \emph{span} survives
+  a moving arm unchanged, and of the solid angle, which is invariant under it
+  exactly --- an arm rotation is a rigid rotation about the sample, so every
+  pixel keeps its distance and its obliquity to its own line of sight.
+
+  The two direct-space integration paths \textbf{correct} for this: they
+  reduce the polarization to a region mean anyway, so a per-frame ratio of two
+  region means, $\langle 1/P_{\mathrm{arm}}\rangle /
+  \langle 1/P_{\mathrm{home}}\rangle$, moves it onto the frame's arm position.
+  That ratio is exactly $1$ at the calibrated position, so a fixed-arm scan is
+  untouched. What remains uncorrected is the \textbf{reciprocal-space
+  reconstruction}, which applies the polarization per pixel rather than as a
+  region mean and would need the array itself rebuilt per frame.
 
 \item[Uncertainty of $\dgam$.] Errors follow the same divisors as the
   intensities, but a $\dgam$ estimated from the calibrated geometry has an
@@ -714,6 +726,7 @@ \section{Summary}
 Lorentz                     & $L_\varphi$ / $L_s$ & \code{geometry} & yes & yes \\
 Rod interception            & $\Crod$      & \code{geometry}      & yes & \textbf{no} \\
 Polarization                & $P$          & \code{detector}      & yes & yes \\
+\quad arm correction        & --           & \code{detector}      & yes & yes \\
 Solid angle                 & $\dOm$       & \code{detector}      & \textbf{no} & \textbf{no} \\
 Active area / footprint     & $A$          & \code{activearea}    & yes & yes \\
 Area correction             & $\Carea$     & \code{geometry}      & slits only & slits only \\
diff --git a/doc/source/image_integration.rst b/doc/source/image_integration.rst
index 737a033..b86a723 100644
--- a/doc/source/image_integration.rst
+++ b/doc/source/image_integration.rst
@@ -93,6 +93,17 @@ integration. The current implementation records the applied ROI sizes,
 reciprocal-space coordinates, detector coordinates, and relevant scan metadata
 with the integrated intensities.
 
+The **polarization correction follows the detector arm**. Its per-pixel array
+is built from the calibrated geometry, which is correct only while the arm
+stays there; on a scan that drives the arm the same pixel looks in a different
+direction on every frame, and the calibrated-position value understates the
+correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at
+30. Both integration paths therefore apply a per-frame factor that moves the
+correction onto the arm position each frame was measured at. It is exactly one
+while the arm is at its calibrated position, so a fixed-arm scan is unchanged.
+The reciprocal-space reconstruction applies the polarization per pixel and
+does not carry this correction.
+
 The Corrections Dialog
 ~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 6d85d19..27cd90c 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -9,6 +9,8 @@ Unreleased (2026-07-19)
 
 Scientific and analysis additions:
 
+- **The polarization correction now follows the detector arm.** *This changes saved numbers for scans that move the detector arm, and only those.* The per-pixel polarization array is built from the calibrated geometry, which is right only while the arm stays there. On a scan that drives the arm -- a reflectivity curve, where it follows twice the incidence angle -- the same pixel looks in a different direction on every frame, and the calibrated-position value understated the correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration paths now apply a per-frame factor, ``corrections.detector.polarization_arm_correction``, that moves the correction onto the arm position each frame was measured at. It is exactly one while the arm sits at its calibrated position, so a fixed-arm scan is bit-identical and needs no switch. The factor is a ratio of two region means rather than a rebuilt per-pixel array, which keeps the cost to a region-sized evaluation per frame; the polarization is not flat across a region at a large scattering angle, so the means matter. The detector solid angle needs no such correction: an arm rotation is a rigid rotation about the sample, so every pixel keeps its distance and its obliquity to its own line of sight, and the solid angle is invariant under it exactly. The reciprocal-space reconstruction applies the polarization per pixel rather than as a region mean and is unchanged; correcting it there would need the array rebuilt per frame.
+
 - **Rocking and stationary integration now produce the same structure factor.** *This changes saved numbers in both modes.* A rocking scan and a stationary scan of the same rod previously differed by exactly exposure time times monitor times the out-of-plane acceptance in degrees; they now agree. Four corrections changed. The rocking path gained the per-frame exposure and monitor normalization, applied inside the rocking integral so that a varying counting time or a drifting monitor is handled correctly rather than only on average; it now integrates the rocking angle in radian as the published expressions require, rather than in degrees; and it divides by the out-of-plane acceptance of its region of interest, without which a rod measured with regions resized along the scan came out with a distorted *shape* -- a factor 2.3 across a simulated Pt(111) rod -- and not merely a wrong scale. Separately, the detector **solid-angle correction no longer reaches a structure factor** in either mode: summing a region of interest already yields the complete angular integral, with every pixel weighted by the solid angle it subtends, so dividing by that solid angle again double-counted the detector obliquity (0.7 % for a detector at 1 m, 7 % at 0.3 m, varying across the detector and therefore a rod shape error). The switch stays, because that correction is the right one for a broad or diffuse feature where a differential cross section is wanted: it still scales the intensity counters, and is now measured over the same regions of interest and divided back out when ``F2_hkl`` is formed, so a structure factor is the same number whether or not it was enabled. Its tooltip and the ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps applying it uncompensated, since that path does form a differential cross section per pixel. For rocking scans the correction is applied when the curves are extracted, so whether to remove it again is read from the configuration stored with the scan; an older database where that cannot be established warns and is left uncompensated. Integrated rocking scans now store a ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit, which normalizations were applied, the acceptance used, whether the solid-angle correction was compensated, and the active-area assumption, so that a saved rod can be placed on a common scale afterwards. Rocking normalization uses the counters stored with the scan, so it requires a backend that declares ``exposure_time`` in ``auxillary_counters``; a missing counter is skipped and recorded rather than failing the integration. Existing configuration files load unchanged.
 
 - **All correction factors collected into one package.** Every factor between detector counts and a structure factor now lives in ``orgui.datautils.xrayutils.corrections``, split by what it depends on: ``geometry`` (the z-axis Lorentz, rod-interception and area table), ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and polarization), ``normalization`` (counting time and monitor), ``roi``, and ``measurement``. The rocking integration, the stationary integration and the reciprocal-space reconstruction previously each carried their own copy of several of these; they now share one definition, so they cannot drift onto different scales. The package is physics only -- numbers in, numbers out -- and reads no scan object, configuration or widget; ``orgui.app`` ``integration_corrections`` is the adapter that supplies those. ``orgui.datautils.xrayutils.geometrycorrections`` and ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the moved modules. **No calculated value changes.**
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index f454a37..f638ddf 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -2123,6 +2123,24 @@ def sumImage(i):
                     croibg1_bgimg_a *= Corr1
                     croibg1_bgimg_err_a *= Corr1
 
+            if self.scanSelector.usePolarizationBox.isChecked():
+                # Corr1 carries the polarization of the calibrated geometry;
+                # move it onto the arm position of each frame (finding F5).
+                # Exactly 1 for a detector whose arm does not move.
+                pol_arm1 = self._polarizationArmFactor(
+                    dc,
+                    xylist[d][1],
+                    xylist[d][0],
+                    roi_d[1].stop - roi_d[1].start,
+                    roi_d[0].stop - roi_d[0].start,
+                    mu,
+                )
+                croibg1_a = croibg1_a * pol_arm1
+                croibg1_err_a = croibg1_err_a * pol_arm1
+                if croibg1_bgimg_a is not None:
+                    croibg1_bgimg_a = croibg1_bgimg_a * pol_arm1
+                    croibg1_bgimg_err_a = croibg1_bgimg_err_a * pol_arm1
+
             rod_mask1 = np.isfinite(croibg1_a)
 
             axis_masked = hkl_del_gam_1[:, 5][rod_mask1]
@@ -3464,6 +3482,76 @@ def _qInSelectedFrame(self, pos):
         except Exception:
             return np.full(3, np.nan)
 
+    def _polarizationArmFactor(self, dc, row, column, row_size, column_size, alpha):
+        """Per-frame factor moving the polarization onto the real arm position.
+
+        The per-pixel polarization array is built once, from the calibrated
+        geometry. That is correct for a detector whose arm does not move, but
+        on a scan that drives the arm the same pixel looks in a different
+        direction on every frame and the correction comes out far too small --
+        10 % at a scattering angle of 18 degrees, 33 % at 30. This returns
+        what the already-corrected intensity has to be multiplied by; see
+        ``doc/design/ctr_structure_factor_scale.md`` finding F5.
+
+        The factor is exactly ``1.0`` wherever the arm sits at its calibrated
+        reference, because both evaluations then use the same geometry, so a
+        fixed-arm scan is untouched without needing to be special-cased. A
+        constant arm is evaluated once and broadcast, which keeps the cost off
+        the common path.
+
+        The arm position comes from :meth:`getArmAngles`, so this shares its
+        convention with every other arm consumer in the application: a scan
+        that knows nothing about an arm reports zero, which is the calibrated
+        reference for the default calibration and therefore leaves the
+        correction at one.
+
+        :param dc: The calibrated
+            :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`.
+        :param row: Region centre row per frame, in pixels (orGUI's ``y``).
+        :param column: Region centre column per frame, in pixels (``x``).
+        :param row_size: Region height per frame, in pixels.
+        :param column_size: Region width per frame, in pixels.
+        :param alpha: Incidence angle per frame, in radian.
+        :returns: The factor per frame.
+        :rtype: numpy.ndarray
+        """
+        gamma_arm, delta_arm = self.getArmAngles()
+        row, column, row_size, column_size, alpha, gamma_arm, delta_arm = (
+            np.broadcast_arrays(
+                np.asarray(row, dtype=np.float64),
+                np.asarray(column, dtype=np.float64),
+                np.maximum(np.asarray(row_size, dtype=np.float64), 1.0),
+                np.maximum(np.asarray(column_size, dtype=np.float64), 1.0),
+                np.asarray(alpha, dtype=np.float64),
+                np.asarray(gamma_arm, dtype=np.float64),
+                np.asarray(delta_arm, dtype=np.float64),
+            )
+        )
+
+        def _at(index):
+            return detector_corrections.polarization_arm_correction(
+                dc,
+                row[index],
+                column[index],
+                row_size[index],
+                column_size[index],
+                alpha[index],
+                float(gamma_arm[index]),
+                float(delta_arm[index]),
+            )
+
+        constant = all(
+            np.all(values == values.flat[0]) if values.size else True
+            for values in (row, column, row_size, column_size, alpha,
+                           gamma_arm, delta_arm)
+        )
+        if constant and row.size:
+            return np.full(row.shape, _at(np.unravel_index(0, row.shape)))
+        factor = np.ones(row.shape, dtype=np.float64)
+        for index in np.ndindex(*row.shape):
+            factor[index] = _at(index)
+        return factor
+
     def getArmAngles(self, imageno=None):
         """Return the detector arm position for an image or the whole scan.
 
@@ -6383,6 +6471,30 @@ def sumImage(i):
                 )
             )
 
+        if options["polarization"]:
+            # Corr1/Corr2 carry the polarization of the calibrated geometry;
+            # move it onto the arm position of each frame (finding F5). This is
+            # exactly 1 for a detector whose arm does not move, and it is the
+            # reflectivity case -- where the arm follows 2*alpha -- that needs
+            # it most.
+            pol_arm1 = self._polarizationArmFactor(
+                dc, y_coord1_a, x_coord1_a, roi_vsize1_a, roi_hsize1_a, alpha_all
+            )
+            croibg1_a = croibg1_a * pol_arm1
+            croibg1_err_a = croibg1_err_a * pol_arm1
+            if croibg1_bgimg_a is not None:
+                croibg1_bgimg_a = croibg1_bgimg_a * pol_arm1
+                croibg1_bgimg_err_a = croibg1_bgimg_err_a * pol_arm1
+
+            pol_arm2 = self._polarizationArmFactor(
+                dc, y_coord2_a, x_coord2_a, roi_vsize2_a, roi_hsize2_a, alpha_all
+            )
+            croibg2_a = croibg2_a * pol_arm2
+            croibg2_err_a = croibg2_err_a * pol_arm2
+            if croibg2_bgimg_a is not None:
+                croibg2_bgimg_a = croibg2_bgimg_a * pol_arm2
+                croibg2_bgimg_err_a = croibg2_bgimg_err_a * pol_arm2
+
         # The solid-angle correction is useful on the *intensity* -- for broad,
         # non-rod features a differential cross-section is what is wanted --
         # but it must not reach a structure factor: a region sum is already the
diff --git a/orgui/app/test/test_orGUI_reflections.py b/orgui/app/test/test_orGUI_reflections.py
index ba03d2e..5a51656 100644
--- a/orgui/app/test/test_orGUI_reflections.py
+++ b/orgui/app/test/test_orGUI_reflections.py
@@ -924,3 +924,61 @@ def test_display_roi_geometry_maps_clipped_detector_rows_to_plot_sides(
         expected_top,
         expected_bottom,
     )
+
+
+class FakeArmPolarizationDetector:
+    """A detector whose polarization falls off with the arm angle.
+
+    Lets the per-frame arm factor be written in closed form, independently of
+    the real z-axis expression, so a failure points at the plumbing rather
+    than at the physics.
+    """
+
+    def polarizationAtPoints(
+        self, row, column, alpha_i, gamma_arm=None, delta_arm=None
+    ):
+        arm = 0.0 if gamma_arm is None else float(gamma_arm)
+        return np.full(np.shape(row), 1.0 - 0.5 * arm**2, dtype=float)
+
+
+def test_the_polarization_arm_factor_follows_a_moving_arm():
+    """Finding F5: the factor is per frame and one at the calibrated position.
+
+    ``_polarizationArmFactor`` reads the arm from ``getArmAngles``, sharing
+    that convention with every other arm consumer in the application, and
+    returns what an intensity corrected at the calibrated position has to be
+    multiplied by.
+    """
+    arms = np.array([0.0, 0.1, 0.2])
+    stub = SimpleNamespace(getArmAngles=lambda: (arms, np.zeros_like(arms)))
+
+    got = orGUI._polarizationArmFactor(
+        stub, FakeArmPolarizationDetector(), 300.0, 240.0, 20.0, 20.0, 0.01
+    )
+
+    np.testing.assert_allclose(got, 1.0 / (1.0 - 0.5 * arms**2), rtol=1e-12)
+    assert got[0] == 1.0, "no arm rotation must leave the intensity alone"
+
+
+def test_the_polarization_arm_factor_broadcasts_a_constant_arm():
+    """The constant-arm shortcut must agree with the per-frame path.
+
+    A fixed arm is evaluated once and broadcast to keep the cost off the
+    common path, so the two branches have to give the same number.
+    """
+    constant = np.full(4, 0.2)
+    varying = np.array([0.2, 0.2, 0.2, 0.2000001])
+    detector = FakeArmPolarizationDetector()
+
+    fast = orGUI._polarizationArmFactor(
+        SimpleNamespace(getArmAngles=lambda: (constant, np.zeros(4))),
+        detector, 300.0, 240.0, 20.0, 20.0, 0.01,
+    )
+    looped = orGUI._polarizationArmFactor(
+        SimpleNamespace(getArmAngles=lambda: (varying, np.zeros(4))),
+        detector, 300.0, 240.0, 20.0, 20.0, 0.01,
+    )
+
+    assert fast.shape == (4,)
+    np.testing.assert_allclose(fast, 1.0 / (1.0 - 0.5 * 0.2**2), rtol=1e-12)
+    np.testing.assert_allclose(looped[:3], fast[:3], rtol=1e-12)
diff --git a/orgui/datautils/xrayutils/corrections/detector.py b/orgui/datautils/xrayutils/corrections/detector.py
index 77f45f8..39f4da0 100644
--- a/orgui/datautils/xrayutils/corrections/detector.py
+++ b/orgui/datautils/xrayutils/corrections/detector.py
@@ -55,7 +55,12 @@
 
 import numpy as np
 
-__all__ = ["pixel_factors", "roi_mean_inverse_solid_angle"]
+__all__ = [
+    "pixel_factors",
+    "polarization_arm_correction",
+    "roi_mean_inverse_polarization",
+    "roi_mean_inverse_solid_angle",
+]
 
 
 def pixel_factors(detector, solid_angle=False, polarization=False, shape=None):
@@ -167,3 +172,149 @@ def roi_mean_inverse_solid_angle(
         if block.size:
             out[index] = np.mean(1.0 / block)
     return out
+
+
+def _roi_sample_grid(row, column, row_size, column_size, samples):
+    """Coordinates spanning one region, at most ``samples`` per direction.
+
+    The polarization varies smoothly across a region, so a coarse sample
+    gives its mean to far better accuracy than the correction itself is
+    known. Capping the count keeps the cost per frame independent of how
+    large the region is.
+
+    Samples sit at the centres of equal sub-intervals, the midpoint rule, so
+    a single sample lands on the region centre rather than on an edge and no
+    sample count is biased towards one side.
+
+    :returns: ``(rows, columns)`` as 1D arrays of pixel coordinates.
+    :rtype: tuple
+    """
+
+    def _centres(centre, size, count):
+        count = int(min(max(int(round(size)), 1), count))
+        return centre + ((np.arange(count) + 0.5) / count - 0.5) * size
+
+    return (
+        _centres(row, row_size, samples),
+        _centres(column, column_size, samples),
+    )
+
+
+def roi_mean_inverse_polarization(
+    detector,
+    row,
+    column,
+    row_size,
+    column_size,
+    alpha,
+    gamma_arm=None,
+    delta_arm=None,
+    samples=17,
+):
+    r"""Mean of :math:`1/P` over a region, at one detector arm position.
+
+    Uses
+    :meth:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD.polarizationAtPoints`,
+    which evaluates the z-axis polarization expression in the surface-frame
+    angles of each pixel **at the arm position given**. That is the difference
+    from :func:`pixel_factors`, whose array comes from pyFAI's detector-frame
+    expression at the *calibrated* position; see
+    :func:`polarization_arm_correction`.
+
+    :param detector: A
+        :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`.
+    :param row: Region centre row, in pixels along pyFAI dimension 1.
+    :param column: Region centre column, in pixels along pyFAI dimension 2.
+    :param row_size: Region height in pixels.
+    :param column_size: Region width in pixels.
+    :param alpha: Incidence angle of the frame, in radian.
+    :param gamma_arm: Detector arm position, in radian; ``None`` is the
+        calibrated position. Give both arm angles or neither.
+    :param delta_arm: Detector arm position, in radian.
+    :param int samples: Upper bound on the sample count per direction.
+    :returns: The mean of :math:`1/P` over the region.
+    :rtype: float
+    """
+    rows, columns = _roi_sample_grid(
+        float(row), float(column), float(row_size), float(column_size), samples
+    )
+    grid_rows, grid_columns = np.meshgrid(rows, columns, indexing="ij")
+    polarization = detector.polarizationAtPoints(
+        np.ascontiguousarray(grid_rows.ravel()),
+        np.ascontiguousarray(grid_columns.ravel()),
+        float(alpha),
+        gamma_arm,
+        delta_arm,
+    )
+    return float(np.mean(1.0 / np.asarray(polarization, dtype=np.float64)))
+
+
+def polarization_arm_correction(
+    detector,
+    row,
+    column,
+    row_size,
+    column_size,
+    alpha,
+    gamma_arm,
+    delta_arm,
+    samples=17,
+):
+    r"""Factor moving a polarization correction onto the frame's arm position.
+
+    :func:`pixel_factors` divides by the polarization of the **calibrated**
+    geometry, evaluated once outside the frame loop. For a detector whose arm
+    does not move that is correct -- every pixel already carries its own
+    scattering angle. For a scan that drives the arm it is not: the same pixel
+    looks in a different direction on every frame, and the correction comes
+    out far too small. Measured at the centre of a detector at one metre, with
+    the arm following a specular scan, the calibrated-position polarization is
+    high by 0.8 % at a scattering angle of 5 degrees, 3.2 % at 10, 10.7 % at
+    18 and 33.6 % at 30.
+
+    This returns
+    :math:`\langle 1/P_\mathrm{arm}\rangle / \langle 1/P_\mathrm{home}\rangle`
+    over the region, the factor an intensity already corrected with the
+    calibrated-position polarization must be multiplied by. It is **exactly
+    one** when the arm sits at its calibrated position, so a fixed-arm scan is
+    untouched.
+
+    The ratio is taken between two region means rather than at the region
+    centre because the polarization is not flat across a region at a large
+    scattering angle: for a 100-pixel region at one metre near
+    :math:`2\theta = 30` degrees it varies by about a percent from edge to
+    edge. What is left out is the covariance with the solid angle over the
+    region, which :func:`pixel_factors` fuses into the same array -- second
+    order in the variation of both across one region.
+
+    See ``doc/design/ctr_structure_factor_scale.md`` finding F5.
+
+    :param detector: A
+        :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`.
+    :param row: Region centre row, in pixels along pyFAI dimension 1.
+    :param column: Region centre column, in pixels along pyFAI dimension 2.
+    :param row_size: Region height in pixels.
+    :param column_size: Region width in pixels.
+    :param alpha: Incidence angle of the frame, in radian.
+    :param gamma_arm: Detector arm position of the frame, in radian.
+    :param delta_arm: Detector arm position of the frame, in radian.
+    :param int samples: Upper bound on the sample count per direction.
+    :returns: The multiplicative correction, ``1.0`` at the calibrated
+        position.
+    :rtype: float
+    """
+    at_home = roi_mean_inverse_polarization(
+        detector, row, column, row_size, column_size, alpha, samples=samples
+    )
+    at_arm = roi_mean_inverse_polarization(
+        detector,
+        row,
+        column,
+        row_size,
+        column_size,
+        alpha,
+        gamma_arm,
+        delta_arm,
+        samples=samples,
+    )
+    return at_arm / at_home
diff --git a/orgui/datautils/xrayutils/test/test_corrections_detector.py b/orgui/datautils/xrayutils/test/test_corrections_detector.py
index d33a47d..89d9aa3 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_detector.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_detector.py
@@ -1,9 +1,11 @@
 """Regression tests for the per-pixel detector correction factors.
 
 :mod:`orgui.datautils.xrayutils.corrections.detector` owns the solid-angle and
-polarization arrays and the region reduction of the solid-angle part that a
-structure factor has to divide back out. See
-``doc/design/ctr_structure_factor_scale.md`` finding F6.
+polarization arrays, the region reduction of the solid-angle part that a
+structure factor has to divide back out (finding F6), and the factor that
+moves a polarization correction from the calibrated arm position onto the arm
+position a frame was actually measured at (finding F5). See
+``doc/design/ctr_structure_factor_scale.md``.
 """
 
 import numpy as np
@@ -134,3 +136,85 @@ def test_a_zero_or_negative_region_is_rejected():
         detector_corrections.roi_mean_inverse_solid_angle(
             det, 300.0, 240.0, 20.0, -5.0
         )
+
+
+def test_the_arm_correction_is_one_at_the_calibrated_position():
+    """A fixed-arm scan must come out bit-identical.
+
+    The whole point of expressing finding F5 as a ratio is that it changes
+    nothing for a detector that does not move: the correction already applied
+    is the right one there.
+    """
+    det = _calibrated_detector()
+
+    got = detector_corrections.polarization_arm_correction(
+        det, 300.0, 240.0, 60.0, 60.0, np.deg2rad(0.6), None, None
+    )
+
+    assert got == 1.0
+
+
+def test_the_arm_correction_recovers_the_documented_errors():
+    """The size of finding F5, written out from the two evaluations.
+
+    The calibrated-position polarization is too small a correction for a
+    moving arm, so the factor is above one and grows with the scattering
+    angle. The reference is the ratio of the polarization at the two arm
+    positions at the region centre, which is what the region means reduce to
+    for a small region.
+    """
+    det = _calibrated_detector()
+    row, column = 310.0, 244.0
+    alpha = np.deg2rad(0.6)
+
+    for two_theta, expected_percent in ((10.0, 3.2), (18.0, 10.7), (30.0, 33.6)):
+        arm = np.deg2rad(two_theta)
+        got = detector_corrections.polarization_arm_correction(
+            det, row, column, 4.0, 4.0, alpha, arm, 0.0
+        )
+
+        p_home = det.polarizationAtPoints(
+            np.array([row]), np.array([column]), alpha
+        )[0]
+        p_arm = det.polarizationAtPoints(
+            np.array([row]), np.array([column]), alpha, arm, 0.0
+        )[0]
+        np.testing.assert_allclose(got, p_home / p_arm, rtol=1e-3)
+        np.testing.assert_allclose(100.0 * (got - 1.0), expected_percent, rtol=5e-2)
+
+
+def test_the_arm_correction_averages_over_the_region():
+    """At a large scattering angle the polarization is not flat over a region.
+
+    Taking the ratio at the region centre instead of between two region means
+    is a fraction of a percent off for a large region at
+    :math:`2\\theta = 30` degrees, which is why the means are used.
+    """
+    det = _calibrated_detector()
+    row, column, alpha = 310.0, 244.0, np.deg2rad(0.6)
+    arm = np.deg2rad(30.0)
+
+    small = detector_corrections.polarization_arm_correction(
+        det, row, column, 2.0, 2.0, alpha, arm, 0.0
+    )
+    large = detector_corrections.polarization_arm_correction(
+        det, row, column, 300.0, 300.0, alpha, arm, 0.0
+    )
+
+    assert not np.isclose(small, large, rtol=1e-4)
+    # Both still describe the same correction, so they stay close.
+    np.testing.assert_allclose(large, small, rtol=2e-2)
+
+
+def test_the_region_mean_polarization_follows_the_arm():
+    """The underlying quantity, which the ratio is built from."""
+    det = _calibrated_detector()
+    args = (det, 310.0, 244.0, 40.0, 40.0, np.deg2rad(0.6))
+
+    home = detector_corrections.roi_mean_inverse_polarization(*args)
+    moved = detector_corrections.roi_mean_inverse_polarization(
+        *args, gamma_arm=np.deg2rad(30.0), delta_arm=0.0
+    )
+
+    assert home < moved, "a larger scattering angle needs a larger correction"
+    np.testing.assert_allclose(home, 1.0, rtol=1e-3)

From 6672938d6c2c3728d49927c7ff96c7395772650d Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 11 Sep 2026 13:35:12 -0400
Subject: [PATCH 08/33] fix: start the CLI on the offscreen Qt platform

---
 orgui/main.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/orgui/main.py b/orgui/main.py
index 585847c..7341d0d 100644
--- a/orgui/main.py
+++ b/orgui/main.py
@@ -268,9 +268,13 @@ def main():
         os.environ["NUMEXPR_NUM_THREADS"] = os.environ["NUMEXPR_MAX_THREADS"]
 
     if options.cli:
-        os.environ["QT_QPA_PLATFORM"] = (
-            "minimal"  # "offscreen" # maybe use minimal instead
-        )
+        # "offscreen" rather than "minimal": the minimal platform plugin has
+        # no font database, so Qt cannot load an application font there. silx
+        # builds its plot windows with qtawesome icons, which loads one, and
+        # under "minimal" that fails the whole CLI startup with a FontError
+        # before any batch script runs. setdefault so an explicitly chosen
+        # platform still wins.
+        os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
         from . import logger_utils
 
         logger_utils.set_logging_context("cli")

From 9fcfb51e8b625e417a5a04d2933c8c4993f45b34 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 11 Sep 2026 13:37:55 -0400
Subject: [PATCH 09/33] fix(phys): keep off-detector regions out of the
 detector corrections

---
 .../xrayutils/corrections/detector.py         | 29 ++++++++--
 .../test/test_corrections_detector.py         | 54 +++++++++++++++++++
 2 files changed, 79 insertions(+), 4 deletions(-)

diff --git a/orgui/datautils/xrayutils/corrections/detector.py b/orgui/datautils/xrayutils/corrections/detector.py
index 39f4da0..d6f543b 100644
--- a/orgui/datautils/xrayutils/corrections/detector.py
+++ b/orgui/datautils/xrayutils/corrections/detector.py
@@ -137,9 +137,12 @@ def roi_mean_inverse_solid_angle(
     :returns: The mean of the reciprocal normalized solid angle, broadcast
         over the inputs. A region entirely off the detector contains no pixels
         and no counts, and yields ``1.0`` so that it neither rescales nor
-        invalidates the zero intensity there.
+        invalidates the zero intensity there. So does a region whose position
+        is not finite: a real scan has frames where the rod never reaches the
+        detector, and those arrive here as ``inf`` or ``nan`` centres while
+        carrying no counts either.
     :rtype: numpy.ndarray
-    :raises ValueError: If a region size is not positive.
+    :raises ValueError: If a finite region size is not positive.
     """
     solid_angle = np.asarray(
         detector.solidAngleArray(shape) if shape is not None
@@ -152,8 +155,17 @@ def roi_mean_inverse_solid_angle(
         np.asarray(row_size, dtype=np.float64),
         np.asarray(column_size, dtype=np.float64),
     )
+    # A non-finite position or size is a frame on which the rod never reached
+    # the detector. Those carry no counts, so they are skipped rather than
+    # rejected; only a *finite* size that is not positive is a real error.
+    defined = (
+        np.isfinite(row)
+        & np.isfinite(column)
+        & np.isfinite(row_size)
+        & np.isfinite(column_size)
+    )
     for name, value in (("height", row_size), ("width", column_size)):
-        if np.any(value <= 0) or not np.all(np.isfinite(value)):
+        if np.any(value[defined] <= 0):
             raise ValueError(
                 f"the region of interest must have a positive {name} in "
                 f"pixels; got {value!r}"
@@ -162,6 +174,8 @@ def roi_mean_inverse_solid_angle(
     n_rows, n_columns = solid_angle.shape[0], solid_angle.shape[1]
     out = np.ones(row.shape, dtype=np.float64)
     for index in np.ndindex(*row.shape):
+        if not defined[index]:
+            continue
         r0 = int(np.floor(row[index] - row_size[index] / 2.0))
         r1 = int(np.ceil(row[index] + row_size[index] / 2.0))
         c0 = int(np.floor(column[index] - column_size[index] / 2.0))
@@ -300,9 +314,16 @@ def polarization_arm_correction(
     :param delta_arm: Detector arm position of the frame, in radian.
     :param int samples: Upper bound on the sample count per direction.
     :returns: The multiplicative correction, ``1.0`` at the calibrated
-        position.
+        position and ``1.0`` where the region position is not finite -- a
+        frame on which the rod never reached the detector, which carries no
+        counts to correct.
     :rtype: float
     """
+    if not all(
+        np.isfinite(float(value))
+        for value in (row, column, row_size, column_size, alpha)
+    ):
+        return 1.0
     at_home = roi_mean_inverse_polarization(
         detector, row, column, row_size, column_size, alpha, samples=samples
     )
diff --git a/orgui/datautils/xrayutils/test/test_corrections_detector.py b/orgui/datautils/xrayutils/test/test_corrections_detector.py
index 89d9aa3..171df64 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_detector.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_detector.py
@@ -218,3 +218,57 @@ def test_the_region_mean_polarization_follows_the_arm():
 
     assert home < moved, "a larger scattering angle needs a larger correction"
     np.testing.assert_allclose(home, 1.0, rtol=1e-3)
+
+
+def test_a_non_finite_region_position_is_neutral_not_fatal():
+    """Real scans have frames on which the rod never reaches the detector.
+
+    Those arrive with ``inf`` or ``nan`` region centres -- and with no counts,
+    since no pixel was valid. Found on FeReO4 scan 39, where it aborted a
+    stationary integration with ``OverflowError: cannot convert float
+    infinity to integer`` after the frame loop had already finished.
+    """
+    det = _calibrated_detector()
+    row = np.array([300.0, np.inf, np.nan, 400.0])
+    column = np.array([240.0, 240.0, np.nan, np.inf])
+
+    got = detector_corrections.roi_mean_inverse_solid_angle(
+        det, row, column, 20.0, 20.0
+    )
+
+    assert np.all(np.isfinite(got))
+    np.testing.assert_allclose(got[[1, 2, 3]], 1.0, rtol=0.0)
+    assert got[0] > 1.0, "the finite frame must still be corrected"
+
+
+def test_a_non_finite_region_size_is_neutral_too():
+    """The size can be degenerate on an off-detector frame as well."""
+    det = _calibrated_detector()
+
+    got = detector_corrections.roi_mean_inverse_solid_angle(
+        det, 300.0, 240.0, np.array([20.0, np.nan]), 20.0
+    )
+
+    assert np.all(np.isfinite(got))
+    np.testing.assert_allclose(got[1], 1.0, rtol=0.0)
+
+
+def test_a_finite_but_empty_region_is_still_rejected():
+    """Guarding non-finite sizes must not swallow a genuinely bad one."""
+    det = _calibrated_detector()
+
+    with pytest.raises(ValueError, match="positive height"):
+        detector_corrections.roi_mean_inverse_solid_angle(
+            det, 300.0, 240.0, np.array([20.0, 0.0]), 20.0
+        )
+
+
+def test_the_arm_correction_is_neutral_for_a_non_finite_region():
+    """Same guard on the F5 factor, which is fed the same coordinates."""
+    det = _calibrated_detector()
+
+    got = detector_corrections.polarization_arm_correction(
+        det, np.inf, 240.0, 20.0, 20.0, np.deg2rad(0.6), np.deg2rad(30.0), 0.0
+    )
+
+    assert got == 1.0

From 964d2875d9ebb5f3aa386b11024075517c74c15f Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 11 Sep 2026 13:38:50 -0400
Subject: [PATCH 10/33] fix(phys): measure the rocking corrections on the
 stored detector

---
 orgui/app/peak1Dintegr.py           | 76 ++++++++++++++++++--------
 orgui/app/test/test_peak1Dintegr.py | 84 +++++++++++++++++++++++++++--
 2 files changed, 136 insertions(+), 24 deletions(-)

diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 8b99d4c..9421173 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -55,7 +55,7 @@
 import traceback
 
 from . import qutils
-from .config_data import ConfigData
+from .config_data import ConfigData, detector_from_nxdict
 from .. import resources
 from .. import logger_utils
 from ..datautils.xrayutils.corrections import beamprofile
@@ -1421,7 +1421,45 @@ def _rocking_normalization(self, aux, size):
             size, exposure_time=exposure, monitors=monitors
         )
 
-    def _rocking_solid_angle_mean(self, scangroup, cnters, x, y):
+    def _stored_detector(self, scangroup):
+        """The detector geometry the rocking curves were measured with.
+
+        Read from the configuration stored beside the scan, never from the
+        current application state. The acceptance and the solid-angle factor
+        are properties of the geometry the data was *taken* with, and a
+        reduction run later -- from a batch script, or after another
+        calibration has been loaded -- would otherwise silently use whatever
+        detector happens to be loaded. Measured on a LaNiO3 rocking scan, that
+        mistake scaled every ``Delta_gamma`` by 2.3 and left no trace in the
+        output.
+
+        :param scangroup: The scan group holding ``configuration``.
+        :returns: A
+            :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`,
+            or ``None`` when the scan stores no detector configuration.
+        :rtype: object or None
+        """
+        path = scangroup.name + "/configuration/instrument/detector_SXRD"
+        if path not in self.database.nxfile:
+            logger.warning(
+                "This scan stores no detector configuration, so the "
+                "out-of-plane acceptance cannot be calculated from the "
+                "geometry the data was measured with. F2_hkl is left on the "
+                "acceptance-blind scale."
+            )
+            return None
+        try:
+            return detector_from_nxdict(h5todict(self.database.nxfile, path))
+        except Exception:
+            logger.exception(
+                "Cannot rebuild the detector geometry stored with this scan, "
+                "so the out-of-plane acceptance cannot be calculated. F2_hkl "
+                "is left on the acceptance-blind scale.",
+                extra={"title": "Cannot read the stored detector geometry"},
+            )
+            return None
+
+    def _rocking_solid_angle_mean(self, detector, scangroup, cnters, x, y):
         """Region mean of the solid-angle correction that was applied, or None.
 
         The solid-angle correction is applied to the *intensity* when the
@@ -1435,8 +1473,11 @@ def _rocking_solid_angle_mean(self, scangroup, cnters, x, y):
 
         Whether it was applied is a property of the *extraction*, not of the
         switches in this dialog, so it is read from the configuration snapshot
-        stored with the scan rather than from the current GUI state.
+        stored with the scan rather than from the current GUI state -- as is
+        the detector geometry it is measured over.
 
+        :param detector: The geometry the scan was measured with, from
+            :meth:`_stored_detector`.
         :param scangroup: The scan group holding the ``configuration`` written
             when the rocking curves were extracted.
         :param cnters: The ``rois`` group of the rocking scan.
@@ -1466,14 +1507,12 @@ def _rocking_solid_angle_mean(self, scangroup, cnters, x, y):
         if not was_applied:
             return None, False
 
-        config_target = self.database.config_target
-        detector = getattr(getattr(config_target, "ubcalc", None), "detectorCal", None)
         if detector is None:
             logger.warning(
                 "The solid angle correction was applied to these rocking "
-                "curves, but no calibrated detector is available to measure it "
-                "over the regions of interest, so it is not divided out of "
-                "F2_hkl."
+                "curves, but the detector geometry stored with the scan is "
+                "not available to measure it over the regions of interest, so "
+                "it is not divided out of F2_hkl."
             )
             return None, False
 
@@ -1493,7 +1532,7 @@ def _rocking_solid_angle_mean(self, scangroup, cnters, x, y):
         )
         return np.asarray(mean, dtype=float), True
 
-    def _rocking_acceptance(self, cnters, x, y):
+    def _rocking_acceptance(self, detector, cnters, x, y):
         """Out-of-plane acceptance of every region of interest, in radian.
 
         A rocking scan intercepts a slice of rod proportional to
@@ -1512,23 +1551,17 @@ def _rocking_acceptance(self, cnters, x, y):
         :math:`\\gamma` is measured around, so this costs nothing measurable;
         see ``doc/design/ctr_structure_factor_scale.md`` section 4.4.
 
+        :param detector: The geometry the scan was measured with, from
+            :meth:`_stored_detector`; ``None`` leaves the acceptance out.
         :param cnters: The ``rois`` group of the rocking scan.
         :param x: Region centre column per ``s`` point, in pixels.
         :param y: Region centre row per ``s`` point, in pixels.
         :returns: ``(acceptance, applied)`` -- the acceptance in radian of
-            shape ``(n_s,)``, or ``(None, False)`` when no calibrated
-            detector is reachable.
+            shape ``(n_s,)``, or ``(None, False)`` when the stored geometry
+            is unavailable.
         :rtype: tuple
         """
-        config_target = self.database.config_target
-        detector = getattr(getattr(config_target, "ubcalc", None), "detectorCal", None)
         if detector is None:
-            logger.warning(
-                "No calibrated detector is available, so the out-of-plane "
-                "acceptance of the regions of interest cannot be calculated. "
-                "F2_hkl is left on the acceptance-blind scale and will not "
-                "agree with a stationary integration of the same rod."
-            )
             return None, False
 
         vsize = cnters["vsize"][()]
@@ -1632,11 +1665,12 @@ def integrate(self):
         detector_acceptance, acceptance_applied = None, False
         solid_angle_mean, solid_angle_compensated = None, False
         if self.lorentzButton.isChecked():
+            detector = self._stored_detector(scangroup)
             detector_acceptance, acceptance_applied = self._rocking_acceptance(
-                cnters, x, y
+                detector, cnters, x, y
             )
             solid_angle_mean, solid_angle_compensated = (
-                self._rocking_solid_angle_mean(scangroup, cnters, x, y)
+                self._rocking_solid_angle_mean(detector, scangroup, cnters, x, y)
             )
 
         self.database.nxfile[self._currentRoInfo["name"] + "/integration/"]
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index a36b1e7..1b3d033 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -13,9 +13,13 @@
 saved rocking intensities and uncertainties from regression.
 """
 
+import os
+import tempfile
 from types import SimpleNamespace
 
+import h5py
 import numpy as np
+import pytest
 
 from orgui.app.peak1Dintegr import (
     RockingPeakIntegrator,
@@ -454,7 +458,8 @@ def test_the_acceptance_reads_the_row_from_y_and_the_column_from_x():
     }
 
     acceptance, applied = RockingPeakIntegrator._rocking_acceptance(
-        _stub(detector), cnters, x=np.array([5.0, 300.0, 470.0]), y=np.full(3, 250.0)
+        _stub(), detector, cnters,
+        x=np.array([5.0, 300.0, 470.0]), y=np.full(3, 250.0)
     )
 
     assert applied is True
@@ -462,11 +467,11 @@ def test_the_acceptance_reads_the_row_from_y_and_the_column_from_x():
 
 
 def test_a_missing_detector_leaves_the_acceptance_out_rather_than_failing():
-    """CLI use without a calibration must not lose the integration."""
+    """A scan storing no detector geometry must not lose the integration."""
     cnters = {"vsize": np.array([40.0]), "alpha_pk": np.zeros(1)}
 
     acceptance, applied = RockingPeakIntegrator._rocking_acceptance(
-        _stub(None), cnters, x=np.array([100.0]), y=np.array([200.0])
+        _stub(), None, cnters, x=np.array([100.0]), y=np.array([200.0])
     )
 
     assert acceptance is None
@@ -503,3 +508,76 @@ def test_a_missing_exposure_counter_is_skipped_and_recorded():
 
     np.testing.assert_allclose(divisor, np.ones(3), rtol=1e-12)
     assert applied == []
+
+
+def test_the_detector_comes_from_the_scan_not_from_the_application():
+    """The acceptance must use the geometry the data was measured with.
+
+    ``Delta_gamma`` is a property of the detector the rocking curves were
+    recorded on. Reading it from whatever calibration the application happens
+    to hold makes a reduction run later -- from a batch script, or after a
+    different calibration was loaded -- silently wrong: on a real LaNiO3 scan
+    that scaled every acceptance by 2.3 with nothing in the output to show
+    for it.
+    """
+    pyFAI = pytest.importorskip("pyFAI")
+    from silx.io.dictdump import dicttonx
+
+    from orgui.app.config_data import detector_to_nxdict
+    from orgui.datautils.xrayutils import DetectorCalibration
+
+    stored = DetectorCalibration.Detector2D_SXRD()
+    stored.detector = pyFAI.detectors.Detector(
+        pixel1=172e-6, pixel2=172e-6, max_shape=(619, 487)
+    )
+    stored.dist = 0.5
+    stored.poni1, stored.poni2 = 0.05, 0.04
+    stored.rot1 = stored.rot2 = stored.rot3 = 0.0
+    stored.set_energy(15.0)
+    stored.setAzimuthalReference(np.deg2rad(90.0))
+    stored.setPolarization(0.0, 1.0)
+
+    with tempfile.TemporaryDirectory() as folder:
+        path = os.path.join(folder, "scan.h5")
+        dicttonx(
+            {"configuration": {"instrument": {
+                "detector_SXRD": detector_to_nxdict(stored)}}},
+            path,
+            h5path="/61.1",
+            update_mode="add",
+        )
+        with h5py.File(path, "r") as handle:
+            integrator = SimpleNamespace(
+                database=SimpleNamespace(
+                    nxfile=handle,
+                    # A *different* geometry in the application, which must
+                    # not be the one that gets used.
+                    config_target=SimpleNamespace(
+                        ubcalc=SimpleNamespace(detectorCal="wrong detector")
+                    ),
+                )
+            )
+            got = RockingPeakIntegrator._stored_detector(
+                integrator, handle["/61.1"]
+            )
+
+    assert got is not None
+    assert got != "wrong detector"
+    assert got.dist == pytest.approx(0.5)
+    assert got.poni1 == pytest.approx(0.05)
+    assert got.poni2 == pytest.approx(0.04)
+
+
+def test_a_scan_without_a_stored_detector_gives_none():
+    """An older database has no geometry to read; that is not a crash."""
+    with tempfile.TemporaryDirectory() as folder:
+        path = os.path.join(folder, "scan.h5")
+        with h5py.File(path, "w") as handle:
+            handle.create_group("/61.1")
+        with h5py.File(path, "r") as handle:
+            integrator = SimpleNamespace(
+                database=SimpleNamespace(nxfile=handle, config_target=None)
+            )
+            assert RockingPeakIntegrator._stored_detector(
+                integrator, handle["/61.1"]
+            ) is None

From ec5454b67f379d78a7ea0bd58c6e0bf96775f9e7 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 11 Sep 2026 13:54:57 -0400
Subject: [PATCH 11/33] refactor: name every integration option in snake_case

---
 orgui/app/QScanSelector.py                   | 192 ++++++++++++++-----
 orgui/app/ROIutils.py                        |  19 +-
 orgui/app/ReconstructionDialog.py            |   4 +-
 orgui/app/_option_keys.py                    | 154 +++++++++++++++
 orgui/app/orGUI.py                           |  26 +--
 orgui/app/test/test_config_data.py           |   2 +-
 orgui/app/test/test_option_keys.py           | 113 +++++++++++
 orgui/app/test/test_reconstruction_dialog.py |   8 +-
 8 files changed, 450 insertions(+), 68 deletions(-)
 create mode 100644 orgui/app/_option_keys.py
 create mode 100644 orgui/app/test/test_option_keys.py

diff --git a/orgui/app/QScanSelector.py b/orgui/app/QScanSelector.py
index 94df425..13ec7a8 100644
--- a/orgui/app/QScanSelector.py
+++ b/orgui/app/QScanSelector.py
@@ -49,6 +49,7 @@
 from ..backend import backends, scans
 from . import qutils
 from . import integration_corrections
+from ._option_keys import LegacyKeyDict, canonical_options
 from .QReflectionSelector import QReflectionAnglesDialog
 from .QHKLDialog import HKLDialog
 
@@ -891,32 +892,115 @@ def fun(x):
 
         self.sigROIChanged.emit()
 
+    #: Integration switch name -> the checkbox holding it.
+    @property
+    def _switch_boxes(self):
+        return {
+            "mask": self.useMaskBox,
+            "solid_angle": self.useSolidAngleBox,
+            "polarization": self.usePolarizationBox,
+            "lorentz": self.useLorentzBox,
+            "footprint": self.useFootprintBox,
+            "normalization": self.useNormalizationBox,
+        }
+
+    #: Region control name -> the spin box or check box holding it.
+    @property
+    def _region_controls(self):
+        return {
+            "hsize": self.hsize,
+            "vsize": self.vsize,
+            "left": self.left,
+            "right": self.right,
+            "top": self.top,
+            "bottom": self.bottom,
+            "auto_hsize": self.autoROIHsize,
+            "auto_vsize": self.autoROIVsize,
+        }
+
+    #: Rocking-scan sampling control name -> the spin box holding it.
+    @property
+    def _rocking_controls(self):
+        return {"delta_s": self.roscanDeltaS, "max_s": self.roscanMaxS}
+
     def set_integration_options(self, ddict):
-        for key in ddict:
-            if key == "mask":
-                self.useMaskBox.setChecked(ddict[key])
-            elif key == "solidAngle":
-                self.useSolidAngleBox.setChecked(ddict[key])
-            elif key == "polarization":
-                self.usePolarizationBox.setChecked(ddict[key])
-            elif key == "lorentz":
-                self.useLorentzBox.setChecked(ddict[key])
-            elif key == "footprint":
-                self.useFootprintBox.setChecked(ddict[key])
-            elif key == "normalization":
-                self.useNormalizationBox.setChecked(ddict[key])
+        """Restore integration options from a mapping.
+
+        A key this version does not know is ignored rather than rejected,
+        which is what lets an older orGUI read a newer configuration. Legacy
+        key spellings are accepted with a deprecation warning; see
+        :mod:`orgui.app._option_keys`.
+
+        :param dict ddict: Any subset of the keys
+            :meth:`get_integration_options` returns.
+        """
+        ddict = canonical_options(ddict)
+        boxes = self._switch_boxes
+        for key, value in ddict.items():
+            if key in boxes:
+                boxes[key].setChecked(bool(value))
             elif key == "advanced":
-                self.roioptions.set_parameters(ddict[key])
+                self.roioptions.set_parameters(value)
+            elif key == "region":
+                self._set_region_options(value)
+            elif key == "rocking_scan":
+                self._set_rocking_options(value)
+
+    def _set_region_options(self, ddict):
+        """Restore the region sizes and the automatic-sizing switches."""
+        controls = self._region_controls
+        ddict = canonical_options(ddict)
+        for key, value in ddict.items():
+            control = controls.get(key)
+            if control is None:
+                continue
+            with blockSignals(control):
+                if key.startswith("auto_"):
+                    control.setChecked(bool(value))
+                else:
+                    control.setValue(float(value))
+        self.sigROIChanged.emit()
+
+    def _set_rocking_options(self, ddict):
+        """Restore the rocking-scan sampling.
+
+        Signals are blocked deliberately: assigning ``delta_s`` normally runs
+        :meth:`onRoSChanged`, which clips it to the detector resolution and
+        writes the clipped value back. The stored value is already the
+        clipped one, and re-clipping it against whatever scan happens to be
+        loaded would not restore what was saved.
+        """
+        controls = self._rocking_controls
+        ddict = canonical_options(ddict)
+        for key, value in ddict.items():
+            control = controls.get(key)
+            if control is not None:
+                with blockSignals(control):
+                    control.setValue(float(value))
 
     def get_integration_options(self):
-        ddict = {}
-        ddict["mask"] = self.useMaskBox.isChecked()
-        ddict["solidAngle"] = self.useSolidAngleBox.isChecked()
-        ddict["polarization"] = self.usePolarizationBox.isChecked()
-        ddict["lorentz"] = self.useLorentzBox.isChecked()
-        ddict["footprint"] = self.useFootprintBox.isChecked()
-        ddict["normalization"] = self.useNormalizationBox.isChecked()
+        """Every integration option, under its current key spelling.
+
+        :returns: The switches as flat booleans, plus ``advanced`` (the
+            region-of-interest options dialog), ``region`` (sizes and
+            automatic sizing) and ``rocking_scan`` (the ``s`` sampling).
+            Reading a legacy key off the result still works, with a
+            deprecation warning.
+        :rtype: LegacyKeyDict
+        """
+        ddict = LegacyKeyDict(
+            (name, box.isChecked()) for name, box in self._switch_boxes.items()
+        )
         ddict["advanced"] = self.roioptions.get_parameters()
+        ddict["region"] = LegacyKeyDict(
+            (name, control.isChecked() if name.startswith("auto_")
+             else control.value())
+            for name, control in self._region_controls.items()
+        )
+        ddict["rocking_scan"] = LegacyKeyDict(
+            (name, control.value())
+            for name, control in self._rocking_controls.items()
+        )
         return ddict
 
     #: Enabled corrections, as ``(checkbox attribute, abbreviation, color,
@@ -1763,36 +1847,56 @@ def set_offsets(self, offsetx, offsety):
         self._onAnyValueChanged()
 
     def get_parameters(self):
+        """Advanced region-of-interest options, under current key spellings.
+
+        Sample sizes are in **meter** and offsets in **pixels**, which is the
+        unit the consumers of this dictionary expect; the widgets show
+        micrometer. Reading a legacy key off the result still works, with a
+        deprecation warning.
+
+        :rtype: LegacyKeyDict
+        """
         sizes = self.get_sample_size()
-        offX, offY = self._offsetx.value(), self._offsety.value()
-
-        ddict = {
-            "DetectorInclination": self.hasDetectorInclination(),
-            "ProjectSampleSize": self.hasProjectSampleSize(),
-            "xoffset": offX,
-            "yoffset": offY,
-            "sizeX": sizes[0],
-            "sizeY": sizes[1],
-            "sizeZ": sizes[2],
+        return LegacyKeyDict({
+            "detector_inclination": self.hasDetectorInclination(),
+            "project_sample_size": self.hasProjectSampleSize(),
+            "offset_x": self._offsetx.value(),
+            "offset_y": self._offsety.value(),
+            "sample_size_x": sizes[0],
+            "sample_size_y": sizes[1],
+            "sample_size_z": sizes[2],
             "factor": self.get_apply_factor(),
-            "FittedBackground": self.hasFittedBackground(),
-            "FittedBackgroundOrder": self.get_background_fit_order(),
-        }
-
-        return ddict
+            "fitted_background": self.hasFittedBackground(),
+            "fitted_background_order": self.get_background_fit_order(),
+        })
 
     def set_parameters(self, ddict):
+        """Restore the advanced options from a mapping.
+
+        Legacy key spellings are accepted with a deprecation warning; see
+        :mod:`orgui.app._option_keys`. Sample sizes are in meter, offsets in
+        pixels.
+
+        :param dict ddict: As returned by :meth:`get_parameters`.
+        """
+        ddict = canonical_options(ddict)
         self._updating_parameters = True
         try:
-            self.inclinationBox.setChecked(ddict["DetectorInclination"])
-            self.sizeGroup.setChecked(ddict["ProjectSampleSize"])
-            self.set_sample_size(ddict["sizeX"], ddict["sizeY"], ddict["sizeZ"])
-            self.set_offsets(ddict["xoffset"], ddict["yoffset"])
+            self.inclinationBox.setChecked(ddict["detector_inclination"])
+            self.sizeGroup.setChecked(ddict["project_sample_size"])
+            self.set_sample_size(
+                ddict["sample_size_x"],
+                ddict["sample_size_y"],
+                ddict["sample_size_z"],
+            )
+            self.set_offsets(ddict["offset_x"], ddict["offset_y"])
             self.set_apply_factor(ddict["factor"])
-            self.backgroundFitGroup.setChecked(ddict.get("FittedBackground", False))
-            self._backgroundFitOrder.setValue(ddict.get("FittedBackgroundOrder", 1))
-        except Exception:
-            raise
+            self.backgroundFitGroup.setChecked(
+                ddict.get("fitted_background", False)
+            )
+            self._backgroundFitOrder.setValue(
+                ddict.get("fitted_background_order", 1)
+            )
         finally:
             self._updating_parameters = False
         self._onAnyValueChanged()
diff --git a/orgui/app/ROIutils.py b/orgui/app/ROIutils.py
index 65c651d..96512b5 100644
--- a/orgui/app/ROIutils.py
+++ b/orgui/app/ROIutils.py
@@ -30,6 +30,8 @@
 
 import numpy as np
 
+from ._option_keys import canonical_options
+
 
 def cos_incidence_12(xy, sxrddetector):
     xy = np.asarray(xy)
@@ -120,16 +122,25 @@ def calc_corrections(
     parallax=True,
     factor=1.0,
 ):
-    """samplesize must be a dict, sizes in m"""
+    """Region sizes projected from the sample onto the detector.
+
+    :param samplesize: Mapping with ``sample_size_x``, ``sample_size_y`` and
+        ``sample_size_z`` **in meter**, as
+        :meth:`~orgui.app.QScanSelector.ROIAdvancedOptions.get_parameters`
+        returns. The legacy ``sizeX``/``sizeY``/``sizeZ`` spellings are
+        accepted with a deprecation warning. ``None`` uses ``roisize0``
+        alone.
+    """
     if np.all(roisize0 == np.array([0, 0])) and samplesize is None:
         raise ValueError("You must either provide the sample size or a minimum roisize")
 
     roisize_X_real = roisize0[0] * sxrddetector.detector.pixel2
     roisize_Y_real = roisize0[1] * sxrddetector.detector.pixel1
     if samplesize is not None:
-        sizeX = samplesize["sizeX"]
-        sizeY = samplesize["sizeY"]
-        sizeZ = samplesize["sizeZ"]
+        samplesize = canonical_options(samplesize)
+        sizeX = samplesize["sample_size_x"]
+        sizeY = samplesize["sample_size_y"]
+        sizeZ = samplesize["sample_size_z"]
 
         beamX, beamY = projected_beamsize(xy, sxrddetector, sizeX, sizeY, sizeZ)
 
diff --git a/orgui/app/ReconstructionDialog.py b/orgui/app/ReconstructionDialog.py
index e96d2cd..d6d821a 100644
--- a/orgui/app/ReconstructionDialog.py
+++ b/orgui/app/ReconstructionDialog.py
@@ -490,7 +490,7 @@ def _data_tab(self):
         self.use_polarization.setToolTip(shared_tooltip)
         for control, key, row, column in (
             (self.use_pixel_mask, "mask", 0, 0),
-            (self.use_solid_angle, "solidAngle", 0, 1),
+            (self.use_solid_angle, "solid_angle", 0, 1),
             (self.use_polarization, "polarization", 1, 0),
         ):
             control.toggled.connect(
@@ -619,7 +619,7 @@ def _sync_integration_options(self):
         options = selector.get_integration_options()
         for control, key in (
             (self.use_pixel_mask, "mask"),
-            (self.use_solid_angle, "solidAngle"),
+            (self.use_solid_angle, "solid_angle"),
             (self.use_polarization, "polarization"),
         ):
             with qt.QSignalBlocker(control):
diff --git a/orgui/app/_option_keys.py b/orgui/app/_option_keys.py
new file mode 100644
index 0000000..a407a2b
--- /dev/null
+++ b/orgui/app/_option_keys.py
@@ -0,0 +1,154 @@
+# /*##########################################################################
+#
+# Copyright (c) 2026 Timo Fuchs
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+"""Option-dictionary key names, and the legacy spellings they replaced.
+
+The integration options and the advanced region-of-interest options are
+passed around as plain dictionaries, including by user batch scripts. Their
+keys were originally spelled in mixed case (``solidAngle``,
+``DetectorInclination``, ``sizeX``) while everything those options are stored
+next to uses ``snake_case``. The names are now ``snake_case`` throughout, and
+the old spellings keep working for one deprecation cycle.
+
+Both directions are covered, and they need different mechanisms:
+
+* a script that *passes* an old key is handled by :func:`canonical_options`,
+  which rewrites the mapping on the way in. Rewriting on read is not enough,
+  because ``for key in ddict`` and ``**ddict`` never reach ``__getitem__``.
+* code that *reads* an old key off a returned dictionary is handled by
+  :class:`LegacyKeyDict`, which resolves the alias on lookup.
+
+Each legacy key warns twice on first use: a :exc:`DeprecationWarning` for
+tooling, and one log record, because :exc:`DeprecationWarning` is invisible by
+default and these dictionaries are mostly written in batch scripts whose only
+output is a log.
+"""
+
+import logging
+import warnings
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "LEGACY_KEYS",
+    "LegacyKeyDict",
+    "canonical_key",
+    "canonical_options",
+]
+
+#: Legacy option-dictionary key -> the name that replaced it.
+LEGACY_KEYS = {
+    # Integration options
+    "solidAngle": "solid_angle",
+    # Advanced region-of-interest options
+    "DetectorInclination": "detector_inclination",
+    "ProjectSampleSize": "project_sample_size",
+    "sizeX": "sample_size_x",
+    "sizeY": "sample_size_y",
+    "sizeZ": "sample_size_z",
+    "xoffset": "offset_x",
+    "yoffset": "offset_y",
+    "FittedBackground": "fitted_background",
+    "FittedBackgroundOrder": "fitted_background_order",
+}
+
+#: Legacy keys already reported, so a loop over a scan warns once, not once
+#: per frame.
+_reported = set()
+
+
+def _report(legacy):
+    """Warn once per legacy key, to both the warnings system and the log."""
+    message = (
+        f"The integration option key {legacy!r} is deprecated; use "
+        f"{LEGACY_KEYS[legacy]!r} instead. The old spelling will be removed "
+        f"in a future release."
+    )
+    warnings.warn(message, DeprecationWarning, stacklevel=3)
+    if legacy not in _reported:
+        _reported.add(legacy)
+        logger.warning(message)
+
+
+def canonical_key(key):
+    """Current spelling of one option key.
+
+    :param str key: A current or legacy key.
+    :returns: The current spelling; unknown keys are returned unchanged, so
+        that a caller passing an option this version does not know about gets
+        the same "ignored" behaviour as before rather than an error.
+    :rtype: str
+    """
+    if key in LEGACY_KEYS:
+        _report(key)
+        return LEGACY_KEYS[key]
+    return key
+
+
+def canonical_options(mapping):
+    """Rewrite an option mapping onto the current key spellings.
+
+    Applied at the entry of every setter, because a mapping is consumed by
+    iteration and unpacking as often as by lookup.
+
+    :param mapping: Option dictionary, possibly using legacy keys. ``None``
+        is treated as empty.
+    :returns: A new plain :class:`dict` with current keys. A legacy key and
+        its replacement in the same mapping is an error rather than a silent
+        precedence rule.
+    :rtype: dict
+    :raises ValueError: If a key is given under both spellings.
+    """
+    result = {}
+    for key, value in dict(mapping or {}).items():
+        name = canonical_key(key)
+        if name in result:
+            raise ValueError(
+                f"option {name!r} was given twice, once as {key!r}; pass only "
+                f"one spelling"
+            )
+        result[name] = value
+    return result
+
+
+class LegacyKeyDict(dict):
+    """Option dictionary that still answers to the legacy key spellings.
+
+    Returned by the option getters so that existing code and scripts reading
+    ``options["solidAngle"]`` keep working, with a deprecation warning. Only
+    lookup is aliased: iteration, :meth:`keys` and unpacking expose the
+    current names, which is what makes the old spellings disappear from
+    anything that round-trips a whole dictionary.
+    """
+
+    def __getitem__(self, key):
+        return super().__getitem__(canonical_key(key))
+
+    def __contains__(self, key):
+        return super().__contains__(canonical_key(key))
+
+    def get(self, key, default=None):
+        return super().get(canonical_key(key), default)
+
+    def pop(self, key, *default):
+        return super().pop(canonical_key(key), *default)
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index f638ddf..e0fe200 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -1048,14 +1048,14 @@ def intkeys_rocking(self, refldict, **kwargs):
 
         if size_exact is None:
             roioptions = self.scanSelector.roioptions.get_parameters()
-            if roioptions["DetectorInclination"] or roioptions["ProjectSampleSize"]:
-                if roioptions["ProjectSampleSize"]:
+            if roioptions["detector_inclination"] or roioptions["project_sample_size"]:
+                if roioptions["project_sample_size"]:
                     size_exact = ROIutils.calc_corrections(
                         xy,
                         self.ubcalc.detectorCal,
                         np.array([hsize, vsize]),
                         roioptions,
-                        roioptions["DetectorInclination"],
+                        roioptions["detector_inclination"],
                         roioptions["factor"],
                     )
                 else:
@@ -1064,7 +1064,7 @@ def intkeys_rocking(self, refldict, **kwargs):
                         self.ubcalc.detectorCal,
                         np.array([hsize, vsize]),
                         None,
-                        roioptions["DetectorInclination"],
+                        roioptions["detector_inclination"],
                         roioptions["factor"],
                     )
 
@@ -1669,8 +1669,8 @@ def fill_counters(image, pixelavail, key, bkgkey):
         background_image = self.background_image
         has_bg_img = False
         roioptions = self.scanSelector.roioptions.get_parameters()
-        use_fitted_background = bool(roioptions.get("FittedBackground", False))
-        fitted_background_order = int(roioptions.get("FittedBackgroundOrder", 1))
+        use_fitted_background = bool(roioptions.get("fitted_background", False))
+        fitted_background_order = int(roioptions.get("fitted_background_order", 1))
         if use_fitted_background and not HAS_ACCEL:
             logger.warning(
                 "Fitted local background requires the compiled ROI accelerator; "
@@ -4971,7 +4971,7 @@ def _current_preview_mask(self, image_shape):
     def _apply_interpolated_bg_patch(self, image, mask, ckey, bgkeys):
         """Overwrite one center ROI in ``image`` with fitted background."""
         roioptions = self.scanSelector.roioptions.get_parameters()
-        fit_order = int(roioptions.get("FittedBackgroundOrder", 1))
+        fit_order = int(roioptions.get("fitted_background_order", 1))
         patch, stats = _roi_sum_accel.interpolate_polybg_croi(
             image,
             mask,
@@ -5920,8 +5920,8 @@ def integrateROI(self):
 
         has_bg_img = False
         roioptions = self.scanSelector.roioptions.get_parameters()
-        use_fitted_background = bool(roioptions.get("FittedBackground", False))
-        fitted_background_order = int(roioptions.get("FittedBackgroundOrder", 1))
+        use_fitted_background = bool(roioptions.get("fitted_background", False))
+        fitted_background_order = int(roioptions.get("fitted_background_order", 1))
         if use_fitted_background and not HAS_ACCEL:
             logger.warning(
                 "Fitted local background requires the compiled ROI accelerator; "
@@ -6915,15 +6915,15 @@ def intkey(self, coords):
         roioptions = self.scanSelector.roioptions.get_parameters()
         current_mode = self.scanSelector.scanstab.currentIndex()
         if (
-            roioptions["DetectorInclination"] or roioptions["ProjectSampleSize"]
+            roioptions["detector_inclination"] or roioptions["project_sample_size"]
         ) and current_mode != 1:
-            if roioptions["ProjectSampleSize"]:
+            if roioptions["project_sample_size"]:
                 size_exact = ROIutils.calc_corrections(
                     coord_restr,
                     self.ubcalc.detectorCal,
                     np.array([hsize, vsize]),
                     roioptions,
-                    roioptions["DetectorInclination"],
+                    roioptions["detector_inclination"],
                     roioptions["factor"],
                 )
             else:
@@ -6932,7 +6932,7 @@ def intkey(self, coords):
                     self.ubcalc.detectorCal,
                     np.array([hsize, vsize]),
                     None,
-                    roioptions["DetectorInclination"],
+                    roioptions["detector_inclination"],
                     roioptions["factor"],
                 )
             hsize = size_exact[0][0]
diff --git a/orgui/app/test/test_config_data.py b/orgui/app/test/test_config_data.py
index 212e8a2..f6a4e39 100644
--- a/orgui/app/test/test_config_data.py
+++ b/orgui/app/test/test_config_data.py
@@ -158,7 +158,7 @@ def test_enabled_pixel_repair_implies_mask_correction():
         scanSelector=SimpleNamespace(
             get_integration_options=lambda: {
                 "mask": False,
-                "solidAngle": False,
+                "solid_angle": False,
                 "polarization": False,
             }
         ),
diff --git a/orgui/app/test/test_option_keys.py b/orgui/app/test/test_option_keys.py
new file mode 100644
index 0000000..6ef630f
--- /dev/null
+++ b/orgui/app/test/test_option_keys.py
@@ -0,0 +1,113 @@
+"""Regression tests for the option-key deprecation shim.
+
+The integration and region-of-interest option dictionaries are part of the
+scripting surface -- ``startup_setup.py``-style batch scripts write them by
+hand -- so renaming their keys has to keep the old spellings working for a
+deprecation cycle. See :mod:`orgui.app._option_keys`.
+"""
+
+import logging
+import warnings
+
+import pytest
+
+from orgui.app import _option_keys
+from orgui.app._option_keys import (
+    LEGACY_KEYS,
+    LegacyKeyDict,
+    canonical_key,
+    canonical_options,
+)
+
+
+@pytest.fixture(autouse=True)
+def _forget_reported():
+    """Each test sees a fresh once-per-key log state."""
+    _option_keys._reported.clear()
+    yield
+    _option_keys._reported.clear()
+
+
+def test_a_current_key_passes_through_silently():
+    """The common path must not warn, or every run would be noisy."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", DeprecationWarning)
+        assert canonical_key("solid_angle") == "solid_angle"
+        assert canonical_options({"mask": True}) == {"mask": True}
+
+
+def test_a_legacy_key_is_translated_and_warns():
+    """Old scripts keep working, loudly enough to be noticed."""
+    with pytest.deprecated_call():
+        assert canonical_key("solidAngle") == "solid_angle"
+
+
+def test_every_legacy_key_maps_to_a_distinct_current_name():
+    """A mapping collision would silently merge two options."""
+    assert len(set(LEGACY_KEYS.values())) == len(LEGACY_KEYS)
+    # No legacy key may also be a current name, or translation would loop.
+    assert not (set(LEGACY_KEYS) & set(LEGACY_KEYS.values()))
+
+
+def test_an_unknown_key_is_left_alone():
+    """Options this version does not know stay ignored, not fatal.
+
+    ``set_integration_options`` has always skipped keys it has no branch for,
+    which is what lets an older orGUI read a newer configuration.
+    """
+    assert canonical_key("something_new") == "something_new"
+    assert canonical_options({"something_new": 1}) == {"something_new": 1}
+
+
+def test_the_whole_mapping_is_rewritten_on_the_way_in():
+    """Setters consume mappings by iteration, which no alias can intercept."""
+    with pytest.deprecated_call():
+        got = canonical_options(
+            {"solidAngle": True, "sizeX": 5e-4, "mask": False}
+        )
+    assert got == {"solid_angle": True, "sample_size_x": 5e-4, "mask": False}
+    assert list(got) == ["solid_angle", "sample_size_x", "mask"]
+
+
+def test_both_spellings_at_once_is_an_error():
+    """Silently preferring one would hide a real inconsistency."""
+    with pytest.raises(ValueError, match="given twice"):
+        with pytest.deprecated_call():
+            canonical_options({"solidAngle": True, "solid_angle": False})
+
+
+def test_reading_a_legacy_key_off_a_returned_dict_still_works():
+    """Existing consumers index the getter's result directly."""
+    options = LegacyKeyDict({"solid_angle": True, "sample_size_x": 5e-4})
+
+    with pytest.deprecated_call():
+        assert options["solidAngle"] is True
+    with pytest.deprecated_call():
+        assert options.get("sizeX") == 5e-4
+    with pytest.deprecated_call():
+        assert "solidAngle" in options
+    assert options["solid_angle"] is True
+
+
+def test_iterating_a_returned_dict_exposes_only_current_names():
+    """A whole-dictionary round trip must not carry the old names along."""
+    options = LegacyKeyDict({"solid_angle": True})
+
+    assert list(options) == ["solid_angle"]
+    assert list(options.keys()) == ["solid_angle"]
+    assert dict(**options) == {"solid_angle": True}
+
+
+def test_the_log_warns_once_per_key(caplog):
+    """DeprecationWarning is invisible by default; the log is not.
+
+    A scan loop would otherwise emit one record per frame.
+    """
+    with caplog.at_level(logging.WARNING, logger="orgui.app._option_keys"):
+        with pytest.deprecated_call():
+            canonical_key("solidAngle")
+            canonical_key("solidAngle")
+            canonical_key("sizeX")
+
+    records = [r for r in caplog.records if "deprecated" in r.message]
+    assert len(records) == 2, [r.message for r in records]
diff --git a/orgui/app/test/test_reconstruction_dialog.py b/orgui/app/test/test_reconstruction_dialog.py
index df011a9..02fca3e 100644
--- a/orgui/app/test/test_reconstruction_dialog.py
+++ b/orgui/app/test/test_reconstruction_dialog.py
@@ -663,7 +663,7 @@ def test_open_job_restores_all_editable_job_settings(tmp_path, monkeypatch):
     )
     shared_options = {
         "mask": False,
-        "solidAngle": False,
+        "solid_angle": False,
         "polarization": False,
     }
     dialog.orgui.scanSelector = SimpleNamespace(
@@ -684,7 +684,7 @@ def test_open_job_restores_all_editable_job_settings(tmp_path, monkeypatch):
     assert dialog.use_polarization.isChecked()
     assert shared_options == {
         "mask": True,
-        "solidAngle": True,
+        "solid_angle": True,
         "polarization": True,
     }
     assert not dialog.normalize_exposure.isChecked()
@@ -721,7 +721,7 @@ def test_reconstruction_correction_switches_sync_with_integration_options(
     dialog = _dialog(tmp_path)
     shared_options = {
         "mask": True,
-        "solidAngle": False,
+        "solid_angle": False,
         "polarization": True,
         "advanced": {"unchanged": True},
     }
@@ -741,7 +741,7 @@ def test_reconstruction_correction_switches_sync_with_integration_options(
 
     assert shared_options == {
         "mask": True,
-        "solidAngle": True,
+        "solid_angle": True,
         "polarization": False,
         "advanced": {"unchanged": True},
     }

From 7b6e3a2cfc4c3764f416005955f1899966d12acc Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 11 Sep 2026 13:56:55 -0400
Subject: [PATCH 12/33] feat!: store the integration settings in a typed NeXus
 layout

BREAKING CHANGE: integration_corrections is now a group of typed datasets
instead of a single json string. The json dataset is still read, but no
longer written, so post-processing that parses it will not see new files.
---
 orgui/app/config_data.py                      | 310 ++++++++++++++--
 orgui/app/peak1Dintegr.py                     |  22 +-
 orgui/app/test/test_config_nexus_layout.py    | 337 ++++++++++++++++++
 .../test_integration_options_roundtrip.py     | 202 +++++++++++
 orgui/app/test/test_peak1Dintegr.py           |  91 +++++
 5 files changed, 932 insertions(+), 30 deletions(-)
 create mode 100644 orgui/app/test/test_config_nexus_layout.py
 create mode 100644 orgui/app/test/test_integration_options_roundtrip.py

diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index aa7fc35..8b64279 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -31,6 +31,13 @@
 
 SCHEMA_VERSION = 1
 
+#: Layout version of the integration_corrections group. Version 2 is the
+#: typed layout that replaced a single JSON string.
+CORRECTIONS_SCHEMA_VERSION = 2
+
+#: Layout version of the roi_integration group.
+ROI_SCHEMA_VERSION = 1
+
 
 def _json_value(value):
     if isinstance(value, dict):
@@ -58,6 +65,12 @@ class CorrectionState:
     use_background: bool = False
     use_solid_angle: bool = False
     use_polarization: bool = False
+    # Tri-state on purpose: ``None`` is "this configuration predates the
+    # switch being stored", which must leave the GUI as it is rather than
+    # silently turning the correction off.
+    use_lorentz: bool | None = None
+    use_footprint: bool | None = None
+    use_normalization: bool | None = None
     repair_masked_pixels: bool = False
     repair_max_component_pixels: int | None = None
     repair_max_span: int | None = None
@@ -260,6 +273,228 @@ def reflections_from_nxdict(nxdict):
     ]
 
 
+#: Region-of-interest option group -> the unit attributes written beside its
+#: values. Anything absent here is dimensionless.
+_ROI_UNITS = {
+    "region": {"@unit": "px"},
+    "advanced": {"@sample_size_unit": "m", "@offset_unit": "px"},
+    "rocking_scan": {"@unit": "rlu"},
+}
+
+
+def _nx_group(mapping, units=None):
+    """A NeXus subgroup from a flat mapping, skipping ``None`` values."""
+    group = {"@NX_class": "NXcollection"}
+    group.update(units or {})
+    for key, value in mapping.items():
+        if value is None:
+            continue
+        group[key] = value
+    return group
+
+
+def _plain(value):
+    """Strip the numpy and bytes wrappers that HDF5 hands back."""
+    if isinstance(value, bytes):
+        return value.decode()
+    if isinstance(value, np.ndarray):
+        if value.shape == ():
+            return _plain(value[()])
+        return [_plain(item) for item in value]
+    if isinstance(value, np.generic):
+        return value.item()
+    return value
+
+
+def _read_group(nxdict, name):
+    """Values of one subgroup, without its NeXus bookkeeping keys."""
+    group = nxdict.get(name) or {}
+    return {
+        key: _plain(value)
+        for key, value in group.items()
+        if not key.startswith("@")
+    }
+
+
+def corrections_to_nxdict(state):
+    """Serialize a :class:`CorrectionState` as a typed NeXus group.
+
+    Replaces the single opaque JSON string this used to be written as. Every
+    value is its own dataset, so a stored configuration can be read in an
+    HDF5 browser and units can sit beside the numbers that have them.
+
+    ``None`` and empty sequences are written by *omission*: HDF5 has no null,
+    and absence already means "not recorded" to the reader.
+
+    :param CorrectionState state: The state to serialize.
+    :rtype: dict
+    :raises ValueError: If ``uncertainty_provenance`` is not flat.
+    """
+    if any(
+        isinstance(value, (dict, list, tuple))
+        for value in state.uncertainty_provenance.values()
+    ):
+        raise ValueError(
+            "uncertainty_provenance must be a flat mapping of scalars; a "
+            "nested value cannot be written as a NeXus group"
+        )
+    nxdict = {
+        "@NX_class": "NXcollection",
+        "@orgui_schema_version": CORRECTIONS_SCHEMA_VERSION,
+        "switches": _nx_group({
+            "use_mask": state.use_mask,
+            "use_background": state.use_background,
+            "use_solid_angle": state.use_solid_angle,
+            "use_polarization": state.use_polarization,
+            "use_lorentz": state.use_lorentz,
+            "use_footprint": state.use_footprint,
+            "use_normalization": state.use_normalization,
+        }),
+        "normalization": _nx_group(
+            {"normalize_exposure": state.normalize_exposure}
+        ),
+        "pixel_repair": _nx_group({
+            "enabled": state.repair_masked_pixels,
+            "max_component_pixels": state.repair_max_component_pixels,
+            "max_span": state.repair_max_span,
+            "radius": state.repair_radius,
+            "min_valid_neighbors": state.repair_min_valid_neighbors,
+            "use_pyfai_gaps": state.repair_use_pyfai_gaps,
+            "gap_size_px": state.repair_gap_size_px,
+        }),
+        "assets": _nx_group({
+            "mask": state.mask_asset,
+            "background": state.background_asset,
+            "background_variance": state.background_variance_asset,
+        }),
+    }
+    if state.monitor_corrections:
+        nxdict["normalization"]["monitor_corrections"] = _string_array(
+            list(state.monitor_corrections)
+        )
+    if state.excluded_frames:
+        nxdict["excluded_frames"] = np.asarray(
+            state.excluded_frames, dtype=np.int64
+        )
+    if state.uncertainty_provenance:
+        nxdict["uncertainty_provenance"] = _nx_group(
+            dict(state.uncertainty_provenance)
+        )
+    return nxdict
+
+
+def corrections_from_nxdict(nxdict):
+    """Rebuild a :class:`CorrectionState` from its NeXus group.
+
+    Datasets this version does not know are ignored, so a configuration
+    written by a newer orGUI still loads.
+
+    :param dict nxdict: The ``integration_corrections`` group.
+    :rtype: CorrectionState
+    """
+    switches = _read_group(nxdict, "switches")
+    normalization = _read_group(nxdict, "normalization")
+    repair = _read_group(nxdict, "pixel_repair")
+    assets = _read_group(nxdict, "assets")
+    excluded = _plain(nxdict.get("excluded_frames"))
+    values = {
+        "use_mask": bool(switches.get("use_mask", False)),
+        "use_background": bool(switches.get("use_background", False)),
+        "use_solid_angle": bool(switches.get("use_solid_angle", False)),
+        "use_polarization": bool(switches.get("use_polarization", False)),
+        "repair_masked_pixels": bool(repair.get("enabled", False)),
+        "repair_use_pyfai_gaps": bool(repair.get("use_pyfai_gaps", True)),
+        "repair_gap_size_px": int(repair.get("gap_size_px", 1)),
+        "normalize_exposure": bool(
+            normalization.get("normalize_exposure", True)
+        ),
+        # Written with _string_array, i.e. a uint8 matrix, so it needs the
+        # matching reader rather than a plain tuple().
+        "monitor_corrections": tuple(
+            _read_string_array(normalization.get("monitor_corrections", []))
+        ),
+        "excluded_frames": tuple(int(v) for v in (excluded or ())),
+        "uncertainty_provenance": _read_group(nxdict, "uncertainty_provenance"),
+    }
+    for name in ("use_lorentz", "use_footprint", "use_normalization"):
+        if name in switches:
+            values[name] = bool(switches[name])
+    for name, key in (
+        ("repair_max_component_pixels", "max_component_pixels"),
+        ("repair_max_span", "max_span"),
+        ("repair_radius", "radius"),
+        ("repair_min_valid_neighbors", "min_valid_neighbors"),
+    ):
+        if key in repair:
+            values[name] = int(repair[key])
+    for name, key in (
+        ("mask_asset", "mask"),
+        ("background_asset", "background"),
+        ("background_variance_asset", "background_variance"),
+    ):
+        if key in assets:
+            values[name] = str(assets[key])
+    return CorrectionState(**values)
+
+
+def roi_to_nxdict(state):
+    """Serialize a :class:`ROIState` as a typed NeXus group.
+
+    :param ROIState state: The settings to serialize.
+    :rtype: dict
+    """
+    nxdict = {
+        "@NX_class": "NXcollection",
+        "@orgui_schema_version": ROI_SCHEMA_VERSION,
+    }
+    for name in ("region", "advanced", "rocking_scan"):
+        values = getattr(state, name)
+        if values:
+            nxdict[name] = _nx_group(dict(values), _ROI_UNITS[name])
+    return nxdict
+
+
+def roi_from_nxdict(nxdict):
+    """Rebuild a :class:`ROIState` from its NeXus group.
+
+    :param dict nxdict: The ``roi_integration`` group, or ``None`` for a
+        configuration written before these settings were stored.
+    :rtype: ROIState
+    """
+    nxdict = nxdict or {}
+    return ROIState(
+        region=_read_group(nxdict, "region"),
+        advanced=_read_group(nxdict, "advanced"),
+        rocking_scan=_read_group(nxdict, "rocking_scan"),
+    )
+
+
+@dataclass
+class ROIState:
+    """Region-of-interest settings that decide what a scan integrates.
+
+    Held as the same dictionaries :class:`~orgui.app.QScanSelector.QScanSelector`
+    already speaks, so a new control in the options dialog reaches the file
+    without a change here. The NeXus layout below is typed and carries units;
+    this is only the carrier.
+
+    An empty dictionary means "not recorded", which is what every
+    configuration written before these settings were stored looks like.
+    """
+
+    #: Nominal sizes and the automatic-sizing switches, pixels.
+    region: dict = field(default_factory=dict)
+    #: The advanced options dialog: sample size in meter, offsets in pixels.
+    advanced: dict = field(default_factory=dict)
+    #: Rocking-scan ``s`` sampling, r.l.u. ``delta_s`` is the effective value
+    #: after the resolution clipping of ``onRoSChanged``, not what was typed.
+    rocking_scan: dict = field(default_factory=dict)
+
+    def is_empty(self):
+        """True when nothing was recorded, so nothing should be restored."""
+        return not (self.region or self.advanced or self.rocking_scan)
+
+
 @dataclass
 class ConfigData:
     """Physical application state persisted with scans and integrations."""
@@ -281,6 +516,7 @@ class ConfigData:
     refraction_index: float = 1.0
     reference_reflections: list = field(default_factory=list)
     corrections: CorrectionState = field(default_factory=CorrectionState)
+    roi: ROIState = field(default_factory=ROIState)
     orgui: dict = field(default_factory=dict)
 
     @classmethod
@@ -369,6 +605,7 @@ def from_gui(cls, gui):
         ub_calculator = HKLVlieg.UBCalculator(cell, ub_widget.ubCal.getEnergy())
         ub_calculator.setU(ub_widget.ubCal.getU())
         corrections = CorrectionState()
+        roi = ROIState()
         if hasattr(gui, "scanSelector"):
             options = gui.scanSelector.get_integration_options()
             repair = getattr(getattr(gui, "maskManager", None), "settings", None)
@@ -380,8 +617,11 @@ def from_gui(cls, gui):
                 use_mask=bool(options.get("mask", False)) or repair_enabled,
                 use_background=getattr(gui, "background_image", None)
                 is not None,
-                use_solid_angle=bool(options.get("solidAngle", False)),
+                use_solid_angle=bool(options.get("solid_angle", False)),
                 use_polarization=bool(options.get("polarization", False)),
+                use_lorentz=bool(options.get("lorentz", False)),
+                use_footprint=bool(options.get("footprint", False)),
+                use_normalization=bool(options.get("normalization", False)),
                 repair_masked_pixels=repair_enabled,
                 repair_max_component_pixels=getattr(
                     repair, "max_component_pixels", None
@@ -411,6 +651,11 @@ def from_gui(cls, gui):
                     )
                 ),
             )
+            roi = ROIState(
+                region=dict(options.get("region", {})),
+                advanced=dict(options.get("advanced", {})),
+                rocking_scan=dict(options.get("rocking_scan", {})),
+            )
         return cls(
             detector=ub_widget.detectorCal,
             unit_cell=cell,
@@ -424,6 +669,7 @@ def from_gui(cls, gui):
             refraction_index=getattr(ub_widget, "n", 1.0),
             reference_reflections=reflections,
             corrections=corrections,
+            roi=roi,
         )
 
     def apply_to_gui(self, gui):
@@ -461,13 +707,26 @@ def apply_to_gui(self, gui):
         if hasattr(gui, "reflectionSel"):
             gui.reflectionSel.setReflections(self.reference_reflections)
         if hasattr(gui, "scanSelector"):
-            gui.scanSelector.set_integration_options(
-                {
-                    "mask": self.corrections.use_mask,
-                    "solidAngle": self.corrections.use_solid_angle,
-                    "polarization": self.corrections.use_polarization,
-                }
-            )
+            options = {
+                "mask": self.corrections.use_mask,
+                "solid_angle": self.corrections.use_solid_angle,
+                "polarization": self.corrections.use_polarization,
+            }
+            # Only switches this configuration actually recorded. A file
+            # written before they were stored leaves them as the user has
+            # them, rather than silently turning a correction off.
+            for name, value in (
+                ("lorentz", self.corrections.use_lorentz),
+                ("footprint", self.corrections.use_footprint),
+                ("normalization", self.corrections.use_normalization),
+            ):
+                if value is not None:
+                    options[name] = value
+            for name in ("region", "advanced", "rocking_scan"):
+                values = getattr(self.roi, name)
+                if values:
+                    options[name] = dict(values)
+            gui.scanSelector.set_integration_options(options)
         gui.reconstruction_normalize_exposure = self.corrections.normalize_exposure
         gui.reconstruction_monitor_corrections = self.corrections.monitor_corrections
         if (
@@ -541,12 +800,10 @@ def to_nxdict(self, role="scan", source=None):
                     "@wavelength_unit": "Angstrom",
                 },
                 "refraction_index": self.refraction_index,
-                "integration_corrections": {
-                    "@NX_class": "NXcollection",
-                    "json": json.dumps(
-                        self.corrections.to_dict(), sort_keys=True
-                    ),
-                },
+                "integration_corrections": corrections_to_nxdict(
+                    self.corrections
+                ),
+                "roi_integration": roi_to_nxdict(self.roi),
                 **self.orgui,
             },
         }
@@ -566,16 +823,18 @@ def from_nxdict(cls, nxdict):
         ub_calculator = HKLVlieg.UBCalculator(unit_cell, energy)
         ub_calculator.setU(np.asarray(nxdict["sample"]["orientation_matrix"]))
         diffrac = nxdict.get("orgui", {}).get("diffractometer", {})
-        correction_json = (
-            nxdict.get("orgui", {})
-            .get("integration_corrections", {})
-            .get("json", "{}")
-        )
-        correction_json = np.asarray(correction_json)
-        if correction_json.shape == ():
-            correction_json = correction_json.item()
-        if isinstance(correction_json, bytes):
-            correction_json = correction_json.decode()
+        corrections_group = nxdict.get("orgui", {}).get(
+            "integration_corrections", {}
+        ) or {}
+        if "json" in corrections_group:
+            # Configurations written before the typed layout. Still read, so
+            # that existing databases keep loading; never written any more.
+            corrections = CorrectionState.from_dict(
+                json.loads(_as_text(_plain(corrections_group["json"])) or "{}")
+            )
+        else:
+            corrections = corrections_from_nxdict(corrections_group)
+        roi = roi_from_nxdict(nxdict.get("orgui", {}).get("roi_integration"))
         return cls(
             detector=detector,
             unit_cell=unit_cell,
@@ -590,7 +849,8 @@ def from_nxdict(cls, nxdict):
                 nxdict.get("orgui", {}).get("refraction_index", 1.0)
             ),
             reference_reflections=reflections_from_nxdict(nxdict),
-            corrections=CorrectionState.from_dict(json.loads(correction_json)),
+            corrections=corrections,
+            roi=roi,
         )
 
     def to_json_dict(self) -> dict[str, Any]:
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 9421173..af4979a 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -55,7 +55,12 @@
 import traceback
 
 from . import qutils
-from .config_data import ConfigData, detector_from_nxdict
+from .config_data import (
+    ConfigData,
+    CorrectionState,
+    corrections_from_nxdict,
+    detector_from_nxdict,
+)
 from .. import resources
 from .. import logger_utils
 from ..datautils.xrayutils.corrections import beamprofile
@@ -1489,11 +1494,18 @@ def _rocking_solid_angle_mean(self, detector, scangroup, cnters, x, y):
             be established.
         :rtype: tuple
         """
+        path = scangroup.name + "/configuration/orgui/integration_corrections"
         try:
-            raw = scangroup["configuration/orgui/integration_corrections/json"][()]
-            if isinstance(raw, bytes):
-                raw = raw.decode()
-            was_applied = bool(json.loads(str(raw)).get("use_solid_angle", False))
+            group = h5todict(self.database.nxfile, path)
+            if "json" in group:
+                # Configurations written before the typed layout.
+                raw = group["json"]
+                if isinstance(raw, bytes):
+                    raw = raw.decode()
+                state = CorrectionState.from_dict(json.loads(str(raw)))
+            else:
+                state = corrections_from_nxdict(group)
+            was_applied = bool(state.use_solid_angle)
         except Exception:
             logger.warning(
                 "Cannot tell from this scan's stored configuration whether the "
diff --git a/orgui/app/test/test_config_nexus_layout.py b/orgui/app/test/test_config_nexus_layout.py
new file mode 100644
index 0000000..0d567a5
--- /dev/null
+++ b/orgui/app/test/test_config_nexus_layout.py
@@ -0,0 +1,337 @@
+"""Round-trip tests for the typed NeXus layout of the stored settings.
+
+The integration corrections used to be persisted as one opaque JSON string,
+and the region-of-interest settings -- the advanced options, the ``s``
+sampling and the automatic-sizing switches -- were not persisted at all. A
+saved dataset was therefore not reproducible: reloading its configuration
+restored three of the seven correction switches and none of the region
+settings.
+
+These tests pin the replacement: every field of :class:`CorrectionState` and
+every region-of-interest setting survives
+``state -> NeXus dict -> HDF5 file -> NeXus dict -> state``, and a
+configuration written before the change still loads.
+"""
+
+import dataclasses
+import json
+
+import numpy as np
+import pytest
+from silx.io.dictdump import dicttonx, nxtodict
+
+from orgui.app.config_data import (
+    CORRECTIONS_SCHEMA_VERSION,
+    CorrectionState,
+    ROIState,
+    corrections_from_nxdict,
+    corrections_to_nxdict,
+    roi_from_nxdict,
+    roi_to_nxdict,
+)
+
+
+def _through_file(nxdict, tmp_path, name="group"):
+    """Write one group to HDF5 and read it back, as a database would."""
+    path = tmp_path / f"{name}.h5"
+    dicttonx({name: nxdict}, path)
+    return nxtodict(path)[name]
+
+
+def _populated_corrections():
+    """A correction state with every field away from its default."""
+    return CorrectionState(
+        use_mask=True,
+        use_background=True,
+        use_solid_angle=True,
+        use_polarization=True,
+        use_lorentz=True,
+        use_footprint=True,
+        use_normalization=False,
+        repair_masked_pixels=True,
+        repair_max_component_pixels=4,
+        repair_max_span=3,
+        repair_radius=2,
+        repair_min_valid_neighbors=6,
+        repair_use_pyfai_gaps=False,
+        repair_gap_size_px=6,
+        normalize_exposure=False,
+        monitor_corrections=("mondio", "ic1"),
+        excluded_frames=(3, 7, 11),
+        mask_asset="assets/mask",
+        background_asset="assets/bg",
+        background_variance_asset="assets/bgvar",
+        uncertainty_provenance={"background": "measured"},
+    )
+
+
+def test_every_correction_field_is_covered_by_the_layout():
+    """Adding a field to the dataclass must not silently stop being saved.
+
+    This is the guard that makes the round-trip test below meaningful: it
+    fails when a new field is added to :class:`CorrectionState` and left out
+    of the test fixture, rather than the field quietly never being written.
+    """
+    populated = _populated_corrections()
+    default = CorrectionState()
+    unexercised = [
+        entry.name
+        for entry in dataclasses.fields(CorrectionState)
+        if getattr(populated, entry.name) == getattr(default, entry.name)
+    ]
+    assert not unexercised, (
+        f"these CorrectionState fields are still at their default in the "
+        f"round-trip fixture, so the test would not notice them being "
+        f"dropped: {unexercised}"
+    )
+
+
+def test_a_fully_populated_correction_state_round_trips(tmp_path):
+    """Every field survives state -> NeXus -> file -> NeXus -> state."""
+    state = _populated_corrections()
+
+    loaded = corrections_from_nxdict(
+        _through_file(corrections_to_nxdict(state), tmp_path, "corrections")
+    )
+
+    assert loaded == state
+
+
+def test_a_default_correction_state_round_trips(tmp_path):
+    """The all-defaults case, where most datasets are absent entirely.
+
+    ``None`` and empty sequences are encoded by omission, so this is the
+    path where the reader has to supply the defaults itself.
+    """
+    state = CorrectionState()
+    nxdict = corrections_to_nxdict(state)
+
+    # The optional values must genuinely not be in the file.
+    assert "excluded_frames" not in nxdict
+    assert "monitor_corrections" not in nxdict["normalization"]
+    assert "max_span" not in nxdict["pixel_repair"]
+    assert "use_lorentz" not in nxdict["switches"]
+    assert nxdict["assets"] == {"@NX_class": "NXcollection"}
+
+    loaded = corrections_from_nxdict(
+        _through_file(nxdict, tmp_path, "corrections")
+    )
+    assert loaded == state
+
+
+def test_the_unrecorded_switches_stay_none(tmp_path):
+    """``None`` must not collapse to ``False`` on the way through a file.
+
+    It is the difference between "this configuration says the Lorentz
+    correction was off" and "this configuration predates the switch being
+    stored", and only the first may change a loaded GUI.
+    """
+    loaded = corrections_from_nxdict(
+        _through_file(corrections_to_nxdict(CorrectionState()), tmp_path)
+    )
+
+    assert loaded.use_lorentz is None
+    assert loaded.use_footprint is None
+    assert loaded.use_normalization is None
+
+
+def test_a_nested_uncertainty_provenance_is_refused():
+    """Rather than silently reintroducing a serialized blob."""
+    state = CorrectionState(uncertainty_provenance={"a": {"b": 1}})
+
+    with pytest.raises(ValueError, match="flat mapping"):
+        corrections_to_nxdict(state)
+
+
+def test_unknown_datasets_are_ignored(tmp_path):
+    """A configuration from a newer orGUI still loads."""
+    nxdict = corrections_to_nxdict(CorrectionState(use_mask=True))
+    nxdict["switches"]["use_something_new"] = True
+    nxdict["a_whole_new_group"] = {"@NX_class": "NXcollection", "value": 1}
+
+    loaded = corrections_from_nxdict(_through_file(nxdict, tmp_path))
+
+    assert loaded.use_mask is True
+
+
+def test_the_layout_is_browsable_and_versioned(tmp_path):
+    """The point of replacing the JSON string: values are real datasets."""
+    nxdict = _through_file(
+        corrections_to_nxdict(_populated_corrections()), tmp_path
+    )
+
+    assert nxdict["@orgui_schema_version"] == CORRECTIONS_SCHEMA_VERSION
+    assert "json" not in nxdict
+    assert bool(nxdict["switches"]["use_solid_angle"]) is True
+    assert int(nxdict["pixel_repair"]["radius"]) == 2
+    assert np.array_equal(np.asarray(nxdict["excluded_frames"]), [3, 7, 11])
+
+
+def test_a_legacy_json_configuration_still_reads():
+    """Existing databases must keep loading; only writing changed."""
+    legacy = CorrectionState(
+        use_mask=True, use_solid_angle=True, monitor_corrections=("mondio",)
+    )
+    group = {
+        "@NX_class": "NXcollection",
+        "json": json.dumps(legacy.to_dict(), sort_keys=True),
+    }
+
+    # The reader branch ConfigData.from_nxdict takes for such a file.
+    loaded = CorrectionState.from_dict(json.loads(group["json"]))
+
+    assert loaded.use_mask is True
+    assert loaded.use_solid_angle is True
+    assert loaded.monitor_corrections == ("mondio",)
+    assert loaded.use_lorentz is None
+
+
+def test_the_region_of_interest_settings_round_trip(tmp_path):
+    """Advanced options, region sizes and s sampling all survive."""
+    state = ROIState(
+        region={
+            "hsize": 20.0,
+            "vsize": 6.0,
+            "left": 20.0,
+            "right": 20.0,
+            "top": 5.0,
+            "bottom": 5.0,
+            "auto_hsize": True,
+            "auto_vsize": False,
+        },
+        advanced={
+            "detector_inclination": True,
+            "project_sample_size": True,
+            "offset_x": 1.5,
+            "offset_y": -2.5,
+            "sample_size_x": 5e-4,
+            "sample_size_y": 7e-3,
+            "sample_size_z": 5e-3,
+            "factor": 1.25,
+            "fitted_background": True,
+            "fitted_background_order": 2,
+        },
+        rocking_scan={"delta_s": 0.0019001086, "max_s": 5.0},
+    )
+
+    loaded = roi_from_nxdict(_through_file(roi_to_nxdict(state), tmp_path, "roi"))
+
+    assert loaded.region == pytest.approx(state.region)
+    assert loaded.advanced == pytest.approx(state.advanced)
+    assert loaded.rocking_scan == pytest.approx(state.rocking_scan)
+    # delta_s is the value the auto-pinning settled on, to full precision.
+    assert loaded.rocking_scan["delta_s"] == pytest.approx(
+        0.0019001086, rel=0, abs=1e-12
+    )
+
+
+def test_the_region_of_interest_units_are_recorded(tmp_path):
+    """A reader should not have to guess metres from pixels."""
+    state = ROIState(
+        region={"hsize": 20.0},
+        advanced={"sample_size_x": 5e-4, "offset_x": 1.0},
+        rocking_scan={"delta_s": 0.002},
+    )
+
+    nxdict = roi_to_nxdict(state)
+
+    assert nxdict["region"]["@unit"] == "px"
+    assert nxdict["advanced"]["@sample_size_unit"] == "m"
+    assert nxdict["advanced"]["@offset_unit"] == "px"
+    assert nxdict["rocking_scan"]["@unit"] == "rlu"
+
+
+def test_an_absent_region_group_is_empty_not_fatal():
+    """Every configuration written before this change has no such group."""
+    state = roi_from_nxdict(None)
+
+    assert state.is_empty()
+    assert state.region == {}
+    assert roi_to_nxdict(state) == {
+        "@NX_class": "NXcollection",
+        "@orgui_schema_version": 1,
+    }
+
+
+def _fake_gui(options, captured):
+    """A stand-in exposing only what ConfigData reads and writes."""
+    from types import SimpleNamespace
+
+    from orgui.datautils.xrayutils import CTRcalc, DetectorCalibration, HKLVlieg
+
+    cell = CTRcalc.UnitCell([3.0, 3.0, 5.0], [90.0, 90.0, 90.0], name="bulk")
+    ub = HKLVlieg.UBCalculator(cell, 15.0)
+    ub.defaultU_GID()
+    return SimpleNamespace(
+        ubcalc=SimpleNamespace(
+            detectorCal=DetectorCalibration.Detector2D_SXRD(),
+            crystal=cell,
+            ubCal=ub,
+            mu=0.0,
+            chi=0.0,
+            phi=0.0,
+            n=1.0,
+        ),
+        scanSelector=SimpleNamespace(
+            get_integration_options=lambda: dict(options),
+            set_integration_options=captured.update,
+        ),
+    )
+
+
+def test_the_gui_switches_and_region_settings_survive_from_gui_to_apply():
+    """Closes the gap: reloading restored 3 of 7 switches and no region.
+
+    ``from_gui`` must collect every switch and the region settings, and
+    ``apply_to_gui`` must put them all back.
+    """
+    from orgui.app.config_data import ConfigData
+
+    options = {
+        "mask": True,
+        "solid_angle": True,
+        "polarization": True,
+        "lorentz": True,
+        "footprint": True,
+        "normalization": True,
+        "region": {"hsize": 21.0, "auto_vsize": True},
+        "advanced": {"detector_inclination": True, "sample_size_x": 5e-4},
+        "rocking_scan": {"delta_s": 0.0019, "max_s": 5.0},
+    }
+    captured = {}
+    config = ConfigData.from_gui(_fake_gui(options, captured))
+
+    assert config.corrections.use_lorentz is True
+    assert config.corrections.use_footprint is True
+    assert config.corrections.use_normalization is True
+    assert config.roi.region["hsize"] == 21.0
+    assert config.roi.rocking_scan["delta_s"] == pytest.approx(0.0019)
+
+    config.apply_to_gui(_fake_gui(options, captured))
+
+    for name in ("mask", "solid_angle", "polarization",
+                 "lorentz", "footprint", "normalization"):
+        assert captured[name] is True, name
+    assert captured["region"]["hsize"] == 21.0
+    assert captured["advanced"]["sample_size_x"] == pytest.approx(5e-4)
+    assert captured["rocking_scan"]["max_s"] == 5.0
+
+
+def test_an_old_configuration_does_not_touch_the_unrecorded_switches():
+    """A file predating the switches must leave the GUI as the user has it."""
+    from orgui.app.config_data import ConfigData
+
+    captured = {}
+    config = ConfigData.from_gui(_fake_gui({"mask": True}, captured))
+    config.corrections.use_lorentz = None
+    config.corrections.use_footprint = None
+    config.corrections.use_normalization = None
+    config.roi = ROIState()
+
+    captured.clear()
+    config.apply_to_gui(_fake_gui({}, captured))
+
+    assert "lorentz" not in captured
+    assert "footprint" not in captured
+    assert "normalization" not in captured
+    assert "region" not in captured
diff --git a/orgui/app/test/test_integration_options_roundtrip.py b/orgui/app/test/test_integration_options_roundtrip.py
new file mode 100644
index 0000000..c2126e3
--- /dev/null
+++ b/orgui/app/test/test_integration_options_roundtrip.py
@@ -0,0 +1,202 @@
+"""The integration settings must survive a save and a reload, in full.
+
+Before the typed NeXus layout, reloading a configuration restored three of
+the seven correction switches and none of the region-of-interest settings, so
+a saved dataset could not be reproduced from what was stored with it. These
+tests drive the real :class:`~orgui.app.QScanSelector.QScanSelector` widgets
+rather than a stand-in, because the gap was in the wiring between the widgets
+and :class:`~orgui.app.config_data.ConfigData`, not in either alone.
+"""
+
+import numpy as np
+import pytest
+from silx.gui import qt
+
+from orgui.app.config_data import ROIState, roi_from_nxdict, roi_to_nxdict
+from orgui.app.QScanSelector import QScanSelector
+
+
+@pytest.fixture(scope="module")
+def qapp():
+    application = qt.QApplication.instance()
+    if application is None:
+        application = qt.QApplication([])
+    return application
+
+
+class _StubMainWindow(qt.QMainWindow):
+    """The smallest parent a selector will build against.
+
+    ``QScanSelector.__init__`` reads two attributes off its parent -- the
+    plot the alpha slider drives and the current image legend -- and also
+    passes it to child dialogs as a Qt parent, so it has to be a real
+    widget rather than a namespace.
+    """
+
+    def __init__(self):
+        super().__init__()
+        from silx.gui.plot import Plot2D
+
+        self.centralPlot = Plot2D(parent=self)
+        self.currentAddImageLabel = "image"
+
+
+def _make_selector():
+    parent = _StubMainWindow()
+    selector = QScanSelector(parent)
+    # Keep the parent alive for as long as the selector needs it.
+    selector._test_parent = parent
+    return selector
+
+
+@pytest.fixture
+def selector(qapp):
+    widget = _make_selector()
+    yield widget
+    widget.deleteLater()
+
+
+#: Every switch off its default, so a dropped one is visible.
+SWITCHES = {
+    "mask": True,
+    "solid_angle": True,
+    "polarization": True,
+    "lorentz": True,
+    "footprint": True,
+    "normalization": True,
+}
+
+REGION = {
+    "hsize": 21.0,
+    "vsize": 7.0,
+    "left": 19.0,
+    "right": 18.0,
+    "top": 4.0,
+    "bottom": 3.0,
+    "auto_hsize": True,
+    "auto_vsize": True,
+}
+
+ADVANCED = {
+    "detector_inclination": True,
+    "project_sample_size": True,
+    "offset_x": 1.5,
+    "offset_y": -2.5,
+    "sample_size_x": 5e-4,
+    "sample_size_y": 7e-3,
+    "sample_size_z": 5e-3,
+    "factor": 1.25,
+    "fitted_background": True,
+    "fitted_background_order": 2,
+}
+
+ROCKING = {"delta_s": 0.0019, "max_s": 5.0}
+
+
+def test_every_setting_round_trips_through_the_widgets(selector):
+    """Set everything, read it back, get the same thing."""
+    selector.set_integration_options({
+        **SWITCHES,
+        "region": REGION,
+        "advanced": ADVANCED,
+        "rocking_scan": ROCKING,
+    })
+
+    options = selector.get_integration_options()
+
+    for name, value in SWITCHES.items():
+        assert options[name] == value, name
+    assert options["region"] == pytest.approx(REGION)
+    assert options["advanced"] == pytest.approx(ADVANCED)
+    assert options["rocking_scan"] == pytest.approx(ROCKING)
+
+
+def test_restoring_delta_s_does_not_re_clip_it(selector):
+    """The stored value is already the resolution-clipped one.
+
+    Assigning it normally triggers ``onRoSChanged``, which solves for the
+    step that keeps rod points one pixel apart and writes the result back.
+    Re-running that against whatever scan is loaded would not restore what
+    was saved, so the setter blocks it.
+    """
+    selector.set_integration_options({"rocking_scan": {"delta_s": 0.0019}})
+
+    assert selector.roscanDeltaS.value() == pytest.approx(0.0019)
+
+
+def test_the_settings_survive_a_nexus_group(selector, tmp_path):
+    """Widgets -> ROIState -> NeXus -> ROIState -> widgets is the identity."""
+    from silx.io.dictdump import dicttonx, nxtodict
+
+    selector.set_integration_options({
+        "region": REGION, "advanced": ADVANCED, "rocking_scan": ROCKING,
+    })
+    options = selector.get_integration_options()
+    state = ROIState(
+        region=dict(options["region"]),
+        advanced=dict(options["advanced"]),
+        rocking_scan=dict(options["rocking_scan"]),
+    )
+
+    path = tmp_path / "roi.h5"
+    dicttonx({"roi": roi_to_nxdict(state)}, path)
+    restored = roi_from_nxdict(nxtodict(path)["roi"])
+
+    fresh = _make_selector()
+    try:
+        fresh.set_integration_options({
+            "region": restored.region,
+            "advanced": restored.advanced,
+            "rocking_scan": restored.rocking_scan,
+        })
+        after = fresh.get_integration_options()
+    finally:
+        fresh.deleteLater()
+
+    assert after["region"] == pytest.approx(options["region"])
+    assert after["advanced"] == pytest.approx(options["advanced"])
+    assert after["rocking_scan"] == pytest.approx(options["rocking_scan"])
+
+
+def test_a_legacy_option_dictionary_is_still_accepted(selector):
+    """``startup_setup.py``-style scripts keep working for a cycle."""
+    with pytest.deprecated_call():
+        selector.set_integration_options({
+            "solidAngle": True,
+            "advanced": {
+                "DetectorInclination": True,
+                "ProjectSampleSize": True,
+                "xoffset": 0.0,
+                "yoffset": 0.0,
+                "sizeX": 5e-4,
+                "sizeY": 7e-3,
+                "sizeZ": 5e-3,
+                "factor": 1.0,
+            },
+        })
+
+    options = selector.get_integration_options()
+    assert options["solid_angle"] is True
+    assert options["advanced"]["detector_inclination"] is True
+    assert options["advanced"]["sample_size_y"] == pytest.approx(7e-3)
+    # and the legacy spelling still reads off the result, with a warning
+    with pytest.deprecated_call():
+        assert options["solidAngle"] is True
+
+
+def test_an_unknown_option_is_ignored(selector):
+    """What lets an older orGUI open a newer configuration."""
+    selector.set_integration_options({"mask": True, "from_the_future": 1})
+
+    assert selector.get_integration_options()["mask"] is True
+
+
+def test_sample_sizes_are_stored_in_meter(selector):
+    """The widgets show micrometer; the dictionary and the file use meter."""
+    selector.set_integration_options({"advanced": {**ADVANCED,
+                                                   "sample_size_y": 7e-3}})
+
+    assert selector.get_integration_options()["advanced"][
+        "sample_size_y"
+    ] == pytest.approx(7e-3)
+    assert np.isclose(selector.roioptions._sizeYsample.value(), 7000.0)
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index 1b3d033..0964521 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -581,3 +581,94 @@ def test_a_scan_without_a_stored_detector_gives_none():
             assert RockingPeakIntegrator._stored_detector(
                 integrator, handle["/61.1"]
             ) is None
+
+
+def _scan_with_corrections(folder, corrections_group):
+    """Write one scan whose stored configuration holds ``corrections_group``."""
+    from silx.io.dictdump import dicttonx
+
+    path = os.path.join(folder, "scan.h5")
+    dicttonx(
+        {"configuration": {"orgui": {
+            "integration_corrections": corrections_group}}},
+        path,
+        h5path="/61.1",
+        update_mode="add",
+    )
+    return path
+
+
+def _solid_angle_detector():
+    """A calibrated geometry the solid-angle correction can be measured on."""
+    pyFAI = pytest.importorskip("pyFAI")
+    from orgui.datautils.xrayutils import DetectorCalibration
+
+    detector = DetectorCalibration.Detector2D_SXRD()
+    detector.detector = pyFAI.detectors.Detector(
+        pixel1=172e-6, pixel2=172e-6, max_shape=(619, 487)
+    )
+    detector.dist = 0.5
+    detector.poni1, detector.poni2 = 0.05, 0.04
+    detector.rot1 = detector.rot2 = detector.rot3 = 0.0
+    detector.set_energy(15.0)
+    return detector
+
+
+@pytest.mark.parametrize("applied_at_extraction", [True, False])
+def test_the_typed_corrections_group_is_read_back(applied_at_extraction):
+    """The F6 compensation must survive the layout it is stored in.
+
+    Whether the solid-angle correction was applied to the intensity is read
+    from the configuration written at extraction time. When that group
+    changed from a single JSON string to typed datasets, this reader kept
+    parsing the JSON and silently stopped compensating -- the unit tests
+    passed because the layout and the reduction were only ever tested apart.
+    So this writes the group with the *current* writer and reads it back
+    through the reducer.
+    """
+    from orgui.app.config_data import CorrectionState, corrections_to_nxdict
+
+    detector = _solid_angle_detector()
+    state = CorrectionState(use_solid_angle=applied_at_extraction)
+    cnters = {"hsize": np.full(3, 20.0), "vsize": np.full(3, 5.0)}
+
+    with tempfile.TemporaryDirectory() as folder:
+        path = _scan_with_corrections(folder, corrections_to_nxdict(state))
+        with h5py.File(path, "r") as handle:
+            integrator = SimpleNamespace(
+                database=SimpleNamespace(nxfile=handle, config_target=None)
+            )
+            mean, compensated = RockingPeakIntegrator._rocking_solid_angle_mean(
+                integrator, detector, handle["/61.1"], cnters,
+                x=np.full(3, 240.0), y=np.full(3, 300.0),
+            )
+
+    assert compensated is applied_at_extraction
+    if applied_at_extraction:
+        assert mean is not None
+        assert np.all(np.isfinite(mean)) and np.all(mean > 0.0)
+    else:
+        assert mean is None
+
+
+def test_a_legacy_json_corrections_group_is_still_read():
+    """Databases written before the typed layout must keep reducing."""
+    import json
+
+    detector = _solid_angle_detector()
+    cnters = {"hsize": np.full(2, 20.0), "vsize": np.full(2, 5.0)}
+    legacy = {"json": json.dumps({"use_solid_angle": True})}
+
+    with tempfile.TemporaryDirectory() as folder:
+        path = _scan_with_corrections(folder, legacy)
+        with h5py.File(path, "r") as handle:
+            integrator = SimpleNamespace(
+                database=SimpleNamespace(nxfile=handle, config_target=None)
+            )
+            mean, compensated = RockingPeakIntegrator._rocking_solid_angle_mean(
+                integrator, detector, handle["/61.1"], cnters,
+                x=np.full(2, 240.0), y=np.full(2, 300.0),
+            )
+
+    assert compensated is True
+    assert mean is not None and np.all(mean > 0.0)

From f025b73dd62d432853631869c882afd24f3dbf4e Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 11 Sep 2026 13:57:01 -0400
Subject: [PATCH 13/33] feat(phys): record C_solid_angle with the integrated
 intensities

---
 orgui/app/orGUI.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index e0fe200..08cc7b9 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -6711,6 +6711,10 @@ def sumImage(i):
                 "C_flux_on_sample": factors1.get("C_flux_on_sample"),
                 "C_illum_area": factors1.get("C_illum_area"),
                 "C_norm": factors1.get("C_norm"),
+                # Divided back out of F2_hkl rather than applied to it
+                # (finding F6); recorded so a saved rod can be put
+                # back on the intensity scale.
+                "C_solid_angle": factors1.get("C_solid_angle"),
             },
             "pixelcoord": {
                 "@NX_class": "NXdetector",
@@ -6771,6 +6775,10 @@ def sumImage(i):
                 "C_flux_on_sample": factors2.get("C_flux_on_sample"),
                 "C_illum_area": factors2.get("C_illum_area"),
                 "C_norm": factors2.get("C_norm"),
+                # Divided back out of F2_hkl rather than applied to it
+                # (finding F6); recorded so a saved rod can be put
+                # back on the intensity scale.
+                "C_solid_angle": factors2.get("C_solid_angle"),
             },
             "pixelcoord": {
                 "@NX_class": "NXdetector",

From 68998fcb137cf5c509e69bb62493430b5f4cfea7 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 11 Sep 2026 16:59:42 -0400
Subject: [PATCH 14/33] docs: record the real-data validation and the stored
 integration settings

---
 CHANGELOG.md                                |  50 ++++++++
 doc/design/ctr_structure_factor_handover.md |  48 ++++++--
 doc/design/ctr_structure_factor_scale.md    | 128 +++++++++++++++++---
 doc/source/release_notes.rst                |  10 +-
 orgui/app/config_data.py                    |   8 +-
 5 files changed, 218 insertions(+), 26 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 901d048..71ac0e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -68,6 +68,32 @@ Scientific and analysis additions:
   a backend that declares ``exposure_time`` in ``auxillary_counters``; a
   missing counter is skipped and recorded rather than failing the integration.
   Existing configuration files load unchanged.
+  This equivalence has now been checked on real data as well as in simulation:
+  on a LaNiO3 rod measured both ways, the two modes agree to a median 1.03
+  along the rod, with the remaining spread explained by the resolution
+  difference between them rather than by a normalization. At a Bragg peak on
+  the same rod they differ by a factor of five, which is expected — a
+  stationary region cannot collect a peak much wider than itself.
+
+- **The settings that decide what was integrated are now stored with every
+  integration.** A reduction could previously not be reproduced from its own
+  output: the background ROI margins, the automatic-sizing switches, the
+  projected sample size, and the effective ``delta_s`` of a rocking scan were
+  not written anywhere. They are now saved under
+  ``configuration/orgui/roi_integration`` as typed groups carrying their
+  units — ``region`` (sizes, margins, automatic sizing), ``advanced`` (sample
+  size in meter, offsets, the inclination and projection switches) and
+  ``rocking_scan`` (``delta_s`` and ``max_s``, with ``delta_s`` stored as the
+  value actually used after the resolution clipping, not as typed). The
+  correction switches move the same way: ``integration_corrections`` is now a
+  group of typed datasets instead of one opaque JSON string, so a stored
+  configuration can be read in any HDF5 browser. Databases written with the
+  JSON layout are still read. The Lorentz, footprint and normalization
+  switches are recorded alongside the others, and a configuration that predates
+  them leaves those controls as the user has them rather than silently
+  switching a correction off. ``C_solid_angle`` is now saved beside
+  ``F2_hkl``, because the structure factor divides it back out and a saved rod
+  cannot otherwise be returned to the intensity scale.
 
 - **All correction factors collected into one package.** Every factor between
   detector counts and a structure factor now lives in
@@ -742,6 +768,30 @@ A ***critical bug*** was fixed that affects bulk CTR calculations:
   exposure bounds already read each segment's own arm, and they now agree with
   the arm the rest of the program sees.
 
+- **Reducing a rocking scan now uses the detector geometry stored with that
+  scan**, instead of whatever calibration the application happens to hold.
+  *This changes saved numbers for any reduction run against a different
+  calibration than the one the curves were extracted with.* The out-of-plane
+  acceptance and the solid-angle compensation are properties of the geometry
+  the data was taken with, so reducing from a script that has not loaded the
+  matching configuration, or after another calibration was opened, silently
+  produced a wrongly scaled ``F2_hkl``: on a real scan it scaled every
+  acceptance by 2.3, with nothing in the output to show for it. A scan that
+  stores no detector geometry warns and is left on the acceptance-blind scale
+  rather than using the wrong one.
+
+- **Integrating a scan whose rod leaves the detector no longer fails.** Frames
+  where the rod never reaches the detector carry region positions that are not
+  finite; the solid-angle and polarization corrections rejected those with
+  ``OverflowError`` or ``ValueError`` and aborted the integration. They now
+  yield a neutral factor for such frames, which carry no counts anyway. A
+  region size that is finite but not positive is still an error.
+
+- **The command-line interface starts again.** ``--cli`` selected the Qt
+  ``minimal`` platform plugin, which has no font database, so loading the
+  icon font raised ``FontError`` before any batch script could run. It now
+  uses ``offscreen``, and an explicitly set ``QT_QPA_PLATFORM`` is respected.
+
 GUI changes:
 
 - The "Scan data" and "Reciprocal space navigation" panels no longer reserve
diff --git a/doc/design/ctr_structure_factor_handover.md b/doc/design/ctr_structure_factor_handover.md
index 78da839..43752b1 100644
--- a/doc/design/ctr_structure_factor_handover.md
+++ b/doc/design/ctr_structure_factor_handover.md
@@ -1,17 +1,20 @@
 # CTR structure-factor scale: implementation status and handover
 
-> **Status as of 2026-09-10.** Branch `claude/ctr-structure-factor-9633bc`,
-> seven commits ahead of `master`, nothing pushed.
+> **Status as of 2026-09-11.** Branch `claude/ctr-structure-factor-9633bc`,
+> thirteen commits ahead of `master`, nothing pushed.
 >
 > The physics analysis is complete and quantified, and the reduction is now
 > **wired in**: a rocking scan and a stationary scan of the same rod come out
 > with the same `F2_hkl`, asserted by
 > `test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_agree`.
-> This **changed saved numbers in both modes**.
-> [#82](https://github.com/tifuchs/orGUI/issues/82) is closed up to the
-> real-data check of section 6 and `C_det` (F7), the one mechanism simulation
-> cannot test. [#15](https://github.com/tifuchs/orGUI/issues/15) still needs
-> the two absolute-scale inputs of section 6.
+> This **changed saved numbers in both modes**. The **real-data check has now
+> been done** — LaNiO3 scan 61, both modes run from the raw images, agreeing
+> to a median 1.033 along the CTR; see
+> [`ctr_structure_factor_scale.md`](ctr_structure_factor_scale.md) section
+> 5.1. [#82](https://github.com/tifuchs/orGUI/issues/82) is closed up to
+> `C_det` (F7), which that check bounds but does not model.
+> [#15](https://github.com/tifuchs/orGUI/issues/15) still needs the two
+> absolute-scale inputs of section 6.
 >
 > This document is the handover: what exists, how to run it, what to do next,
 > and which of my predictions turned out wrong. The physics itself is in
@@ -249,8 +252,12 @@ be left behind cannot come back unnoticed.
   paths; the reciprocal-space reconstruction still evaluates the polarization
   per pixel at the calibrated position.
 * **`C_det` (F7)** is the only mechanism that can still break mode equivalence
-  after the wiring, and it cannot be validated on simulated data. It needs the
-  real-data overlap comparison.
+  after the wiring, and it cannot be validated on simulated data. The
+  real-data overlap comparison has now been run and **bounds** it: not
+  detectable against 3 % scatter along a CTR whose regions cover the peak, a
+  factor of 5 at the Bragg peak on the same rod. Modelling it is still open,
+  and the bound is an upper limit for one rod on one sample, not a general
+  result.
 
 ## 7. Predictions that turned out wrong
 
@@ -313,3 +320,26 @@ pytest orgui/app/test/test_scan_mode_equivalence.py
 
 These five do not need the native extension. Everything else in the suite may,
 so use section 3 before concluding anything from a failure.
+
+The real-data check of `ctr_structure_factor_scale.md` section 5.1 needs data
+that is not in the repository (LaNiO3 scan 61). To repeat it on another pair
+of scans, run orGUI with `--nogui -i <script>` and, in that script: read the
+configuration, load the scan, set the mask, load the reference reflections,
+`fitExperiment`, then integrate the same rod twice — once stationary, once
+rocking — before reducing the rocking curves. Four settings decide whether the
+comparison means anything, and all four are now stored with the integration,
+so on a database written after this branch they can be read back out of
+`configuration/orgui/roi_integration` rather than guessed:
+
+* the background margins, which dominate everything else (section 5.1);
+* `auto_hsize`/`auto_vsize` — the reference used the *projected* horizontal
+  size for the rocking pass, not the automatic one-pixel rule;
+* the projected sample size, in meter;
+* the reduction windows, which must be the same for both modes; a signal
+  window several times wider than the peak shifts the ratio by tens of per
+  cent on its own.
+
+Compare on `F2_hkl`, not on the raw curves: match each rocking point to the
+stationary points within a few thousandths of `s`, require signal-to-noise of
+at least 5 on both sides, and drop regions whose `croi_pix` falls below the
+nominal `vsize * hsize`, which is how a detector gap shows up.
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
index 2a0b4ee..90035c4 100644
--- a/doc/design/ctr_structure_factor_scale.md
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -16,7 +16,8 @@
 >
 > F1, F2, F3, F5 and F6 are now **applied**, which changed saved numbers in
 > both modes; the two paths agree to `1e-6` on simulated data, limited by the
-> trapezoidal sampling of the rocking profile. F4 and F7 remain open and are
+> trapezoidal sampling of the rocking profile, and to a median **1.033** on a
+> real rod (section 5.1). F4 and F7 remain open and are
 > described below as they stand. Findings are written in the present tense
 > of the analysis; section 5 says what each one's status is now, and
 > [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
@@ -350,6 +351,13 @@ This is the one remaining mechanism that can make the two modes disagree
 *after* F1-F3 are fixed, and it is a modelling problem, not a normalization
 one.
 
+The real-data check (section 5.1) bounds it without modelling it: along a CTR
+whose regions were sized to cover the peak, truncation is not detectable
+against 3 % scatter, while at the Bragg peak on the same rod the two modes
+differ by a factor of 5. So the assumption `C_det = 1` is defensible where the
+region covers the profile and fails where it does not, which is what Vlieg's
+derivation already says.
+
 ## 4. What landed
 
 ### 4.1 One home for the corrections
@@ -518,12 +526,12 @@ along a scan in the first place.
 
 ## 5. Status of each finding
 
-**F1, F2, F3 and F6 are applied.** Steps 1-5 below are done; the wiring of
-each is in [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
-section 5, and the equivalence is asserted by
-`test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_agree`.
-Step 6, the real-data check, is the one that remains, together with F4 and
-F7.
+**F1, F2, F3, F5 and F6 are applied, and step 6 has been carried out.** All
+six steps below are done; the wiring of each is in
+[`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
+section 5, the simulated equivalence is asserted by
+`test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_agree`, and
+the real-data check is section 5.1. **F4 and F7 remain open.**
 
 Recorded in the order they had to be done, because the ordering was itself a
 result -- F6 had to be settled before F3 could be wired:
@@ -559,17 +567,108 @@ result -- F6 had to be settled before F3 could be wired:
    acceptance, the normalization that was applied, and the active-area
    assumption of F4. Without them a saved rod cannot be put on a common scale
    after the fact.
-6. **Then verify on real data. Not done — this is the remaining step.** The
-   overlap region of a rocking scan and a stationary scan on the same rod
-   (Drnec Fig. 8, right) is the acceptance test. Simulation cannot catch F7,
-   an incorrect `Delta_gamma` definition, or a beamline that reports counting
-   time in the wrong place. The simulated equivalence test does cover the F6
-   compensation
+6. **Then verify on real data. Done — section 5.1.** The overlap region of a
+   rocking scan and a stationary scan on the same rod (Drnec Fig. 8, right) is
+   the acceptance test. Simulation cannot catch F7, an incorrect `Delta_gamma`
+   definition, or a beamline that reports counting time in the wrong place.
+   The simulated equivalence test does cover the F6 compensation
    (`test_the_solid_angle_correction_does_not_reach_the_structure_factor`),
    but it supplies the region mean itself rather than reading a detector, so
    the geometry evaluation is pinned separately in
    `test_corrections_detector.py`.
 
+### 5.1 The real-data check
+
+Run on LaNiO3 scan 61, rod `(-1, 0, L)`, a 10 mm sample about 0.4 m from the
+detector. The whole pipeline was re-run from the raw images — `fitExperiment`
+on the stored Bragg reflections, both integrations, then the rocking reduction
+— rather than reduced from an existing database, so that the ROI machinery and
+the geometry were exercised too, not only the arithmetic on stored sums.
+
+The extraction reproduces the reference data set: the fit returns the stored
+calibration to about six significant figures, `delta_s` auto-pins to the same
+0.0019 and yields the same 1651-point `s` grid, and the rocking regions come
+out identical (`vsize` 1, `hsize` 16-27, centres to 0.001 px). Stationary
+`F2_hkl` agrees with the reference to a median 1.032.
+
+**Mode agreement.** Rocking against stationary, weighted mean of the
+stationary points within 0.004 r.l.u., signal-to-noise at least 5 in both, and
+regions free of detector gaps:
+
+| region | points | median ratio | quartiles |
+|---|---|---|---|
+| CTR, `s < 2.75` | 738 | **1.033** | 0.91 - 1.22 |
+| whole rod | 980 | 1.064 | 0.90 - 1.43 |
+
+Reducing the *reference* rocking curves with the same code gives 1.0245
+independently, so the result does not depend on whose extraction it is. The
+residual drift is about -16 % over 2 r.l.u., which is the resolution
+difference the two modes genuinely have rather than a normalization error: at
+low `L` the mosaic spread dominates and the rocking scan recovers it because
+`L` is still well defined, while at high `L` the sample size projected on the
+detector broadens the peak, which is a harmless area average for the
+stationary mode but reads as `Q` dependence to the rocking one.
+
+**The `s ~ 3` outlier is the (-1 0 3) Bragg peak**, not a scale error.
+Stationary `F2_hkl` rises 260-fold into `s = 3.06` and falls away again, and
+the ratio there reaches 5. A stationary ROI cannot collect a peak much wider
+than itself; a rocking scan can. This is `C_det` truncation (F7) made visible,
+and it is the one place on this rod where the two modes must not agree.
+
+**What this does not establish.** F7 is bounded, not measured: with the ROI
+chosen to cover the peak, truncation is not detectable against the 3 % scatter
+along the CTR, which is an upper limit rather than a model. F4 is untouched -
+both modes carry the same active-area assumption, so it cancels here and the
+comparison is blind to it.
+
+**Background margins dominate any such comparison**, which is worth recording
+because it cost a full diagnostic cycle. With the same regions, the same
+detector and the same `s` grid, only the background margins differing:
+
+| margins l/r/t/b, px | rocking `F2_hkl` | drift across the rod |
+|---|---|---|
+| 20/20/20/20 | 1.00 | -67 % |
+| 6/6/0/0 | 1.87 | -20 % |
+| 15/15/0/0 (as measured) | - | -4 % |
+
+A rocking region is one pixel tall, so a non-zero `top`/`bottom` margin puts
+the background regions on the rod itself, which is extended vertically. That
+over-subtracts, progressively worse with `L`. None of these margins were
+recoverable from the reference file, which is what prompted storing them; see
+section 5.2.
+
+### 5.2 What a reduction needs to be reproducible
+
+The check above could not be set up from the stored data alone. The margins,
+the automatic-sizing switches, the projected sample size and the effective
+`delta_s` were not written anywhere, so they had to be guessed, and two of the
+guesses were wrong in ways that changed the answer by more than the effect
+being measured.
+
+Those settings are now stored with every integration, as typed NeXus groups
+under `configuration/orgui`: `roi_integration/region` (sizes, margins,
+automatic sizing), `roi_integration/advanced` (sample size in meter, offsets,
+the inclination and projection switches), `roi_integration/rocking_scan`
+(`delta_s`, `max_s`), and `integration_corrections` (the correction switches,
+which replaced an opaque JSON string). `C_solid_angle` is saved beside
+`F2_hkl` for the same reason: F6 divides it back out, so a saved rod cannot be
+returned to the intensity scale without it.
+
+Two mistakes this run exposed are worth keeping:
+
+* **The reduction must read the detector stored with the scan**, not whatever
+  calibration the application holds. Reducing from a batch script that had not
+  loaded the configuration silently scaled every `Delta_gamma` by 2.3, and the
+  only symptom was a mode ratio of 2.19 instead of 1.02 — an error that looks
+  exactly like a missing physical factor. Pinned by
+  `test_peak1Dintegr.py::test_the_detector_comes_from_the_scan_not_from_the_application`.
+* **Layout changes and reduction must be tested together.** When
+  `integration_corrections` became a typed group, the reducer kept parsing the
+  JSON string that was no longer written, so the F6 compensation stopped being
+  applied to newly written databases. Every unit test passed, because the
+  layout and the reduction were only ever tested apart. Pinned by
+  `test_peak1Dintegr.py::test_the_typed_corrections_group_is_read_back`.
+
 ## 6. What is needed to close issue #15, and reflectivity
 
 Issue #15 asks for
@@ -654,7 +753,8 @@ it, in both modes).
   piece of work and was not analysed here.
 * **`C_det` (F7)** is the only remaining mechanism that can break the mode
   equivalence after F1-F3, and it is the one that cannot be validated on
-  simulated data. It needs the real-data comparison of section 5, step 6.
+  simulated data. The real-data comparison of section 5.1 has been run and
+  bounds it on one rod; modelling it is still open.
 * **Error propagation through the new factors.** `measurement` reduces
   intensities; the errors follow the same divisors, but a `Delta_gamma`
   estimated from the geometry has an uncertainty of its own that nothing
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 27cd90c..021bb3b 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -11,7 +11,9 @@ Scientific and analysis additions:
 
 - **The polarization correction now follows the detector arm.** *This changes saved numbers for scans that move the detector arm, and only those.* The per-pixel polarization array is built from the calibrated geometry, which is right only while the arm stays there. On a scan that drives the arm -- a reflectivity curve, where it follows twice the incidence angle -- the same pixel looks in a different direction on every frame, and the calibrated-position value understated the correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration paths now apply a per-frame factor, ``corrections.detector.polarization_arm_correction``, that moves the correction onto the arm position each frame was measured at. It is exactly one while the arm sits at its calibrated position, so a fixed-arm scan is bit-identical and needs no switch. The factor is a ratio of two region means rather than a rebuilt per-pixel array, which keeps the cost to a region-sized evaluation per frame; the polarization is not flat across a region at a large scattering angle, so the means matter. The detector solid angle needs no such correction: an arm rotation is a rigid rotation about the sample, so every pixel keeps its distance and its obliquity to its own line of sight, and the solid angle is invariant under it exactly. The reciprocal-space reconstruction applies the polarization per pixel rather than as a region mean and is unchanged; correcting it there would need the array rebuilt per frame.
 
-- **Rocking and stationary integration now produce the same structure factor.** *This changes saved numbers in both modes.* A rocking scan and a stationary scan of the same rod previously differed by exactly exposure time times monitor times the out-of-plane acceptance in degrees; they now agree. Four corrections changed. The rocking path gained the per-frame exposure and monitor normalization, applied inside the rocking integral so that a varying counting time or a drifting monitor is handled correctly rather than only on average; it now integrates the rocking angle in radian as the published expressions require, rather than in degrees; and it divides by the out-of-plane acceptance of its region of interest, without which a rod measured with regions resized along the scan came out with a distorted *shape* -- a factor 2.3 across a simulated Pt(111) rod -- and not merely a wrong scale. Separately, the detector **solid-angle correction no longer reaches a structure factor** in either mode: summing a region of interest already yields the complete angular integral, with every pixel weighted by the solid angle it subtends, so dividing by that solid angle again double-counted the detector obliquity (0.7 % for a detector at 1 m, 7 % at 0.3 m, varying across the detector and therefore a rod shape error). The switch stays, because that correction is the right one for a broad or diffuse feature where a differential cross section is wanted: it still scales the intensity counters, and is now measured over the same regions of interest and divided back out when ``F2_hkl`` is formed, so a structure factor is the same number whether or not it was enabled. Its tooltip and the ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps applying it uncompensated, since that path does form a differential cross section per pixel. For rocking scans the correction is applied when the curves are extracted, so whether to remove it again is read from the configuration stored with the scan; an older database where that cannot be established warns and is left uncompensated. Integrated rocking scans now store a ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit, which normalizations were applied, the acceptance used, whether the solid-angle correction was compensated, and the active-area assumption, so that a saved rod can be placed on a common scale afterwards. Rocking normalization uses the counters stored with the scan, so it requires a backend that declares ``exposure_time`` in ``auxillary_counters``; a missing counter is skipped and recorded rather than failing the integration. Existing configuration files load unchanged.
+- **Rocking and stationary integration now produce the same structure factor.** *This changes saved numbers in both modes.* A rocking scan and a stationary scan of the same rod previously differed by exactly exposure time times monitor times the out-of-plane acceptance in degrees; they now agree. Four corrections changed. The rocking path gained the per-frame exposure and monitor normalization, applied inside the rocking integral so that a varying counting time or a drifting monitor is handled correctly rather than only on average; it now integrates the rocking angle in radian as the published expressions require, rather than in degrees; and it divides by the out-of-plane acceptance of its region of interest, without which a rod measured with regions resized along the scan came out with a distorted *shape* -- a factor 2.3 across a simulated Pt(111) rod -- and not merely a wrong scale. Separately, the detector **solid-angle correction no longer reaches a structure factor** in either mode: summing a region of interest already yields the complete angular integral, with every pixel weighted by the solid angle it subtends, so dividing by that solid angle again double-counted the detector obliquity (0.7 % for a detector at 1 m, 7 % at 0.3 m, varying across the detector and therefore a rod shape error). The switch stays, because that correction is the right one for a broad or diffuse feature where a differential cross section is wanted: it still scales the intensity counters, and is now measured over the same regions of interest and divided back out when ``F2_hkl`` is formed, so a structure factor is the same number whether or not it was enabled. Its tooltip and the ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps applying it uncompensated, since that path does form a differential cross section per pixel. For rocking scans the correction is applied when the curves are extracted, so whether to remove it again is read from the configuration stored with the scan; an older database where that cannot be established warns and is left uncompensated. Integrated rocking scans now store a ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit, which normalizations were applied, the acceptance used, whether the solid-angle correction was compensated, and the active-area assumption, so that a saved rod can be placed on a common scale afterwards. Rocking normalization uses the counters stored with the scan, so it requires a backend that declares ``exposure_time`` in ``auxillary_counters``; a missing counter is skipped and recorded rather than failing the integration. Existing configuration files load unchanged. This equivalence has now been checked on real data as well as in simulation: on a LaNiO3 rod measured both ways, the two modes agree to a median 1.03 along the rod, with the remaining spread explained by the resolution difference between them rather than by a normalization. At a Bragg peak on the same rod they differ by a factor of five, which is expected — a stationary region cannot collect a peak much wider than itself.
+
+- **The settings that decide what was integrated are now stored with every integration.** A reduction could previously not be reproduced from its own output: the background ROI margins, the automatic-sizing switches, the projected sample size, and the effective ``delta_s`` of a rocking scan were not written anywhere. They are now saved under ``configuration/orgui/roi_integration`` as typed groups carrying their units — ``region`` (sizes, margins, automatic sizing), ``advanced`` (sample size in meter, offsets, the inclination and projection switches) and ``rocking_scan`` (``delta_s`` and ``max_s``, with ``delta_s`` stored as the value actually used after the resolution clipping, not as typed). The correction switches move the same way: ``integration_corrections`` is now a group of typed datasets instead of one opaque JSON string, so a stored configuration can be read in any HDF5 browser. Databases written with the JSON layout are still read. The Lorentz, footprint and normalization switches are recorded alongside the others, and a configuration that predates them leaves those controls as the user has them rather than silently switching a correction off. ``C_solid_angle`` is now saved beside ``F2_hkl``, because the structure factor divides it back out and a saved rod cannot otherwise be returned to the intensity scale.
 
 - **All correction factors collected into one package.** Every factor between detector counts and a structure factor now lives in ``orgui.datautils.xrayutils.corrections``, split by what it depends on: ``geometry`` (the z-axis Lorentz, rod-interception and area table), ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and polarization), ``normalization`` (counting time and monitor), ``roi``, and ``measurement``. The rocking integration, the stationary integration and the reciprocal-space reconstruction previously each carried their own copy of several of these; they now share one definition, so they cannot drift onto different scales. The package is physics only -- numbers in, numbers out -- and reads no scan object, configuration or widget; ``orgui.app`` ``integration_corrections`` is the adapter that supplies those. ``orgui.datautils.xrayutils.geometrycorrections`` and ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the moved modules. **No calculated value changes.**
 
@@ -114,6 +116,12 @@ A ***critical bug*** was fixed that affects bulk CTR calculations:
 - A segmented ("interlaced") scan now provides the counters its segments share. It previously reported no counters at all, so combining scans in the segmented scan loader silently dropped every monitor, the exposure time and everything else the backend reads from the file: the monitor normalization offered nothing to pick, exposure normalization was skipped, and no auxiliary counter was written to the database. A counter is taken over when *every* segment provides it, since one that only some segments have would misalign all following values, and the counters that are dropped for this reason are named in the log. Counters held once per segment, such as a segment's exposure time, are expanded to one value per image, so segments measured with different exposure times or monitors now normalize correctly against each other. Sorting the segments by axis value reorders the counters with the images.
 - A segmented scan now also describes its detector arm. ``gamma_arm``, ``delta_arm``, ``arm_angle_frame`` and ``continuous_exposure`` were dropped along with the counters, so the per-pixel conversions fell back to the fixed arm position from the configuration and converted every image of a segmented scan at the wrong place -- an XRR measurement split into several ``a2scan th tth`` segments was the case that showed it. The arm is merged conservatively, since a wrong arm position yields plausible-looking angles rather than an error: the arm motors have to be provided by every segment and all in the same form, either a single fixed value per segment or one value per image, and a mix of the two is refused because a fixed value often means a backend did not find the motor. Fixed values that differ between segments are expanded to one value per image, which is where the arm actually was. ``arm_angle_frame`` and ``continuous_exposure`` must match exactly; segments that disagree, or that state one of them only in part, are reported in the log and the property is left to the configuration. Disagreement about ``arm_angle_frame`` also blocks the arm angles themselves, since the segments' motor values would then be in different conventions. Reciprocal-space reconstruction was never affected: its exposure bounds already read each segment's own arm, and they now agree with the arm the rest of the program sees.
 
+- **Reducing a rocking scan now uses the detector geometry stored with that scan**, instead of whatever calibration the application happens to hold. *This changes saved numbers for any reduction run against a different calibration than the one the curves were extracted with.* The out-of-plane acceptance and the solid-angle compensation are properties of the geometry the data was taken with, so reducing from a script that has not loaded the matching configuration, or after another calibration was opened, silently produced a wrongly scaled ``F2_hkl``: on a real scan it scaled every acceptance by 2.3, with nothing in the output to show for it. A scan that stores no detector geometry warns and is left on the acceptance-blind scale rather than using the wrong one.
+
+- **Integrating a scan whose rod leaves the detector no longer fails.** Frames where the rod never reaches the detector carry region positions that are not finite; the solid-angle and polarization corrections rejected those with ``OverflowError`` or ``ValueError`` and aborted the integration. They now yield a neutral factor for such frames, which carry no counts anyway. A region size that is finite but not positive is still an error.
+
+- **The command-line interface starts again.** ``--cli`` selected the Qt ``minimal`` platform plugin, which has no font database, so loading the icon font raised ``FontError`` before any batch script could run. It now uses ``offscreen``, and an explicitly set ``QT_QPA_PLATFORM`` is respected.
+
 GUI changes:
 
 - The "Scan data" and "Reciprocal space navigation" panels no longer reserve horizontal space they do not need. In the "Scan data" panel, spin boxes are sized for the values that are typically entered instead of the widest value of their range, the integration option check boxes reflow into one or two columns depending on the available width, tab labels and the backend combo box elide, and long descriptions wrap. That panel can now be made about 20% narrower than before and, unlike before, can be resized at all. All widths follow the font metrics and the current widget style, so they scale with high DPI settings. Some labels were shortened: the ROI sizes state their pixel unit in the group title instead of on every spin box, "Start H_0:"/"Direction H_1:" became "H_0:"/"H_1:", "ROI size (hxv):" became "ROI (h, v):", and "Integrate at multiples of:" became "Multiples of:"; the full wording is available as a tool tip.
diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index 8b64279..e8e4159 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -486,8 +486,12 @@ class ROIState:
     region: dict = field(default_factory=dict)
     #: The advanced options dialog: sample size in meter, offsets in pixels.
     advanced: dict = field(default_factory=dict)
-    #: Rocking-scan ``s`` sampling, r.l.u. ``delta_s`` is the effective value
-    #: after the resolution clipping of ``onRoSChanged``, not what was typed.
+    #: Rocking-scan ``s`` sampling, r.l.u. Saved with a *rocking* scan,
+    #: ``delta_s`` is the effective value after the resolution clipping of
+    #: ``onRoSChanged`` rather than what was typed. Saved with a stationary
+    #: one it is whatever the control held, since nothing there clips it and
+    #: the value is unused -- so do not read it as an effective sampling
+    #: without checking which mode wrote it.
     rocking_scan: dict = field(default_factory=dict)
 
     def is_empty(self):

From 5af29cc70ba20fa256f90e23dfa47425e8197414 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 11 Sep 2026 18:31:38 -0400
Subject: [PATCH 15/33] docs: drop the stale commit count from the handover
 header

---
 doc/design/ctr_structure_factor_handover.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/design/ctr_structure_factor_handover.md b/doc/design/ctr_structure_factor_handover.md
index 43752b1..8189c82 100644
--- a/doc/design/ctr_structure_factor_handover.md
+++ b/doc/design/ctr_structure_factor_handover.md
@@ -1,7 +1,8 @@
 # CTR structure-factor scale: implementation status and handover
 
 > **Status as of 2026-09-11.** Branch `claude/ctr-structure-factor-9633bc`,
-> thirteen commits ahead of `master`, nothing pushed.
+> nothing pushed. `git log --oneline master..HEAD` is the commit list; a
+> count written here goes stale on the commit that writes it.
 >
 > The physics analysis is complete and quantified, and the reduction is now
 > **wired in**: a rocking scan and a stationary scan of the same rod come out

From abf6992a23e94e2036403d7dfe3a45f5abc95151 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Sun, 13 Sep 2026 15:40:11 -0400
Subject: [PATCH 16/33] feat: add absolute active area and a beam flux input
 for absolute F and R calculation

---
 CHANGELOG.md                                  |  38 ++++
 doc/design/ctr_structure_factor_scale.md      |  72 ++++---
 doc/source/release_notes.rst                  |   5 +
 orgui/app/config_data.py                      |  74 ++++++++
 orgui/app/orGUI.py                            |   2 +-
 orgui/app/peak1Dintegr.py                     | 176 ++++++++++++++++--
 orgui/app/test/test_config_data.py            | 109 +++++++++++
 orgui/app/test/test_config_nexus_layout.py    |   3 +
 .../test_integration_corrections_dialog.py    | 111 ++++++++++-
 9 files changed, 546 insertions(+), 44 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 71ac0e1..74f64df 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,6 +95,35 @@ Scientific and analysis additions:
   ``F2_hkl``, because the structure factor divides it back out and a saved rod
   cannot otherwise be returned to the intensity scale.
 
+- **The corrections dialog now asks for the sample size across the beam.** A
+  second size ``W`` sits beside the existing sample size ``L``, in millimeter.
+  It is the sample extent perpendicular to the beam in the surface plane, and
+  it is taken to be the width of the illuminated area, on the assumption that
+  the beam is at least as wide as the sample -- so the sample bounds the lit
+  area rather than the beam. Nothing in a *relative* structure factor uses it:
+  the active-area correction that is applied to an integrated intensity is
+  ``illuminated_area_fraction``, which is dimensionless and unchanged, so no
+  saved number moves. ``W`` supplies the missing input for the *absolute*
+  active area in square meter, ``IntegrationCorrectionsDialog.activeArea``,
+  which an absolutely scaled structure factor needs. The measurement is
+  assumed throughout to be made with open post-sample slits and an area
+  detector, which is what makes the footprint the active area; the
+  slit-limited case, where ``1/(sin(delta) cos(alpha - beta_in))`` would apply
+  instead, is not supported. Both size controls now say so in their tooltips.
+
+- **A beam flux input, and every footprint-dialog input, is now stored with
+  the configuration.** The corrections dialog gains a beam flux field, the
+  incident photon flux density needed together with the active area for an
+  absolutely scaled structure factor (issue #15); called "beam flux" rather
+  than ``Phi_0`` or ``phi`` to avoid confusion with the diffractometer's own
+  sample-circle ``phi``. It, and the existing ``L`` and ``W`` sample sizes,
+  are now recorded in a typed ``integration_corrections/footprint`` NeXus
+  group beside the correction switches -- previously none of the three
+  reached the saved configuration at all, so a stored active-area calculation
+  could not be reproduced from its own output. A configuration written before
+  they existed, or a dialog that was never opened, leaves the running dialog
+  exactly as it is rather than resetting it to defaults.
+
 - **All correction factors collected into one package.** Every factor between
   detector counts and a structure factor now lives in
   ``orgui.datautils.xrayutils.corrections``, split by what it depends on:
@@ -859,6 +888,15 @@ GUI fixes:
   opened. Both dialogs apply every edit immediately, so restoring the widgets
   alone left the edited values active, and the discarded configuration stayed
   in use until it was overwritten or a config file was loaded.
+- The footprint correction dialog now fits a normal screen. Both the
+  analytical-shape and the measured-profile groups used to be given layout
+  space at once, only one of them disabled, and everything was stacked in a
+  single column below a full-width schematic image and a 220-pixel preview
+  plot -- together taller than most displays. It is now two columns, the
+  beam and sample inputs on the left and the sample position and preview on
+  the right; the inactive beam-model group is hidden rather than merely
+  disabled, so it stops reserving space it is not using; the schematic image
+  is capped; and the preview plot is a little shorter.
 
 ESRF ID31 beamline support and reciprocal-space display:
 
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
index 90035c4..eb892d6 100644
--- a/doc/design/ctr_structure_factor_scale.md
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -17,8 +17,8 @@
 > F1, F2, F3, F5 and F6 are now **applied**, which changed saved numbers in
 > both modes; the two paths agree to `1e-6` on simulated data, limited by the
 > trapezoidal sampling of the rocking profile, and to a median **1.033** on a
-> real rod (section 5.1). F4 and F7 remain open and are
-> described below as they stand. Findings are written in the present tense
+> real rod (section 5.1). F4 is closed; F7 remains open. Both are described
+> below as they stand. Findings are written in the present tense
 > of the analysis; section 5 says what each one's status is now, and
 > [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
 > section 5 says how each was wired.
@@ -154,33 +154,60 @@ a per-frame time of a few tenths of a second - the two modes land within a
 factor of a few of each other, which is exactly the regime in which the
 discrepancy looks like a plausible scale factor rather than a bug.
 
-### F4 - the active area is a dimensionless fraction, and `C_area` is skipped
+### F4 - the active area is a dimensionless fraction
 
-`geometrycorrections.area_correction` (`1/sin(delta)`) exists but is
-deliberately not applied; the numerical `beamprofile` factors are used instead.
+**`C_area` is applied**, in the form the open-slit case calls for.
 `BeamProfile.illuminated_area_fraction` returns
 `C_flux_on_sample / (p_max * L sin(alpha))` - the beam profile integrated over
-the projected sample, normalized to a uniform beam. It is a *fraction*, not an
-area.
+the projected sample, normalized to a uniform beam - and that *is* the active
+area correction for an area detector with open post-sample slits, evaluated at
+the incidence angle. Once the footprint exceeds the beam it carries exactly a
+`1/sin(alpha)` dependence: for a 100 um FWHM beam on a 10 mm sample,
+`C_illum_area * sin(alpha)` approaches `sqrt(2 pi) sigma / L`, holding to four
+parts in `1e5` at `alpha = 2` degrees - where the footprint is 3.5 times the
+FWHM - and to seven digits by 5 degrees. Below that it rolls over towards 1 as
+the beam overfills the sample (0.97 at 0.2 degrees), which a bare
+`1/sin(alpha)` would get wrong.
+
+What is *not* applied is `geometrycorrections.area_correction`'s
+`1/sin(delta)`, the **slit-limited** form. That is deliberate and correct: it
+describes a different regime, not a missing factor.
+
+The finding is therefore about one narrow thing: the factor is a dimensionless
+*fraction* rather than an area in square meter, which is what issue #15 needs.
+That is closed by the sample width `W` in the corrections dialog -
+`activeArea(alpha)` returns `W * L * C_illum_area` in square meter via
+`activearea.beam_limited_area`. **`W` is the sample size perpendicular to the
+beam, and it is used as the illuminated width on the assumption that the beam
+is at least as wide as the sample**, so the sample bounds the lit area rather
+than the beam. A narrower beam would make this an overestimate; there is no
+horizontal beam-width input, by decision.
+
+**The slit-limited regime is out of scope** and is not planned in the
+mid-term. `activearea.slit_limited_area` stays available for a script that
+needs it, but nothing selects it, no dialog offers it, and the output does not
+record the choice, because there is only one choice.
 
 This is **not** a mode-equivalence problem: the active area enters both
 expressions identically and cancels from their ratio
-(`test_footprint_area_cancels_between_the_modes`). It is a problem for
-issue #15, and it hides an undocumented assumption:
+(`test_footprint_area_cancels_between_the_modes`), which is also why the
+real-data check of section 5.1 is blind to it. The two regimes, for the
+record:
 
 * With **open post-sample slits and an area detector** - orGUI's usual
   configuration - the illuminated footprint defines the active area, it has no
-  `delta` dependence, and skipping `C_area` is right.
+  `delta` dependence, and `illuminated_area_fraction` is the right factor.
   `test_the_stationary_path_recovers_the_rod_up_to_one_constant` confirms the
   stationary path then recovers the rod shape to machine precision.
 * With **slits narrower than the footprint**,
   `C_area = 1/(sin(delta) cos(alpha - beta_in))` applies and varies along the
   rod. On the simulated rod above, `delta` moves from 16.77 to 16.95 degrees
   between `l = 0.4` and `l = 3.0`, a 1.1 % shape error - small here, much
-  larger between rods at different in-plane momentum transfer.
+  larger between rods at different in-plane momentum transfer. Out of scope,
+  as above.
 
-Neither the assumption nor which case a given data set is in is recorded
-anywhere in the output.
+orGUI assumes the first case throughout. That assumption is now stated in the
+dialog rather than only here, on the tooltips of `L` and `W`.
 
 ### F5 - the polarization correction is evaluated at the calibrated arm position
 
@@ -531,7 +558,9 @@ six steps below are done; the wiring of each is in
 [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
 section 5, the simulated equivalence is asserted by
 `test_scan_mode_equivalence.py::test_rocking_and_stationary_paths_agree`, and
-the real-data check is section 5.1. **F4 and F7 remain open.**
+the real-data check is section 5.1. **F4 is closed** - the active area is
+available in square meter and the slit-limited regime is out of scope.
+**F7 remains open.**
 
 Recorded in the order they had to be done, because the ordering was itself a
 result -- F6 had to be settled before F3 could be wired:
@@ -617,7 +646,7 @@ and it is the one place on this rod where the two modes must not agree.
 
 **What this does not establish.** F7 is bounded, not measured: with the ROI
 chosen to cover the peak, truncation is not detectable against the 3 % scatter
-along the CTR, which is an upper limit rather than a model. F4 is untouched -
+along the CTR, which is an upper limit rather than a model. F4 does not enter -
 both modes carry the same active-area assumption, so it cancels here and the
 comparison is blind to it.
 
@@ -680,13 +709,12 @@ constants:
   `Lattice.uc_area`, `measurement.CLASSICAL_ELECTRON_RADIUS`).
 * `Phi_0` and `T` - user input. `T` is in the scan; `Phi_0` needs a flux
   measurement and a field to put it in.
-* `A` - `activearea.beam_limited_area(alpha, beam_width, sample_length,
-  profile)` returns it in square meter, as `w * L * C_illum_area(alpha, L)`
-  (section 4.3; `C_illum_area` alone is a fraction, not an area - F4). Of its
-  inputs only the **horizontal beam width** is missing: the footprint dialog
-  already asks for the sample size and the beam profile, and the profile
-  carries the vertical direction. `activearea.slit_limited_area` covers the
-  narrow-slit case instead.
+* `A` - **available**, as
+  `IntegrationCorrectionsDialog.activeArea(alpha)`, which is
+  `activearea.beam_limited_area(alpha, W, L, profile)` in square meter
+  (section 4.3; `C_illum_area` alone is a fraction, not an area - F4). The
+  dialog supplies both sizes and the profile; the illuminated width is taken
+  to be the sample width `W`, assuming a beam at least that wide.
 * `C_det` - F7, unmodelled.
 
 **Reflectivity comes for free.**
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 021bb3b..4d5a778 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -15,6 +15,10 @@ Scientific and analysis additions:
 
 - **The settings that decide what was integrated are now stored with every integration.** A reduction could previously not be reproduced from its own output: the background ROI margins, the automatic-sizing switches, the projected sample size, and the effective ``delta_s`` of a rocking scan were not written anywhere. They are now saved under ``configuration/orgui/roi_integration`` as typed groups carrying their units — ``region`` (sizes, margins, automatic sizing), ``advanced`` (sample size in meter, offsets, the inclination and projection switches) and ``rocking_scan`` (``delta_s`` and ``max_s``, with ``delta_s`` stored as the value actually used after the resolution clipping, not as typed). The correction switches move the same way: ``integration_corrections`` is now a group of typed datasets instead of one opaque JSON string, so a stored configuration can be read in any HDF5 browser. Databases written with the JSON layout are still read. The Lorentz, footprint and normalization switches are recorded alongside the others, and a configuration that predates them leaves those controls as the user has them rather than silently switching a correction off. ``C_solid_angle`` is now saved beside ``F2_hkl``, because the structure factor divides it back out and a saved rod cannot otherwise be returned to the intensity scale.
 
+- **The corrections dialog now asks for the sample size across the beam.** A second size ``W`` sits beside the existing sample size ``L``, in millimeter. It is the sample extent perpendicular to the beam in the surface plane, and it is taken to be the width of the illuminated area, on the assumption that the beam is at least as wide as the sample -- so the sample bounds the lit area rather than the beam. Nothing in a *relative* structure factor uses it: the active-area correction that is applied to an integrated intensity is ``illuminated_area_fraction``, which is dimensionless and unchanged, so no saved number moves. ``W`` supplies the missing input for the *absolute* active area in square meter, ``IntegrationCorrectionsDialog.activeArea``, which an absolutely scaled structure factor needs. The measurement is assumed throughout to be made with open post-sample slits and an area detector, which is what makes the footprint the active area; the slit-limited case, where ``1/(sin(delta) cos(alpha - beta_in))`` would apply instead, is not supported. Both size controls now say so in their tooltips.
+
+- **A beam flux input, and every footprint-dialog input, is now stored with the configuration.** The corrections dialog gains a beam flux field, the incident photon flux density needed together with the active area for an absolutely scaled structure factor (issue #15); called "beam flux" rather than ``Phi_0`` or ``phi`` to avoid confusion with the diffractometer's own sample-circle ``phi``. It, and the existing ``L`` and ``W`` sample sizes, are now recorded in a typed ``integration_corrections/footprint`` NeXus group beside the correction switches -- previously none of the three reached the saved configuration at all, so a stored active-area calculation could not be reproduced from its own output. A configuration written before they existed, or a dialog that was never opened, leaves the running dialog exactly as it is rather than resetting it to defaults.
+
 - **All correction factors collected into one package.** Every factor between detector counts and a structure factor now lives in ``orgui.datautils.xrayutils.corrections``, split by what it depends on: ``geometry`` (the z-axis Lorentz, rod-interception and area table), ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and polarization), ``normalization`` (counting time and monitor), ``roi``, and ``measurement``. The rocking integration, the stationary integration and the reciprocal-space reconstruction previously each carried their own copy of several of these; they now share one definition, so they cannot drift onto different scales. The package is physics only -- numbers in, numbers out -- and reads no scan object, configuration or widget; ``orgui.app`` ``integration_corrections`` is the adapter that supplies those. ``orgui.datautils.xrayutils.geometrycorrections`` and ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the moved modules. **No calculated value changes.**
 
 - **Out-of-plane detector acceptance.** ``orgui.datautils.xrayutils.corrections.acceptance`` estimates ``Delta_gamma``, the angular height of a region of interest as seen from the sample, which a rocking-scan integrated intensity is proportional to (Vlieg equations 20 and 42) and which orGUI previously did not compute at all. Measured edge to edge, at the region's centre column where the rod crosses the aperture, and vectorized over a scan because orGUI resizes regions per detector position. ``gamma_range`` reports the span over the whole region as a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row case. The rocking integration now divides by it -- see the mode-equivalence entry below.
@@ -135,6 +139,7 @@ GUI fixes:
 - The Q-plot ordinate now follows the geometry instead of always pointing upwards. In an inverted, downward-scattering setup such as the one at ID31 — recognised from the azimuthal reference, not hardcoded — the out-of-plane coordinate grows towards the bottom of the detector image, and drawing it upwards showed the reciprocal-space image mirrored with respect to the detector image.
 - The position readout is now correct while the Q-plot is switched on. The plot axes hold momentum transfer there and not detector pixels, so the ``X``/``Y`` labels were wrong and ``HKL``, ``del``, ``gam`` and ``Q`` were computed as if the cursor were on a pixel. The two axis fields are now labelled ``q_par[<frame>]`` and ``q_perp[<frame>]`` and shown with five decimals, and the remaining fields are obtained by inverting the conversion, so hovering a point of the Q-plot reports the same ``HKL`` and the same detector angles as hovering the pixel it came from. The reported ``Q`` is the reconstructed vector, so its components are exactly the coordinates under the cursor; it is unrefracted in the Q-plot because the axes are unrefracted as well, while ``HKL`` stays refraction corrected in both modes. Positions that no pixel maps to — the corners of the rebinned grid, or anything outside the Ewald sphere — are shown as ``------``.
 - Cancelling or resetting the machine parameter or the crystal parameter dialog now restores the configuration that was active when the dialog was opened. Both dialogs apply every edit immediately, so restoring the widgets alone left the edited values active, and the discarded configuration stayed in use until it was overwritten or a config file was loaded.
+- The footprint correction dialog now fits a normal screen. Both the analytical-shape and the measured-profile groups used to be given layout space at once, only one of them disabled, and everything was stacked in a single column below a full-width schematic image and a 220-pixel preview plot -- together taller than most displays. It is now two columns, the beam and sample inputs on the left and the sample position and preview on the right; the inactive beam-model group is hidden rather than merely disabled, so it stops reserving space it is not using; the schematic image is capped; and the preview plot is a little shorter.
 
 ESRF ID31 beamline support and reciprocal-space display:
 
diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index e8e4159..63078bd 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -85,6 +85,17 @@ class CorrectionState:
     background_asset: str | None = None
     background_variance_asset: str | None = None
     uncertainty_provenance: dict[str, Any] = field(default_factory=dict)
+    # Sample size, in meter, along and across the beam: inputs to the beam
+    # footprint dialog, not the footprint itself. ``None`` means "this
+    # configuration predates them, or the dialog was never opened", which
+    # must leave the dialog at its own defaults rather than zeroing it out.
+    sample_length_m: float | None = None
+    sample_width_m: float | None = None
+    # Incident flux density Phi_0, in photons per second per square meter
+    # (see corrections.measurement.scale_factor). Optional: only needed for
+    # an absolutely scaled structure factor (issue #15); a relative one does
+    # not use it.
+    beam_flux_density: float | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """Return a JSON-compatible correction-state dictionary."""
@@ -367,6 +378,17 @@ def corrections_to_nxdict(state):
             "background": state.background_asset,
             "background_variance": state.background_variance_asset,
         }),
+        "footprint": _nx_group(
+            {
+                "sample_length": state.sample_length_m,
+                "sample_width": state.sample_width_m,
+                "beam_flux_density": state.beam_flux_density,
+            },
+            units={
+                "@sample_size_unit": "m",
+                "@beam_flux_density_unit": "1/(s m^2)",
+            },
+        ),
     }
     if state.monitor_corrections:
         nxdict["normalization"]["monitor_corrections"] = _string_array(
@@ -434,6 +456,14 @@ def corrections_from_nxdict(nxdict):
     ):
         if key in assets:
             values[name] = str(assets[key])
+    footprint = _read_group(nxdict, "footprint")
+    for name, key in (
+        ("sample_length_m", "sample_length"),
+        ("sample_width_m", "sample_width"),
+        ("beam_flux_density", "beam_flux_density"),
+    ):
+        if key in footprint:
+            values[name] = float(footprint[key])
     return CorrectionState(**values)
 
 
@@ -617,6 +647,22 @@ def from_gui(cls, gui):
             repair_enabled = bool(getattr(repair, "enabled", False))
             excluded = getattr(gui, "excludedImagesDialog", None)
             excluded = () if excluded is None else excluded.getData()
+            # Read only if the dialog was already created (i.e. opened at
+            # least once); a config capture must not build GUI it does not
+            # otherwise need. An unopened dialog has nothing to record, which
+            # is the same "not recorded" state as a config predating it.
+            footprint_dialog = getattr(
+                getattr(gui.scanSelector, "correctionsDialog", None),
+                "footprintOptions",
+                None,
+            )
+            sample_length_m = None
+            sample_width_m = None
+            beam_flux_density = None
+            if footprint_dialog is not None:
+                sample_length_m = footprint_dialog.sampleLength()
+                sample_width_m = footprint_dialog.sampleWidth()
+                beam_flux_density = footprint_dialog.beamFluxDensity()
             corrections = CorrectionState(
                 use_mask=bool(options.get("mask", False)) or repair_enabled,
                 use_background=getattr(gui, "background_image", None)
@@ -654,6 +700,9 @@ def from_gui(cls, gui):
                         if int(value) >= 0
                     )
                 ),
+                sample_length_m=sample_length_m,
+                sample_width_m=sample_width_m,
+                beam_flux_density=beam_flux_density,
             )
             roi = ROIState(
                 region=dict(options.get("region", {})),
@@ -731,6 +780,31 @@ def apply_to_gui(self, gui):
                 if values:
                     options[name] = dict(values)
             gui.scanSelector.set_integration_options(options)
+            # Only if this configuration actually recorded them: a file
+            # written before these existed must leave the dialog at whatever
+            # the user already has, not reset it to its own defaults.
+            if (
+                self.corrections.sample_length_m is not None
+                or self.corrections.sample_width_m is not None
+                or self.corrections.beam_flux_density is not None
+            ):
+                corrections_dialog = getattr(
+                    gui.scanSelector, "correctionsDialog", None
+                )
+                if corrections_dialog is not None:
+                    footprint_dialog = corrections_dialog.footprintOptions_shared()
+                    if self.corrections.sample_length_m is not None:
+                        footprint_dialog.setSampleLength(
+                            self.corrections.sample_length_m
+                        )
+                    if self.corrections.sample_width_m is not None:
+                        footprint_dialog.setSampleWidth(
+                            self.corrections.sample_width_m
+                        )
+                    if self.corrections.beam_flux_density is not None:
+                        footprint_dialog.setBeamFluxDensity(
+                            self.corrections.beam_flux_density
+                        )
         gui.reconstruction_normalize_exposure = self.corrections.normalize_exposure
         gui.reconstruction_monitor_corrections = self.corrections.monitor_corrections
         if (
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index 08cc7b9..0229749 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -6458,7 +6458,7 @@ def sumImage(i):
                 self.scanSelector.correctionsDialog.footprintOptions_shared()
             )  # noqa: E501
             beam_profile = footprint_dialog.beamProfile()
-            sample_size = footprint_dialog.L.value() * 1e-3  # mm -> m
+            sample_size = footprint_dialog.sampleLength()  # m
         normalization = None
         normalization_applied = []
         if options["normalization"]:
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index af4979a..c33c7fa 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -66,6 +66,7 @@
 from ..datautils.xrayutils.corrections import beamprofile
 from ..datautils.xrayutils.corrections import (
     acceptance as acceptance_corrections,
+    activearea as activearea_corrections,
     detector as detector_corrections,
     measurement as measurement_corrections,
     normalization as normalization_corrections,
@@ -1643,7 +1644,7 @@ def integrate(self):
             C_rod = 1.0
 
         if self.footprintButton.isChecked():
-            L = self.integrationCorrection.L.value() * 1e-3  # sample size (mm -> m)
+            L = self.integrationCorrection.sampleLength()  # sample size, m
             # Gaussian or measured beam profile, depending on the dialog.
             # C_flux_on_sample is saved as the diagnostic numerator of the
             # single applied active-area factor.
@@ -2563,6 +2564,9 @@ def __init__(self, parent=None):
         img = qutils.AspectRatioPixmapLabel(self)
         pixmp = qt.QPixmap(resources.getPath("incident_corrections.png"))
         img.setPixmap(pixmp)
+        # A schematic, not the main content: capped so a wide-aspect image
+        # cannot by itself push the dialog past a normal screen's height.
+        img.setMaximumHeight(110)
 
         verticalLayout.addWidget(img)
 
@@ -2575,15 +2579,53 @@ def __init__(self, parent=None):
             shape.name: [p.default for p in shape.parameters] for shape in BEAM_SHAPES
         }
 
-        layout = qt.QGridLayout()
-        layout.addWidget(qt.QLabel("Sample size L:"), 0, 0)
+        sizesLayout = qt.QGridLayout()
+        sizesLayout.addWidget(qt.QLabel("Sample size L:"), 0, 0)
         self.L = qt.QDoubleSpinBox()
         self.L.setRange(0.00001, 1000000)
         self.L.setDecimals(4)
         self.L.setSuffix(" mm")
         self.L.setValue(5)
-        layout.addWidget(self.L, 0, 1)
+        self.L.setToolTip(
+            "Sample size along the beam. With the beam profile, this sets the "
+            "illuminated fraction of the projected footprint, which is the "
+            "active-area correction for open post-sample slits."
+        )
+        sizesLayout.addWidget(self.L, 0, 1)
+
+        sizesLayout.addWidget(qt.QLabel("Sample size W:"), 1, 0)
+        self.W = qt.QDoubleSpinBox()
+        self.W.setRange(0.00001, 1000000)
+        self.W.setDecimals(4)
+        self.W.setSuffix(" mm")
+        self.W.setValue(5)
+        self.W.setToolTip(
+            "Sample size perpendicular to the beam, in the surface plane.\n"
+            "The horizontal extent of the active area is taken to be this "
+            "value, i.e. the beam is assumed at least as wide as the sample, "
+            "so the sample bounds the illuminated width.\n"
+            "Only the absolute active area in square meter uses it; a "
+            "structure factor on a relative scale is unaffected."
+        )
+        sizesLayout.addWidget(self.W, 1, 1)
+
+        sizesLayout.addWidget(qt.QLabel("Beam flux:"), 2, 0)
+        self.beamFlux = qt.QDoubleSpinBox()
+        self.beamFlux.setRange(0.0, 1e30)
+        self.beamFlux.setDecimals(3)
+        self.beamFlux.setSuffix(" ph/(s·mm²)")
+        self.beamFlux.setValue(0.0)
+        self.beamFlux.setToolTip(
+            "Incident photon flux density (Phi_0) at the sample position.\n"
+            "Called 'beam flux' here rather than Phi_0 or phi, to avoid "
+            "confusion with the sample-circle phi of the diffractometer.\n"
+            "Only needed for an absolutely scaled structure factor "
+            "(issue #15); leave at 0 if it has not been measured -- a "
+            "structure factor on a relative scale does not use it."
+        )
+        sizesLayout.addWidget(self.beamFlux, 2, 1)
 
+        modeLayout = qt.QHBoxLayout()
         self.analyticalButton = qt.QRadioButton("analytical beam shape")
         self.analyticalButton.setChecked(True)
         self.analyticalButton.setToolTip(
@@ -2594,14 +2636,33 @@ def __init__(self, parent=None):
             "Use a beam profile measured at the beamline. Required for a "
             "beam that is asymmetric or has more than one maximum."
         )
-        layout.addWidget(self.analyticalButton, 1, 0)
-        layout.addWidget(self.measuredButton, 1, 1)
-        verticalLayout.addLayout(layout)
-
-        verticalLayout.addWidget(self._createShapeGroup())
-        verticalLayout.addWidget(self._createProfileGroup())
-        verticalLayout.addWidget(self._createCenteringGroup())
-        verticalLayout.addWidget(self._createPreviewGroup())
+        modeLayout.addWidget(self.analyticalButton)
+        modeLayout.addWidget(self.measuredButton)
+
+        # Left column: the beam and sample. Right column: where the sample
+        # sits in the beam, and the resulting preview. Side by side rather
+        # than one long stack, so the dialog fits a normal screen instead of
+        # running off the bottom of it.
+        leftColumn = qt.QVBoxLayout()
+        leftColumn.addLayout(sizesLayout)
+        leftColumn.addLayout(modeLayout)
+        # Only the active beam model's settings take up space; the other is
+        # hidden rather than merely disabled, which used to reserve room for
+        # both at once.
+        self.beamModelStack = qt.QStackedWidget()
+        self.beamModelStack.addWidget(self._createShapeGroup())
+        self.beamModelStack.addWidget(self._createProfileGroup())
+        leftColumn.addWidget(self.beamModelStack)
+        leftColumn.addStretch(1)
+
+        rightColumn = qt.QVBoxLayout()
+        rightColumn.addWidget(self._createCenteringGroup())
+        rightColumn.addWidget(self._createPreviewGroup())
+
+        columns = qt.QHBoxLayout()
+        columns.addLayout(leftColumn, 1)
+        columns.addLayout(rightColumn, 1)
+        verticalLayout.addLayout(columns)
 
         buttons = qt.QDialogButtonBox(
             qt.QDialogButtonBox.Ok | qt.QDialogButtonBox.Cancel
@@ -2731,10 +2792,15 @@ def _createPreviewGroup(self):
         return group
 
     def _onModeChanged(self):
-        """Enable the widgets belonging to the selected beam model."""
+        """Show only the settings of the selected beam model.
+
+        The other group is hidden by switching the stacked page rather than
+        merely disabled, so it stops reserving layout space it is not using.
+        """
         analytical = self.analyticalButton.isChecked()
-        self.shapeGroup.setEnabled(analytical)
-        self.profileGroup.setEnabled(not analytical)
+        self.beamModelStack.setCurrentWidget(
+            self.shapeGroup if analytical else self.profileGroup
+        )
         self._updatePreview()
 
     def _onShapeChanged(self):
@@ -2786,7 +2852,9 @@ def showEvent(self, event):
             self.profilePlot = silx.gui.plot.Plot1D(self)
             self.profilePlot.setGraphXLabel("position rel. to sample center / microns")
             self.profilePlot.setGraphYLabel("normalized profile / mm$^{-1}$")
-            self.profilePlot.setMinimumHeight(220)
+            # Small enough that the two-column dialog still fits a normal
+            # screen; still tall enough to read the profile shape.
+            self.profilePlot.setMinimumHeight(160)
             self._previewLayout.insertWidget(0, self.profilePlot)
             self._updatePreview()
         qt.QDialog.showEvent(self, event)
@@ -2946,6 +3014,76 @@ def beamProfile(self):
             return self.analyticalProfile()
         return self.measuredProfile()
 
+    def sampleLength(self):
+        """Sample size along the beam, converted from millimeter to **meter**.
+
+        :rtype: float
+        """
+        return self.L.value() * 1e-3
+
+    def setSampleLength(self, value):
+        """Set the sample size along the beam, from **meter**.
+
+        :param float value: Sample size in meter.
+        """
+        self.L.setValue(value * 1e3)
+
+    def sampleWidth(self):
+        """Sample size perpendicular to the beam, in **meter**.
+
+        The dialog shows millimeter. This is the horizontal extent the active
+        area is taken to have: the beam is assumed at least as wide as the
+        sample, so the sample bounds the illuminated width rather than the
+        beam. Only :meth:`activeArea` uses it.
+
+        :rtype: float
+        """
+        return self.W.value() * 1e-3
+
+    def setSampleWidth(self, value):
+        """Set the sample size perpendicular to the beam, from **meter**.
+
+        :param float value: Sample size in meter.
+        """
+        self.W.setValue(value * 1e3)
+
+    def activeArea(self, alpha):
+        """Illuminated sample area at incidence angle ``alpha``, in m^2.
+
+        The dimensionless active-area correction applied to an integrated
+        intensity is
+        :meth:`~.beamprofile.BeamProfile.illuminated_area_fraction`; this is
+        the same quantity carrying its area, which is what an *absolute*
+        structure factor needs (issue #15). It assumes open post-sample
+        slits, and the horizontal extent of :meth:`sampleWidth`.
+
+        :param alpha: Incidence angle(s) in radian, any array shape.
+        :returns: The active area in square meter, broadcast over ``alpha``.
+        :rtype: numpy.ndarray
+        """
+        return activearea_corrections.beam_limited_area(
+            alpha, self.sampleWidth(), self.sampleLength(), self.beamProfile()
+        )
+
+    def beamFluxDensity(self):
+        """Incident flux density, converted to **photons/(s m^2)**.
+
+        The dialog shows photons/(s mm^2). ``0`` means unmeasured; pass it as
+        ``flux_density`` to :func:`~.measurement.scale_factor` only once it
+        is nonzero, since ``0`` there would zero the absolute scale rather
+        than fall back to the relative one.
+
+        :rtype: float
+        """
+        return self.beamFlux.value() * 1e6
+
+    def setBeamFluxDensity(self, value):
+        """Set the incident flux density from **photons/(s m^2)**.
+
+        :param float value: Flux density in photons/(s m^2).
+        """
+        self.beamFlux.setValue(value * 1e-6)
+
     def settings(self):
         """Return the dialog state as a plain dict.
 
@@ -2954,6 +3092,8 @@ def settings(self):
         shape = self.currentShape()
         return {
             "L": self.L.value(),
+            "W": self.W.value(),
+            "beam_flux": self.beamFlux.value(),
             "analytical": self.analyticalButton.isChecked(),
             "shape": shape.name,
             "shape_values": list(self._shape_values[shape.name]),
@@ -2981,6 +3121,10 @@ def setSettings(self, settings):
         with blockSignals(widgets):
             if "L" in settings:
                 self.L.setValue(settings["L"])
+            if "W" in settings:
+                self.W.setValue(settings["W"])
+            if "beam_flux" in settings:
+                self.beamFlux.setValue(settings["beam_flux"])
             if "analytical" in settings:
                 self.analyticalButton.setChecked(bool(settings["analytical"]))
                 self.measuredButton.setChecked(not settings["analytical"])
diff --git a/orgui/app/test/test_config_data.py b/orgui/app/test/test_config_data.py
index f6a4e39..a4f25ad 100644
--- a/orgui/app/test/test_config_data.py
+++ b/orgui/app/test/test_config_data.py
@@ -1,5 +1,6 @@
 import h5py
 import numpy as np
+from silx.gui import qt
 from silx.io.dictdump import dicttonx, nxtodict
 import pytest
 from types import SimpleNamespace
@@ -7,10 +8,24 @@
 from orgui.app.QReflectionSelector import HKLReflection
 from orgui.app.config_data import CorrectionState, ConfigData, ConfigHandler
 from orgui.app.database import config_data_from_json, config_data_to_json
+from orgui.app.peak1Dintegr import IntegrationCorrectionsDialog
 from orgui.datautils.xrayutils import CTRcalc, DetectorCalibration, HKLVlieg
 from orgui.reconstruction_job import _snapshot_assets
 
 
+@pytest.fixture(scope="session")
+def qapp():
+    """The Qt application, kept referenced for the whole test session.
+
+    A ``QApplication`` that is not held on to is garbage-collected, and
+    creating a widget afterwards aborts the interpreter.
+    """
+    application = qt.QApplication.instance()
+    if application is None:
+        application = qt.QApplication([])
+    return application
+
+
 def _make_config():
     unit_cell = CTRcalc.UnitCell([3.0, 4.0, 5.0], [90.0, 91.0, 120.0], name="bulk")
     unit_cell.addAtom("Pt", [0.0, 0.5, 0.25], 0.1, 0.2, 0.8, 1)
@@ -180,6 +195,100 @@ def test_enabled_pixel_repair_implies_mask_correction():
     assert captured.corrections.monitor_corrections == ("mondio",)
 
 
+def test_from_gui_captures_the_footprint_dialogs_inputs(qapp):
+    """L, W and the beam flux are captured only if the dialog was opened.
+
+    An unopened footprint dialog has nothing to record, which must be the
+    same "not recorded" state as a config written before these fields
+    existed -- not a silent zero.
+    """
+    config = _make_config()
+    unopened_gui = SimpleNamespace(
+        ubcalc=SimpleNamespace(
+            detectorCal=config.detector,
+            crystal=config.unit_cell,
+            ubCal=config.ub_calculator,
+            mu=config.mu,
+            chi=config.chi,
+            phi=config.phi,
+            n=config.refraction_index,
+        ),
+        scanSelector=SimpleNamespace(
+            get_integration_options=lambda: {
+                "mask": False,
+                "solid_angle": False,
+                "polarization": False,
+            },
+            correctionsDialog=SimpleNamespace(footprintOptions=None),
+        ),
+        excludedImagesDialog=SimpleNamespace(
+            getData=lambda: np.empty(0, dtype=np.int64)
+        ),
+    )
+    unopened = ConfigData.from_gui(unopened_gui)
+    assert unopened.corrections.sample_length_m is None
+    assert unopened.corrections.sample_width_m is None
+    assert unopened.corrections.beam_flux_density is None
+
+    footprint_dialog = IntegrationCorrectionsDialog()
+    try:
+        footprint_dialog.L.setValue(2.5)
+        footprint_dialog.W.setValue(7.5)
+        footprint_dialog.beamFlux.setValue(4.2)
+        gui = SimpleNamespace(**unopened_gui.__dict__)
+        gui.scanSelector = SimpleNamespace(
+            get_integration_options=unopened_gui.scanSelector.get_integration_options,
+            correctionsDialog=SimpleNamespace(footprintOptions=footprint_dialog),
+        )
+
+        captured = ConfigData.from_gui(gui)
+
+        assert captured.corrections.sample_length_m == pytest.approx(2.5e-3)
+        assert captured.corrections.sample_width_m == pytest.approx(7.5e-3)
+        assert captured.corrections.beam_flux_density == pytest.approx(4.2e6)
+    finally:
+        footprint_dialog.deleteLater()
+
+
+def test_apply_to_gui_restores_the_footprint_dialogs_inputs(qapp):
+    """Restoring a config sets L, W and the beam flux on the shared dialog."""
+    config = _make_config()
+    config.corrections = CorrectionState(
+        sample_length_m=4e-3,
+        sample_width_m=9e-3,
+        beam_flux_density=3e12,
+    )
+    footprint_dialog = IntegrationCorrectionsDialog()
+    try:
+        corrections_dialog = SimpleNamespace(
+            footprintOptions_shared=lambda: footprint_dialog
+        )
+        gui = SimpleNamespace(
+            ubcalc=SimpleNamespace(
+                detectorCal=config.detector,
+                crystal=config.unit_cell,
+                ubCal=config.ub_calculator,
+                mu=config.mu,
+                chi=config.chi,
+                phi=config.phi,
+                n=config.refraction_index,
+            ),
+            scanSelector=SimpleNamespace(
+                get_integration_options=lambda: {},
+                set_integration_options=lambda options: None,
+                correctionsDialog=corrections_dialog,
+            ),
+        )
+
+        config.apply_to_gui(gui)
+
+        assert footprint_dialog.sampleLength() == pytest.approx(4e-3)
+        assert footprint_dialog.sampleWidth() == pytest.approx(9e-3)
+        assert footprint_dialog.beamFluxDensity() == pytest.approx(3e12)
+    finally:
+        footprint_dialog.deleteLater()
+
+
 def test_apply_to_gui_sets_reconstruction_normalization_attributes():
     config = _make_config()
     config.corrections = CorrectionState(
diff --git a/orgui/app/test/test_config_nexus_layout.py b/orgui/app/test/test_config_nexus_layout.py
index 0d567a5..30e6035 100644
--- a/orgui/app/test/test_config_nexus_layout.py
+++ b/orgui/app/test/test_config_nexus_layout.py
@@ -62,6 +62,9 @@ def _populated_corrections():
         background_asset="assets/bg",
         background_variance_asset="assets/bgvar",
         uncertainty_provenance={"background": "measured"},
+        sample_length_m=5e-3,
+        sample_width_m=3e-3,
+        beam_flux_density=1.2e16,
     )
 
 
diff --git a/orgui/app/test/test_integration_corrections_dialog.py b/orgui/app/test/test_integration_corrections_dialog.py
index c395aff..9792cbe 100644
--- a/orgui/app/test/test_integration_corrections_dialog.py
+++ b/orgui/app/test/test_integration_corrections_dialog.py
@@ -263,14 +263,16 @@ def test_offset_spin_box_is_micrometers(dialog, tmp_path):
 
 
 def test_mode_switch_enables_the_matching_widgets(dialog):
-    """Only the widgets of the selected beam model are editable."""
-    assert dialog.shapeGroup.isEnabled()
-    assert not dialog.profileGroup.isEnabled()
+    """Only the widgets of the selected beam model are shown.
+
+    The inactive group is a hidden page of ``beamModelStack`` rather than a
+    merely disabled widget, so it stops reserving layout space.
+    """
+    assert dialog.beamModelStack.currentWidget() is dialog.shapeGroup
 
     dialog.measuredButton.setChecked(True)
 
-    assert not dialog.shapeGroup.isEnabled()
-    assert dialog.profileGroup.isEnabled()
+    assert dialog.beamModelStack.currentWidget() is dialog.profileGroup
 
 
 def test_preview_summary_reports_width_and_centroid(dialog, tmp_path):
@@ -350,6 +352,8 @@ def test_settings_round_trip(dialog, tmp_path):
     path = tmp_path / "gauss.dat"
     _write_gaussian_profile(path, 100e-6)
     dialog.L.setValue(2.25)
+    dialog.W.setValue(7.5)
+    dialog.beamFlux.setValue(4.2)
     dialog.measuredButton.setChecked(True)
     dialog.profileFileEdit.setText(str(path))
     dialog.loadProfile()
@@ -402,3 +406,100 @@ def test_an_unreadable_profile_does_not_switch_the_beam(dialog, tmp_path):
 
     assert dialog.analyticalButton.isChecked()
     assert isinstance(dialog.beamProfile(), DistributionBeamProfile)
+
+
+def test_sample_sizes_are_millimeters(dialog):
+    """Both sample sizes are shown in millimeter and handed over in meter."""
+    dialog.L.setValue(2.5)
+    dialog.W.setValue(7.5)
+
+    assert dialog.L.suffix().strip() == "mm"
+    assert dialog.W.suffix().strip() == "mm"
+    assert dialog.sampleLength() == pytest.approx(2.5e-3)
+    assert dialog.sampleWidth() == pytest.approx(7.5e-3)
+
+
+def test_sample_size_setters_are_the_getters_inverse(dialog):
+    """``setSampleLength``/``setSampleWidth`` round-trip through meter."""
+    dialog.setSampleLength(4e-3)
+    dialog.setSampleWidth(9e-3)
+
+    assert dialog.sampleLength() == pytest.approx(4e-3)
+    assert dialog.sampleWidth() == pytest.approx(9e-3)
+
+
+def test_beam_flux_is_photons_per_second_per_square_millimeter(dialog):
+    """The beam-flux field is shown per mm^2 and handed over per m^2.
+
+    Named 'beam flux' rather than Phi_0 or phi in the UI, to avoid confusion
+    with the diffractometer's sample-circle phi.
+    """
+    assert dialog.beamFlux.value() == 0.0
+    assert dialog.beamFluxDensity() == 0.0
+
+    dialog.beamFlux.setValue(2.5)
+
+    assert dialog.beamFluxDensity() == pytest.approx(2.5e6)
+
+    dialog.setBeamFluxDensity(3e12)
+
+    assert dialog.beamFlux.value() == pytest.approx(3e6)
+    assert dialog.beamFluxDensity() == pytest.approx(3e12)
+
+
+def test_active_area_carries_the_width_the_fraction_does_not(dialog):
+    """``activeArea`` is the applied correction with its area put back.
+
+    ``illuminated_area_fraction`` is the active-area correction for open
+    post-sample slits, but it is normalized to a uniform beam and is
+    therefore dimensionless. The absolute scale of issue #15 needs square
+    meters, which is the same quantity times the illuminated width -- taken
+    to be the sample width, on the assumption that the beam is at least as
+    wide as the sample.
+    """
+    dialog.L.setValue(5.0)
+    dialog.W.setValue(3.0)
+    profile = dialog.beamProfile()
+
+    area = dialog.activeArea(ALPHAS)
+    fraction = profile.illuminated_area_fraction(ALPHAS, 5e-3)
+
+    np.testing.assert_allclose(area, 3e-3 * 5e-3 * fraction, rtol=1e-12)
+    # The width scales the area and nothing else: doubling it doubles the
+    # area at every angle, and leaves the dimensionless factor alone.
+    dialog.W.setValue(6.0)
+    np.testing.assert_allclose(dialog.activeArea(ALPHAS), 2.0 * area, rtol=1e-12)
+    np.testing.assert_allclose(
+        profile.illuminated_area_fraction(ALPHAS, 5e-3), fraction, rtol=1e-12
+    )
+
+
+def test_the_area_fraction_is_the_open_slit_area_correction(dialog):
+    """The applied factor carries a ``1/sin(alpha)`` active-area dependence.
+
+    This is what makes skipping ``geometrycorrections.area_correction``'s
+    ``1/sin(delta)`` right rather than a missing correction: the open-slit
+    active area is set by the footprint, and the beam-profile factor already
+    is it. Once the footprint exceeds the beam the factor goes as
+    ``1/sin(alpha)``; below that it rolls over towards one as the beam
+    overfills the sample, which a bare ``1/sin(alpha)`` would not do.
+    """
+    dialog.L.setValue(10.0)
+    (fwhm,) = _select_shape(dialog, "Gaussian")
+    fwhm.setValue(100.0)
+    profile = dialog.beamProfile()
+
+    # sqrt(2 pi) sigma / L, the limit the product approaches once the
+    # footprint exceeds the beam. At 2 degrees the footprint is 3.5 times
+    # the FWHM and the erf is saturated to a few parts in 1e5; by 5 degrees
+    # it holds to seven digits.
+    sigma = 100e-6 / (2.0 * np.sqrt(2.0 * np.log(2.0)))
+    limit = np.sqrt(2.0 * np.pi) * sigma / 10e-3
+
+    wide = np.deg2rad(np.array([2.0, 5.0, 10.0]))
+    product = profile.illuminated_area_fraction(wide, 10e-3) * np.sin(wide)
+    np.testing.assert_allclose(product, limit, rtol=1e-4)
+    np.testing.assert_allclose(product[1:], limit, rtol=1e-7)
+
+    grazing = profile.illuminated_area_fraction(np.deg2rad(0.02), 10e-3)
+    assert 0.99 < float(grazing) <= 1.0

From f960b442f1452a8f6ed81bee4346711bc464869c Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Mon, 14 Sep 2026 13:27:28 -0400
Subject: [PATCH 17/33] feat: store the footprint dialog's beam shape with the
 configuration

---
 CHANGELOG.md                               | 12 ++-
 doc/source/release_notes.rst               |  2 +-
 orgui/app/config_data.py                   | 90 ++++++++++++++++++++++
 orgui/app/test/test_config_data.py         | 28 +++++++
 orgui/app/test/test_config_nexus_layout.py |  8 ++
 5 files changed, 136 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 74f64df..77c4b0f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -120,9 +120,15 @@ Scientific and analysis additions:
   are now recorded in a typed ``integration_corrections/footprint`` NeXus
   group beside the correction switches -- previously none of the three
   reached the saved configuration at all, so a stored active-area calculation
-  could not be reproduced from its own output. A configuration written before
-  they existed, or a dialog that was never opened, leaves the running dialog
-  exactly as it is rather than resetting it to defaults.
+  could not be reproduced from its own output. **The beam shape itself was
+  the same gap and is now closed too:** whether the beam is described
+  analytically or by a measured profile, the selected shape and its
+  parameters, the profile file and how to read it, and where the sample sits
+  in the beam are all recorded in a new ``integration_corrections/beam_shape``
+  group, in the same units the dialog itself shows them in. A configuration
+  written before any of this existed, or a dialog that was never opened,
+  leaves the running dialog exactly as it is rather than resetting it to
+  defaults.
 
 - **All correction factors collected into one package.** Every factor between
   detector counts and a structure factor now lives in
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 4d5a778..d001d0c 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -17,7 +17,7 @@ Scientific and analysis additions:
 
 - **The corrections dialog now asks for the sample size across the beam.** A second size ``W`` sits beside the existing sample size ``L``, in millimeter. It is the sample extent perpendicular to the beam in the surface plane, and it is taken to be the width of the illuminated area, on the assumption that the beam is at least as wide as the sample -- so the sample bounds the lit area rather than the beam. Nothing in a *relative* structure factor uses it: the active-area correction that is applied to an integrated intensity is ``illuminated_area_fraction``, which is dimensionless and unchanged, so no saved number moves. ``W`` supplies the missing input for the *absolute* active area in square meter, ``IntegrationCorrectionsDialog.activeArea``, which an absolutely scaled structure factor needs. The measurement is assumed throughout to be made with open post-sample slits and an area detector, which is what makes the footprint the active area; the slit-limited case, where ``1/(sin(delta) cos(alpha - beta_in))`` would apply instead, is not supported. Both size controls now say so in their tooltips.
 
-- **A beam flux input, and every footprint-dialog input, is now stored with the configuration.** The corrections dialog gains a beam flux field, the incident photon flux density needed together with the active area for an absolutely scaled structure factor (issue #15); called "beam flux" rather than ``Phi_0`` or ``phi`` to avoid confusion with the diffractometer's own sample-circle ``phi``. It, and the existing ``L`` and ``W`` sample sizes, are now recorded in a typed ``integration_corrections/footprint`` NeXus group beside the correction switches -- previously none of the three reached the saved configuration at all, so a stored active-area calculation could not be reproduced from its own output. A configuration written before they existed, or a dialog that was never opened, leaves the running dialog exactly as it is rather than resetting it to defaults.
+- **A beam flux input, and every footprint-dialog input, is now stored with the configuration.** The corrections dialog gains a beam flux field, the incident photon flux density needed together with the active area for an absolutely scaled structure factor (issue #15); called "beam flux" rather than ``Phi_0`` or ``phi`` to avoid confusion with the diffractometer's own sample-circle ``phi``. It, and the existing ``L`` and ``W`` sample sizes, are now recorded in a typed ``integration_corrections/footprint`` NeXus group beside the correction switches -- previously none of the three reached the saved configuration at all, so a stored active-area calculation could not be reproduced from its own output. **The beam shape itself was the same gap and is now closed too:** whether the beam is described analytically or by a measured profile, the selected shape and its parameters, the profile file and how to read it, and where the sample sits in the beam are all recorded in a new ``integration_corrections/beam_shape`` group, in the same units the dialog itself shows them in. A configuration written before any of this existed, or a dialog that was never opened, leaves the running dialog exactly as it is rather than resetting it to defaults.
 
 - **All correction factors collected into one package.** Every factor between detector counts and a structure factor now lives in ``orgui.datautils.xrayutils.corrections``, split by what it depends on: ``geometry`` (the z-axis Lorentz, rod-interception and area table), ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and polarization), ``normalization`` (counting time and monitor), ``roi``, and ``measurement``. The rocking integration, the stationary integration and the reciprocal-space reconstruction previously each carried their own copy of several of these; they now share one definition, so they cannot drift onto different scales. The package is physics only -- numbers in, numbers out -- and reads no scan object, configuration or widget; ``orgui.app`` ``integration_corrections`` is the adapter that supplies those. ``orgui.datautils.xrayutils.geometrycorrections`` and ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the moved modules. **No calculated value changes.**
 
diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index 63078bd..a77ba39 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -96,6 +96,22 @@ class CorrectionState:
     # an absolutely scaled structure factor (issue #15); a relative one does
     # not use it.
     beam_flux_density: float | None = None
+    # The beam shape the footprint dialog describes the incident beam with --
+    # analytical or measured, and every input either needs. Kept in the same
+    # units the dialog itself shows them in (IntegrationCorrectionsDialog.
+    # settings()), not converted to SI: an analytical shape's numeric values
+    # are only meaningful together with its name (a width in micrometer for
+    # one shape, a dimensionless flatness or skew for another), so there is
+    # no single physical unit to convert them to. ``None``/empty means "this
+    # configuration predates them, or the dialog was never opened".
+    beam_shape_analytical: bool | None = None
+    beam_shape_name: str | None = None
+    beam_shape_values: tuple[float, ...] = ()
+    beam_profile_file: str | None = None
+    beam_profile_content: str | None = None
+    beam_profile_unit: str | None = None
+    beam_profile_center: str | None = None
+    beam_profile_offset_um: float | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """Return a JSON-compatible correction-state dictionary."""
@@ -114,6 +130,9 @@ def from_dict(cls, values):
         values["excluded_frames"] = tuple(
             int(value) for value in values.get("excluded_frames", ())
         )
+        values["beam_shape_values"] = tuple(
+            float(value) for value in values.get("beam_shape_values", ())
+        )
         return cls(**values)
 
 
@@ -389,6 +408,19 @@ def corrections_to_nxdict(state):
                 "@beam_flux_density_unit": "1/(s m^2)",
             },
         ),
+        # The dialog's own display units, not SI: see CorrectionState.
+        "beam_shape": _nx_group(
+            {
+                "analytical": state.beam_shape_analytical,
+                "shape": state.beam_shape_name,
+                "profile_file": state.beam_profile_file,
+                "profile_content": state.beam_profile_content,
+                "profile_unit": state.beam_profile_unit,
+                "profile_center": state.beam_profile_center,
+                "profile_offset": state.beam_profile_offset_um,
+            },
+            units={"@profile_offset_unit": "micron"},
+        ),
     }
     if state.monitor_corrections:
         nxdict["normalization"]["monitor_corrections"] = _string_array(
@@ -398,6 +430,10 @@ def corrections_to_nxdict(state):
         nxdict["excluded_frames"] = np.asarray(
             state.excluded_frames, dtype=np.int64
         )
+    if state.beam_shape_values:
+        nxdict["beam_shape"]["shape_values"] = np.asarray(
+            state.beam_shape_values, dtype=np.float64
+        )
     if state.uncertainty_provenance:
         nxdict["uncertainty_provenance"] = _nx_group(
             dict(state.uncertainty_provenance)
@@ -464,6 +500,24 @@ def corrections_from_nxdict(nxdict):
     ):
         if key in footprint:
             values[name] = float(footprint[key])
+    beam_shape = _read_group(nxdict, "beam_shape")
+    if "analytical" in beam_shape:
+        values["beam_shape_analytical"] = bool(beam_shape["analytical"])
+    for name, key in (
+        ("beam_shape_name", "shape"),
+        ("beam_profile_file", "profile_file"),
+        ("beam_profile_content", "profile_content"),
+        ("beam_profile_unit", "profile_unit"),
+        ("beam_profile_center", "profile_center"),
+    ):
+        if key in beam_shape:
+            values[name] = str(beam_shape[key])
+    if "profile_offset" in beam_shape:
+        values["beam_profile_offset_um"] = float(beam_shape["profile_offset"])
+    if "shape_values" in beam_shape:
+        values["beam_shape_values"] = tuple(
+            float(v) for v in np.atleast_1d(beam_shape["shape_values"])
+        )
     return CorrectionState(**values)
 
 
@@ -659,10 +713,14 @@ def from_gui(cls, gui):
             sample_length_m = None
             sample_width_m = None
             beam_flux_density = None
+            beam_shape = {}
             if footprint_dialog is not None:
                 sample_length_m = footprint_dialog.sampleLength()
                 sample_width_m = footprint_dialog.sampleWidth()
                 beam_flux_density = footprint_dialog.beamFluxDensity()
+                # The dialog's own settings() dict, in its own display units;
+                # see CorrectionState.beam_shape_values.
+                beam_shape = footprint_dialog.settings()
             corrections = CorrectionState(
                 use_mask=bool(options.get("mask", False)) or repair_enabled,
                 use_background=getattr(gui, "background_image", None)
@@ -703,6 +761,14 @@ def from_gui(cls, gui):
                 sample_length_m=sample_length_m,
                 sample_width_m=sample_width_m,
                 beam_flux_density=beam_flux_density,
+                beam_shape_analytical=beam_shape.get("analytical"),
+                beam_shape_name=beam_shape.get("shape"),
+                beam_shape_values=tuple(beam_shape.get("shape_values", ())),
+                beam_profile_file=beam_shape.get("profile_file"),
+                beam_profile_content=beam_shape.get("profile_content"),
+                beam_profile_unit=beam_shape.get("profile_unit"),
+                beam_profile_center=beam_shape.get("profile_center"),
+                beam_profile_offset_um=beam_shape.get("profile_offset"),
             )
             roi = ROIState(
                 region=dict(options.get("region", {})),
@@ -787,6 +853,8 @@ def apply_to_gui(self, gui):
                 self.corrections.sample_length_m is not None
                 or self.corrections.sample_width_m is not None
                 or self.corrections.beam_flux_density is not None
+                or self.corrections.beam_shape_name is not None
+                or self.corrections.beam_profile_file is not None
             ):
                 corrections_dialog = getattr(
                     gui.scanSelector, "correctionsDialog", None
@@ -805,6 +873,28 @@ def apply_to_gui(self, gui):
                         footprint_dialog.setBeamFluxDensity(
                             self.corrections.beam_flux_density
                         )
+                    # The dialog's own setSettings(), in its own display
+                    # units; only the keys this configuration actually
+                    # recorded are passed, so the rest of the dialog is left
+                    # alone (setSettings()'s own contract).
+                    beam_shape = {}
+                    for key, value in (
+                        ("analytical", self.corrections.beam_shape_analytical),
+                        ("shape", self.corrections.beam_shape_name),
+                        ("profile_file", self.corrections.beam_profile_file),
+                        ("profile_content", self.corrections.beam_profile_content),
+                        ("profile_unit", self.corrections.beam_profile_unit),
+                        ("profile_center", self.corrections.beam_profile_center),
+                        ("profile_offset", self.corrections.beam_profile_offset_um),
+                    ):
+                        if value is not None:
+                            beam_shape[key] = value
+                    if self.corrections.beam_shape_values:
+                        beam_shape["shape_values"] = list(
+                            self.corrections.beam_shape_values
+                        )
+                    if beam_shape:
+                        footprint_dialog.setSettings(beam_shape)
         gui.reconstruction_normalize_exposure = self.corrections.normalize_exposure
         gui.reconstruction_monitor_corrections = self.corrections.monitor_corrections
         if (
diff --git a/orgui/app/test/test_config_data.py b/orgui/app/test/test_config_data.py
index a4f25ad..3795d66 100644
--- a/orgui/app/test/test_config_data.py
+++ b/orgui/app/test/test_config_data.py
@@ -229,12 +229,24 @@ def test_from_gui_captures_the_footprint_dialogs_inputs(qapp):
     assert unopened.corrections.sample_length_m is None
     assert unopened.corrections.sample_width_m is None
     assert unopened.corrections.beam_flux_density is None
+    assert unopened.corrections.beam_shape_name is None
+    assert unopened.corrections.beam_shape_values == ()
 
     footprint_dialog = IntegrationCorrectionsDialog()
     try:
         footprint_dialog.L.setValue(2.5)
         footprint_dialog.W.setValue(7.5)
         footprint_dialog.beamFlux.setValue(4.2)
+        footprint_dialog.shapeSelector.setCurrentIndex(
+            footprint_dialog.shapeSelector.findText("Trapezoid")
+        )
+        base, flat = footprint_dialog.shapeParameters[:2]
+        base.setValue(90.0)
+        flat.setValue(30.0)
+        footprint_dialog.profileCenter.setCurrentIndex(
+            footprint_dialog.profileCenter.findText("median")
+        )
+        footprint_dialog.profileOffset.setValue(-12.5)
         gui = SimpleNamespace(**unopened_gui.__dict__)
         gui.scanSelector = SimpleNamespace(
             get_integration_options=unopened_gui.scanSelector.get_integration_options,
@@ -246,6 +258,11 @@ def test_from_gui_captures_the_footprint_dialogs_inputs(qapp):
         assert captured.corrections.sample_length_m == pytest.approx(2.5e-3)
         assert captured.corrections.sample_width_m == pytest.approx(7.5e-3)
         assert captured.corrections.beam_flux_density == pytest.approx(4.2e6)
+        assert captured.corrections.beam_shape_analytical is True
+        assert captured.corrections.beam_shape_name == "Trapezoid"
+        assert captured.corrections.beam_shape_values == (90.0, 30.0)
+        assert captured.corrections.beam_profile_center == "median"
+        assert captured.corrections.beam_profile_offset_um == pytest.approx(-12.5)
     finally:
         footprint_dialog.deleteLater()
 
@@ -257,6 +274,11 @@ def test_apply_to_gui_restores_the_footprint_dialogs_inputs(qapp):
         sample_length_m=4e-3,
         sample_width_m=9e-3,
         beam_flux_density=3e12,
+        beam_shape_analytical=True,
+        beam_shape_name="Trapezoid",
+        beam_shape_values=(90.0, 30.0),
+        beam_profile_center="median",
+        beam_profile_offset_um=-12.5,
     )
     footprint_dialog = IntegrationCorrectionsDialog()
     try:
@@ -285,6 +307,12 @@ def test_apply_to_gui_restores_the_footprint_dialogs_inputs(qapp):
         assert footprint_dialog.sampleLength() == pytest.approx(4e-3)
         assert footprint_dialog.sampleWidth() == pytest.approx(9e-3)
         assert footprint_dialog.beamFluxDensity() == pytest.approx(3e12)
+        assert footprint_dialog.analyticalButton.isChecked() is True
+        assert footprint_dialog.currentShape().name == "Trapezoid"
+        assert footprint_dialog.shapeParameters[0].value() == pytest.approx(90.0)
+        assert footprint_dialog.shapeParameters[1].value() == pytest.approx(30.0)
+        assert footprint_dialog.profileCenter.currentText() == "median"
+        assert footprint_dialog.profileOffset.value() == pytest.approx(-12.5)
     finally:
         footprint_dialog.deleteLater()
 
diff --git a/orgui/app/test/test_config_nexus_layout.py b/orgui/app/test/test_config_nexus_layout.py
index 30e6035..0037bd7 100644
--- a/orgui/app/test/test_config_nexus_layout.py
+++ b/orgui/app/test/test_config_nexus_layout.py
@@ -65,6 +65,14 @@ def _populated_corrections():
         sample_length_m=5e-3,
         sample_width_m=3e-3,
         beam_flux_density=1.2e16,
+        beam_shape_analytical=False,
+        beam_shape_name="Trapezoid",
+        beam_shape_values=(90.0, 30.0),
+        beam_profile_file="profiles/beam.dat",
+        beam_profile_content="height scan (-dI/dz)",
+        beam_profile_unit="mm",
+        beam_profile_center="median",
+        beam_profile_offset_um=-12.5,
     )
 
 

From 3033f8804dc54f800a44401ec921671d3cb46285 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Mon, 14 Sep 2026 13:33:01 -0400
Subject: [PATCH 18/33] perf: numpyparallel calc of polarization correction for
 moving detector

---
 CHANGELOG.md                                  |  18 +++
 doc/design/ctr_structure_factor_scale.md      |  39 +++++
 doc/source/release_notes.rst                  |   2 +
 orgui/app/orGUI.py                            |  60 +++++---
 orgui/app/test/test_orGUI_reflections.py      |  63 ++++++++
 .../xrayutils/DetectorCalibration.py          | 135 ++++++++++++++++++
 .../xrayutils/corrections/detector.py         |  96 +++++++++++++
 .../test/test_DetectorCalibration.py          | 106 ++++++++++++++
 .../test/test_corrections_detector.py         |  94 ++++++++++++
 9 files changed, 596 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 77c4b0f..72c397f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,24 @@ Scientific and analysis additions:
   than as a region mean and is unchanged; correcting it there would need the
   array rebuilt per frame.
 
+- **The arm-following polarization correction no longer makes a mu-scan
+  rocking reduction unusably slow.** It evaluates once and broadcasts when
+  the incidence angle and the arm are constant across a curve, which covers
+  every fixed-arm scan and every th-scan rocking curve; a mu scan rocks the
+  incidence angle itself, and a reflectivity rocking curve additionally
+  tracks the arm at twice it, so nothing was constant and it fell back to a
+  Python loop calling the per-frame correction once per point -- about 20
+  seconds for a thousand-point mu scan, a minute or more for several
+  thousand, with no error, just a reduction that looked stuck. It is now one
+  batched call per rocking curve instead of one per frame
+  (``corrections.detector.polarization_arm_correction_frames``, backed by
+  ``DetectorCalibration.Detector2D_SXRD._tthAzimuthAtArms``), verified
+  against the per-frame loop to floating-point precision and measured about
+  7-8x faster end to end. A stationary integration tracking a rod across the
+  detector has no single region to batch on and keeps the per-frame loop,
+  unchanged. **No saved value changes** -- this is the same correction,
+  computed the same way, just not one frame at a time.
+
 - **Rocking and stationary integration now produce the same structure factor.**
   *This changes saved numbers in both modes.* A rocking scan and a stationary
   scan of the same rod previously differed by exactly exposure time times
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
index eb892d6..4a14c9c 100644
--- a/doc/design/ctr_structure_factor_scale.md
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -265,6 +265,45 @@ apply to it; that path would need the array itself rebuilt per frame, which is
 a detector-sized evaluation per frame and belongs with the rest of the
 reconstruction work in section 7.
 
+**A mu scan made this factor's cost visible in a way a th scan never does.**
+`_polarizationArmFactor` evaluates once and broadcasts when its inputs are
+uniform, which is every fixed-arm scan and every th-scan rocking curve, where
+alpha does not move. A mu scan rocks alpha itself, and a reflectivity rocking
+curve additionally tracks `gamma_arm = 2 alpha`, so nothing is uniform and it
+fell back to a plain Python loop calling `polarization_arm_correction` once
+per frame - about 0.2 ms each, dominated by the pyFAI geometry evaluation
+inside it, not by anything Python-level. `rocking_integrate` calls it once per
+`s` point, so the real cost is `O(n_s * n_pts)` individual calls: about 20 s
+for a thousand-point mu scan, a minute or more for several thousand - a
+reduction that used to finish in a blink became "stuck," with no error, just
+one warning every processing pass repeating slowly enough to look like it had
+died.
+
+Threading the loop does not help - the workload is GIL-bound, measured
+*slower* than serial at every worker count tried. The fix is
+`polarization_arm_correction_frames`: one region, many frames, batched into
+one call instead of `n_pts` of them.
+`Detector2D_SXRD._tthAzimuthAtArms` is what makes that possible - the
+position-only half of the geometry (`calc_cartesian_positions`, independent
+of the arm) is computed once and shared, and every frame's rotation is
+composed as a batched `(n_frames, 3, 3)` matrix stack via `armRotation`'s
+existing array support, applied as one `einsum` rather than pyFAI's
+single-geometry `calc_pos_zyx`/`rotation_matrix`. It deliberately bypasses the
+`(rot1, rot2, rot3)` round trip `paramAtArm` normally takes: that
+parameterization exists so a *single* geometry can be handed back to pyFAI,
+and reconstructing it from a rotation matrix costs a `scipy.Rotation` Euler
+decomposition - exactly what batching needs not to pay for the position-only
+half, and exactly the step this skips for the arm-varying half too, since the
+batched matrix is applied directly instead of decomposed and reconstructed.
+Verified against the per-frame loop to floating-point precision across
+several detector tilts, azimuthal references and a non-identity arm
+reference; measured about 7-8x faster end to end, turning a several-minute
+reduction into single-digit seconds. Parallax is not implemented in the
+batched path - orGUI never configures one, so this raises rather than
+silently diverging if that ever changes. A stationary integration tracking a
+rod across the detector has no single shared region to batch on and keeps the
+per-frame loop, unchanged.
+
 ### F6 - solid-angle correction applied to an already-summed ROI
 
 For a ROI-summed intensity, the raw sum over pixels *is* the angular integral
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index d001d0c..352bd3a 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -11,6 +11,8 @@ Scientific and analysis additions:
 
 - **The polarization correction now follows the detector arm.** *This changes saved numbers for scans that move the detector arm, and only those.* The per-pixel polarization array is built from the calibrated geometry, which is right only while the arm stays there. On a scan that drives the arm -- a reflectivity curve, where it follows twice the incidence angle -- the same pixel looks in a different direction on every frame, and the calibrated-position value understated the correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration paths now apply a per-frame factor, ``corrections.detector.polarization_arm_correction``, that moves the correction onto the arm position each frame was measured at. It is exactly one while the arm sits at its calibrated position, so a fixed-arm scan is bit-identical and needs no switch. The factor is a ratio of two region means rather than a rebuilt per-pixel array, which keeps the cost to a region-sized evaluation per frame; the polarization is not flat across a region at a large scattering angle, so the means matter. The detector solid angle needs no such correction: an arm rotation is a rigid rotation about the sample, so every pixel keeps its distance and its obliquity to its own line of sight, and the solid angle is invariant under it exactly. The reciprocal-space reconstruction applies the polarization per pixel rather than as a region mean and is unchanged; correcting it there would need the array rebuilt per frame.
 
+- **The arm-following polarization correction no longer makes a mu-scan rocking reduction unusably slow.** It evaluates once and broadcasts when the incidence angle and the arm are constant across a curve, which covers every fixed-arm scan and every th-scan rocking curve; a mu scan rocks the incidence angle itself, and a reflectivity rocking curve additionally tracks the arm at twice it, so nothing was constant and it fell back to a Python loop calling the per-frame correction once per point -- about 20 seconds for a thousand-point mu scan, a minute or more for several thousand, with no error, just a reduction that looked stuck. It is now one batched call per rocking curve instead of one per frame (``corrections.detector.polarization_arm_correction_frames``, backed by ``DetectorCalibration.Detector2D_SXRD._tthAzimuthAtArms``), verified against the per-frame loop to floating-point precision and measured about 7-8x faster end to end. A stationary integration tracking a rod across the detector has no single region to batch on and keeps the per-frame loop, unchanged. **No saved value changes** -- this is the same correction, computed the same way, just not one frame at a time.
+
 - **Rocking and stationary integration now produce the same structure factor.** *This changes saved numbers in both modes.* A rocking scan and a stationary scan of the same rod previously differed by exactly exposure time times monitor times the out-of-plane acceptance in degrees; they now agree. Four corrections changed. The rocking path gained the per-frame exposure and monitor normalization, applied inside the rocking integral so that a varying counting time or a drifting monitor is handled correctly rather than only on average; it now integrates the rocking angle in radian as the published expressions require, rather than in degrees; and it divides by the out-of-plane acceptance of its region of interest, without which a rod measured with regions resized along the scan came out with a distorted *shape* -- a factor 2.3 across a simulated Pt(111) rod -- and not merely a wrong scale. Separately, the detector **solid-angle correction no longer reaches a structure factor** in either mode: summing a region of interest already yields the complete angular integral, with every pixel weighted by the solid angle it subtends, so dividing by that solid angle again double-counted the detector obliquity (0.7 % for a detector at 1 m, 7 % at 0.3 m, varying across the detector and therefore a rod shape error). The switch stays, because that correction is the right one for a broad or diffuse feature where a differential cross section is wanted: it still scales the intensity counters, and is now measured over the same regions of interest and divided back out when ``F2_hkl`` is formed, so a structure factor is the same number whether or not it was enabled. Its tooltip and the ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps applying it uncompensated, since that path does form a differential cross section per pixel. For rocking scans the correction is applied when the curves are extracted, so whether to remove it again is read from the configuration stored with the scan; an older database where that cannot be established warns and is left uncompensated. Integrated rocking scans now store a ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit, which normalizations were applied, the acceptance used, whether the solid-angle correction was compensated, and the active-area assumption, so that a saved rod can be placed on a common scale afterwards. Rocking normalization uses the counters stored with the scan, so it requires a backend that declares ``exposure_time`` in ``auxillary_counters``; a missing counter is skipped and recorded rather than failing the integration. Existing configuration files load unchanged. This equivalence has now been checked on real data as well as in simulation: on a LaNiO3 rod measured both ways, the two modes agree to a median 1.03 along the rod, with the remaining spread explained by the resolution difference between them rather than by a normalization. At a Bragg peak on the same rod they differ by a factor of five, which is expected — a stationary region cannot collect a peak much wider than itself.
 
 - **The settings that decide what was integrated are now stored with every integration.** A reduction could previously not be reproduced from its own output: the background ROI margins, the automatic-sizing switches, the projected sample size, and the effective ``delta_s`` of a rocking scan were not written anywhere. They are now saved under ``configuration/orgui/roi_integration`` as typed groups carrying their units — ``region`` (sizes, margins, automatic sizing), ``advanced`` (sample size in meter, offsets, the inclination and projection switches) and ``rocking_scan`` (``delta_s`` and ``max_s``, with ``delta_s`` stored as the value actually used after the resolution clipping, not as typed). The correction switches move the same way: ``integration_corrections`` is now a group of typed datasets instead of one opaque JSON string, so a stored configuration can be read in any HDF5 browser. Databases written with the JSON layout are still read. The Lorentz, footprint and normalization switches are recorded alongside the others, and a configuration that predates them leaves those controls as the user has them rather than silently switching a correction off. ``C_solid_angle`` is now saved beside ``F2_hkl``, because the structure factor divides it back out and a saved rod cannot otherwise be returned to the intensity scale.
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index 0229749..22910b9 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -3499,6 +3499,17 @@ def _polarizationArmFactor(self, dc, row, column, row_size, column_size, alpha):
         constant arm is evaluated once and broadcast, which keeps the cost off
         the common path.
 
+        A rocking or reflectivity scan tracks one region across many frames
+        with the arm (and, for a mu scan, alpha itself) different on every
+        one -- so nothing is constant, only the region is. That is the case
+        :func:`~.corrections.detector.polarization_arm_correction_frames`
+        batches into one call instead of one per frame; evaluating the
+        per-frame geometry separately for every frame of a mu scan with
+        thousands of s points used to make the reduction take minutes. Only
+        when the region also changes frame to frame -- a stationary
+        integration tracking a rod across the detector -- is there no shared
+        region left to batch on, and this falls back to the per-frame loop.
+
         The arm position comes from :meth:`getArmAngles`, so this shares its
         convention with every other arm consumer in the application: a scan
         that knows nothing about an arm reports zero, which is the calibrated
@@ -3527,29 +3538,44 @@ def _polarizationArmFactor(self, dc, row, column, row_size, column_size, alpha):
                 np.asarray(delta_arm, dtype=np.float64),
             )
         )
+        if not row.size:
+            return np.ones(row.shape, dtype=np.float64)
 
-        def _at(index):
-            return detector_corrections.polarization_arm_correction(
-                dc,
-                row[index],
-                column[index],
-                row_size[index],
-                column_size[index],
-                alpha[index],
-                float(gamma_arm[index]),
-                float(delta_arm[index]),
+        def _is_constant(values):
+            return np.all(values == values.flat[0])
+
+        if _is_constant(alpha) and _is_constant(gamma_arm) and _is_constant(delta_arm):
+            constant = _is_constant(row) and _is_constant(column) and (
+                _is_constant(row_size) and _is_constant(column_size)
             )
+            if constant:
+                index = np.unravel_index(0, row.shape)
+                factor = detector_corrections.polarization_arm_correction(
+                    dc, row[index], column[index], row_size[index],
+                    column_size[index], alpha[index], float(gamma_arm[index]),
+                    float(delta_arm[index]),
+                )
+                return np.full(row.shape, factor)
 
-        constant = all(
-            np.all(values == values.flat[0]) if values.size else True
-            for values in (row, column, row_size, column_size, alpha,
-                           gamma_arm, delta_arm)
+        region_constant = (
+            _is_constant(row) and _is_constant(column)
+            and _is_constant(row_size) and _is_constant(column_size)
         )
-        if constant and row.size:
-            return np.full(row.shape, _at(np.unravel_index(0, row.shape)))
+        if region_constant:
+            index = np.unravel_index(0, row.shape)
+            return detector_corrections.polarization_arm_correction_frames(
+                dc, row[index], column[index], row_size[index],
+                column_size[index], alpha.ravel(), gamma_arm.ravel(),
+                delta_arm.ravel(),
+            ).reshape(row.shape)
+
         factor = np.ones(row.shape, dtype=np.float64)
         for index in np.ndindex(*row.shape):
-            factor[index] = _at(index)
+            factor[index] = detector_corrections.polarization_arm_correction(
+                dc, row[index], column[index], row_size[index],
+                column_size[index], alpha[index], float(gamma_arm[index]),
+                float(delta_arm[index]),
+            )
         return factor
 
     def getArmAngles(self, imageno=None):
diff --git a/orgui/app/test/test_orGUI_reflections.py b/orgui/app/test/test_orGUI_reflections.py
index 5a51656..101e1d8 100644
--- a/orgui/app/test/test_orGUI_reflections.py
+++ b/orgui/app/test/test_orGUI_reflections.py
@@ -940,6 +940,15 @@ def polarizationAtPoints(
         arm = 0.0 if gamma_arm is None else float(gamma_arm)
         return np.full(np.shape(row), 1.0 - 0.5 * arm**2, dtype=float)
 
+    def polarizationAtPointsFrames(self, row, column, alpha_i, gamma_arm, delta_arm):
+        """The batched counterpart, same closed form, one arm per frame."""
+        gamma_arm = np.asarray(gamma_arm, dtype=float)
+        factor = 1.0 - 0.5 * gamma_arm**2
+        return np.broadcast_to(
+            factor.reshape(factor.shape + (1,) * np.ndim(row)),
+            factor.shape + np.shape(row),
+        ).astype(float)
+
 
 def test_the_polarization_arm_factor_follows_a_moving_arm():
     """Finding F5: the factor is per frame and one at the calibrated position.
@@ -982,3 +991,57 @@ def test_the_polarization_arm_factor_broadcasts_a_constant_arm():
     assert fast.shape == (4,)
     np.testing.assert_allclose(fast, 1.0 / (1.0 - 0.5 * 0.2**2), rtol=1e-12)
     np.testing.assert_allclose(looped[:3], fast[:3], rtol=1e-12)
+
+
+def test_the_polarization_arm_factor_batches_a_varying_arm_on_one_region():
+    """A moving arm on one fixed region must take one batched call, not N.
+
+    This is the mu-scan performance fix: a rocking or reflectivity scan
+    tracks one region across a curve with the arm different every frame,
+    which used to force a Python loop calling ``polarizationAtPoints`` once
+    per frame -- slow enough that a scan with thousands of points made the
+    reduction take minutes. The routing in ``_polarizationArmFactor`` must
+    recognise "one region, many frames" and call the batched
+    ``polarizationAtPointsFrames`` exactly once, not fall back to the loop.
+    """
+    calls = SimpleNamespace(points=0, frames=0)
+
+    class CountingDetector(FakeArmPolarizationDetector):
+        def polarizationAtPoints(self, *args, **kwargs):
+            calls.points += 1
+            return super().polarizationAtPoints(*args, **kwargs)
+
+        def polarizationAtPointsFrames(self, *args, **kwargs):
+            calls.frames += 1
+            return super().polarizationAtPointsFrames(*args, **kwargs)
+
+    arms = np.linspace(0.0, 0.3, 50)
+    stub = SimpleNamespace(getArmAngles=lambda: (arms, np.zeros_like(arms)))
+
+    got = orGUI._polarizationArmFactor(
+        stub, CountingDetector(), 300.0, 240.0, 20.0, 20.0, 0.01
+    )
+
+    np.testing.assert_allclose(got, 1.0 / (1.0 - 0.5 * arms**2), rtol=1e-12)
+    assert calls.frames == 1, "one region and 50 frames must be one batched call"
+    assert calls.points == 1, "only the shared 'at home' evaluation, also batched"
+
+
+def test_the_polarization_arm_factor_still_loops_when_the_region_also_moves():
+    """A stationary scan tracking a rod has no single shared region to batch.
+
+    There, the per-frame region position is itself an array -- the ROI
+    follows the reflection across the detector -- so batching on "one
+    region" does not apply and the per-frame loop, unchanged, is still the
+    correct fallback.
+    """
+    row = np.array([300.0, 310.0, 320.0])
+    column = np.array([240.0, 242.0, 244.0])
+    arm = np.array([0.0, 0.1, 0.2])
+    stub = SimpleNamespace(getArmAngles=lambda: (arm, np.zeros_like(arm)))
+
+    got = orGUI._polarizationArmFactor(
+        stub, FakeArmPolarizationDetector(), row, column, 20.0, 20.0, 0.01
+    )
+
+    np.testing.assert_allclose(got, 1.0 / (1.0 - 0.5 * arm**2), rtol=1e-12)
diff --git a/orgui/datautils/xrayutils/DetectorCalibration.py b/orgui/datautils/xrayutils/DetectorCalibration.py
index 1d01f85..d18bd29 100644
--- a/orgui/datautils/xrayutils/DetectorCalibration.py
+++ b/orgui/datautils/xrayutils/DetectorCalibration.py
@@ -576,6 +576,14 @@ def polarizationAtPoints(self, x, y, alpha_i, gamma_arm=None, delta_arm=None):
         :rtype: numpy.ndarray
         """
         gamma, delta = self.surfaceAnglesPoint(x, y, alpha_i, gamma_arm, delta_arm)
+        return self._polarizationFromSurfaceAngles(alpha_i, gamma, delta)
+
+    def _polarizationFromSurfaceAngles(self, alpha_i, gamma, delta):
+        r"""The z-axis polarization expression of :meth:`polarizationAtPoints`.
+
+        Factored out so :meth:`polarizationAtPointsFrames` can share it
+        rather than recompute the same formula from different surface angles.
+        """
         fraction = self._polFactor
         p_hor = (
             1.0
@@ -588,6 +596,46 @@ def polarizationAtPoints(self, x, y, alpha_i, gamma_arm=None, delta_arm=None):
         p_ver = 1.0 - (np.sin(delta) ** 2) * (np.cos(gamma) ** 2)
         return fraction * p_hor + (1.0 - fraction) * p_ver
 
+    def polarizationAtPointsFrames(self, x, y, alpha_i, gamma_arm, delta_arm):
+        r"""Polarization correction of one set of points, at many arm positions.
+
+        Vectorized counterpart of :meth:`polarizationAtPoints` for the shape
+        of problem a rocking or reflectivity scan has: one region of
+        interest, many frames, each at its own incidence angle and arm
+        position. See :meth:`_tthAzimuthAtArms` for why this is one batched
+        evaluation instead of ``len(alpha_i)`` separate ones.
+
+        Unlike :meth:`polarizationAtPoints`, ``gamma_arm``/``delta_arm`` are
+        required here rather than defaulting to the calibrated position --
+        :meth:`polarizationAtPoints` already broadcasts a per-frame
+        ``alpha_i`` correctly at a *fixed* arm position (including the
+        calibrated one), so this method exists only for the case that does
+        not broadcast: the arm moving too.
+
+        :param x: detector coordinates along pyFAI dimension 1, in pixels,
+            any shape, shared by every frame.
+        :param y: detector coordinates along pyFAI dimension 2, same shape.
+        :param alpha_i: incidence angle per frame, shape ``(n_frames,)``, in
+            rad.
+        :param gamma_arm: detector arm position per frame, shape
+            ``(n_frames,)``, as true scattering angle ``gamma_p``, in rad.
+        :param delta_arm: detector arm position per frame, shape
+            ``(n_frames,)``.
+        :returns: The polarization correction, shape
+            ``(n_frames,) + numpy.shape(x)``.
+        :rtype: numpy.ndarray
+        """
+        alpha_i = np.asarray(alpha_i, dtype=np.float64)
+        tth, azimuth = self._tthAzimuthAtArms(x, y, gamma_arm, delta_arm)
+        gamma_p, delta_p = _primBeamFromTthAzimuth(tth, azimuth)
+        alpha = alpha_i.reshape(alpha_i.shape + (1,) * (gamma_p.ndim - 1))
+        gamma = np.arcsin(
+            np.cos(alpha) * np.sin(gamma_p)
+            - np.sin(alpha) * np.cos(delta_p) * np.cos(gamma_p)
+        )
+        delta = np.arcsin(np.sin(delta_p) * np.cos(gamma_p) / np.cos(gamma))
+        return self._polarizationFromSurfaceAngles(alpha, gamma, delta)
+
     def polarizationArray(self, shape=None):
         r"""Polarization correction of every detector pixel.
 
@@ -685,6 +733,93 @@ def _tthAzimuthAtArm(self, x, y, gamma_arm, delta_arm):
         tth = np.arctan2(np.sqrt(t1 * t1 + t2 * t2), t3)
         return tth, np.arctan2(t1, t2) + self._deltaChi
 
+    def _tthAzimuthAtArms(self, x, y, gamma_arm, delta_arm):
+        """:meth:`_tthAzimuthAtArm` for one set of points at many arm positions.
+
+        A rocking or reflectivity scan needs exactly this shape of problem:
+        one region of interest, many frames, each at its own arm position.
+        Computing it frame by frame repeats the position-only half of the
+        geometry -- pixel coordinates, minus the PONI, converted to a vector
+        from the sample -- which does not depend on the arm at all; only the
+        final rotation into the sample frame does (an arm rotates the
+        detector rigidly about the sample). This does that position step
+        once and applies every frame's rotation as one batched
+        matrix-vector product, instead of ``len(gamma_arm)`` separate calls
+        each repeating it.
+
+        Numerically this must reproduce :meth:`_tthAzimuthAtArm` called once
+        per frame; ``test_DetectorCalibration.py`` pins the two against each
+        other rather than against a closed form, because the closed form
+        *is* :meth:`_tthAzimuthAtArm`.
+
+        :param x: Pixel row (pyFAI dimension 1), any shape, shared by every
+            frame.
+        :param y: Pixel column (pyFAI dimension 2), same shape as ``x``.
+        :param gamma_arm: Arm ``gamma_p`` per frame, shape ``(n_frames,)``.
+        :param delta_arm: Arm ``delta_p`` per frame, shape ``(n_frames,)``.
+        :returns: ``(tth, azimuth)``, each shape ``(n_frames,) + x.shape``,
+            in rad, azimuth already offset by the azimuthal reference.
+        :rtype: tuple
+        :raises NotImplementedError: If a parallax correction is configured.
+            orGUI never configures one -- :meth:`_tthAzimuthAtArm` is always
+            called with ``do_parallax=True``, but that only has an effect
+            once :meth:`~pyFAI.geometry.Geometry.set_parallax` has been
+            called, which nothing in this repository does.
+        """
+        if self._parallax is not None:
+            raise NotImplementedError(
+                "the batched arm-position geometry does not implement the "
+                "parallax correction; call _tthAzimuthAtArm per frame "
+                "instead if one has been configured"
+            )
+        x = np.asarray(x, dtype=np.float64)
+        y = np.asarray(y, dtype=np.float64)
+        gamma_arm = np.asarray(gamma_arm, dtype=np.float64)
+        delta_arm = np.asarray(delta_arm, dtype=np.float64)
+        point_shape = x.shape
+
+        # The position-only half: pixel coordinates minus the PONI, as a
+        # vector from the sample. Computed once, shared by every frame.
+        # Reproduces the non-cython branch of calc_pos_zyx exactly, which is
+        # what a per-frame param there would also fall back to.
+        p1, p2, p3 = self.detector.calc_cartesian_positions(x, y)
+        p1 = (np.asarray(p1, dtype=np.float64) - self.poni1).ravel()
+        p2 = (np.asarray(p2, dtype=np.float64) - self.poni2).ravel()
+        if p3 is None:
+            p3 = np.full(p1.shape, self._dist, dtype=np.float64)
+        else:
+            p3 = (np.asarray(p3, dtype=np.float64) + self._dist).ravel()
+        coord_det = np.stack((p1, p2, p3), axis=0)  # (3, n_points)
+
+        # Every frame's rotation, batched: the arm rotation (which is where
+        # the frames differ) composed with the fixed calibrated-position
+        # rotation, without the round trip through the (rot1, rot2, rot3)
+        # parameterization -- pyFAI's own rotation_matrix() builds one
+        # matrix for one geometry, not a stack of them, so paramAtArm's
+        # angle decomposition exists only so a *scalar* param can be handed
+        # back to it. Skipping that here is what makes this batchable; see
+        # armAdjustedParam for the same composition with it.
+        relative = armRotation(gamma_arm, delta_arm) @ self._R_arm_reference.T
+        relabel = azimuthRelabel(self._deltaChi)
+        home = pyFAIRotationMatrix(*self.param[3:6])
+        rotation = relabel.T @ relative @ relabel @ home  # (n_frames, 3, 3)
+
+        coord_sample = np.einsum("nij,jm->nim", rotation, coord_det)
+        t1, t2, t3 = coord_sample[:, 0], coord_sample[:, 1], coord_sample[:, 2]
+
+        orientation = self.detector.orientation
+        if orientation in (1, 2):
+            t1 = -t1
+        if orientation in (1, 4):
+            t2 = -t2
+
+        out_shape = (gamma_arm.shape[0],) + point_shape
+        t1 = t1.reshape(out_shape)
+        t2 = t2.reshape(out_shape)
+        t3 = t3.reshape(out_shape)
+        tth = np.arctan2(np.sqrt(t1 * t1 + t2 * t2), t3)
+        return tth, np.arctan2(t1, t2) + self._deltaChi
+
     def surfaceAngles(self, alpha_i, shape=None):
         """Angles in the reference frame, where the crystal is tilted by alpha_i.
 
diff --git a/orgui/datautils/xrayutils/corrections/detector.py b/orgui/datautils/xrayutils/corrections/detector.py
index d6f543b..b445c47 100644
--- a/orgui/datautils/xrayutils/corrections/detector.py
+++ b/orgui/datautils/xrayutils/corrections/detector.py
@@ -339,3 +339,99 @@ def polarization_arm_correction(
         samples=samples,
     )
     return at_arm / at_home
+
+
+def polarization_arm_correction_frames(
+    detector,
+    row,
+    column,
+    row_size,
+    column_size,
+    alpha,
+    gamma_arm,
+    delta_arm,
+    samples=17,
+):
+    r"""Many frames of :func:`polarization_arm_correction`, one region.
+
+    A rocking or reflectivity scan needs exactly this: one region of
+    interest, tracked across many frames, each with its own incidence angle
+    and arm position. Calling :func:`polarization_arm_correction` once per
+    frame is correct but repeats the sample-grid geometry evaluation from
+    scratch every time; with the region and its grid fixed for the whole
+    call, evaluating every frame's angles as one batched matrix-vector
+    product (:meth:`~.DetectorCalibration.Detector2D_SXRD.polarizationAtPointsFrames`)
+    instead of ``len(alpha)`` separate calls measures about ten times faster
+    on a 300-frame rocking curve -- the difference between a mu scan
+    finishing in seconds and taking minutes.
+
+    :param detector: A
+        :class:`~orgui.datautils.xrayutils.DetectorCalibration.Detector2D_SXRD`.
+    :param float row: Region centre row, in pixels along pyFAI dimension 1.
+        A single region, shared by every frame -- unlike
+        :func:`polarization_arm_correction`, this does not accept a region
+        that also moves frame to frame; use that function in a loop for such
+        a scan instead.
+    :param float column: Region centre column, in pixels along pyFAI
+        dimension 2.
+    :param float row_size: Region height in pixels.
+    :param float column_size: Region width in pixels.
+    :param alpha: Incidence angle per frame, shape ``(n_frames,)``, in
+        radian.
+    :param gamma_arm: Detector arm position per frame, shape
+        ``(n_frames,)``, in radian.
+    :param delta_arm: Detector arm position per frame, shape
+        ``(n_frames,)``, in radian.
+    :param int samples: Upper bound on the sample count per direction.
+    :returns: The multiplicative correction per frame, shape
+        ``(n_frames,)``. ``1.0`` at a frame whose arm sits at the calibrated
+        position, and at a frame whose region position or arm is not finite
+        -- a frame on which the rod never reached the detector, which
+        carries no counts to correct.
+    :rtype: numpy.ndarray
+    """
+    alpha, gamma_arm, delta_arm = np.broadcast_arrays(
+        np.asarray(alpha, dtype=np.float64),
+        np.asarray(gamma_arm, dtype=np.float64),
+        np.asarray(delta_arm, dtype=np.float64),
+    )
+    out = np.ones(alpha.shape, dtype=np.float64)
+    if not np.isfinite(float(row)) or not np.isfinite(float(column)):
+        return out
+
+    # Non-finite frames are skipped rather than computed and masked, so they
+    # cannot raise a spurious warning from evaluating trigonometry on a NaN
+    # or infinite arm angle; see roi_mean_inverse_solid_angle for the same
+    # pattern. They stay at the neutral 1.0 already in `out`.
+    defined = np.isfinite(alpha) & np.isfinite(gamma_arm) & np.isfinite(delta_arm)
+    if not np.any(defined):
+        return out
+
+    rows, columns = _roi_sample_grid(
+        float(row), float(column), float(row_size), float(column_size), samples
+    )
+    grid_rows, grid_columns = np.meshgrid(rows, columns, indexing="ij")
+    grid_rows = np.ascontiguousarray(grid_rows.ravel())
+    grid_columns = np.ascontiguousarray(grid_columns.ravel())
+
+    alpha_defined = alpha[defined]
+    at_home = np.mean(
+        1.0
+        / detector.polarizationAtPoints(
+            grid_rows[None, :], grid_columns[None, :], alpha_defined[:, None]
+        ),
+        axis=-1,
+    )
+    at_arm = np.mean(
+        1.0
+        / detector.polarizationAtPointsFrames(
+            grid_rows,
+            grid_columns,
+            alpha_defined,
+            gamma_arm[defined],
+            delta_arm[defined],
+        ),
+        axis=-1,
+    )
+    out[defined] = at_arm / at_home
+    return out
diff --git a/orgui/datautils/xrayutils/test/test_DetectorCalibration.py b/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
index ef02ac7..37b5a34 100644
--- a/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
+++ b/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
@@ -710,6 +710,112 @@ def test_reference_rejects_improper_rotations(self):
         with self.assertRaises(ValueError):
             det.setArmReference()  # neither
 
+    def test_batched_arm_matches_the_per_frame_geometry(self):
+        """``_tthAzimuthAtArms`` must reproduce ``_tthAzimuthAtArm`` in a loop.
+
+        A rocking or reflectivity scan tracks one region across many frames,
+        each at its own arm position -- what ``_tthAzimuthAtArms`` batches
+        into one call instead of one per frame, to keep a mu scan with
+        thousands of points from taking minutes (see
+        ``doc/design/ctr_structure_factor_scale.md`` finding F5). There is
+        no independent closed form for this: :meth:`_tthAzimuthAtArm` is the
+        closed form, verified elsewhere in this class, so correctness here
+        means reproducing it exactly for every arm position and detector
+        configuration those tests already cover.
+        """
+        rows = np.linspace(3.0, 900.0, 11)
+        columns = np.linspace(9.0, 950.0, 11)
+        grid_rows, grid_columns = np.meshgrid(rows, columns, indexing="ij")
+        grid_rows = grid_rows.ravel()
+        grid_columns = grid_columns.ravel()
+
+        gamma_arm = np.deg2rad([g for g, _ in self.ARM_POSITIONS_DEG])
+        delta_arm = np.deg2rad([d for _, d in self.ARM_POSITIONS_DEG])
+
+        for det, label in (
+            (self.build(), "home reference"),
+            (self.build(rot3=0.22), "rotated about the beam"),
+            (self.build(dist=0.3, poni1=-0.05), "closer, offset PONI"),
+        ):
+            with self.subTest(detector=label):
+                tth_batch, az_batch = det._tthAzimuthAtArms(
+                    grid_rows, grid_columns, gamma_arm, delta_arm
+                )
+                for i, (g, d) in enumerate(zip(gamma_arm, delta_arm)):
+                    with self.subTest(gamma_arm=g, delta_arm=d):
+                        tth_ref, az_ref = det._tthAzimuthAtArm(
+                            grid_rows, grid_columns, float(g), float(d)
+                        )
+                        np.testing.assert_allclose(
+                            tth_batch[i], tth_ref, atol=1e-12
+                        )
+                        np.testing.assert_allclose(
+                            np.mod(az_batch[i] - az_ref + np.pi, 2 * np.pi) - np.pi,
+                            0.0,
+                            atol=1e-10,
+                        )
+
+    def test_batched_arm_respects_a_non_identity_reference(self):
+        """The reference rotation must apply per frame, not just at rest."""
+        det = self.build()
+        det.setArmReference(gamma_arm=np.deg2rad(3.0), delta_arm=np.deg2rad(-2.0))
+        rows = np.array([100.0, 400.0, 700.0])
+        columns = np.array([150.0, 450.0, 800.0])
+        gamma_arm = np.deg2rad([0.0, 12.0, -7.0])
+        delta_arm = np.deg2rad([0.0, 30.0, 55.0])
+
+        tth_batch, az_batch = det._tthAzimuthAtArms(
+            rows, columns, gamma_arm, delta_arm
+        )
+        for i in range(gamma_arm.size):
+            tth_ref, az_ref = det._tthAzimuthAtArm(
+                rows, columns, float(gamma_arm[i]), float(delta_arm[i])
+            )
+            np.testing.assert_allclose(tth_batch[i], tth_ref, atol=1e-12)
+            np.testing.assert_allclose(
+                np.mod(az_batch[i] - az_ref + np.pi, 2 * np.pi) - np.pi,
+                0.0,
+                atol=1e-10,
+            )
+
+    def test_batched_arm_refuses_a_configured_parallax_correction(self):
+        """Silently wrong is worse than refusing: this path skips parallax.
+
+        orGUI never configures one, but if that ever changes, a silent
+        divergence from the per-frame path -- which does apply it -- would
+        be a scientific correctness bug, not a performance one.
+        """
+        det = self.build()
+        det._parallax = object()  # stand-in: only its not-None-ness matters
+        with self.assertRaises(NotImplementedError):
+            det._tthAzimuthAtArms(
+                np.array([1.0]), np.array([1.0]), np.array([0.1]), np.array([0.0])
+            )
+
+    def test_batched_polarization_matches_the_per_frame_geometry(self):
+        """``polarizationAtPointsFrames`` end to end, against the per-frame call."""
+        det = self.build()
+        rows = np.linspace(3.0, 900.0, 7)
+        columns = np.linspace(9.0, 950.0, 7)
+        grid_rows, grid_columns = np.meshgrid(rows, columns, indexing="ij")
+        grid_rows = grid_rows.ravel()
+        grid_columns = grid_columns.ravel()
+        alpha = np.deg2rad(np.linspace(0.3, 3.0, 6))
+        gamma_arm = 2.0 * alpha
+        delta_arm = np.deg2rad(np.linspace(-1.0, 1.0, 6))
+
+        got = det.polarizationAtPointsFrames(
+            grid_rows, grid_columns, alpha, gamma_arm, delta_arm
+        )
+        expected = np.stack([
+            det.polarizationAtPoints(
+                grid_rows, grid_columns, float(alpha[i]),
+                float(gamma_arm[i]), float(delta_arm[i]),
+            )
+            for i in range(alpha.size)
+        ])
+        np.testing.assert_allclose(got, expected, rtol=1e-12)
+
 
 """
 def test_del_gam_range():
diff --git a/orgui/datautils/xrayutils/test/test_corrections_detector.py b/orgui/datautils/xrayutils/test/test_corrections_detector.py
index 171df64..2b1be13 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_detector.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_detector.py
@@ -272,3 +272,97 @@ def test_the_arm_correction_is_neutral_for_a_non_finite_region():
     )
 
     assert got == 1.0
+
+
+def test_the_batched_arm_correction_matches_the_per_frame_one():
+    """The whole point: one region, many frames, same numbers.
+
+    A rocking or reflectivity scan tracks one region across a curve, with
+    the incidence angle and the arm different on every frame -- exactly
+    what previously forced ``orGUI._polarizationArmFactor`` into a Python
+    loop calling :func:`polarization_arm_correction` once per frame, slow
+    enough to make a mu scan with thousands of points unusable. This must
+    reproduce that loop exactly, just batched.
+    """
+    det = _calibrated_detector()
+    row, column, row_size, column_size = 310.0, 244.0, 40.0, 40.0
+    alpha = np.deg2rad(np.linspace(0.3, 3.0, 9))
+    gamma_arm = 2.0 * alpha
+    delta_arm = np.deg2rad(np.linspace(-1.0, 1.0, 9))
+
+    got = detector_corrections.polarization_arm_correction_frames(
+        det, row, column, row_size, column_size, alpha, gamma_arm, delta_arm
+    )
+    expected = np.array([
+        detector_corrections.polarization_arm_correction(
+            det, row, column, row_size, column_size,
+            float(alpha[i]), float(gamma_arm[i]), float(delta_arm[i]),
+        )
+        for i in range(alpha.size)
+    ])
+
+    np.testing.assert_allclose(got, expected, rtol=1e-10)
+    assert got[0] != 1.0, "the arm does move here, or the test proves nothing"
+
+
+def test_the_batched_arm_correction_is_one_at_the_calibrated_position():
+    """A frame whose arm sits at the calibrated reference stays untouched."""
+    det = _calibrated_detector()
+    alpha = np.deg2rad([0.6, 0.6, 0.6])
+    gamma_arm = np.array([0.0, np.deg2rad(10.0), 0.0])
+    delta_arm = np.zeros(3)
+
+    got = detector_corrections.polarization_arm_correction_frames(
+        det, 300.0, 240.0, 60.0, 60.0, alpha, gamma_arm, delta_arm
+    )
+
+    assert got[0] == 1.0
+    assert got[2] == 1.0
+    assert got[1] != 1.0
+
+
+def test_the_batched_arm_correction_is_neutral_for_a_non_finite_region():
+    """The whole-region guard: a region with no finite position corrects nothing."""
+    det = _calibrated_detector()
+    alpha = np.deg2rad([0.6, 0.6])
+    gamma_arm = np.deg2rad([10.0, 20.0])
+    delta_arm = np.zeros(2)
+
+    got = detector_corrections.polarization_arm_correction_frames(
+        det, np.inf, 240.0, 20.0, 20.0, alpha, gamma_arm, delta_arm
+    )
+
+    np.testing.assert_array_equal(got, [1.0, 1.0])
+
+
+def test_the_batched_arm_correction_skips_non_finite_frames_only(recwarn):
+    """A frame on which the rod never reached the detector must not corrupt
+    or warn about the others -- it is skipped, not computed and masked.
+
+    Found by profiling the mu-scan slowdown: a naive fix that computed
+    every frame and masked afterwards emitted a ``RuntimeWarning`` for
+    every off-detector frame, since NaN/inf angles were fed to trigonometry
+    regardless. ``recwarn`` catches that regression directly.
+    """
+    det = _calibrated_detector()
+    alpha = np.deg2rad(np.linspace(0.3, 3.0, 6))
+    gamma_arm = 2.0 * alpha
+    delta_arm = np.zeros(6)
+
+    bad_alpha = alpha.copy()
+    bad_alpha[2] = np.nan
+    bad_gamma_arm = gamma_arm.copy()
+    bad_gamma_arm[4] = np.inf
+
+    got = detector_corrections.polarization_arm_correction_frames(
+        det, 310.0, 244.0, 40.0, 40.0, bad_alpha, bad_gamma_arm, delta_arm
+    )
+    expected = detector_corrections.polarization_arm_correction_frames(
+        det, 310.0, 244.0, 40.0, 40.0, alpha, gamma_arm, delta_arm
+    )
+
+    assert got[2] == 1.0
+    assert got[4] == 1.0
+    other = [0, 1, 3, 5]
+    np.testing.assert_allclose(got[other], expected[other], rtol=1e-10)
+    assert not [w for w in recwarn.list if issubclass(w.category, RuntimeWarning)]

From d52ab8f5234ef6375cb0a173252d22585774899f Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Mon, 14 Sep 2026 16:04:06 -0400
Subject: [PATCH 19/33] fix: refresh HKL-dependent plots after loading a stored
 configuration

---
 CHANGELOG.md                       | 10 ++++++
 doc/source/release_notes.rst       |  1 +
 orgui/app/config_data.py           | 12 ++++++++
 orgui/app/test/test_config_data.py | 49 ++++++++++++++++++++++++++++++
 4 files changed, 72 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 44906cc..1275419 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -935,6 +935,16 @@ GUI fixes:
   the right; the inactive beam-model group is hidden rather than merely
   disabled, so it stops reserving space it is not using; the schematic image
   is capped; and the preview plot is a little shorter.
+- Loading a stored configuration from the database now refreshes the ROI and
+  reflection overlays and the Q-plot. ``mu``/``chi``/``phi``, the UB matrix
+  and the detector geometry were already updated correctly and immediately --
+  every live angle and HKL readout reads them fresh rather than from a cache
+  -- but nothing told the plot to redraw, so it kept showing reflection
+  markers, ROI positions and the reciprocal-space conversion computed from
+  the geometry active *before* the load, which looked like the angle-to-HKL
+  conversion itself had not updated. Loading a configuration now emits the
+  same replot request every interactive machine-parameter, crystal-parameter
+  or U-alignment change already does.
 
 ESRF ID31 beamline support and reciprocal-space display:
 
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index bc2fb99..ed95372 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -144,6 +144,7 @@ GUI fixes:
 - The position readout is now correct while the Q-plot is switched on. The plot axes hold momentum transfer there and not detector pixels, so the ``X``/``Y`` labels were wrong and ``HKL``, ``del``, ``gam`` and ``Q`` were computed as if the cursor were on a pixel. The two axis fields are now labelled ``q_par[<frame>]`` and ``q_perp[<frame>]`` and shown with five decimals, and the remaining fields are obtained by inverting the conversion, so hovering a point of the Q-plot reports the same ``HKL`` and the same detector angles as hovering the pixel it came from. The reported ``Q`` is the reconstructed vector, so its components are exactly the coordinates under the cursor; it is unrefracted in the Q-plot because the axes are unrefracted as well, while ``HKL`` stays refraction corrected in both modes. Positions that no pixel maps to — the corners of the rebinned grid, or anything outside the Ewald sphere — are shown as ``------``.
 - Cancelling or resetting the machine parameter or the crystal parameter dialog now restores the configuration that was active when the dialog was opened. Both dialogs apply every edit immediately, so restoring the widgets alone left the edited values active, and the discarded configuration stayed in use until it was overwritten or a config file was loaded.
 - The footprint correction dialog now fits a normal screen. Both the analytical-shape and the measured-profile groups used to be given layout space at once, only one of them disabled, and everything was stacked in a single column below a full-width schematic image and a 220-pixel preview plot -- together taller than most displays. It is now two columns, the beam and sample inputs on the left and the sample position and preview on the right; the inactive beam-model group is hidden rather than merely disabled, so it stops reserving space it is not using; the schematic image is capped; and the preview plot is a little shorter.
+- Loading a stored configuration from the database now refreshes the ROI and reflection overlays and the Q-plot. ``mu``/``chi``/``phi``, the UB matrix and the detector geometry were already updated correctly and immediately -- every live angle and HKL readout reads them fresh rather than from a cache -- but nothing told the plot to redraw, so it kept showing reflection markers, ROI positions and the reciprocal-space conversion computed from the geometry active *before* the load, which looked like the angle-to-HKL conversion itself had not updated. Loading a configuration now emits the same replot request every interactive machine-parameter, crystal-parameter or U-alignment change already does.
 
 ESRF ID31 beamline support and reciprocal-space display:
 
diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index a77ba39..f526a2e 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -927,6 +927,18 @@ def apply_to_gui(self, gui):
             gui.excludedImagesDialog.updateArrayData(excluded)
         if hasattr(ub_widget, "updateReflectionMismatch"):
             ub_widget.updateReflectionMismatch()
+        # Every interactive path that changes mu/chi/phi, the UB matrix or
+        # the detector geometry (_onMachineParamsChanged, _onCrystalParamsChanged,
+        # _onAlignU) emits these right after updateReflectionMismatch(), which
+        # documents exactly that contract; skipping it here left the ROI and
+        # reflection overlays, and the Q-plot, showing the geometry from
+        # before the config was loaded; the angle readout in the caller
+        # (`orgui.mu`, etc.) was already correct -- only the cached HKL and
+        # its dependent plot elements were stale.
+        if hasattr(ub_widget, "sigPlottableMachineParamsChanged"):
+            ub_widget.sigPlottableMachineParamsChanged.emit()
+        if hasattr(ub_widget, "sigReplotRequest"):
+            ub_widget.sigReplotRequest.emit(True)
 
     def to_nxdict(self, role="scan", source=None):
         """Convert this config to a NeXus-compatible nested dictionary."""
diff --git a/orgui/app/test/test_config_data.py b/orgui/app/test/test_config_data.py
index 3795d66..a1b9e6e 100644
--- a/orgui/app/test/test_config_data.py
+++ b/orgui/app/test/test_config_data.py
@@ -340,6 +340,55 @@ def test_apply_to_gui_sets_reconstruction_normalization_attributes():
     assert gui.reconstruction_monitor_corrections == ("mondio",)
 
 
+def test_apply_to_gui_requests_a_replot(qapp):
+    """Loading a config must refresh HKL-dependent plot elements too.
+
+    Every interactive path that changes mu/chi/phi, the UB matrix or the
+    detector geometry (``_onMachineParamsChanged``, ``_onCrystalParamsChanged``,
+    ``_onAlignU``) emits ``sigReplotRequest`` right after
+    ``updateReflectionMismatch()`` -- that method's own docstring documents
+    the contract. Without it here, ``mu``/``chi``/``phi`` and the UB matrix
+    were already correct immediately after loading (they are read fresh, not
+    cached), but the ROI and reflection overlays and the Q-plot kept showing
+    the geometry from before the config was loaded -- what looked like
+    "loading a config does not update the angles to hkl conversion."
+    """
+    config = _make_config()
+
+    class _UBStub(qt.QObject):
+        sigPlottableMachineParamsChanged = qt.pyqtSignal()
+        sigReplotRequest = qt.pyqtSignal(bool)
+
+        def __init__(self):
+            super().__init__()
+            self.detectorCal = config.detector
+            self.crystal = config.unit_cell
+            self.ubCal = config.ub_calculator
+            self.mu = 0.0
+            self.chi = 0.0
+            self.phi = 0.0
+            self.n = 1.0
+
+        def updateReflectionMismatch(self):
+            pass
+
+    ub_widget = _UBStub()
+    gui = SimpleNamespace(ubcalc=ub_widget)
+
+    replot_calls = []
+    ub_widget.sigReplotRequest.connect(replot_calls.append)
+    plottable_calls = []
+    ub_widget.sigPlottableMachineParamsChanged.connect(
+        lambda: plottable_calls.append(True)
+    )
+
+    config.apply_to_gui(gui)
+
+    assert replot_calls == [True]
+    assert plottable_calls == [True]
+    assert ub_widget.mu == config.mu, "the angle itself must also be updated"
+
+
 def test_snapshot_assets_serializes_active_mask(tmp_path):
     config = _make_config()
     config.corrections = CorrectionState(use_mask=True)

From 5ea1b8f80b4594005ba5fe7a59e26a1368df3bc8 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 16 Sep 2026 12:21:20 -0400
Subject: [PATCH 20/33] test(phys): pin CTR correction contract

---
 doc/design/ctr_stage0_contract.md             |  85 ++++++++++++++
 .../test/fixtures/ctr_stage0_contract.json    |  74 ++++++++++++
 orgui/app/test/test_config_data.py            |  45 ++++++++
 orgui/app/test/test_ctr_stage0_contract.py    | 109 ++++++++++++++++++
 orgui/app/test/test_peak1Dintegr.py           |  52 +++++++++
 .../test/test_DetectorCalibration.py          |  31 +++++
 6 files changed, 396 insertions(+)
 create mode 100644 doc/design/ctr_stage0_contract.md
 create mode 100644 orgui/app/test/fixtures/ctr_stage0_contract.json
 create mode 100644 orgui/app/test/test_ctr_stage0_contract.py

diff --git a/doc/design/ctr_stage0_contract.md b/doc/design/ctr_stage0_contract.md
new file mode 100644
index 0000000..3e10e6c
--- /dev/null
+++ b/doc/design/ctr_stage0_contract.md
@@ -0,0 +1,85 @@
+# CTR targeted implementation: Stage 0 contract
+
+Status: implementation note, 2026-09-16. Numerical behavior was captured at
+commit `d52ab8f5234e`, before Stage 1 of
+[`ctr_targeted_implementation_plan.md`](ctr_targeted_implementation_plan.md).
+
+This note records what the characterization fixture means and which metadata
+is not available. It does not claim that the frozen numbers independently
+validate the physics.
+
+## Frozen extraction behavior
+
+`orgui/app/test/fixtures/ctr_stage0_contract.json` and
+`test_ctr_stage0_contract.py` pin two compact cases:
+
+- A stationary extraction with detector counts and one-sigma count errors,
+  radian diffraction angles, an exposure-times-monitor divisor, and the
+  current stationary Lorentz-to-`F2_hkl` conversion.
+- A mechanical rocking extraction with a degree-valued motor axis, two
+  background regions, per-frame normalization inside the angular integral,
+  radian detector acceptance, and the current relative `F2_hkl` scale.
+
+The fixture also pins a pre-typed correction-settings dictionary. Its sample
+dimensions are meters and `beam_flux_density` remains photons per second per
+square meter. Missing fields remain missing; zero is not substituted for an
+unknown calibration. Existing tests in `test_config_data.py` and
+`test_peak1Dintegr.py` cover typed NeXus round trips, legacy JSON database
+dispatch, and both stored correction-group layouts used by the reducer.
+
+Strict expected-failure tests record the two Stage 1 defects without changing
+application code: the arm-following polarization evaluator ignores a nonzero
+polarization axis, and rocking acceptance ignores stored actual-arm angles.
+
+## Settings-loader audit
+
+All `examples/config_*` files use the legacy INI loader. They define detector,
+lattice and diffractometer values; none selects a normalization monitor or
+stores integration-correction provenance. `ConfigData.from_ini` therefore
+starts with an empty `CorrectionState`. Current database snapshots write the
+typed `integration_corrections` layout (schema version 2), while
+`ConfigData.from_nxdict` still recognizes the older group containing one
+opaque JSON dataset. Neither old layout distinguishes rate-like from
+frame-integrated monitors.
+
+## Backend counter-semantics audit
+
+The implementation assumption is that a selected incident-beam monitor is
+**rate-like**. It is therefore multiplied by exposure time in the fluence
+divisor. This matches the current normalization arithmetic. The present
+backend contract names arrays but does not persist a counter kind or unit, so
+the assumption must remain visible in provenance until a beamline-specific
+calibration establishes the counter-to-total-flux conversion.
+
+| Backend | Persisted candidates | Meaning established by code | Rate/integrated status |
+|---|---|---|---|
+| Base `Scan`, imported images | none | no monitor metadata | unavailable |
+| Built-in P212 | implicit `exposure_time` when present | frame exposure, seconds by loader convention | not a flux monitor; P212 flux counters are unavailable |
+| ID31 fast/BLISS variants | `exposure_time`, `time`/`elapsed_time`/`epoch`, `srcur`, `mondio`, plus electrochemistry values | exposure is seconds; time/epoch are coordinates; `srcur` and `mondio` are often divided by their scan mean and are therefore dimensionless relative factors | selected beam monitors are treated as rate-like relative-flux proxies |
+| Example CHESS QM2 | `diode`, `ic1`, `ic2`, `emon`, `nemon`, `pemon` | raw SPEC columns; `ic2` is ion chamber 2 and is the expected primary incident-beam monitor | `ic2` is treated as rate-like; a later calibrated factor converts its reading to total photons/s |
+| Example P212 | `beckvolt_1`, `beckvolt_2`, `eh3_entrance`, `oh2_diode1`, `oh2_diode2`, `petracurrent`, `timestamp` | raw scan columns; timestamp is not a flux monitor | a selected beam monitor is treated as rate-like; its calibration is unresolved |
+| Segmented/interlaced scans | intersection of segment counters, plus implicit exposure time | values are concatenated/reordered; semantics are inherited | selected monitors remain rate-like; units and calibration are not merged |
+
+`current`, `potential`, `scaled_potv2f`, motor positions and timestamps are not
+incident-flux monitors merely because they appear in `auxillary_counters`.
+Until Stage 3 adds an explicit monitor unit and calibration relation, the
+legacy behavior is exactly exposure time times the selected rate-like monitor
+product recorded by `monitor_corrections`; it must be shown as legacy rather
+than silently assigned an absolute photon scale. For QM2, the intended primary
+monitor is `ic2`, with a future scalar calibration relating its rate to total
+incident flux in photons/s.
+
+## Stage 1 inputs now pinned
+
+- Polarization: at the calibrated arm position,
+  `polarizationAtPoints` must match `polarizationArray` for nonzero axes and
+  mixed polarization fractions. The axis-zero baseline already passes.
+- Acceptance: scan arm values are degrees at the storage boundary and must be
+  converted to radians before calling `out_of_plane_acceptance`. The fallback
+  for old scans with no arm values must remain explicit.
+
+The rolled-detector case uses the published review parameters: 172 micrometer
+pixels, 0.15 meter distance, 30 degree detector roll, ROI center `(row,
+column) = (500, 440)`, height 60 pixels, incidence 10 degrees and actual
+`(gamma, delta)` arm angles `(30, 40)` degrees. It is a counterexample to arm
+invariance, not a statement about a typical experimental error.
diff --git a/orgui/app/test/fixtures/ctr_stage0_contract.json b/orgui/app/test/fixtures/ctr_stage0_contract.json
new file mode 100644
index 0000000..c4323a0
--- /dev/null
+++ b/orgui/app/test/fixtures/ctr_stage0_contract.json
@@ -0,0 +1,74 @@
+{
+  "contract_head": "d52ab8f5234e",
+  "stationary": {
+    "units": {
+      "angles": "rad",
+      "counts": "detector counts per frame",
+      "errors": "1-sigma detector counts per frame",
+      "normalization": "exposure times selected monitor product",
+      "output": "current relative F2 scale"
+    },
+    "alpha": [0.017453292519943295, 0.03490658503988659],
+    "delta": [0.3490658503988659, 0.4363323129985824],
+    "gamma": [0.5235987755982988, 1.0471975511965976],
+    "counts": [120.0, 180.0],
+    "errors": [10.954451150103322, 13.416407864998739],
+    "normalization": [2.0, 3.0],
+    "expected": {
+      "intensity": [60.0, 60.0],
+      "intensity_errors": [5.477225575051661, 4.47213595499958],
+      "F2_hkl": [29.999999999999993, 51.96152422706631],
+      "F2_hkl_errors": [2.73861278752583, 3.8729833462074166]
+    }
+  },
+  "rocking": {
+    "units": {
+      "s": "r.l.u.",
+      "axis": "deg",
+      "curves": "detector counts per frame",
+      "normalization": "exposure times selected monitor product",
+      "acceptance": "rad",
+      "output": "current relative F2 scale"
+    },
+    "s": [0.1, 0.2],
+    "axis": [-1.0, -0.75, -0.5, -0.25, 0.0, 0.25, 0.5, 0.75, 1.0],
+    "curves": [
+      [2.0, 2.0, 2.0, 12.0, 22.0, 12.0, 2.0, 2.0, 2.0],
+      [4.0, 4.0, 4.0, 24.0, 44.0, 24.0, 4.0, 4.0, 4.0]
+    ],
+    "roi": {
+      "sig_1": [-0.25, 0.25],
+      "bg_1": [-1.0, -0.5],
+      "bg_2": [0.5, 1.0]
+    },
+    "normalization": [2.0, 4.0],
+    "C_Lorentz": [2.0, 2.0],
+    "C_rod": [0.8, 0.8],
+    "acceptance": [0.01, 0.02],
+    "expected": {
+      "raw_croi": [8.5, 17.0],
+      "raw_bgroi": [1.0, 2.0],
+      "raw_croibg": [7.5, 15.0],
+      "croi": [4.25, 4.25],
+      "bgroi": [0.5, 0.5],
+      "croibg": [3.75, 3.75],
+      "croibg_errors": [0.6789237807000135, 0.480071609241788],
+      "F2_hkl": [4.090615434361709, 2.0453077171808545],
+      "F2_hkl_errors": [0.7405909589564478, 0.26183844458177613]
+    }
+  },
+  "legacy_corrections": {
+    "use_mask": true,
+    "use_background": true,
+    "use_solid_angle": true,
+    "use_polarization": true,
+    "use_lorentz": true,
+    "use_footprint": false,
+    "use_normalization": true,
+    "normalize_exposure": true,
+    "monitor_corrections": ["mondio"],
+    "sample_length_m": 0.004,
+    "sample_width_m": 0.008,
+    "beam_flux_density": 2500000000000.0
+  }
+}
diff --git a/orgui/app/test/test_config_data.py b/orgui/app/test/test_config_data.py
index a1b9e6e..7d22b98 100644
--- a/orgui/app/test/test_config_data.py
+++ b/orgui/app/test/test_config_data.py
@@ -1,4 +1,6 @@
 import h5py
+import json
+
 import numpy as np
 from silx.gui import qt
 from silx.io.dictdump import dicttonx, nxtodict
@@ -149,6 +151,49 @@ def test_config_data_round_trips_through_database_json():
     assert np.allclose(loaded.ub_calculator.getUB(), config.ub_calculator.getUB())
 
 
+@pytest.fixture
+def legacy_corrections_database(tmp_path):
+    """Database snapshot using the pre-typed correction-settings group."""
+    config = _make_config()
+    values = {
+        "use_mask": True,
+        "use_background": True,
+        "use_solid_angle": True,
+        "use_polarization": True,
+        "use_lorentz": True,
+        "use_footprint": False,
+        "use_normalization": True,
+        "normalize_exposure": True,
+        "monitor_corrections": ["mondio"],
+        "sample_length_m": 0.004,
+        "sample_width_m": 0.008,
+        "beam_flux_density": 2.5e12,
+    }
+    nxdict = config.to_nxdict(role="scan")
+    nxdict["orgui"]["integration_corrections"] = {
+        "@NX_class": "NXcollection",
+        "json": json.dumps(values),
+    }
+    filename = tmp_path / "legacy_corrections.h5"
+    dicttonx({"configuration": nxdict}, filename)
+    return filename, values
+
+
+def test_pre_typed_database_correction_settings_still_load(
+    legacy_corrections_database,
+):
+    """Pin dispatch of an old database containing one opaque JSON dataset."""
+    filename, values = legacy_corrections_database
+
+    stored = nxtodict(filename)["configuration"]
+    loaded = ConfigData.from_nxdict(stored)
+
+    assert "json" in stored["orgui"]["integration_corrections"]
+    serialized = loaded.corrections.to_dict()
+    assert {name: serialized[name] for name in values} == values
+    assert loaded.corrections.monitor_corrections == ("mondio",)
+
+
 def test_enabled_pixel_repair_implies_mask_correction():
     config = _make_config()
     repair = SimpleNamespace(
diff --git a/orgui/app/test/test_ctr_stage0_contract.py b/orgui/app/test/test_ctr_stage0_contract.py
new file mode 100644
index 0000000..5bd6f6c
--- /dev/null
+++ b/orgui/app/test/test_ctr_stage0_contract.py
@@ -0,0 +1,109 @@
+"""Frozen CTR extraction behavior before the targeted correction rework.
+
+The compact JSON fixture records the numerical contract at commit
+``d52ab8f5234e``.  These are characterization tests: they protect legacy
+dispatch and make later convention changes explicit, but they are not an
+independent validation of the CTR physics.
+"""
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+from orgui.app import integration_corrections as stationary
+from orgui.app.config_data import CorrectionState
+from orgui.app.peak1Dintegr import _compute_rocking_integration
+
+
+_FIXTURE = Path(__file__).with_name("fixtures") / "ctr_stage0_contract.json"
+
+
+def _contract():
+    """Return the immutable Stage-0 characterization data."""
+    return json.loads(_FIXTURE.read_text(encoding="utf-8"))
+
+
+def test_stationary_contract_at_stage0():
+    """Pin stationary normalization, Lorentz reduction, errors, and units."""
+    case = _contract()["stationary"]
+    alpha, delta, gamma = (
+        np.asarray(case[name], dtype=float)
+        for name in ("alpha", "delta", "gamma")
+    )
+    factors = stationary.stationary_correction_factors(
+        alpha,
+        delta,
+        gamma,
+        use_lorentz=True,
+        normalization=np.asarray(case["normalization"], dtype=float),
+    )
+    intensity, errors = stationary.apply_stationary_corrections(
+        case["counts"], case["errors"], factors
+    )
+    f2, f2_errors = stationary.structure_factor(intensity, errors, factors)
+
+    expected = case["expected"]
+    np.testing.assert_allclose(intensity, expected["intensity"], rtol=1e-14)
+    np.testing.assert_allclose(
+        errors, expected["intensity_errors"], rtol=1e-14
+    )
+    np.testing.assert_allclose(f2, expected["F2_hkl"], rtol=1e-14)
+    np.testing.assert_allclose(
+        f2_errors, expected["F2_hkl_errors"], rtol=1e-14
+    )
+
+
+def test_rocking_contract_at_stage0():
+    """Pin two-background aggregation and current rocking F2 scaling."""
+    case = _contract()["rocking"]
+    curves = np.asarray(case["curves"], dtype=float)
+    shape = curves.shape
+    roi = {
+        name: {
+            "from": np.full(shape[0], limits[0], dtype=float),
+            "to": np.full(shape[0], limits[1], dtype=float),
+        }
+        for name, limits in case["roi"].items()
+    }
+    result = _compute_rocking_integration(
+        np.asarray(case["s"], dtype=float),
+        np.asarray(case["axis"], dtype=float),
+        curves,
+        np.sqrt(curves),
+        roi,
+        aux={},
+        use_lorentz=True,
+        use_footprint=False,
+        C_Lor=np.broadcast_to(
+            np.asarray(case["C_Lorentz"], dtype=float)[:, None], shape
+        ),
+        C_rod=np.broadcast_to(
+            np.asarray(case["C_rod"], dtype=float)[:, None], shape
+        ),
+        C_norm=np.broadcast_to(
+            np.asarray(case["normalization"], dtype=float)[:, None], shape
+        ),
+        detector_acceptance=np.asarray(case["acceptance"], dtype=float),
+        angle_unit=case["units"]["axis"],
+    )
+
+    for name, expected in case["expected"].items():
+        np.testing.assert_allclose(result[name], expected, rtol=1e-14)
+
+
+def test_legacy_correction_settings_keep_their_old_meanings():
+    """Pin the opaque-JSON settings used by pre-typed database groups."""
+    values = _contract()["legacy_corrections"]
+
+    state = CorrectionState.from_dict(values)
+
+    serialized = state.to_dict()
+    assert {name: serialized[name] for name in values} == values
+    assert state.use_background is True
+    assert state.monitor_corrections == ("mondio",)
+    # These fields retain the old density/area convention until a versioned
+    # replacement exists: meter, meter, and photons / (s m^2), respectively.
+    assert state.sample_length_m == 0.004
+    assert state.sample_width_m == 0.008
+    assert state.beam_flux_density == 2.5e12
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index 0964521..9cb537b 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -614,6 +614,58 @@ def _solid_angle_detector():
     return detector
 
 
+@pytest.mark.xfail(
+    strict=True,
+    reason="Stage 1: rocking acceptance is evaluated at the calibration arm",
+)
+def test_rocking_acceptance_uses_the_stored_arm_position():
+    """Pin the rolled-detector counterexample from the physics review.
+
+    Angles stored with a scan are degrees; the acceptance API takes radians.
+    At this deliberately oblique geometry, using the home arm understates the
+    accepted gamma span by about 3.4 percent.
+    """
+    from orgui.datautils.xrayutils.corrections import acceptance
+
+    detector = _solid_angle_detector()
+    pixel = detector.detector.pixel1
+    detector.dist = 0.15
+    detector.poni1 = detector.detector.shape[0] * pixel / 2.0
+    detector.poni2 = detector.detector.shape[1] * pixel / 2.0
+    detector.rot3 = np.deg2rad(30.0)
+    detector.reset()
+    detector._cached_array = {}
+
+    row = np.array([500.0])
+    column = np.array([440.0])
+    height = np.array([60.0])
+    alpha_deg = np.array([10.0])
+    gamma_arm_deg = np.array([30.0])
+    delta_arm_deg = np.array([40.0])
+    counters = {
+        "vsize": height,
+        "alpha_pk": alpha_deg,
+        "gamma_arm": gamma_arm_deg,
+        "delta_arm": delta_arm_deg,
+    }
+
+    expected = acceptance.out_of_plane_acceptance(
+        detector,
+        row,
+        column,
+        height,
+        np.deg2rad(alpha_deg),
+        np.deg2rad(gamma_arm_deg),
+        np.deg2rad(delta_arm_deg),
+    )
+    actual, applied = RockingPeakIntegrator._rocking_acceptance(
+        _stub(), detector, counters, x=column, y=row
+    )
+
+    assert applied is True
+    np.testing.assert_allclose(actual, expected, rtol=1e-10)
+
+
 @pytest.mark.parametrize("applied_at_extraction", [True, False])
 def test_the_typed_corrections_group_is_read_back(applied_at_extraction):
     """The F6 compensation must survive the layout it is stored in.
diff --git a/orgui/datautils/xrayutils/test/test_DetectorCalibration.py b/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
index 37b5a34..d33e8ca 100644
--- a/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
+++ b/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
@@ -1091,3 +1091,34 @@ def test_unpolarized_beam_has_no_azimuthal_dependence():
 
     tth = sxrddet.center_array(sxrddet.get_shape(), unit=pyFAI.units.TTH_RAD)
     np.testing.assert_allclose(correction, 0.5 * (1.0 + np.cos(tth) ** 2), atol=1e-6)
+
+
+@pytest.mark.xfail(
+    strict=True,
+    reason="Stage 1: arm-following polarization ignores polarization_axis",
+)
+@pytest.mark.parametrize("pol_axis_deg", [30.0, 90.0])
+@pytest.mark.parametrize("fraction", [1.0, 0.75])
+def test_arm_following_polarization_honors_the_configured_axis(
+    pol_axis_deg, fraction
+):
+    """Point and array evaluators must agree at the calibration position.
+
+    This is the minimal reproduction for the targeted-review finding: the
+    array path uses ``_polAxis``, while the arm-following shared evaluator
+    currently does not.  Keeping the expected failure strict makes Stage 1
+    remove the marker when it fixes the shared evaluator.
+    """
+    detector = _sxrd_detector(90.0, pol_axis_deg, fraction)
+    row, column = 309, 243
+    alpha = np.deg2rad(0.6)
+
+    expected = np.asarray(detector.polarizationArray(), dtype=float)[row, column]
+    actual = np.asarray(
+        detector.polarizationAtPoints(
+            np.array([float(row)]), np.array([float(column)]), alpha
+        ),
+        dtype=float,
+    )[0]
+
+    np.testing.assert_allclose(actual, expected, atol=1e-6)

From 5070e7b433b75f4bb3a4cb6396d8ca80b2fd9daf Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 16 Sep 2026 14:38:59 -0400
Subject: [PATCH 21/33] fix(phys): honor polarization and detector arm geometry

---
 CHANGELOG.md                                  |  25 ++++-
 doc/design/ctr_stage0_contract.md             |   7 +-
 doc/source/release_notes.rst                  |   4 +-
 orgui/app/orGUI.py                            |  34 ++++++
 orgui/app/peak1Dintegr.py                     |  93 ++++++++++++++-
 orgui/app/test/test_orGUI_reflections.py      |  15 ++-
 orgui/app/test/test_peak1Dintegr.py           |  41 ++++---
 .../xrayutils/DetectorCalibration.py          |  29 +++--
 .../xrayutils/corrections/acceptance.py       |  57 +++++++---
 .../test/test_DetectorCalibration.py          | 106 +++++++++++++++---
 .../test/test_corrections_acceptance.py       |  32 ++++++
 11 files changed, 370 insertions(+), 73 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1275419..a09b632 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,8 +8,10 @@ This is the changelog for the software orGUI, written by Timo Fuchs
 Scientific and analysis additions:
 
 - **The polarization correction now follows the detector arm.**
-  *This changes saved numbers for scans that move the detector arm, and only
-  those.* The per-pixel polarization array is built from the calibrated
+  *This changes saved numbers for scans that move the detector arm and for
+  arm-corrected integrations using a nonzero configured polarization axis;
+  the conventional axis-zero case is unchanged.* The per-pixel polarization
+  array is built from the calibrated
   geometry, which is right only while the arm stays there. On a scan that
   drives the arm -- a reflectivity curve, where it follows twice the incidence
   angle -- the same pixel looks in a different direction on every frame, and
@@ -18,11 +20,16 @@ Scientific and analysis additions:
   paths now apply a per-frame factor,
   ``corrections.detector.polarization_arm_correction``, that moves the
   correction onto the arm position each frame was measured at. It is exactly
-  one while the arm sits at its calibrated position, so a fixed-arm scan is
+  one while the arm sits at its calibrated position when both paths use the
+  same configured polarization axis, so an axis-zero fixed-arm scan is
   bit-identical and needs no switch. The factor is a ratio of two region
   means rather than a rebuilt per-pixel array, which keeps the cost to a
   region-sized evaluation per frame; the polarization is not flat across a
-  region at a large scattering angle, so the means matter. The detector solid
+  region at a large scattering angle, so the means matter. The arm-following
+  evaluator now rotates the incident electric-field basis by the configured
+  ``polarization_axis``, matching the calibrated array for zero, 90-degree and
+  intermediate axes and for mixed polarization fractions; it previously
+  assumed an axis of zero. The detector solid
   angle needs no such correction: an arm rotation is a rigid rotation about
   the sample, so every pixel keeps its distance and its obliquity to its own
   line of sight, and the solid angle is invariant under it exactly. The
@@ -173,8 +180,14 @@ Scientific and analysis additions:
   the aperture, and vectorized over a scan because orGUI resizes regions per
   detector position. ``gamma_range`` reports the span over the whole region as
   a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row
-  case. The rocking integration now divides by it -- see the mode-equivalence
-  entry below.
+  case. New rocking extractions store the true primary-beam detector-arm
+  angles for every source frame, in radians, and evaluate the acceptance at
+  the frame nearest each calculated peak. This matters for rolled or oblique
+  detectors, where the actual-arm span can differ by several percent from the
+  calibrated-position span. Older databases have no arm history and retain
+  the calibrated-position result with an explicit warning. The rocking
+  integration now divides by this acceptance -- see the mode-equivalence entry
+  below.
 
 - **One structure-factor scale for rocking scans, stationary scans, and
   reflectivity.** The new public module
diff --git a/doc/design/ctr_stage0_contract.md b/doc/design/ctr_stage0_contract.md
index 3e10e6c..2f66fe4 100644
--- a/doc/design/ctr_stage0_contract.md
+++ b/doc/design/ctr_stage0_contract.md
@@ -27,9 +27,10 @@ unknown calibration. Existing tests in `test_config_data.py` and
 `test_peak1Dintegr.py` cover typed NeXus round trips, legacy JSON database
 dispatch, and both stored correction-group layouts used by the reducer.
 
-Strict expected-failure tests record the two Stage 1 defects without changing
-application code: the arm-following polarization evaluator ignores a nonzero
-polarization axis, and rocking acceptance ignores stored actual-arm angles.
+At Stage 0, strict expected-failure tests recorded the two Stage 1 defects
+without changing application code: the arm-following polarization evaluator
+ignored a nonzero polarization axis, and rocking acceptance ignored actual-arm
+angles. Stage 1 converts those reproductions into passing regressions.
 
 ## Settings-loader audit
 
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index ed95372..4120602 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -9,7 +9,7 @@ Unreleased (2026-07-19)
 
 Scientific and analysis additions:
 
-- **The polarization correction now follows the detector arm.** *This changes saved numbers for scans that move the detector arm, and only those.* The per-pixel polarization array is built from the calibrated geometry, which is right only while the arm stays there. On a scan that drives the arm -- a reflectivity curve, where it follows twice the incidence angle -- the same pixel looks in a different direction on every frame, and the calibrated-position value understated the correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration paths now apply a per-frame factor, ``corrections.detector.polarization_arm_correction``, that moves the correction onto the arm position each frame was measured at. It is exactly one while the arm sits at its calibrated position, so a fixed-arm scan is bit-identical and needs no switch. The factor is a ratio of two region means rather than a rebuilt per-pixel array, which keeps the cost to a region-sized evaluation per frame; the polarization is not flat across a region at a large scattering angle, so the means matter. The detector solid angle needs no such correction: an arm rotation is a rigid rotation about the sample, so every pixel keeps its distance and its obliquity to its own line of sight, and the solid angle is invariant under it exactly. The reciprocal-space reconstruction applies the polarization per pixel rather than as a region mean and is unchanged; correcting it there would need the array rebuilt per frame.
+- **The polarization correction now follows the detector arm.** *This changes saved numbers for scans that move the detector arm and for arm-corrected integrations using a nonzero configured polarization axis; the conventional axis-zero case is unchanged.* The per-pixel polarization array is built from the calibrated geometry, which is right only while the arm stays there. On a scan that drives the arm -- a reflectivity curve, where it follows twice the incidence angle -- the same pixel looks in a different direction on every frame, and the calibrated-position value understated the correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration paths now apply a per-frame factor, ``corrections.detector.polarization_arm_correction``, that moves the correction onto the arm position each frame was measured at. It is exactly one while the arm sits at its calibrated position when both paths use the same configured polarization axis, so an axis-zero fixed-arm scan is bit-identical and needs no switch. The factor is a ratio of two region means rather than a rebuilt per-pixel array, which keeps the cost to a region-sized evaluation per frame; the polarization is not flat across a region at a large scattering angle, so the means matter. The arm-following evaluator now rotates the incident electric-field basis by the configured ``polarization_axis``, matching the calibrated array for zero, 90-degree and intermediate axes and for mixed polarization fractions; it previously assumed an axis of zero. The detector solid angle needs no such correction: an arm rotation is a rigid rotation about the sample, so every pixel keeps its distance and its obliquity to its own line of sight, and the solid angle is invariant under it exactly. The reciprocal-space reconstruction applies the polarization per pixel rather than as a region mean and is unchanged; correcting it there would need the array rebuilt per frame.
 
 - **The arm-following polarization correction no longer makes a mu-scan rocking reduction unusably slow.** It evaluates once and broadcasts when the incidence angle and the arm are constant across a curve, which covers every fixed-arm scan and every th-scan rocking curve; a mu scan rocks the incidence angle itself, and a reflectivity rocking curve additionally tracks the arm at twice it, so nothing was constant and it fell back to a Python loop calling the per-frame correction once per point -- about 20 seconds for a thousand-point mu scan, a minute or more for several thousand, with no error, just a reduction that looked stuck. It is now one batched call per rocking curve instead of one per frame (``corrections.detector.polarization_arm_correction_frames``, backed by ``DetectorCalibration.Detector2D_SXRD._tthAzimuthAtArms``), verified against the per-frame loop to floating-point precision and measured about 7-8x faster end to end. A stationary integration tracking a rod across the detector has no single region to batch on and keeps the per-frame loop, unchanged. **No saved value changes** -- this is the same correction, computed the same way, just not one frame at a time.
 
@@ -23,7 +23,7 @@ Scientific and analysis additions:
 
 - **All correction factors collected into one package.** Every factor between detector counts and a structure factor now lives in ``orgui.datautils.xrayutils.corrections``, split by what it depends on: ``geometry`` (the z-axis Lorentz, rod-interception and area table), ``beamprofile``, ``activearea``, ``detector`` (per-pixel solid angle and polarization), ``normalization`` (counting time and monitor), ``roi``, and ``measurement``. The rocking integration, the stationary integration and the reciprocal-space reconstruction previously each carried their own copy of several of these; they now share one definition, so they cannot drift onto different scales. The package is physics only -- numbers in, numbers out -- and reads no scan object, configuration or widget; ``orgui.app`` ``integration_corrections`` is the adapter that supplies those. ``orgui.datautils.xrayutils.geometrycorrections`` and ``orgui.datautils.xrayutils.beamprofile`` keep working as aliases of the moved modules. **No calculated value changes.**
 
-- **Out-of-plane detector acceptance.** ``orgui.datautils.xrayutils.corrections.acceptance`` estimates ``Delta_gamma``, the angular height of a region of interest as seen from the sample, which a rocking-scan integrated intensity is proportional to (Vlieg equations 20 and 42) and which orGUI previously did not compute at all. Measured edge to edge, at the region's centre column where the rod crosses the aperture, and vectorized over a scan because orGUI resizes regions per detector position. ``gamma_range`` reports the span over the whole region as a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row case. The rocking integration now divides by it -- see the mode-equivalence entry below.
+- **Out-of-plane detector acceptance.** ``orgui.datautils.xrayutils.corrections.acceptance`` estimates ``Delta_gamma``, the angular height of a region of interest as seen from the sample, which a rocking-scan integrated intensity is proportional to (Vlieg equations 20 and 42) and which orGUI previously did not compute at all. Measured edge to edge, at the region's centre column where the rod crosses the aperture, and vectorized over a scan because orGUI resizes regions per detector position. ``gamma_range`` reports the span over the whole region as a check on rolled-detector geometries, and ``pixel_acceptance`` the one-row case. New rocking extractions store the true primary-beam detector-arm angles for every source frame, in radians, and evaluate the acceptance at the frame nearest each calculated peak. This matters for rolled or oblique detectors, where the actual-arm span can differ by several percent from the calibrated-position span. Older databases have no arm history and retain the calibrated-position result with an explicit warning. The rocking integration now divides by this acceptance -- see the mode-equivalence entry below.
 
 - **One structure-factor scale for rocking scans, stationary scans, and reflectivity.** The new public module ``orgui.datautils.xrayutils.corrections.measurement`` reduces an integrated intensity to ``|F_hkl|^2`` for any scan mode, following E. Vlieg, *J. Appl. Cryst.* 30 (1997) 532 and J. Drnec et al., *J. Appl. Cryst.* 47 (2014) 365. It normalizes counts by exposure time and monitor, converts a rocking integral from degrees to radians, applies the mode-dependent angular factor (rocking scans additionally require the out-of-plane acceptance of the region of interest, stationary measurements reject it), and, given the incident flux density and the illuminated area, puts the result on the absolute electron-unit scale. It also converts between ``|F_hkl|^2`` and absolute reflectivity, so a reflectivity curve and a set of truncation rods can be brought onto one scale. ``doc/design/ctr_structure_factor_scale.md`` records the full analysis with the measured size of every correction, and ``doc/physics/ctr_structure_factor_physics.tex`` is a typeset reference for the normalizations and integration intervals.
 
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index 22910b9..1ce8e53 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -130,6 +130,28 @@
 silx.config.DEFAULT_PLOT_SYMBOL = "."
 
 
+def _rocking_arm_snapshot(gamma_arm, delta_arm, curve_shape):
+    """Build the unit-tagged per-frame arm fields saved with rocking ROIs."""
+    curve_shape = tuple(curve_shape)
+    if len(curve_shape) != 2:
+        raise ValueError("rocking arm snapshot shape must be (curves, frames)")
+    frame_count = curve_shape[1]
+    gamma_arm = np.broadcast_to(
+        np.asarray(gamma_arm, dtype=np.float64), (frame_count,)
+    )
+    delta_arm = np.broadcast_to(
+        np.asarray(delta_arm, dtype=np.float64), (frame_count,)
+    )
+    return {
+        # scan_arm_angles already converted these to true primary-beam
+        # scattering angles. Radian storage feeds the geometry API directly.
+        "@detector_arm_unit": "rad",
+        "@detector_arm_angle_frame": "prim",
+        "gamma_arm": np.broadcast_to(gamma_arm, curve_shape).copy(),
+        "delta_arm": np.broadcast_to(delta_arm, curve_shape).copy(),
+    }
+
+
 def _display_roi_geometry(center, left, right, top, bottom):
     """Convert detector-array ROI slices to plot rectangle geometry.
 
@@ -1999,6 +2021,13 @@ def sumImage(i):
             om = np.full_like(mu, om)
         if len(np.asarray(mu).shape) == 0:
             mu = np.full_like(om, mu)
+        gamma_arm, delta_arm = self.getArmAngles()
+        gamma_arm = np.broadcast_to(
+            np.asarray(gamma_arm, dtype=np.float64), (len(self.fscan),)
+        ).copy()
+        delta_arm = np.broadcast_to(
+            np.asarray(delta_arm, dtype=np.float64), (len(self.fscan),)
+        ).copy()
 
         config_snapshot = ConfigData.from_gui(self)
         data = {
@@ -2447,6 +2476,11 @@ def sumImage(i):
             "vsize": np.array(vsize),
             "hsize": np.array(hsize),
             "axis": np.vstack(axis),
+            # True scattering angles are repeated for each extracted curve
+            # because its peak can occur at a different source frame.
+            **_rocking_arm_snapshot(
+                gamma_arm, delta_arm, np.vstack(alpha).shape
+            ),
         }
         if alpha_pk:
             rois["alpha_pk"] = np.array(alpha_pk)
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index c33c7fa..b187389 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -1558,11 +1558,11 @@ def _rocking_acceptance(self, detector, cnters, x, y):
         the row while ``x`` is the column -- every call site in the
         application passes them in that swapped order.
 
-        The acceptance is evaluated at the **calibrated** arm position. The
-        span a region subtends is invariant under an arm rotation to nine
-        digits, because that rotation is about the very axis
-        :math:`\\gamma` is measured around, so this costs nothing measurable;
-        see ``doc/design/ctr_structure_factor_scale.md`` section 4.4.
+        New extractions store the true detector-arm scattering angles for
+        every source frame. The frame nearest the calculated peak in
+        ``(alpha, theta)`` supplies the arm position used here. Old databases
+        have no such arrays; they retain the historical calibration-position
+        result, with a warning that makes that fallback visible.
 
         :param detector: The geometry the scan was measured with, from
             :meth:`_stored_detector`; ``None`` leaves the acceptance out.
@@ -1582,6 +1582,9 @@ def _rocking_acceptance(self, detector, cnters, x, y):
         if vsize.ndim > 1:
             vsize = vsize[:, 0]
         alpha_pk = np.deg2rad(np.asarray(cnters["alpha_pk"][()], dtype=float))
+        gamma_arm, delta_arm = RockingPeakIntegrator._rocking_peak_arm_angles(
+            cnters
+        )
 
         acceptance = acceptance_corrections.out_of_plane_acceptance(
             detector,
@@ -1589,9 +1592,89 @@ def _rocking_acceptance(self, detector, cnters, x, y):
             np.asarray(x, dtype=float),
             vsize,
             alpha_pk,
+            gamma_arm,
+            delta_arm,
         )
         return np.asarray(acceptance, dtype=float), True
 
+    @staticmethod
+    def _rocking_peak_arm_angles(cnters):
+        """Stored detector arm at each calculated rocking-curve peak.
+
+        The saved arm arrays are in the primary-beam frame and carry an
+        explicit ``rad`` group attribute. A rocking scan can run in either
+        ``mu`` or ``th``; selecting the stored frame nearest the calculated
+        peak in both ``(alpha, theta)`` coordinates handles either mode and a
+        reversed scan without relying on a separate axis-name string.
+
+        :param cnters: The stored rocking ``rois`` group.
+        :returns: ``(gamma_arm, delta_arm)`` in radian, or ``(None, None)``
+            for an old database that has no arm snapshot.
+        :rtype: tuple
+        """
+        if "gamma_arm" not in cnters or "delta_arm" not in cnters:
+            logger.warning(
+                "This rocking extraction stores no detector-arm positions; "
+                "evaluating its out-of-plane acceptance at the detector "
+                "calibration position (legacy fallback)."
+            )
+            return None, None
+
+        try:
+            gamma_arm = np.asarray(cnters["gamma_arm"][()], dtype=float)
+            delta_arm = np.asarray(cnters["delta_arm"][()], dtype=float)
+            alpha_pk = np.asarray(cnters["alpha_pk"][()], dtype=float).reshape(-1)
+            theta_pk = np.asarray(cnters["theta_pk"][()], dtype=float).reshape(-1)
+
+            def at_peak(values):
+                values = np.asarray(values, dtype=float)
+                if values.ndim == 0:
+                    return np.full(alpha_pk.shape, float(values))
+                if values.shape == alpha_pk.shape:
+                    return values
+
+                alpha = np.asarray(cnters["alpha"][()], dtype=float)
+                theta = np.asarray(cnters["theta"][()], dtype=float)
+                expected = (alpha_pk.size, alpha.shape[-1])
+                alpha = np.broadcast_to(alpha, expected)
+                theta = np.broadcast_to(theta, expected)
+                values = np.broadcast_to(values, expected)
+
+                def angular_difference(actual, target):
+                    return (actual - target[:, None] + 180.0) % 360.0 - 180.0
+
+                distance = angular_difference(alpha, alpha_pk) ** 2
+                distance += angular_difference(theta, theta_pk) ** 2
+                if np.any(~np.isfinite(distance).any(axis=1)):
+                    raise ValueError("no finite frame lies near a calculated peak")
+                indices = np.nanargmin(distance, axis=1)
+                return values[np.arange(alpha_pk.size), indices]
+
+            gamma_arm = at_peak(gamma_arm)
+            delta_arm = at_peak(delta_arm)
+            attrs = getattr(cnters, "attrs", {})
+            unit = attrs.get("detector_arm_unit", "rad")
+            if isinstance(unit, bytes):
+                unit = unit.decode()
+            if unit == "deg":
+                gamma_arm = np.deg2rad(gamma_arm)
+                delta_arm = np.deg2rad(delta_arm)
+            elif unit != "rad":
+                raise ValueError(f"unsupported detector-arm unit {unit!r}")
+            if not np.all(np.isfinite(gamma_arm)) or not np.all(
+                np.isfinite(delta_arm)
+            ):
+                raise ValueError("detector-arm values are not finite")
+            return gamma_arm, delta_arm
+        except Exception:
+            logger.warning(
+                "Cannot resolve the detector-arm position stored with this "
+                "rocking extraction; evaluating its out-of-plane acceptance "
+                "at the detector calibration position.",
+                exc_info=True,
+            )
+            return None, None
+
     def integrate(self):
         """Integrate rocking-scan ROIs.
 
diff --git a/orgui/app/test/test_orGUI_reflections.py b/orgui/app/test/test_orGUI_reflections.py
index 101e1d8..34d5fc1 100644
--- a/orgui/app/test/test_orGUI_reflections.py
+++ b/orgui/app/test/test_orGUI_reflections.py
@@ -6,7 +6,7 @@
 import pytest
 from silx.gui import qt
 
-from orgui.app.orGUI import _display_roi_geometry, orGUI
+from orgui.app.orGUI import _display_roi_geometry, _rocking_arm_snapshot, orGUI
 from orgui.app.QReflectionSelector import (
     AutoBraggOptionsDialog,
     AutoBraggStatusDialog,
@@ -30,6 +30,19 @@ def surfaceAnglesPoint(self, y, x, alpha_i):
         return 2.0e-4 * y + alpha_i, 1.0e-4 * x
 
 
+def test_rocking_arm_snapshot_is_per_frame_and_unit_tagged():
+    """A saved rocking extraction retains the arm history needed later."""
+    gamma = np.deg2rad([0.0, 15.0, 30.0])
+    delta = np.deg2rad([0.0, 20.0, 40.0])
+
+    snapshot = _rocking_arm_snapshot(gamma, delta, (2, 3))
+
+    assert snapshot["@detector_arm_unit"] == "rad"
+    assert snapshot["@detector_arm_angle_frame"] == "prim"
+    np.testing.assert_allclose(snapshot["gamma_arm"], [gamma, gamma])
+    np.testing.assert_allclose(snapshot["delta_arm"], [delta, delta])
+
+
 class FakeScan:
     axisname = "th"
     axis = np.array([0.0, 1.0, 2.0])
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index 9cb537b..24a8374 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -614,16 +614,13 @@ def _solid_angle_detector():
     return detector
 
 
-@pytest.mark.xfail(
-    strict=True,
-    reason="Stage 1: rocking acceptance is evaluated at the calibration arm",
-)
 def test_rocking_acceptance_uses_the_stored_arm_position():
     """Pin the rolled-detector counterexample from the physics review.
 
-    Angles stored with a scan are degrees; the acceptance API takes radians.
-    At this deliberately oblique geometry, using the home arm understates the
-    accepted gamma span by about 3.4 percent.
+    Frame diffraction angles are stored in degrees, while the explicitly
+    unit-tagged arm snapshot and the acceptance API use radians. At this
+    deliberately oblique geometry, using the home arm understates the accepted
+    gamma span by about 3.4 percent.
     """
     from orgui.datautils.xrayutils.corrections import acceptance
 
@@ -640,13 +637,16 @@ def test_rocking_acceptance_uses_the_stored_arm_position():
     column = np.array([440.0])
     height = np.array([60.0])
     alpha_deg = np.array([10.0])
-    gamma_arm_deg = np.array([30.0])
-    delta_arm_deg = np.array([40.0])
+    gamma_arm = np.deg2rad([[0.0, 30.0, 60.0]])
+    delta_arm = np.deg2rad([[0.0, 40.0, 50.0]])
     counters = {
         "vsize": height,
         "alpha_pk": alpha_deg,
-        "gamma_arm": gamma_arm_deg,
-        "delta_arm": delta_arm_deg,
+        "theta_pk": np.array([5.1]),
+        "alpha": np.array([[9.0, 10.0, 11.0]]),
+        "theta": np.array([[4.0, 5.0, 6.0]]),
+        "gamma_arm": gamma_arm,
+        "delta_arm": delta_arm,
     }
 
     expected = acceptance.out_of_plane_acceptance(
@@ -655,8 +655,8 @@ def test_rocking_acceptance_uses_the_stored_arm_position():
         column,
         height,
         np.deg2rad(alpha_deg),
-        np.deg2rad(gamma_arm_deg),
-        np.deg2rad(delta_arm_deg),
+        gamma_arm[:, 1],
+        delta_arm[:, 1],
     )
     actual, applied = RockingPeakIntegrator._rocking_acceptance(
         _stub(), detector, counters, x=column, y=row
@@ -666,6 +666,21 @@ def test_rocking_acceptance_uses_the_stored_arm_position():
     np.testing.assert_allclose(actual, expected, rtol=1e-10)
 
 
+def test_legacy_rocking_acceptance_reports_calibration_fallback(caplog):
+    """An old database remains usable but does not hide missing arm history."""
+    detector = _RowOnlyDetector()
+    counters = {"vsize": np.array([40.0]), "alpha_pk": np.zeros(1)}
+
+    with caplog.at_level("WARNING"):
+        actual, applied = RockingPeakIntegrator._rocking_acceptance(
+            _stub(), detector, counters, x=np.array([240.0]), y=np.array([300.0])
+        )
+
+    assert applied is True
+    np.testing.assert_allclose(actual, 40.0 * detector.PER_ROW, rtol=1e-12)
+    assert "calibration position (legacy fallback)" in caplog.text
+
+
 @pytest.mark.parametrize("applied_at_extraction", [True, False])
 def test_the_typed_corrections_group_is_read_back(applied_at_extraction):
     """The F6 compensation must survive the layout it is stored in.
diff --git a/orgui/datautils/xrayutils/DetectorCalibration.py b/orgui/datautils/xrayutils/DetectorCalibration.py
index d18bd29..8f6f615 100644
--- a/orgui/datautils/xrayutils/DetectorCalibration.py
+++ b/orgui/datautils/xrayutils/DetectorCalibration.py
@@ -579,21 +579,32 @@ def polarizationAtPoints(self, x, y, alpha_i, gamma_arm=None, delta_arm=None):
         return self._polarizationFromSurfaceAngles(alpha_i, gamma, delta)
 
     def _polarizationFromSurfaceAngles(self, alpha_i, gamma, delta):
-        r"""The z-axis polarization expression of :meth:`polarizationAtPoints`.
+        r"""Polarization from surface angles and the configured beam axis.
 
         Factored out so :meth:`polarizationAtPointsFrames` can share it
         rather than recompute the same formula from different surface angles.
+        The two outgoing-ray projections below are the horizontal and
+        vertical terms of the ANA/ROD z-axis expression. ``_polAxis`` rotates
+        that incident electric-field basis; omitting it made the arm-following
+        evaluators disagree with :meth:`polarizationArray` for every nonzero
+        configured axis.
         """
         fraction = self._polFactor
-        p_hor = (
-            1.0
-            - (
-                np.sin(alpha_i) * np.cos(delta) * np.cos(gamma)
-                + np.cos(alpha_i) * np.sin(gamma)
-            )
-            ** 2
+        horizontal_projection = (
+            np.sin(alpha_i) * np.cos(delta) * np.cos(gamma)
+            + np.cos(alpha_i) * np.sin(gamma)
+        )
+        vertical_projection = np.sin(delta) * np.cos(gamma)
+        cosine = np.cos(self._polAxis)
+        sine = np.sin(self._polAxis)
+        rotated_horizontal = (
+            cosine * horizontal_projection + sine * vertical_projection
+        )
+        rotated_vertical = (
+            -sine * horizontal_projection + cosine * vertical_projection
         )
-        p_ver = 1.0 - (np.sin(delta) ** 2) * (np.cos(gamma) ** 2)
+        p_hor = 1.0 - rotated_horizontal**2
+        p_ver = 1.0 - rotated_vertical**2
         return fraction * p_hor + (1.0 - fraction) * p_ver
 
     def polarizationAtPointsFrames(self, x, y, alpha_i, gamma_arm, delta_arm):
diff --git a/orgui/datautils/xrayutils/corrections/acceptance.py b/orgui/datautils/xrayutils/corrections/acceptance.py
index 95c23a9..8a3f0c4 100644
--- a/orgui/datautils/xrayutils/corrections/acceptance.py
+++ b/orgui/datautils/xrayutils/corrections/acceptance.py
@@ -55,16 +55,12 @@
 
 .. note::
 
-    :math:`\Delta\gamma` is almost invariant under a detector-arm rotation.
-    Driving the :math:`\gamma` arm shifts the exit angle at the region center
-    by the full arm angle, but leaves the span that region subtends unchanged
-    to nine digits, because the rotation is about the axis :math:`\gamma` is
-    measured around; a :math:`\delta`-arm rotation of 40 degrees moves it by
-    one part in :math:`10^5`. So an acceptance computed without the arm is
-    still usable, which is the opposite of the polarization factor, where
-    ignoring the arm is a 10 % error at a scattering angle of 18 degrees (see
-    :mod:`~.detector`). Pass the arm anyway where it is known -- it costs
-    nothing -- but a missing arm is not a reason to distrust an acceptance.
+    Evaluate the acceptance at the actual detector-arm position whenever it
+    is known. Arm invariance is not general: a rolled or oblique detector
+    changes the projection of the pixel-edge rays onto :math:`\gamma`, and
+    realistic counterexamples differ by several percent. Omitting the arm is
+    retained only as an explicit compatibility fallback for measurements that
+    predate stored arm metadata.
 """
 
 import numpy as np
@@ -90,18 +86,45 @@ def _surface_gamma(detector, row, column, alpha, gamma_arm=None, delta_arm=None)
     one fixed column -- which is what a rocking integration passes -- would
     otherwise fail inside the extension with ``pos2.size == size``.
     """
+    if (gamma_arm is None) != (delta_arm is None):
+        raise ValueError("both gamma_arm and delta_arm must be given together")
     row, column = np.broadcast_arrays(
         np.asarray(row, dtype=np.float64),
         np.asarray(column, dtype=np.float64),
     )
-    gamma, _delta = detector.surfaceAnglesPoint(
-        np.ascontiguousarray(row),
-        np.ascontiguousarray(column),
-        alpha,
-        gamma_arm,
-        delta_arm,
+    if gamma_arm is None or (
+        np.ndim(gamma_arm) == 0 and np.ndim(delta_arm) == 0
+    ):
+        gamma, _delta = detector.surfaceAnglesPoint(
+            np.ascontiguousarray(row),
+            np.ascontiguousarray(column),
+            alpha,
+            gamma_arm,
+            delta_arm,
+        )
+        return np.asarray(gamma, dtype=np.float64)
+
+    # ``surfaceAnglesPoint`` accepts one arm geometry at a time. A rocking
+    # reduction instead supplies one ROI and one arm position per curve, so
+    # evaluate those pairs rather than forming every arm-by-ROI combination.
+    row, column, alpha, gamma_arm, delta_arm = np.broadcast_arrays(
+        row,
+        column,
+        np.asarray(alpha, dtype=np.float64),
+        np.asarray(gamma_arm, dtype=np.float64),
+        np.asarray(delta_arm, dtype=np.float64),
     )
-    return np.asarray(gamma, dtype=np.float64)
+    result = np.empty(row.shape, dtype=np.float64)
+    for index in np.ndindex(row.shape):
+        gamma, _delta = detector.surfaceAnglesPoint(
+            np.array([row[index]]),
+            np.array([column[index]]),
+            float(alpha[index]),
+            float(gamma_arm[index]),
+            float(delta_arm[index]),
+        )
+        result[index] = np.asarray(gamma, dtype=np.float64).reshape(-1)[0]
+    return result
 
 
 def out_of_plane_acceptance(
diff --git a/orgui/datautils/xrayutils/test/test_DetectorCalibration.py b/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
index d33e8ca..5ea2565 100644
--- a/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
+++ b/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
@@ -946,6 +946,23 @@ def checkPixel_tth():
 """
 
 
+def _polarization_from_outgoing_ray(
+    alpha_i, gamma, delta, axis, fraction
+):
+    """Independent electric-field projection reference."""
+    horizontal = (
+        np.sin(alpha_i) * np.cos(delta) * np.cos(gamma)
+        + np.cos(alpha_i) * np.sin(gamma)
+    )
+    vertical = np.sin(delta) * np.cos(gamma)
+    projection_1 = np.cos(axis) * horizontal + np.sin(axis) * vertical
+    projection_2 = -np.sin(axis) * horizontal + np.cos(axis) * vertical
+    return (
+        fraction * (1.0 - projection_1**2)
+        + (1.0 - fraction) * (1.0 - projection_2**2)
+    )
+
+
 def _polarization_reference(sxrddet, alpha_i):
     """Polarization from orGUI's own z-axis expression.
 
@@ -958,17 +975,13 @@ def _polarization_reference(sxrddet, alpha_i):
     if hasattr(sxrddet, "_alpha_i"):
         del sxrddet._alpha_i
     gamma, delta = sxrddet.surfaceAngles(alpha_i)
-    fraction = sxrddet._polFactor
-    p_hor = (
-        1.0
-        - (
-            np.sin(alpha_i) * np.cos(delta) * np.cos(gamma)
-            + np.cos(alpha_i) * np.sin(gamma)
-        )
-        ** 2
+    return _polarization_from_outgoing_ray(
+        alpha_i,
+        gamma,
+        delta,
+        sxrddet._polAxis,
+        sxrddet._polFactor,
     )
-    p_ver = 1.0 - (np.sin(delta) ** 2) * (np.cos(gamma) ** 2)
-    return fraction * p_hor + (1.0 - fraction) * p_ver
 
 
 def _sxrd_detector(azimuth_deg, pol_axis_deg, fraction):
@@ -1093,10 +1106,6 @@ def test_unpolarized_beam_has_no_azimuthal_dependence():
     np.testing.assert_allclose(correction, 0.5 * (1.0 + np.cos(tth) ** 2), atol=1e-6)
 
 
-@pytest.mark.xfail(
-    strict=True,
-    reason="Stage 1: arm-following polarization ignores polarization_axis",
-)
 @pytest.mark.parametrize("pol_axis_deg", [30.0, 90.0])
 @pytest.mark.parametrize("fraction", [1.0, 0.75])
 def test_arm_following_polarization_honors_the_configured_axis(
@@ -1105,9 +1114,8 @@ def test_arm_following_polarization_honors_the_configured_axis(
     """Point and array evaluators must agree at the calibration position.
 
     This is the minimal reproduction for the targeted-review finding: the
-    array path uses ``_polAxis``, while the arm-following shared evaluator
-    currently does not.  Keeping the expected failure strict makes Stage 1
-    remove the marker when it fixes the shared evaluator.
+    array and arm-following paths must use the same configured incident-field
+    basis.
     """
     detector = _sxrd_detector(90.0, pol_axis_deg, fraction)
     row, column = 309, 243
@@ -1122,3 +1130,67 @@ def test_arm_following_polarization_honors_the_configured_axis(
     )[0]
 
     np.testing.assert_allclose(actual, expected, atol=1e-6)
+
+
+@pytest.mark.parametrize("pol_axis_deg", [0.0, 30.0, 90.0, -40.0])
+@pytest.mark.parametrize("fraction", [1.0, 0.75, 0.5])
+def test_arm_following_polarization_matches_outgoing_ray_projection(
+    pol_axis_deg, fraction
+):
+    """A moved-arm scalar evaluation honors axis and polarization fraction."""
+    detector = _sxrd_detector(90.0, pol_axis_deg, fraction)
+    row = np.array([309.0])
+    column = np.array([243.0])
+    alpha = np.deg2rad(0.6)
+    gamma_arm = np.deg2rad(30.0)
+    delta_arm = np.deg2rad(20.0)
+    gamma, delta = detector.surfaceAnglesPoint(
+        row, column, alpha, gamma_arm, delta_arm
+    )
+    expected = _polarization_from_outgoing_ray(
+        alpha,
+        gamma,
+        delta,
+        np.deg2rad(pol_axis_deg),
+        fraction,
+    )
+
+    actual = detector.polarizationAtPoints(
+        row, column, alpha, gamma_arm, delta_arm
+    )
+
+    np.testing.assert_allclose(actual, expected, atol=1e-12)
+
+
+def test_batched_arm_following_polarization_matches_outgoing_rays():
+    """The multi-frame evaluator preserves the scalar vector convention."""
+    detector = _sxrd_detector(90.0, 35.0, 0.8)
+    row = np.array([100.0, 309.0, 500.0])
+    column = np.array([80.0, 243.0, 420.0])
+    alpha = np.deg2rad([0.6, 2.0])
+    gamma_arm = np.deg2rad([0.0, 30.0])
+    delta_arm = np.deg2rad([0.0, 20.0])
+    expected = []
+    for frame in range(alpha.size):
+        gamma, delta = detector.surfaceAnglesPoint(
+            row,
+            column,
+            alpha[frame],
+            gamma_arm[frame],
+            delta_arm[frame],
+        )
+        expected.append(
+            _polarization_from_outgoing_ray(
+                alpha[frame],
+                gamma,
+                delta,
+                detector._polAxis,
+                detector._polFactor,
+            )
+        )
+
+    actual = detector.polarizationAtPointsFrames(
+        row, column, alpha, gamma_arm, delta_arm
+    )
+
+    np.testing.assert_allclose(actual, expected, atol=1e-12)
diff --git a/orgui/datautils/xrayutils/test/test_corrections_acceptance.py b/orgui/datautils/xrayutils/test/test_corrections_acceptance.py
index c6c3c6b..3c34297 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_acceptance.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_acceptance.py
@@ -107,6 +107,38 @@ def test_acceptance_is_positive_and_vectorized_over_a_scan():
     np.testing.assert_allclose(got, size * det.PER_ROW, rtol=1e-12)
 
 
+def test_acceptance_pairs_each_region_with_its_actual_arm_position():
+    """Vector arm metadata is pairwise, not an arm-by-region product."""
+    det = _calibrated_detector(rot3=np.deg2rad(30.0))
+    row = np.array([200.0, 350.0, 500.0])
+    column = np.array([100.0, 240.0, 440.0])
+    height = np.array([20.0, 40.0, 60.0])
+    alpha = np.deg2rad([1.0, 5.0, 10.0])
+    gamma_arm = np.deg2rad([0.0, 15.0, 30.0])
+    delta_arm = np.deg2rad([0.0, 20.0, 40.0])
+
+    got = acceptance.out_of_plane_acceptance(
+        det, row, column, height, alpha, gamma_arm, delta_arm
+    )
+    expected = np.array(
+        [
+            acceptance.out_of_plane_acceptance(
+                det,
+                row[index],
+                column[index],
+                height[index],
+                alpha[index],
+                gamma_arm[index],
+                delta_arm[index],
+            )
+            for index in range(row.size)
+        ]
+    ).reshape(-1)
+
+    assert got.shape == row.shape
+    np.testing.assert_allclose(got, expected, rtol=1e-12)
+
+
 def test_a_zero_or_negative_region_is_rejected():
     """An empty region accepts no rod, and silently returning 0 would divide."""
     det = _LinearDetector()

From 899c87fe7d372d7f80a2595f83cb64255a751d87 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 16 Sep 2026 14:59:53 -0400
Subject: [PATCH 22/33] feat(phys): add versioned CTR correction records

---
 CHANGELOG.md                                  |  15 +
 doc/design/ctr_stage2_persistence_contract.md |  62 +++
 doc/source/release_notes.rst                  |   2 +
 orgui/app/config_data.py                      | 433 +++++++++++++++++-
 orgui/app/orGUI.py                            | 231 +++++++++-
 orgui/app/peak1Dintegr.py                     |  50 +-
 orgui/app/test/test_config_data.py            |  40 ++
 orgui/app/test/test_config_nexus_layout.py    | 171 +++++++
 orgui/app/test/test_peak1Dintegr.py           |  32 ++
 9 files changed, 1028 insertions(+), 8 deletions(-)
 create mode 100644 doc/design/ctr_stage2_persistence_contract.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a09b632..48efb5f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,21 @@ This is the changelog for the software orGUI, written by Timo Fuchs
 
 Scientific and analysis additions:
 
+- **Saved CTR curves now carry a versioned correction record.** This is a
+  persistence-only compatibility step: numerical defaults and the established
+  ``rois``, ``croibg`` and ``Cfactors_*`` meanings are unchanged. A separate
+  ``ctr_curve_v3`` branch records the reversible pre-normalization scalar
+  curve and variance, exact applied normalization and illumination divisors,
+  explicit applied/not-applied/unavailable/unknown states, pixel-factor
+  provenance, detector-arm/ROI geometry and embedded beam-profile data. The
+  requested correction settings schema is version 3 and stores total incident
+  flux separately from the legacy flux density, together with primary-monitor
+  kind/reference and horizontal-interception fields; absent values remain
+  unknown rather than physical zero or unity. The rocking reducer explicitly
+  accepts the unchanged legacy-algorithm record but refuses a future
+  frame-normalized record until its dedicated dispatch path is implemented,
+  preventing it from silently normalizing a new curve twice.
+
 - **The polarization correction now follows the detector arm.**
   *This changes saved numbers for scans that move the detector arm and for
   arm-corrected integrations using a nonzero configured polarization axis;
diff --git a/doc/design/ctr_stage2_persistence_contract.md b/doc/design/ctr_stage2_persistence_contract.md
new file mode 100644
index 0000000..6ad24fe
--- /dev/null
+++ b/doc/design/ctr_stage2_persistence_contract.md
@@ -0,0 +1,62 @@
+# CTR Stage 2 persistence contract
+
+Status: implemented, 2026-09-16.
+
+Stage 2 introduces persistence and dispatch boundaries only. It deliberately
+does not enable the total-flux calculation or move normalization/footprint
+between extraction and reduction. Existing numerical defaults and legacy
+dataset meanings remain unchanged.
+
+## Requested settings
+
+`configuration/orgui/integration_corrections` now has schema version 3. The
+legacy `beam_flux_density` field remains photons/(s m2). The distinct
+`total_incident_flux` field is photons/s and is never inferred from that
+density. Primary-monitor name, rate/integrated kind, unit, calibration reading
+and calibration exposure have separate fields. Horizontal interception is an
+explicit mode plus optional fraction. Missing values mean unknown or not
+configured; they do not mean zero flux, full interception or a unity divisor.
+
+Measured vertical profiles store their normalized positions [m] and density
+[1/m] in addition to the source path and import settings. Analytical profiles
+remain reproducible from their named shape and parameters.
+
+## Applied curve record
+
+New extractions retain all established groups and add a sibling named
+`ctr_curve_v3`. It is not named `rois` or `counters`, so an older reducer cannot
+mistake this branch for the legacy unnormalized input. The record separates:
+
+- identity: algorithm, output quantity and scale convention;
+- normalization: explicit status, exact divisor and contributing counters;
+- illumination: explicit status, exact divisor, named legacy/new convention,
+  overlap components and alpha in radians when available;
+- base: center/background sums and variances plus the reversible background-
+  subtracted scalar curve and variance before normalization/illumination;
+- pixel corrections: the established combined center/background factors,
+  with separate polarization-only fields reserved for Stage 4;
+- geometry: actual detector arms in radians and ROI location/size in pixels;
+- profile: embedded profile provenance rather than only an external path.
+
+Correction statuses are exactly `applied`, `not_applied`, `unavailable` or
+`unknown`. An absent dataset is never read as unity.
+
+Stationary records capture the scalar curve immediately before the existing
+normalization and active-area divisors. Rocking extraction currently applies
+neither divisor, so both statuses are explicitly `not_applied`; its current
+legacy reducer remains responsible for them until Stage 5.
+
+## Compatibility and dispatch
+
+The existing `rois`, `croibg`, `Cfactors_croi` and `Cfactors_bgroi` datasets
+retain their meanings. Current Stage 2 records identify their algorithm as
+`legacy_stationary_roi_v1` or `legacy_rocking_roi_v1`, allowing the existing
+paths to reproduce the same numbers.
+
+The rocking loader checks the sibling record before returning the legacy ROI
+curve. A record with a non-legacy algorithm (for example the later framewise
+total-flux convention) is refused by the legacy reducer instead of being
+silently reinterpreted. Incomplete older records remain accessible through the
+legacy diagnostic path with unknown provenance. Reduction outputs continue to
+be added as new measurement groups, so re-reduction does not overwrite the
+source extraction record.
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 4120602..ec61654 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -9,6 +9,8 @@ Unreleased (2026-07-19)
 
 Scientific and analysis additions:
 
+- **Saved CTR curves now carry a versioned correction record.** This is a persistence-only compatibility step: numerical defaults and the established ``rois``, ``croibg`` and ``Cfactors_*`` meanings are unchanged. A separate ``ctr_curve_v3`` branch records the reversible pre-normalization scalar curve and variance, exact applied normalization and illumination divisors, explicit applied/not-applied/unavailable/unknown states, pixel-factor provenance, detector-arm/ROI geometry and embedded beam-profile data. The requested correction settings schema is version 3 and stores total incident flux separately from the legacy flux density, together with primary-monitor kind/reference and horizontal-interception fields; absent values remain unknown rather than physical zero or unity. The rocking reducer explicitly accepts the unchanged legacy-algorithm record but refuses a future frame-normalized record until its dedicated dispatch path is implemented, preventing it from silently normalizing a new curve twice.
+
 - **The polarization correction now follows the detector arm.** *This changes saved numbers for scans that move the detector arm and for arm-corrected integrations using a nonzero configured polarization axis; the conventional axis-zero case is unchanged.* The per-pixel polarization array is built from the calibrated geometry, which is right only while the arm stays there. On a scan that drives the arm -- a reflectivity curve, where it follows twice the incidence angle -- the same pixel looks in a different direction on every frame, and the calibrated-position value understated the correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration paths now apply a per-frame factor, ``corrections.detector.polarization_arm_correction``, that moves the correction onto the arm position each frame was measured at. It is exactly one while the arm sits at its calibrated position when both paths use the same configured polarization axis, so an axis-zero fixed-arm scan is bit-identical and needs no switch. The factor is a ratio of two region means rather than a rebuilt per-pixel array, which keeps the cost to a region-sized evaluation per frame; the polarization is not flat across a region at a large scattering angle, so the means matter. The arm-following evaluator now rotates the incident electric-field basis by the configured ``polarization_axis``, matching the calibrated array for zero, 90-degree and intermediate axes and for mixed polarization fractions; it previously assumed an axis of zero. The detector solid angle needs no such correction: an arm rotation is a rigid rotation about the sample, so every pixel keeps its distance and its obliquity to its own line of sight, and the solid angle is invariant under it exactly. The reciprocal-space reconstruction applies the polarization per pixel rather than as a region mean and is unchanged; correcting it there would need the array rebuilt per frame.
 
 - **The arm-following polarization correction no longer makes a mu-scan rocking reduction unusably slow.** It evaluates once and broadcasts when the incidence angle and the arm are constant across a curve, which covers every fixed-arm scan and every th-scan rocking curve; a mu scan rocks the incidence angle itself, and a reflectivity rocking curve additionally tracks the arm at twice it, so nothing was constant and it fell back to a Python loop calling the per-frame correction once per point -- about 20 seconds for a thousand-point mu scan, a minute or more for several thousand, with no error, just a reduction that looked stuck. It is now one batched call per rocking curve instead of one per frame (``corrections.detector.polarization_arm_correction_frames``, backed by ``DetectorCalibration.Detector2D_SXRD._tthAzimuthAtArms``), verified against the per-frame loop to floating-point precision and measured about 7-8x faster end to end. A stationary integration tracking a rod across the detector has no single region to batch on and keeps the per-frame loop, unchanged. **No saved value changes** -- this is the same correction, computed the same way, just not one frame at a time.
diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index f526a2e..27e83c5 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -31,9 +31,20 @@
 
 SCHEMA_VERSION = 1
 
-#: Layout version of the integration_corrections group. Version 2 is the
-#: typed layout that replaced a single JSON string.
-CORRECTIONS_SCHEMA_VERSION = 2
+#: Layout version of the integration_corrections group. Version 2 introduced
+#: the typed layout; version 3 adds explicit total-flux and primary-monitor
+#: settings without reinterpreting the legacy flux-density fields.
+CORRECTIONS_SCHEMA_VERSION = 3
+
+#: Layout version and group name of an applied per-curve correction record.
+#: This deliberately is not named ``rois``: an older reducer must not mistake
+#: a future frame-normalized curve for the legacy unnormalized input.
+CURVE_CORRECTIONS_SCHEMA_VERSION = 3
+CURVE_CORRECTIONS_GROUP = "ctr_curve_v3"
+
+CORRECTION_STATUSES = frozenset(
+    {"applied", "not_applied", "unavailable", "unknown"}
+)
 
 #: Layout version of the roi_integration group.
 ROI_SCHEMA_VERSION = 1
@@ -96,6 +107,18 @@ class CorrectionState:
     # an absolutely scaled structure factor (issue #15); a relative one does
     # not use it.
     beam_flux_density: float | None = None
+    # New total-flux convention. These fields describe requested settings;
+    # the exact values actually used for a curve live in CurveCorrectionRecord.
+    # ``None`` means unknown/not configured, never physical zero.
+    total_incident_flux: float | None = None
+    total_flux_calibrated: bool | None = None
+    primary_monitor: str | None = None
+    primary_monitor_kind: str | None = None
+    primary_monitor_unit: str | None = None
+    monitor_reference_reading: float | None = None
+    monitor_reference_exposure_s: float | None = None
+    horizontal_interception: str | None = None
+    horizontal_intercepted_fraction: float | None = None
     # The beam shape the footprint dialog describes the incident beam with --
     # analytical or measured, and every input either needs. Kept in the same
     # units the dialog itself shows them in (IntegrationCorrectionsDialog.
@@ -112,6 +135,10 @@ class CorrectionState:
     beam_profile_unit: str | None = None
     beam_profile_center: str | None = None
     beam_profile_offset_um: float | None = None
+    # Embedded, normalized measured profile. A path alone is not sufficient
+    # provenance once the source file moves or changes.
+    beam_profile_positions_m: tuple[float, ...] = ()
+    beam_profile_density_per_m: tuple[float, ...] = ()
 
     def to_dict(self) -> dict[str, Any]:
         """Return a JSON-compatible correction-state dictionary."""
@@ -133,9 +160,70 @@ def from_dict(cls, values):
         values["beam_shape_values"] = tuple(
             float(value) for value in values.get("beam_shape_values", ())
         )
+        values["beam_profile_positions_m"] = tuple(
+            float(value) for value in values.get("beam_profile_positions_m", ())
+        )
+        values["beam_profile_density_per_m"] = tuple(
+            float(value)
+            for value in values.get("beam_profile_density_per_m", ())
+        )
         return cls(**values)
 
 
+@dataclass
+class CurveCorrectionRecord:
+    """Applied correction provenance for one saved curve branch.
+
+    Arrays are stored exactly as used, with radians at geometry boundaries.
+    The record is separate from :class:`CorrectionState`: that class captures
+    requested settings, while this one records what happened to the saved
+    numbers. Optional fields remain absent rather than being guessed as unity.
+
+    ``base_croibg`` and its variance are the reversible scalar curve before
+    normalization and illumination divisors. They are not raw detector images
+    and cannot undo arbitrary pixel reweighting.
+    """
+
+    algorithm: str
+    output_quantity: str
+    scale_convention: str
+    normalization_status: str = "unknown"
+    illumination_status: str = "unknown"
+    pixel_correction_status: str = "unknown"
+    normalization_divisor: Any = None
+    normalization_unit: str | None = None
+    normalization_components: tuple[str, ...] = ()
+    illumination_divisor: Any = None
+    illumination_convention: str | None = None
+    vertical_intercepted_fraction: Any = None
+    horizontal_intercepted_fraction: Any = None
+    intercepted_fraction: Any = None
+    alpha: Any = None
+    base_croi: Any = None
+    base_croi_variance: Any = None
+    base_bgroi: Any = None
+    base_bgroi_variance: Any = None
+    base_croibg: Any = None
+    base_croibg_variance: Any = None
+    combined_croi_factor: Any = None
+    combined_bgroi_factor: Any = None
+    polarization_croi_factor: Any = None
+    polarization_bgroi_factor: Any = None
+    gamma_arm: Any = None
+    delta_arm: Any = None
+    roi_x: Any = None
+    roi_y: Any = None
+    roi_width: Any = None
+    roi_height: Any = None
+    roi_x_start: Any = None
+    roi_x_stop: Any = None
+    roi_y_start: Any = None
+    roi_y_stop: Any = None
+    detector_acceptance: Any = None
+    lorentz_mode: str | None = None
+    profile_provenance: dict[str, Any] = field(default_factory=dict)
+
+
 def _as_text(value):
     if isinstance(value, bytes):
         return value.decode()
@@ -368,6 +456,12 @@ def corrections_to_nxdict(state):
             "uncertainty_provenance must be a flat mapping of scalars; a "
             "nested value cannot be written as a NeXus group"
         )
+    if len(state.beam_profile_positions_m) != len(
+        state.beam_profile_density_per_m
+    ):
+        raise ValueError(
+            "embedded beam profile positions and density must have equal length"
+        )
     nxdict = {
         "@NX_class": "NXcollection",
         "@orgui_schema_version": CORRECTIONS_SCHEMA_VERSION,
@@ -381,7 +475,17 @@ def corrections_to_nxdict(state):
             "use_normalization": state.use_normalization,
         }),
         "normalization": _nx_group(
-            {"normalize_exposure": state.normalize_exposure}
+            {
+                "normalize_exposure": state.normalize_exposure,
+                "primary_monitor": state.primary_monitor,
+                "primary_monitor_kind": state.primary_monitor_kind,
+                "primary_monitor_unit": state.primary_monitor_unit,
+                "monitor_reference_reading": state.monitor_reference_reading,
+                "monitor_reference_exposure": (
+                    state.monitor_reference_exposure_s
+                ),
+            },
+            units={"@monitor_reference_exposure_unit": "s"},
         ),
         "pixel_repair": _nx_group({
             "enabled": state.repair_masked_pixels,
@@ -402,10 +506,17 @@ def corrections_to_nxdict(state):
                 "sample_length": state.sample_length_m,
                 "sample_width": state.sample_width_m,
                 "beam_flux_density": state.beam_flux_density,
+                "total_incident_flux": state.total_incident_flux,
+                "total_flux_calibrated": state.total_flux_calibrated,
+                "horizontal_interception": state.horizontal_interception,
+                "horizontal_intercepted_fraction": (
+                    state.horizontal_intercepted_fraction
+                ),
             },
             units={
                 "@sample_size_unit": "m",
                 "@beam_flux_density_unit": "1/(s m^2)",
+                "@total_incident_flux_unit": "photons/s",
             },
         ),
         # The dialog's own display units, not SI: see CorrectionState.
@@ -419,7 +530,11 @@ def corrections_to_nxdict(state):
                 "profile_center": state.beam_profile_center,
                 "profile_offset": state.beam_profile_offset_um,
             },
-            units={"@profile_offset_unit": "micron"},
+            units={
+                "@profile_offset_unit": "micron",
+                "@profile_position_unit": "m",
+                "@profile_density_unit": "1/m",
+            },
         ),
     }
     if state.monitor_corrections:
@@ -434,6 +549,14 @@ def corrections_to_nxdict(state):
         nxdict["beam_shape"]["shape_values"] = np.asarray(
             state.beam_shape_values, dtype=np.float64
         )
+    if state.beam_profile_positions_m:
+        nxdict["beam_shape"]["profile_positions"] = np.asarray(
+            state.beam_profile_positions_m, dtype=np.float64
+        )
+    if state.beam_profile_density_per_m:
+        nxdict["beam_shape"]["profile_density"] = np.asarray(
+            state.beam_profile_density_per_m, dtype=np.float64
+        )
     if state.uncertainty_provenance:
         nxdict["uncertainty_provenance"] = _nx_group(
             dict(state.uncertainty_provenance)
@@ -474,6 +597,21 @@ def corrections_from_nxdict(nxdict):
         "excluded_frames": tuple(int(v) for v in (excluded or ())),
         "uncertainty_provenance": _read_group(nxdict, "uncertainty_provenance"),
     }
+    for name in (
+        "primary_monitor",
+        "primary_monitor_kind",
+        "primary_monitor_unit",
+    ):
+        if name in normalization:
+            values[name] = str(normalization[name])
+    if "monitor_reference_reading" in normalization:
+        values["monitor_reference_reading"] = float(
+            normalization["monitor_reference_reading"]
+        )
+    if "monitor_reference_exposure" in normalization:
+        values["monitor_reference_exposure_s"] = float(
+            normalization["monitor_reference_exposure"]
+        )
     for name in ("use_lorentz", "use_footprint", "use_normalization"):
         if name in switches:
             values[name] = bool(switches[name])
@@ -497,9 +635,19 @@ def corrections_from_nxdict(nxdict):
         ("sample_length_m", "sample_length"),
         ("sample_width_m", "sample_width"),
         ("beam_flux_density", "beam_flux_density"),
+        ("total_incident_flux", "total_incident_flux"),
+        ("horizontal_intercepted_fraction", "horizontal_intercepted_fraction"),
     ):
         if key in footprint:
             values[name] = float(footprint[key])
+    if "total_flux_calibrated" in footprint:
+        values["total_flux_calibrated"] = bool(
+            footprint["total_flux_calibrated"]
+        )
+    if "horizontal_interception" in footprint:
+        values["horizontal_interception"] = str(
+            footprint["horizontal_interception"]
+        )
     beam_shape = _read_group(nxdict, "beam_shape")
     if "analytical" in beam_shape:
         values["beam_shape_analytical"] = bool(beam_shape["analytical"])
@@ -518,9 +666,263 @@ def corrections_from_nxdict(nxdict):
         values["beam_shape_values"] = tuple(
             float(v) for v in np.atleast_1d(beam_shape["shape_values"])
         )
+    if "profile_positions" in beam_shape:
+        values["beam_profile_positions_m"] = tuple(
+            float(v) for v in np.atleast_1d(beam_shape["profile_positions"])
+        )
+    if "profile_density" in beam_shape:
+        values["beam_profile_density_per_m"] = tuple(
+            float(v) for v in np.atleast_1d(beam_shape["profile_density"])
+        )
     return CorrectionState(**values)
 
 
+def _group_metadata(group, name, default=None):
+    """Read one ``@`` metadata value from a dict or live HDF5 group."""
+    if hasattr(group, "attrs"):
+        return _plain(group.attrs.get(name.removeprefix("@"), default))
+    return _plain(group.get(name, default))
+
+
+def _validate_correction_status(name, value):
+    if value not in CORRECTION_STATUSES:
+        raise ValueError(
+            f"{name} must be one of {sorted(CORRECTION_STATUSES)}, got {value!r}"
+        )
+
+
+def curve_correction_record_to_nxdict(record):
+    """Serialize an applied :class:`CurveCorrectionRecord` to NeXus.
+
+    The returned group is intended to live under
+    :data:`CURVE_CORRECTIONS_GROUP`, beside rather than inside legacy
+    ``rois``/``counters`` data. This makes its different normalization
+    contract visible to both humans and dispatch code.
+
+    :param CurveCorrectionRecord record: Applied curve provenance.
+    :rtype: dict
+    :raises ValueError: If a status or profile value is not representable.
+    """
+    for name in (
+        "normalization_status",
+        "illumination_status",
+        "pixel_correction_status",
+    ):
+        _validate_correction_status(name, getattr(record, name))
+    if any(
+        isinstance(value, (dict, list, tuple))
+        for value in record.profile_provenance.values()
+    ):
+        raise ValueError("profile_provenance must be a flat mapping of scalars")
+
+    result = {
+        "@NX_class": "NXcollection",
+        "@orgui_schema_version": CURVE_CORRECTIONS_SCHEMA_VERSION,
+        "@orgui_curve_contract": "frame_corrections",
+        "identity": _nx_group({
+            "algorithm": record.algorithm,
+            "output_quantity": record.output_quantity,
+            "scale_convention": record.scale_convention,
+        }),
+        "normalization": _nx_group({
+            "status": record.normalization_status,
+            "divisor": record.normalization_divisor,
+            "divisor_unit": record.normalization_unit,
+        }),
+        "illumination": _nx_group(
+            {
+                "status": record.illumination_status,
+                "divisor": record.illumination_divisor,
+                "convention": record.illumination_convention,
+                "vertical_intercepted_fraction": (
+                    record.vertical_intercepted_fraction
+                ),
+                "horizontal_intercepted_fraction": (
+                    record.horizontal_intercepted_fraction
+                ),
+                "intercepted_fraction": record.intercepted_fraction,
+                "alpha": record.alpha,
+            },
+            units={"@alpha_unit": "rad"},
+        ),
+        "base": _nx_group({
+            "croi": record.base_croi,
+            "croi_variance": record.base_croi_variance,
+            "bgroi": record.base_bgroi,
+            "bgroi_variance": record.base_bgroi_variance,
+            "croibg": record.base_croibg,
+            "croibg_variance": record.base_croibg_variance,
+        }),
+        "pixel_corrections": _nx_group({
+            "status": record.pixel_correction_status,
+            "combined_croi": record.combined_croi_factor,
+            "combined_bgroi": record.combined_bgroi_factor,
+            "polarization_croi": record.polarization_croi_factor,
+            "polarization_bgroi": record.polarization_bgroi_factor,
+        }),
+        "geometry": _nx_group(
+            {
+                "gamma_arm": record.gamma_arm,
+                "delta_arm": record.delta_arm,
+                "roi_x": record.roi_x,
+                "roi_y": record.roi_y,
+                "roi_width": record.roi_width,
+                "roi_height": record.roi_height,
+                "roi_x_start": record.roi_x_start,
+                "roi_x_stop": record.roi_x_stop,
+                "roi_y_start": record.roi_y_start,
+                "roi_y_stop": record.roi_y_stop,
+                "detector_acceptance": record.detector_acceptance,
+                "lorentz_mode": record.lorentz_mode,
+            },
+            units={
+                "@detector_arm_unit": "rad",
+                "@roi_position_unit": "px",
+                "@detector_acceptance_unit": "rad",
+            },
+        ),
+        "profile": _nx_group(
+            dict(record.profile_provenance),
+            units={
+                "@profile_position_unit": "m",
+                "@profile_density_unit": "1/m",
+                "@profile_offset_unit": "micron",
+            },
+        ),
+    }
+    if record.normalization_components:
+        result["normalization"]["components"] = _string_array(
+            record.normalization_components
+        )
+    return result
+
+
+def curve_correction_record_from_nxdict(nxdict):
+    """Load a :class:`CurveCorrectionRecord` from its versioned group.
+
+    :param dict nxdict: Contents of :data:`CURVE_CORRECTIONS_GROUP`.
+    :rtype: CurveCorrectionRecord
+    :raises ValueError: If this is not a supported versioned curve record.
+    """
+    version = int(_group_metadata(nxdict, "@orgui_schema_version", 0))
+    contract = _as_text(_group_metadata(nxdict, "@orgui_curve_contract", ""))
+    if version != CURVE_CORRECTIONS_SCHEMA_VERSION or contract != "frame_corrections":
+        raise ValueError(
+            f"unsupported curve correction record version/contract: "
+            f"{version}/{contract!r}"
+        )
+    identity = _read_group(nxdict, "identity")
+    normalization = _read_group(nxdict, "normalization")
+    illumination = _read_group(nxdict, "illumination")
+    base = _read_group(nxdict, "base")
+    pixel = _read_group(nxdict, "pixel_corrections")
+    geometry = _read_group(nxdict, "geometry")
+    components = normalization.get("components", ())
+    values = {
+        "algorithm": str(identity["algorithm"]),
+        "output_quantity": str(identity["output_quantity"]),
+        "scale_convention": str(identity["scale_convention"]),
+        "normalization_status": str(normalization.get("status", "unknown")),
+        "illumination_status": str(illumination.get("status", "unknown")),
+        "pixel_correction_status": str(pixel.get("status", "unknown")),
+        "normalization_components": tuple(_read_string_array(components)),
+        "profile_provenance": _read_group(nxdict, "profile"),
+    }
+    if "divisor_unit" in normalization:
+        values["normalization_unit"] = str(normalization["divisor_unit"])
+    if "convention" in illumination:
+        values["illumination_convention"] = str(illumination["convention"])
+    groups = (
+        (normalization, {"normalization_divisor": "divisor"}),
+        (
+            illumination,
+            {
+                "illumination_divisor": "divisor",
+                "vertical_intercepted_fraction": "vertical_intercepted_fraction",
+                "horizontal_intercepted_fraction": "horizontal_intercepted_fraction",
+                "intercepted_fraction": "intercepted_fraction",
+                "alpha": "alpha",
+            },
+        ),
+        (
+            base,
+            {
+                "base_croi": "croi",
+                "base_croi_variance": "croi_variance",
+                "base_bgroi": "bgroi",
+                "base_bgroi_variance": "bgroi_variance",
+                "base_croibg": "croibg",
+                "base_croibg_variance": "croibg_variance",
+            },
+        ),
+        (
+            pixel,
+            {
+                "combined_croi_factor": "combined_croi",
+                "combined_bgroi_factor": "combined_bgroi",
+                "polarization_croi_factor": "polarization_croi",
+                "polarization_bgroi_factor": "polarization_bgroi",
+            },
+        ),
+        (
+            geometry,
+            {
+                "gamma_arm": "gamma_arm",
+                "delta_arm": "delta_arm",
+                "roi_x": "roi_x",
+                "roi_y": "roi_y",
+                "roi_width": "roi_width",
+                "roi_height": "roi_height",
+                "roi_x_start": "roi_x_start",
+                "roi_x_stop": "roi_x_stop",
+                "roi_y_start": "roi_y_start",
+                "roi_y_stop": "roi_y_stop",
+                "detector_acceptance": "detector_acceptance",
+                "lorentz_mode": "lorentz_mode",
+            },
+        ),
+    )
+    for group, mapping in groups:
+        for field_name, dataset_name in mapping.items():
+            if dataset_name in group:
+                values[field_name] = group[dataset_name]
+    record = CurveCorrectionRecord(**values)
+    for name in (
+        "normalization_status",
+        "illumination_status",
+        "pixel_correction_status",
+    ):
+        _validate_correction_status(name, getattr(record, name))
+    return record
+
+
+def curve_record_kind(container):
+    """Classify a loaded curve container without guessing missing provenance.
+
+    :param container: Mapping or HDF5 group containing a saved curve.
+    :returns: ``"versioned"``, ``"legacy"``, or ``"unknown"``.
+    :rtype: str
+    """
+    if CURVE_CORRECTIONS_GROUP in container:
+        group = container[CURVE_CORRECTIONS_GROUP]
+        version = int(_group_metadata(group, "@orgui_schema_version", 0))
+        contract = _as_text(
+            _group_metadata(group, "@orgui_curve_contract", "")
+        )
+        if (
+            version == CURVE_CORRECTIONS_SCHEMA_VERSION
+            and contract == "frame_corrections"
+        ):
+            return "versioned"
+        return "unknown"
+    if "rois" in container or "croibg" in container:
+        return "legacy"
+    counters = container.get("counters") if hasattr(container, "get") else None
+    if counters is not None and "croibg" in counters:
+        return "legacy"
+    return "unknown"
+
+
 def roi_to_nxdict(state):
     """Serialize a :class:`ROIState` as a typed NeXus group.
 
@@ -714,6 +1116,8 @@ def from_gui(cls, gui):
             sample_width_m = None
             beam_flux_density = None
             beam_shape = {}
+            beam_profile_positions_m = ()
+            beam_profile_density_per_m = ()
             if footprint_dialog is not None:
                 sample_length_m = footprint_dialog.sampleLength()
                 sample_width_m = footprint_dialog.sampleWidth()
@@ -721,6 +1125,23 @@ def from_gui(cls, gui):
                 # The dialog's own settings() dict, in its own display units;
                 # see CorrectionState.beam_shape_values.
                 beam_shape = footprint_dialog.settings()
+                if not beam_shape.get("analytical", True):
+                    try:
+                        positions, density = (
+                            footprint_dialog.measuredProfile().profile_curve()
+                        )
+                    except ValueError:
+                        # An unresolved imported path stays unresolved. Config
+                        # capture must not make an otherwise-unused correction
+                        # fatal or invent an empty physical profile.
+                        pass
+                    else:
+                        beam_profile_positions_m = tuple(
+                            float(value) for value in positions
+                        )
+                        beam_profile_density_per_m = tuple(
+                            float(value) for value in density
+                        )
             corrections = CorrectionState(
                 use_mask=bool(options.get("mask", False)) or repair_enabled,
                 use_background=getattr(gui, "background_image", None)
@@ -769,6 +1190,8 @@ def from_gui(cls, gui):
                 beam_profile_unit=beam_shape.get("profile_unit"),
                 beam_profile_center=beam_shape.get("profile_center"),
                 beam_profile_offset_um=beam_shape.get("profile_offset"),
+                beam_profile_positions_m=beam_profile_positions_m,
+                beam_profile_density_per_m=beam_profile_density_per_m,
             )
             roi = ROIState(
                 region=dict(options.get("region", {})),
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index 1ce8e53..6d31bd9 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -75,7 +75,12 @@
 from .bgroi import RectangleBgROI
 from .database import DataBase, FILTERS
 from .mask_config import MaskManager
-from .config_data import ConfigData
+from .config_data import (
+    CURVE_CORRECTIONS_GROUP,
+    ConfigData,
+    CurveCorrectionRecord,
+    curve_correction_record_to_nxdict,
+)
 from types import SimpleNamespace
 
 from ..backend.scans import SimulationScan, scan_arm_angles
@@ -152,6 +157,33 @@ def _rocking_arm_snapshot(gamma_arm, delta_arm, curve_shape):
     }
 
 
+def _curve_profile_provenance(state):
+    """Flat, self-contained beam-profile provenance for a curve record."""
+    result = {
+        "analytical": state.beam_shape_analytical,
+        "shape": state.beam_shape_name,
+        "shape_values": np.asarray(state.beam_shape_values, dtype=np.float64)
+        if state.beam_shape_values
+        else None,
+        "profile_file": state.beam_profile_file,
+        "profile_content": state.beam_profile_content,
+        "profile_unit": state.beam_profile_unit,
+        "profile_center": state.beam_profile_center,
+        "profile_offset_um": state.beam_profile_offset_um,
+        "profile_positions_m": np.asarray(
+            state.beam_profile_positions_m, dtype=np.float64
+        )
+        if state.beam_profile_positions_m
+        else None,
+        "profile_density_per_m": np.asarray(
+            state.beam_profile_density_per_m, dtype=np.float64
+        )
+        if state.beam_profile_density_per_m
+        else None,
+    }
+    return {name: value for name, value in result.items() if value is not None}
+
+
 def _display_roi_geometry(center, left, right, top, bottom):
     """Convert detector-array ROI slices to plot rectangle geometry.
 
@@ -1581,6 +1613,20 @@ def rocking_integrate(self, xylist, rois, hkl_del_gam, refldict, name):
             )
             return {"status": "error", "message": "No database available"}
         dc = self.ubcalc.detectorCal
+        rocking_roi_edges = {
+            "x_start": np.asarray(
+                [region[0].start for region in rois["center"]], dtype=np.int64
+            ),
+            "x_stop": np.asarray(
+                [region[0].stop for region in rois["center"]], dtype=np.int64
+            ),
+            "y_start": np.asarray(
+                [region[1].start for region in rois["center"]], dtype=np.int64
+            ),
+            "y_stop": np.asarray(
+                [region[1].stop for region in rois["center"]], dtype=np.int64
+            ),
+        }
 
         imgmask = None
 
@@ -2517,6 +2563,43 @@ def sumImage(i):
                 }
 
         data_2d_structured[self.activescanname]["measurement"][name]["rois"] = rois
+        # A distinct versioned branch preserves the reversible scalar curve
+        # and applied-state provenance without changing the legacy ``rois``
+        # contract consumed by today's reducer. Stage 5 will opt into this
+        # branch when framewise Q/H normalization becomes active.
+        curve_record = CurveCorrectionRecord(
+            algorithm="legacy_rocking_roi_v1",
+            output_quantity="rocking_roi_curve",
+            scale_convention="legacy_unnormalized",
+            normalization_status="not_applied",
+            illumination_status="not_applied",
+            pixel_correction_status=("applied" if corr else "not_applied"),
+            alpha=np.deg2rad(rois["alpha"]),
+            base_croi=rois["croi"],
+            base_croi_variance=rois["croi"],
+            base_bgroi=rois["bgroi"],
+            base_bgroi_variance=rois["bgroi"],
+            base_croibg=rois["croibg"],
+            base_croibg_variance=np.square(rois["croibg_errors"]),
+            combined_croi_factor=rois["Cfactors_croi"],
+            combined_bgroi_factor=rois["Cfactors_bgroi"],
+            gamma_arm=rois["gamma_arm"],
+            delta_arm=rois["delta_arm"],
+            roi_x=rois["x"],
+            roi_y=rois["y"],
+            roi_width=rois["hsize"],
+            roi_height=rois["vsize"],
+            roi_x_start=rocking_roi_edges["x_start"],
+            roi_x_stop=rocking_roi_edges["x_stop"],
+            roi_y_start=rocking_roi_edges["y_start"],
+            roi_y_stop=rocking_roi_edges["y_stop"],
+            profile_provenance=_curve_profile_provenance(
+                config_snapshot.corrections
+            ),
+        )
+        data_2d_structured[self.activescanname]["measurement"][name][
+            CURVE_CORRECTIONS_GROUP
+        ] = curve_correction_record_to_nxdict(curve_record)
 
         error = self._saveIntegrationResult(
             data_2d_structured, f"the rocking scan integration {name}"
@@ -5943,6 +6026,10 @@ def integrateROI(self):
         y_coord1_a = hkl_del_gam_1[:, 7]
         roi_hsize1_a = np.full_like(dataavail, hsize, dtype=int)
         roi_vsize1_a = np.full_like(dataavail, vsize, dtype=int)
+        roi_x_start1_a = np.zeros_like(dataavail, dtype=int)
+        roi_x_stop1_a = np.zeros_like(dataavail, dtype=int)
+        roi_y_start1_a = np.zeros_like(dataavail, dtype=int)
+        roi_y_stop1_a = np.zeros_like(dataavail, dtype=int)
 
         croi2_a = np.zeros_like(dataavail, dtype=np.float64)
         cpixel2_a = np.zeros_like(dataavail, dtype=np.float64)
@@ -5973,6 +6060,10 @@ def integrateROI(self):
         y_coord2_a = hkl_del_gam_2[:, 7]
         roi_hsize2_a = np.full_like(dataavail, hsize, dtype=int)
         roi_vsize2_a = np.full_like(dataavail, vsize, dtype=int)
+        roi_x_start2_a = np.zeros_like(dataavail, dtype=int)
+        roi_x_stop2_a = np.zeros_like(dataavail, dtype=int)
+        roi_y_start2_a = np.zeros_like(dataavail, dtype=int)
+        roi_y_stop2_a = np.zeros_like(dataavail, dtype=int)
 
         progress = logger_utils.create_progress_logger(
             self, len(self.fscan), "Integrating stationary scan"
@@ -6023,12 +6114,16 @@ def integrateROI(self):
             )
             roi_hsize1_a[i] = int(np.abs(np.diff(croi_key[0])[0]))
             roi_vsize1_a[i] = int(np.abs(np.diff(croi_key[1])[0]))
+            roi_x_start1_a[i], roi_x_stop1_a[i] = croi_key[0]
+            roi_y_start1_a[i], roi_y_stop1_a[i] = croi_key[1]
             key = self.intkey(hkl_del_gam_2[i, 6:8])
             croi_key = np.array(
                 [[key[0].start, key[0].stop], [key[1].start, key[1].stop]]
             )
             roi_hsize2_a[i] = int(np.abs(np.diff(croi_key[0])[0]))
             roi_vsize2_a[i] = int(np.abs(np.diff(croi_key[1])[0]))
+            roi_x_start2_a[i], roi_x_stop2_a[i] = croi_key[0]
+            roi_y_start2_a[i], roi_y_stop2_a[i] = croi_key[1]
 
         if HAS_ACCEL:
             roi_lists_accel = []
@@ -6612,6 +6707,19 @@ def sumImage(i):
                 ),
             )
 
+        # Reversible scalar base, after the existing background/pixel path but
+        # before the framewise normalization and illumination divisors. Keep a
+        # copy because apply_stationary_corrections returns the saved legacy
+        # intensity below.
+        base_croibg1 = np.asarray(croibg1_a, dtype=np.float64).copy()
+        base_croibg1_variance = np.square(
+            np.asarray(croibg1_err_a, dtype=np.float64)
+        )
+        base_croibg2 = np.asarray(croibg2_a, dtype=np.float64).copy()
+        base_croibg2_variance = np.square(
+            np.asarray(croibg2_err_a, dtype=np.float64)
+        )
+
         croibg1_a, croibg1_err_a = integration_corrections.apply_stationary_corrections(
             croibg1_a, croibg1_err_a, factors1
         )
@@ -6700,6 +6808,13 @@ def sumImage(i):
             om = np.full_like(mu, om)
         if len(np.asarray(mu).shape) == 0:
             mu = np.full_like(om, mu)
+        gamma_arm_all, delta_arm_all = self.getArmAngles()
+        gamma_arm_all = np.broadcast_to(
+            np.asarray(gamma_arm_all, dtype=np.float64), (nodatapoints,)
+        ).copy()
+        delta_arm_all = np.broadcast_to(
+            np.asarray(delta_arm_all, dtype=np.float64), (nodatapoints,)
+        ).copy()
 
         suffix = ""
         i = 0
@@ -6859,6 +6974,120 @@ def sumImage(i):
         }
 
         config_snapshot = ConfigData.from_gui(self)
+
+        normalization_status = "not_applied"
+        normalization_divisor = None
+        if options["normalization"]:
+            if normalization_applied:
+                normalization_status = "applied"
+                normalization_divisor = factors1.get("C_norm")
+            else:
+                normalization_status = "unavailable"
+        illumination_status = (
+            "applied" if options["footprint"] else "not_applied"
+        )
+
+        def versioned_stationary_curve(
+            factors,
+            base_croibg,
+            base_croibg_variance,
+            croi,
+            bgroi,
+            combined_croi,
+            combined_bgroi,
+            x,
+            y,
+            width,
+            height,
+            x_start,
+            x_stop,
+            y_start,
+            y_stop,
+        ):
+            """Build the non-legacy sibling branch for one trajectory."""
+            record = CurveCorrectionRecord(
+                algorithm="legacy_stationary_roi_v1",
+                output_quantity="stationary_roi_intensity",
+                scale_convention=(
+                    "legacy_density_area"
+                    if options["footprint"]
+                    else "legacy_relative"
+                ),
+                normalization_status=normalization_status,
+                illumination_status=illumination_status,
+                pixel_correction_status=("applied" if corr else "not_applied"),
+                normalization_divisor=normalization_divisor,
+                normalization_unit=(
+                    "legacy_counter_product"
+                    if normalization_divisor is not None
+                    else None
+                ),
+                normalization_components=tuple(normalization_applied),
+                illumination_divisor=factors.get("C_illum_area"),
+                illumination_convention=(
+                    "legacy_C_illum_area" if options["footprint"] else None
+                ),
+                vertical_intercepted_fraction=factors.get("C_flux_on_sample"),
+                alpha=alpha_all,
+                base_croi=croi,
+                base_croi_variance=croi,
+                base_bgroi=bgroi,
+                base_bgroi_variance=bgroi,
+                base_croibg=base_croibg,
+                base_croibg_variance=base_croibg_variance,
+                combined_croi_factor=combined_croi,
+                combined_bgroi_factor=combined_bgroi,
+                gamma_arm=gamma_arm_all,
+                delta_arm=delta_arm_all,
+                roi_x=x,
+                roi_y=y,
+                roi_width=width,
+                roi_height=height,
+                roi_x_start=x_start,
+                roi_x_stop=x_stop,
+                roi_y_start=y_start,
+                roi_y_stop=y_stop,
+                lorentz_mode=("stationary" if options["lorentz"] else None),
+                profile_provenance=_curve_profile_provenance(
+                    config_snapshot.corrections
+                ),
+            )
+            return curve_correction_record_to_nxdict(record)
+
+        datas1[CURVE_CORRECTIONS_GROUP] = versioned_stationary_curve(
+            factors1,
+            base_croibg1,
+            base_croibg1_variance,
+            croi1_a,
+            bgroi1_a,
+            Corr_croi1_a,
+            Corr_bgroi1_a,
+            x_coord1_a,
+            y_coord1_a,
+            roi_hsize1_a,
+            roi_vsize1_a,
+            roi_x_start1_a,
+            roi_x_stop1_a,
+            roi_y_start1_a,
+            roi_y_stop1_a,
+        )
+        datas2[CURVE_CORRECTIONS_GROUP] = versioned_stationary_curve(
+            factors2,
+            base_croibg2,
+            base_croibg2_variance,
+            croi2_a,
+            bgroi2_a,
+            Corr_croi2_a,
+            Corr_bgroi2_a,
+            x_coord2_a,
+            y_coord2_a,
+            roi_hsize2_a,
+            roi_vsize2_a,
+            roi_x_start2_a,
+            roi_x_stop2_a,
+            roi_y_start2_a,
+            roi_y_stop2_a,
+        )
         data = {
             self.activescanname: {
                 "instrument": {
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index b187389..eed1385 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -56,6 +56,8 @@
 
 from . import qutils
 from .config_data import (
+    CURVE_CORRECTIONS_GROUP,
+    CURVE_CORRECTIONS_SCHEMA_VERSION,
     ConfigData,
     CorrectionState,
     corrections_from_nxdict,
@@ -2000,10 +2002,54 @@ def onRoiChanged(self, roi):
         # with qt.QSignalBlocker(self.anchorROIButton):
         #    self.anchorROIButton.setChecked(True)
 
+    @staticmethod
+    def _legacy_rocking_curve_group(h5_obj):
+        """Return legacy ``rois`` only when the sibling record permits it.
+
+        Stage-2 records describe the unchanged legacy extraction and therefore
+        explicitly allow this compatibility path. A future normalized record
+        uses the same distinct sibling name but a different algorithm; this
+        reducer must refuse to reinterpret that curve as unnormalized input.
+        An incomplete record beside an existing legacy group remains usable as
+        legacy data, with its provenance reported as unknown.
+        """
+        if CURVE_CORRECTIONS_GROUP in h5_obj:
+            record = h5_obj[CURVE_CORRECTIONS_GROUP]
+            version = int(record.attrs.get("orgui_schema_version", 0))
+            contract = record.attrs.get("orgui_curve_contract", "")
+            if isinstance(contract, bytes):
+                contract = contract.decode()
+            try:
+                algorithm = record["identity"]["algorithm"][()]
+                if isinstance(algorithm, bytes):
+                    algorithm = algorithm.decode()
+                else:
+                    algorithm = str(algorithm)
+            except (KeyError, TypeError, ValueError):
+                algorithm = None
+            if (
+                version == CURVE_CORRECTIONS_SCHEMA_VERSION
+                and contract == "frame_corrections"
+                and algorithm is not None
+                and not algorithm.startswith("legacy_rocking_roi_")
+            ):
+                raise ValueError(
+                    "This rocking curve uses a versioned normalized contract "
+                    "that the legacy reducer must not reinterpret. Use a "
+                    "reducer that supports its correction record."
+                )
+            if algorithm is None:
+                logger.warning(
+                    "The rocking curve has an incomplete correction record; "
+                    "using its preserved legacy ROI curve with unknown "
+                    "provenance."
+                )
+        return h5_obj["rois"]
+
     def get_ro_curve(self, idx):
         name = self._currentRoInfo["name"]
         h5_obj = self.database.nxfile[name]
-        cnters = h5_obj["rois"]
+        cnters = self._legacy_rocking_curve_group(h5_obj)
         curve = {
             "axisname": self._currentRoInfo["axisname"],
             "axis": self._currentRoInfo["axis"],
@@ -2015,7 +2061,7 @@ def get_ro_curve(self, idx):
     def get_all_ro_curves(self):
         name = self._currentRoInfo["name"]
         h5_obj = self.database.nxfile[name]
-        cnters = h5_obj["rois"]
+        cnters = self._legacy_rocking_curve_group(h5_obj)
         curve = {
             "axisname": self._currentRoInfo["axisname"],
             "axis": self._currentRoInfo["axis"],
diff --git a/orgui/app/test/test_config_data.py b/orgui/app/test/test_config_data.py
index 7d22b98..58e1040 100644
--- a/orgui/app/test/test_config_data.py
+++ b/orgui/app/test/test_config_data.py
@@ -312,6 +312,46 @@ def test_from_gui_captures_the_footprint_dialogs_inputs(qapp):
         footprint_dialog.deleteLater()
 
 
+def test_from_gui_embeds_a_loaded_measured_beam_profile():
+    """A future reader must not depend on the original profile file path."""
+    config = _make_config()
+    positions = np.array([-2e-4, 0.0, 2e-4])
+    density = np.array([500.0, 4000.0, 500.0])
+    profile = SimpleNamespace(profile_curve=lambda: (positions, density))
+    footprint = SimpleNamespace(
+        sampleLength=lambda: 3e-3,
+        sampleWidth=lambda: 8e-3,
+        beamFluxDensity=lambda: 2e12,
+        settings=lambda: {
+            "analytical": False,
+            "profile_file": "moved/or/replaced.dat",
+            "profile_content": "intensity",
+            "profile_unit": "mm",
+        },
+        measuredProfile=lambda: profile,
+    )
+    gui = SimpleNamespace(
+        ubcalc=SimpleNamespace(
+            detectorCal=config.detector,
+            crystal=config.unit_cell,
+            ubCal=config.ub_calculator,
+            mu=config.mu,
+            chi=config.chi,
+            phi=config.phi,
+            n=config.refraction_index,
+        ),
+        scanSelector=SimpleNamespace(
+            get_integration_options=lambda: {},
+            correctionsDialog=SimpleNamespace(footprintOptions=footprint),
+        ),
+    )
+
+    captured = ConfigData.from_gui(gui).corrections
+
+    assert captured.beam_profile_positions_m == pytest.approx(positions)
+    assert captured.beam_profile_density_per_m == pytest.approx(density)
+
+
 def test_apply_to_gui_restores_the_footprint_dialogs_inputs(qapp):
     """Restoring a config sets L, W and the beam flux on the shared dialog."""
     config = _make_config()
diff --git a/orgui/app/test/test_config_nexus_layout.py b/orgui/app/test/test_config_nexus_layout.py
index 0037bd7..4d0789b 100644
--- a/orgui/app/test/test_config_nexus_layout.py
+++ b/orgui/app/test/test_config_nexus_layout.py
@@ -22,10 +22,16 @@
 
 from orgui.app.config_data import (
     CORRECTIONS_SCHEMA_VERSION,
+    CURVE_CORRECTIONS_GROUP,
+    CURVE_CORRECTIONS_SCHEMA_VERSION,
     CorrectionState,
+    CurveCorrectionRecord,
     ROIState,
     corrections_from_nxdict,
     corrections_to_nxdict,
+    curve_correction_record_from_nxdict,
+    curve_correction_record_to_nxdict,
+    curve_record_kind,
     roi_from_nxdict,
     roi_to_nxdict,
 )
@@ -65,6 +71,15 @@ def _populated_corrections():
         sample_length_m=5e-3,
         sample_width_m=3e-3,
         beam_flux_density=1.2e16,
+        total_incident_flux=4.2e11,
+        total_flux_calibrated=True,
+        primary_monitor="ic2",
+        primary_monitor_kind="rate",
+        primary_monitor_unit="count/s",
+        monitor_reference_reading=2.4e6,
+        monitor_reference_exposure_s=0.5,
+        horizontal_interception="fraction",
+        horizontal_intercepted_fraction=0.85,
         beam_shape_analytical=False,
         beam_shape_name="Trapezoid",
         beam_shape_values=(90.0, 30.0),
@@ -73,6 +88,8 @@ def _populated_corrections():
         beam_profile_unit="mm",
         beam_profile_center="median",
         beam_profile_offset_um=-12.5,
+        beam_profile_positions_m=(-1e-4, 0.0, 1e-4),
+        beam_profile_density_per_m=(1000.0, 8000.0, 1000.0),
     )
 
 
@@ -154,6 +171,16 @@ def test_a_nested_uncertainty_provenance_is_refused():
         corrections_to_nxdict(state)
 
 
+def test_an_incomplete_embedded_profile_is_refused():
+    state = CorrectionState(
+        beam_profile_positions_m=(0.0, 1.0),
+        beam_profile_density_per_m=(1.0,),
+    )
+
+    with pytest.raises(ValueError, match="equal length"):
+        corrections_to_nxdict(state)
+
+
 def test_unknown_datasets_are_ignored(tmp_path):
     """A configuration from a newer orGUI still loads."""
     nxdict = corrections_to_nxdict(CorrectionState(use_mask=True))
@@ -178,6 +205,150 @@ def test_the_layout_is_browsable_and_versioned(tmp_path):
     assert np.array_equal(np.asarray(nxdict["excluded_frames"]), [3, 7, 11])
 
 
+def test_total_flux_fields_do_not_reinterpret_legacy_density(tmp_path):
+    """The two flux conventions remain distinct through persistence."""
+    state = CorrectionState(
+        beam_flux_density=1.2e16,
+        total_incident_flux=4.2e11,
+        total_flux_calibrated=True,
+        primary_monitor="ic2",
+        primary_monitor_kind="rate",
+        primary_monitor_unit="count/s",
+        monitor_reference_reading=2.4e6,
+        monitor_reference_exposure_s=0.5,
+        horizontal_interception="fraction",
+        horizontal_intercepted_fraction=0.85,
+    )
+
+    nxdict = _through_file(corrections_to_nxdict(state), tmp_path)
+    loaded = corrections_from_nxdict(nxdict)
+
+    assert nxdict["@orgui_schema_version"] == 3
+    assert nxdict["footprint"]["@beam_flux_density_unit"] == "1/(s m^2)"
+    assert nxdict["footprint"]["@total_incident_flux_unit"] == "photons/s"
+    assert loaded == state
+
+
+def _curve_record():
+    return CurveCorrectionRecord(
+        algorithm="legacy_stationary_roi_v1",
+        output_quantity="roi_intensity",
+        scale_convention="legacy_density_area",
+        normalization_status="applied",
+        illumination_status="applied",
+        pixel_correction_status="applied",
+        normalization_divisor=np.array([2.0, 4.0]),
+        normalization_unit="s count/s",
+        normalization_components=("exposure_time", "ic2"),
+        illumination_divisor=np.array([0.5, 0.25]),
+        illumination_convention="legacy_C_illum_area",
+        vertical_intercepted_fraction=np.array([0.8, 0.9]),
+        horizontal_intercepted_fraction=np.array([1.0, 1.0]),
+        intercepted_fraction=np.array([0.8, 0.9]),
+        alpha=np.deg2rad([1.0, 2.0]),
+        base_croi=np.array([100.0, 120.0]),
+        base_croi_variance=np.array([100.0, 120.0]),
+        base_bgroi=np.array([20.0, 24.0]),
+        base_bgroi_variance=np.array([20.0, 24.0]),
+        base_croibg=np.array([80.0, 96.0]),
+        base_croibg_variance=np.array([125.0, 150.0]),
+        combined_croi_factor=np.array([1.1, 1.2]),
+        combined_bgroi_factor=np.array([1.05, 1.06]),
+        gamma_arm=np.deg2rad([10.0, 20.0]),
+        delta_arm=np.deg2rad([1.0, 2.0]),
+        roi_x=np.array([12.0, 13.0]),
+        roi_y=np.array([22.0, 23.0]),
+        roi_width=np.array([10, 10]),
+        roi_height=np.array([6, 6]),
+        roi_x_start=np.array([7, 8]),
+        roi_x_stop=np.array([17, 18]),
+        roi_y_start=np.array([19, 20]),
+        roi_y_stop=np.array([25, 26]),
+        lorentz_mode="stationary",
+        profile_provenance={
+            "analytical": True,
+            "shape": "Gaussian",
+            "profile_content": "embedded parameters",
+        },
+    )
+
+
+def test_applied_curve_record_arrays_survive_save_and_reopen(tmp_path):
+    """Exact base values and divisors are independently recoverable."""
+    expected = _curve_record()
+    stored = _through_file(
+        curve_correction_record_to_nxdict(expected), tmp_path, "curve"
+    )
+    loaded = curve_correction_record_from_nxdict(stored)
+
+    assert stored["@orgui_schema_version"] == CURVE_CORRECTIONS_SCHEMA_VERSION
+    assert stored["@orgui_curve_contract"] == "frame_corrections"
+    assert loaded.algorithm == expected.algorithm
+    assert loaded.normalization_components == expected.normalization_components
+    assert loaded.normalization_unit == expected.normalization_unit
+    assert loaded.illumination_convention == expected.illumination_convention
+    assert loaded.profile_provenance == expected.profile_provenance
+    for name in (
+        "normalization_divisor",
+        "illumination_divisor",
+        "base_croi",
+        "base_croi_variance",
+        "base_bgroi",
+        "base_bgroi_variance",
+        "base_croibg",
+        "base_croibg_variance",
+        "gamma_arm",
+        "delta_arm",
+        "roi_x_start",
+        "roi_x_stop",
+        "roi_y_start",
+        "roi_y_stop",
+    ):
+        np.testing.assert_array_equal(getattr(loaded, name), getattr(expected, name))
+
+
+def test_versioned_curve_branch_is_not_dispatched_as_legacy():
+    """A normalized-capable branch cannot masquerade as ``rois/croibg``."""
+    versioned = {CURVE_CORRECTIONS_GROUP: curve_correction_record_to_nxdict(
+        _curve_record()
+    )}
+
+    assert CURVE_CORRECTIONS_GROUP != "rois"
+    assert curve_record_kind(versioned) == "versioned"
+    assert curve_record_kind({"rois": {"croibg": np.ones(2)}}) == "legacy"
+    assert curve_record_kind({"counters": {"croibg": np.ones(2)}}) == "legacy"
+    assert curve_record_kind({}) == "unknown"
+
+
+def test_missing_applied_fields_remain_unknown(tmp_path):
+    """Absence must never be interpreted as an applied divisor of one."""
+    record = CurveCorrectionRecord(
+        algorithm="legacy_import",
+        output_quantity="roi_intensity",
+        scale_convention="unknown",
+    )
+    loaded = curve_correction_record_from_nxdict(
+        _through_file(curve_correction_record_to_nxdict(record), tmp_path)
+    )
+
+    assert loaded.normalization_status == "unknown"
+    assert loaded.illumination_status == "unknown"
+    assert loaded.normalization_divisor is None
+    assert loaded.illumination_divisor is None
+
+
+def test_invalid_applied_status_is_refused():
+    record = CurveCorrectionRecord(
+        algorithm="bad",
+        output_quantity="roi_intensity",
+        scale_convention="unknown",
+        normalization_status="probably",
+    )
+
+    with pytest.raises(ValueError, match="normalization_status"):
+        curve_correction_record_to_nxdict(record)
+
+
 def test_a_legacy_json_configuration_still_reads():
     """Existing databases must keep loading; only writing changed."""
     legacy = CorrectionState(
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index 24a8374..38208b9 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -681,6 +681,38 @@ def test_legacy_rocking_acceptance_reports_calibration_fallback(caplog):
     assert "calibration position (legacy fallback)" in caplog.text
 
 
+def test_stage2_record_explicitly_allows_the_legacy_curve(tmp_path):
+    """The new provenance sibling does not alter current numerical defaults."""
+    path = tmp_path / "legacy_curve_record.h5"
+    with h5py.File(path, "w") as database:
+        scan = database.create_group("scan")
+        rois = scan.create_group("rois")
+        record = scan.create_group("ctr_curve_v3")
+        record.attrs["orgui_schema_version"] = 3
+        record.attrs["orgui_curve_contract"] = "frame_corrections"
+        identity = record.create_group("identity")
+        identity.create_dataset("algorithm", data="legacy_rocking_roi_v1")
+
+        selected = RockingPeakIntegrator._legacy_rocking_curve_group(scan)
+        assert selected.name == rois.name
+
+
+def test_versioned_normalized_curve_is_not_consumed_as_legacy(tmp_path):
+    """Future Q/H-normalized curves require their explicit dispatch path."""
+    path = tmp_path / "normalized_curve_record.h5"
+    with h5py.File(path, "w") as database:
+        scan = database.create_group("scan")
+        scan.create_group("rois")
+        record = scan.create_group("ctr_curve_v3")
+        record.attrs["orgui_schema_version"] = 3
+        record.attrs["orgui_curve_contract"] = "frame_corrections"
+        identity = record.create_group("identity")
+        identity.create_dataset("algorithm", data="total_flux_framewise_v1")
+
+        with pytest.raises(ValueError, match="must not reinterpret"):
+            RockingPeakIntegrator._legacy_rocking_curve_group(scan)
+
+
 @pytest.mark.parametrize("applied_at_extraction", [True, False])
 def test_the_typed_corrections_group_is_read_back(applied_at_extraction):
     """The F6 compensation must survive the layout it is stored in.

From 38559002fad77401b925c5b44cce54a683f968bf Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 16 Sep 2026 15:18:06 -0400
Subject: [PATCH 23/33] feat(phys): add total-flux correction core

---
 CHANGELOG.md                                  |  11 ++
 doc/design/ctr_stage3_total_flux_contract.md  |  81 ++++++++++
 doc/source/ctr_structure_factors.rst          |  39 +++++
 doc/source/release_notes.rst                  |   2 +
 .../xrayutils/corrections/activearea.py       | 108 +++++++++++++
 .../xrayutils/corrections/beamprofile.py      |  42 +++++
 .../xrayutils/corrections/measurement.py      | 133 ++++++++++++++++
 .../xrayutils/corrections/normalization.py    | 147 ++++++++++++++++++
 .../test/test_corrections_activearea.py       | 122 +++++++++++++++
 .../test/test_corrections_beamprofile.py      |  17 ++
 .../test/test_corrections_measurement.py      |  72 +++++++++
 .../test/test_corrections_normalization.py    | 133 ++++++++++++++++
 12 files changed, 907 insertions(+)
 create mode 100644 doc/design/ctr_stage3_total_flux_contract.md
 create mode 100644 orgui/datautils/xrayutils/test/test_corrections_normalization.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 48efb5f..8ccac15 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,17 @@ This is the changelog for the software orGUI, written by Timo Fuchs
 
 Scientific and analysis additions:
 
+- **The numerical correction core now has an explicit total-incident-flux
+  convention.** New pure APIs calculate calibrated photons per frame from a
+  constant flux or an explicitly rate-like/integrated monitor, distinguish the
+  intercepted fraction from the dimensionless illumination divisor
+  ``H = f_hit / sin(alpha)``, and reduce photon-normalized yield with
+  ``K = r_e^2 lambda^2 / A_u^2``. Built-in beam profiles retain the finite
+  grazing-incidence limit, and horizontal interception must be stated
+  separately because a vertical profile cannot infer it. This stage adds the
+  unit-audited numerical path only: current extraction/UI behavior and the
+  legacy flux-density APIs remain unchanged until the later wiring stage.
+
 - **Saved CTR curves now carry a versioned correction record.** This is a
   persistence-only compatibility step: numerical defaults and the established
   ``rois``, ``croibg`` and ``Cfactors_*`` meanings are unchanged. A separate
diff --git a/doc/design/ctr_stage3_total_flux_contract.md b/doc/design/ctr_stage3_total_flux_contract.md
new file mode 100644
index 0000000..b123825
--- /dev/null
+++ b/doc/design/ctr_stage3_total_flux_contract.md
@@ -0,0 +1,81 @@
+# CTR Stage 3 total-flux numerical contract
+
+Status: implemented, 2026-09-16.
+
+Stage 3 adds pure numerical building blocks for calibrated total incident flux.
+It does not change either integration path, the current GUI/config behavior or
+the legacy flux-density APIs. Stage 5 will select and persist this convention
+during extraction.
+
+## Per-frame incident photons
+
+`corrections.normalization.frame_fluence` returns `Q_f` in photons. A constant
+total flux `Phi` [photons/s] gives `Q_f = Phi T_f`. A rate-like primary monitor
+uses
+
+```text
+Q_f = Phi_ref T_f M_f / M_ref.
+```
+
+An integrated monitor already contains the exposure and instead uses
+
+```text
+Q_f = Phi_ref T_ref U_f / U_ref.
+```
+
+There is no second multiplication by `T_f` in the integrated case. Monitor kind
+is explicit; the numerical core does not infer it from a counter name or unit.
+The beamline counters expected for the first wiring pass, including QM2 `ic2`,
+are rate-like after applying their configured conversion to total incident
+flux. `relative_frame_fluence` applies the same exposure rule without claiming
+photon units when no absolute calibration exists.
+
+All fluxes, exposures, monitor readings and calibration references must be
+finite and strictly positive. Calibration references correspond to the stated
+reference flux; no scan-mean normalization is introduced.
+
+## Beam/sample illumination
+
+For a normalized vertical beam profile, sample length `L` [m], incidence angle
+`alpha` [rad] and explicit horizontal intercepted fraction `f_x`,
+
+```text
+f_z   = profile.flux_on_sample(alpha, L)
+f_hit = f_z f_x
+H     = f_hit / sin(alpha).
+```
+
+`corrections.activearea.intercepted_fraction` returns `f_hit`, while
+`illumination_divisor` returns the dimensionless `H`. These are different
+quantities: photons physically hitting the sample are `Q_f f_hit`, whereas the
+retained CTR reduction divides counts by `Q_f H`.
+
+`BeamProfile.flux_over_sine` evaluates the ratio directly. Built-in measured,
+distribution and analytical Gaussian profiles continue it to the finite
+grazing-incidence limit, avoiding numerical zero divided by zero. Existing
+external profile subclasses remain instantiable through a non-abstract default
+implementation.
+
+The vertical profile supplies no horizontal geometry. `f_x` is therefore an
+explicit number in `(0, 1]`; one means the full horizontal beam is intercepted.
+No general two-dimensional clipping model is implied.
+
+## Structure-factor scale
+
+`corrections.measurement.total_flux_prefactor` returns
+
+```text
+K = r_e^2 lambda^2 / A_u^2,
+```
+
+with wavelength in Angstrom and surface unit-cell area in square Angstrom.
+`structure_factor_squared_from_photon_yield` reduces
+`Y = N_net / (Q_f H)` with the existing scan-mode angular factor and optional
+detector efficiency. `photon_yield_from_structure_factor` is its exact forward
+inverse.
+
+The total-flux identity is pinned independently for a separable 2-D Gaussian:
+total flux times `H` equals peak flux density times the existing effective beam
+area. Thus `Q H` replaces the legacy density-times-area fluence; it is not an
+extra footprint correction. `scale_factor`, `structure_factor_squared` and
+`integrated_intensity` retain their legacy density semantics unchanged.
diff --git a/doc/source/ctr_structure_factors.rst b/doc/source/ctr_structure_factors.rst
index 61dc987..68c8391 100644
--- a/doc/source/ctr_structure_factors.rst
+++ b/doc/source/ctr_structure_factors.rst
@@ -138,6 +138,45 @@ set of truncation rods can be brought onto one scale before they are combined.
 The relation is kinematical: it does not hold near a bulk Bragg peak, nor below
 the critical angle, where the distorted-wave treatment of :doc:`dwba` applies.
 
+Total-incident-flux numerical API
+---------------------------------
+
+The correction core provides an explicit alternative to the legacy peak-flux-
+density times effective-area convention. This API is available for scripted
+reductions, but is not yet selected by the integration dialogs or extraction
+paths.
+
+``corrections.normalization.frame_fluence`` calculates incident photons
+:math:`Q_f` in a frame. A rate-like monitor is multiplied by that frame's
+exposure; an integrated monitor is not, because its reading already contains
+the exposure. The monitor kind and its calibration reference are mandatory
+rather than inferred from a counter name. The uncalibrated
+``relative_frame_fluence`` helper follows the same exposure rule while keeping
+the output on a relative scale.
+
+For a normalized vertical beam profile, incidence angle :math:`\alpha` in
+radians and sample length :math:`L` in metres,
+``corrections.activearea.illumination_divisor`` returns
+
+.. math::
+
+   H = \frac{f_z f_x}{\sin\alpha},
+
+where :math:`f_z` is the vertical beam fraction on the sample and :math:`f_x`
+is an explicitly supplied horizontal intercepted fraction. ``H`` is
+dimensionless. It is not the fraction of photons that hit the sample; that
+fraction is :math:`f_\mathrm{hit}=f_zf_x`. Built-in profiles evaluate the
+finite grazing-incidence limit without clipping the angle.
+
+Given a background-subtracted photon-normalized yield
+:math:`Y=N_\mathrm{net}/(Q_f H)`, the pair
+``measurement.structure_factor_squared_from_photon_yield`` and
+``measurement.photon_yield_from_structure_factor`` applies the existing scan-
+mode angular factor and the total-flux prefactor
+:math:`K=r_e^2\lambda^2/A_u^2`. Wavelength is in Angstrom and surface
+unit-cell area in square Angstrom. Existing ``scale_factor`` and
+``structure_factor_squared`` calls keep their flux-density semantics.
+
 CTR fit predictions and statistics
 ----------------------------------
 
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index ec61654..19d6701 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -9,6 +9,8 @@ Unreleased (2026-07-19)
 
 Scientific and analysis additions:
 
+- **The numerical correction core now has an explicit total-incident-flux convention.** New pure APIs calculate calibrated photons per frame from a constant flux or an explicitly rate-like/integrated monitor, distinguish the intercepted fraction from the dimensionless illumination divisor ``H = f_hit / sin(alpha)``, and reduce photon-normalized yield with ``K = r_e^2 lambda^2 / A_u^2``. Built-in beam profiles retain the finite grazing-incidence limit, and horizontal interception must be stated separately because a vertical profile cannot infer it. This stage adds the unit-audited numerical path only: current extraction/UI behavior and the legacy flux-density APIs remain unchanged until the later wiring stage.
+
 - **Saved CTR curves now carry a versioned correction record.** This is a persistence-only compatibility step: numerical defaults and the established ``rois``, ``croibg`` and ``Cfactors_*`` meanings are unchanged. A separate ``ctr_curve_v3`` branch records the reversible pre-normalization scalar curve and variance, exact applied normalization and illumination divisors, explicit applied/not-applied/unavailable/unknown states, pixel-factor provenance, detector-arm/ROI geometry and embedded beam-profile data. The requested correction settings schema is version 3 and stores total incident flux separately from the legacy flux density, together with primary-monitor kind/reference and horizontal-interception fields; absent values remain unknown rather than physical zero or unity. The rocking reducer explicitly accepts the unchanged legacy-algorithm record but refuses a future frame-normalized record until its dedicated dispatch path is implemented, preventing it from silently normalizing a new curve twice.
 
 - **The polarization correction now follows the detector arm.** *This changes saved numbers for scans that move the detector arm and for arm-corrected integrations using a nonzero configured polarization axis; the conventional axis-zero case is unchanged.* The per-pixel polarization array is built from the calibrated geometry, which is right only while the arm stays there. On a scan that drives the arm -- a reflectivity curve, where it follows twice the incidence angle -- the same pixel looks in a different direction on every frame, and the calibrated-position value understated the correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration paths now apply a per-frame factor, ``corrections.detector.polarization_arm_correction``, that moves the correction onto the arm position each frame was measured at. It is exactly one while the arm sits at its calibrated position when both paths use the same configured polarization axis, so an axis-zero fixed-arm scan is bit-identical and needs no switch. The factor is a ratio of two region means rather than a rebuilt per-pixel array, which keeps the cost to a region-sized evaluation per frame; the polarization is not flat across a region at a large scattering angle, so the means matter. The arm-following evaluator now rotates the incident electric-field basis by the configured ``polarization_axis``, matching the calibrated array for zero, 90-degree and intermediate axes and for mixed polarization fractions; it previously assumed an axis of zero. The detector solid angle needs no such correction: an arm rotation is a rigid rotation about the sample, so every pixel keeps its distance and its obliquity to its own line of sight, and the solid angle is invariant under it exactly. The reciprocal-space reconstruction applies the polarization per pixel rather than as a region mean and is unchanged; correcting it there would need the array rebuilt per frame.
diff --git a/orgui/datautils/xrayutils/corrections/activearea.py b/orgui/datautils/xrayutils/corrections/activearea.py
index 70664df..1d12dae 100644
--- a/orgui/datautils/xrayutils/corrections/activearea.py
+++ b/orgui/datautils/xrayutils/corrections/activearea.py
@@ -68,6 +68,13 @@
     19 % at grazing incidence and by 6.5 % once the beam is fully on the
     sample, so the closed form is not a general shortcut and this module does
     not offer one.
+
+For the alternative total-incident-flux convention, this module also returns
+the intercepted fraction :math:`f_\mathrm{hit}=f_zf_x` and the dimensionless
+illumination divisor :math:`H=f_\mathrm{hit}/\sin\alpha`. These replace the
+legacy density-times-area term; they are not additional corrections. The
+horizontal fraction is required explicitly because a vertical profile cannot
+determine it.
 """
 
 import numpy as np
@@ -77,10 +84,111 @@
 __all__ = [
     "beam_limited_area",
     "footprint_length",
+    "illumination_divisor",
+    "intercepted_fraction",
     "slit_limited_area",
 ]
 
 
+def _total_flux_inputs(alpha, sample_length, horizontal_fraction, profile):
+    """Validate and return inputs shared by total-flux overlap helpers."""
+    if profile is None:
+        raise ValueError("total-flux illumination needs a beam profile")
+    if not float(sample_length) > 0 or not np.isfinite(sample_length):
+        raise ValueError("sample_length must be finite and positive, in meter")
+    alpha = np.asarray(alpha, dtype=np.float64)
+    if (
+        np.any(alpha <= 0)
+        or np.any(alpha > np.pi / 2)
+        or not np.all(np.isfinite(alpha))
+    ):
+        raise ValueError(
+            "alpha must be finite and in the physical interval (0, pi/2] rad"
+        )
+    horizontal = np.asarray(horizontal_fraction, dtype=np.float64)
+    if (
+        np.any(horizontal <= 0)
+        or np.any(horizontal > 1)
+        or not np.all(np.isfinite(horizontal))
+    ):
+        raise ValueError("horizontal_fraction must be finite and in (0, 1]")
+    return alpha, horizontal
+
+
+def intercepted_fraction(
+    alpha,
+    sample_length,
+    profile,
+    *,
+    horizontal_fraction,
+):
+    r"""Fraction :math:`f_\mathrm{hit}=f_z f_x` of total flux on sample.
+
+    The vertical fraction ``f_z`` is the integral of ``profile`` over the
+    sample's projected interval. ``horizontal_fraction`` supplies the
+    independently known horizontal interception; a one-dimensional vertical
+    profile cannot infer it.
+
+    :param alpha: Incidence angle(s), in radian and in ``(0, pi/2]``.
+    :param float sample_length: Sample length along the beam, in meter.
+    :param profile: A :class:`~.beamprofile.BeamProfile`.
+    :param horizontal_fraction: Known horizontal intercepted fraction
+        :math:`f_x`, in ``(0, 1]``.
+    :returns: Dimensionless total intercepted fraction.
+    :rtype: numpy.ndarray
+    :raises ValueError: If the geometry, profile or fraction is invalid.
+    """
+    alpha, horizontal = _total_flux_inputs(
+        alpha, sample_length, horizontal_fraction, profile
+    )
+    vertical = np.asarray(
+        profile.flux_on_sample(alpha, float(sample_length)), dtype=np.float64
+    )
+    if (
+        np.any(vertical < 0)
+        or np.any(vertical > 1.0 + 1e-12)
+        or not np.all(np.isfinite(vertical))
+    ):
+        raise ValueError("beam profile returned an invalid intercepted fraction")
+    return vertical * horizontal
+
+
+def illumination_divisor(
+    alpha,
+    sample_length,
+    profile,
+    *,
+    horizontal_fraction,
+):
+    r"""Total-flux illumination divisor :math:`H=f_\mathrm{hit}/\sin\alpha`.
+
+    This is the dimensionless geometrical divisor paired with a total incident
+    frame fluence :math:`Q_f`. It is a replacement convention for the legacy
+    density-times-active-area product, not an additional footprint factor.
+    The profile evaluates ``f_z / sin(alpha)`` directly so the finite
+    grazing-incidence limit is retained without silently clipping the angle.
+
+    :param alpha: Incidence angle(s), in radian and in ``(0, pi/2]``.
+    :param float sample_length: Sample length along the beam, in meter.
+    :param profile: A :class:`~.beamprofile.BeamProfile`.
+    :param horizontal_fraction: Known horizontal intercepted fraction
+        :math:`f_x`, in ``(0, 1]``.
+    :returns: Dimensionless :math:`H`, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If the geometry or overlap is nonphysical.
+    """
+    alpha, horizontal = _total_flux_inputs(
+        alpha, sample_length, horizontal_fraction, profile
+    )
+    ratio = np.asarray(
+        profile.flux_over_sine(alpha, float(sample_length)), dtype=np.float64
+    )
+    result = ratio * horizontal
+    if np.any(result <= 0) or not np.all(np.isfinite(result)):
+        raise ValueError("sample/beam overlap must be finite and positive")
+    return result
+
+
 def footprint_length(alpha, beam_height, sample_length):
     r"""Illuminated length along the beam, in meter.
 
diff --git a/orgui/datautils/xrayutils/corrections/beamprofile.py b/orgui/datautils/xrayutils/corrections/beamprofile.py
index abb5937..7b98b61 100644
--- a/orgui/datautils/xrayutils/corrections/beamprofile.py
+++ b/orgui/datautils/xrayutils/corrections/beamprofile.py
@@ -152,6 +152,26 @@ def corrections(self, alpha, L):
         """
         return self.flux_on_sample(alpha, L), self.illuminated_area_fraction(alpha, L)
 
+    def flux_over_sine(self, alpha, L):
+        r"""Stable ratio :math:`f_z(\alpha, L)/\sin\alpha`.
+
+        This is the vertical part of the total-flux illumination divisor.
+        Implementations continue the ratio to its finite grazing-incidence
+        limit instead of dividing two independently vanishing values.
+
+        :param alpha: Positive incidence angle(s), in radian.
+        :param float L: Sample length along the beam, in meter.
+        :returns: Dimensionless ratio, broadcast over ``alpha``.
+        Custom profiles may override this method to supply an analytic
+        grazing-incidence limit. The default remains compatible with older
+        :class:`BeamProfile` subclasses and is valid for nonzero ``alpha``.
+
+        :rtype: numpy.ndarray
+        """
+        sine = np.sin(np.asarray(alpha, dtype=np.float64))
+        with np.errstate(divide="ignore", invalid="ignore"):
+            return np.asarray(self.flux_on_sample(alpha, L)) / sine
+
     @abstractmethod
     def profile_curve(self, n=512):
         """Sample the profile for display.
@@ -266,6 +286,17 @@ def flux_on_sample(self, alpha, L):
         """
         return self._flux(L * np.sin(np.asarray(alpha, dtype=float)))
 
+    def flux_over_sine(self, alpha, L):
+        r"""Return :math:`f_z/\sin\alpha` with its finite grazing limit."""
+        sine = np.sin(np.asarray(alpha, dtype=np.float64))
+        h = float(L) * sine
+        result = np.empty_like(sine)
+        resolved = np.abs(h) > self._tiny
+        np.divide(self._flux(h), sine, out=result, where=resolved)
+        if np.any(~resolved):
+            result[~resolved] = float(L) * self._density_at(0.0)
+        return result
+
     def illuminated_area_fraction(self, alpha, L):
         """Illuminated fraction of the projected sample footprint.
 
@@ -315,6 +346,17 @@ def illuminated_area_fraction(self, alpha, L):
             L * np.sin(alpha)
         )
 
+    def flux_over_sine(self, alpha, L):
+        r"""Return :math:`f_z/\sin\alpha`, including its zero-angle limit."""
+        sine = np.sin(np.asarray(alpha, dtype=np.float64))
+        flux = self.flux_on_sample(alpha, L)
+        result = np.empty_like(sine)
+        nonzero = sine != 0.0
+        np.divide(flux, sine, out=result, where=nonzero)
+        if np.any(~nonzero):
+            result[~nonzero] = float(L) / (np.sqrt(2 * np.pi) * self.sigma)
+        return result
+
     def profile_curve(self, n=512):
         """Sample the Gaussian over +- 4 sigma around the sample center."""
         z = np.linspace(-4.0 * self.sigma, 4.0 * self.sigma, int(n))
diff --git a/orgui/datautils/xrayutils/corrections/measurement.py b/orgui/datautils/xrayutils/corrections/measurement.py
index c07628d..f49e4be 100644
--- a/orgui/datautils/xrayutils/corrections/measurement.py
+++ b/orgui/datautils/xrayutils/corrections/measurement.py
@@ -126,6 +126,11 @@
 Either way :math:`A` is the same for a rocking and for a stationary
 measurement at the same incidence angle, so it cancels from their ratio and
 cannot be the reason the two disagree. It does set the absolute scale.
+
+The explicit total-flux entry points use the algebraically equivalent
+:math:`Y=N_\mathrm{net}/(QH)` and
+:math:`K=r_e^2\lambda^2/A_u^2`. They do not reinterpret ``flux_density`` or
+the legacy active-area APIs.
 """
 
 import numpy as np
@@ -142,10 +147,13 @@
     "integrated_intensity",
     "mode_components",
     "normalized_intensity",
+    "photon_yield_from_structure_factor",
     "reflectivity_from_structure_factor",
     "scale_factor",
     "structure_factor_from_reflectivity",
     "structure_factor_squared",
+    "structure_factor_squared_from_photon_yield",
+    "total_flux_prefactor",
 ]
 
 #: Classical electron radius in meter (CODATA 2018).
@@ -421,6 +429,131 @@ def scale_factor(wavelength, unitcell_area, active_area=1.0, flux_density=1.0):
     )
 
 
+def total_flux_prefactor(wavelength, unitcell_area):
+    r"""Total-flux CTR prefactor :math:`K=r_e^2\lambda^2/A_u^2`.
+
+    This is the prefactor paired with photon-normalized yield
+    :math:`Y=N_\mathrm{net}/(QH)`. It contains neither a flux density nor an
+    active area: the total incident frame fluence :math:`Q` and the
+    dimensionless illumination divisor :math:`H` replace that legacy product.
+
+    :param wavelength: X-ray wavelength, in Angstrom.
+    :param unitcell_area: Surface unit-cell area, in square Angstrom.
+    :returns: Dimensionless prefactor, broadcast over the inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If either physical input is not finite and positive.
+    """
+    wavelength = np.asarray(wavelength, dtype=np.float64)
+    unitcell_area = np.asarray(unitcell_area, dtype=np.float64)
+    if not np.all(np.isfinite(wavelength)):
+        raise ValueError("wavelength must be finite and positive, in Angstrom")
+    if not np.all(np.isfinite(unitcell_area)):
+        raise ValueError(
+            "unitcell_area must be finite and positive, in square Angstrom"
+        )
+    return _reflectivity_prefactor(wavelength, unitcell_area)
+
+
+def _total_flux_efficiency(detector_efficiency):
+    efficiency = np.asarray(detector_efficiency, dtype=np.float64)
+    if np.any(efficiency <= 0) or not np.all(np.isfinite(efficiency)):
+        raise ValueError("detector_efficiency must be finite and positive")
+    return efficiency
+
+
+def structure_factor_squared_from_photon_yield(
+    photon_yield,
+    mode,
+    alpha=None,
+    delta=None,
+    gamma=None,
+    detector_acceptance=None,
+    wavelength=None,
+    unitcell_area=None,
+    detector_efficiency=1.0,
+):
+    r"""Reduce :math:`Y=N_\mathrm{net}/(QH)` to :math:`|F_{hkl}|^2`.
+
+    For a rocking scan ``photon_yield`` is the angular integral of the
+    framewise yield in radians. For a stationary frame it is the scalar yield
+    itself. The mode-dependent factor remains :func:`angular_factor`; only the
+    illumination/fluence convention differs from
+    :func:`structure_factor_squared`.
+
+    :param photon_yield: Counts divided framewise by calibrated incident
+        photons ``Q`` and dimensionless illumination ``H``.
+    :param str mode: Measurement mode accepted by :func:`angular_factor`.
+    :param alpha: Incidence angle, radian.
+    :param delta: In-plane detector angle, radian.
+    :param gamma: Out-of-plane detector angle, radian.
+    :param detector_acceptance: Rocking out-of-plane acceptance, radian.
+    :param wavelength: X-ray wavelength, Angstrom.
+    :param unitcell_area: Surface unit-cell area, square Angstrom.
+    :param detector_efficiency: Further multiplicative detector response.
+    :returns: Structure factor squared, in electron units squared for a
+        calibrated ``Q`` and stated detector response.
+    :rtype: numpy.ndarray
+    :raises ValueError: If scale inputs or detector efficiency are invalid.
+    """
+    if wavelength is None or unitcell_area is None:
+        raise ValueError(
+            "wavelength (Angstrom) and unitcell_area (square Angstrom) set the "
+            "scale and must both be given"
+        )
+    eta = angular_factor(
+        mode,
+        alpha=alpha,
+        delta=delta,
+        gamma=gamma,
+        detector_acceptance=detector_acceptance,
+    )
+    return np.asarray(photon_yield, dtype=np.float64) / (
+        total_flux_prefactor(wavelength, unitcell_area)
+        * eta
+        * _total_flux_efficiency(detector_efficiency)
+    )
+
+
+def photon_yield_from_structure_factor(
+    f2,
+    mode,
+    alpha=None,
+    delta=None,
+    gamma=None,
+    detector_acceptance=None,
+    wavelength=None,
+    unitcell_area=None,
+    detector_efficiency=1.0,
+):
+    r"""Forward total-flux model, inverse of the yield reduction.
+
+    Arguments and units match
+    :func:`structure_factor_squared_from_photon_yield`; ``f2`` is in electron
+    units squared and the result is the expected counts per ``Q H``.
+
+    :returns: Photon-normalized detector yield.
+    :rtype: numpy.ndarray
+    """
+    if wavelength is None or unitcell_area is None:
+        raise ValueError(
+            "wavelength (Angstrom) and unitcell_area (square Angstrom) set the "
+            "scale and must both be given"
+        )
+    eta = angular_factor(
+        mode,
+        alpha=alpha,
+        delta=delta,
+        gamma=gamma,
+        detector_acceptance=detector_acceptance,
+    )
+    return (
+        np.asarray(f2, dtype=np.float64)
+        * total_flux_prefactor(wavelength, unitcell_area)
+        * eta
+        * _total_flux_efficiency(detector_efficiency)
+    )
+
+
 def structure_factor_squared(
     intensity,
     mode,
diff --git a/orgui/datautils/xrayutils/corrections/normalization.py b/orgui/datautils/xrayutils/corrections/normalization.py
index 5181bba..ee7f6be 100644
--- a/orgui/datautils/xrayutils/corrections/normalization.py
+++ b/orgui/datautils/xrayutils/corrections/normalization.py
@@ -38,10 +38,17 @@
 import numpy as np
 
 __all__ = [
+    "MONITOR_INTEGRATED",
+    "MONITOR_RATE",
     "broadcast_counter",
+    "frame_fluence",
     "normalization_divisor",
+    "relative_frame_fluence",
 ]
 
+MONITOR_RATE = "rate"
+MONITOR_INTEGRATED = "integrated"
+
 
 def broadcast_counter(value, size, name):
     """Broadcast a scalar or per-frame counter to ``size`` values.
@@ -101,3 +108,143 @@ def normalization_divisor(size, exposure_time=None, monitors=None):
         applied.append(f"monitor:{name}")
 
     return divisor, applied
+
+
+def _positive(value, name):
+    """Return ``value`` as float array after physical-value validation."""
+    array = np.asarray(value, dtype=np.float64)
+    if np.any(array <= 0) or not np.all(np.isfinite(array)):
+        raise ValueError(f"{name} must be finite and positive")
+    return array
+
+
+def _monitor_inputs(monitor, monitor_kind):
+    """Validate the monitor-kind pair shared by fluence helpers."""
+    if monitor_kind is None:
+        if monitor is not None:
+            raise ValueError("monitor_kind is required when a monitor is given")
+        return None
+    if monitor_kind not in (MONITOR_RATE, MONITOR_INTEGRATED):
+        raise ValueError(
+            f"monitor_kind must be {MONITOR_RATE!r} or "
+            f"{MONITOR_INTEGRATED!r}, got {monitor_kind!r}"
+        )
+    if monitor is None:
+        raise ValueError(f"a {monitor_kind} monitor value is required")
+    return _positive(monitor, "monitor")
+
+
+def frame_fluence(
+    total_flux,
+    exposure_time=None,
+    monitor=None,
+    monitor_kind=None,
+    reference_monitor=None,
+    reference_exposure=None,
+):
+    r"""Calibrated incident photons :math:`Q_f` in every frame.
+
+    ``total_flux`` is the calibrated full beam at the sample position before
+    sample clipping, in photons/s. With no monitor it is assumed constant and
+    multiplied by the frame exposure. A rate-like monitor scales that product
+    by ``monitor / reference_monitor``. An integrated monitor already contains
+    the frame exposure, so it instead uses the calibration exposure exactly
+    once:
+
+    .. math::
+
+        Q_f = \Phi_\mathrm{ref} T_f M_f/M_\mathrm{ref}
+
+    for a rate, and
+
+    .. math::
+
+        Q_f = \Phi_\mathrm{ref} T_\mathrm{ref} U_f/U_\mathrm{ref}
+
+    for an integrated reading. Passing ``exposure_time`` in the integrated
+    case is allowed for a common calling interface but does not multiply the
+    result.
+
+    :param total_flux: Reference total incident flux, photons/s.
+    :param exposure_time: Per-frame exposure, seconds. Required without a
+        monitor and for a rate-like monitor.
+    :param monitor: Per-frame primary-monitor reading.
+    :param str monitor_kind: ``"rate"``, ``"integrated"`` or ``None``.
+    :param reference_monitor: Monitor reading associated with ``total_flux``.
+    :param reference_exposure: Exposure of an integrated reference reading,
+        seconds. Required only for an integrated monitor.
+    :returns: Incident photons per frame, broadcast over all inputs.
+    :rtype: numpy.ndarray
+    :raises ValueError: If a required input is absent, non-finite or not
+        positive, or the monitor kind is invalid.
+    """
+    flux = _positive(total_flux, "total_flux")
+    monitor_values = _monitor_inputs(monitor, monitor_kind)
+
+    if monitor_kind is None:
+        if reference_monitor is not None or reference_exposure is not None:
+            raise ValueError("monitor references require a monitor")
+        if exposure_time is None:
+            raise ValueError("exposure_time is required without a monitor")
+        return flux * _positive(exposure_time, "exposure_time")
+
+    if reference_monitor is None:
+        raise ValueError("reference_monitor is required for a calibrated monitor")
+    reference = _positive(reference_monitor, "reference_monitor")
+
+    if monitor_kind == MONITOR_RATE:
+        if exposure_time is None:
+            raise ValueError("exposure_time is required for a rate monitor")
+        if reference_exposure is not None:
+            raise ValueError(
+                "reference_exposure applies only to an integrated monitor"
+            )
+        return (
+            flux
+            * _positive(exposure_time, "exposure_time")
+            * monitor_values
+            / reference
+        )
+
+    if reference_exposure is None:
+        raise ValueError(
+            "reference_exposure is required for an integrated monitor"
+        )
+    return (
+        flux
+        * _positive(reference_exposure, "reference_exposure")
+        * monitor_values
+        / reference
+    )
+
+
+def relative_frame_fluence(
+    exposure_time=None,
+    monitor=None,
+    monitor_kind=None,
+):
+    r"""Uncalibrated relative incident fluence for every frame.
+
+    This preserves variations between frames without claiming photon units.
+    With no monitor the relative divisor is the exposure. For a rate monitor
+    it is ``exposure_time * monitor``; for an integrated monitor it is the
+    monitor reading alone, because that reading already integrated over the
+    frame exposure.
+
+    :param exposure_time: Per-frame exposure, seconds.
+    :param monitor: Per-frame primary-monitor reading.
+    :param str monitor_kind: ``"rate"``, ``"integrated"`` or ``None``.
+    :returns: Relative per-frame fluence divisor.
+    :rtype: numpy.ndarray
+    :raises ValueError: If required inputs are absent or nonphysical.
+    """
+    monitor_values = _monitor_inputs(monitor, monitor_kind)
+    if monitor_kind is None:
+        if exposure_time is None:
+            raise ValueError("exposure_time is required without a monitor")
+        return _positive(exposure_time, "exposure_time")
+    if monitor_kind == MONITOR_RATE:
+        if exposure_time is None:
+            raise ValueError("exposure_time is required for a rate monitor")
+        return _positive(exposure_time, "exposure_time") * monitor_values
+    return monitor_values
diff --git a/orgui/datautils/xrayutils/test/test_corrections_activearea.py b/orgui/datautils/xrayutils/test/test_corrections_activearea.py
index 99b960a..b6b3e88 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_activearea.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_activearea.py
@@ -110,6 +110,128 @@ def test_the_two_limits_disagree_and_that_is_the_experimental_question():
     np.testing.assert_allclose(beam, beam[0], rtol=1e-12)
 
 
+def test_total_flux_top_hat_overlap_has_the_closed_form():
+    """``H`` is the intercepted fraction divided by ``sin(alpha)``."""
+    alpha = np.deg2rad(np.array([0.05, 0.5, 5.0]))
+    horizontal = 0.72
+    vertical = np.minimum(L * np.sin(alpha) / H, 1.0)
+
+    fraction = activearea.intercepted_fraction(
+        alpha, L, top_hat_profile(H), horizontal_fraction=horizontal
+    )
+    divisor = activearea.illumination_divisor(
+        alpha, L, top_hat_profile(H), horizontal_fraction=horizontal
+    )
+
+    np.testing.assert_allclose(fraction, horizontal * vertical, rtol=1e-12)
+    np.testing.assert_allclose(
+        divisor, horizontal * vertical / np.sin(alpha), rtol=1e-12
+    )
+    np.testing.assert_allclose(divisor * np.sin(alpha), fraction, rtol=1e-12)
+
+
+def test_horizontal_interception_scales_total_flux_illumination():
+    """A vertical profile cannot infer horizontal sample/beam clipping."""
+    alpha = np.deg2rad(0.6)
+    profile = gaussian_profile(H)
+
+    full = activearea.illumination_divisor(
+        alpha, L, profile, horizontal_fraction=1.0
+    )
+    partial = activearea.illumination_divisor(
+        alpha, L, profile, horizontal_fraction=0.35
+    )
+
+    np.testing.assert_allclose(partial, 0.35 * full, rtol=1e-12)
+
+
+def test_horizontal_interception_must_be_explicit():
+    with pytest.raises(TypeError, match="horizontal_fraction"):
+        activearea.illumination_divisor(np.deg2rad(0.6), L, gaussian_profile(H))
+
+
+def test_total_flux_and_density_conventions_match_for_a_gaussian_beam():
+    """Integrating a 2-D Gaussian converts peak density into total flux."""
+    alpha = np.deg2rad(np.array([0.08, 0.3, 1.2, 8.0]))
+    sigma_x = 120e-6
+    sigma_z = 9e-6
+    fwhm_z = 2.0 * np.sqrt(2.0 * np.log(2.0)) * sigma_z
+    profile = gaussian_profile(fwhm_z)
+    peak_flux_density = 3.1e17  # photons / (s m^2)
+    total_flux = peak_flux_density * 2.0 * np.pi * sigma_x * sigma_z
+
+    legacy = peak_flux_density * activearea.beam_limited_area(
+        alpha,
+        np.sqrt(2.0 * np.pi) * sigma_x,
+        L,
+        profile,
+    )
+    total = total_flux * activearea.illumination_divisor(
+        alpha, L, profile, horizontal_fraction=1.0
+    )
+
+    np.testing.assert_allclose(total, legacy, rtol=2e-12)
+
+
+def test_vertical_offset_changes_total_flux_overlap():
+    """A displaced sample intercepts less of the same incident beam."""
+    alpha = np.deg2rad(0.12)
+    centered = activearea.intercepted_fraction(
+        alpha, L, gaussian_profile(H), horizontal_fraction=1.0
+    )
+    displaced = activearea.intercepted_fraction(
+        alpha,
+        L,
+        gaussian_profile(H, offset=2.0 * H),
+        horizontal_fraction=1.0,
+    )
+
+    assert displaced < centered
+
+
+def test_gaussian_illumination_has_a_finite_grazing_limit():
+    """The direct ratio avoids a zero-over-zero loss at tiny incidence."""
+    sigma = H / (2.0 * np.sqrt(2.0 * np.log(2.0)))
+    expected = L / (np.sqrt(2.0 * np.pi) * sigma)
+
+    got = activearea.illumination_divisor(
+        np.array([1e-20, 1e-15, 1e-10]),
+        L,
+        gaussian_profile(H),
+        horizontal_fraction=1.0,
+    )
+
+    np.testing.assert_allclose(got, expected, rtol=5e-9)
+
+
+@pytest.mark.parametrize("alpha", [0.0, -1e-3, np.pi, np.nan])
+def test_total_flux_illumination_rejects_nonphysical_angles(alpha):
+    with pytest.raises(ValueError, match="physical interval"):
+        activearea.illumination_divisor(
+            alpha, L, gaussian_profile(H), horizontal_fraction=1.0
+        )
+
+
+@pytest.mark.parametrize("horizontal", [0.0, -0.1, 1.1, np.inf])
+def test_total_flux_illumination_rejects_bad_horizontal_fraction(horizontal):
+    with pytest.raises(ValueError, match="horizontal_fraction"):
+        activearea.illumination_divisor(
+            np.deg2rad(1.0),
+            L,
+            gaussian_profile(H),
+            horizontal_fraction=horizontal,
+        )
+
+
+def test_total_flux_illumination_rejects_zero_overlap():
+    profile = top_hat_profile(H, offset=10.0 * H)
+
+    with pytest.raises(ValueError, match="overlap"):
+        activearea.illumination_divisor(
+            np.deg2rad(0.05), L, profile, horizontal_fraction=1.0
+        )
+
+
 def test_sizes_must_be_physical():
     """A zero or negative size is a units mistake, not a value."""
     alpha = np.deg2rad(1.0)
diff --git a/orgui/datautils/xrayutils/test/test_corrections_beamprofile.py b/orgui/datautils/xrayutils/test/test_corrections_beamprofile.py
index 3fc06ba..a69f61e 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_beamprofile.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_beamprofile.py
@@ -67,6 +67,23 @@ def test_measured_profile_reproduces_analytical_gaussian():
     np.testing.assert_allclose(area_num, area_ana, rtol=1e-6)
 
 
+def test_total_flux_ratio_reproduces_analytical_gaussian_and_zero_limit():
+    """Both Gaussian implementations evaluate ``f_z / sin(alpha)`` stably."""
+    fwhm = 20e-6
+    analytical = GaussianBeamProfile(fwhm)
+    numerical = MeasuredBeamProfile(*_sampled_gaussian(fwhm))
+    alpha = np.concatenate(([0.0, 1e-15], ALPHAS))
+
+    ratio_ana = analytical.flux_over_sine(alpha, L)
+    ratio_num = numerical.flux_over_sine(alpha, L)
+
+    sigma = fwhm / (2.0 * np.sqrt(2.0 * np.log(2.0)))
+    assert ratio_ana[0] == pytest.approx(
+        L / (np.sqrt(2.0 * np.pi) * sigma), rel=1e-12
+    )
+    np.testing.assert_allclose(ratio_num, ratio_ana, rtol=1e-6)
+
+
 def test_measured_profile_recovers_gaussian_width():
     """FWHM, rms width and the three center definitions of a Gaussian."""
     fwhm = 264.7e-6
diff --git a/orgui/datautils/xrayutils/test/test_corrections_measurement.py b/orgui/datautils/xrayutils/test/test_corrections_measurement.py
index fcd0429..aaaf8a4 100644
--- a/orgui/datautils/xrayutils/test/test_corrections_measurement.py
+++ b/orgui/datautils/xrayutils/test/test_corrections_measurement.py
@@ -165,6 +165,78 @@ def test_scale_factor_rejects_nonphysical_lengths():
         ii.scale_factor(WAVELENGTH, 0.0)
 
 
+def test_total_flux_prefactor_has_no_density_or_area_conversion():
+    """``K`` contains only ``r_e``, wavelength and surface-cell area."""
+    expected = (
+        ii.CLASSICAL_ELECTRON_RADIUS**2
+        * (WAVELENGTH * 1e-10) ** 2
+        / (UC_AREA * 1e-20) ** 2
+    )
+
+    got = ii.total_flux_prefactor(WAVELENGTH, UC_AREA)
+
+    np.testing.assert_allclose(got, expected, rtol=1e-12)
+
+
+@pytest.mark.parametrize(
+    ("wavelength", "unitcell_area", "message"),
+    [
+        (np.nan, UC_AREA, "wavelength"),
+        (WAVELENGTH, np.inf, "unitcell_area"),
+    ],
+)
+def test_total_flux_prefactor_rejects_nonfinite_scale_inputs(
+    wavelength, unitcell_area, message
+):
+    with pytest.raises(ValueError, match=message):
+        ii.total_flux_prefactor(wavelength, unitcell_area)
+
+
+def test_total_flux_photon_yield_round_trips_for_every_mode():
+    """The calibrated-photon reduction is invertible for all scan modes."""
+    f2 = np.array([273.6, 148.3, 108.2, 98.0, 865.9, 5000.0])
+    common = dict(
+        wavelength=WAVELENGTH,
+        unitcell_area=UC_AREA,
+        detector_efficiency=0.93,
+    )
+
+    for kwargs in (
+        dict(
+            mode=ii.ROCKING,
+            alpha=ALPHA,
+            delta=DELTA,
+            gamma=GAMMA,
+            detector_acceptance=DGAMMA,
+        ),
+        dict(mode=ii.STATIONARY, gamma=GAMMA),
+        dict(mode=ii.SPECULAR, alpha=GAMMA),
+    ):
+        photon_yield = ii.photon_yield_from_structure_factor(
+            f2, **kwargs, **common
+        )
+        back = ii.structure_factor_squared_from_photon_yield(
+            photon_yield, **kwargs, **common
+        )
+        np.testing.assert_allclose(back, f2, rtol=1e-12)
+
+
+def test_total_flux_reduction_rejects_missing_scale_or_bad_efficiency():
+    with pytest.raises(ValueError, match="set the scale"):
+        ii.structure_factor_squared_from_photon_yield(
+            1.0, ii.STATIONARY, gamma=GAMMA
+        )
+    with pytest.raises(ValueError, match="detector_efficiency"):
+        ii.structure_factor_squared_from_photon_yield(
+            1.0,
+            ii.STATIONARY,
+            gamma=GAMMA,
+            wavelength=WAVELENGTH,
+            unitcell_area=UC_AREA,
+            detector_efficiency=0.0,
+        )
+
+
 def test_structure_factor_round_trips_through_the_forward_model():
     """The reduction is the exact inverse of the forward model, per mode."""
     f2 = np.array([273.6, 148.3, 108.2, 98.0, 865.9, 5000.0])
diff --git a/orgui/datautils/xrayutils/test/test_corrections_normalization.py b/orgui/datautils/xrayutils/test/test_corrections_normalization.py
new file mode 100644
index 0000000..a117760
--- /dev/null
+++ b/orgui/datautils/xrayutils/test/test_corrections_normalization.py
@@ -0,0 +1,133 @@
+"""Tests for calibrated and relative per-frame incident fluence."""
+
+import numpy as np
+import pytest
+
+from orgui.datautils.xrayutils.corrections import normalization
+
+
+def test_constant_total_flux_uses_each_frame_exposure():
+    exposure = np.array([0.1, 0.25, 0.8])
+
+    fluence = normalization.frame_fluence(4.0e11, exposure_time=exposure)
+
+    np.testing.assert_allclose(fluence, 4.0e11 * exposure)
+
+
+def test_rate_and_integrated_monitors_give_the_same_photons():
+    """An integrated reading contains exposure; a rate reading does not."""
+    reference_flux = 5.0e11
+    reference_rate = 2.0e6
+    reference_exposure = 0.4
+    exposure = np.array([0.1, 0.35, 1.2])
+    flux = np.array([4.0e11, 6.0e11, 2.5e11])
+    rate = reference_rate * flux / reference_flux
+    integrated = rate * exposure
+
+    from_rate = normalization.frame_fluence(
+        reference_flux,
+        exposure_time=exposure,
+        monitor=rate,
+        monitor_kind="rate",
+        reference_monitor=reference_rate,
+    )
+    from_integrated = normalization.frame_fluence(
+        reference_flux,
+        exposure_time=exposure,
+        monitor=integrated,
+        monitor_kind="integrated",
+        reference_monitor=reference_rate * reference_exposure,
+        reference_exposure=reference_exposure,
+    )
+
+    expected = flux * exposure
+    np.testing.assert_allclose(from_rate, expected, rtol=1e-14)
+    np.testing.assert_allclose(from_integrated, expected, rtol=1e-14)
+
+
+def test_integrated_monitor_does_not_apply_frame_exposure_twice():
+    integrated = np.array([10.0, 20.0, 40.0])
+
+    first = normalization.frame_fluence(
+        1.0e10,
+        exposure_time=np.array([0.1, 0.2, 0.4]),
+        monitor=integrated,
+        monitor_kind="integrated",
+        reference_monitor=20.0,
+        reference_exposure=0.5,
+    )
+    second = normalization.frame_fluence(
+        1.0e10,
+        exposure_time=np.array([7.0, 8.0, 9.0]),
+        monitor=integrated,
+        monitor_kind="integrated",
+        reference_monitor=20.0,
+        reference_exposure=0.5,
+    )
+
+    np.testing.assert_array_equal(first, second)
+
+
+def test_uncalibrated_fluence_preserves_relative_frame_scale():
+    exposure = np.array([0.2, 0.5, 1.0])
+    rate = np.array([4.0, 3.0, 2.0])
+    integrated = rate * exposure
+
+    np.testing.assert_allclose(
+        normalization.relative_frame_fluence(
+            exposure, monitor=rate, monitor_kind="rate"
+        ),
+        exposure * rate,
+    )
+    np.testing.assert_allclose(
+        normalization.relative_frame_fluence(
+            exposure, monitor=integrated, monitor_kind="integrated"
+        ),
+        integrated,
+    )
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "message"),
+    [
+        ({"total_flux": 0.0, "exposure_time": 1.0}, "total_flux"),
+        ({"total_flux": 1.0}, "exposure_time"),
+        (
+            {"total_flux": 1.0, "exposure_time": 1.0, "monitor": 2.0},
+            "monitor_kind",
+        ),
+        (
+            {
+                "total_flux": 1.0,
+                "exposure_time": 1.0,
+                "monitor": 2.0,
+                "monitor_kind": "rate",
+            },
+            "reference_monitor",
+        ),
+        (
+            {
+                "total_flux": 1.0,
+                "monitor": 2.0,
+                "monitor_kind": "integrated",
+                "reference_monitor": 2.0,
+            },
+            "reference_exposure",
+        ),
+        (
+            {
+                "total_flux": 1.0,
+                "monitor": -2.0,
+                "monitor_kind": "integrated",
+                "reference_monitor": 2.0,
+                "reference_exposure": 1.0,
+            },
+            "monitor must be finite and positive",
+        ),
+    ],
+)
+def test_calibrated_fluence_rejects_missing_or_nonphysical_inputs(
+    kwargs, message
+):
+    with pytest.raises(ValueError, match=message):
+        normalization.frame_fluence(**kwargs)

From 98e872e0c86a176185bdf0e7fe900044c457e09d Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 16 Sep 2026 21:01:24 -0400
Subject: [PATCH 24/33] fix(phys): isolate CTR photon correction branch

---
 CHANGELOG.md                                  |  36 +-
 doc/source/image_integration.rst              |  34 +-
 doc/source/release_notes.rst                  |   4 +-
 orgui/app/integration_corrections.py          |  46 ++
 orgui/app/orGUI.py                            | 451 +++++++++++++-----
 orgui/app/peak1Dintegr.py                     |  93 +++-
 .../app/test/test_integration_corrections.py  |  43 ++
 orgui/app/test/test_orGUI_reflections.py      |  46 +-
 orgui/app/test/test_peak1Dintegr.py           |  85 ++++
 orgui/app/test/test_scan_mode_equivalence.py  |  32 +-
 10 files changed, 713 insertions(+), 157 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ccac15..9b3ab29 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -101,20 +101,31 @@ Scientific and analysis additions:
   0.3 m, varying across the detector and therefore a rod shape error). The
   switch stays, because that correction is the right one for a broad or
   diffuse feature where a differential cross section is wanted: it still
-  scales the intensity counters, and is now measured over the same regions of
-  interest and divided back out when ``F2_hkl`` is formed, so a structure
-  factor is the same number whether or not it was enabled. Its tooltip and the
+  scales the intensity counters, while a direct polarization-only photon
+  branch forms ``F2_hkl``, so a structure factor is the same number whether or
+  not it was enabled. Its tooltip and the
   ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps
   applying it uncompensated, since that path does form a differential cross
   section per pixel. For rocking scans the correction is applied when the
-  curves are extracted, so whether to remove it again is read from the
-  configuration stored with the scan; an older database where that cannot be
-  established warns and is left uncompensated. Integrated rocking scans now
-  store a
+  curves are extracted. New extractions now derive a second CTR photon curve
+  from the same background-subtracted signal using only the polarization
+  correction, including its detector-arm adjustment; ``croibg`` retains the
+  combined solid-angle and polarization correction as the diagnostic
+  intensity. This direct branch removes the covariance error from dividing a
+  combined correction mean by a separately estimated solid-angle mean. Older
+  databases without the photon curve retain the configuration-driven scalar
+  fallback and warn if its correction state cannot be established. A partly
+  masked center ROI now also warns that nominal-area scaling preserves a flat
+  density but cannot physically reconstruct peak intensity hidden by a mask
+  or detector gap. Integrated rocking scans store a
   ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit,
   which normalizations were applied, the acceptance used, whether the
-  solid-angle correction was compensated, and the active-area assumption, so
-  that a saved rod can be placed on a common scale afterwards.
+  direct photon curve or legacy solid-angle compensation was used, and the
+  active-area assumption, so that a saved rod can be placed on a common scale
+  afterwards. Rocking reductions also average the joint Lorentz and
+  rod-intersection factor with the same angular quadrature as the counts,
+  avoiding a covariance residual from multiplying two separately averaged
+  factors.
   Rocking normalization uses the counters stored with the scan, so it requires
   a backend that declares ``exposure_time`` in ``auxillary_counters``; a
   missing counter is skipped and recorded rather than failing the integration.
@@ -142,9 +153,10 @@ Scientific and analysis additions:
   JSON layout are still read. The Lorentz, footprint and normalization
   switches are recorded alongside the others, and a configuration that predates
   them leaves those controls as the user has them rather than silently
-  switching a correction off. ``C_solid_angle`` is now saved beside
-  ``F2_hkl``, because the structure factor divides it back out and a saved rod
-  cannot otherwise be returned to the intensity scale.
+  switching a correction off. New curve records save the combined and
+  polarization-only region factors separately, which makes the
+  diagnostic-intensity and CTR-photon branches reproducible; legacy reductions
+  continue to read ``C_solid_angle`` where it is available.
 
 - **The corrections dialog now asks for the sample size across the beam.** A
   second size ``W`` sits beside the existing sample size ``L``, in millimeter.
diff --git a/doc/source/image_integration.rst b/doc/source/image_integration.rst
index b86a723..9451837 100644
--- a/doc/source/image_integration.rst
+++ b/doc/source/image_integration.rst
@@ -215,23 +215,32 @@ diffuse feature**, where a differential cross section rather than an
 integrated rod intensity is what is wanted. What it does is scoped:
 
 * it scales the **intensity** counters, as before;
-* it is measured over the same regions of interest and **divided back out**
-  when ``F2_hkl`` is formed, so a structure factor is the same number whether
-  or not the switch was on;
+* a new extraction builds a **separate CTR photon curve** from the same
+  background-subtracted signal using the polarization correction but not the
+  solid-angle correction. ``F2_hkl`` uses that direct curve, so it is the same
+  number whether or not the switch was on, without dividing one independently
+  estimated region mean by another;
 * the **reciprocal-space reconstruction** keeps applying it and does not
   divide it out, since that path forms a differential cross section per pixel.
 
-For a rocking scan the correction is applied when the curves are extracted, so
-whether to remove it again is read from the configuration stored with the
-scan rather than from the current state of the switch. If that cannot be
-established -- an older database -- the integration warns and leaves it in
+For a rocking scan both curves are saved when the images are extracted. An
+older database has no direct photon curve, so its reduction retains the scalar
+solid-angle fallback read from the configuration stored with the scan. If the
+old correction state cannot be established, integration warns and leaves it in
 rather than guessing.
 
+The Lorentz and rod-intersection terms can both vary through a rocking window.
+They are therefore multiplied point by point and averaged with the same
+trapezoidal angular quadrature as the counts, rather than multiplying two
+separately averaged factors. This remains the explicit region-mean
+approximation used by extraction; it does not claim a signal-weighted
+per-pixel correction.
+
 Each integrated rocking scan stores a ``reduction`` group beside ``F2_hkl``
 recording the mode, the angle unit, which normalizations were applied, the
-acceptance that was divided out, whether the solid-angle correction was
-compensated and the active-area assumption, so that a saved rod can be placed
-on a common scale after the fact.
+acceptance that was divided out, whether the direct photon curve or legacy
+solid-angle compensation was used, and the active-area assumption, so that a
+saved rod can be placed on a common scale after the fact.
 
 What is still **not** on this scale is the absolute one: ``F2_hkl`` is
 proportional to :math:`|F_{hkl}|^2` with one common, arbitrary constant.
@@ -414,6 +423,11 @@ from center ROI sums, background ROI sums, background-image counters, fitted
 background samples, and correction counters unless pixel repair explicitly
 repairs a tiny signal-ROI defect as described below.
 
+When only some center-ROI pixels remain valid, orGUI retains the established
+nominal-area/valid-pixel scaling and emits a warning. That scaling preserves a
+flat intensity density; it is not a physical reconstruction of peak intensity
+hidden by a detector gap or mask.
+
 .. _pixel-repair-algorithm:
 
 Pixel Repair Algorithm
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 19d6701..44107da 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -17,9 +17,9 @@ Scientific and analysis additions:
 
 - **The arm-following polarization correction no longer makes a mu-scan rocking reduction unusably slow.** It evaluates once and broadcasts when the incidence angle and the arm are constant across a curve, which covers every fixed-arm scan and every th-scan rocking curve; a mu scan rocks the incidence angle itself, and a reflectivity rocking curve additionally tracks the arm at twice it, so nothing was constant and it fell back to a Python loop calling the per-frame correction once per point -- about 20 seconds for a thousand-point mu scan, a minute or more for several thousand, with no error, just a reduction that looked stuck. It is now one batched call per rocking curve instead of one per frame (``corrections.detector.polarization_arm_correction_frames``, backed by ``DetectorCalibration.Detector2D_SXRD._tthAzimuthAtArms``), verified against the per-frame loop to floating-point precision and measured about 7-8x faster end to end. A stationary integration tracking a rod across the detector has no single region to batch on and keeps the per-frame loop, unchanged. **No saved value changes** -- this is the same correction, computed the same way, just not one frame at a time.
 
-- **Rocking and stationary integration now produce the same structure factor.** *This changes saved numbers in both modes.* A rocking scan and a stationary scan of the same rod previously differed by exactly exposure time times monitor times the out-of-plane acceptance in degrees; they now agree. Four corrections changed. The rocking path gained the per-frame exposure and monitor normalization, applied inside the rocking integral so that a varying counting time or a drifting monitor is handled correctly rather than only on average; it now integrates the rocking angle in radian as the published expressions require, rather than in degrees; and it divides by the out-of-plane acceptance of its region of interest, without which a rod measured with regions resized along the scan came out with a distorted *shape* -- a factor 2.3 across a simulated Pt(111) rod -- and not merely a wrong scale. Separately, the detector **solid-angle correction no longer reaches a structure factor** in either mode: summing a region of interest already yields the complete angular integral, with every pixel weighted by the solid angle it subtends, so dividing by that solid angle again double-counted the detector obliquity (0.7 % for a detector at 1 m, 7 % at 0.3 m, varying across the detector and therefore a rod shape error). The switch stays, because that correction is the right one for a broad or diffuse feature where a differential cross section is wanted: it still scales the intensity counters, and is now measured over the same regions of interest and divided back out when ``F2_hkl`` is formed, so a structure factor is the same number whether or not it was enabled. Its tooltip and the ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps applying it uncompensated, since that path does form a differential cross section per pixel. For rocking scans the correction is applied when the curves are extracted, so whether to remove it again is read from the configuration stored with the scan; an older database where that cannot be established warns and is left uncompensated. Integrated rocking scans now store a ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit, which normalizations were applied, the acceptance used, whether the solid-angle correction was compensated, and the active-area assumption, so that a saved rod can be placed on a common scale afterwards. Rocking normalization uses the counters stored with the scan, so it requires a backend that declares ``exposure_time`` in ``auxillary_counters``; a missing counter is skipped and recorded rather than failing the integration. Existing configuration files load unchanged. This equivalence has now been checked on real data as well as in simulation: on a LaNiO3 rod measured both ways, the two modes agree to a median 1.03 along the rod, with the remaining spread explained by the resolution difference between them rather than by a normalization. At a Bragg peak on the same rod they differ by a factor of five, which is expected — a stationary region cannot collect a peak much wider than itself.
+- **Rocking and stationary integration now produce the same structure factor.** *This changes saved numbers in both modes.* A rocking scan and a stationary scan of the same rod previously differed by exactly exposure time times monitor times the out-of-plane acceptance in degrees; they now agree. Four corrections changed. The rocking path gained the per-frame exposure and monitor normalization, applied inside the rocking integral so that a varying counting time or a drifting monitor is handled correctly rather than only on average; it now integrates the rocking angle in radian as the published expressions require, rather than in degrees; and it divides by the out-of-plane acceptance of its region of interest, without which a rod measured with regions resized along the scan came out with a distorted *shape* -- a factor 2.3 across a simulated Pt(111) rod -- and not merely a wrong scale. Separately, the detector **solid-angle correction no longer reaches a structure factor** in either mode: summing a region of interest already yields the complete angular integral, with every pixel weighted by the solid angle it subtends, so dividing by that solid angle again double-counted the detector obliquity (0.7 % for a detector at 1 m, 7 % at 0.3 m, varying across the detector and therefore a rod shape error). The switch stays, because that correction is the right one for a broad or diffuse feature where a differential cross section is wanted: it still scales the intensity counters, while a direct polarization-only photon branch forms ``F2_hkl``, so a structure factor is the same number whether or not it was enabled. Its tooltip and the ``SOLA`` status badge say so. The reciprocal-space reconstruction keeps applying it uncompensated, since that path does form a differential cross section per pixel. For rocking scans the correction is applied when the curves are extracted. New extractions now derive a second CTR photon curve from the same background-subtracted signal using only the polarization correction, including its detector-arm adjustment; ``croibg`` retains the combined solid-angle and polarization correction as the diagnostic intensity. This direct branch removes the covariance error from dividing a combined correction mean by a separately estimated solid-angle mean. Older databases without the photon curve retain the configuration-driven scalar fallback and warn if its correction state cannot be established. A partly masked center ROI now also warns that nominal-area scaling preserves a flat density but cannot physically reconstruct peak intensity hidden by a mask or detector gap. Integrated rocking scans store a ``reduction`` group beside ``F2_hkl`` recording the mode, the angle unit, which normalizations were applied, the acceptance used, whether the direct photon curve or legacy solid-angle compensation was used, and the active-area assumption, so that a saved rod can be placed on a common scale afterwards. Rocking reductions also average the joint Lorentz and rod-intersection factor with the same angular quadrature as the counts, avoiding a covariance residual from multiplying two separately averaged factors. Rocking normalization uses the counters stored with the scan, so it requires a backend that declares ``exposure_time`` in ``auxillary_counters``; a missing counter is skipped and recorded rather than failing the integration. Existing configuration files load unchanged. This equivalence has now been checked on real data as well as in simulation: on a LaNiO3 rod measured both ways, the two modes agree to a median 1.03 along the rod, with the remaining spread explained by the resolution difference between them rather than by a normalization. At a Bragg peak on the same rod they differ by a factor of five, which is expected — a stationary region cannot collect a peak much wider than itself.
 
-- **The settings that decide what was integrated are now stored with every integration.** A reduction could previously not be reproduced from its own output: the background ROI margins, the automatic-sizing switches, the projected sample size, and the effective ``delta_s`` of a rocking scan were not written anywhere. They are now saved under ``configuration/orgui/roi_integration`` as typed groups carrying their units — ``region`` (sizes, margins, automatic sizing), ``advanced`` (sample size in meter, offsets, the inclination and projection switches) and ``rocking_scan`` (``delta_s`` and ``max_s``, with ``delta_s`` stored as the value actually used after the resolution clipping, not as typed). The correction switches move the same way: ``integration_corrections`` is now a group of typed datasets instead of one opaque JSON string, so a stored configuration can be read in any HDF5 browser. Databases written with the JSON layout are still read. The Lorentz, footprint and normalization switches are recorded alongside the others, and a configuration that predates them leaves those controls as the user has them rather than silently switching a correction off. ``C_solid_angle`` is now saved beside ``F2_hkl``, because the structure factor divides it back out and a saved rod cannot otherwise be returned to the intensity scale.
+- **The settings that decide what was integrated are now stored with every integration.** A reduction could previously not be reproduced from its own output: the background ROI margins, the automatic-sizing switches, the projected sample size, and the effective ``delta_s`` of a rocking scan were not written anywhere. They are now saved under ``configuration/orgui/roi_integration`` as typed groups carrying their units — ``region`` (sizes, margins, automatic sizing), ``advanced`` (sample size in meter, offsets, the inclination and projection switches) and ``rocking_scan`` (``delta_s`` and ``max_s``, with ``delta_s`` stored as the value actually used after the resolution clipping, not as typed). The correction switches move the same way: ``integration_corrections`` is now a group of typed datasets instead of one opaque JSON string, so a stored configuration can be read in any HDF5 browser. Databases written with the JSON layout are still read. The Lorentz, footprint and normalization switches are recorded alongside the others, and a configuration that predates them leaves those controls as the user has them rather than silently switching a correction off. New curve records save the combined and polarization-only region factors separately, which makes the diagnostic-intensity and CTR-photon branches reproducible; legacy reductions continue to read ``C_solid_angle`` where it is available.
 
 - **The corrections dialog now asks for the sample size across the beam.** A second size ``W`` sits beside the existing sample size ``L``, in millimeter. It is the sample extent perpendicular to the beam in the surface plane, and it is taken to be the width of the illuminated area, on the assumption that the beam is at least as wide as the sample -- so the sample bounds the lit area rather than the beam. Nothing in a *relative* structure factor uses it: the active-area correction that is applied to an integrated intensity is ``illuminated_area_fraction``, which is dimensionless and unchanged, so no saved number moves. ``W`` supplies the missing input for the *absolute* active area in square meter, ``IntegrationCorrectionsDialog.activeArea``, which an absolutely scaled structure factor needs. The measurement is assumed throughout to be made with open post-sample slits and an area detector, which is what makes the footprint the active area; the slit-limited case, where ``1/(sin(delta) cos(alpha - beta_in))`` would apply instead, is not supported. Both size controls now say so in their tooltips.
 
diff --git a/orgui/app/integration_corrections.py b/orgui/app/integration_corrections.py
index ec68ec5..1d26d2e 100644
--- a/orgui/app/integration_corrections.py
+++ b/orgui/app/integration_corrections.py
@@ -71,12 +71,58 @@
     "apply_stationary_corrections",
     "monitor_counter_candidates",
     "normalization_divisor",
+    "pixel_correction_branches",
     "roi_mean_correction",
     "stationary_correction_factors",
     "structure_factor",
 ]
 
 
+def pixel_correction_branches(
+    base_intensity,
+    base_errors,
+    combined_factor,
+    polarization_factor,
+    polarization_arm_factor=1.0,
+):
+    r"""Build diagnostic and CTR branches from one scalar ROI signal.
+
+    The diagnostic intensity retains the established combined per-pixel
+    correction (solid angle times polarization). The CTR photon branch uses
+    the independently accumulated polarization-only mean, so detector solid
+    angle never has to be divided out through a separately estimated scalar.
+    Both branches start from the same background-subtracted signal and apply
+    the actual-arm polarization ratio exactly once.
+
+    This remains the existing ROI-mean approximation: it does not claim that
+    a geometric mean correction equals a signal-weighted per-pixel sum.
+
+    :param base_intensity: Background-subtracted ROI signal before pixel
+        corrections.
+    :param base_errors: One-sigma errors paired with ``base_intensity``.
+    :param combined_factor: Mean combined pixel correction over the valid
+        center-ROI pixels.
+    :param polarization_factor: Mean inverse-polarization correction over the
+        same valid center-ROI pixels; one when polarization is disabled.
+    :param polarization_arm_factor: Ratio moving the home-geometry
+        polarization mean to the actual arm position; one when polarization
+        is disabled.
+    :returns: ``(intensity, errors, ctr_intensity, ctr_errors)``.
+    :rtype: tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]
+    """
+    base_intensity = np.asarray(base_intensity, dtype=np.float64)
+    base_errors = np.asarray(base_errors, dtype=np.float64)
+    arm = np.asarray(polarization_arm_factor, dtype=np.float64)
+    combined_scale = np.asarray(combined_factor, dtype=np.float64) * arm
+    polarization_scale = np.asarray(polarization_factor, dtype=np.float64) * arm
+    return (
+        base_intensity * combined_scale,
+        base_errors * combined_scale,
+        base_intensity * polarization_scale,
+        base_errors * polarization_scale,
+    )
+
+
 def monitor_counter_candidates(scan):
     """Counter names of ``scan`` usable as a monitor normalization.
 
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index 6d31bd9..754c4cc 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -157,6 +157,49 @@ def _rocking_arm_snapshot(gamma_arm, delta_arm, curve_shape):
     }
 
 
+def _correction_region_counters(correction, mask, center, backgrounds):
+    """Sum one correction array over the exact valid ROI pixels.
+
+    ``center`` and every entry of ``backgrounds`` use orGUI's ``(x, y)``
+    slice order. The returned four counters match the accelerated ROI-sum
+    contract: center sum/count and combined-background sum/count.
+    """
+    correction = np.asarray(correction, dtype=np.float64)
+    valid = ~np.asarray(mask, dtype=bool)
+
+    def region_values(region):
+        values = correction[region[::-1]]
+        region_valid = valid[region[::-1]] & np.isfinite(values)
+        return float(np.sum(values[region_valid])), float(np.sum(region_valid))
+
+    center_sum, center_pixels = region_values(center)
+    background_sum = 0.0
+    background_pixels = 0.0
+    for region in backgrounds:
+        summed, pixels = region_values(region)
+        background_sum += summed
+        background_pixels += pixels
+    return np.array(
+        [center_sum, center_pixels, background_sum, background_pixels],
+        dtype=np.float64,
+    )
+
+
+def _warn_masked_peak_scaling(valid_pixels, nominal_pixels, context):
+    """Warn once that nominal-area scaling cannot reconstruct masked peaks."""
+    valid_pixels = np.asarray(valid_pixels, dtype=np.float64)
+    nominal_pixels = np.asarray(nominal_pixels, dtype=np.float64)
+    incomplete = (nominal_pixels > 0) & (valid_pixels < nominal_pixels)
+    if np.any(incomplete):
+        logger.warning(
+            "%s contains masked or missing center-ROI pixels. Scaling by "
+            "nominal ROI area divided by valid-pixel count preserves a flat "
+            "density, but it is not a physical recovery of peak intensity "
+            "hidden by detector gaps or masks.",
+            context,
+        )
+
+
 def _curve_profile_provenance(state):
     """Flat, self-contained beam-profile provenance for a curve record."""
     result = {
@@ -1647,9 +1690,13 @@ def rocking_integrate(self, xylist, rois, hkl_del_gam, refldict, name):
                         }
                 logger.warn("No mask was selected with the masking tool.")
 
-        corr = (
-            self.scanSelector.useSolidAngleBox.isChecked()
-            or self.scanSelector.usePolarizationBox.isChecked()
+        use_solid_angle = self.scanSelector.useSolidAngleBox.isChecked()
+        use_polarization = self.scanSelector.usePolarizationBox.isChecked()
+        corr = use_solid_angle or use_polarization
+        mask = (
+            np.ascontiguousarray(imgmask, dtype=bool)
+            if imgmask is not None
+            else np.zeros(image.img.shape, dtype=bool)
         )
 
         # One definition of the per-pixel factors, shared with the rocking
@@ -1660,11 +1707,16 @@ def rocking_integrate(self, xylist, rois, hkl_del_gam, refldict, name):
         # NumPy-only path would otherwise be handed None.
         C_arr = detector_corrections.pixel_factors(
             dc,
-            solid_angle=self.scanSelector.useSolidAngleBox.isChecked(),
-            polarization=self.scanSelector.usePolarizationBox.isChecked(),
+            solid_angle=use_solid_angle,
+            polarization=use_polarization,
         )
         if C_arr is None:
             C_arr = np.ones(dc.detector.shape, dtype=np.float64)
+        P_arr = detector_corrections.pixel_factors(
+            dc, polarization=use_polarization
+        )
+        if P_arr is None:
+            P_arr = np.ones(dc.detector.shape, dtype=np.float64)
 
         def fill_counters(image, pixelavail, key, bkgkey):
             """CLI-safe: sum one center ROI and its background ROIs."""
@@ -1752,6 +1804,8 @@ def fill_counters(image, pixelavail, key, bkgkey):
                 "the polynomial fit's covariance.",
                 fitted_background_order,
             )
+        repair_enabled = False
+        roi_lists_accel = None
         if HAS_ACCEL:
             repair_enabled, repair, row_gaps, col_gaps = self._repair_config_for_image(
                 image.img.shape
@@ -1762,10 +1816,6 @@ def fill_counters(image, pixelavail, key, bkgkey):
                     "using the original mask for this integration."
                 )
                 repair_enabled = False
-            if imgmask is not None:
-                mask = np.ascontiguousarray(imgmask, dtype=bool)
-            else:
-                mask = np.zeros(image.img.shape, dtype=bool)
             if corr:
                 C_arr = np.ascontiguousarray(C_arr, dtype=np.float64)
             else:
@@ -2030,6 +2080,61 @@ def sumImage(i):
                     "message": "Reason: Cancelled during integration",
                 }
 
+        # Accumulate polarization independently of the combined pixel factor.
+        # This uses the same center/background regions and valid-pixel policy
+        # as the raw ROI counters, including repaired center pixels when that
+        # path is active. The result is geometry-only and therefore needs to
+        # be calculated once for all frames of a rocking extraction.
+        polarization_counters = np.zeros((xylist.shape[0], 4), dtype=np.float64)
+        if use_polarization and HAS_ACCEL and repair_enabled:
+            dummy_counters = np.zeros_like(polarization_counters)
+            _roi_sum_accel.processImage_repair_Carr(
+                np.ones(image.img.shape, dtype=np.float64),
+                mask,
+                np.ascontiguousarray(P_arr, dtype=np.float64),
+                *roi_lists_accel,
+                row_gaps,
+                col_gaps,
+                dummy_counters,
+                polarization_counters,
+                repair.max_component_pixels,
+                repair.max_span,
+                repair.radius,
+                repair.min_valid_neighbors,
+            )
+        else:
+            for crnr in range(xylist.shape[0]):
+                polarization_counters[crnr] = _correction_region_counters(
+                    P_arr,
+                    mask,
+                    rois["center"][crnr],
+                    [
+                        rois["left"][crnr],
+                        rois["right"][crnr],
+                        rois["top"][crnr],
+                        rois["bottom"][crnr],
+                    ],
+                )
+        P_croi = integration_corrections.roi_mean_correction(
+            polarization_counters[:, 0], polarization_counters[:, 1]
+        )
+        P_bgroi = integration_corrections.roi_mean_correction(
+            polarization_counters[:, 2], polarization_counters[:, 3]
+        )
+        nominal_rocking_pixels = np.asarray(
+            [
+                (region[0].stop - region[0].start)
+                * (region[1].stop - region[1].start)
+                for region in rois["center"]
+            ],
+            dtype=np.float64,
+        )
+        _warn_masked_peak_scaling(
+            cpixel1_all,
+            np.broadcast_to(nominal_rocking_pixels, cpixel1_all.shape),
+            "Rocking extraction",
+        )
+
         currentPlotCount = len(self.integrdataPlot.getAllCurves())
         numberOfNewPlots = xylist.shape[0]
         maxAmountOfPlots = 30
@@ -2191,14 +2296,10 @@ def sumImage(i):
                     croibg1_a = croi1_a * (roi_size / cpixel1_a)
                     croibg1_err_a = np.sqrt(croi1_a) * (roi_size / cpixel1_a)
 
-            if corr:
-                croibg1_a *= Corr1
-                croibg1_err_a *= Corr1
-                if croibg1_bgimg_a is not None:
-                    croibg1_bgimg_a *= Corr1
-                    croibg1_bgimg_err_a *= Corr1
-
-            if self.scanSelector.usePolarizationBox.isChecked():
+            base_croibg1 = np.asarray(croibg1_a, dtype=np.float64).copy()
+            base_croibg1_err = np.asarray(croibg1_err_a, dtype=np.float64).copy()
+            pol_arm1 = np.ones_like(base_croibg1)
+            if use_polarization:
                 # Corr1 carries the polarization of the calibrated geometry;
                 # move it onto the arm position of each frame (finding F5).
                 # Exactly 1 for a detector whose arm does not move.
@@ -2210,11 +2311,33 @@ def sumImage(i):
                     roi_d[0].stop - roi_d[0].start,
                     mu,
                 )
-                croibg1_a = croibg1_a * pol_arm1
-                croibg1_err_a = croibg1_err_a * pol_arm1
-                if croibg1_bgimg_a is not None:
-                    croibg1_bgimg_a = croibg1_bgimg_a * pol_arm1
-                    croibg1_bgimg_err_a = croibg1_bgimg_err_a * pol_arm1
+
+            (
+                croibg1_a,
+                croibg1_err_a,
+                ctr_croibg1_a,
+                ctr_croibg1_err_a,
+            ) = integration_corrections.pixel_correction_branches(
+                base_croibg1,
+                base_croibg1_err,
+                Corr1,
+                P_croi[d],
+                pol_arm1,
+            )
+            combined_croi_factor = Corr1 * pol_arm1
+            combined_bgroi_factor = (
+                integration_corrections.roi_mean_correction(
+                    Corr_bgroi1_a, Corr_bgpixel1_all[..., d]
+                )
+                * pol_arm1
+            )
+            polarization_croi_factor = P_croi[d] * pol_arm1
+            polarization_bgroi_factor = P_bgroi[d] * pol_arm1
+            if croibg1_bgimg_a is not None:
+                croibg1_bgimg_a = croibg1_bgimg_a * combined_croi_factor
+                croibg1_bgimg_err_a = (
+                    croibg1_bgimg_err_a * combined_croi_factor
+                )
 
             rod_mask1 = np.isfinite(croibg1_a)
 
@@ -2305,6 +2428,8 @@ def sumImage(i):
                     "@NX_class": "NXdetector",
                     "croibg": croibg1_a,
                     "croibg_errors": croibg1_err_a,
+                    "ctr_croibg": ctr_croibg1_a,
+                    "ctr_croibg_errors": ctr_croibg1_err_a,
                     "croibg_bgimg": croibg1_bgimg_a,  # when None, will not create data set  # noqa: E501
                     "croibg_bgimg_errors": croibg1_bgimg_err_a,  # when None, will not create data set  # noqa: E501
                     "croi": croi1_a,
@@ -2313,6 +2438,10 @@ def sumImage(i):
                     "bgroi_pix": bgpixel1_a,
                     "Cfactors_croi": Corr_croi1_a,
                     "Cfactors_bgroi": Corr_bgroi1_a,
+                    "Cfactor_croi": combined_croi_factor,
+                    "Cfactor_bgroi": combined_bgroi_factor,
+                    "Pfactor_croi": polarization_croi_factor,
+                    "Pfactor_bgroi": polarization_bgroi_factor,
                     "bgimg_croi": bgimg_croi1_a,
                     "bgimg_bgroi": bgimg_bgroi1_a,
                 },
@@ -2406,6 +2535,8 @@ def sumImage(i):
         l = []  # noqa: E741
         croibg = []
         croibg_errors = []
+        ctr_croibg = []
+        ctr_croibg_errors = []
         croi = []
         bgroi = []
         croi_pix = []
@@ -2414,6 +2545,10 @@ def sumImage(i):
         croibg_bgimg_errors = []
         Cfactors_croi = []
         Cfactors_bgroi = []
+        Cfactor_croi = []
+        Cfactor_bgroi = []
+        Pfactor_croi = []
+        Pfactor_bgroi = []
         bgimg_croi = []
         bgimg_bgroi = []
         axis = []
@@ -2451,6 +2586,8 @@ def sumImage(i):
                 # 2D arrays
                 croibg.append(dsc["counters"]["croibg"])
                 croibg_errors.append(dsc["counters"]["croibg_errors"])
+                ctr_croibg.append(dsc["counters"]["ctr_croibg"])
+                ctr_croibg_errors.append(dsc["counters"]["ctr_croibg_errors"])
                 croi.append(dsc["counters"]["croi"])
                 bgroi.append(dsc["counters"]["bgroi"])
                 croi_pix.append(dsc["counters"]["croi_pix"])
@@ -2460,6 +2597,10 @@ def sumImage(i):
                     croibg_bgimg_errors.append(dsc["counters"]["croibg_bgimg_errors"])
                 Cfactors_croi.append(dsc["counters"]["Cfactors_croi"])
                 Cfactors_bgroi.append(dsc["counters"]["Cfactors_bgroi"])
+                Cfactor_croi.append(dsc["counters"]["Cfactor_croi"])
+                Cfactor_bgroi.append(dsc["counters"]["Cfactor_bgroi"])
+                Pfactor_croi.append(dsc["counters"]["Pfactor_croi"])
+                Pfactor_bgroi.append(dsc["counters"]["Pfactor_bgroi"])
                 bgimg_croi.append(dsc["counters"]["bgimg_croi"])
                 bgimg_bgroi.append(dsc["counters"]["bgimg_bgroi"])
 
@@ -2509,12 +2650,18 @@ def sumImage(i):
             "l": np.vstack(l),
             "croibg": np.vstack(croibg),
             "croibg_errors": np.vstack(croibg_errors),
+            "ctr_croibg": np.vstack(ctr_croibg),
+            "ctr_croibg_errors": np.vstack(ctr_croibg_errors),
             "croi": np.vstack(croi),
             "bgroi": np.vstack(bgroi),
             "croi_pix": np.vstack(croi_pix),
             "bgroi_pix": np.vstack(bgroi_pix),
             "Cfactors_croi": np.vstack(Cfactors_croi),
             "Cfactors_bgroi": np.vstack(Cfactors_bgroi),
+            "Cfactor_croi": np.vstack(Cfactor_croi),
+            "Cfactor_bgroi": np.vstack(Cfactor_bgroi),
+            "Pfactor_croi": np.vstack(Pfactor_croi),
+            "Pfactor_bgroi": np.vstack(Pfactor_bgroi),
             "bgimg_croi": np.vstack(bgimg_croi),
             "bgimg_bgroi": np.vstack(bgimg_bgroi),
             "x": np.array(x),
@@ -2568,7 +2715,7 @@ def sumImage(i):
         # contract consumed by today's reducer. Stage 5 will opt into this
         # branch when framewise Q/H normalization becomes active.
         curve_record = CurveCorrectionRecord(
-            algorithm="legacy_rocking_roi_v1",
+            algorithm="legacy_rocking_roi_v2",
             output_quantity="rocking_roi_curve",
             scale_convention="legacy_unnormalized",
             normalization_status="not_applied",
@@ -2579,10 +2726,12 @@ def sumImage(i):
             base_croi_variance=rois["croi"],
             base_bgroi=rois["bgroi"],
             base_bgroi_variance=rois["bgroi"],
-            base_croibg=rois["croibg"],
-            base_croibg_variance=np.square(rois["croibg_errors"]),
-            combined_croi_factor=rois["Cfactors_croi"],
-            combined_bgroi_factor=rois["Cfactors_bgroi"],
+            base_croibg=rois["ctr_croibg"],
+            base_croibg_variance=np.square(rois["ctr_croibg_errors"]),
+            combined_croi_factor=rois["Cfactor_croi"],
+            combined_bgroi_factor=rois["Cfactor_bgroi"],
+            polarization_croi_factor=rois["Pfactor_croi"],
+            polarization_bgroi_factor=rois["Pfactor_bgroi"],
             gamma_arm=rois["gamma_arm"],
             delta_arm=rois["delta_arm"],
             roi_x=rois["x"],
@@ -5980,10 +6129,9 @@ def integrateROI(self):
                     "No mask was selected with the masking tool. Continue without mask."
                 )
 
-        corr = (
-            self.scanSelector.useSolidAngleBox.isChecked()
-            or self.scanSelector.usePolarizationBox.isChecked()
-        )
+        use_solid_angle = self.scanSelector.useSolidAngleBox.isChecked()
+        use_polarization = self.scanSelector.usePolarizationBox.isChecked()
+        corr = use_solid_angle or use_polarization
 
         # One definition of the per-pixel factors, shared with the rocking
         # integration and the reciprocal-space reconstruction. It returns None
@@ -5993,11 +6141,16 @@ def integrateROI(self):
         # NumPy-only path would otherwise be handed None.
         C_arr = detector_corrections.pixel_factors(
             dc,
-            solid_angle=self.scanSelector.useSolidAngleBox.isChecked(),
-            polarization=self.scanSelector.usePolarizationBox.isChecked(),
+            solid_angle=use_solid_angle,
+            polarization=use_polarization,
         )
         if C_arr is None:
             C_arr = np.ones(dc.detector.shape, dtype=np.float64)
+        P_arr = detector_corrections.pixel_factors(
+            dc, polarization=use_polarization
+        )
+        if P_arr is None:
+            P_arr = np.ones(dc.detector.shape, dtype=np.float64)
 
         hkl_del_gam_s1, hkl_del_gam_s2 = self.getROIloc()
 
@@ -6479,6 +6632,69 @@ def sumImage(i):
         roi_size1 = roi_hsize1_a * roi_vsize1_a
         roi_size2 = roi_hsize2_a * roi_vsize2_a
 
+        # Polarization-only factors must be accumulated over the same valid
+        # pixels as the combined correction. This creates the direct CTR
+        # photon branch and avoids estimating it later as mean(S*P)/mean(S).
+        polarization_counters = np.zeros((nodatapoints, 2, 4), dtype=np.float64)
+        if use_polarization and HAS_ACCEL and repair_enabled:
+            for i in range(nodatapoints):
+                if not dataavail[i]:
+                    continue
+                dummy_counters = np.zeros((2, 4), dtype=np.float64)
+                _roi_sum_accel.processImage_repair_Carr(
+                    np.ones(image.img.shape, dtype=np.float64),
+                    mask,
+                    np.ascontiguousarray(P_arr, dtype=np.float64),
+                    *roi_lists_accel[i],
+                    row_gaps,
+                    col_gaps,
+                    dummy_counters,
+                    polarization_counters[i],
+                    repair.max_component_pixels,
+                    repair.max_span,
+                    repair.radius,
+                    repair.min_valid_neighbors,
+                )
+        else:
+            for i in range(nodatapoints):
+                for intersect, hkl_del_gam_current in enumerate(
+                    (hkl_del_gam_1, hkl_del_gam_2)
+                ):
+                    if not hkl_del_gam_current[i, -1]:
+                        continue
+                    coordinates = hkl_del_gam_current[i, 6:8]
+                    polarization_counters[i, intersect] = (
+                        _correction_region_counters(
+                            P_arr,
+                            mask,
+                            self.intkey(coordinates),
+                            self.bkgkeys(coordinates),
+                        )
+                    )
+
+        P_croi1 = integration_corrections.roi_mean_correction(
+            polarization_counters[:, 0, 0], polarization_counters[:, 0, 1]
+        )
+        P_bgroi1 = integration_corrections.roi_mean_correction(
+            polarization_counters[:, 0, 2], polarization_counters[:, 0, 3]
+        )
+        P_croi2 = integration_corrections.roi_mean_correction(
+            polarization_counters[:, 1, 0], polarization_counters[:, 1, 1]
+        )
+        P_bgroi2 = integration_corrections.roi_mean_correction(
+            polarization_counters[:, 1, 2], polarization_counters[:, 1, 3]
+        )
+        _warn_masked_peak_scaling(
+            cpixel1_a,
+            np.where(hkl_del_gam_1[:, -1], roi_size1, 0),
+            "Stationary S1 extraction",
+        )
+        _warn_masked_peak_scaling(
+            cpixel2_a,
+            np.where(hkl_del_gam_2[:, -1], roi_size2, 0),
+            "Stationary S2 extraction",
+        )
+
         # Mean correction over the valid pixels of the center ROI. The ROI sum
         # of the correction array must not be rescaled to the nominal ROI area
         # here: croibg already carries that (roi_size / cpixel) factor, so
@@ -6583,17 +6799,10 @@ def sumImage(i):
                 croibg2_a = croi2_a * (roi_size2 / cpixel2_a)
                 croibg2_err_a = np.sqrt(croi2_a) * (roi_size2 / cpixel2_a)
 
-        if corr:
-            croibg1_a *= Corr1
-            croibg1_err_a *= Corr1
-            croibg2_a *= Corr2
-            croibg2_err_a *= Corr2
-            if croibg1_bgimg_a is not None:
-                croibg1_bgimg_a *= Corr1
-                croibg1_bgimg_err_a *= Corr1
-            if croibg2_bgimg_a is not None:
-                croibg2_bgimg_a *= Corr2
-                croibg2_bgimg_err_a *= Corr2
+        base_signal1 = np.asarray(croibg1_a, dtype=np.float64).copy()
+        base_error1 = np.asarray(croibg1_err_a, dtype=np.float64).copy()
+        base_signal2 = np.asarray(croibg2_a, dtype=np.float64).copy()
+        base_error2 = np.asarray(croibg2_err_a, dtype=np.float64).copy()
 
         # Geometrical, footprint and normalization corrections. The numerical
         # active area and normalization are intensity divisors. The
@@ -6626,7 +6835,9 @@ def sumImage(i):
                 )
             )
 
-        if options["polarization"]:
+        pol_arm1 = np.ones(nodatapoints, dtype=np.float64)
+        pol_arm2 = np.ones(nodatapoints, dtype=np.float64)
+        if use_polarization:
             # Corr1/Corr2 carry the polarization of the calibrated geometry;
             # move it onto the arm position of each frame (finding F5). This is
             # exactly 1 for a detector whose arm does not move, and it is the
@@ -6635,53 +6846,53 @@ def sumImage(i):
             pol_arm1 = self._polarizationArmFactor(
                 dc, y_coord1_a, x_coord1_a, roi_vsize1_a, roi_hsize1_a, alpha_all
             )
-            croibg1_a = croibg1_a * pol_arm1
-            croibg1_err_a = croibg1_err_a * pol_arm1
-            if croibg1_bgimg_a is not None:
-                croibg1_bgimg_a = croibg1_bgimg_a * pol_arm1
-                croibg1_bgimg_err_a = croibg1_bgimg_err_a * pol_arm1
-
             pol_arm2 = self._polarizationArmFactor(
                 dc, y_coord2_a, x_coord2_a, roi_vsize2_a, roi_hsize2_a, alpha_all
             )
-            croibg2_a = croibg2_a * pol_arm2
-            croibg2_err_a = croibg2_err_a * pol_arm2
-            if croibg2_bgimg_a is not None:
-                croibg2_bgimg_a = croibg2_bgimg_a * pol_arm2
-                croibg2_bgimg_err_a = croibg2_bgimg_err_a * pol_arm2
-
-        # The solid-angle correction is useful on the *intensity* -- for broad,
-        # non-rod features a differential cross-section is what is wanted --
-        # but it must not reach a structure factor: a region sum is already the
-        # complete angular integral, each pixel weighted by the solid angle it
-        # subtends. So it is measured here over the same regions and divided
-        # back out when F2_hkl is formed. Finding F6 of
-        # doc/design/ctr_structure_factor_scale.md; the per-pixel
-        # reconstruction keeps it, because that path does form a differential
-        # cross-section.
-        solid_angle_means = (None, None)
-        if self.scanSelector.useSolidAngleBox.isChecked():
-            solid_angle_means = tuple(
-                detector_corrections.roi_mean_inverse_solid_angle(
-                    dc,
-                    row,
-                    column,
-                    # A frame whose region fell off the detector can leave a
-                    # degenerate size behind; it carries no counts either, so
-                    # one pixel keeps the factor defined and harmless.
-                    np.maximum(row_size, 1),
-                    np.maximum(column_size, 1),
-                )
-                for row, column, row_size, column_size in (
-                    (y_coord1_a, x_coord1_a, roi_vsize1_a, roi_hsize1_a),
-                    (y_coord2_a, x_coord2_a, roi_vsize2_a, roi_hsize2_a),
-                )
+
+        (
+            croibg1_a,
+            croibg1_err_a,
+            ctr_croibg1_a,
+            ctr_croibg1_err_a,
+        ) = integration_corrections.pixel_correction_branches(
+            base_signal1, base_error1, Corr1, P_croi1, pol_arm1
+        )
+        (
+            croibg2_a,
+            croibg2_err_a,
+            ctr_croibg2_a,
+            ctr_croibg2_err_a,
+        ) = integration_corrections.pixel_correction_branches(
+            base_signal2, base_error2, Corr2, P_croi2, pol_arm2
+        )
+        combined_croi_factor1 = Corr1 * pol_arm1
+        combined_croi_factor2 = Corr2 * pol_arm2
+        combined_bgroi_factor1 = (
+            integration_corrections.roi_mean_correction(
+                Corr_bgroi1_a, Corr_bgpixel1_a
+            )
+            * pol_arm1
+        )
+        combined_bgroi_factor2 = (
+            integration_corrections.roi_mean_correction(
+                Corr_bgroi2_a, Corr_bgpixel2_a
             )
+            * pol_arm2
+        )
+        polarization_croi_factor1 = P_croi1 * pol_arm1
+        polarization_croi_factor2 = P_croi2 * pol_arm2
+        polarization_bgroi_factor1 = P_bgroi1 * pol_arm1
+        polarization_bgroi_factor2 = P_bgroi2 * pol_arm2
+        if croibg1_bgimg_a is not None:
+            croibg1_bgimg_a *= combined_croi_factor1
+            croibg1_bgimg_err_a *= combined_croi_factor1
+        if croibg2_bgimg_a is not None:
+            croibg2_bgimg_a *= combined_croi_factor2
+            croibg2_bgimg_err_a *= combined_croi_factor2
 
         correction_factors = []
-        for hkl_del_gam, solid_angle_mean in zip(
-            (hkl_del_gam_1, hkl_del_gam_2), solid_angle_means
-        ):
+        for hkl_del_gam in (hkl_del_gam_1, hkl_del_gam_2):
             correction_factors.append(
                 integration_corrections.stationary_correction_factors(
                     alpha_all,
@@ -6692,7 +6903,6 @@ def sumImage(i):
                     beam_profile=beam_profile,
                     sample_size=sample_size,
                     normalization=normalization,
-                    solid_angle_mean=solid_angle_mean,
                 )
             )
         factors1, factors2 = correction_factors
@@ -6707,17 +6917,16 @@ def sumImage(i):
                 ),
             )
 
-        # Reversible scalar base, after the existing background/pixel path but
-        # before the framewise normalization and illumination divisors. Keep a
-        # copy because apply_stationary_corrections returns the saved legacy
-        # intensity below.
-        base_croibg1 = np.asarray(croibg1_a, dtype=np.float64).copy()
+        # Reversible photon-counting base, after polarization but before the
+        # framewise normalization and illumination divisors. Detector solid
+        # angle remains confined to the diagnostic intensity branch.
+        base_croibg1 = np.asarray(ctr_croibg1_a, dtype=np.float64).copy()
         base_croibg1_variance = np.square(
-            np.asarray(croibg1_err_a, dtype=np.float64)
+            np.asarray(ctr_croibg1_err_a, dtype=np.float64)
         )
-        base_croibg2 = np.asarray(croibg2_a, dtype=np.float64).copy()
+        base_croibg2 = np.asarray(ctr_croibg2_a, dtype=np.float64).copy()
         base_croibg2_variance = np.square(
-            np.asarray(croibg2_err_a, dtype=np.float64)
+            np.asarray(ctr_croibg2_err_a, dtype=np.float64)
         )
 
         croibg1_a, croibg1_err_a = integration_corrections.apply_stationary_corrections(
@@ -6726,6 +6935,16 @@ def sumImage(i):
         croibg2_a, croibg2_err_a = integration_corrections.apply_stationary_corrections(
             croibg2_a, croibg2_err_a, factors2
         )
+        ctr_croibg1_a, ctr_croibg1_err_a = (
+            integration_corrections.apply_stationary_corrections(
+                ctr_croibg1_a, ctr_croibg1_err_a, factors1
+            )
+        )
+        ctr_croibg2_a, ctr_croibg2_err_a = (
+            integration_corrections.apply_stationary_corrections(
+                ctr_croibg2_a, ctr_croibg2_err_a, factors2
+            )
+        )
         if croibg1_bgimg_a is not None:
             croibg1_bgimg_a, croibg1_bgimg_err_a = (
                 integration_corrections.apply_stationary_corrections(
@@ -6742,10 +6961,10 @@ def sumImage(i):
         F2_hkl1 = F2_hkl1_err = F2_hkl2 = F2_hkl2_err = None
         if options["lorentz"]:
             F2_hkl1, F2_hkl1_err = integration_corrections.structure_factor(
-                croibg1_a, croibg1_err_a, factors1
+                ctr_croibg1_a, ctr_croibg1_err_a, factors1
             )
             F2_hkl2, F2_hkl2_err = integration_corrections.structure_factor(
-                croibg2_a, croibg2_err_a, factors2
+                ctr_croibg2_a, ctr_croibg2_err_a, factors2
             )
 
         rod_mask1 = np.isfinite(croibg1_a)
@@ -6868,6 +7087,8 @@ def sumImage(i):
                 "@NX_class": "NXdetector",
                 "croibg": croibg1_a,
                 "croibg_errors": croibg1_err_a,
+                "ctr_croibg": ctr_croibg1_a,
+                "ctr_croibg_errors": ctr_croibg1_err_a,
                 "croibg_bgimg": croibg1_bgimg_a,  # when None, will not create data set
                 "croibg_bgimg_errors": croibg1_bgimg_err_a,  # when None, will not create data set  # noqa: E501
                 "croi": croi1_a,
@@ -6876,6 +7097,10 @@ def sumImage(i):
                 "bgroi_pix": bgpixel1_a,
                 "Cfactors_croi": Corr_croi1_a,
                 "Cfactors_bgroi": Corr_bgroi1_a,
+                "Cfactor_croi": combined_croi_factor1,
+                "Cfactor_bgroi": combined_bgroi_factor1,
+                "Pfactor_croi": polarization_croi_factor1,
+                "Pfactor_bgroi": polarization_bgroi_factor1,
                 "bgimg_croi": bgimg_croi1_a,
                 "bgimg_bgroi": bgimg_bgroi1_a,
                 # None entries do not create a data set, so only the
@@ -6886,10 +7111,6 @@ def sumImage(i):
                 "C_flux_on_sample": factors1.get("C_flux_on_sample"),
                 "C_illum_area": factors1.get("C_illum_area"),
                 "C_norm": factors1.get("C_norm"),
-                # Divided back out of F2_hkl rather than applied to it
-                # (finding F6); recorded so a saved rod can be put
-                # back on the intensity scale.
-                "C_solid_angle": factors1.get("C_solid_angle"),
             },
             "pixelcoord": {
                 "@NX_class": "NXdetector",
@@ -6932,6 +7153,8 @@ def sumImage(i):
                 "@NX_class": "NXdetector",
                 "croibg": croibg2_a,
                 "croibg_errors": croibg2_err_a,
+                "ctr_croibg": ctr_croibg2_a,
+                "ctr_croibg_errors": ctr_croibg2_err_a,
                 "croibg_bgimg": croibg2_bgimg_a,
                 "croibg_bgimg_errors": croibg2_bgimg_err_a,
                 "croi": croi2_a,
@@ -6940,6 +7163,10 @@ def sumImage(i):
                 "bgroi_pix": bgpixel2_a,
                 "Cfactors_croi": Corr_croi2_a,
                 "Cfactors_bgroi": Corr_bgroi2_a,
+                "Cfactor_croi": combined_croi_factor2,
+                "Cfactor_bgroi": combined_bgroi_factor2,
+                "Pfactor_croi": polarization_croi_factor2,
+                "Pfactor_bgroi": polarization_bgroi_factor2,
                 "bgimg_croi": bgimg_croi2_a,
                 "bgimg_bgroi": bgimg_bgroi2_a,
                 # None entries do not create a data set, so only the
@@ -6950,10 +7177,6 @@ def sumImage(i):
                 "C_flux_on_sample": factors2.get("C_flux_on_sample"),
                 "C_illum_area": factors2.get("C_illum_area"),
                 "C_norm": factors2.get("C_norm"),
-                # Divided back out of F2_hkl rather than applied to it
-                # (finding F6); recorded so a saved rod can be put
-                # back on the intensity scale.
-                "C_solid_angle": factors2.get("C_solid_angle"),
             },
             "pixelcoord": {
                 "@NX_class": "NXdetector",
@@ -6995,6 +7218,8 @@ def versioned_stationary_curve(
             bgroi,
             combined_croi,
             combined_bgroi,
+            polarization_croi,
+            polarization_bgroi,
             x,
             y,
             width,
@@ -7006,7 +7231,7 @@ def versioned_stationary_curve(
         ):
             """Build the non-legacy sibling branch for one trajectory."""
             record = CurveCorrectionRecord(
-                algorithm="legacy_stationary_roi_v1",
+                algorithm="legacy_stationary_roi_v2",
                 output_quantity="stationary_roi_intensity",
                 scale_convention=(
                     "legacy_density_area"
@@ -7037,6 +7262,8 @@ def versioned_stationary_curve(
                 base_croibg_variance=base_croibg_variance,
                 combined_croi_factor=combined_croi,
                 combined_bgroi_factor=combined_bgroi,
+                polarization_croi_factor=polarization_croi,
+                polarization_bgroi_factor=polarization_bgroi,
                 gamma_arm=gamma_arm_all,
                 delta_arm=delta_arm_all,
                 roi_x=x,
@@ -7060,8 +7287,10 @@ def versioned_stationary_curve(
             base_croibg1_variance,
             croi1_a,
             bgroi1_a,
-            Corr_croi1_a,
-            Corr_bgroi1_a,
+            combined_croi_factor1,
+            combined_bgroi_factor1,
+            polarization_croi_factor1,
+            polarization_bgroi_factor1,
             x_coord1_a,
             y_coord1_a,
             roi_hsize1_a,
@@ -7077,8 +7306,10 @@ def versioned_stationary_curve(
             base_croibg2_variance,
             croi2_a,
             bgroi2_a,
-            Corr_croi2_a,
-            Corr_bgroi2_a,
+            combined_croi_factor2,
+            combined_bgroi_factor2,
+            polarization_croi_factor2,
+            polarization_bgroi_factor2,
             x_coord2_a,
             y_coord2_a,
             roi_hsize2_a,
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index eed1385..7e08ce7 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -128,6 +128,8 @@ def _compute_rocking_integration(
     C_norm=1.0,
     detector_acceptance=None,
     solid_angle_mean=None,
+    ctr_croibg_curves=None,
+    ctr_croibg_errors_curves=None,
     angle_unit="deg",
     progress_callback=None,
     should_cancel=None,
@@ -195,6 +197,15 @@ def _compute_rocking_integration(
         detector obliquity in a structure factor even though it is what a
         broad, non-rod feature wants on its intensity. ``None`` when the
         correction was not applied.
+    :param ctr_croibg_curves:
+        Optional polarization-only per-image ROI curves for new extractions,
+        with the same shape as ``croibg_curves``. When supplied, ``F2_hkl``
+        is derived from this branch while the saved intensity outputs retain
+        ``croibg_curves``. Legacy curves omit it and keep the historical
+        solid-angle compensation path.
+    :param ctr_croibg_errors_curves:
+        One-sigma errors paired with ``ctr_croibg_curves``. Both CTR arrays
+        must be supplied together.
     :param str angle_unit:
         Unit of ``axis``, ``'deg'`` or ``'rad'``. The published expressions
         integrate the rocking angle in radian; ``'deg'`` converts the integral
@@ -215,6 +226,10 @@ def _compute_rocking_integration(
         ``use_lorentz`` is ``True``, ``F2_hkl`` and ``F2_hkl_errors``.
     :rtype: dict
     """
+    if (ctr_croibg_curves is None) != (ctr_croibg_errors_curves is None):
+        raise ValueError(
+            "ctr_croibg_curves and ctr_croibg_errors_curves must be given together"
+        )
     int_data = {}
     for roikey in roi_info:
         if roikey.startswith("sig") or roikey.startswith("bg"):
@@ -227,6 +242,7 @@ def _compute_rocking_integration(
                 "C_norm": [],
                 "C_Lor": [],
                 "C_rod": [],
+                "C_Lorentz_rod": [],
                 "C_flux_on_sample": [],
                 "C_illum_area": [],
                 "auxillary": dict((a, []) for a in aux),
@@ -271,8 +287,23 @@ def _compute_rocking_integration(
                 int_data[roikey]["C_norm"].append(1.0)
 
             if use_lorentz:
-                int_data[roikey]["C_Lor"].append(np.mean(C_Lor[i][roi_slice]))
-                int_data[roikey]["C_rod"].append(np.mean(C_rod[i][roi_slice]))
+                lorentz_roi = np.asarray(C_Lor[i][roi_slice], dtype=float)
+                rod_roi = np.asarray(C_rod[i][roi_slice], dtype=float)
+
+                def interval_mean(values):
+                    if values.size < 2 or int_interval == 0.0:
+                        return float(np.mean(values))
+                    return float(
+                        _trapz_impl(values, roi_axis)
+                        * sign_interval
+                        / int_interval
+                    )
+
+                int_data[roikey]["C_Lor"].append(interval_mean(lorentz_roi))
+                int_data[roikey]["C_rod"].append(interval_mean(rod_roi))
+                int_data[roikey]["C_Lorentz_rod"].append(
+                    interval_mean(lorentz_roi * rod_roi)
+                )
 
             if use_footprint:
                 int_data[roikey]["C_flux_on_sample"].append(
@@ -344,6 +375,7 @@ def _compute_rocking_integration(
     sig_interval = np.zeros(s_array.size, dtype=float)
     C_Lorentz = np.zeros(s_array.size, dtype=float)
     C_rod_intersect = np.zeros(s_array.size, dtype=float)
+    C_Lorentz_rod = np.zeros(s_array.size, dtype=float)
     aux_cnts_integral = dict((a, np.zeros(s_array.size, dtype=float)) for a in aux)
     aux_cnts_integral_mean = dict((a, np.zeros(s_array.size, dtype=float)) for a in aux)
     aux_cnts_sum = dict((a, np.zeros(s_array.size, dtype=float)) for a in aux)
@@ -376,6 +408,9 @@ def _compute_rocking_integration(
                 C_rod_intersect += int_data[roikey]["C_rod"] * (
                     int_data[roikey]["int_interval"] / sig_interval
                 )
+                C_Lorentz_rod += int_data[roikey]["C_Lorentz_rod"] * (
+                    int_data[roikey]["int_interval"] / sig_interval
+                )
 
     raw_croi_errors = np.sqrt(raw_croi_errors)
     croi_errors = np.sqrt(croi_errors)
@@ -468,10 +503,11 @@ def _compute_rocking_integration(
         intensity_errors = measurement_corrections.normalized_intensity(
             croibg_errors, angle_unit=angle_unit
         )
-        # The mode components are interval-weighted means over the rocking
-        # interval, which is why they are multiplied here rather than asking
-        # measurement.angular_factor to rebuild eta from point angles.
-        denominator = C_Lorentz * C_rod_intersect
+        # The joint factor is integrated with the same trapezoidal angular
+        # quadrature as the counts. Multiplying independently averaged
+        # Lorentz and rod terms leaves a covariance residual whenever both
+        # vary through the rocking window.
+        denominator = C_Lorentz_rod
         if detector_acceptance is not None:
             denominator = denominator * np.asarray(detector_acceptance, dtype=float)
         if solid_angle_mean is not None:
@@ -479,6 +515,33 @@ def _compute_rocking_integration(
         result["F2_hkl"] = intensity / denominator
         result["F2_hkl_errors"] = intensity_errors / denominator
 
+        if ctr_croibg_curves is not None:
+            # New extractions carry a polarization-only curve made from the
+            # same base signal. Re-run the pure aggregation on that branch so
+            # signal/background windows, nonuniform or reversed angular
+            # quadrature and error propagation stay identical. No separately
+            # estimated solid-angle mean enters this path.
+            ctr_result = _compute_rocking_integration(
+                s_array,
+                axis,
+                ctr_croibg_curves,
+                ctr_croibg_errors_curves,
+                roi_info,
+                aux,
+                use_lorentz,
+                use_footprint,
+                C_Lor=C_Lor,
+                C_rod=C_rod,
+                C_flux_on_sample=C_flux_on_sample,
+                C_illum_area=C_illum_area,
+                C_norm=C_norm,
+                detector_acceptance=detector_acceptance,
+                solid_angle_mean=None,
+                angle_unit=angle_unit,
+            )
+            result["F2_hkl"] = ctr_result["F2_hkl"]
+            result["F2_hkl_errors"] = ctr_result["F2_hkl_errors"]
+
     return result
 
 
@@ -1767,9 +1830,15 @@ def integrate(self):
             detector_acceptance, acceptance_applied = self._rocking_acceptance(
                 detector, cnters, x, y
             )
-            solid_angle_mean, solid_angle_compensated = (
-                self._rocking_solid_angle_mean(detector, scangroup, cnters, x, y)
-            )
+            # New extractions carry their polarization-only CTR branch
+            # directly. The separately estimated solid-angle compensation is
+            # retained only for legacy database files that lack that branch.
+            if "ctr_croibg" not in curves:
+                solid_angle_mean, solid_angle_compensated = (
+                    self._rocking_solid_angle_mean(
+                        detector, scangroup, cnters, x, y
+                    )
+                )
 
         self.database.nxfile[self._currentRoInfo["name"] + "/integration/"]
         roi_info = h5todict(
@@ -1796,6 +1865,8 @@ def integrate(self):
             C_norm=C_norm,
             detector_acceptance=detector_acceptance,
             solid_angle_mean=solid_angle_mean,
+            ctr_croibg_curves=curves.get("ctr_croibg"),
+            ctr_croibg_errors_curves=curves.get("ctr_croibg_errors"),
             angle_unit="deg",
             progress_callback=progress.update,
             should_cancel=progress.wasCanceled,
@@ -1925,6 +1996,7 @@ def integrate(self):
                 "@normalization_applied": ",".join(normalization_applied) or "none",
                 "@acceptance_applied": bool(acceptance_applied),
                 "@solid_angle_compensated": bool(solid_angle_compensated),
+                "@photon_curve_used": "ctr_croibg" in curves,
                 "@active_area_applied": bool(self.footprintButton.isChecked()),
             }
             if detector_acceptance is not None:
@@ -2068,6 +2140,9 @@ def get_all_ro_curves(self):
             "croibg": cnters["croibg"][()],
             "croibg_errors": cnters["croibg_errors"][()],
         }
+        if "ctr_croibg" in cnters and "ctr_croibg_errors" in cnters:
+            curve["ctr_croibg"] = cnters["ctr_croibg"][()]
+            curve["ctr_croibg_errors"] = cnters["ctr_croibg_errors"][()]
         return curve
 
     # def onAnchorBtnToggled(self, state):
diff --git a/orgui/app/test/test_integration_corrections.py b/orgui/app/test/test_integration_corrections.py
index 226bcdb..64d55ab 100644
--- a/orgui/app/test/test_integration_corrections.py
+++ b/orgui/app/test/test_integration_corrections.py
@@ -186,6 +186,49 @@ def test_disabled_corrections_leave_the_intensity_untouched():
     np.testing.assert_array_equal(errors, np.ones(3))
 
 
+def test_pixel_branches_keep_solid_angle_out_of_ctr_counts():
+    """The CTR branch is built directly, not by scalar compensation."""
+    base = np.array([100.0, 200.0])
+    errors = np.array([10.0, 14.0])
+    polarization = np.array([1.2, 1.3])
+    arm = np.array([1.0, 1.1])
+
+    off = ic.pixel_correction_branches(
+        base, errors, polarization, polarization, arm
+    )
+    on = ic.pixel_correction_branches(
+        base,
+        errors,
+        np.array([2.4, 3.9]),
+        polarization,
+        arm,
+    )
+
+    assert not np.allclose(on[0], off[0])
+    np.testing.assert_allclose(on[2], off[2])
+    np.testing.assert_allclose(on[3], off[3])
+    np.testing.assert_allclose(on[2], base * polarization * arm)
+
+
+def test_pixel_branches_do_not_leak_combined_factor_covariance():
+    """``mean(S*P)/mean(S)`` must not stand in for ``mean(P)``."""
+    solid_angle = np.array([1.0, 2.0])
+    polarization = np.array([2.0, 1.0])
+    combined_mean = np.mean(solid_angle * polarization)
+    solid_angle_mean = np.mean(solid_angle)
+    polarization_mean = np.mean(polarization)
+    assert combined_mean / solid_angle_mean != polarization_mean
+
+    _, _, ctr, _ = ic.pixel_correction_branches(
+        np.array([10.0]),
+        np.array([2.0]),
+        np.array([combined_mean]),
+        np.array([polarization_mean]),
+    )
+
+    np.testing.assert_allclose(ctr, 10.0 * polarization_mean)
+
+
 def test_factors_broadcast_to_the_shape_of_alpha():
     """A scalar normalization still yields one factor per image."""
     factors = ic.stationary_correction_factors(
diff --git a/orgui/app/test/test_orGUI_reflections.py b/orgui/app/test/test_orGUI_reflections.py
index 34d5fc1..8b645e5 100644
--- a/orgui/app/test/test_orGUI_reflections.py
+++ b/orgui/app/test/test_orGUI_reflections.py
@@ -6,7 +6,13 @@
 import pytest
 from silx.gui import qt
 
-from orgui.app.orGUI import _display_roi_geometry, _rocking_arm_snapshot, orGUI
+from orgui.app.orGUI import (
+    _correction_region_counters,
+    _display_roi_geometry,
+    _rocking_arm_snapshot,
+    _warn_masked_peak_scaling,
+    orGUI,
+)
 from orgui.app.QReflectionSelector import (
     AutoBraggOptionsDialog,
     AutoBraggStatusDialog,
@@ -30,6 +36,44 @@ def surfaceAnglesPoint(self, y, x, alpha_i):
         return 2.0e-4 * y + alpha_i, 1.0e-4 * x
 
 
+def test_correction_counters_share_mask_across_center_and_backgrounds():
+    correction = np.arange(30, dtype=float).reshape(5, 6) + 1.0
+    mask = np.zeros_like(correction, dtype=bool)
+    mask[1, 2] = True
+    mask[3, 4] = True
+    center = (slice(1, 4), slice(1, 3))
+    backgrounds = [
+        (slice(0, 1), slice(1, 3)),
+        (slice(4, 6), slice(3, 5)),
+    ]
+
+    counters = _correction_region_counters(
+        correction, mask, center, backgrounds
+    )
+
+    valid = np.where(mask, np.nan, correction)
+    expected_center = valid[1:3, 1:4]
+    expected_background = np.concatenate(
+        [valid[1:3, 0:1].ravel(), valid[3:5, 4:6].ravel()]
+    )
+    np.testing.assert_allclose(
+        counters,
+        [
+            np.nansum(expected_center),
+            np.sum(np.isfinite(expected_center)),
+            np.nansum(expected_background),
+            np.sum(np.isfinite(expected_background)),
+        ],
+    )
+
+
+def test_masked_peak_scaling_warning_explains_nonphysical_recovery(caplog):
+    with caplog.at_level(logging.WARNING):
+        _warn_masked_peak_scaling([8.0, 10.0], [10.0, 10.0], "Test ROI")
+
+    assert "not a physical recovery of peak intensity" in caplog.text
+
+
 def test_rocking_arm_snapshot_is_per_frame_and_unit_tagged():
     """A saved rocking extraction retains the arm history needed later."""
     gamma = np.deg2rad([0.0, 15.0, 30.0])
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index 38208b9..4716773 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -417,6 +417,91 @@ def test_the_acceptance_divides_f2_and_only_f2():
     )
 
 
+def test_joint_lorentz_rod_factor_uses_the_count_quadrature():
+    """Correlated factors are averaged as a product on a nonuniform axis."""
+    axis = np.array([-0.5, -0.2, 0.0, 0.1, 0.5])
+    curve = np.full(axis.shape, 10.0)
+    lorentz = np.array([[1.0, 1.4, 2.0, 2.5, 4.0]])
+    rod = np.array([[4.0, 2.5, 2.0, 1.4, 1.0]])
+    result = _compute_rocking_integration(
+        np.array([0.0]),
+        axis,
+        curve[None, :],
+        np.sqrt(curve)[None, :],
+        _roi_info(0.0, {"sig_1": (-0.5, 0.5)}),
+        {},
+        True,
+        False,
+        C_Lor=lorentz,
+        C_rod=rod,
+        angle_unit="rad",
+    )
+
+    joint = _trapz_impl((lorentz * rod)[0], axis) / (axis[-1] - axis[0])
+    separate = (
+        _trapz_impl(lorentz[0], axis)
+        * _trapz_impl(rod[0], axis)
+        / (axis[-1] - axis[0]) ** 2
+    )
+    assert not np.isclose(joint, separate)
+    np.testing.assert_allclose(result["F2_hkl"], result["croibg"] / joint)
+
+    reversed_result = _compute_rocking_integration(
+        np.array([0.0]),
+        axis[::-1],
+        curve[None, ::-1],
+        np.sqrt(curve)[None, ::-1],
+        _roi_info(0.0, {"sig_1": (-0.5, 0.5)}),
+        {},
+        True,
+        False,
+        C_Lor=lorentz[:, ::-1],
+        C_rod=rod[:, ::-1],
+        angle_unit="rad",
+    )
+    np.testing.assert_allclose(reversed_result["F2_hkl"], result["F2_hkl"])
+    np.testing.assert_allclose(
+        reversed_result["F2_hkl_errors"], result["F2_hkl_errors"]
+    )
+
+
+def test_polarization_only_rocking_branch_controls_f2():
+    """Solid-angle changes remain in intensity but cannot enter new F2."""
+    axis = np.linspace(-0.5, 0.5, 101)
+    photon_curve = np.full((1, axis.size), 10.0)
+    intensity_curve = photon_curve * 2.5
+    errors = np.sqrt(photon_curve)
+    common = dict(
+        s_array=np.array([0.0]),
+        axis=axis,
+        croibg_errors_curves=errors,
+        roi_info=_roi_info(0.0, {"sig_1": (-0.4, 0.4)}),
+        aux={},
+        use_lorentz=True,
+        use_footprint=False,
+        C_Lor=np.ones_like(photon_curve),
+        C_rod=np.ones_like(photon_curve),
+        ctr_croibg_curves=photon_curve,
+        ctr_croibg_errors_curves=errors,
+        angle_unit="rad",
+    )
+
+    with_solid_angle = _compute_rocking_integration(
+        croibg_curves=intensity_curve, **common
+    )
+    without = _compute_rocking_integration(
+        croibg_curves=photon_curve, **common
+    )
+
+    np.testing.assert_allclose(
+        with_solid_angle["croibg"], 2.5 * without["croibg"]
+    )
+    np.testing.assert_allclose(with_solid_angle["F2_hkl"], without["F2_hkl"])
+    np.testing.assert_allclose(
+        with_solid_angle["F2_hkl_errors"], without["F2_hkl_errors"]
+    )
+
+
 class _RowOnlyDetector:
     """A detector whose exit angle depends only on pyFAI dimension 1.
 
diff --git a/orgui/app/test/test_scan_mode_equivalence.py b/orgui/app/test/test_scan_mode_equivalence.py
index 175c457..1e917c7 100644
--- a/orgui/app/test/test_scan_mode_equivalence.py
+++ b/orgui/app/test/test_scan_mode_equivalence.py
@@ -158,10 +158,12 @@ def _orgui_rocking_f2(rod, acceptance, reduce=True, solid_angle_mean=None):
         distortion test below needs to compare against.
     """
     ell, alpha, delta, gamma, _, _, _ = rod
-    axis, curves = _simulate_rocking(rod, acceptance)
+    axis, photon_curves = _simulate_rocking(rod, acceptance)
+    curves = photon_curves
     if solid_angle_mean is not None:
         # As the per-pixel correction does when the switch is on: it scales
-        # the counts, region by region.
+        # the diagnostic intensity, region by region. The independently
+        # accumulated CTR branch retains the photon counts.
         curves = curves * np.asarray(solid_angle_mean)[:, None]
     shape = curves.shape
     lorentz = np.broadcast_to(
@@ -173,7 +175,8 @@ def _orgui_rocking_f2(rod, acceptance, reduce=True, solid_angle_mean=None):
         extra = dict(
             C_norm=np.full(shape, ROCKING_EXPOSURE * ROCKING_MONITOR),
             detector_acceptance=acceptance,
-            solid_angle_mean=solid_angle_mean,
+            ctr_croibg_curves=photon_curves,
+            ctr_croibg_errors_curves=np.sqrt(np.abs(photon_curves)),
             angle_unit="deg",
         )
     else:
@@ -198,14 +201,18 @@ def _orgui_stationary_f2(rod, solid_angle_mean=None):
     """``F2_hkl`` as :mod:`orgui.app.integration_corrections` computes it.
 
     :param solid_angle_mean: When given, the region-mean solid-angle
-        correction is applied to the counts, as the per-pixel array does when
-        the switch is on, and handed to the reduction so that it comes back
-        out of the structure factor.
+        correction is applied only to the diagnostic intensity. The direct
+        photon branch used for the structure factor remains unchanged.
     """
     ell, alpha, delta, gamma, _, _, _ = rod
-    counts = _simulate_stationary(rod)
-    if solid_angle_mean is not None:
-        counts = counts * np.asarray(solid_angle_mean)
+    photon_counts = _simulate_stationary(rod)
+    combined = 1.0 if solid_angle_mean is None else solid_angle_mean
+    _, _, ctr_counts, ctr_errors = ic.pixel_correction_branches(
+        photon_counts,
+        np.sqrt(photon_counts),
+        combined,
+        1.0,
+    )
     factors = ic.stationary_correction_factors(
         alpha,
         delta,
@@ -214,12 +221,11 @@ def _orgui_stationary_f2(rod, solid_angle_mean=None):
         normalization=np.full(
             ell.size, STATIONARY_EXPOSURE * STATIONARY_MONITOR
         ),
-        solid_angle_mean=solid_angle_mean,
     )
-    intensity, errors = ic.apply_stationary_corrections(
-        counts, np.sqrt(counts), factors
+    ctr_intensity, ctr_errors = ic.apply_stationary_corrections(
+        ctr_counts, ctr_errors, factors
     )
-    return ic.structure_factor(intensity, errors, factors)[0]
+    return ic.structure_factor(ctr_intensity, ctr_errors, factors)[0]
 
 
 def test_the_unified_reduction_recovers_one_structure_factor(rod):

From 2c7fd63fef0ee1f925016b447d6053bfca4829fd Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Wed, 16 Sep 2026 21:33:35 -0400
Subject: [PATCH 25/33] feat(phys): wire framewise CTR normalization

---
 CHANGELOG.md                                  |  32 +-
 orgui/app/config_data.py                      |  27 ++
 orgui/app/integration_corrections.py          | 420 +++++++++++++++++-
 orgui/app/orGUI.py                            | 260 ++++++++---
 orgui/app/peak1Dintegr.py                     | 155 ++++++-
 orgui/app/test/test_config_data.py            |  41 ++
 .../app/test/test_frame_correction_policy.py  | 214 +++++++++
 orgui/app/test/test_peak1Dintegr.py           |  60 +++
 8 files changed, 1125 insertions(+), 84 deletions(-)
 create mode 100644 orgui/app/test/test_frame_correction_policy.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b3ab29..c768609 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,8 +15,29 @@ Scientific and analysis additions:
   ``K = r_e^2 lambda^2 / A_u^2``. Built-in beam profiles retain the finite
   grazing-incidence limit, and horizontal interception must be stated
   separately because a vertical profile cannot infer it. This stage adds the
-  unit-audited numerical path only: current extraction/UI behavior and the
-  legacy flux-density APIs remain unchanged until the later wiring stage.
+  unit-audited numerical path; the extraction/reduction wiring described
+  below activates it only for explicit version-3 settings. The UI and legacy
+  flux-density APIs remain unchanged until the later UI stage.
+
+- **Stationary and rocking CTR integrations now share one framewise total-flux
+  policy.** An explicitly configured primary monitor is classified as a rate
+  or an integrated reading, so exposure enters its photon-fluence divisor
+  exactly once; an ``ic2``-style ion-chamber rate is therefore handled as
+  ``exposure * monitor_rate`` before applying its calibration factor. New
+  total-flux curves require both the stored incident-photon divisor ``Q`` and
+  the stated horizontal plus calculated vertical illumination divisor ``H``
+  before they can be labeled ``F2_hkl``. Stationary scans form that result
+  immediately. Rocking scans keep the existing later reduction step, but the
+  reducer now recognizes ``framewise_ctr_total_flux_v1``, reconstructs the
+  curve from its immutable polarization-only base values and exact stored Q/H
+  arrays, and does not call the live legacy normalization or footprint path a
+  second time. Calibrated curves additionally use the stored wavelength and
+  surface unit-cell area with ``r_e^2 lambda^2 / A_u^2``; detector efficiency
+  and external transmission remain explicit unity assumptions. Footprint
+  keep/remove/replace operations always restart from the saved base curve,
+  reject unknown provenance, and require explicit permission to cross between
+  the legacy active-area and new total-flux conventions. Legacy databases and
+  reconstruction defaults retain their existing numerical behavior.
 
 - **Saved CTR curves now carry a versioned correction record.** This is a
   persistence-only compatibility step: numerical defaults and the established
@@ -29,9 +50,10 @@ Scientific and analysis additions:
   flux separately from the legacy flux density, together with primary-monitor
   kind/reference and horizontal-interception fields; absent values remain
   unknown rather than physical zero or unity. The rocking reducer explicitly
-  accepts the unchanged legacy-algorithm record but refuses a future
-  frame-normalized record until its dedicated dispatch path is implemented,
-  preventing it from silently normalizing a new curve twice.
+  accepts unchanged legacy-algorithm records, dispatches the supported
+  total-flux algorithm through its stored divisors, and refuses any other
+  normalized contract, preventing it from silently normalizing a new curve
+  twice.
 
 - **The polarization correction now follows the detector arm.**
   *This changes saved numbers for scans that move the detector arm and for
diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index 27e83c5..4a0b10c 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -170,6 +170,19 @@ def from_dict(cls, values):
         return cls(**values)
 
 
+_TOTAL_FLUX_STATE_FIELDS = (
+    "total_incident_flux",
+    "total_flux_calibrated",
+    "primary_monitor",
+    "primary_monitor_kind",
+    "primary_monitor_unit",
+    "monitor_reference_reading",
+    "monitor_reference_exposure_s",
+    "horizontal_interception",
+    "horizontal_intercepted_fraction",
+)
+
+
 @dataclass
 class CurveCorrectionRecord:
     """Applied correction provenance for one saved curve branch.
@@ -1193,6 +1206,14 @@ def from_gui(cls, gui):
                 beam_profile_positions_m=beam_profile_positions_m,
                 beam_profile_density_per_m=beam_profile_density_per_m,
             )
+            # Stage 5 has a numerical total-flux path before Stage 6 adds its
+            # widgets. Preserve explicitly loaded/programmatic version-3
+            # settings on the GUI object instead of dropping them when a new
+            # extraction snapshot is captured.
+            total_flux_state = getattr(gui, "ctr_correction_state", None)
+            if total_flux_state is not None:
+                for name in _TOTAL_FLUX_STATE_FIELDS:
+                    setattr(corrections, name, getattr(total_flux_state, name))
             roi = ROIState(
                 region=dict(options.get("region", {})),
                 advanced=dict(options.get("advanced", {})),
@@ -1219,6 +1240,12 @@ def apply_to_gui(self, gui):
         ub_widget = getattr(gui, "ubcalc", gui)
         ub_widget.detectorCal = detector_from_nxdict(detector_to_nxdict(self.detector))
         ub_widget.crystal = unit_cell_from_nxdict(unit_cell_to_nxdict(self.unit_cell))
+        # Keep the not-yet-widget-backed total-flux settings available to the
+        # extraction policy. Copy through the public JSON representation so a
+        # later GUI edit cannot mutate the loaded ConfigData instance.
+        gui.ctr_correction_state = CorrectionState.from_dict(
+            self.corrections.to_dict()
+        )
         ub_widget.ubCal = HKLVlieg.UBCalculator(
             ub_widget.crystal, self.ub_calculator.getEnergy()
         )
diff --git a/orgui/app/integration_corrections.py b/orgui/app/integration_corrections.py
index 1d26d2e..517bc50 100644
--- a/orgui/app/integration_corrections.py
+++ b/orgui/app/integration_corrections.py
@@ -31,7 +31,8 @@
 into arguments for those functions, and assembling the result into the bundle
 that is stored beside the integrated intensity.
 
-The normalization and numerical active-area factor are intensity divisors:
+The legacy normalization and numerical active-area factor are intensity
+divisors:
 
 .. math::
 
@@ -51,15 +52,24 @@
 reconstruction (:mod:`orgui.reconstruction_job`), so a stationary integration
 and a reconstruction of the same scan are normalized identically.
 
+An explicit total-flux configuration instead stores incident photons per frame
+``Q`` and the dimensionless illumination divisor ``H``. That versioned path
+does not reinterpret the legacy density/area fields, and reversible changes
+always restart from the stored polarization-only scalar curve.
+
 This module holds no Qt state and reads only public scan attributes, so it is
 safe in CLI and batch use.
 """
 
+from dataclasses import dataclass
+
 import numpy as np
 
-from ..datautils.xrayutils.corrections import measurement
+from ..datautils.xrayutils.corrections import activearea, measurement
 from ..datautils.xrayutils.corrections.normalization import (
+    frame_fluence,
     normalization_divisor as _divisor_from_counters,
+    relative_frame_fluence,
 )
 from ..datautils.xrayutils.corrections.roi import (  # noqa: F401
     CorrectionFactors,
@@ -68,15 +78,370 @@
 
 __all__ = [
     "CorrectionFactors",
+    "FrameCorrectionPolicy",
+    "FOOTPRINT_APPLY",
+    "FOOTPRINT_KEEP",
+    "FOOTPRINT_REMOVE",
     "apply_stationary_corrections",
+    "corrected_curve_from_record",
+    "frame_correction_policy",
     "monitor_counter_candidates",
     "normalization_divisor",
     "pixel_correction_branches",
     "roi_mean_correction",
     "stationary_correction_factors",
     "structure_factor",
+    "structure_factor_from_policy",
 ]
 
+FOOTPRINT_KEEP = "keep"
+FOOTPRINT_APPLY = "apply"
+FOOTPRINT_REMOVE = "remove"
+
+
+@dataclass(frozen=True)
+class FrameCorrectionPolicy:
+    """Exact framewise normalization and illumination decision.
+
+    ``new_contract`` distinguishes an explicitly configured primary-monitor
+    or total-flux convention from the legacy product of reconstruction
+    monitor counters. Optional arrays remain ``None`` when deliberately not
+    applied; statuses record that decision without inventing unity data.
+    """
+
+    new_contract: bool
+    scale_convention: str
+    normalization_status: str
+    normalization_divisor: object = None
+    normalization_unit: str | None = None
+    normalization_components: tuple[str, ...] = ()
+    illumination_status: str = "not_applied"
+    illumination_divisor: object = None
+    illumination_convention: str | None = None
+    vertical_intercepted_fraction: object = None
+    horizontal_intercepted_fraction: object = None
+    intercepted_fraction: object = None
+    calibrated: bool = False
+
+    @property
+    def ctr_scale_ready(self):
+        """Whether both required :math:`Q` and :math:`H` were applied."""
+        return (
+            self.normalization_status == "applied"
+            and self.illumination_status == "applied"
+        )
+
+
+def _explicit_total_flux_contract(state):
+    """Return whether ``state`` explicitly selects the new convention."""
+    return any(
+        getattr(state, name, None) is not None
+        for name in (
+            "total_incident_flux",
+            "total_flux_calibrated",
+            "primary_monitor",
+            "primary_monitor_kind",
+            "horizontal_interception",
+            "horizontal_intercepted_fraction",
+        )
+    )
+
+
+def _horizontal_fraction(state):
+    """Resolve an explicit horizontal-interception setting."""
+    mode = getattr(state, "horizontal_interception", None)
+    if mode == "full":
+        return 1.0
+    if mode == "fraction":
+        value = getattr(state, "horizontal_intercepted_fraction", None)
+        if value is None:
+            raise ValueError(
+                "horizontal_intercepted_fraction is required for fraction mode"
+            )
+        return float(value)
+    raise ValueError(
+        "total-flux illumination requires horizontal_interception to be "
+        "'full' or 'fraction'"
+    )
+
+
+def frame_correction_policy(
+    scan,
+    state,
+    size,
+    *,
+    use_normalization,
+    use_illumination,
+    alpha=None,
+    beam_profile=None,
+    sample_length=None,
+):
+    r"""Resolve the exact framewise :math:`Q` and :math:`H` policy.
+
+    Explicit primary-monitor/total-flux fields select the new convention.
+    Otherwise the established exposure-times-multiple-monitors and legacy
+    numerical active-area convention is retained. A calibrated flux is used
+    only when marked calibrated and every required reference value exists.
+
+    :param scan: Loaded scan providing exposure and counter attributes.
+    :param state: Correction-state-like object with the version-3 fields.
+    :param int size: Number of frames.
+    :param bool use_normalization: Apply the requested frame normalization.
+    :param bool use_illumination: Apply the requested footprint correction.
+    :param alpha: Incidence angle(s), radian; required for illumination.
+    :param beam_profile: Vertical beam profile; required for illumination.
+    :param sample_length: Sample length along the beam, meter.
+    :returns: Fully resolved policy with the arrays actually applied.
+    :rtype: FrameCorrectionPolicy
+    """
+    new_contract = _explicit_total_flux_contract(state)
+    if not new_contract:
+        divisor = None
+        components = ()
+        norm_status = "not_applied"
+        if use_normalization:
+            divisor, applied = normalization_divisor(
+                scan,
+                bool(getattr(state, "normalize_exposure", True)),
+                tuple(getattr(state, "monitor_corrections", ()) or ()),
+                size,
+            )
+            components = tuple(applied)
+            norm_status = "applied" if applied else "unavailable"
+
+        illumination = vertical = None
+        illum_status = "not_applied"
+        if use_illumination:
+            if alpha is None or beam_profile is None or sample_length is None:
+                raise ValueError(
+                    "legacy footprint correction needs alpha, beam profile "
+                    "and sample length"
+                )
+            vertical, illumination = beam_profile.corrections(
+                alpha, sample_length
+            )
+            illum_status = "applied"
+        return FrameCorrectionPolicy(
+            new_contract=False,
+            scale_convention="legacy_relative",
+            normalization_status=norm_status,
+            normalization_divisor=divisor,
+            normalization_unit=(
+                "legacy_counter_product" if divisor is not None else None
+            ),
+            normalization_components=components,
+            illumination_status=illum_status,
+            illumination_divisor=illumination,
+            illumination_convention=(
+                "legacy_C_illum_area" if illumination is not None else None
+            ),
+            vertical_intercepted_fraction=vertical,
+        )
+
+    calibrated = bool(getattr(state, "total_flux_calibrated", False))
+    normalization = None
+    components = ()
+    norm_status = "not_applied"
+    norm_unit = None
+    if use_normalization:
+        exposure = getattr(scan, "exposure_time", None)
+        monitor_name = getattr(state, "primary_monitor", None)
+        monitor_kind = getattr(state, "primary_monitor_kind", None)
+        monitor = None
+        if monitor_name is not None:
+            if not hasattr(scan, monitor_name):
+                raise ValueError(
+                    f"Active scan has no primary monitor named {monitor_name!r}"
+                )
+            monitor = getattr(scan, monitor_name)
+        if calibrated:
+            total_flux = getattr(state, "total_incident_flux", None)
+            if total_flux is None:
+                raise ValueError(
+                    "a calibrated total-flux correction requires "
+                    "total_incident_flux"
+                )
+            normalization = frame_fluence(
+                total_flux,
+                exposure_time=exposure,
+                monitor=monitor,
+                monitor_kind=monitor_kind,
+                reference_monitor=getattr(
+                    state, "monitor_reference_reading", None
+                ),
+                reference_exposure=getattr(
+                    state, "monitor_reference_exposure_s", None
+                ),
+            )
+            norm_unit = "photons"
+        else:
+            normalization = relative_frame_fluence(
+                exposure_time=exposure,
+                monitor=monitor,
+                monitor_kind=monitor_kind,
+            )
+            norm_unit = "relative_fluence"
+        normalization = np.broadcast_to(
+            np.asarray(normalization, dtype=np.float64), (int(size),)
+        ).copy()
+        norm_status = "applied"
+        if monitor_name is None:
+            components = ("exposure",)
+        elif monitor_kind == "rate":
+            components = (
+                "exposure",
+                f"primary_monitor:{monitor_name}:{monitor_kind}",
+            )
+        else:
+            components = (f"primary_monitor:{monitor_name}:{monitor_kind}",)
+
+    illumination = vertical = intercepted = None
+    horizontal = None
+    illum_status = "not_applied"
+    if use_illumination:
+        if alpha is None or beam_profile is None or sample_length is None:
+            raise ValueError(
+                "total-flux illumination needs alpha, beam profile and "
+                "sample length"
+            )
+        horizontal = _horizontal_fraction(state)
+        vertical = np.asarray(
+            beam_profile.flux_on_sample(alpha, sample_length), dtype=np.float64
+        )
+        illumination = activearea.illumination_divisor(
+            alpha,
+            sample_length,
+            beam_profile,
+            horizontal_fraction=horizontal,
+        )
+        intercepted = activearea.intercepted_fraction(
+            alpha,
+            sample_length,
+            beam_profile,
+            horizontal_fraction=horizontal,
+        )
+        illum_status = "applied"
+
+    if calibrated:
+        scale = "total_flux_calibrated"
+    else:
+        scale = "total_flux_relative"
+    if norm_status != "applied" or illum_status != "applied":
+        scale += "_incomplete"
+    return FrameCorrectionPolicy(
+        new_contract=True,
+        scale_convention=scale,
+        normalization_status=norm_status,
+        normalization_divisor=normalization,
+        normalization_unit=norm_unit,
+        normalization_components=components,
+        illumination_status=illum_status,
+        illumination_divisor=illumination,
+        illumination_convention=(
+            "total_flux_H" if illumination is not None else None
+        ),
+        vertical_intercepted_fraction=vertical,
+        horizontal_intercepted_fraction=horizontal,
+        intercepted_fraction=intercepted,
+        calibrated=calibrated,
+    )
+
+
+def corrected_curve_from_record(
+    record,
+    *,
+    footprint_action=FOOTPRINT_KEEP,
+    replacement_illumination=None,
+    replacement_convention=None,
+    allow_convention_change=False,
+):
+    """Rebuild a corrected scalar curve from its immutable base values.
+
+    Every action starts from ``base_croibg`` and its variance, so applying or
+    replacing a footprint repeatedly cannot compound scaling. Unknown or
+    unavailable provenance is rejected rather than guessed.
+
+    :returns: ``(curve, errors, illumination_status, convention)``.
+    :rtype: tuple
+    """
+    if footprint_action not in (
+        FOOTPRINT_KEEP,
+        FOOTPRINT_APPLY,
+        FOOTPRINT_REMOVE,
+    ):
+        raise ValueError(f"unknown footprint action {footprint_action!r}")
+    if record.base_croibg is None or record.base_croibg_variance is None:
+        raise ValueError("curve record has no reversible base curve")
+
+    curve = np.asarray(record.base_croibg, dtype=np.float64).copy()
+    variance = np.asarray(record.base_croibg_variance, dtype=np.float64).copy()
+    if record.normalization_status == "applied":
+        if record.normalization_divisor is None:
+            raise ValueError("applied normalization has no stored divisor")
+        divisor = np.asarray(record.normalization_divisor, dtype=np.float64)
+        if np.any(divisor == 0) or not np.all(np.isfinite(divisor)):
+            raise ValueError("normalization divisor must be finite and nonzero")
+        curve = curve / divisor
+        variance = variance / np.square(divisor)
+    elif record.normalization_status != "not_applied":
+        raise ValueError(
+            "normalization provenance is insufficient for safe re-reduction"
+        )
+
+    stored_status = record.illumination_status
+    stored_convention = record.illumination_convention
+    if footprint_action == FOOTPRINT_KEEP:
+        if stored_status == "applied":
+            if record.illumination_divisor is None:
+                raise ValueError("applied illumination has no stored divisor")
+            illumination = np.asarray(
+                record.illumination_divisor, dtype=np.float64
+            )
+            status = "applied"
+            convention = stored_convention
+        elif stored_status == "not_applied":
+            illumination = None
+            status = "not_applied"
+            convention = None
+        else:
+            raise ValueError(
+                "illumination provenance is insufficient for safe re-reduction"
+            )
+    elif footprint_action == FOOTPRINT_REMOVE:
+        if stored_status != "applied" or record.illumination_divisor is None:
+            raise ValueError("there is no known stored illumination to remove")
+        illumination = None
+        status = "removed"
+        convention = stored_convention
+    else:
+        if stored_status not in ("applied", "not_applied"):
+            raise ValueError(
+                "unknown stored illumination cannot be safely replaced"
+            )
+        if replacement_illumination is None or replacement_convention is None:
+            raise ValueError(
+                "applying illumination requires its divisor and convention"
+            )
+        if (
+            stored_status == "applied"
+            and stored_convention != replacement_convention
+            and not allow_convention_change
+        ):
+            raise ValueError(
+                "changing illumination convention requires an explicit "
+                "reconstruction from the stored base curve"
+            )
+        illumination = np.asarray(replacement_illumination, dtype=np.float64)
+        status = "replaced" if stored_status == "applied" else "applied_here"
+        convention = replacement_convention
+
+    if illumination is not None:
+        if np.any(illumination <= 0) or not np.all(np.isfinite(illumination)):
+            raise ValueError("illumination divisor must be finite and positive")
+        curve = curve / illumination
+        variance = variance / np.square(illumination)
+    return curve, np.sqrt(variance), status, convention
+
 
 def pixel_correction_branches(
     base_intensity,
@@ -201,6 +566,7 @@ def stationary_correction_factors(
     sample_size=None,
     normalization=None,
     solid_angle_mean=None,
+    illumination_divisor=None,
 ):
     r"""Correction divisors for one stationary-scan trajectory.
 
@@ -228,6 +594,8 @@ def stationary_correction_factors(
         was applied to the intensity, so that :func:`structure_factor` can
         divide it back out; a region sum is already a complete angular
         integral and must not carry it (finding F6).
+    :param illumination_divisor: Optional explicit total-flux illumination
+        :math:`H`. Mutually exclusive with the legacy ``use_footprint`` path.
     :returns: The factors, each broadcast to the shape of ``alpha``.
     :rtype: CorrectionFactors
     :raises ValueError: If the footprint correction is requested without a
@@ -249,6 +617,17 @@ def stationary_correction_factors(
         ).copy()
         applied.append("solid_angle")
 
+    if illumination_divisor is not None:
+        if use_footprint:
+            raise ValueError(
+                "explicit total-flux illumination and legacy footprint are "
+                "mutually exclusive"
+            )
+        factors["C_illumination"] = np.broadcast_to(
+            np.asarray(illumination_divisor, dtype=np.float64), alpha.shape
+        ).copy()
+        applied.append("total_flux_illumination")
+
     if use_footprint:
         if beam_profile is None:
             raise ValueError(
@@ -289,7 +668,9 @@ def apply_stationary_corrections(intensity, errors, factors):
     :returns: ``(intensity, errors)`` corrected.
     :rtype: tuple of numpy.ndarray
     """
-    divisor = factors.divisor("C_norm", "C_illum_area")
+    divisor = factors.divisor(
+        "C_norm", "C_illum_area", "C_illumination"
+    )
     return np.asarray(intensity) / divisor, np.asarray(errors) / divisor
 
 
@@ -320,3 +701,36 @@ def structure_factor(intensity, errors, factors):
     """
     divisor = factors["C_Lorentz"] * factors.divisor("C_solid_angle")
     return np.asarray(intensity) / divisor, np.asarray(errors) / divisor
+
+
+def structure_factor_from_policy(
+    intensity,
+    errors,
+    factors,
+    policy,
+    *,
+    wavelength=None,
+    unitcell_area=None,
+):
+    """Form relative or calibrated stationary CTR :math:`|F|^2`.
+
+    The calibrated branch is reachable only when the explicit total-flux
+    policy applied both Q and H and the crystallographic scale inputs are
+    supplied. Detector efficiency and external transmission are unity in this
+    first wired implementation and must be recorded by the caller.
+    """
+    if policy.new_contract and not policy.ctr_scale_ready:
+        raise ValueError(
+            "new CTR normalization must apply both frame fluence Q and "
+            "illumination H before a structure factor can be formed"
+        )
+    result, result_errors = structure_factor(intensity, errors, factors)
+    if not policy.calibrated:
+        return result, result_errors
+    if wavelength is None or unitcell_area is None:
+        raise ValueError(
+            "calibrated total-flux F2 needs wavelength and surface "
+            "unit-cell area"
+        )
+    prefactor = measurement.total_flux_prefactor(wavelength, unitcell_area)
+    return result / prefactor, result_errors / prefactor
diff --git a/orgui/app/orGUI.py b/orgui/app/orGUI.py
index 754c4cc..2cc7e1a 100644
--- a/orgui/app/orGUI.py
+++ b/orgui/app/orGUI.py
@@ -2710,17 +2710,106 @@ def sumImage(i):
                 }
 
         data_2d_structured[self.activescanname]["measurement"][name]["rois"] = rois
-        # A distinct versioned branch preserves the reversible scalar curve
-        # and applied-state provenance without changing the legacy ``rois``
-        # contract consumed by today's reducer. Stage 5 will opt into this
-        # branch when framewise Q/H normalization becomes active.
+        options = self.scanSelector.get_integration_options()
+        beam_profile = sample_length = None
+        if options["footprint"]:
+            footprint_dialog = (
+                self.scanSelector.correctionsDialog.footprintOptions_shared()
+            )
+            beam_profile = footprint_dialog.beamProfile()
+            sample_length = footprint_dialog.sampleLength()
+        frame_policy = integration_corrections.frame_correction_policy(
+            self.fscan,
+            config_snapshot.corrections,
+            rois["axis"].shape[1],
+            use_normalization=options["normalization"],
+            use_illumination=options["footprint"],
+            alpha=np.deg2rad(rois["alpha"]),
+            beam_profile=beam_profile,
+            sample_length=sample_length,
+        )
+        profile_provenance = _curve_profile_provenance(
+            config_snapshot.corrections
+        )
+        profile_provenance.update(
+            {
+                "wavelength_angstrom": config_snapshot.ub_calculator.getLambda(),
+                "unitcell_area_angstrom2": config_snapshot.unit_cell.uc_area,
+                "detector_efficiency_assumed": 1.0,
+                "external_transmission_assumed": 1.0,
+            }
+        )
+        # The preserved ``rois`` group remains legacy-compatible. An explicit
+        # primary-monitor/total-flux setup activates the sibling framewise
+        # contract; its Q/H arrays are applied by the rocking reducer before
+        # angular aggregation.
         curve_record = CurveCorrectionRecord(
-            algorithm="legacy_rocking_roi_v2",
-            output_quantity="rocking_roi_curve",
-            scale_convention="legacy_unnormalized",
-            normalization_status="not_applied",
-            illumination_status="not_applied",
+            algorithm=(
+                "framewise_ctr_total_flux_v1"
+                if frame_policy.new_contract
+                else "legacy_rocking_roi_v2"
+            ),
+            output_quantity=(
+                "rocking_ctr_photon_curve"
+                if frame_policy.new_contract
+                else "rocking_roi_curve"
+            ),
+            scale_convention=(
+                frame_policy.scale_convention
+                if frame_policy.new_contract
+                else "legacy_unnormalized"
+            ),
+            normalization_status=(
+                frame_policy.normalization_status
+                if frame_policy.new_contract
+                else "not_applied"
+            ),
+            illumination_status=(
+                frame_policy.illumination_status
+                if frame_policy.new_contract
+                else "not_applied"
+            ),
             pixel_correction_status=("applied" if corr else "not_applied"),
+            normalization_divisor=(
+                frame_policy.normalization_divisor
+                if frame_policy.new_contract
+                else None
+            ),
+            normalization_unit=(
+                frame_policy.normalization_unit
+                if frame_policy.new_contract
+                else None
+            ),
+            normalization_components=(
+                frame_policy.normalization_components
+                if frame_policy.new_contract
+                else ()
+            ),
+            illumination_divisor=(
+                frame_policy.illumination_divisor
+                if frame_policy.new_contract
+                else None
+            ),
+            illumination_convention=(
+                frame_policy.illumination_convention
+                if frame_policy.new_contract
+                else None
+            ),
+            vertical_intercepted_fraction=(
+                frame_policy.vertical_intercepted_fraction
+                if frame_policy.new_contract
+                else None
+            ),
+            horizontal_intercepted_fraction=(
+                frame_policy.horizontal_intercepted_fraction
+                if frame_policy.new_contract
+                else None
+            ),
+            intercepted_fraction=(
+                frame_policy.intercepted_fraction
+                if frame_policy.new_contract
+                else None
+            ),
             alpha=np.deg2rad(rois["alpha"]),
             base_croi=rois["croi"],
             base_croi_variance=rois["croi"],
@@ -2742,9 +2831,7 @@ def sumImage(i):
             roi_x_stop=rocking_roi_edges["x_stop"],
             roi_y_start=rocking_roi_edges["y_start"],
             roi_y_stop=rocking_roi_edges["y_stop"],
-            profile_provenance=_curve_profile_provenance(
-                config_snapshot.corrections
-            ),
+            profile_provenance=profile_provenance,
         )
         data_2d_structured[self.activescanname]["measurement"][name][
             CURVE_CORRECTIONS_GROUP
@@ -6815,6 +6902,7 @@ def sumImage(i):
             np.atleast_1d(np.asarray(mu_all, dtype=np.float64)), (nodatapoints,)
         )
         options = self.scanSelector.get_integration_options()
+        config_snapshot = ConfigData.from_gui(self)
         beam_profile = None
         sample_size = None
         if options["footprint"]:
@@ -6823,17 +6911,22 @@ def sumImage(i):
             )  # noqa: E501
             beam_profile = footprint_dialog.beamProfile()
             sample_size = footprint_dialog.sampleLength()  # m
-        normalization = None
-        normalization_applied = []
-        if options["normalization"]:
-            normalization, normalization_applied = (
-                integration_corrections.normalization_divisor(
-                    self.fscan,
-                    bool(getattr(self, "reconstruction_normalize_exposure", True)),
-                    tuple(getattr(self, "reconstruction_monitor_corrections", ())),
-                    nodatapoints,
-                )
-            )
+        frame_policy = integration_corrections.frame_correction_policy(
+            self.fscan,
+            config_snapshot.corrections,
+            nodatapoints,
+            use_normalization=options["normalization"],
+            use_illumination=options["footprint"],
+            alpha=alpha_all,
+            beam_profile=beam_profile,
+            sample_length=sample_size,
+        )
+        normalization = (
+            frame_policy.normalization_divisor
+            if frame_policy.normalization_status == "applied"
+            else None
+        )
+        normalization_applied = list(frame_policy.normalization_components)
 
         pol_arm1 = np.ones(nodatapoints, dtype=np.float64)
         pol_arm2 = np.ones(nodatapoints, dtype=np.float64)
@@ -6899,10 +6992,18 @@ def sumImage(i):
                     hkl_del_gam[:, 3],
                     hkl_del_gam[:, 4],
                     use_lorentz=options["lorentz"],
-                    use_footprint=options["footprint"],
+                    use_footprint=(
+                        options["footprint"] and not frame_policy.new_contract
+                    ),
                     beam_profile=beam_profile,
                     sample_size=sample_size,
                     normalization=normalization,
+                    illumination_divisor=(
+                        frame_policy.illumination_divisor
+                        if frame_policy.new_contract
+                        and frame_policy.illumination_status == "applied"
+                        else None
+                    ),
                 )
             )
         factors1, factors2 = correction_factors
@@ -6960,12 +7061,37 @@ def sumImage(i):
 
         F2_hkl1 = F2_hkl1_err = F2_hkl2 = F2_hkl2_err = None
         if options["lorentz"]:
-            F2_hkl1, F2_hkl1_err = integration_corrections.structure_factor(
-                ctr_croibg1_a, ctr_croibg1_err_a, factors1
-            )
-            F2_hkl2, F2_hkl2_err = integration_corrections.structure_factor(
-                ctr_croibg2_a, ctr_croibg2_err_a, factors2
-            )
+            try:
+                common_scale = {
+                    "wavelength": config_snapshot.ub_calculator.getLambda(),
+                    "unitcell_area": config_snapshot.unit_cell.uc_area,
+                }
+                F2_hkl1, F2_hkl1_err = (
+                    integration_corrections.structure_factor_from_policy(
+                        ctr_croibg1_a,
+                        ctr_croibg1_err_a,
+                        factors1,
+                        frame_policy,
+                        **common_scale,
+                    )
+                )
+                F2_hkl2, F2_hkl2_err = (
+                    integration_corrections.structure_factor_from_policy(
+                        ctr_croibg2_a,
+                        ctr_croibg2_err_a,
+                        factors2,
+                        frame_policy,
+                        **common_scale,
+                    )
+                )
+            except ValueError:
+                if not frame_policy.new_contract:
+                    raise
+                logger.warning(
+                    "The explicit CTR normalization is incomplete; saving "
+                    "diagnostic intensity without labeling it F2_hkl.",
+                    exc_info=True,
+                )
 
         rod_mask1 = np.isfinite(croibg1_a)
         rod_mask2 = np.isfinite(croibg2_a)
@@ -7110,6 +7236,7 @@ def sumImage(i):
                 "C_Lorentz": factors1.get("C_Lorentz"),
                 "C_flux_on_sample": factors1.get("C_flux_on_sample"),
                 "C_illum_area": factors1.get("C_illum_area"),
+                "C_illumination": factors1.get("C_illumination"),
                 "C_norm": factors1.get("C_norm"),
             },
             "pixelcoord": {
@@ -7176,6 +7303,7 @@ def sumImage(i):
                 "C_Lorentz": factors2.get("C_Lorentz"),
                 "C_flux_on_sample": factors2.get("C_flux_on_sample"),
                 "C_illum_area": factors2.get("C_illum_area"),
+                "C_illumination": factors2.get("C_illumination"),
                 "C_norm": factors2.get("C_norm"),
             },
             "pixelcoord": {
@@ -7196,18 +7324,16 @@ def sumImage(i):
             "@orgui_meta": "roi",
         }
 
-        config_snapshot = ConfigData.from_gui(self)
-
-        normalization_status = "not_applied"
-        normalization_divisor = None
-        if options["normalization"]:
-            if normalization_applied:
-                normalization_status = "applied"
-                normalization_divisor = factors1.get("C_norm")
-            else:
-                normalization_status = "unavailable"
-        illumination_status = (
-            "applied" if options["footprint"] else "not_applied"
+        profile_provenance = _curve_profile_provenance(
+            config_snapshot.corrections
+        )
+        profile_provenance.update(
+            {
+                "wavelength_angstrom": config_snapshot.ub_calculator.getLambda(),
+                "unitcell_area_angstrom2": config_snapshot.unit_cell.uc_area,
+                "detector_efficiency_assumed": 1.0,
+                "external_transmission_assumed": 1.0,
+            }
         )
 
         def versioned_stationary_curve(
@@ -7231,28 +7357,40 @@ def versioned_stationary_curve(
         ):
             """Build the non-legacy sibling branch for one trajectory."""
             record = CurveCorrectionRecord(
-                algorithm="legacy_stationary_roi_v2",
-                output_quantity="stationary_roi_intensity",
+                algorithm=(
+                    "framewise_ctr_total_flux_v1"
+                    if frame_policy.new_contract
+                    else "legacy_stationary_roi_v2"
+                ),
+                output_quantity=(
+                    "stationary_ctr_photon_curve"
+                    if frame_policy.new_contract
+                    else "stationary_roi_intensity"
+                ),
                 scale_convention=(
-                    "legacy_density_area"
-                    if options["footprint"]
-                    else "legacy_relative"
+                    frame_policy.scale_convention
+                    if frame_policy.new_contract
+                    else (
+                        "legacy_density_area"
+                        if options["footprint"]
+                        else "legacy_relative"
+                    )
                 ),
-                normalization_status=normalization_status,
-                illumination_status=illumination_status,
+                normalization_status=frame_policy.normalization_status,
+                illumination_status=frame_policy.illumination_status,
                 pixel_correction_status=("applied" if corr else "not_applied"),
-                normalization_divisor=normalization_divisor,
-                normalization_unit=(
-                    "legacy_counter_product"
-                    if normalization_divisor is not None
-                    else None
+                normalization_divisor=frame_policy.normalization_divisor,
+                normalization_unit=frame_policy.normalization_unit,
+                normalization_components=frame_policy.normalization_components,
+                illumination_divisor=frame_policy.illumination_divisor,
+                illumination_convention=frame_policy.illumination_convention,
+                vertical_intercepted_fraction=(
+                    frame_policy.vertical_intercepted_fraction
                 ),
-                normalization_components=tuple(normalization_applied),
-                illumination_divisor=factors.get("C_illum_area"),
-                illumination_convention=(
-                    "legacy_C_illum_area" if options["footprint"] else None
+                horizontal_intercepted_fraction=(
+                    frame_policy.horizontal_intercepted_fraction
                 ),
-                vertical_intercepted_fraction=factors.get("C_flux_on_sample"),
+                intercepted_fraction=frame_policy.intercepted_fraction,
                 alpha=alpha_all,
                 base_croi=croi,
                 base_croi_variance=croi,
@@ -7275,9 +7413,7 @@ def versioned_stationary_curve(
                 roi_y_start=y_start,
                 roi_y_stop=y_stop,
                 lorentz_mode=("stationary" if options["lorentz"] else None),
-                profile_provenance=_curve_profile_provenance(
-                    config_snapshot.corrections
-                ),
+                profile_provenance=profile_provenance,
             )
             return curve_correction_record_to_nxdict(record)
 
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 7e08ce7..13f3b01 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -61,8 +61,13 @@
     ConfigData,
     CorrectionState,
     corrections_from_nxdict,
+    curve_correction_record_from_nxdict,
     detector_from_nxdict,
 )
+from .integration_corrections import (
+    FOOTPRINT_KEEP,
+    corrected_curve_from_record,
+)
 from .. import resources
 from .. import logger_utils
 from ..datautils.xrayutils.corrections import beamprofile
@@ -1750,6 +1755,8 @@ def integrate(self):
         if not self._currentRoInfo:
             raise ValueError("No rocking scan selected.")
         curves = self.get_all_ro_curves()
+        correction_record = curves.get("correction_record")
+        versioned_total_flux = correction_record is not None
         name = self._currentRoInfo["name"]
         h5_obj = self.database.nxfile[name]
         cnters = h5_obj["rois"]
@@ -1791,7 +1798,13 @@ def integrate(self):
             C_Lor = 1.0
             C_rod = 1.0
 
-        if self.footprintButton.isChecked():
+        if versioned_total_flux:
+            # Q and H were resolved framewise at extraction and reconstructed
+            # from their stored divisors by get_all_ro_curves. Applying the
+            # live dialog here would scale the same photons a second time.
+            C_flux_on_sample = 1.0
+            C_illum_area = 1.0
+        elif self.footprintButton.isChecked():
             L = self.integrationCorrection.sampleLength()  # sample size, m
             # Gaussian or measured beam profile, depending on the dialog.
             # C_flux_on_sample is saved as the diagnostic numerator of the
@@ -1818,8 +1831,26 @@ def integrate(self):
             x = cnters["x"][()]
             y = cnters["y"][()]
 
-        C_norm, normalization_applied = self._rocking_normalization(aux, axis.size)
-        C_norm = np.broadcast_to(C_norm, np.shape(curves["croibg"])).copy()
+        if versioned_total_flux:
+            if (
+                correction_record.normalization_status != "applied"
+                or curves["illumination_action"]
+                not in ("applied", "replaced", "applied_here")
+                or curves["illumination_convention"] != "total_flux_H"
+            ):
+                raise ValueError(
+                    "This versioned total-flux curve lacks an applied Q or H "
+                    "divisor and cannot be reduced to a CTR structure factor."
+                )
+            C_norm = np.ones_like(curves["croibg"], dtype=np.float64)
+            normalization_applied = tuple(
+                correction_record.normalization_components
+            )
+        else:
+            C_norm, normalization_applied = self._rocking_normalization(
+                aux, axis.size
+            )
+            C_norm = np.broadcast_to(C_norm, np.shape(curves["croibg"])).copy()
 
         # Only F2_hkl is divided by these, so asking for them with the
         # Lorentz switch off would warn about a detector nothing needs.
@@ -1833,7 +1864,7 @@ def integrate(self):
             # New extractions carry their polarization-only CTR branch
             # directly. The separately estimated solid-angle compensation is
             # retained only for legacy database files that lack that branch.
-            if "ctr_croibg" not in curves:
+            if "ctr_croibg" not in curves and not versioned_total_flux:
                 solid_angle_mean, solid_angle_compensated = (
                     self._rocking_solid_angle_mean(
                         detector, scangroup, cnters, x, y
@@ -1857,7 +1888,7 @@ def integrate(self):
             roi_info,
             aux,
             self.lorentzButton.isChecked(),
-            self.footprintButton.isChecked(),
+            self.footprintButton.isChecked() and not versioned_total_flux,
             C_Lor=C_Lor,
             C_rod=C_rod,
             C_flux_on_sample=C_flux_on_sample,
@@ -1890,6 +1921,31 @@ def integrate(self):
         if self.lorentzButton.isChecked():
             F2_hkl = result["F2_hkl"]
             F2_hkl_errors = result["F2_hkl_errors"]
+            if versioned_total_flux and correction_record.scale_convention.startswith(
+                "total_flux_calibrated"
+            ):
+                provenance = correction_record.profile_provenance
+                try:
+                    prefactor = measurement_corrections.total_flux_prefactor(
+                        float(provenance["wavelength_angstrom"]),
+                        float(provenance["unitcell_area_angstrom2"]),
+                    )
+                    efficiency = float(
+                        provenance.get("detector_efficiency_assumed", 1.0)
+                    )
+                    transmission = float(
+                        provenance.get("external_transmission_assumed", 1.0)
+                    )
+                    absolute_divisor = prefactor * efficiency * transmission
+                    if not np.isfinite(absolute_divisor) or absolute_divisor <= 0:
+                        raise ValueError("absolute divisor is not positive")
+                except (KeyError, TypeError, ValueError) as error:
+                    raise ValueError(
+                        "The calibrated total-flux curve lacks valid wavelength, "
+                        "surface unit-cell area, or detector-response provenance."
+                    ) from error
+                F2_hkl = F2_hkl / absolute_divisor
+                F2_hkl_errors = F2_hkl_errors / absolute_divisor
 
         int_data["@NX_class"] = "NXdetector"
 
@@ -1997,12 +2053,28 @@ def integrate(self):
                 "@acceptance_applied": bool(acceptance_applied),
                 "@solid_angle_compensated": bool(solid_angle_compensated),
                 "@photon_curve_used": "ctr_croibg" in curves,
-                "@active_area_applied": bool(self.footprintButton.isChecked()),
+                "@active_area_applied": bool(
+                    curves["illumination_action"]
+                    in ("applied", "replaced", "applied_here")
+                    if versioned_total_flux
+                    else self.footprintButton.isChecked()
+                ),
             }
+            if versioned_total_flux:
+                reduction.update({
+                    "@curve_algorithm": correction_record.algorithm,
+                    "@scale_convention": correction_record.scale_convention,
+                    "@illumination_action": curves["illumination_action"],
+                    "@illumination_convention": (
+                        curves["illumination_convention"] or "none"
+                    ),
+                    "@normalization_source": "stored_frame_divisor",
+                    "@illumination_source": "stored_frame_divisor",
+                })
             if detector_acceptance is not None:
                 reduction["detector_acceptance"] = detector_acceptance
                 reduction["@detector_acceptance_unit"] = "rad"
-            if self.footprintButton.isChecked():
+            if self.footprintButton.isChecked() and not versioned_total_flux:
                 reduction["sample_size"] = L
                 reduction["@sample_size_unit"] = "m"
             measurement[availname1]["reduction"] = reduction
@@ -2119,20 +2191,75 @@ def _legacy_rocking_curve_group(h5_obj):
         return h5_obj["rois"]
 
     def get_ro_curve(self, idx):
-        name = self._currentRoInfo["name"]
-        h5_obj = self.database.nxfile[name]
-        cnters = self._legacy_rocking_curve_group(h5_obj)
+        """Return one rocking curve under its stored correction contract."""
+        curves = self.get_all_ro_curves()
         curve = {
-            "axisname": self._currentRoInfo["axisname"],
-            "axis": self._currentRoInfo["axis"],
-            "croibg": cnters["croibg"][idx][()],
-            "croibg_errors": cnters["croibg_errors"][idx][()],
+            "axisname": curves["axisname"],
+            "axis": curves["axis"],
+            "croibg": curves["croibg"][idx],
+            "croibg_errors": curves["croibg_errors"][idx],
         }
         return curve
 
     def get_all_ro_curves(self):
+        """Return rocking curves without silently changing their scale.
+
+        New total-flux records are reconstructed from the immutable base
+        curve and the exact stored Q/H divisors. Legacy records retain the
+        historical ``rois`` path and are normalized later by
+        :meth:`_rocking_normalization`.
+        """
         name = self._currentRoInfo["name"]
         h5_obj = self.database.nxfile[name]
+        if CURVE_CORRECTIONS_GROUP in h5_obj:
+            record_group = h5_obj[CURVE_CORRECTIONS_GROUP]
+            try:
+                record_dict = h5todict(
+                    self.database.nxfile,
+                    record_group.name,
+                )
+                record_dict["@orgui_schema_version"] = record_group.attrs.get(
+                    "orgui_schema_version", 0
+                )
+                record_dict["@orgui_curve_contract"] = record_group.attrs.get(
+                    "orgui_curve_contract", ""
+                )
+                record = curve_correction_record_from_nxdict(
+                    record_dict
+                )
+            except ValueError:
+                # Let the legacy gate distinguish supported legacy records
+                # from unknown normalized contracts and produce its targeted
+                # error instead of guessing which numbers the curve contains.
+                record = None
+            if record is not None and record.algorithm.startswith(
+                "framewise_ctr_total_flux_"
+            ):
+                curve, errors, action, convention = corrected_curve_from_record(
+                    record,
+                    footprint_action=getattr(
+                        self, "footprint_action", FOOTPRINT_KEEP
+                    ),
+                    replacement_illumination=getattr(
+                        self, "replacement_illumination", None
+                    ),
+                    replacement_convention=getattr(
+                        self, "replacement_illumination_convention", None
+                    ),
+                    allow_convention_change=bool(
+                        getattr(self, "allow_illumination_convention_change", False)
+                    ),
+                )
+                return {
+                    "axisname": self._currentRoInfo["axisname"],
+                    "axis": self._currentRoInfo["axis"],
+                    "croibg": curve,
+                    "croibg_errors": errors,
+                    "correction_record": record,
+                    "illumination_action": action,
+                    "illumination_convention": convention,
+                }
+
         cnters = self._legacy_rocking_curve_group(h5_obj)
         curve = {
             "axisname": self._currentRoInfo["axisname"],
diff --git a/orgui/app/test/test_config_data.py b/orgui/app/test/test_config_data.py
index 58e1040..1d60f5a 100644
--- a/orgui/app/test/test_config_data.py
+++ b/orgui/app/test/test_config_data.py
@@ -425,6 +425,47 @@ def test_apply_to_gui_sets_reconstruction_normalization_attributes():
     assert gui.reconstruction_monitor_corrections == ("mondio",)
 
 
+def test_total_flux_state_survives_before_its_widgets_exist():
+    """Stage-5 programmatic settings round-trip through the GUI snapshot."""
+    config = _make_config()
+    config.corrections = CorrectionState(
+        total_incident_flux=2.5e10,
+        total_flux_calibrated=True,
+        primary_monitor="ic2",
+        primary_monitor_kind="rate",
+        primary_monitor_unit="count/s",
+        monitor_reference_reading=4200.0,
+        horizontal_interception="fraction",
+        horizontal_intercepted_fraction=0.85,
+    )
+    gui = SimpleNamespace(
+        ubcalc=SimpleNamespace(
+            detectorCal=config.detector,
+            crystal=config.unit_cell,
+            ubCal=config.ub_calculator,
+            mu=config.mu,
+            chi=config.chi,
+            phi=config.phi,
+            n=config.refraction_index,
+        ),
+        scanSelector=SimpleNamespace(
+            get_integration_options=lambda: {},
+            set_integration_options=lambda options: None,
+        ),
+    )
+
+    config.apply_to_gui(gui)
+    captured = ConfigData.from_gui(gui).corrections
+
+    assert captured.total_incident_flux == pytest.approx(2.5e10)
+    assert captured.total_flux_calibrated is True
+    assert captured.primary_monitor == "ic2"
+    assert captured.primary_monitor_kind == "rate"
+    assert captured.monitor_reference_reading == pytest.approx(4200.0)
+    assert captured.horizontal_interception == "fraction"
+    assert captured.horizontal_intercepted_fraction == pytest.approx(0.85)
+
+
 def test_apply_to_gui_requests_a_replot(qapp):
     """Loading a config must refresh HKL-dependent plot elements too.
 
diff --git a/orgui/app/test/test_frame_correction_policy.py b/orgui/app/test/test_frame_correction_policy.py
new file mode 100644
index 0000000..4999420
--- /dev/null
+++ b/orgui/app/test/test_frame_correction_policy.py
@@ -0,0 +1,214 @@
+"""Regression tests for the versioned framewise CTR correction policy."""
+
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+from orgui.app import integration_corrections as ic
+from orgui.app.config_data import CorrectionState, CurveCorrectionRecord
+from orgui.datautils.xrayutils.corrections import measurement
+from orgui.datautils.xrayutils.corrections.beamprofile import top_hat_profile
+
+
+def _state(**updates):
+    values = {
+        "total_incident_flux": 2.0e10,
+        "total_flux_calibrated": True,
+        "primary_monitor": "ic2",
+        "primary_monitor_kind": "rate",
+        "primary_monitor_unit": "count/s",
+        "monitor_reference_reading": 100.0,
+        "horizontal_interception": "full",
+    }
+    values.update(updates)
+    return CorrectionState(**values)
+
+
+def test_calibrated_rate_monitor_counts_exposure_exactly_once():
+    """A rate-like ion chamber is converted to frame photon fluence."""
+    exposure = np.array([0.5, 1.0, 2.0])
+    monitor = np.array([50.0, 100.0, 200.0])
+    scan = SimpleNamespace(exposure_time=exposure, ic2=monitor)
+
+    policy = ic.frame_correction_policy(
+        scan,
+        _state(),
+        3,
+        use_normalization=True,
+        use_illumination=False,
+    )
+
+    expected = 2.0e10 * exposure * monitor / 100.0
+    np.testing.assert_allclose(policy.normalization_divisor, expected)
+    assert policy.normalization_unit == "photons"
+    assert policy.normalization_components == (
+        "exposure",
+        "primary_monitor:ic2:rate",
+    )
+
+
+def test_integrated_monitor_does_not_multiply_frame_exposure_again():
+    """An integrated monitor already contains the acquisition duration."""
+    scan = SimpleNamespace(
+        exposure_time=np.array([0.5, 1.0, 2.0]),
+        ic2=np.array([50.0, 100.0, 200.0]),
+    )
+    state = _state(
+        primary_monitor_kind="integrated",
+        monitor_reference_exposure_s=0.25,
+    )
+
+    policy = ic.frame_correction_policy(
+        scan,
+        state,
+        3,
+        use_normalization=True,
+        use_illumination=False,
+    )
+
+    expected = 2.0e10 * 0.25 * scan.ic2 / 100.0
+    np.testing.assert_allclose(policy.normalization_divisor, expected)
+    assert policy.normalization_components == (
+        "primary_monitor:ic2:integrated",
+    )
+
+
+def test_total_flux_illumination_requires_horizontal_provenance():
+    """The unmeasured beam direction cannot silently be called complete."""
+    scan = SimpleNamespace(exposure_time=np.ones(3), ic2=np.ones(3) * 100.0)
+    with pytest.raises(ValueError, match="horizontal_interception"):
+        ic.frame_correction_policy(
+            scan,
+            _state(horizontal_interception=None),
+            3,
+            use_normalization=True,
+            use_illumination=True,
+            alpha=np.deg2rad([0.2, 0.5, 1.0]),
+            beam_profile=top_hat_profile(300e-6),
+            sample_length=5e-3,
+        )
+
+
+def test_legacy_policy_preserves_counter_product_and_active_area():
+    """Absent version-3 fields retain the established numerical convention."""
+    exposure = np.array([0.5, 1.0, 2.0])
+    monitor = np.array([10.0, 20.0, 40.0])
+    alpha = np.deg2rad([0.2, 0.5, 1.0])
+    profile = top_hat_profile(300e-6)
+    scan = SimpleNamespace(exposure_time=exposure, mon=monitor)
+    state = CorrectionState(
+        normalize_exposure=True, monitor_corrections=("mon",)
+    )
+
+    policy = ic.frame_correction_policy(
+        scan,
+        state,
+        3,
+        use_normalization=True,
+        use_illumination=True,
+        alpha=alpha,
+        beam_profile=profile,
+        sample_length=5e-3,
+    )
+
+    vertical, area = profile.corrections(alpha, 5e-3)
+    np.testing.assert_allclose(policy.normalization_divisor, exposure * monitor)
+    np.testing.assert_allclose(policy.vertical_intercepted_fraction, vertical)
+    np.testing.assert_allclose(policy.illumination_divisor, area)
+    assert policy.new_contract is False
+    assert policy.scale_convention == "legacy_relative"
+
+
+def _record(**updates):
+    values = {
+        "algorithm": "framewise_ctr_total_flux_v1",
+        "output_quantity": "rocking_ctr_photon_curve",
+        "scale_convention": "total_flux_calibrated",
+        "normalization_status": "applied",
+        "normalization_divisor": np.array([2.0, 4.0]),
+        "illumination_status": "applied",
+        "illumination_divisor": np.array([0.5, 0.25]),
+        "illumination_convention": "total_flux_H",
+        "base_croibg": np.array([80.0, 96.0]),
+        "base_croibg_variance": np.array([16.0, 36.0]),
+    }
+    values.update(updates)
+    return CurveCorrectionRecord(**values)
+
+
+def test_footprint_actions_always_restart_from_the_stored_base():
+    """Keep, remove, and replace never compound a previous transformation."""
+    record = _record()
+
+    kept, kept_errors, status, convention = ic.corrected_curve_from_record(record)
+    removed, removed_errors, removed_status, _ = ic.corrected_curve_from_record(
+        record, footprint_action=ic.FOOTPRINT_REMOVE
+    )
+    replaced, replaced_errors, replaced_status, _ = ic.corrected_curve_from_record(
+        record,
+        footprint_action=ic.FOOTPRINT_APPLY,
+        replacement_illumination=np.array([0.25, 0.5]),
+        replacement_convention="total_flux_H",
+    )
+
+    np.testing.assert_allclose(kept, [80.0, 96.0] / np.array([2.0, 4.0]) / [0.5, 0.25])
+    np.testing.assert_allclose(removed, [80.0, 96.0] / np.array([2.0, 4.0]))
+    np.testing.assert_allclose(
+        replaced, [80.0, 96.0] / np.array([2.0, 4.0]) / [0.25, 0.5]
+    )
+    np.testing.assert_allclose(
+        kept_errors, [4.0, 6.0] / np.array([2.0, 4.0]) / [0.5, 0.25]
+    )
+    np.testing.assert_allclose(removed_errors, [4.0, 6.0] / np.array([2.0, 4.0]))
+    np.testing.assert_allclose(
+        replaced_errors, [4.0, 6.0] / np.array([2.0, 4.0]) / [0.25, 0.5]
+    )
+    assert (status, convention) == ("applied", "total_flux_H")
+    assert removed_status == "removed"
+    assert replaced_status == "replaced"
+
+
+def test_convention_change_and_unknown_provenance_are_explicit_errors():
+    """Unsafe migrations are never inferred from a curve's numeric values."""
+    with pytest.raises(ValueError, match="changing illumination convention"):
+        ic.corrected_curve_from_record(
+            _record(),
+            footprint_action=ic.FOOTPRINT_APPLY,
+            replacement_illumination=np.ones(2),
+            replacement_convention="legacy_C_illum_area",
+        )
+
+    with pytest.raises(ValueError, match="normalization provenance"):
+        ic.corrected_curve_from_record(_record(normalization_status="unknown"))
+
+
+def test_calibrated_stationary_structure_factor_uses_total_flux_prefactor():
+    """The total-flux scale omits the legacy flux-density/area product."""
+    alpha = np.deg2rad(np.array([0.5]))
+    delta = np.deg2rad(np.array([20.0]))
+    gamma = np.deg2rad(np.array([3.0]))
+    factors = ic.stationary_correction_factors(
+        alpha, delta, gamma, use_lorentz=True
+    )
+    policy = ic.FrameCorrectionPolicy(
+        new_contract=True,
+        scale_convention="total_flux_calibrated",
+        normalization_status="applied",
+        illumination_status="applied",
+        calibrated=True,
+    )
+
+    result, errors = ic.structure_factor_from_policy(
+        np.array([3.0]),
+        np.array([0.3]),
+        factors,
+        policy,
+        wavelength=1.0,
+        unitcell_area=16.0,
+    )
+
+    prefactor = measurement.total_flux_prefactor(1.0, 16.0)
+    expected = 3.0 / factors["C_Lorentz"] / prefactor
+    np.testing.assert_allclose(result, expected)
+    np.testing.assert_allclose(errors / result, 0.1)
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index 4716773..7feb928 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -20,7 +20,13 @@
 import h5py
 import numpy as np
 import pytest
+from silx.io.dictdump import dicttonx
 
+from orgui.app.config_data import (
+    CURVE_CORRECTIONS_GROUP,
+    CurveCorrectionRecord,
+    curve_correction_record_to_nxdict,
+)
 from orgui.app.peak1Dintegr import (
     RockingPeakIntegrator,
     _compute_rocking_integration,
@@ -798,6 +804,60 @@ def test_versioned_normalized_curve_is_not_consumed_as_legacy(tmp_path):
             RockingPeakIntegrator._legacy_rocking_curve_group(scan)
 
 
+def test_versioned_total_flux_curve_uses_stored_divisors_once(tmp_path):
+    """The supported reducer dispatch ignores the legacy sibling values."""
+    base = np.array([[80.0, 96.0, 120.0], [40.0, 48.0, 60.0]])
+    variance = np.array([[16.0, 36.0, 64.0], [4.0, 9.0, 16.0]])
+    q = np.array([2.0, 4.0, 5.0])
+    h = np.array([0.5, 0.25, 1.0])
+    record = CurveCorrectionRecord(
+        algorithm="framewise_ctr_total_flux_v1",
+        output_quantity="rocking_ctr_photon_curve",
+        scale_convention="total_flux_calibrated",
+        normalization_status="applied",
+        normalization_divisor=q,
+        normalization_unit="photons",
+        illumination_status="applied",
+        illumination_divisor=h,
+        illumination_convention="total_flux_H",
+        base_croibg=base,
+        base_croibg_variance=variance,
+    )
+    path = tmp_path / "total_flux_curve.h5"
+    dicttonx(
+        {
+            "scan": {
+                "@NX_class": "NXcollection",
+                "rois": {
+                    "@NX_class": "NXcollection",
+                    "croibg": np.full_like(base, -999.0),
+                    "croibg_errors": np.ones_like(base),
+                },
+                CURVE_CORRECTIONS_GROUP: curve_correction_record_to_nxdict(
+                    record
+                ),
+            }
+        },
+        path,
+    )
+
+    with h5py.File(path, "r") as handle:
+        integrator = SimpleNamespace(
+            _currentRoInfo={
+                "name": "/scan",
+                "axisname": "mu",
+                "axis": np.arange(3.0),
+            },
+            database=SimpleNamespace(nxfile=handle),
+        )
+        curves = RockingPeakIntegrator.get_all_ro_curves(integrator)
+
+    np.testing.assert_allclose(curves["croibg"], base / q / h)
+    np.testing.assert_allclose(curves["croibg_errors"], np.sqrt(variance) / q / h)
+    assert curves["correction_record"].algorithm == record.algorithm
+    assert curves["illumination_action"] == "applied"
+
+
 @pytest.mark.parametrize("applied_at_extraction", [True, False])
 def test_the_typed_corrections_group_is_read_back(applied_at_extraction):
     """The F6 compensation must survive the layout it is stored in.

From 9b772f4b9724f01876c17cf04d4b4d5f69d9d844 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Thu, 17 Sep 2026 11:10:18 -0400
Subject: [PATCH 26/33] feat(phys): expose CTR correction state in UI

---
 CHANGELOG.md                                  |  18 +-
 orgui/app/QScanSelector.py                    | 491 ++++++++++++++---
 orgui/app/config_data.py                      |  12 +
 orgui/app/peak1Dintegr.py                     | 510 ++++++++++++++++--
 .../test_integration_corrections_dialog.py    |  38 ++
 .../test/test_integration_options_dialog.py   | 149 ++++-
 orgui/app/test/test_peak1Dintegr.py           |  55 ++
 7 files changed, 1163 insertions(+), 110 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c768609..a572b78 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,20 @@ This is the changelog for the software orGUI, written by Timo Fuchs
 
 Scientific and analysis additions:
 
+- **CTR correction controls now state what is saved and what the next
+  operation will do.** The integration dialog separates detector signal,
+  incident beam and CTR result settings; new sessions use an explicitly
+  relative total-flux convention, while calibrated photon flux, one
+  rate-like or integrated primary monitor, its calibration reference and the
+  effective normalization formula are shown with units. Legacy flux density
+  and multi-monitor products remain labeled and are not reinterpreted.
+  Horizontal interception must be selected as full or as a known fraction;
+  unresolved imported settings stay ``Not specified``. The rocking reducer
+  shows the loaded curve's saved normalization/footprint provenance separately
+  from the next reduction and replaces the footprint checkbox with safe
+  keep/apply/remove actions. Unknown legacy provenance disables replacement
+  and removal and directs the user to re-extract rather than guessing.
+
 - **The numerical correction core now has an explicit total-incident-flux
   convention.** New pure APIs calculate calibrated photons per frame from a
   constant flux or an explicitly rate-like/integrated monitor, distinguish the
@@ -16,8 +30,8 @@ Scientific and analysis additions:
   grazing-incidence limit, and horizontal interception must be stated
   separately because a vertical profile cannot infer it. This stage adds the
   unit-audited numerical path; the extraction/reduction wiring described
-  below activates it only for explicit version-3 settings. The UI and legacy
-  flux-density APIs remain unchanged until the later UI stage.
+  below activates it only for explicit version-3 settings. Legacy
+  flux-density APIs retain their original units and meaning.
 
 - **Stationary and rocking CTR integrations now share one framewise total-flux
   policy.** An explicitly configured primary monitor is classified as a rate
diff --git a/orgui/app/QScanSelector.py b/orgui/app/QScanSelector.py
index 13ec7a8..117d8cf 100644
--- a/orgui/app/QScanSelector.py
+++ b/orgui/app/QScanSelector.py
@@ -49,6 +49,7 @@
 from ..backend import backends, scans
 from . import qutils
 from . import integration_corrections
+from .config_data import CorrectionState
 from ._option_keys import LegacyKeyDict, canonical_options
 from .QReflectionSelector import QReflectionAnglesDialog
 from .QHKLDialog import HKLDialog
@@ -746,11 +747,15 @@ def __init__(self, parentmainwindow, parent=None):
         # attributes of this widget so that get_integration_options() and the
         # integration code keep reading them from the same place.
         self.useMaskBox = qt.QCheckBox("Use pixel mask")
-        self.useSolidAngleBox = qt.QCheckBox("Solid angle correction")
+        self.useSolidAngleBox = qt.QCheckBox(
+            "Solid-angle normalization (intensity output only)"
+        )
         self.usePolarizationBox = qt.QCheckBox("Polarization correction")
-        self.useLorentzBox = qt.QCheckBox("Lorentz correction")
-        self.useFootprintBox = qt.QCheckBox("Beam footprint")
-        self.useNormalizationBox = qt.QCheckBox("Normalize integrated intensities")
+        self.useLorentzBox = qt.QCheckBox("Calculate CTR structure factor")
+        self.useFootprintBox = qt.QCheckBox("Correct beam/sample overlap")
+        self.useNormalizationBox = qt.QCheckBox(
+            "Normalize intensity frame by frame"
+        )
 
         # Parent this top-level dialog to the stable application window, not
         # to this widget inside a dock.  Dock tab/visibility changes can
@@ -1017,22 +1022,22 @@ def get_integration_options(self):
         ("usePolarizationBox", "POL", "#6c71c4", "Polarization correction"),
         (
             "useLorentzBox",
-            "LOR",
+            "CTR",
             "#2aa198",
-            "Lorentz correction and F2_hkl; rocking scans also include rod "
-            "interception",
+            "Calculate CTR structure factor; rocking scans also include rod "
+            "interception and angular acceptance",
         ),
         (
             "useFootprintBox",
             "FOOT",
             "#859900",
-            "Numerical active surface area from the beam profile",
+            "Beam/sample overlap from stored vertical and horizontal inputs",
         ),
         (
             "useNormalizationBox",
             "NORM",
             "#d33682",
-            "Exposure time and monitor normalization",
+            "Framewise incident-fluence normalization",
         ),
     )
 
@@ -1999,10 +2004,13 @@ def __init__(self, selector, parent=None):
         # Shared with the rocking-scan integration; see
         # RockingPeakIntegrator.useSharedFootprintOptions.
         self.footprintOptions = None
+        self._standaloneCorrectionState = CorrectionState(
+            total_flux_calibrated=False
+        )
 
         layout = qt.QVBoxLayout(self)
 
-        detector = qt.QGroupBox("Detector corrections")
+        detector = qt.QGroupBox("Detector signal")
         detectorLayout = qt.QVBoxLayout()
         detectorLayout.addWidget(selector.useMaskBox)
         self.maskToolBtn = qt.QPushButton("Open mask tool ...")
@@ -2028,73 +2036,142 @@ def __init__(self, selector, parent=None):
         )
         detectorLayout.addWidget(selector.useSolidAngleBox)
         detectorLayout.addWidget(selector.usePolarizationBox)
+        selector.useSolidAngleBox.setText(
+            "Solid-angle normalization (intensity output only)"
+        )
         detector.setLayout(detectorLayout)
         layout.addWidget(detector)
 
-        geometry = qt.QGroupBox("Geometrical corrections")
-        geometryLayout = qt.QVBoxLayout()
-        geometryLayout.addWidget(selector.useLorentzBox)
-        selector.useLorentzBox.setToolTip(
-            "Divide out the Lorentz factor and store the structure factor "
-            "F2_hkl. Rocking scans also divide out rod interception; "
-            "stationary scans do not. The z-axis Lorentz factor is "
-            "1/sin(gamma) for a stationary scan, "
-            "1/(sin(delta) cos(alpha) cos(gamma)) for a rocking scan and "
-            "1/sin(2 alpha) for a reflectivity rocking scan."
-        )
-        self.lorentzInfo = qt.QLabel(
-            "<i>Stationary scans use the stationary-mode factor "
-            "1/sin(&gamma;) without rod interception; rocking scans use "
-            "their own Lorentz factor and cos(&gamma;).</i>"
+        incident = qt.QGroupBox("Incident beam")
+        incidentLayout = qt.QVBoxLayout()
+        incidentLayout.addWidget(selector.useNormalizationBox)
+        selector.useNormalizationBox.setText("Normalize intensity frame by frame")
+        selector.useNormalizationBox.setToolTip(
+            "Apply the selected exposure/primary-monitor convention to each "
+            "frame. The reciprocal-space reconstruction keeps its separate "
+            "legacy monitor-product settings below."
         )
-        self.lorentzInfo.setWordWrap(True)
-        # Wrapped labels report a one-line height to a layout that has not
-        # laid them out yet, which clips them in a freshly sized dialog.
-        self.lorentzInfo.setMinimumHeight(self.lorentzInfo.fontMetrics().height() * 3)
-        geometryLayout.addWidget(self.lorentzInfo)
 
-        geometryLayout.addWidget(selector.useFootprintBox)
+        scaleRow = qt.QHBoxLayout()
+        scaleRow.addWidget(qt.QLabel("Flux convention:"))
+        self.scaleModeCombo = qt.QComboBox()
+        self.scaleModeCombo.addItem("Total flux — relative scale", "relative")
+        self.scaleModeCombo.addItem("Total flux — calibrated", "calibrated")
+        self.scaleModeCombo.addItem("Legacy density/area", "legacy")
+        self.scaleModeCombo.setToolTip(
+            "New sessions use total incident flux. Legacy density/area is "
+            "retained only for imported configurations and is never converted "
+            "without a known horizontal beam profile."
+        )
+        scaleRow.addWidget(self.scaleModeCombo, 1)
+        incidentLayout.addLayout(scaleRow)
+
+        fluxRow = qt.QHBoxLayout()
+        fluxRow.addWidget(qt.QLabel("Total incident beam flux:"))
+        self.totalFluxEdit = qt.QLineEdit()
+        self.totalFluxEdit.setPlaceholderText("Not calibrated")
+        fluxValidator = qt.QDoubleValidator(0.0, 1e300, 12, self)
+        fluxValidator.setNotation(qt.QDoubleValidator.ScientificNotation)
+        self.totalFluxEdit.setValidator(fluxValidator)
+        self.totalFluxEdit.setToolTip(
+            "Full beam at the sample position before clipping, after upstream "
+            "attenuation, in photons/s. Required only for calibrated scale."
+        )
+        fluxRow.addWidget(self.totalFluxEdit, 1)
+        fluxRow.addWidget(qt.QLabel("photons/s"))
+        incidentLayout.addLayout(fluxRow)
+
+        monitorRow = qt.QGridLayout()
+        monitorRow.addWidget(qt.QLabel("Primary monitor:"), 0, 0)
+        self.primaryMonitorCombo = qt.QComboBox()
+        self.primaryMonitorCombo.setMinimumContentsLength(12)
+        monitorRow.addWidget(self.primaryMonitorCombo, 0, 1)
+        monitorRow.addWidget(qt.QLabel("Monitor records:"), 1, 0)
+        self.monitorKindCombo = qt.QComboBox()
+        self.monitorKindCombo.addItem("Rate", "rate")
+        self.monitorKindCombo.addItem("Integrated per frame", "integrated")
+        monitorRow.addWidget(self.monitorKindCombo, 1, 1)
+        monitorRow.addWidget(qt.QLabel("Counter unit:"), 2, 0)
+        self.monitorUnitEdit = qt.QLineEdit()
+        self.monitorUnitEdit.setPlaceholderText("Not reported")
+        monitorRow.addWidget(self.monitorUnitEdit, 2, 1)
+        monitorRow.addWidget(qt.QLabel("Reference reading:"), 3, 0)
+        self.referenceMonitorEdit = qt.QLineEdit()
+        self.referenceMonitorEdit.setValidator(fluxValidator)
+        monitorRow.addWidget(self.referenceMonitorEdit, 3, 1)
+        self.referenceExposureLabel = qt.QLabel("Reference exposure:")
+        monitorRow.addWidget(self.referenceExposureLabel, 4, 0)
+        self.referenceExposureEdit = qt.QLineEdit()
+        self.referenceExposureEdit.setValidator(fluxValidator)
+        self.referenceExposureEdit.setPlaceholderText("seconds")
+        monitorRow.addWidget(self.referenceExposureEdit, 4, 1)
+        incidentLayout.addLayout(monitorRow)
+
+        self.normalizationFormula = qt.QLabel()
+        self.normalizationFormula.setWordWrap(True)
+        incidentLayout.addWidget(self.normalizationFormula)
+
+        incidentLayout.addWidget(selector.useFootprintBox)
+        selector.useFootprintBox.setText("Correct beam/sample overlap")
         selector.useFootprintBox.setToolTip(
-            "Correct the numerical active surface area from the vertical "
-            "beam profile. Its overlap integral already includes beam "
-            "overspill and is applied only once."
+            "Apply the vertical profile and explicitly stated horizontal "
+            "interception once per frame."
+        )
+        self.footprintBtn = qt.QPushButton(
+            "Beam profile, sample size and horizontal interception ..."
         )
-        self.footprintBtn = qt.QPushButton("Beam profile and sample size ...")
         self.footprintBtn.clicked.connect(self._openFootprintOptions)
-        geometryLayout.addWidget(self.footprintBtn)
-        geometry.setLayout(geometryLayout)
-        layout.addWidget(geometry)
+        incidentLayout.addWidget(self.footprintBtn)
 
-        normalization = qt.QGroupBox("Exposure and monitor normalization")
-        normalizationLayout = qt.QVBoxLayout()
-        normalizationLayout.addWidget(selector.useNormalizationBox)
-        selector.useNormalizationBox.setToolTip(
-            "Divide each image by its exposure time and by the monitor "
-            "counters below, the same normalization the reciprocal-space "
-            "reconstruction applies."
-        )
+        legacy = qt.QFrame()
+        legacy.setFrameShape(qt.QFrame.StyledPanel)
+        legacyLayout = qt.QVBoxLayout()
+        legacyHeading = qt.QLabel("<b>Legacy / reconstruction normalization</b>")
+        legacyLayout.addWidget(legacyHeading)
         self.normalizeExposureBox = qt.QCheckBox("Normalize by exposure time")
         self.normalizeExposureBox.setChecked(True)
         self.normalizeExposureBox.toggled.connect(self._onNormalizationChanged)
-        normalizationLayout.addWidget(self.normalizeExposureBox)
-
-        monitorRow = qt.QHBoxLayout()
-        monitorRow.addWidget(qt.QLabel("Monitor counters:"))
+        legacyLayout.addWidget(self.normalizeExposureBox)
+        legacyMonitorRow = qt.QHBoxLayout()
+        legacyMonitorRow.addWidget(qt.QLabel("Monitor product:"))
         self.monitorEdit = qt.QLineEdit()
-        self.monitorEdit.setPlaceholderText("Optional scan counters, comma-separated")
+        self.monitorEdit.setPlaceholderText("Optional counters, comma-separated")
         self.monitorEdit.setToolTip(
-            "Counters applied as divisive normalizations. Shared with the "
-            "reciprocal-space reconstruction settings."
+            "Preserved multi-counter convention used by reconstruction and "
+            "legacy rocking reductions. It is not reinterpreted as the new "
+            "primary monitor."
         )
         self.monitorEdit.editingFinished.connect(self._onNormalizationChanged)
-        monitorRow.addWidget(self.monitorEdit)
-        normalizationLayout.addLayout(monitorRow)
-
+        legacyMonitorRow.addWidget(self.monitorEdit)
+        legacyLayout.addLayout(legacyMonitorRow)
         self.monitorInfo = qt.QLabel("")
         self.monitorInfo.setWordWrap(True)
-        normalizationLayout.addWidget(self.monitorInfo)
-        normalization.setLayout(normalizationLayout)
-        layout.addWidget(normalization)
+        legacyLayout.addWidget(self.monitorInfo)
+        legacy.setLayout(legacyLayout)
+        incidentLayout.addWidget(legacy)
+        incident.setLayout(incidentLayout)
+        layout.addWidget(incident)
+
+        ctr = qt.QGroupBox("CTR result")
+        ctrLayout = qt.QVBoxLayout()
+        selector.useLorentzBox.setText("Calculate CTR structure factor")
+        ctrLayout.addWidget(selector.useLorentzBox)
+        selector.useLorentzBox.setToolTip(
+            "Divide out the Lorentz factor and store the structure factor "
+            "F2_hkl. Rocking scans also divide out rod interception; "
+            "stationary scans do not. The z-axis Lorentz factor is "
+            "1/sin(gamma) for a stationary scan, "
+            "1/(sin(delta) cos(alpha) cos(gamma)) for a rocking scan and "
+            "1/sin(2 alpha) for a reflectivity rocking scan."
+        )
+        self.measurementModeInfo = qt.QLabel()
+        self.measurementModeInfo.setWordWrap(True)
+        ctrLayout.addWidget(self.measurementModeInfo)
+        self.scaleStatus = qt.QLabel()
+        self.scaleStatus.setWordWrap(True)
+        ctrLayout.addWidget(self.scaleStatus)
+        ctr.setLayout(ctrLayout)
+        layout.addWidget(ctr)
 
         self.reconstructionBtn = qt.QPushButton("Reciprocal-space reconstruction ...")
         self.reconstructionBtn.setToolTip(
@@ -2108,6 +2185,23 @@ def __init__(self, selector, parent=None):
         buttons.rejected.connect(self.reject)
         layout.addWidget(buttons)
 
+        for signal in (
+            self.scaleModeCombo.currentIndexChanged,
+            self.totalFluxEdit.editingFinished,
+            self.primaryMonitorCombo.currentIndexChanged,
+            self.monitorKindCombo.currentIndexChanged,
+            self.monitorUnitEdit.editingFinished,
+            self.referenceMonitorEdit.editingFinished,
+            self.referenceExposureEdit.editingFinished,
+            selector.useNormalizationBox.toggled,
+            selector.useFootprintBox.toggled,
+            selector.useLorentzBox.toggled,
+        ):
+            signal.connect(self._onTotalFluxChanged)
+        if hasattr(selector, "scanstab"):
+            selector.scanstab.currentChanged.connect(self._updateCtrStatus)
+        self.refresh()
+
     def reject(self):
         """Hide this persistent non-modal dialog.
 
@@ -2126,9 +2220,40 @@ def _mainWindow(self):
         """Return the orGUI main window, or ``None`` outside the app."""
         return getattr(self._selector, "parentmainwindow", None)
 
+    def _correctionState(self):
+        """Return the live total-flux state, creating a new-session default."""
+        main = self._mainWindow()
+        if main is None:
+            return self._standaloneCorrectionState
+        state = getattr(main, "ctr_correction_state", None)
+        if state is None:
+            state = CorrectionState(total_flux_calibrated=False)
+            main.ctr_correction_state = state
+        return state
+
+    @staticmethod
+    def _optionalFloat(editor):
+        """Parse an optional scientific-notation line editor."""
+        text = editor.text().strip()
+        if not text:
+            return None
+        try:
+            return float(text)
+        except ValueError:
+            # A connected widget can briefly contain an intermediate value
+            # such as ``1e`` while another control emits. Treat that as an
+            # incomplete required input until editing is finished.
+            return None
+
+    @staticmethod
+    def _setOptionalFloat(editor, value):
+        """Show an optional float compactly in scientific notation."""
+        editor.setText("" if value is None else f"{float(value):.8g}")
+
     def refresh(self):
         """Reload the settings shared with other parts of the application."""
         main = self._mainWindow()
+        state = self._correctionState()
         if main is not None:
             with blockSignals([self.normalizeExposureBox, self.monitorEdit]):
                 self.normalizeExposureBox.setChecked(
@@ -2138,6 +2263,70 @@ def refresh(self):
                     ", ".join(getattr(main, "reconstruction_monitor_corrections", ()))
                 )
         self._updateMonitorInfo()
+        available = self._availableMonitorNames()
+        selected = state.primary_monitor
+        if selected and selected not in available:
+            available.append(selected)
+        widgets = [
+            self.scaleModeCombo,
+            self.primaryMonitorCombo,
+            self.monitorKindCombo,
+            self.monitorUnitEdit,
+            self.totalFluxEdit,
+            self.referenceMonitorEdit,
+            self.referenceExposureEdit,
+        ]
+        with blockSignals(widgets):
+            self.primaryMonitorCombo.clear()
+            self.primaryMonitorCombo.addItem("No primary monitor", "")
+            for name in sorted(available):
+                self.primaryMonitorCombo.addItem(name, name)
+            self.primaryMonitorCombo.setCurrentIndex(
+                max(self.primaryMonitorCombo.findData(selected or ""), 0)
+            )
+            kind = state.primary_monitor_kind or "rate"
+            self.monitorKindCombo.setCurrentIndex(
+                max(self.monitorKindCombo.findData(kind), 0)
+            )
+            self.monitorUnitEdit.setText(state.primary_monitor_unit or "")
+            self._setOptionalFloat(self.totalFluxEdit, state.total_incident_flux)
+            self._setOptionalFloat(
+                self.referenceMonitorEdit, state.monitor_reference_reading
+            )
+            self._setOptionalFloat(
+                self.referenceExposureEdit,
+                state.monitor_reference_exposure_s,
+            )
+            explicit = any(
+                getattr(state, name) is not None
+                for name in (
+                    "total_incident_flux",
+                    "total_flux_calibrated",
+                    "primary_monitor",
+                    "primary_monitor_kind",
+                    "horizontal_interception",
+                    "horizontal_intercepted_fraction",
+                )
+            )
+            if not explicit:
+                mode = "legacy"
+            elif state.total_flux_calibrated:
+                mode = "calibrated"
+            else:
+                mode = "relative"
+            self.scaleModeCombo.setCurrentIndex(
+                max(self.scaleModeCombo.findData(mode), 0)
+            )
+        self._syncFootprintState()
+        self._updateCtrStatus()
+
+    def _availableMonitorNames(self):
+        """Return usable monitor names from the currently loaded scan."""
+        main = self._mainWindow()
+        scan = getattr(main, "fscan", None) if main is not None else None
+        if scan is None:
+            return []
+        return integration_corrections.monitor_counter_candidates(scan)
 
     def _updateMonitorInfo(self):
         """Show which counters of the loaded scan could be used as monitors."""
@@ -2146,7 +2335,7 @@ def _updateMonitorInfo(self):
         if scan is None:
             self.monitorInfo.setText("<i>No scan loaded.</i>")
             return
-        available = integration_corrections.monitor_counter_candidates(scan)
+        available = self._availableMonitorNames()
         if available:
             self.monitorInfo.setText(
                 "<i>Available in this scan: " + ", ".join(available) + "</i>"
@@ -2168,6 +2357,184 @@ def _onNormalizationChanged(self):
             if value.strip()
         )
 
+    def _onTotalFluxChanged(self, *args):
+        """Write total-flux widgets to the typed correction state."""
+        state = self._correctionState()
+        mode = self.scaleModeCombo.currentData()
+        if mode == "legacy":
+            state.total_incident_flux = None
+            state.total_flux_calibrated = None
+            state.primary_monitor = None
+            state.primary_monitor_kind = None
+            state.primary_monitor_unit = None
+            state.monitor_reference_reading = None
+            state.monitor_reference_exposure_s = None
+            state.horizontal_interception = None
+            state.horizontal_intercepted_fraction = None
+        else:
+            state.total_flux_calibrated = mode == "calibrated"
+            state.total_incident_flux = (
+                self._optionalFloat(self.totalFluxEdit)
+                if mode == "calibrated"
+                else None
+            )
+            monitor = self.primaryMonitorCombo.currentData() or None
+            state.primary_monitor = monitor
+            state.primary_monitor_kind = (
+                self.monitorKindCombo.currentData() if monitor else None
+            )
+            state.primary_monitor_unit = (
+                self.monitorUnitEdit.text().strip() or None
+                if monitor
+                else None
+            )
+            state.monitor_reference_reading = (
+                self._optionalFloat(self.referenceMonitorEdit)
+                if monitor and mode == "calibrated"
+                else None
+            )
+            state.monitor_reference_exposure_s = (
+                self._optionalFloat(self.referenceExposureEdit)
+                if monitor
+                and mode == "calibrated"
+                and state.primary_monitor_kind == "integrated"
+                else None
+            )
+            if self.footprintOptions is not None:
+                state.horizontal_interception = (
+                    self.footprintOptions.horizontalInterceptionMode()
+                )
+                state.horizontal_intercepted_fraction = (
+                    self.footprintOptions.horizontalInterceptedFraction()
+                )
+        self._syncFootprintState()
+        self._updateCtrStatus()
+
+    def _syncFootprintState(self):
+        """Keep the shared overlap dialog on the active scale convention."""
+        if self.footprintOptions is None:
+            return
+        state = self._correctionState()
+        total_flux = self.scaleModeCombo.currentData() != "legacy"
+        self.footprintOptions.setTotalFluxMode(total_flux)
+        if total_flux:
+            self.footprintOptions.setHorizontalInterception(
+                state.horizontal_interception,
+                state.horizontal_intercepted_fraction,
+            )
+
+    def _onFootprintChanged(self):
+        """Copy horizontal-overlap edits into the typed correction state."""
+        if self.footprintOptions is None:
+            return
+        state = self._correctionState()
+        if self.scaleModeCombo.currentData() != "legacy":
+            state.horizontal_interception = (
+                self.footprintOptions.horizontalInterceptionMode()
+            )
+            state.horizontal_intercepted_fraction = (
+                self.footprintOptions.horizontalInterceptedFraction()
+            )
+        self._updateCtrStatus()
+
+    def _updateCtrStatus(self, *args):
+        """Show the next extraction's mode, formula, and scale completeness."""
+        state = self._correctionState()
+        mode = self.scaleModeCombo.currentData()
+        monitor = self.primaryMonitorCombo.currentData() or None
+        kind = self.monitorKindCombo.currentData() if monitor else None
+        if mode == "legacy":
+            formula = (
+                "Legacy convention: exposure × every listed monitor; beam "
+                "density and numerical active area remain separate."
+            )
+        elif monitor is None:
+            formula = (
+                "Q = Φtot × exposure" if mode == "calibrated" else "Q ∝ exposure"
+            )
+        elif kind == "rate":
+            formula = (
+                "Q = Φref × exposure × M/Mref"
+                if mode == "calibrated"
+                else "Q ∝ exposure × monitor rate"
+            )
+        else:
+            formula = (
+                "Q = Φref × Tref × U/Uref (no second frame exposure)"
+                if mode == "calibrated"
+                else "Q ∝ integrated monitor (frame exposure already included)"
+            )
+        unit = self.monitorUnitEdit.text().strip()
+        if monitor and unit:
+            formula += f"; {monitor} [{unit}]"
+        self.normalizationFormula.setText(f"<i>{formula}</i>")
+
+        rocking = False
+        scanstab = getattr(self._selector, "scanstab", None)
+        if scanstab is not None:
+            rocking = scanstab.currentIndex() in (2, 3)
+        self.measurementModeInfo.setText(
+            "Measurement mode: rocking scan — calculated after rocking-curve "
+            "integration; angular acceptance is applied there."
+            if rocking
+            else "Measurement mode: stationary — calculated during ROI integration."
+        )
+
+        missing = []
+        if not self._selector.useNormalizationBox.isChecked():
+            missing.append("frame normalization Q")
+        if not self._selector.useFootprintBox.isChecked():
+            missing.append("illumination H")
+        if mode == "calibrated":
+            flux = self._optionalFloat(self.totalFluxEdit)
+            if flux is None or flux <= 0:
+                missing.append("positive total flux")
+            if monitor and self._optionalFloat(self.referenceMonitorEdit) is None:
+                missing.append("reference monitor reading")
+            elif (
+                monitor
+                and self._optionalFloat(self.referenceMonitorEdit) is not None
+                and self._optionalFloat(self.referenceMonitorEdit) <= 0
+            ):
+                missing.append("positive reference monitor reading")
+            if (
+                monitor
+                and kind == "integrated"
+                and (
+                    self._optionalFloat(self.referenceExposureEdit) is None
+                    or self._optionalFloat(self.referenceExposureEdit) <= 0
+                )
+            ):
+                missing.append("positive reference exposure")
+        if mode != "legacy" and state.horizontal_interception is None:
+            missing.append("horizontal interception")
+
+        calibrated = mode == "calibrated" and not missing
+        if mode == "legacy":
+            status = "Legacy density/area convention"
+        elif missing:
+            scale = "Calibrated scale" if mode == "calibrated" else "Relative scale"
+            status = f"{scale} pending — missing " + ", ".join(missing)
+        elif calibrated:
+            status = (
+                "Calibrated F² scale; detector efficiency and external "
+                "transmission are currently explicit unity assumptions."
+            )
+        else:
+            status = "Relative F² scale (arbitrary units)"
+        self.scaleStatus.setText(f"<b>Next extraction:</b> {status}")
+
+        total_flux = mode != "legacy"
+        self.totalFluxEdit.setEnabled(mode == "calibrated")
+        self.primaryMonitorCombo.setEnabled(total_flux)
+        self.monitorKindCombo.setEnabled(total_flux and monitor is not None)
+        self.monitorUnitEdit.setEnabled(total_flux and monitor is not None)
+        reference = mode == "calibrated" and monitor is not None
+        self.referenceMonitorEdit.setEnabled(reference)
+        integrated_reference = reference and kind == "integrated"
+        self.referenceExposureLabel.setEnabled(integrated_reference)
+        self.referenceExposureEdit.setEnabled(integrated_reference)
+
     def footprintOptions_shared(self):
         """Return the beam-profile dialog, creating it on first use.
 
@@ -2180,6 +2547,10 @@ def footprintOptions_shared(self):
             from .peak1Dintegr import IntegrationCorrectionsDialog
 
             self.footprintOptions = IntegrationCorrectionsDialog(self)
+            self.footprintOptions.settingsChanged.connect(
+                self._onFootprintChanged
+            )
+            self._syncFootprintState()
         return self.footprintOptions
 
     # GUI-only: user-triggered dialog.
diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index 4a0b10c..67d4916 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -1305,6 +1305,7 @@ def apply_to_gui(self, gui):
                 or self.corrections.beam_flux_density is not None
                 or self.corrections.beam_shape_name is not None
                 or self.corrections.beam_profile_file is not None
+                or self.corrections.horizontal_interception is not None
             ):
                 corrections_dialog = getattr(
                     gui.scanSelector, "correctionsDialog", None
@@ -1323,6 +1324,11 @@ def apply_to_gui(self, gui):
                         footprint_dialog.setBeamFluxDensity(
                             self.corrections.beam_flux_density
                         )
+                    if self.corrections.horizontal_interception is not None:
+                        footprint_dialog.setHorizontalInterception(
+                            self.corrections.horizontal_interception,
+                            self.corrections.horizontal_intercepted_fraction,
+                        )
                     # The dialog's own setSettings(), in its own display
                     # units; only the keys this configuration actually
                     # recorded are passed, so the rest of the dialog is left
@@ -1345,6 +1351,12 @@ def apply_to_gui(self, gui):
                         )
                     if beam_shape:
                         footprint_dialog.setSettings(beam_shape)
+            corrections_dialog = getattr(
+                gui.scanSelector, "correctionsDialog", None
+            )
+            refresh = getattr(corrections_dialog, "refresh", None)
+            if refresh is not None:
+                refresh()
         gui.reconstruction_normalize_exposure = self.corrections.normalize_exposure
         gui.reconstruction_monitor_corrections = self.corrections.monitor_corrections
         if (
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 13f3b01..0717931 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -65,7 +65,9 @@
     detector_from_nxdict,
 )
 from .integration_corrections import (
+    FOOTPRINT_APPLY,
     FOOTPRINT_KEEP,
+    FOOTPRINT_REMOVE,
     corrected_curve_from_record,
 )
 from .. import resources
@@ -559,6 +561,10 @@ def __init__(self, database, parent=None):
         self.filedialogdir = "."
         self._currentRoInfo = {}
         self._idx = 0
+        self.footprint_action = FOOTPRINT_KEEP
+        self.replacement_illumination = None
+        self.replacement_illumination_convention = None
+        self.allow_illumination_convention_change = False
 
         dbdockwidget = qt.QDockWidget("Integrated data")
 
@@ -738,17 +744,54 @@ def __init__(self, database, parent=None):
 
         roi_edit_layout.addWidget(modifyROIsGroup)
 
-        integrateOptionsGroup = qt.QGroupBox("Integrate options")
-        integrateOptionsGroupLayout = qt.QHBoxLayout()
+        integrateOptionsGroup = qt.QGroupBox("CTR reduction")
+        integrateOptionsGroupLayout = qt.QGridLayout()
 
-        self.lorentzButton = qt.QCheckBox("Lorentz")
-        self.footprintButton = qt.QCheckBox("footprint")
-        self.footprintOptionsButton = qt.QPushButton("options")
+        self.lorentzButton = qt.QCheckBox("Calculate CTR structure factor")
+        self.lorentzButton.setToolTip(
+            "Apply the rocking-mode Lorentz, rod-intersection and angular-"
+            "acceptance factors. Disable this to save diagnostic intensity "
+            "when Q or H is deliberately absent."
+        )
+        self.normalizationStatus = qt.QLabel(
+            "Normalization: Unknown (no rocking scan selected)"
+        )
+        self.normalizationStatus.setWordWrap(True)
+        self.footprintAction = qt.QComboBox()
+        self.footprintAction.addItem("Keep stored correction", FOOTPRINT_KEEP)
+        self.footprintAction.addItem("Apply current beam settings", FOOTPRINT_APPLY)
+        self.footprintAction.addItem(
+            "Remove stored correction", FOOTPRINT_REMOVE
+        )
+        self.footprintAction.setToolTip(
+            "Every action starts from the stored base curve. Unsafe actions "
+            "are disabled when correction provenance is unknown."
+        )
+        self.footprintStatus = qt.QLabel(
+            "Saved result: Unknown (no rocking scan selected)"
+        )
+        self.footprintStatus.setWordWrap(True)
+        self.reductionPreview = qt.QLabel("Next reduction: no scan selected")
+        self.reductionPreview.setWordWrap(True)
+        self.reductionDetails = qt.QLabel("")
+        self.reductionDetails.setWordWrap(True)
+        self.footprintOptionsButton = qt.QPushButton("Current beam settings ...")
         self.footprintOptionsButton.clicked.connect(self._showFootprintOptions)
-
-        integrateOptionsGroupLayout.addWidget(self.lorentzButton)
-        integrateOptionsGroupLayout.addWidget(self.footprintButton)
-        integrateOptionsGroupLayout.addWidget(self.footprintOptionsButton)
+        self.footprintAction.currentIndexChanged.connect(
+            self._onFootprintActionChanged
+        )
+        self.lorentzButton.toggled.connect(self._onFootprintActionChanged)
+
+        integrateOptionsGroupLayout.addWidget(self.lorentzButton, 0, 0, 1, 2)
+        integrateOptionsGroupLayout.addWidget(self.normalizationStatus, 1, 0, 1, 2)
+        integrateOptionsGroupLayout.addWidget(qt.QLabel("Footprint action:"), 2, 0)
+        integrateOptionsGroupLayout.addWidget(self.footprintAction, 2, 1)
+        integrateOptionsGroupLayout.addWidget(self.footprintStatus, 3, 0, 1, 2)
+        integrateOptionsGroupLayout.addWidget(self.reductionPreview, 4, 0, 1, 2)
+        integrateOptionsGroupLayout.addWidget(self.reductionDetails, 5, 0, 1, 2)
+        integrateOptionsGroupLayout.addWidget(
+            self.footprintOptionsButton, 6, 0, 1, 2
+        )
 
         integrateOptionsGroup.setLayout(integrateOptionsGroupLayout)
 
@@ -803,6 +846,11 @@ def __init__(self, database, parent=None):
         self.curveSlider.sigValueChanged.connect(self.onSliderValueChanged)
         # self.roiwidget.sigROISignal.connect(lambda d: print(d))
 
+        self.integrationCorrection.settingsChanged.connect(
+            self._onFootprintActionChanged
+        )
+        self._refreshReductionCorrectionStatus()
+
     def _check_ro_present(self):
         if not self.database.nxfile:
             self._currentRoInfo = {}
@@ -844,8 +892,252 @@ def useSharedFootprintOptions(self, dialog):
             return
         previous = self.integrationCorrection
         self.integrationCorrection = dialog
+        self.integrationCorrection.settingsChanged.connect(
+            self._onFootprintActionChanged
+        )
         if previous is not None:
             previous.deleteLater()
+        self._onFootprintActionChanged()
+
+    @staticmethod
+    def _correctionUiState(record, record_present=True):
+        """Describe safe rocking-reduction actions for a stored record.
+
+        :param CurveCorrectionRecord or None record: Parsed stored record.
+        :param bool record_present: Whether a correction group exists at all.
+        :rtype: dict
+        """
+        if record is None:
+            reason = (
+                "an incomplete correction record"
+                if record_present
+                else "legacy data without a correction record"
+            )
+            return {
+                "actions": (FOOTPRINT_KEEP,),
+                "normalization": "Unknown (legacy data)",
+                "footprint": "Unknown",
+                "details": (
+                    f"Correction provenance is unknown because this scan has {reason}. "
+                    "Re-extract images to change this correction safely."
+                ),
+                "known_total_flux": False,
+            }
+
+        if record.algorithm.startswith("legacy_rocking_roi_"):
+            return {
+                "actions": (FOOTPRINT_KEEP, FOOTPRINT_APPLY),
+                "normalization": "Applied later by the legacy reducer",
+                "footprint": "Not applied to the saved curve",
+                "details": (
+                    f"Algorithm {record.algorithm}; scale {record.scale_convention}. "
+                    "Current beam settings may be applied using the preserved "
+                    "legacy density/area convention."
+                ),
+                "known_total_flux": False,
+            }
+
+        if record.algorithm.startswith("framewise_ctr_total_flux_"):
+            reversible = (
+                record.base_croibg is not None
+                and record.base_croibg_variance is not None
+            )
+            known_illumination = record.illumination_status in (
+                "applied",
+                "not_applied",
+            )
+            actions = [FOOTPRINT_KEEP]
+            if reversible and known_illumination:
+                actions.append(FOOTPRINT_APPLY)
+            if (
+                reversible
+                and record.illumination_status == "applied"
+                and record.illumination_divisor is not None
+            ):
+                actions.append(FOOTPRINT_REMOVE)
+            normalization = {
+                "applied": "Applied during extraction",
+                "not_applied": "Not applied",
+                "unavailable": "Unavailable",
+            }.get(record.normalization_status, "Unknown")
+            footprint = {
+                "applied": "Applied during extraction",
+                "not_applied": "Not applied",
+                "unavailable": "Unavailable",
+            }.get(record.illumination_status, "Unknown")
+            extra = ""
+            if not reversible or not known_illumination:
+                extra = " Re-extract images to change this correction safely."
+            return {
+                "actions": tuple(actions),
+                "normalization": normalization,
+                "footprint": footprint,
+                "details": (
+                    f"Algorithm {record.algorithm}; scale {record.scale_convention}; "
+                    f"illumination convention "
+                    f"{record.illumination_convention or 'none'}.{extra}"
+                ),
+                "known_total_flux": True,
+            }
+
+        return {
+            "actions": (FOOTPRINT_KEEP,),
+            "normalization": "Unknown",
+            "footprint": "Unknown",
+            "details": (
+                f"Unsupported correction algorithm {record.algorithm!r}. "
+                "Re-extract images to change this correction safely."
+            ),
+            "known_total_flux": False,
+        }
+
+    @staticmethod
+    def _storedCurveCorrectionRecord(h5_obj, nxfile):
+        """Return a parsed stored record, or ``None`` when it is incomplete."""
+        if CURVE_CORRECTIONS_GROUP not in h5_obj:
+            return None
+        record_group = h5_obj[CURVE_CORRECTIONS_GROUP]
+        try:
+            record_dict = h5todict(nxfile, record_group.name)
+            record_dict["@orgui_schema_version"] = record_group.attrs.get(
+                "orgui_schema_version", 0
+            )
+            record_dict["@orgui_curve_contract"] = record_group.attrs.get(
+                "orgui_curve_contract", ""
+            )
+            return curve_correction_record_from_nxdict(record_dict)
+        except (KeyError, TypeError, ValueError):
+            return None
+
+    def _setFootprintActionEnabled(self, action, enabled):
+        """Enable one footprint-action choice in the combo-box model."""
+        index = self.footprintAction.findData(action)
+        if index >= 0:
+            self.footprintAction.model().item(index).setEnabled(bool(enabled))
+
+    def _refreshReductionCorrectionStatus(self):
+        """Refresh saved-result provenance and safe next actions."""
+        record = None
+        present = False
+        if self._currentRoInfo and self.database.nxfile:
+            name = self._currentRoInfo.get("name")
+            if name in self.database.nxfile:
+                h5_obj = self.database.nxfile[name]
+                present = CURVE_CORRECTIONS_GROUP in h5_obj
+                record = self._storedCurveCorrectionRecord(
+                    h5_obj, self.database.nxfile
+                )
+        state = self._correctionUiState(record, present)
+        self._activeCorrectionRecord = record
+        self._activeCorrectionUiState = state
+        allowed = state["actions"]
+        for action in (FOOTPRINT_KEEP, FOOTPRINT_APPLY, FOOTPRINT_REMOVE):
+            self._setFootprintActionEnabled(action, action in allowed)
+        if self.footprintAction.currentData() not in allowed:
+            self.footprintAction.setCurrentIndex(
+                self.footprintAction.findData(FOOTPRINT_KEEP)
+            )
+        self.normalizationStatus.setText(
+            f"Saved normalization: {state['normalization']}"
+        )
+        self.footprintStatus.setText(
+            f"Saved footprint: {state['footprint']}"
+        )
+        self.reductionDetails.setText(state["details"])
+        self._onFootprintActionChanged()
+
+    def _onFootprintActionChanged(self, *args):
+        """Prepare and describe the selected next-reduction footprint action."""
+        action = self.footprintAction.currentData() or FOOTPRINT_KEEP
+        self.footprint_action = action
+        self.replacement_illumination = None
+        self.replacement_illumination_convention = None
+        self.allow_illumination_convention_change = False
+
+        action_text = {
+            FOOTPRINT_KEEP: "keep the stored footprint state",
+            FOOTPRINT_APPLY: "apply current beam settings from the base curve",
+            FOOTPRINT_REMOVE: "remove the stored footprint from the base curve",
+        }[action]
+        record = getattr(self, "_activeCorrectionRecord", None)
+        known_total_flux = bool(
+            getattr(self, "_activeCorrectionUiState", {}).get(
+                "known_total_flux", False
+            )
+        )
+        if action == FOOTPRINT_APPLY:
+            action_text = (
+                "Replaced here using current beam settings"
+                if record is not None and record.illumination_status == "applied"
+                else "Applied here using current beam settings"
+            )
+        f2_ready = action != FOOTPRINT_REMOVE
+        if known_total_flux:
+            f2_ready = record.normalization_status == "applied"
+            if action == FOOTPRINT_KEEP:
+                f2_ready = f2_ready and record.illumination_status == "applied"
+            elif action == FOOTPRINT_APPLY:
+                f2_ready = (
+                    f2_ready
+                    and self.integrationCorrection.horizontalInterceptedFraction()
+                    is not None
+                )
+            else:
+                f2_ready = False
+        if not f2_ready and self.lorentzButton.isChecked():
+            with qt.QSignalBlocker(self.lorentzButton):
+                self.lorentzButton.setChecked(False)
+        self.lorentzButton.setEnabled(f2_ready)
+        quantity = (
+            "CTR structure factor"
+            if self.lorentzButton.isChecked() and f2_ready
+            else "diagnostic intensity (not F²)"
+        )
+        warning = ""
+        if action == FOOTPRINT_REMOVE and self.lorentzButton.isChecked():
+            warning = " Remove leaves H absent, so F² is unavailable."
+        self.reductionPreview.setText(
+            f"Next reduction: {action_text}; output {quantity}.{warning}"
+        )
+
+    def _prepareFootprintAction(self, h5_obj):
+        """Resolve any live illumination divisor before reading the curve."""
+        action = self.footprintAction.currentData() or FOOTPRINT_KEEP
+        self.footprint_action = action
+        self.replacement_illumination = None
+        self.replacement_illumination_convention = None
+        record = self._storedCurveCorrectionRecord(h5_obj, self.database.nxfile)
+        if (
+            action == FOOTPRINT_APPLY
+            and record is not None
+            and record.algorithm.startswith("framewise_ctr_total_flux_")
+        ):
+            horizontal = self.integrationCorrection.horizontalInterceptedFraction()
+            if horizontal is None:
+                raise ValueError(
+                    "Applying current total-flux beam settings requires an "
+                    "explicit horizontal interception choice."
+                )
+            if record.alpha is None:
+                raise ValueError(
+                    "The stored curve has no incidence angles; re-extract "
+                    "images before changing its footprint."
+                )
+            self.replacement_illumination = (
+                activearea_corrections.illumination_divisor(
+                    record.alpha,
+                    self.integrationCorrection.sampleLength(),
+                    self.integrationCorrection.beamProfile(),
+                    horizontal_fraction=horizontal,
+                )
+            )
+            self.replacement_illumination_convention = "total_flux_H"
+        elif action != FOOTPRINT_KEEP and record is None:
+            raise ValueError(
+                "Correction provenance is unknown. Re-extract images before "
+                "changing the footprint."
+            )
+        return record
 
     def onIntegrate(self):
         try:
@@ -904,6 +1196,7 @@ def set_roscan(self, name):
         self.plotROIselect.resetZoom()
         if self.autozoom_checkbox.isChecked():
             self.resetXZoomScaled(self.zoomslider.value())
+        self._refreshReductionCorrectionStatus()
 
     def onAnchorSaveRoi(self):
         # GUI-only: user-triggered save dialog path.
@@ -1754,12 +2047,17 @@ def integrate(self):
         """
         if not self._currentRoInfo:
             raise ValueError("No rocking scan selected.")
+        name = self._currentRoInfo["name"]
+        h5_obj = self.database.nxfile[name]
+        self._prepareFootprintAction(h5_obj)
         curves = self.get_all_ro_curves()
         correction_record = curves.get("correction_record")
         versioned_total_flux = correction_record is not None
-        name = self._currentRoInfo["name"]
-        h5_obj = self.database.nxfile[name]
         cnters = h5_obj["rois"]
+        footprint_action = self.footprint_action
+        apply_legacy_footprint = (
+            not versioned_total_flux and footprint_action == FOOTPRINT_APPLY
+        )
 
         s_array = cnters["s"][()]
         alpha = np.deg2rad(cnters["alpha"][()])
@@ -1804,7 +2102,7 @@ def integrate(self):
             # live dialog here would scale the same photons a second time.
             C_flux_on_sample = 1.0
             C_illum_area = 1.0
-        elif self.footprintButton.isChecked():
+        elif apply_legacy_footprint:
             L = self.integrationCorrection.sampleLength()  # sample size, m
             # Gaussian or measured beam profile, depending on the dialog.
             # C_flux_on_sample is saved as the diagnostic numerator of the
@@ -1888,7 +2186,7 @@ def integrate(self):
             roi_info,
             aux,
             self.lorentzButton.isChecked(),
-            self.footprintButton.isChecked() and not versioned_total_flux,
+            apply_legacy_footprint,
             C_Lor=C_Lor,
             C_rod=C_rod,
             C_flux_on_sample=C_flux_on_sample,
@@ -2057,7 +2355,7 @@ def integrate(self):
                     curves["illumination_action"]
                     in ("applied", "replaced", "applied_here")
                     if versioned_total_flux
-                    else self.footprintButton.isChecked()
+                    else apply_legacy_footprint
                 ),
             }
             if versioned_total_flux:
@@ -2074,7 +2372,7 @@ def integrate(self):
             if detector_acceptance is not None:
                 reduction["detector_acceptance"] = detector_acceptance
                 reduction["@detector_acceptance_unit"] = "rad"
-            if self.footprintButton.isChecked() and not versioned_total_flux:
+            if apply_legacy_footprint:
                 reduction["sample_size"] = L
                 reduction["@sample_size_unit"] = "m"
             measurement[availname1]["reduction"] = reduction
@@ -2084,6 +2382,7 @@ def integrate(self):
             update_mode="modify",
             h5path=self._currentRoInfo["name"] + "/measurement",
         )
+        self._refreshReductionCorrectionStatus()
 
     def onSliderValueChanged(self, ddict):
         try:
@@ -2212,26 +2511,9 @@ def get_all_ro_curves(self):
         name = self._currentRoInfo["name"]
         h5_obj = self.database.nxfile[name]
         if CURVE_CORRECTIONS_GROUP in h5_obj:
-            record_group = h5_obj[CURVE_CORRECTIONS_GROUP]
-            try:
-                record_dict = h5todict(
-                    self.database.nxfile,
-                    record_group.name,
-                )
-                record_dict["@orgui_schema_version"] = record_group.attrs.get(
-                    "orgui_schema_version", 0
-                )
-                record_dict["@orgui_curve_contract"] = record_group.attrs.get(
-                    "orgui_curve_contract", ""
-                )
-                record = curve_correction_record_from_nxdict(
-                    record_dict
-                )
-            except ValueError:
-                # Let the legacy gate distinguish supported legacy records
-                # from unknown normalized contracts and produce its targeted
-                # error instead of guessing which numbers the curve contains.
-                record = None
+            record = RockingPeakIntegrator._storedCurveCorrectionRecord(
+                h5_obj, self.database.nxfile
+            )
             if record is not None and record.algorithm.startswith(
                 "framewise_ctr_total_flux_"
             ):
@@ -2887,6 +3169,7 @@ class IntegrationCorrectionsDialog(qt.QDialog):
     #: File-column meaning of the loaded beam-profile file.
     CONTENT_PROFILE = "beam profile"
     CONTENT_HEIGHT_SCAN = "height scan (-dI/dz)"
+    settingsChanged = qt.Signal()
 
     def __init__(self, parent=None):
         qt.QDialog.__init__(self, parent)
@@ -2938,24 +3221,52 @@ def __init__(self, parent=None):
             "Only the absolute active area in square meter uses it; a "
             "structure factor on a relative scale is unaffected."
         )
+        self._legacyWidthToolTip = self.W.toolTip()
         sizesLayout.addWidget(self.W, 1, 1)
 
-        sizesLayout.addWidget(qt.QLabel("Beam flux:"), 2, 0)
+        self.legacyFluxLabel = qt.QLabel("Legacy flux density:")
+        sizesLayout.addWidget(self.legacyFluxLabel, 2, 0)
         self.beamFlux = qt.QDoubleSpinBox()
         self.beamFlux.setRange(0.0, 1e30)
         self.beamFlux.setDecimals(3)
         self.beamFlux.setSuffix(" ph/(s·mm²)")
         self.beamFlux.setValue(0.0)
         self.beamFlux.setToolTip(
-            "Incident photon flux density (Phi_0) at the sample position.\n"
-            "Called 'beam flux' here rather than Phi_0 or phi, to avoid "
-            "confusion with the sample-circle phi of the diffractometer.\n"
-            "Only needed for an absolutely scaled structure factor "
-            "(issue #15); leave at 0 if it has not been measured -- a "
-            "structure factor on a relative scale does not use it."
+            "Legacy incident photon flux density at the sample position. "
+            "This remains photons/(s mm²) and is never reinterpreted as "
+            "total photons/s. New total-flux calibration is configured in "
+            "the parent corrections dialog."
         )
+        self._legacyFluxToolTip = self.beamFlux.toolTip()
         sizesLayout.addWidget(self.beamFlux, 2, 1)
 
+        sizesLayout.addWidget(qt.QLabel("Horizontal interception:"), 3, 0)
+        self.horizontalInterception = qt.QComboBox()
+        self.horizontalInterception.addItem("Not specified", "")
+        self.horizontalInterception.addItem("Full beam intercepted", "full")
+        self.horizontalInterception.addItem(
+            "Known intercepted fraction", "fraction"
+        )
+        self.horizontalInterception.setToolTip(
+            "A vertical beam profile cannot establish how much of the beam "
+            "is intercepted horizontally. New total-flux corrections require "
+            "this choice to be explicit."
+        )
+        sizesLayout.addWidget(self.horizontalInterception, 3, 1)
+
+        self.horizontalFractionLabel = qt.QLabel("Horizontal fraction:")
+        sizesLayout.addWidget(self.horizontalFractionLabel, 4, 0)
+        self.horizontalFraction = qt.QDoubleSpinBox()
+        self.horizontalFraction.setRange(0.000001, 1.0)
+        self.horizontalFraction.setDecimals(6)
+        self.horizontalFraction.setSingleStep(0.01)
+        self.horizontalFraction.setValue(1.0)
+        self.horizontalFraction.setToolTip(
+            "Known fraction of the full incident beam intercepted in the "
+            "horizontal direction. Must be greater than zero and at most one."
+        )
+        sizesLayout.addWidget(self.horizontalFraction, 4, 1)
+
         modeLayout = qt.QHBoxLayout()
         self.analyticalButton = qt.QRadioButton("analytical beam shape")
         self.analyticalButton.setChecked(True)
@@ -3005,10 +3316,96 @@ def __init__(self, parent=None):
         self.setLayout(verticalLayout)
 
         self.analyticalButton.toggled.connect(self._onModeChanged)
+        self.horizontalInterception.currentIndexChanged.connect(
+            self._onHorizontalInterceptionChanged
+        )
+        self.horizontalFraction.valueChanged.connect(self._settingsChanged)
+        self.L.valueChanged.connect(self._settingsChanged)
+        self.W.valueChanged.connect(self._settingsChanged)
+        self.beamFlux.valueChanged.connect(self._settingsChanged)
+        self.profileOffset.valueChanged.connect(self._settingsChanged)
+        self.profileCenter.currentIndexChanged.connect(self._settingsChanged)
+        self.analyticalButton.toggled.connect(self._settingsChanged)
         self._onShapeChanged()
         self._onModeChanged()
+        self._onHorizontalInterceptionChanged()
         self._settings_save = self.settings()
 
+    def _settingsChanged(self, *args):
+        """Notify owners that the effective beam settings changed."""
+        self.settingsChanged.emit()
+
+    def _onHorizontalInterceptionChanged(self, *args):
+        """Enable the fraction editor only for the explicit fraction mode."""
+        fraction_mode = self.horizontalInterception.currentData() == "fraction"
+        self.horizontalFractionLabel.setEnabled(fraction_mode)
+        self.horizontalFraction.setEnabled(fraction_mode)
+        self._updateLegacyControlState()
+        self._updatePreview()
+        self._settingsChanged()
+
+    def horizontalInterceptionMode(self):
+        """Return ``'full'``, ``'fraction'`` or ``None`` from the UI."""
+        return self.horizontalInterception.currentData() or None
+
+    def horizontalInterceptedFraction(self):
+        """Return the stated horizontal fraction, or ``None`` if unresolved."""
+        mode = self.horizontalInterceptionMode()
+        if mode == "full":
+            return 1.0
+        if mode == "fraction":
+            return self.horizontalFraction.value()
+        return None
+
+    def setHorizontalInterception(self, mode, fraction=None):
+        """Restore the horizontal interception convention.
+
+        :param str or None mode: ``'full'``, ``'fraction'`` or ``None``.
+        :param float or None fraction: Fraction used by ``'fraction'`` mode.
+        """
+        index = self.horizontalInterception.findData(mode or "")
+        with blockSignals([self.horizontalInterception, self.horizontalFraction]):
+            self.horizontalInterception.setCurrentIndex(max(index, 0))
+            if fraction is not None:
+                self.horizontalFraction.setValue(float(fraction))
+        self._onHorizontalInterceptionChanged()
+
+    def setTotalFluxMode(self, enabled):
+        """Show which legacy density controls are inactive in total-flux mode."""
+        self._totalFluxMode = bool(enabled)
+        self._updateLegacyControlState()
+
+    def _updateLegacyControlState(self):
+        """Apply total-flux/legacy enablement without changing stored values."""
+        enabled = bool(getattr(self, "_totalFluxMode", False))
+        self.beamFlux.setEnabled(not enabled)
+        self.legacyFluxLabel.setEnabled(not enabled)
+        full_horizontal = (
+            enabled and self.horizontalInterceptionMode() == "full"
+        )
+        self.W.setEnabled(not full_horizontal)
+        if full_horizontal:
+            reason = (
+                "Not a total-flux scale input. Horizontal interception is "
+                "explicitly the full beam."
+            )
+            self.W.setToolTip(reason)
+        elif enabled:
+            self.W.setToolTip(
+                "Retained for geometry and legacy density calculations; it "
+                "does not set the total-flux scale."
+            )
+        else:
+            self.W.setToolTip(self._legacyWidthToolTip)
+        if enabled:
+            self.beamFlux.setToolTip(
+                "Legacy density value preserved for compatibility; the "
+                "active total-flux convention uses photons/s in the parent "
+                "corrections dialog."
+            )
+        else:
+            self.beamFlux.setToolTip(self._legacyFluxToolTip)
+
     def _createShapeGroup(self):
         """Build the analytical-shape group box."""
         self.shapeGroup = qt.QGroupBox("Analytical shape parameters")
@@ -3133,6 +3530,7 @@ def _onModeChanged(self):
             self.shapeGroup if analytical else self.profileGroup
         )
         self._updatePreview()
+        self._settingsChanged()
 
     def _onShapeChanged(self):
         """Relabel the numeric controls for the newly selected shape."""
@@ -3155,6 +3553,7 @@ def _onShapeChanged(self):
                     label.setVisible(False)
                     spin.setVisible(False)
         self._updatePreview()
+        self._settingsChanged()
 
     def _onShapeValueChanged(self):
         """Remember the edited values for the current shape and redraw."""
@@ -3163,6 +3562,7 @@ def _onShapeValueChanged(self):
             self.shapeParameters[i].value() for i in range(len(shape.parameters))
         ]
         self._updatePreview()
+        self._settingsChanged()
 
     def currentShape(self):
         """Return the selected analytical beam shape.
@@ -3292,6 +3692,14 @@ def _updatePreview(self):
             summary += f", centroid at {centroid * 1e6:+.1f} microns"
         else:
             summary += ", centroid undefined (the profile has no center of mass)"
+        mode = self.horizontalInterceptionMode()
+        if mode == "full":
+            summary += "; horizontal fraction 1 (full beam intercepted)"
+        elif mode == "fraction":
+            summary += f"; horizontal fraction {self.horizontalFraction.value():.6g}"
+        else:
+            summary += "; horizontal interception not specified"
+        summary += "; vertical fraction is evaluated per frame from L and incidence"
         self.profileInfo.setText(summary)
 
     def measuredProfile(self):
@@ -3425,6 +3833,10 @@ def settings(self):
             "L": self.L.value(),
             "W": self.W.value(),
             "beam_flux": self.beamFlux.value(),
+            "horizontal_interception": self.horizontalInterceptionMode(),
+            "horizontal_intercepted_fraction": (
+                self.horizontalInterceptedFraction()
+            ),
             "analytical": self.analyticalButton.isChecked(),
             "shape": shape.name,
             "shape_values": list(self._shape_values[shape.name]),
@@ -3446,6 +3858,8 @@ def setSettings(self, settings):
             self.profileUnit,
             self.profileCenter,
             self.profileOffset,
+            self.horizontalInterception,
+            self.horizontalFraction,
             self.analyticalButton,
             self.shapeSelector,
         ] + self.shapeParameters
@@ -3456,6 +3870,17 @@ def setSettings(self, settings):
                 self.W.setValue(settings["W"])
             if "beam_flux" in settings:
                 self.beamFlux.setValue(settings["beam_flux"])
+            if "horizontal_interception" in settings:
+                mode = settings["horizontal_interception"]
+                index = self.horizontalInterception.findData(mode or "")
+                self.horizontalInterception.setCurrentIndex(max(index, 0))
+            if (
+                "horizontal_intercepted_fraction" in settings
+                and settings["horizontal_intercepted_fraction"] is not None
+            ):
+                self.horizontalFraction.setValue(
+                    settings["horizontal_intercepted_fraction"]
+                )
             if "analytical" in settings:
                 self.analyticalButton.setChecked(bool(settings["analytical"]))
                 self.measuredButton.setChecked(not settings["analytical"])
@@ -3479,6 +3904,7 @@ def setSettings(self, settings):
                 self.profileOffset.setValue(settings["profile_offset"])
         self._onShapeChanged()
         self._onModeChanged()
+        self._onHorizontalInterceptionChanged()
         self.loadProfile()
 
     def onOk(self):
diff --git a/orgui/app/test/test_integration_corrections_dialog.py b/orgui/app/test/test_integration_corrections_dialog.py
index 9792cbe..8e4af8c 100644
--- a/orgui/app/test/test_integration_corrections_dialog.py
+++ b/orgui/app/test/test_integration_corrections_dialog.py
@@ -329,6 +329,7 @@ def test_cancel_restores_the_last_accepted_settings(dialog, tmp_path):
     dialog.measuredButton.setChecked(True)
     dialog.profileFileEdit.setText(str(path))
     dialog.loadProfile()
+    dialog.setHorizontalInterception("full")
     dialog.onOk()
 
     dialog.L.setValue(7.5)
@@ -336,6 +337,7 @@ def test_cancel_restores_the_last_accepted_settings(dialog, tmp_path):
     dialog.profileCenter.setCurrentIndex(dialog.profileCenter.findText("peak"))
     _select_shape(dialog, "Top hat")
     dialog.analyticalButton.setChecked(True)
+    dialog.setHorizontalInterception("fraction", 0.25)
     dialog.onCancel()
 
     assert dialog.L.value() == pytest.approx(3.0)
@@ -343,6 +345,8 @@ def test_cancel_restores_the_last_accepted_settings(dialog, tmp_path):
     assert dialog.profileCenter.currentText() == "centroid"
     assert dialog.currentShape().name == "Gaussian"
     assert dialog.measuredButton.isChecked()
+    assert dialog.horizontalInterceptionMode() == "full"
+    assert dialog.horizontalInterceptedFraction() == pytest.approx(1.0)
     # The restored state is still usable, not just cosmetically reset.
     assert isinstance(dialog.beamProfile(), MeasuredBeamProfile)
 
@@ -362,6 +366,7 @@ def test_settings_round_trip(dialog, tmp_path):
     flat.setValue(30.0)
     dialog.profileCenter.setCurrentIndex(dialog.profileCenter.findText("median"))
     dialog.profileOffset.setValue(-12.5)
+    dialog.setHorizontalInterception("fraction", 0.35)
     saved = dialog.settings()
 
     restored = IntegrationCorrectionsDialog()
@@ -375,6 +380,39 @@ def test_settings_round_trip(dialog, tmp_path):
         restored.deleteLater()
 
 
+def test_horizontal_interception_is_explicit_and_round_trips(dialog):
+    """Unknown, full, and fractional horizontal overlap remain distinct."""
+    assert dialog.horizontalInterceptionMode() is None
+    assert dialog.horizontalInterceptedFraction() is None
+    assert not dialog.horizontalFraction.isEnabled()
+
+    dialog.setHorizontalInterception("full")
+    assert dialog.horizontalInterceptionMode() == "full"
+    assert dialog.horizontalInterceptedFraction() == pytest.approx(1.0)
+    assert not dialog.horizontalFraction.isEnabled()
+
+    dialog.setHorizontalInterception("fraction", 0.42)
+    assert dialog.horizontalInterceptionMode() == "fraction"
+    assert dialog.horizontalInterceptedFraction() == pytest.approx(0.42)
+    assert dialog.horizontalFraction.isEnabled()
+
+
+def test_total_flux_mode_disables_density_and_full_mode_width_input(dialog):
+    """Legacy density/area inputs cannot silently enter total-flux H."""
+    dialog.setTotalFluxMode(True)
+    assert not dialog.beamFlux.isEnabled()
+    assert dialog.W.isEnabled()
+    assert "does not set the total-flux scale" in dialog.W.toolTip()
+
+    dialog.setHorizontalInterception("full")
+    assert not dialog.W.isEnabled()
+    assert "Not a total-flux scale input" in dialog.W.toolTip()
+
+    dialog.setTotalFluxMode(False)
+    assert dialog.beamFlux.isEnabled()
+    assert dialog.W.isEnabled()
+
+
 def test_choosing_a_profile_file_selects_it_as_the_beam(dialog, tmp_path):
     """A loaded profile must not sit behind an analytical shape.
 
diff --git a/orgui/app/test/test_integration_options_dialog.py b/orgui/app/test/test_integration_options_dialog.py
index dae6dfd..e0ea0ca 100644
--- a/orgui/app/test/test_integration_options_dialog.py
+++ b/orgui/app/test/test_integration_options_dialog.py
@@ -2,9 +2,11 @@
 
 from types import SimpleNamespace
 
+import numpy as np
 import pytest
 from silx.gui import qt
 
+from orgui.app.config_data import CorrectionState
 from orgui.app.QScanSelector import IntegrationOptionsDialog
 
 
@@ -17,10 +19,22 @@ def qapp():
     return application
 
 
-def _selector():
+class _Scan:
+    """Minimal scan exposing one rate-like beam monitor."""
+
+    auxillary_counters = ("ic2", "temperature")
+    ic2 = np.array([10.0, 11.0, 12.0])
+    temperature = np.array([295.0, 295.1, 295.2])
+    exposure_time = np.array([1.0, 2.0, 3.0])
+
+    def __len__(self):
+        return 3
+
+
+def _selector(main=None, *, rocking=False):
     """Return the correction state needed by the options dialog."""
-    return SimpleNamespace(
-        parentmainwindow=None,
+    selector = SimpleNamespace(
+        parentmainwindow=main,
         useMaskBox=qt.QCheckBox("Use pixel mask"),
         useSolidAngleBox=qt.QCheckBox("Solid angle correction"),
         usePolarizationBox=qt.QCheckBox("Polarization correction"),
@@ -28,6 +42,12 @@ def _selector():
         useFootprintBox=qt.QCheckBox("Beam footprint"),
         useNormalizationBox=qt.QCheckBox("Normalize integrated intensities"),
     )
+    if rocking:
+        selector.scanstab = qt.QTabWidget()
+        for name in ("stationary", "other", "rocking", "reflectivity"):
+            selector.scanstab.addTab(qt.QWidget(), name)
+        selector.scanstab.setCurrentIndex(2)
+    return selector
 
 
 def test_close_and_reopen_preserves_contents_and_settings(qapp):
@@ -43,9 +63,9 @@ def test_close_and_reopen_preserves_contents_and_settings(qapp):
 
         assert not dialog.testAttribute(qt.Qt.WA_DeleteOnClose)
         assert {group.title() for group in groups} == {
-            "Detector corrections",
-            "Geometrical corrections",
-            "Exposure and monitor normalization",
+            "Detector signal",
+            "Incident beam",
+            "CTR result",
         }
 
         dialog.close()
@@ -61,3 +81,120 @@ def test_close_and_reopen_preserves_contents_and_settings(qapp):
     finally:
         dialog.deleteLater()
         main_window.deleteLater()
+
+
+def test_new_session_uses_relative_total_flux_and_requires_horizontal_choice(qapp):
+    """A new session is explicit about its relative and incomplete scale."""
+    main = qt.QMainWindow()
+    main.fscan = _Scan()
+    selector = _selector(main)
+    dialog = IntegrationOptionsDialog(selector, parent=main)
+    try:
+        assert dialog.scaleModeCombo.currentData() == "relative"
+        assert main.ctr_correction_state.total_flux_calibrated is False
+        assert "Relative scale pending" in dialog.scaleStatus.text()
+        assert "horizontal interception" in dialog.scaleStatus.text()
+        assert "No primary monitor" == dialog.primaryMonitorCombo.currentText()
+    finally:
+        dialog.deleteLater()
+        main.deleteLater()
+
+
+def test_calibrated_rate_monitor_is_one_counter_with_exposure_once(qapp):
+    """A rate-like monitor such as QM2 ic2 multiplies one frame exposure."""
+    main = qt.QMainWindow()
+    main.fscan = _Scan()
+    selector = _selector(main)
+    dialog = IntegrationOptionsDialog(selector, parent=main)
+    try:
+        selector.useNormalizationBox.setChecked(True)
+        selector.useFootprintBox.setChecked(True)
+        dialog.scaleModeCombo.setCurrentIndex(
+            dialog.scaleModeCombo.findData("calibrated")
+        )
+        dialog.totalFluxEdit.setText("2.5e10")
+        dialog.primaryMonitorCombo.setCurrentIndex(
+            dialog.primaryMonitorCombo.findData("ic2")
+        )
+        dialog.monitorKindCombo.setCurrentIndex(
+            dialog.monitorKindCombo.findData("rate")
+        )
+        dialog.monitorUnitEdit.setText("counts/s")
+        dialog.referenceMonitorEdit.setText("1000")
+        footprint = dialog.footprintOptions_shared()
+        footprint.setHorizontalInterception("full")
+        dialog._onTotalFluxChanged()
+
+        state = main.ctr_correction_state
+        assert state.total_incident_flux == pytest.approx(2.5e10)
+        assert state.primary_monitor == "ic2"
+        assert state.primary_monitor_kind == "rate"
+        assert state.monitor_reference_exposure_s is None
+        assert "exposure × M/Mref" in dialog.normalizationFormula.text()
+        assert "Calibrated F² scale" in dialog.scaleStatus.text()
+    finally:
+        dialog.deleteLater()
+        main.deleteLater()
+
+
+def test_integrated_monitor_formula_does_not_apply_frame_exposure_twice(qapp):
+    """Integrated counters use their own accumulated frame exposure."""
+    main = qt.QMainWindow()
+    main.fscan = _Scan()
+    selector = _selector(main)
+    dialog = IntegrationOptionsDialog(selector, parent=main)
+    try:
+        dialog.scaleModeCombo.setCurrentIndex(
+            dialog.scaleModeCombo.findData("calibrated")
+        )
+        dialog.primaryMonitorCombo.setCurrentIndex(
+            dialog.primaryMonitorCombo.findData("ic2")
+        )
+        dialog.monitorKindCombo.setCurrentIndex(
+            dialog.monitorKindCombo.findData("integrated")
+        )
+        dialog._onTotalFluxChanged()
+
+        assert "no second frame exposure" in dialog.normalizationFormula.text()
+        assert dialog.referenceExposureEdit.isEnabled()
+        assert "positive reference exposure" in dialog.scaleStatus.text()
+    finally:
+        dialog.deleteLater()
+        main.deleteLater()
+
+
+def test_legacy_multi_monitor_settings_remain_separate_and_labeled(qapp):
+    """Opening an old configuration does not reinterpret its monitor product."""
+    main = qt.QMainWindow()
+    main.fscan = _Scan()
+    main.ctr_correction_state = CorrectionState(
+        normalize_exposure=True,
+        monitor_corrections=("ic2", "temperature"),
+    )
+    main.reconstruction_normalize_exposure = True
+    main.reconstruction_monitor_corrections = ("ic2", "temperature")
+    selector = _selector(main)
+    dialog = IntegrationOptionsDialog(selector, parent=main)
+    try:
+        assert dialog.scaleModeCombo.currentData() == "legacy"
+        assert dialog.monitorEdit.text() == "ic2, temperature"
+        assert "Legacy density/area convention" in dialog.scaleStatus.text()
+        assert dialog.primaryMonitorCombo.currentData() == ""
+    finally:
+        dialog.deleteLater()
+        main.deleteLater()
+
+
+def test_rocking_scan_reports_that_ctr_is_calculated_during_reduction(qapp):
+    """The extraction dialog identifies the later rocking-reducer boundary."""
+    main = qt.QMainWindow()
+    selector = _selector(main, rocking=True)
+    dialog = IntegrationOptionsDialog(selector, parent=main)
+    try:
+        assert "calculated after rocking-curve integration" in (
+            dialog.measurementModeInfo.text()
+        )
+        assert "angular acceptance" in dialog.measurementModeInfo.text()
+    finally:
+        dialog.deleteLater()
+        main.deleteLater()
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index 7feb928..aa04a1c 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -32,6 +32,11 @@
     _compute_rocking_integration,
     _trapz_impl,
 )
+from orgui.app.integration_corrections import (
+    FOOTPRINT_APPLY,
+    FOOTPRINT_KEEP,
+    FOOTPRINT_REMOVE,
+)
 
 
 def _piecewise_curve(axis, regions, background=0.0):
@@ -858,6 +863,56 @@ def test_versioned_total_flux_curve_uses_stored_divisors_once(tmp_path):
     assert curves["illumination_action"] == "applied"
 
 
+def test_unknown_legacy_curve_only_allows_keep_and_requests_reextraction():
+    """Unknown provenance cannot expose apply/remove as safe operations."""
+    state = RockingPeakIntegrator._correctionUiState(
+        None, record_present=False
+    )
+
+    assert state["actions"] == (FOOTPRINT_KEEP,)
+    assert state["normalization"] == "Unknown (legacy data)"
+    assert "Re-extract images" in state["details"]
+
+
+def test_known_legacy_curve_allows_current_legacy_footprint_only():
+    """A typed legacy record retains the old, explicitly labeled workflow."""
+    record = CurveCorrectionRecord(
+        algorithm="legacy_rocking_roi_v1",
+        output_quantity="legacy_roi_curve",
+        scale_convention="legacy_relative",
+    )
+    state = RockingPeakIntegrator._correctionUiState(record)
+
+    assert state["actions"] == (FOOTPRINT_KEEP, FOOTPRINT_APPLY)
+    assert state["normalization"] == "Applied later by the legacy reducer"
+    assert FOOTPRINT_REMOVE not in state["actions"]
+
+
+def test_reversible_total_flux_curve_exposes_keep_apply_and_remove():
+    """All three actions are safe only with a known reversible base curve."""
+    record = CurveCorrectionRecord(
+        algorithm="framewise_ctr_total_flux_v1",
+        output_quantity="rocking_ctr_photon_curve",
+        scale_convention="total_flux_relative",
+        normalization_status="applied",
+        illumination_status="applied",
+        illumination_divisor=np.ones(3),
+        illumination_convention="total_flux_H",
+        base_croibg=np.ones((2, 3)),
+        base_croibg_variance=np.ones((2, 3)),
+    )
+    state = RockingPeakIntegrator._correctionUiState(record)
+
+    assert state["actions"] == (
+        FOOTPRINT_KEEP,
+        FOOTPRINT_APPLY,
+        FOOTPRINT_REMOVE,
+    )
+    assert state["normalization"] == "Applied during extraction"
+    assert state["footprint"] == "Applied during extraction"
+    assert "total_flux_H" in state["details"]
+
+
 @pytest.mark.parametrize("applied_at_extraction", [True, False])
 def test_the_typed_corrections_group_is_read_back(applied_at_extraction):
     """The F6 compensation must survive the layout it is stored in.

From 8116639dcc510f237e976cf2b4b54c03f6d05ce9 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Thu, 17 Sep 2026 11:33:06 -0400
Subject: [PATCH 27/33] test(phys): validate total-flux CTR workflow

---
 CHANGELOG.md                                  |  15 +
 doc/design/ctr_structure_factor_scale.md      |  13 +-
 doc/source/ctr_structure_factors.rst          |  37 +-
 doc/source/image_integration.rst              |  77 ++-
 doc/source/release_notes.rst                  |  10 +-
 orgui/app/test/test_ctr_forward_validation.py | 441 ++++++++++++++++++
 6 files changed, 564 insertions(+), 29 deletions(-)
 create mode 100644 orgui/app/test/test_ctr_forward_validation.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a572b78..596a7ea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,21 @@ This is the changelog for the software orGUI, written by Timo Fuchs
 
 Scientific and analysis additions:
 
+- **The end-to-end CTR correction contract now has an independent
+  calibrated-pixel forward validation and published limits.** A finite-width
+  Gaussian rod is simulated directly on calibrated detector rays without using the
+  production normalization, illumination, angular-factor or structure-factor
+  helpers, then reduced through the stationary and rocking workflows. The
+  matrix covers changing flux/exposure, rate-like and integrated monitors,
+  measured-profile width and offset, moving detector arms, complete and
+  clipped ROIs, and convergence of the rocking quadrature before its tolerance
+  is chosen. Finite apertures are compared with their resolution-weighted
+  structure-factor integral rather than a point value. No distributable raw
+  CTR scan with independent absolute-flux calibration is present, so the docs
+  deliberately stop short of a real-data absolute-accuracy claim and identify
+  detector efficiency, external transmission and in-plane acceptance as the
+  remaining experimental inputs.
+
 - **CTR correction controls now state what is saved and what the next
   operation will do.** The integration dialog separates detector signal,
   incident beam and CTR result settings; new sessions use an explicitly
diff --git a/doc/design/ctr_structure_factor_scale.md b/doc/design/ctr_structure_factor_scale.md
index 4a14c9c..2c99a91 100644
--- a/doc/design/ctr_structure_factor_scale.md
+++ b/doc/design/ctr_structure_factor_scale.md
@@ -1,7 +1,11 @@
 # One structure-factor scale for rocking scans, stationary scans and reflectivity
 
-> **Status: analysis complete, reduction landed and wired into both
-> integration paths.** This is the review document for
+> **Status: superseded as an implementation status document.** The reduction
+> described here is now wired into both integration paths, and the final
+> user-facing total-flux contract, assumptions and validation limits are in
+> [`image_integration.rst`](../source/image_integration.rst) and
+> [`ctr_structure_factors.rst`](../source/ctr_structure_factors.rst). This is
+> retained as the review document for
 > [issue #82](https://github.com/tifuchs/orGUI/issues/82) ("Regression tests
 > and validation of equivalence of rocking and stationary scan integration")
 > and for the physics half of
@@ -21,7 +25,10 @@
 > below as they stand. Findings are written in the present tense
 > of the analysis; section 5 says what each one's status is now, and
 > [`ctr_structure_factor_handover.md`](ctr_structure_factor_handover.md)
-> section 5 says how each was wired.
+> section 5 says how each was wired. Later total-flux work replaces the
+> document's remaining-absolute-scale status: calibrated `|F|^2` is now
+> available, with detector efficiency, external transmission and in-plane
+> acceptance retained as explicit experimental limitations.
 
 ## 1. What the two papers require
 
diff --git a/doc/source/ctr_structure_factors.rst b/doc/source/ctr_structure_factors.rst
index 68c8391..0898f67 100644
--- a/doc/source/ctr_structure_factors.rst
+++ b/doc/source/ctr_structure_factors.rst
@@ -138,13 +138,14 @@ set of truncation rods can be brought onto one scale before they are combined.
 The relation is kinematical: it does not hold near a bulk Bragg peak, nor below
 the critical angle, where the distorted-wave treatment of :doc:`dwba` applies.
 
-Total-incident-flux numerical API
----------------------------------
+Total-incident-flux measurement contract
+----------------------------------------
 
-The correction core provides an explicit alternative to the legacy peak-flux-
-density times effective-area convention. This API is available for scripted
-reductions, but is not yet selected by the integration dialogs or extraction
-paths.
+The correction core and both integration paths provide an explicit alternative
+to the legacy peak-flux-density times effective-area convention. New sessions
+default to a relative total-flux contract; calibrated output is opt-in and is
+labeled separately. Legacy saved configurations retain their old numerical
+meaning.
 
 ``corrections.normalization.frame_fluence`` calculates incident photons
 :math:`Q_f` in a frame. A rate-like monitor is multiplied by that frame's
@@ -177,6 +178,30 @@ mode angular factor and the total-flux prefactor
 unit-cell area in square Angstrom. Existing ``scale_factor`` and
 ``structure_factor_squared`` calls keep their flux-density semantics.
 
+The integration dialog stores the exact :math:`Q_f` and :math:`H` arrays used
+for every extracted curve, together with applied/not-applied status, monitor
+kind and units, beam-profile provenance, detector-arm/ROI geometry and the
+scale convention. A rocking reduction always reconstructs from the immutable
+polarization-only base curve before applying these divisors; keep, remove and
+replace actions therefore cannot compound a correction. Unknown legacy
+provenance is rejected rather than guessed.
+
+For calibrated total flux, stationary and rocking results additionally divide
+by :math:`K`. Detector efficiency and external transmission are currently
+explicit unity assumptions. The numerical contract has an independent
+finite-width Gaussian-rod forward test evaluated on calibrated detector rays.
+It varies flux, exposure, rate-like/integrated monitors, beam width/offset,
+detector arms and ROI clipping, and establishes rocking-grid convergence
+before setting tolerances. A finite or clipped ROI is compared with its
+resolution-weighted :math:`|F|^2` integral, not with an unrelated point value.
+
+No distributable raw CTR scan with independently calibrated incident flux is
+present in the repository. Consequently this validation establishes the
+implemented numerical contract but not beamline-specific absolute accuracy.
+That still requires a real standard measurement, detector efficiency and
+external transmission, and characterization of the in-plane acceptance
+:math:`C_\mathrm{det}` when the ROI does not contain the complete peak.
+
 CTR fit predictions and statistics
 ----------------------------------
 
diff --git a/doc/source/image_integration.rst b/doc/source/image_integration.rst
index 9451837..c869ded 100644
--- a/doc/source/image_integration.rst
+++ b/doc/source/image_integration.rst
@@ -242,11 +242,28 @@ acceptance that was divided out, whether the direct photon curve or legacy
 solid-angle compensation was used, and the active-area assumption, so that a
 saved rod can be placed on a common scale after the fact.
 
-What is still **not** on this scale is the absolute one: ``F2_hkl`` is
-proportional to :math:`|F_{hkl}|^2` with one common, arbitrary constant.
-:mod:`orgui.datautils.xrayutils.corrections.measurement` supplies the absolute
-prefactor given the incident flux density and the illuminated area, and
-converts between :math:`|F_{hkl}|^2` and absolute reflectivity.
+The scale is selected explicitly in the correction dialog. ``Relative
+total-flux`` produces a common relative ``F2_hkl`` scale. ``Calibrated
+total-flux`` additionally requires the incident photon flux, monitor
+calibration, wavelength and surface unit-cell area, and applies
+:math:`K=r_e^2\lambda^2/A_u^2`; its output is :math:`|F_{hkl}|^2` in electron
+units squared. Detector efficiency and external transmission are currently
+recorded unity assumptions, not inferred corrections. The older flux-density
+and numerical-active-area path remains available as ``Legacy`` and is not
+reinterpreted as total flux.
+
+This contract has independent simulated forward validation on calibrated
+pixel rays, including rate-like and integrated monitors, changing exposure,
+moving detector arms, full and clipped regions, measured beam profiles and
+rocking-grid convergence. The repository does not contain a distributable raw
+CTR scan with independently calibrated flux, so no real-data absolute-accuracy
+claim is made. In-plane detector acceptance :math:`C_\mathrm{det}` also remains
+an experimental responsibility: the reduction assumes a region wide enough
+to contain the complete in-plane peak unless clipping is deliberately retained
+as part of the measured resolution integral.
+
+:mod:`orgui.datautils.xrayutils.corrections.measurement` contains the pure
+forward/inverse functions and the absolute-reflectivity conversion.
 ``doc/physics/ctr_structure_factor_physics.tex`` is a typeset reference for
 every normalization and integration interval described here.
 
@@ -254,23 +271,47 @@ every normalization and integration interval described here.
 Exposure and Monitor Normalization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``Normalize integrated intensities`` divides every image by its exposure time
-and by each configured monitor counter, the same normalization the
-reciprocal-space reconstruction applies, so an integration and a
-reconstruction of one scan are normalized identically. The settings are
-shared: changing them here changes them for the reconstruction and the other
-way round.
-
-A scan backend that provides no exposure time is not an error; the exposure
-part of the normalization is then skipped. A monitor counter that is missing,
-zero or non-finite does stop the integration, since it would otherwise scale
-intensities by infinity. The dialog lists the counters of the loaded scan that
-can be used.
+For the total-flux convention, ``Normalize integrated intensities`` stores one
+fluence divisor :math:`Q_f` per frame. The selected primary monitor must be
+declared ``rate-like`` or ``integrated``. A rate-like ion chamber such as an
+``ic2`` counts-per-second channel uses
+``flux * exposure * monitor / reference``. An integrated monitor already
+contains the frame exposure and uses
+``flux * reference_exposure * monitor / reference``. Exposure therefore
+enters exactly once. The dialog shows the effective formula and units; it does
+not infer monitor kind from a counter name.
+
+Without a flux calibration, the same exposure rule produces a relative
+fluence and the saved scale remains explicitly relative. The legacy
+normalization continues to divide by exposure and by every selected monitor
+counter, matching reciprocal-space reconstruction, but it is labeled as a
+counter product rather than photons.
+
+In the legacy path, a scan backend that provides no exposure time skips that
+part of the normalization. In the total-flux path, missing inputs required by
+the selected monitor convention stop extraction. A monitor counter that is
+missing, zero or non-finite always stops the integration, since it would
+otherwise produce an undefined scale. The dialog lists compatible one-value-
+per-frame counters from the loaded scan.
 
 Footprint Corrections
 ~~~~~~~~~~~~~~~~~~~~~
 
-``Beam footprint`` applies one numerical active-area correction that depends
+In the total-flux convention, ``Beam footprint`` uses the vertical beam
+profile and an explicit horizontal interception choice, and applies the
+dimensionless divisor
+
+.. math::
+
+   H = \frac{f_z f_x}{\sin\alpha},
+
+where :math:`f_z` is the vertical intercepted fraction and :math:`f_x` is the
+stated full or fractional horizontal interception. Both :math:`Q_f` and
+:math:`H` must be applied before the result may be labeled ``F2_hkl``. The
+intercepted photon fraction itself is :math:`f_zf_x`, not :math:`H`.
+
+The legacy ``Beam footprint`` convention applies one numerical active-area
+correction that depends
 on the incidence angle :math:`\alpha` and on the
 vertical profile :math:`p(z)` of the incident beam, normalized to
 :math:`\int p(z)\,\mathrm{d}z = 1`. With a sample of length :math:`L` along the
diff --git a/doc/source/release_notes.rst b/doc/source/release_notes.rst
index 44107da..c6f7aed 100644
--- a/doc/source/release_notes.rst
+++ b/doc/source/release_notes.rst
@@ -9,9 +9,15 @@ Unreleased (2026-07-19)
 
 Scientific and analysis additions:
 
-- **The numerical correction core now has an explicit total-incident-flux convention.** New pure APIs calculate calibrated photons per frame from a constant flux or an explicitly rate-like/integrated monitor, distinguish the intercepted fraction from the dimensionless illumination divisor ``H = f_hit / sin(alpha)``, and reduce photon-normalized yield with ``K = r_e^2 lambda^2 / A_u^2``. Built-in beam profiles retain the finite grazing-incidence limit, and horizontal interception must be stated separately because a vertical profile cannot infer it. This stage adds the unit-audited numerical path only: current extraction/UI behavior and the legacy flux-density APIs remain unchanged until the later wiring stage.
+- **The end-to-end CTR correction contract now has an independent calibrated-pixel forward validation and published limits.** A finite-width Gaussian rod is simulated directly on calibrated detector rays without using the production normalization, illumination, angular-factor or structure-factor helpers, then reduced through the stationary and rocking workflows. The matrix covers changing flux/exposure, rate-like and integrated monitors, measured-profile width and offset, moving detector arms, complete and clipped ROIs, and convergence of the rocking quadrature before its tolerance is chosen. Finite apertures are compared with their resolution-weighted structure-factor integral rather than a point value. No distributable raw CTR scan with independent absolute-flux calibration is present, so the docs deliberately stop short of a real-data absolute-accuracy claim and identify detector efficiency, external transmission and in-plane acceptance as the remaining experimental inputs.
 
-- **Saved CTR curves now carry a versioned correction record.** This is a persistence-only compatibility step: numerical defaults and the established ``rois``, ``croibg`` and ``Cfactors_*`` meanings are unchanged. A separate ``ctr_curve_v3`` branch records the reversible pre-normalization scalar curve and variance, exact applied normalization and illumination divisors, explicit applied/not-applied/unavailable/unknown states, pixel-factor provenance, detector-arm/ROI geometry and embedded beam-profile data. The requested correction settings schema is version 3 and stores total incident flux separately from the legacy flux density, together with primary-monitor kind/reference and horizontal-interception fields; absent values remain unknown rather than physical zero or unity. The rocking reducer explicitly accepts the unchanged legacy-algorithm record but refuses a future frame-normalized record until its dedicated dispatch path is implemented, preventing it from silently normalizing a new curve twice.
+- **CTR correction controls now state what is saved and what the next operation will do.** The integration dialog separates detector signal, incident beam and CTR result settings; new sessions use an explicitly relative total-flux convention, while calibrated photon flux, one rate-like or integrated primary monitor, its calibration reference and the effective normalization formula are shown with units. Legacy flux density and multi-monitor products remain labeled and are not reinterpreted. Horizontal interception must be selected as full or as a known fraction; unresolved imported settings stay ``Not specified``. The rocking reducer shows the loaded curve's saved normalization/footprint provenance separately from the next reduction and replaces the footprint checkbox with safe keep/apply/remove actions. Unknown legacy provenance disables replacement and removal and directs the user to re-extract rather than guessing.
+
+- **The numerical correction core now has an explicit total-incident-flux convention.** New pure APIs calculate calibrated photons per frame from a constant flux or an explicitly rate-like/integrated monitor, distinguish the intercepted fraction from the dimensionless illumination divisor ``H = f_hit / sin(alpha)``, and reduce photon-normalized yield with ``K = r_e^2 lambda^2 / A_u^2``. Built-in beam profiles retain the finite grazing-incidence limit, and horizontal interception must be stated separately because a vertical profile cannot infer it. This stage adds the unit-audited numerical path; the extraction/reduction wiring described below activates it only for explicit version-3 settings. Legacy flux-density APIs retain their original units and meaning.
+
+- **Stationary and rocking CTR integrations now share one framewise total-flux policy.** An explicitly configured primary monitor is classified as a rate or an integrated reading, so exposure enters its photon-fluence divisor exactly once; an ``ic2``-style ion-chamber rate is therefore handled as ``exposure * monitor_rate`` before applying its calibration factor. New total-flux curves require both the stored incident-photon divisor ``Q`` and the stated horizontal plus calculated vertical illumination divisor ``H`` before they can be labeled ``F2_hkl``. Stationary scans form that result immediately. Rocking scans keep the existing later reduction step, but the reducer now recognizes ``framewise_ctr_total_flux_v1``, reconstructs the curve from its immutable polarization-only base values and exact stored Q/H arrays, and does not call the live legacy normalization or footprint path a second time. Calibrated curves additionally use the stored wavelength and surface unit-cell area with ``r_e^2 lambda^2 / A_u^2``; detector efficiency and external transmission remain explicit unity assumptions. Footprint keep/remove/replace operations always restart from the saved base curve, reject unknown provenance, and require explicit permission to cross between the legacy active-area and new total-flux conventions. Legacy databases and reconstruction defaults retain their existing numerical behavior.
+
+- **Saved CTR curves now carry a versioned correction record.** This is a persistence-only compatibility step: numerical defaults and the established ``rois``, ``croibg`` and ``Cfactors_*`` meanings are unchanged. A separate ``ctr_curve_v3`` branch records the reversible pre-normalization scalar curve and variance, exact applied normalization and illumination divisors, explicit applied/not-applied/unavailable/unknown states, pixel-factor provenance, detector-arm/ROI geometry and embedded beam-profile data. The requested correction settings schema is version 3 and stores total incident flux separately from the legacy flux density, together with primary-monitor kind/reference and horizontal-interception fields; absent values remain unknown rather than physical zero or unity. The rocking reducer explicitly accepts unchanged legacy-algorithm records, dispatches the supported total-flux algorithm through its stored divisors, and refuses any other normalized contract, preventing it from silently normalizing a new curve twice.
 
 - **The polarization correction now follows the detector arm.** *This changes saved numbers for scans that move the detector arm and for arm-corrected integrations using a nonzero configured polarization axis; the conventional axis-zero case is unchanged.* The per-pixel polarization array is built from the calibrated geometry, which is right only while the arm stays there. On a scan that drives the arm -- a reflectivity curve, where it follows twice the incidence angle -- the same pixel looks in a different direction on every frame, and the calibrated-position value understated the correction by 3 % at a scattering angle of 10 degrees, 10 % at 18 and 33 % at 30. Both integration paths now apply a per-frame factor, ``corrections.detector.polarization_arm_correction``, that moves the correction onto the arm position each frame was measured at. It is exactly one while the arm sits at its calibrated position when both paths use the same configured polarization axis, so an axis-zero fixed-arm scan is bit-identical and needs no switch. The factor is a ratio of two region means rather than a rebuilt per-pixel array, which keeps the cost to a region-sized evaluation per frame; the polarization is not flat across a region at a large scattering angle, so the means matter. The arm-following evaluator now rotates the incident electric-field basis by the configured ``polarization_axis``, matching the calibrated array for zero, 90-degree and intermediate axes and for mixed polarization fractions; it previously assumed an axis of zero. The detector solid angle needs no such correction: an arm rotation is a rigid rotation about the sample, so every pixel keeps its distance and its obliquity to its own line of sight, and the solid angle is invariant under it exactly. The reciprocal-space reconstruction applies the polarization per pixel rather than as a region mean and is unchanged; correcting it there would need the array rebuilt per frame.
 
diff --git a/orgui/app/test/test_ctr_forward_validation.py b/orgui/app/test/test_ctr_forward_validation.py
new file mode 100644
index 0000000..2ffb866
--- /dev/null
+++ b/orgui/app/test/test_ctr_forward_validation.py
@@ -0,0 +1,441 @@
+"""Independent forward validation of the calibrated CTR reduction path.
+
+The simulated counts below are assembled directly on calibrated detector rays
+from the measurement equation.  In particular, the forward calculation does
+not call the production structure-factor, normalization, illumination or
+angular-factor helpers.  The production reduction is then required to recover
+the explicitly quadrature-averaged input ``|F|^2``.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+import pytest
+
+pyFAI = pytest.importorskip("pyFAI")
+
+from orgui.app.config_data import CorrectionState, CurveCorrectionRecord  # noqa: E402
+from orgui.app.integration_corrections import (  # noqa: E402
+    apply_stationary_corrections,
+    corrected_curve_from_record,
+    frame_correction_policy,
+    stationary_correction_factors,
+    structure_factor_from_policy,
+)
+from orgui.app.peak1Dintegr import _compute_rocking_integration  # noqa: E402
+from orgui.datautils.xrayutils import DetectorCalibration  # noqa: E402
+from orgui.datautils.xrayutils.corrections import acceptance, beamprofile  # noqa: E402
+
+
+ELECTRON_RADIUS_M = 2.8179403262e-15
+WAVELENGTH_ANGSTROM = 0.7005
+UNIT_CELL_AREA_ANGSTROM2 = 15.8
+PIXEL_M = 172e-6
+DISTANCE_M = 0.24
+SHAPE = (241, 261)
+
+
+@dataclass
+class _Scan:
+    """Small scan object exposing the counters used by the policy adapter."""
+
+    exposure_time: np.ndarray
+    monitor: np.ndarray
+
+    @property
+    def auxillary_counters(self):
+        return ("monitor",)
+
+    def __len__(self):
+        return self.exposure_time.size
+
+
+def _detector():
+    """Return a calibrated flat detector with nontrivial arm geometry."""
+    detector = DetectorCalibration.Detector2D_SXRD()
+    detector.detector = pyFAI.detectors.Detector(
+        pixel1=PIXEL_M, pixel2=PIXEL_M, max_shape=SHAPE
+    )
+    detector.poni1 = SHAPE[0] * PIXEL_M / 2.0
+    detector.poni2 = SHAPE[1] * PIXEL_M / 2.0
+    detector.rot1 = detector.rot2 = detector.rot3 = 0.0
+    detector.dist = DISTANCE_M
+    detector.set_energy(17.7)
+    detector.setAzimuthalReference(np.deg2rad(90.0))
+    detector.setPolarization(0.0, 1.0)
+    detector.reset()
+    detector._cached_array = {}
+    return detector
+
+
+def _prefactor():
+    """Independent evaluation of ``r_e**2 lambda**2 / A_u**2``."""
+    wavelength_m = WAVELENGTH_ANGSTROM * 1e-10
+    area_m2 = UNIT_CELL_AREA_ANGSTROM2 * 1e-20
+    return ELECTRON_RADIUS_M**2 * wavelength_m**2 / area_m2**2
+
+
+def _profile(fwhm_m, offset_m):
+    """A densely sampled measured profile, including a sample offset."""
+    sigma = fwhm_m / np.sqrt(8.0 * np.log(2.0))
+    z = np.linspace(-8.0 * sigma, 8.0 * sigma, 4001)
+    density = np.exp(-0.5 * (z / sigma) ** 2)
+    return beamprofile.MeasuredBeamProfile(z, density, offset=offset_m)
+
+
+def _piecewise_integral(x, y, lower, upper):
+    """Integrate tabulated linear data without using the beam-profile API."""
+    points = np.concatenate(
+        ([lower], x[(x > lower) & (x < upper)], [upper])
+    )
+    values = np.interp(points, x, y, left=0.0, right=0.0)
+    return np.trapezoid(values, points)
+
+
+def _independent_illumination(profile, alpha, length, horizontal):
+    """Evaluate ``H = f_z f_x / sin(alpha)`` from the sampled profile."""
+    result = []
+    for angle in np.atleast_1d(alpha):
+        projected = length * np.sin(angle)
+        fraction = _piecewise_integral(
+            profile.z, profile.density, -projected / 2.0, projected / 2.0
+        )
+        result.append(fraction * horizontal / np.sin(angle))
+    return np.asarray(result)
+
+
+def _independent_fluence(
+    flux, exposure, monitor, monitor_kind, reference, reference_exposure
+):
+    """Calculate photons per frame from the stated monitor convention."""
+    if monitor_kind == "rate":
+        return flux * exposure * monitor / reference
+    return flux * reference_exposure * monitor / reference
+
+
+def _state(flux, monitor_kind, reference, reference_exposure, horizontal):
+    """Return an explicitly calibrated total-flux correction state."""
+    return CorrectionState(
+        use_normalization=True,
+        use_footprint=True,
+        total_incident_flux=flux,
+        total_flux_calibrated=True,
+        primary_monitor="monitor",
+        primary_monitor_kind=monitor_kind,
+        primary_monitor_unit=("counts/s" if monitor_kind == "rate" else "counts"),
+        monitor_reference_reading=reference,
+        monitor_reference_exposure_s=(
+            reference_exposure if monitor_kind == "integrated" else None
+        ),
+        horizontal_interception="fraction",
+        horizontal_intercepted_fraction=horizontal,
+    )
+
+
+def _pixel_rays(detector, center, size, alpha, gamma_arm, delta_arm):
+    """Return calibrated ray angles and edge-to-edge angular pixel widths."""
+    row0, column0 = center
+    rows, columns = size
+    row = row0 + np.arange(rows) - (rows - 1.0) / 2.0
+    column = column0 + np.arange(columns) - (columns - 1.0) / 2.0
+    rr, cc = np.meshgrid(row, column, indexing="ij")
+    args = (alpha, gamma_arm, delta_arm)
+    gamma, delta = detector.surfaceAnglesPoint(rr, cc, *args)
+    gamma_low = detector.surfaceAnglesPoint(rr - 0.5, cc, *args)[0]
+    gamma_high = detector.surfaceAnglesPoint(rr + 0.5, cc, *args)[0]
+    delta_low = detector.surfaceAnglesPoint(rr, cc - 0.5, *args)[1]
+    delta_high = detector.surfaceAnglesPoint(rr, cc + 0.5, *args)[1]
+    return (
+        np.asarray(gamma),
+        np.asarray(delta),
+        np.abs(np.asarray(gamma_high) - np.asarray(gamma_low)),
+        np.abs(np.asarray(delta_high) - np.asarray(delta_low)),
+    )
+
+
+def _polarization(alpha, gamma, delta):
+    """Horizontal-polarization factor written independently from the model."""
+    projection = (
+        np.sin(alpha) * np.cos(delta) * np.cos(gamma)
+        + np.cos(alpha) * np.sin(gamma)
+    )
+    return 1.0 - projection**2
+
+
+def _f2_profile(gamma, center, sigma):
+    """A smooth, finite-width rod whose value varies across the aperture."""
+    coordinate = (gamma - center) / sigma
+    return 420.0 * (1.0 + 0.08 * coordinate + 0.035 * coordinate**2)
+
+
+@pytest.mark.parametrize(
+    "monitor_kind, roi_size, arms, fwhm_um, offset_um, horizontal",
+    [
+        ("rate", (41, 39), (0.08, 0.11), 34.0, 0.0, 1.0),
+        ("integrated", (9, 11), (0.14, 0.22), 76.0, 19.0, 0.63),
+    ],
+)
+def test_stationary_reduction_recovers_the_pixel_ray_resolution_average(
+    monitor_kind, roi_size, arms, fwhm_um, offset_um, horizontal
+):
+    """Flux, exposure, arm position, ROI clipping and footprint all cancel."""
+    detector = _detector()
+    center = (145.0, 169.0)
+    alpha = np.array([0.018, 0.032, 0.051])
+    gamma_arm = arms[0] + np.array([-0.012, 0.0, 0.017])
+    delta_arm = arms[1] + np.array([-0.018, 0.0, 0.021])
+    exposure = np.array([0.37, 0.82, 1.41])
+    reference = 2.4e6
+    reference_exposure = 0.65
+    if monitor_kind == "rate":
+        monitor = reference * np.array([0.72, 1.13, 0.91])
+    else:
+        monitor = reference * exposure / reference_exposure
+        monitor *= np.array([0.72, 1.13, 0.91])
+    scan = _Scan(exposure, monitor)
+    flux = 3.7e10
+    length = 4.2e-3
+    profile = _profile(fwhm_um * 1e-6, offset_um * 1e-6)
+    state = _state(
+        flux, monitor_kind, reference, reference_exposure, horizontal
+    )
+
+    policy = frame_correction_policy(
+        scan,
+        state,
+        alpha.size,
+        use_normalization=True,
+        use_illumination=True,
+        alpha=alpha,
+        beam_profile=profile,
+        sample_length=length,
+    )
+    q_forward = _independent_fluence(
+        flux,
+        exposure,
+        monitor,
+        monitor_kind,
+        reference,
+        reference_exposure,
+    )
+    h_forward = _independent_illumination(profile, alpha, length, horizontal)
+    np.testing.assert_allclose(policy.normalization_divisor, q_forward, rtol=2e-14)
+    np.testing.assert_allclose(policy.illumination_divisor, h_forward, rtol=2e-12)
+
+    raw = []
+    expected = []
+    center_gamma = []
+    center_delta = []
+    for index in range(alpha.size):
+        gamma, delta, dgamma, ddelta = _pixel_rays(
+            detector,
+            center,
+            roi_size,
+            alpha[index],
+            gamma_arm[index],
+            delta_arm[index],
+        )
+        gamma0, delta0 = detector.surfaceAnglesPoint(
+            np.array([center[0]]),
+            np.array([center[1]]),
+            alpha[index],
+            gamma_arm[index],
+            delta_arm[index],
+        )
+        gamma0, delta0 = float(gamma0[0]), float(delta0[0])
+        center_gamma.append(gamma0)
+        center_delta.append(delta0)
+        sigma_gamma = 3.6 * PIXEL_M / DISTANCE_M
+        sigma_delta = 3.1 * PIXEL_M / DISTANCE_M
+        resolution = np.exp(-0.5 * ((gamma - gamma0) / sigma_gamma) ** 2)
+        resolution *= np.exp(-0.5 * ((delta - delta0) / sigma_delta) ** 2)
+        resolution /= 2.0 * np.pi * sigma_gamma * sigma_delta
+        polarization = _polarization(alpha[index], gamma, delta)
+        f2 = _f2_profile(gamma, gamma0, sigma_gamma)
+        lorentz = 1.0 / np.sin(gamma)
+        quadrature = dgamma * ddelta
+        photon_sum = np.sum(
+            f2 * lorentz * polarization * resolution * quadrature
+        )
+        polarization_correction = np.mean(1.0 / polarization)
+        raw.append(
+            q_forward[index]
+            * h_forward[index]
+            * _prefactor()
+            * photon_sum
+            * polarization_correction
+        )
+        expected.append(
+            photon_sum * polarization_correction * np.sin(gamma0)
+        )
+
+    factors = stationary_correction_factors(
+        alpha,
+        np.asarray(center_delta),
+        np.asarray(center_gamma),
+        use_lorentz=True,
+        normalization=policy.normalization_divisor,
+        illumination_divisor=policy.illumination_divisor,
+    )
+    corrected, errors = apply_stationary_corrections(
+        np.asarray(raw), np.zeros(alpha.size), factors
+    )
+    actual, _ = structure_factor_from_policy(
+        corrected,
+        errors,
+        factors,
+        policy,
+        wavelength=WAVELENGTH_ANGSTROM,
+        unitcell_area=UNIT_CELL_AREA_ANGSTROM2,
+    )
+
+    # The forward target is a finite-resolution integral, not F2 at one ray.
+    expected = np.asarray(expected)
+    np.testing.assert_allclose(actual, expected, rtol=2e-10)
+    if min(roi_size) < 15:
+        point_f2 = _f2_profile(np.asarray(center_gamma), np.asarray(center_gamma), 1.0)
+        assert np.max(np.abs(actual / point_f2 - 1.0)) > 0.05
+
+
+def _rocking_result(sample_count, roi_size):
+    """Forward-simulate and reduce one rocking curve."""
+    detector = _detector()
+    center = (154.0, 171.0)
+    alpha = 0.031
+    gamma_arm, delta_arm = 0.105, 0.19
+    gamma, delta, dgamma, ddelta = _pixel_rays(
+        detector, center, roi_size, alpha, gamma_arm, delta_arm
+    )
+    gamma0, delta0 = detector.surfaceAnglesPoint(
+        np.array([center[0]]),
+        np.array([center[1]]),
+        alpha,
+        gamma_arm,
+        delta_arm,
+    )
+    gamma0, delta0 = float(gamma0[0]), float(delta0[0])
+    sigma_delta = 3.0 * PIXEL_M / DISTANCE_M
+    sigma_gamma = 4.0 * PIXEL_M / DISTANCE_M
+    transverse = np.exp(-0.5 * ((delta - delta0) / sigma_delta) ** 2)
+    transverse /= np.sqrt(2.0 * np.pi) * sigma_delta
+    polarization = _polarization(alpha, gamma, delta)
+    f2 = _f2_profile(gamma, gamma0, sigma_gamma)
+    cross_section = np.sum(
+        f2 * polarization * transverse * ddelta * dgamma
+    )
+    polarization_correction = np.mean(1.0 / polarization)
+
+    sigma_omega = np.deg2rad(0.055)
+    axis = np.linspace(-4.5 * sigma_omega, 4.5 * sigma_omega, sample_count)
+    rocking_profile = np.exp(-0.5 * (axis / sigma_omega) ** 2)
+    rocking_profile /= np.sqrt(2.0 * np.pi) * sigma_omega
+    exposure = 0.25 + 0.7 * (axis - axis.min()) / np.ptp(axis)
+    reference = 1.8e6
+    monitor = reference * (1.0 + 0.17 * np.sin(axis / sigma_omega))
+    scan = _Scan(exposure, monitor)
+    flux = 8.1e9
+    reference_exposure = 0.5
+    horizontal = 0.71
+    length = 3.8e-3
+    profile = _profile(58e-6, -13e-6)
+    state = _state(flux, "rate", reference, reference_exposure, horizontal)
+    policy = frame_correction_policy(
+        scan,
+        state,
+        sample_count,
+        use_normalization=True,
+        use_illumination=True,
+        alpha=np.full(sample_count, alpha),
+        beam_profile=profile,
+        sample_length=length,
+    )
+    q_forward = _independent_fluence(
+        flux, exposure, monitor, "rate", reference, reference_exposure
+    )
+    h_forward = _independent_illumination(
+        profile, np.full(sample_count, alpha), length, horizontal
+    )
+    lorentz = 1.0 / (
+        np.sin(delta0) * np.cos(alpha) * np.cos(gamma0)
+    )
+    rod = np.cos(gamma0)
+    base_curve = (
+        q_forward
+        * h_forward
+        * _prefactor()
+        * lorentz
+        * rod
+        * rocking_profile
+        * cross_section
+        * polarization_correction
+    )
+    record = CurveCorrectionRecord(
+        algorithm="framewise_ctr_total_flux_v1",
+        output_quantity="ctr_photon_curve",
+        scale_convention="total_flux_calibrated",
+        normalization_status="applied",
+        illumination_status="applied",
+        pixel_correction_status="polarization_only",
+        normalization_divisor=policy.normalization_divisor,
+        normalization_unit="photons",
+        illumination_divisor=policy.illumination_divisor,
+        illumination_convention="total_flux_H",
+        base_croibg=base_curve,
+        base_croibg_variance=np.zeros(sample_count),
+    )
+    corrected, corrected_errors, _status, _convention = (
+        corrected_curve_from_record(record)
+    )
+    detector_acceptance = float(
+        np.asarray(
+            acceptance.out_of_plane_acceptance(
+                detector,
+                center[0],
+                center[1],
+                roi_size[0],
+                alpha,
+                gamma_arm,
+                delta_arm,
+            )
+        ).reshape(-1)[0]
+    )
+    result = _compute_rocking_integration(
+        np.array([0.0]),
+        axis,
+        corrected[np.newaxis, :],
+        corrected_errors[np.newaxis, :],
+        {"sig_1": {"from": np.array([axis[0]]), "to": np.array([axis[-1]])}},
+        {},
+        True,
+        False,
+        C_Lor=np.full((1, sample_count), lorentz),
+        C_rod=np.full((1, sample_count), rod),
+        detector_acceptance=np.array([detector_acceptance]),
+        angle_unit="rad",
+    )
+    actual = result["F2_hkl"][0] / _prefactor()
+    expected = (
+        np.trapezoid(rocking_profile, axis)
+        * cross_section
+        * polarization_correction
+        / detector_acceptance
+    )
+    return actual, expected
+
+
+@pytest.mark.parametrize("roi_size", [(41, 41), (11, 7)])
+def test_rocking_reduction_recovers_full_and_clipped_pixel_ray_integrals(roi_size):
+    """A clipped transverse peak is compared with its captured integral."""
+    actual, expected = _rocking_result(257, roi_size)
+    np.testing.assert_allclose(actual, expected, rtol=3e-11)
+
+
+def test_rocking_sampling_converges_before_the_validation_tolerance_is_set():
+    """The chosen grid is demonstrably inside its numerical convergence regime."""
+    reference = _rocking_result(2049, (31, 31))[0]
+    approximations = np.array(
+        [_rocking_result(count, (31, 31))[0] for count in (9, 17, 33, 65)]
+    )
+    errors = np.abs(approximations - reference)
+    assert np.all(np.diff(errors) < 0.0)
+    assert errors[-1] / reference < 3e-7

From 31525da0194e6a7de62c5c0688b8b4408c00de28 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Thu, 17 Sep 2026 18:50:30 -0400
Subject: [PATCH 28/33] fix(phys): standardize kinematic coordinate
 broadcasting

---
 orgui/datautils/xrayutils/CTRcalc.py          | 62 +++++++++++++------
 .../datautils/xrayutils/test/test_CTRcalc.py  | 49 ++++++++++++---
 2 files changed, 85 insertions(+), 26 deletions(-)

diff --git a/orgui/datautils/xrayutils/CTRcalc.py b/orgui/datautils/xrayutils/CTRcalc.py
index 25ae1a3..19d2815 100644
--- a/orgui/datautils/xrayutils/CTRcalc.py
+++ b/orgui/datautils/xrayutils/CTRcalc.py
@@ -59,6 +59,20 @@
 )
 
 
+def _broadcast_kinematic_hkl(h, k, l):  # noqa: E741
+    """Return contiguous, flattened hkl arrays and their broadcast shape."""
+    arrays = np.broadcast_arrays(
+        np.asarray(h, dtype=np.float64),
+        np.asarray(k, dtype=np.float64),
+        np.asarray(l, dtype=np.float64),
+    )
+    shape = arrays[0].shape or (1,)
+    return (
+        tuple(np.ascontiguousarray(array).reshape(-1) for array in arrays),
+        shape,
+    )
+
+
 @dataclass(frozen=True)
 class KinematicComponentAmplitude:
     """One top-level component's scaled contribution to ``SXRDCrystal.F``.
@@ -391,12 +405,13 @@ def F(self, harray, karray, Larray):
         scale is included; calculated intensity is proportional to
         ``abs(F)**2``.
 
-        :param numpy.ndarray harray:
-            Reference-frame reciprocal coordinate in r.l.u.
-        :param numpy.ndarray karray:
-            Reference-frame reciprocal coordinate in r.l.u.
-        :param numpy.ndarray Larray:
-            Reference-frame reciprocal coordinate in r.l.u.
+        ``harray``, ``karray``, and ``Larray`` are broadcast together. Scalar
+        coordinates produce a one-point array, preserving the array-valued
+        structure-factor boundary.
+
+        :param harray: Reference-frame reciprocal coordinate in r.l.u.
+        :param karray: Reference-frame reciprocal coordinate in r.l.u.
+        :param Larray: Reference-frame reciprocal coordinate in r.l.u.
         :returns:
             Complex crystal amplitude in electrons per reference lateral cell.
         :rtype: numpy.ndarray
@@ -414,12 +429,12 @@ def F2(self, harray, karray, Larray):
         which is a dimensionless intensity ratio formed from an optical
         reflection amplitude.
 
-        :param numpy.ndarray harray:
-            Reference-frame reciprocal coordinate in r.l.u.
-        :param numpy.ndarray karray:
-            Reference-frame reciprocal coordinate in r.l.u.
-        :param numpy.ndarray Larray:
-            Reference-frame reciprocal coordinate in r.l.u.
+        ``harray``, ``karray``, and ``Larray`` are broadcast together. Scalar
+        coordinates produce one-point arrays in every returned amplitude.
+
+        :param harray: Reference-frame reciprocal coordinate in r.l.u.
+        :param karray: Reference-frame reciprocal coordinate in r.l.u.
+        :param Larray: Reference-frame reciprocal coordinate in r.l.u.
         :returns:
             Real, nonnegative squared structure factor.
         :rtype: numpy.ndarray
@@ -481,17 +496,20 @@ def evaluate_kinematic(self, harray, karray, Larray):
         amplitude carries its own area scaling, weight, and outer
         coherent-domain transforms and occupancies.
 
-        :param numpy.ndarray harray:
-            Reference-frame reciprocal coordinate in r.l.u.
-        :param numpy.ndarray karray:
-            Reference-frame reciprocal coordinate in r.l.u.
-        :param numpy.ndarray Larray:
-            Reference-frame reciprocal coordinate in r.l.u.
+        ``harray``, ``karray``, and ``Larray`` are broadcast together. Scalar
+        coordinates produce one-point arrays in every returned amplitude.
+
+        :param harray: Reference-frame reciprocal coordinate in r.l.u.
+        :param karray: Reference-frame reciprocal coordinate in r.l.u.
+        :param Larray: Reference-frame reciprocal coordinate in r.l.u.
         :returns:
             Bulk amplitude, per-component amplitudes in crystal order, and
             their total.
         :rtype: KinematicAmplitudeResult
         """
+        (harray, karray, Larray), output_shape = _broadcast_kinematic_hkl(
+            harray, karray, Larray
+        )
         bulk_scale = self.reference_area / self.uc_bulk.uc_area
         bulk = bulk_scale * self.uc_bulk.F_bulk(
             harray, karray, Larray, self.atten
@@ -524,9 +542,15 @@ def evaluate_kinematic(self, harray, karray, Larray):
                 KinematicComponentAmplitude(
                     index,
                     getattr(uc, "name", f"component_{index}"),
-                    amplitude,
+                    np.asarray(amplitude).reshape(output_shape),
                 )
             )
+        total_is_bulk = total is bulk
+        bulk = np.asarray(bulk).reshape(output_shape)
+        if total_is_bulk:
+            total = bulk
+        else:
+            total = np.asarray(total).reshape(output_shape)
         return KinematicAmplitudeResult(bulk, tuple(components), total)
 
     def setDomain(self, uc_no, domains):
diff --git a/orgui/datautils/xrayutils/test/test_CTRcalc.py b/orgui/datautils/xrayutils/test/test_CTRcalc.py
index 892b24d..4775603 100644
--- a/orgui/datautils/xrayutils/test/test_CTRcalc.py
+++ b/orgui/datautils/xrayutils/test/test_CTRcalc.py
@@ -1585,14 +1585,23 @@ def test_F2_is_the_squared_modulus_of_F(self):
         self.assertTrue(np.all(np.isreal(squared)))
         self.assertTrue(np.all(squared >= 0.0))
 
-        # Scalar coordinates are rejected inside `F_bulk`, which predates this
-        # boundary; `F2` must inherit that rather than diverge from `F`.
-        with self.assertRaises(AttributeError):
-            crystal.F(0.0, 0.0, 1.3)
-        with self.assertRaises(AttributeError):
-            crystal.F2(0.0, 0.0, 1.3)
-
         one_point = np.array([1.3])
+        scalar = crystal.evaluate_kinematic(0.0, 0.0, 1.3)
+        self.assertEqual(scalar.bulk.shape, (1,))
+        self.assertEqual(scalar.total.shape, (1,))
+        self.assertTrue(
+            all(part.amplitude.shape == (1,) for part in scalar.components)
+        )
+        np.testing.assert_allclose(
+            scalar.total,
+            crystal.F(one_point * 0.0, one_point * 0.0, one_point),
+            rtol=1e-14,
+        )
+        np.testing.assert_allclose(
+            crystal.F2(0.0, 0.0, 1.3),
+            np.abs(scalar.total) ** 2,
+            rtol=1e-14,
+        )
         np.testing.assert_allclose(
             crystal.F2(one_point * 0.0, one_point * 0.0, one_point),
             np.abs(crystal.F(one_point * 0.0, one_point * 0.0, one_point))
@@ -1600,6 +1609,32 @@ def test_F2_is_the_squared_modulus_of_F(self):
             rtol=1e-14,
         )
 
+    def test_kinematic_coordinates_broadcast_and_preserve_shape(self):
+        """Scalar and array coordinates share one backend-independent boundary."""
+        crystal = self.crystal()
+        h = np.array([[0.0], [1.0]])
+        k = np.array([[0.0, 0.25, 0.5]])
+        l_value = 1.3
+
+        result = crystal.evaluate_kinematic(h, k, l_value)
+        self.assertEqual(result.bulk.shape, (2, 3))
+        self.assertEqual(result.total.shape, (2, 3))
+        self.assertTrue(
+            all(part.amplitude.shape == (2, 3) for part in result.components)
+        )
+        np.testing.assert_allclose(
+            result.total,
+            crystal.F(
+                np.broadcast_to(h, (2, 3)),
+                np.broadcast_to(k, (2, 3)),
+                l_value,
+            ),
+            rtol=1e-14,
+        )
+        np.testing.assert_allclose(
+            crystal.F2(h, k, l_value), np.abs(result.total) ** 2, rtol=1e-14
+        )
+
 
 class TestLayerStacking(unittest.TestCase):
     @staticmethod

From 441069927dbd5aa8408141f70e673eab3d39914d Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Fri, 18 Sep 2026 12:31:31 -0400
Subject: [PATCH 29/33] fix: loading UB from h5 config, preserve lazy loading
 of ro scans

---
 orgui/app/config_data.py            |  11 ++-
 orgui/app/peak1Dintegr.py           | 100 ++++++++++++++++------------
 orgui/app/test/test_config_data.py  |  36 ++++++++++
 orgui/app/test/test_peak1Dintegr.py |  42 ++++++++++++
 4 files changed, 144 insertions(+), 45 deletions(-)

diff --git a/orgui/app/config_data.py b/orgui/app/config_data.py
index 67d4916..936d2d9 100644
--- a/orgui/app/config_data.py
+++ b/orgui/app/config_data.py
@@ -425,7 +425,13 @@ def _nx_group(mapping, units=None):
 
 
 def _plain(value):
-    """Strip the numpy and bytes wrappers that HDF5 hands back."""
+    """Strip the numpy and bytes wrappers that HDF5 hands back.
+
+    Live datasets with two or more dimensions (per-curve, per-frame arrays)
+    are returned unread so callers can slice one curve lazily.
+    """
+    if isinstance(value, h5py.Dataset):
+        return value if value.ndim >= 2 else _plain(value[()])
     if isinstance(value, bytes):
         return value.decode()
     if isinstance(value, np.ndarray):
@@ -1250,6 +1256,9 @@ def apply_to_gui(self, gui):
             ub_widget.crystal, self.ub_calculator.getEnergy()
         )
         ub_widget.ubCal.setU(self.ub_calculator.getU())
+        # calcReflection reads the orientation through ``angles``; it must
+        # not keep the replaced calculator (peak positions used the old U).
+        ub_widget.angles = HKLVlieg.VliegAngles(ub_widget.ubCal)
         ub_widget.mu = self.mu
         ub_widget.chi = self.chi
         ub_widget.phi = self.phi
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 0717931..8202613 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -31,6 +31,7 @@
 __maintainer__ = "Timo Fuchs"
 __email__ = "tfuchs@cornell.edu"
 
+import dataclasses
 import json
 import logging
 import sys
@@ -992,20 +993,18 @@ def _correctionUiState(record, record_present=True):
         }
 
     @staticmethod
-    def _storedCurveCorrectionRecord(h5_obj, nxfile):
-        """Return a parsed stored record, or ``None`` when it is incomplete."""
+    def _storedCurveCorrectionRecord(h5_obj):
+        """Return a parsed stored record, or ``None`` when it is incomplete.
+
+        Parsed from the live group: 2-D per-curve arrays stay unread
+        ``h5py.Dataset`` objects, valid while the database file is open.
+        """
         if CURVE_CORRECTIONS_GROUP not in h5_obj:
             return None
-        record_group = h5_obj[CURVE_CORRECTIONS_GROUP]
         try:
-            record_dict = h5todict(nxfile, record_group.name)
-            record_dict["@orgui_schema_version"] = record_group.attrs.get(
-                "orgui_schema_version", 0
-            )
-            record_dict["@orgui_curve_contract"] = record_group.attrs.get(
-                "orgui_curve_contract", ""
+            return curve_correction_record_from_nxdict(
+                h5_obj[CURVE_CORRECTIONS_GROUP]
             )
-            return curve_correction_record_from_nxdict(record_dict)
         except (KeyError, TypeError, ValueError):
             return None
 
@@ -1024,9 +1023,7 @@ def _refreshReductionCorrectionStatus(self):
             if name in self.database.nxfile:
                 h5_obj = self.database.nxfile[name]
                 present = CURVE_CORRECTIONS_GROUP in h5_obj
-                record = self._storedCurveCorrectionRecord(
-                    h5_obj, self.database.nxfile
-                )
+                record = self._storedCurveCorrectionRecord(h5_obj)
         state = self._correctionUiState(record, present)
         self._activeCorrectionRecord = record
         self._activeCorrectionUiState = state
@@ -1106,7 +1103,7 @@ def _prepareFootprintAction(self, h5_obj):
         self.footprint_action = action
         self.replacement_illumination = None
         self.replacement_illumination_convention = None
-        record = self._storedCurveCorrectionRecord(h5_obj, self.database.nxfile)
+        record = self._storedCurveCorrectionRecord(h5_obj)
         if (
             action == FOOTPRINT_APPLY
             and record is not None
@@ -1125,7 +1122,7 @@ def _prepareFootprintAction(self, h5_obj):
                 )
             self.replacement_illumination = (
                 activearea_corrections.illumination_divisor(
-                    record.alpha,
+                    np.asarray(record.alpha),
                     self.integrationCorrection.sampleLength(),
                     self.integrationCorrection.beamProfile(),
                     horizontal_fraction=horizontal,
@@ -2491,46 +2488,60 @@ def _legacy_rocking_curve_group(h5_obj):
 
     def get_ro_curve(self, idx):
         """Return one rocking curve under its stored correction contract."""
-        curves = self.get_all_ro_curves()
-        curve = {
-            "axisname": curves["axisname"],
-            "axis": curves["axis"],
-            "croibg": curves["croibg"][idx],
-            "croibg_errors": curves["croibg_errors"][idx],
-        }
-        return curve
+        return self.get_all_ro_curves(idx)
 
-    def get_all_ro_curves(self):
+    def get_all_ro_curves(self, idx=None):
         """Return rocking curves without silently changing their scale.
 
         New total-flux records are reconstructed from the immutable base
         curve and the exact stored Q/H divisors. Legacy records retain the
         historical ``rois`` path and are normalized later by
         :meth:`_rocking_normalization`.
+
+        :param int or None idx: Read only this curve. It is shown in its
+            stored footprint state; a pending footprint action is applied
+            only by :meth:`integrate`.
         """
         name = self._currentRoInfo["name"]
         h5_obj = self.database.nxfile[name]
         if CURVE_CORRECTIONS_GROUP in h5_obj:
-            record = RockingPeakIntegrator._storedCurveCorrectionRecord(
-                h5_obj, self.database.nxfile
-            )
+            record = RockingPeakIntegrator._storedCurveCorrectionRecord(h5_obj)
             if record is not None and record.algorithm.startswith(
                 "framewise_ctr_total_flux_"
             ):
+                if idx is None:
+                    footprint = {
+                        "footprint_action": getattr(
+                            self, "footprint_action", FOOTPRINT_KEEP
+                        ),
+                        "replacement_illumination": getattr(
+                            self, "replacement_illumination", None
+                        ),
+                        "replacement_convention": getattr(
+                            self, "replacement_illumination_convention", None
+                        ),
+                        "allow_convention_change": bool(
+                            getattr(
+                                self, "allow_illumination_convention_change", False
+                            )
+                        ),
+                    }
+                else:
+                    # (curve, frame) arrays: read one row; 1-D divisors are
+                    # shared per frame and broadcast unchanged.
+                    record = dataclasses.replace(record, **{
+                        field: getattr(record, field)[idx]
+                        for field in (
+                            "base_croibg",
+                            "base_croibg_variance",
+                            "normalization_divisor",
+                            "illumination_divisor",
+                        )
+                        if np.ndim(getattr(record, field)) == 2
+                    })
+                    footprint = {}
                 curve, errors, action, convention = corrected_curve_from_record(
-                    record,
-                    footprint_action=getattr(
-                        self, "footprint_action", FOOTPRINT_KEEP
-                    ),
-                    replacement_illumination=getattr(
-                        self, "replacement_illumination", None
-                    ),
-                    replacement_convention=getattr(
-                        self, "replacement_illumination_convention", None
-                    ),
-                    allow_convention_change=bool(
-                        getattr(self, "allow_illumination_convention_change", False)
-                    ),
+                    record, **footprint
                 )
                 return {
                     "axisname": self._currentRoInfo["axisname"],
@@ -2543,15 +2554,16 @@ def get_all_ro_curves(self):
                 }
 
         cnters = self._legacy_rocking_curve_group(h5_obj)
+        rows = () if idx is None else idx
         curve = {
             "axisname": self._currentRoInfo["axisname"],
             "axis": self._currentRoInfo["axis"],
-            "croibg": cnters["croibg"][()],
-            "croibg_errors": cnters["croibg_errors"][()],
+            "croibg": cnters["croibg"][rows],
+            "croibg_errors": cnters["croibg_errors"][rows],
         }
         if "ctr_croibg" in cnters and "ctr_croibg_errors" in cnters:
-            curve["ctr_croibg"] = cnters["ctr_croibg"][()]
-            curve["ctr_croibg_errors"] = cnters["ctr_croibg_errors"][()]
+            curve["ctr_croibg"] = cnters["ctr_croibg"][rows]
+            curve["ctr_croibg_errors"] = cnters["ctr_croibg_errors"][rows]
         return curve
 
     # def onAnchorBtnToggled(self, state):
diff --git a/orgui/app/test/test_config_data.py b/orgui/app/test/test_config_data.py
index 1d60f5a..174cdbb 100644
--- a/orgui/app/test/test_config_data.py
+++ b/orgui/app/test/test_config_data.py
@@ -425,6 +425,42 @@ def test_apply_to_gui_sets_reconstruction_normalization_attributes():
     assert gui.reconstruction_monitor_corrections == ("mondio",)
 
 
+def test_apply_to_gui_peak_angles_use_the_loaded_orientation():
+    """Loaded U must reach ``angles``, which calcReflection reads."""
+    config = _make_config()
+    rotation = np.deg2rad(68.0)
+    config.ub_calculator.setU(
+        np.array(
+            [
+                [np.cos(rotation), -np.sin(rotation), 0.0],
+                [np.sin(rotation), np.cos(rotation), 0.0],
+                [0.0, 0.0, 1.0],
+            ]
+        )
+    )
+    stale = HKLVlieg.UBCalculator(config.unit_cell, 70.0)
+    stale.defaultU()
+    gui = SimpleNamespace(
+        ubcalc=SimpleNamespace(
+            detectorCal=config.detector,
+            crystal=config.unit_cell,
+            ubCal=stale,
+            angles=HKLVlieg.VliegAngles(stale),
+        ),
+    )
+
+    config.apply_to_gui(gui)
+
+    hkl = np.array([[1.0], [0.0], [1.0]])
+    expected = HKLVlieg.VliegAngles(config.ub_calculator).anglesZmode(
+        hkl, config.mu, "in", config.chi, config.phi
+    )
+    np.testing.assert_allclose(
+        gui.ubcalc.angles.anglesZmode(hkl, config.mu, "in", config.chi, config.phi),
+        expected,
+    )
+
+
 def test_total_flux_state_survives_before_its_widgets_exist():
     """Stage-5 programmatic settings round-trip through the GUI snapshot."""
     config = _make_config()
diff --git a/orgui/app/test/test_peak1Dintegr.py b/orgui/app/test/test_peak1Dintegr.py
index aa04a1c..4186caa 100644
--- a/orgui/app/test/test_peak1Dintegr.py
+++ b/orgui/app/test/test_peak1Dintegr.py
@@ -863,6 +863,48 @@ def test_versioned_total_flux_curve_uses_stored_divisors_once(tmp_path):
     assert curves["illumination_action"] == "applied"
 
 
+def test_one_total_flux_curve_is_read_lazily_in_its_stored_state(tmp_path):
+    """Selecting a curve reads its row only and ignores a pending action."""
+    base = np.array([[80.0, 96.0, 120.0], [40.0, 48.0, 60.0]])
+    variance = np.array([[16.0, 36.0, 64.0], [4.0, 9.0, 16.0]])
+    q = np.array([2.0, 4.0, 5.0])
+    h = np.array([[0.5, 0.25, 1.0], [0.8, 0.4, 0.2]])
+    record = CurveCorrectionRecord(
+        algorithm="framewise_ctr_total_flux_v1",
+        output_quantity="rocking_ctr_photon_curve",
+        scale_convention="total_flux_calibrated",
+        normalization_status="applied",
+        normalization_divisor=q,
+        normalization_unit="photons",
+        illumination_status="applied",
+        illumination_divisor=h,
+        illumination_convention="total_flux_H",
+        base_croibg=base,
+        base_croibg_variance=variance,
+    )
+    path = tmp_path / "lazy_curve.h5"
+    dicttonx(
+        {"scan": {CURVE_CORRECTIONS_GROUP: curve_correction_record_to_nxdict(record)}},
+        path,
+    )
+
+    with h5py.File(path, "r") as handle:
+        integrator = SimpleNamespace(
+            _currentRoInfo={"name": "/scan", "axisname": "mu", "axis": np.arange(3.0)},
+            database=SimpleNamespace(nxfile=handle),
+            footprint_action=FOOTPRINT_APPLY,
+            replacement_illumination=None,
+        )
+        stored = RockingPeakIntegrator._storedCurveCorrectionRecord(handle["scan"])
+        assert isinstance(stored.base_croibg, h5py.Dataset)
+        assert isinstance(stored.illumination_divisor, h5py.Dataset)
+        curve = RockingPeakIntegrator.get_all_ro_curves(integrator, 1)
+
+    np.testing.assert_allclose(curve["croibg"], base[1] / q / h[1])
+    np.testing.assert_allclose(curve["croibg_errors"], np.sqrt(variance[1]) / q / h[1])
+    assert curve["illumination_action"] == "applied"
+
+
 def test_unknown_legacy_curve_only_allows_keep_and_requests_reextraction():
     """Unknown provenance cannot expose apply/remove as safe operations."""
     state = RockingPeakIntegrator._correctionUiState(

From 8c69c9df102040bf31eb0bbdb2479e967f5cbb18 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Sat, 19 Sep 2026 21:40:09 -0400
Subject: [PATCH 30/33] fix: allow integration at alpha<=0 discarding invalid
 data

---
 orgui/app/integration_corrections.py          | 92 ++++++++++++++++---
 orgui/app/peak1Dintegr.py                     | 15 ++-
 .../app/test/test_frame_correction_policy.py  | 63 +++++++++++++
 3 files changed, 151 insertions(+), 19 deletions(-)

diff --git a/orgui/app/integration_corrections.py b/orgui/app/integration_corrections.py
index 517bc50..5a68c62 100644
--- a/orgui/app/integration_corrections.py
+++ b/orgui/app/integration_corrections.py
@@ -61,6 +61,7 @@
 safe in CLI and batch use.
 """
 
+import logging
 from dataclasses import dataclass
 
 import numpy as np
@@ -85,6 +86,7 @@
     "apply_stationary_corrections",
     "corrected_curve_from_record",
     "frame_correction_policy",
+    "framewise_illumination_divisor",
     "monitor_counter_candidates",
     "normalization_divisor",
     "pixel_correction_branches",
@@ -98,6 +100,8 @@
 FOOTPRINT_APPLY = "apply"
 FOOTPRINT_REMOVE = "remove"
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass(frozen=True)
 class FrameCorrectionPolicy:
@@ -165,6 +169,69 @@ def _horizontal_fraction(state):
     )
 
 
+def framewise_illumination_divisor(
+    alpha,
+    sample_length,
+    profile,
+    *,
+    horizontal_fraction,
+):
+    r"""Total-flux :math:`H` per frame, excluding nonphysical incidence.
+
+    :func:`~orgui.datautils.xrayutils.corrections.activearea.illumination_divisor`
+    only accepts incidence angles in :math:`(0, \pi/2]`. A scan that starts
+    at the horizon (e.g. ``flyscan th 0 12`` on a z-axis backend that maps
+    ``th`` to ``alpha``) contains frames without a defined illumination.
+    Those frames are excluded, not extrapolated: their :math:`H` and
+    :math:`f_\mathrm{hit}` are NaN, so every value corrected with them is NaN
+    and any integral over them is NaN rather than silently integrating over a
+    gap.
+
+    :param alpha: Incidence angle(s) per frame, in radian.
+    :param float sample_length: Sample length along the beam, in meter.
+    :param profile: A :class:`~.beamprofile.BeamProfile`.
+    :param horizontal_fraction: Horizontal intercepted fraction, in
+        ``(0, 1]``.
+    :returns: ``(H, f_hit, valid)`` broadcast to the shape of ``alpha``;
+        ``valid`` is the boolean mask of frames with a defined :math:`H`.
+    :rtype: tuple of numpy.ndarray
+    :raises ValueError: If no frame has a physical incidence angle, or the
+        geometry or profile is otherwise invalid.
+    """
+    alpha = np.asarray(alpha, dtype=np.float64)
+    valid = np.isfinite(alpha) & (alpha > 0) & (alpha <= np.pi / 2)
+    if not np.any(valid):
+        raise ValueError(
+            "total-flux illumination needs at least one frame with an "
+            "incidence angle in (0, 90] deg"
+        )
+    illumination = np.full(alpha.shape, np.nan)
+    intercepted = np.full(alpha.shape, np.nan)
+    illumination[valid] = activearea.illumination_divisor(
+        alpha[valid],
+        sample_length,
+        profile,
+        horizontal_fraction=horizontal_fraction,
+    )
+    intercepted[valid] = activearea.intercepted_fraction(
+        alpha[valid],
+        sample_length,
+        profile,
+        horizontal_fraction=horizontal_fraction,
+    )
+    excluded = int(np.count_nonzero(~valid))
+    if excluded:
+        logger.warning(
+            "Total-flux illumination is undefined for %d of %d frame values "
+            "with incidence angle outside (0, 90] deg (e.g. alpha = %.4g deg); "
+            "these frames are excluded (NaN).",
+            excluded,
+            alpha.size,
+            np.rad2deg(alpha[~valid].flat[0]),
+        )
+    return illumination, intercepted, valid
+
+
 def frame_correction_policy(
     scan,
     state,
@@ -305,21 +372,16 @@ def frame_correction_policy(
                 "sample length"
             )
         horizontal = _horizontal_fraction(state)
-        vertical = np.asarray(
-            beam_profile.flux_on_sample(alpha, sample_length), dtype=np.float64
-        )
-        illumination = activearea.illumination_divisor(
+        illumination, intercepted, valid = framewise_illumination_divisor(
             alpha,
             sample_length,
             beam_profile,
             horizontal_fraction=horizontal,
         )
-        intercepted = activearea.intercepted_fraction(
-            alpha,
-            sample_length,
-            beam_profile,
-            horizontal_fraction=horizontal,
+        vertical = np.asarray(
+            beam_profile.flux_on_sample(alpha, sample_length), dtype=np.float64
         )
+        vertical = np.where(valid, vertical, np.nan)
         illum_status = "applied"
 
     if calibrated:
@@ -436,8 +498,16 @@ def corrected_curve_from_record(
         convention = replacement_convention
 
     if illumination is not None:
-        if np.any(illumination <= 0) or not np.all(np.isfinite(illumination)):
-            raise ValueError("illumination divisor must be finite and positive")
+        # NaN marks a frame excluded by framewise_illumination_divisor (no
+        # physical incidence angle); it propagates to that frame only.
+        if (
+            np.any(illumination <= 0)
+            or np.any(np.isinf(illumination))
+            or np.all(np.isnan(illumination))
+        ):
+            raise ValueError(
+                "illumination divisor must be positive where defined"
+            )
         curve = curve / illumination
         variance = variance / np.square(illumination)
     return curve, np.sqrt(variance), status, convention
diff --git a/orgui/app/peak1Dintegr.py b/orgui/app/peak1Dintegr.py
index 8202613..3403666 100644
--- a/orgui/app/peak1Dintegr.py
+++ b/orgui/app/peak1Dintegr.py
@@ -70,6 +70,7 @@
     FOOTPRINT_KEEP,
     FOOTPRINT_REMOVE,
     corrected_curve_from_record,
+    framewise_illumination_divisor,
 )
 from .. import resources
 from .. import logger_utils
@@ -1120,14 +1121,12 @@ def _prepareFootprintAction(self, h5_obj):
                     "The stored curve has no incidence angles; re-extract "
                     "images before changing its footprint."
                 )
-            self.replacement_illumination = (
-                activearea_corrections.illumination_divisor(
-                    np.asarray(record.alpha),
-                    self.integrationCorrection.sampleLength(),
-                    self.integrationCorrection.beamProfile(),
-                    horizontal_fraction=horizontal,
-                )
-            )
+            self.replacement_illumination = framewise_illumination_divisor(
+                np.asarray(record.alpha),
+                self.integrationCorrection.sampleLength(),
+                self.integrationCorrection.beamProfile(),
+                horizontal_fraction=horizontal,
+            )[0]
             self.replacement_illumination_convention = "total_flux_H"
         elif action != FOOTPRINT_KEEP and record is None:
             raise ValueError(
diff --git a/orgui/app/test/test_frame_correction_policy.py b/orgui/app/test/test_frame_correction_policy.py
index 4999420..860e40d 100644
--- a/orgui/app/test/test_frame_correction_policy.py
+++ b/orgui/app/test/test_frame_correction_policy.py
@@ -90,6 +90,53 @@ def test_total_flux_illumination_requires_horizontal_provenance():
         )
 
 
+def test_total_flux_illumination_excludes_frames_at_the_horizon():
+    """A scan starting at alpha = 0 drops that frame instead of failing.
+
+    Regression: ``flyscan th 0 12`` on the CHESS QM2 backend (th -> alpha)
+    rejected the whole extraction because of its first frame.
+    """
+    scan = SimpleNamespace(exposure_time=np.ones(4), ic2=np.ones(4) * 100.0)
+    alpha = np.deg2rad([[0.0, 0.5, 1.0, -0.1]] * 2)
+    profile = top_hat_profile(300e-6)
+
+    policy = ic.frame_correction_policy(
+        scan,
+        _state(),
+        4,
+        use_normalization=True,
+        use_illumination=True,
+        alpha=alpha,
+        beam_profile=profile,
+        sample_length=5e-3,
+    )
+
+    valid = np.array([[False, True, True, False]] * 2)
+    expected = ic.activearea.illumination_divisor(
+        alpha[valid], 5e-3, profile, horizontal_fraction=1.0
+    )
+    for values in (
+        policy.illumination_divisor,
+        policy.intercepted_fraction,
+        policy.vertical_intercepted_fraction,
+    ):
+        assert values.shape == alpha.shape
+        np.testing.assert_array_equal(np.isfinite(values), valid)
+    np.testing.assert_allclose(policy.illumination_divisor[valid], expected)
+    assert policy.illumination_status == "applied"
+
+
+def test_total_flux_illumination_needs_one_physical_frame():
+    """Excluding frames must not turn an all-invalid scan into all-NaN data."""
+    with pytest.raises(ValueError, match="at least one frame"):
+        ic.framewise_illumination_divisor(
+            np.deg2rad([0.0, -1.0]),
+            5e-3,
+            top_hat_profile(300e-6),
+            horizontal_fraction=1.0,
+        )
+
+
 def test_legacy_policy_preserves_counter_product_and_active_area():
     """Absent version-3 fields retain the established numerical convention."""
     exposure = np.array([0.5, 1.0, 2.0])
@@ -169,6 +216,22 @@ def test_footprint_actions_always_restart_from_the_stored_base():
     assert replaced_status == "replaced"
 
 
+def test_excluded_illumination_frame_is_nan_only_in_that_frame():
+    """A NaN H marks an excluded frame; a nonpositive H is still an error."""
+    curve, errors, _status, _convention = ic.corrected_curve_from_record(
+        _record(illumination_divisor=np.array([np.nan, 0.25]))
+    )
+    assert np.isnan(curve[0]) and np.isnan(errors[0])
+    np.testing.assert_allclose(curve[1], 96.0 / 4.0 / 0.25)
+    np.testing.assert_allclose(errors[1], 6.0 / 4.0 / 0.25)
+
+    for bad in ([0.0, 0.25], [np.inf, 0.25], [np.nan, np.nan]):
+        with pytest.raises(ValueError, match="positive where defined"):
+            ic.corrected_curve_from_record(
+                _record(illumination_divisor=np.array(bad))
+            )
+
+
 def test_convention_change_and_unknown_provenance_are_explicit_errors():
     """Unsafe migrations are never inferred from a curve's numeric values."""
     with pytest.raises(ValueError, match="changing illumination convention"):

From 7d5852bb56d4ebee1ebc830b81c74eef68b52c72 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Sat, 19 Sep 2026 21:44:18 -0400
Subject: [PATCH 31/33] fix: rsmap json config now correctly converts nexus
 detector config

---
 orgui/app/ReconstructionDialog.py                | 16 ++++++++++++++--
 orgui/datautils/xrayutils/DetectorCalibration.py |  5 +++--
 .../xrayutils/test/test_DetectorCalibration.py   | 11 +++++++++++
 3 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/orgui/app/ReconstructionDialog.py b/orgui/app/ReconstructionDialog.py
index d6d821a..5224444 100644
--- a/orgui/app/ReconstructionDialog.py
+++ b/orgui/app/ReconstructionDialog.py
@@ -332,6 +332,14 @@ def _format_size(size_bytes):
         size_bytes /= 1024
 
 
+def _json_display(value):
+    # Numpy scalars/arrays leak in from h5-loaded configs; the summary is
+    # display-only, so fall back to their Python equivalents or repr.
+    if isinstance(value, (np.generic, np.ndarray)):
+        return value.tolist()
+    return str(value)
+
+
 class _ReconstructionCancelled(RuntimeError):
     """Signal cancellation between reconstruction tasks."""
 
@@ -1727,7 +1735,9 @@ def refresh_live_state(self):
                 self.experiment_summary.setPlainText("No active scan.")
                 return
             config = ConfigData.from_gui(self.orgui)
-            detector_shape = self.orgui.ubcalc.detectorCal.detector.shape
+            detector_shape = tuple(
+                int(n) for n in self.orgui.ubcalc.detectorCal.detector.shape
+            )
             summary = {
                 "scan": getattr(
                     self.orgui.fscan,
@@ -1745,7 +1755,9 @@ def refresh_live_state(self):
                 "memory_MiB": self.orgui.maxMemory,
             }
             self.experiment_summary.setPlainText(
-                json.dumps(summary, indent=2, sort_keys=True)
+                json.dumps(
+                    summary, indent=2, sort_keys=True, default=_json_display
+                )
             )
             stem = "".join(
                 character if character.isalnum() or character in "-_" else "_"
diff --git a/orgui/datautils/xrayutils/DetectorCalibration.py b/orgui/datautils/xrayutils/DetectorCalibration.py
index 8f6f615..d983449 100644
--- a/orgui/datautils/xrayutils/DetectorCalibration.py
+++ b/orgui/datautils/xrayutils/DetectorCalibration.py
@@ -433,10 +433,11 @@ def fromNXdict(self, nxdict):
         if "detector" in config:
             config["detector"] = str(config["detector"])
         self.set_config(config)
+        # Stored as an int64 array; restore plain ints like pyFAI itself uses.
         if max_shape is not None:
-            self.detector.max_shape = tuple(max_shape)
+            self.detector.max_shape = tuple(int(n) for n in max_shape)
         if shape is not None:
-            self.detector.shape = tuple(shape)
+            self.detector.shape = tuple(int(n) for n in shape)
         self.setAzimuthalReference(detdict["azimuth"])
         self.setPolarization(detdict["polarization_axis"], detdict["polarization"])
         # Calibrations written before the moveable detector arm carry no
diff --git a/orgui/datautils/xrayutils/test/test_DetectorCalibration.py b/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
index 5ea2565..18506d2 100644
--- a/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
+++ b/orgui/datautils/xrayutils/test/test_DetectorCalibration.py
@@ -28,6 +28,7 @@
 __maintainer__ = "Timo Fuchs"
 __email__ = "fuchs@physik.uni-kiel.de"
 
+import json
 import unittest
 
 from .. import DetectorCalibration, HKLVlieg
@@ -120,6 +121,16 @@ def test_read_write_nx(self):
 
         os.remove(self._nxfilename)
 
+    def test_nx_shape_restores_python_ints(self):
+        """h5 configs store the shape as int64; it must not leak numpy
+        scalars into consumers such as ``json.dumps``."""
+        other = DetectorCalibration.Detector2D_SXRD()
+        other.fromNXdict(self.sxrddet.toNXdict())
+        for shape in (other.detector.shape, other.detector.max_shape):
+            self.assertEqual(shape, tuple(self.sxrddet.detector.shape))
+            self.assertTrue(all(type(n) is int for n in shape))
+        json.dumps(other.detector.shape)
+
     def _destruct_file(self, filename):
         if os.path.exists(filename):
             os.remove(self._nxfilename)

From 8758660d6c32f66e7da6afd70fce949332badb5c Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Sat, 19 Sep 2026 22:06:48 -0400
Subject: [PATCH 32/33] fix(rsmap): fix thread stall after automatic rebalance

---
 CHANGELOG.md                                  |  12 ++
 .../test/test_reconstruction_pipeline.py      | 187 ++++++++++++++++++
 orgui/reconstruction_job.py                   | 110 ++++++++++-
 3 files changed, 299 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index acfa1cf..2df990f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1471,6 +1471,18 @@ Reciprocal-space reconstruction:
   times the headroom actually needed and still falls back to the heap if
   a block ever exceeds it, so this bounds memory, never correctness;
   mapped output is unchanged, verified record for record.
+- **A reciprocal-space mapping run no longer stops partway through when
+  automatic mode retunes its thread split.** Changing the native threads
+  per image needs a whole new compute pool rather than a resize, and the
+  replacement used to be started before the outgoing one was retired.
+  Both then drew from the same queue, so the outgoing pool's shutdown
+  signals were picked up by the incoming workers, which stopped
+  immediately -- leaving the run with no compute workers, no error and no
+  progress, indefinitely. Affected runs hung at whichever frame the
+  retune landed on, typically within the first minute. The outgoing pool
+  is now fully retired before its replacement starts, and any leftover
+  signals are cleared while nothing is reading the queue. Mapped output
+  is unaffected.
 
 
 ## [1.5.0] (2026-06-07)
diff --git a/orgui/datautils/xrayutils/test/test_reconstruction_pipeline.py b/orgui/datautils/xrayutils/test/test_reconstruction_pipeline.py
index d770b55..2fa8085 100644
--- a/orgui/datautils/xrayutils/test/test_reconstruction_pipeline.py
+++ b/orgui/datautils/xrayutils/test/test_reconstruction_pipeline.py
@@ -18,9 +18,11 @@
 from orgui.reconstruction_job import (
     _AdjustablePool,
     _BoundedGate,
+    _drain_surplus_sentinels,
     _kernel_threads_candidates,
     _map_pending_ranges,
     _FrameFingerprintLog,
+    _SHUTDOWN_SENTINEL,
 )
 from orgui.datautils.xrayutils.reconstruction import _GridSpec, _ReconstructionSpec
 
@@ -783,6 +785,191 @@ def fake_sweep(
     assert len(set(compute_pool_sizes)) == len(compute_pool_sizes)
 
 
+def test_drain_surplus_sentinels_removes_only_sentinels():
+    """The drain keeps queued work and reports what it took out."""
+    from queue import Queue
+
+    work_queue = Queue()
+    first, second = object(), object()
+    for item in (_SHUTDOWN_SENTINEL, first, _SHUTDOWN_SENTINEL, second):
+        work_queue.put(item)
+
+    assert _drain_surplus_sentinels(work_queue) == 2
+    assert work_queue.qsize() == 2
+    assert {work_queue.get_nowait(), work_queue.get_nowait()} == {first, second}
+    assert _drain_surplus_sentinels(work_queue) == 0
+
+
+def test_compute_pool_swap_does_not_hand_the_new_generation_an_exit_order(
+    tmp_path, monkeypatch
+):
+    """A kernel_threads swap must leave the replacement pool working.
+
+    The retired pool is woken by putting one ``_SHUTDOWN_SENTINEL`` per
+    outstanding worker on ``ready_queue``, and a sentinel belongs to
+    whoever reads it next. While the replacement pool was spawned
+    *before* that shutdown, its workers drained the backlog, reached the
+    block of sentinels and returned -- all of them. Nothing was left to
+    release the gate, so the readers parked on it, ``readers_done`` never
+    fired, and the coordinator waited forever with three live threads and
+    no CPU. Caught mid-run on the real ``39_1-rsmap`` job, 2026-09-19,
+    at 9% of 3651 frames.
+
+    The ingredient that makes it deterministic rather than a race is a
+    *backlog*: with work already queued, the retired workers exit on
+    their cancellation check long before their own sentinels surface, so
+    every sentinel falls through to the new generation. This test builds
+    that backlog on purpose by making a map call far slower than a read.
+    """
+    real_parallelism = reconstruction_job_module._frame_parallelism
+    real_map_frame_group = reconstruction_job_module._map_frame_group
+    events = []
+    events_lock = threading.Lock()
+
+    class _SpyPool(reconstruction_job_module._AdjustablePool):
+        def __init__(self, worker_fn, *, initial_size, name):
+            if name == "orgui-rsmap-compute":
+                with events_lock:
+                    events.append(("created", initial_size))
+            super().__init__(worker_fn, initial_size=initial_size, name=name)
+
+        def shutdown(self, *, wait=True):
+            super().shutdown(wait=wait)
+            if self._name == "orgui-rsmap-compute":
+                with events_lock:
+                    events.append(("retired", None))
+
+    def fixed_parallelism(spec, tiles, memory_bytes, **kwargs):
+        # Pins the seed: eight pending ranges each affording eight
+        # workers give one native thread per image, so the sweep below
+        # unambiguously favors a *different* kernel_threads and the swap
+        # is guaranteed to happen rather than depending on what the
+        # memory estimate makes of this synthetic grid.
+        _limit, native, memory, accumulation = real_parallelism(
+            spec, tiles, memory_bytes, **kwargs
+        )
+        return 8, kwargs.get("threads_per_image", native), memory, accumulation
+
+    def fake_sweep(*args, candidates, **kwargs):
+        # Favors the largest candidate at an effectively-zero per-frame
+        # time, so every candidate stays feasible and the rebalance picks
+        # the largest -- away from the seeded 1.
+        return {c: (0.5 if c == 1 else 1e-6) for c in candidates}
+
+    def slow_map_frame_group(*args, **kwargs):
+        # Slower than a read, so the readers keep ready_queue non-empty
+        # and the retired workers are mid-call when the swap lands.
+        time.sleep(0.005)
+        return real_map_frame_group(*args, **kwargs)
+
+    monkeypatch.setattr(reconstruction_job_module, "_AdjustablePool", _SpyPool)
+    monkeypatch.setattr(
+        reconstruction_job_module, "_frame_parallelism", fixed_parallelism
+    )
+    # One frame per group: frame grouping routes to
+    # _map_frame_groups_streamed, which has a single compute-pool
+    # generation and therefore no swap to test. Without this the whole
+    # test passes vacuously.
+    monkeypatch.setattr(
+        reconstruction_job_module, "_choose_frames_per_group", lambda *a, **k: 1
+    )
+    monkeypatch.setattr(
+        reconstruction_job_module, "_kernel_threads_sweep", fake_sweep
+    )
+    monkeypatch.setattr(
+        reconstruction_job_module, "_map_frame_group", slow_map_frame_group
+    )
+    monkeypatch.setattr(
+        reconstruction_job_module, "_REBALANCE_INITIAL_SECONDS", 0.05
+    )
+    monkeypatch.setattr(
+        reconstruction_job_module, "_COORDINATOR_TICK_SECONDS", 0.05
+    )
+
+    frame_count = 240
+    range_size = frame_count // 8
+    pending_ranges = [
+        (start, start + range_size)
+        for start in range(0, frame_count, range_size)
+    ]
+    scan = _SlowScan(frame_count, delay=0.0)
+    config = _FakeConfig()
+    spec = _ReconstructionSpec(
+        grids=(
+            _GridSpec(
+                minimum=(-1.0, -1.0, -1.0),
+                maximum=(1.0, 1.0, 1.0),
+                step=(1.0, 1.0, 1.0),
+                frame="lab",
+                chunk_shape=(2, 2, 2),
+            ),
+        ),
+        max_depth=0,
+        threads=4,
+    )
+    bounds = np.zeros((frame_count, 2, 4), dtype=np.float64)
+    tiles = [(0, 1, 0, 1)]
+    grid_name = spec.grids[0].grid_name
+    router = _router({grid_name: [(0, frame_count)]}, tmp_path=tmp_path)
+    failure = []
+
+    def run():
+        try:
+            _map_pending_ranges(
+                spec,
+                scan,
+                config,
+                bounds,
+                tiles,
+                pending_ranges,
+                router,
+                correction_pipeline=_correction,
+                effective_memory=256 * 1024**2,
+                threads_per_image=None,
+                accumulation_budget_bytes=None,
+                total_images=frame_count,
+                completed_images=0,
+                progress=None,
+            )
+        except BaseException as error:  # noqa: BLE001 -- reported below
+            failure.append(error)
+
+    # In a thread with a deadline: the regression is a permanent stall,
+    # and a test that reproduces it must fail rather than hang the suite.
+    runner = threading.Thread(target=run, daemon=True)
+    runner.start()
+    runner.join(timeout=120)
+    assert not runner.is_alive(), (
+        "_map_pending_ranges never returned -- the compute pool was left "
+        "with no workers after a kernel_threads swap"
+    )
+    if failure:
+        raise failure[0]
+
+    # The swap happened, and each replacement was created only after its
+    # predecessor had been joined. That ordering is the fix: it is what
+    # makes the retired pool the only possible reader of its own wake
+    # sentinels. Counting creations, not retirements -- the coordinator's
+    # own teardown retires the last pool too, so a retirement alone does
+    # not prove a swap and an assertion on it passes vacuously.
+    creations = [event for event in events if event[0] == "created"]
+    assert len(creations) >= 2, f"no compute-pool swap occurred: {events}"
+    for index, (kind, _size) in enumerate(events):
+        if kind == "created" and index > 0:
+            assert events[index - 1][0] == "retired", (
+                "a replacement compute pool was spawned while the retired "
+                f"one was still being woken on the shared ready_queue: {events}"
+            )
+
+    from orgui.datautils.xrayutils.reconstruction import _read_checkpoint
+
+    # And the swap still changes nothing scientific: every frame lands
+    # exactly once.
+    assert len(router.written) == 1
+    written = _read_checkpoint(router.written[0])
+    assert int(written["contributors"].sum()) == frame_count
+
+
 def test_frame_fingerprint_flags_a_reused_read_buffer(tmp_path):
     """A frame served another frame's pixels must be visible.
 
diff --git a/orgui/reconstruction_job.py b/orgui/reconstruction_job.py
index 57ca811..c2e27d3 100644
--- a/orgui/reconstruction_job.py
+++ b/orgui/reconstruction_job.py
@@ -2476,8 +2476,54 @@ def retarget(self, capacity) -> None:
 already true -- observed repeatedly in 2026-08, on two builds, with
 ``cancellation`` and ``dispatch_done`` set and the queue empty. A sentinel
 wakes the consumer with data instead of with the clock.
+
+A sentinel is addressed to a *pool*, but it travels on a queue, so it is
+really addressed to whoever reads it next. Where one pool replaces
+another on the same queue, the replacement must therefore not be
+consuming yet when the retired pool is woken -- see
+:func:`_drain_surplus_sentinels` and the compute-pool generation swap in
+:func:`_map_pending_ranges`.
 """
 
+
+def _drain_surplus_sentinels(work_queue):
+    """Remove leftover :data:`_SHUTDOWN_SENTINEL` values from a queue.
+
+    A pool's ``shutdown`` puts one sentinel per outstanding worker, and a
+    worker that had already exited leaves its sentinel behind. Harmless
+    while that queue has no other consumer; fatal once a replacement pool
+    starts draining the same queue, because the first thing each new
+    worker reads is an exit order meant for a thread that is already
+    gone.
+
+    Call this only when no consumer is running -- between a retired
+    pool's join and its replacement's first worker. Real work items are
+    put back, so nothing queued is lost; producers may interleave with
+    the put-back, which reorders items relative to each other. Groups are
+    mapped independently and accumulated commutatively, so queue order
+    carries no meaning to preserve.
+
+    :param queue.Queue work_queue:
+        The queue both pool generations drain.
+    :returns:
+        Number of sentinels removed.
+    """
+    kept = []
+    removed = 0
+    while True:
+        try:
+            item = work_queue.get_nowait()
+        except Empty:
+            break
+        if item is _SHUTDOWN_SENTINEL:
+            removed += 1
+        else:
+            kept.append(item)
+    for item in kept:
+        work_queue.put(item)
+    return removed
+
+
 _POLL_TIMEOUT_SECONDS = 0.2
 _REBALANCE_INITIAL_SECONDS = 30
 """How soon automatic mode first re-evaluates its thread/worker pair.
@@ -4039,6 +4085,23 @@ def _wake_compute(count):
                             feasible.append(
                                 (candidate_threads, min(needed, ceiling))
                             )
+                    # The whole decision, in one record. Every term that
+                    # steers it is either measured against a single
+                    # sample tile of one frame (the sweep) or gated by
+                    # the configuration currently in effect (the rate),
+                    # so a choice that looks wrong in hindsight can only
+                    # be attributed with the inputs written down.
+                    logger.debug(
+                        "rebalance: rate %.3f frame/s over %.1f s; "
+                        "sweep (s/frame) %s; feasible %s; in effect "
+                        "%d worker(s) x %d thread(s)",
+                        rate,
+                        elapsed,
+                        {c: round(t, 4) for c, t in sweep.items()},
+                        feasible,
+                        compute_pool.size,
+                        current_kernel_threads[0],
+                    )
                     if feasible:
                         new_kernel_threads, new_image_workers = max(
                             feasible, key=lambda pair: pair[0]
@@ -4055,27 +4118,54 @@ def _wake_compute(count):
                             # kernel_threads change: each compute worker's
                             # kernel is built once at worker-start, so this
                             # needs a full generation swap, not a resize.
-                            # ready_queue/gate are untouched -- readers and
-                            # already-queued frames are unaffected, only
-                            # which pool drains the queue changes.
+                            # Queued frames survive it -- readers are
+                            # unaffected and only which pool drains the
+                            # queue changes; the one thing taken off
+                            # ready_queue is the retired pool's own wake
+                            # sentinels, below.
                             current_kernel_threads[0] = new_kernel_threads
                             gate.retarget(
                                 new_image_workers + _PREFETCH_QUEUE_SLACK
                             )
                             old_compute_pool = compute_pool
+                            # Retire the old generation *before* the new
+                            # one exists. Its shutdown wakes its workers
+                            # by putting one _SHUTDOWN_SENTINEL per
+                            # outstanding worker on ready_queue, and a
+                            # sentinel belongs to whoever reads it next:
+                            # spawning the replacement first let the new
+                            # workers drain the backlog, reach that block
+                            # of sentinels and exit on the spot, every
+                            # one of them. That left no consumer at all,
+                            # so no one released the gate, readers parked
+                            # on it, readers_done never fired and this
+                            # loop waited forever -- the mid-run stall
+                            # caught on 39_1-rsmap on 2026-09-19.
+                            #
+                            # The join blocks until every straggler
+                            # finishes its in-flight _map_frame_group
+                            # call -- a deliberate, rare stall (this
+                            # whole block runs at most once per rebalance
+                            # interval), never abandons in-flight work.
+                            old_compute_pool.shutdown(wait=True)
+                            # Sentinels put for workers that had already
+                            # exited outlive the join; with no consumer
+                            # running they are safe to take back out, and
+                            # must be, or the new generation inherits
+                            # them.
+                            surplus = _drain_surplus_sentinels(ready_queue)
+                            if surplus:
+                                logger.debug(
+                                    "compute pool swap: dropped %d surplus "
+                                    "shutdown sentinel(s)",
+                                    surplus,
+                                )
                             compute_pool = _AdjustablePool(
                                 compute_loop,
                                 initial_size=new_image_workers,
                                 name="orgui-rsmap-compute",
                             )
                             compute_pool.wake_workers = _wake_compute
-                            # Blocks until every straggler on the retired
-                            # generation finishes its in-flight
-                            # _map_frame_group call -- a deliberate, rare
-                            # stall (this whole block runs at most once per
-                            # rebalance interval), never abandons
-                            # in-flight work.
-                            old_compute_pool.shutdown(wait=True)
                             rate_at_last_rebalance = rate
                             rebalance_interval = _REBALANCE_INITIAL_SECONDS
                         elif new_image_workers != compute_pool.size:

From 3dca2fd7584c4480fcfd42627e6134c8546aa478 Mon Sep 17 00:00:00 2001
From: "T. Fuchs" <tfuchs@cornell.edu>
Date: Sun, 20 Sep 2026 18:47:59 -0400
Subject: [PATCH 33/33] perf(rsmap): better skipping of non-contributing images
 using quadtree culling

---
 CHANGELOG.md                                  |  29 ++
 .../cpp/reciprocal_reconstruction_cpp.cpp     | 303 +++++++++++++++++-
 .../test/test_reconstruction_group.py         | 162 ++++++++++
 .../test/test_reconstruction_pipeline.py      | 152 +++++++++
 orgui/reconstruction_job.py                   | 133 ++++++++
 5 files changed, 772 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2df990f..ee44db8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1483,6 +1483,35 @@ Reciprocal-space reconstruction:
   is now fully retired before its replacement starts, and any leftover
   signals are cleared while nothing is reading the queue. Mapped output
   is unaffected.
+- **Reciprocal-space mapping now discards a whole block of detector at a
+  time when it cannot reach the output volume.** The kernel could already
+  prove that an individual pixel misses the grid, but only one pixel at a
+  time, so every frame paid that proof for all 6.2 million of them --
+  including the roughly half of a full rotation whose frames reach the
+  selected volume nowhere at all. The same test now runs once per work
+  block first, and a block it rejects is never opened. On the reference
+  job a frame that contributes nothing became 5.3x faster to reject and a
+  frame that does contribute 1.25x faster, 1.46x averaged over the scan;
+  a block that cannot be rejected costs about 0.1% extra. Mapped output
+  is identical, checked record for record on 21 frames across the scan.
+  The profile reports `skipped_bricks`, and `valid_pixels` now counts
+  only pixels actually visited. Applies to flat detectors without a
+  distortion spline.
+- **A reciprocal-space mapping run no longer reads frames that cannot
+  reach the reconstruction volume.** Whether a frame's detector can reach
+  the selected volume at all depends only on the exposure's angles, the
+  detector geometry and the volume, so it is now decided for the whole
+  scan before the first frame is opened. A frame ruled out costs no read,
+  no correction and no mapping; on the reference job, a small volume
+  crossed by a full rotation, 1516 of 3651 frames are ruled out, and
+  deciding that for the whole scan takes 0.084 s. The test only ever
+  rules a frame *out*, never in, so a frame that is kept costs exactly
+  what it did before. Every one of those 1516 frames was mapped to
+  confirm it produces no records. Skipped frames still count toward their
+  checkpoint, so resuming an interrupted job is unaffected, and progress
+  still reaches 100%. A volume that no frame reaches now fails with the
+  existing empty-result error rather than mapping nothing. Set
+  `ORGUI_NO_FRAME_SKIP=1` to disable.
 
 
 ## [1.5.0] (2026-06-07)
diff --git a/orgui/datautils/xrayutils/cpp/reciprocal_reconstruction_cpp.cpp b/orgui/datautils/xrayutils/cpp/reciprocal_reconstruction_cpp.cpp
index e26deed..25def0b 100644
--- a/orgui/datautils/xrayutils/cpp/reciprocal_reconstruction_cpp.cpp
+++ b/orgui/datautils/xrayutils/cpp/reciprocal_reconstruction_cpp.cpp
@@ -683,6 +683,13 @@ struct BlockProfile {
     // Pixels whose whole footprint was proved to miss the grid, so no
     // subdivision was run for them at all (see pixel_misses_grid).
     std::uint64_t skipped_pixels = 0;
+    // Bricks proved to miss the grid whole, so their pixels were never
+    // visited one by one (see the brick reject in accumulate_brick).
+    // Their pixels are counted in skipped_pixels, but not in
+    // valid_pixels: a rejected brick's mask is never read, since a pixel
+    // that cannot reach the grid contributes nothing whether it is
+    // masked or not.
+    std::uint64_t skipped_bricks = 0;
     std::uint64_t voxel_weights = 0;
     std::uint64_t maximum_weights_per_pixel = 0;
     std::uint64_t unreduced_records = 0;
@@ -1384,7 +1391,96 @@ class ReconstructionKernel {
         return output;
     }
 
+    // Which of many frames can reach this grid through one detector
+    // tile, decided from geometry alone -- no pixel data, so a caller can
+    // ask before reading anything.
+    //
+    // The same reject the brick loop runs, applied top down: a whole tile
+    // is one cell, and a cell that cannot be proved outside is quartered
+    // and its children tried, down to cells of `minimum_cell` pixels. A
+    // frame is reported as reaching as soon as one leaf survives, so a
+    // frame that does reach costs a walk down one branch and a frame that
+    // does not usually costs a single test for the whole tile.
+    //
+    // False is a proof and true is not: a frame reported as reaching may
+    // still map nothing, which only costs the work it would have cost
+    // anyway. A frame reported as missing provably maps nothing, so
+    // skipping it cannot change any output.
+    py::array_t<bool> frames_reach_grid(
+        const FloatArray &corner_rays,
+        const FloatArray &angles_start,
+        const FloatArray &angles_end,
+        const std::size_t minimum_cell = 64
+    ) const {
+        const py::buffer_info ray_info = corner_rays.request();
+        const py::buffer_info start_info = angles_start.request();
+        const py::buffer_info end_info = angles_end.request();
+        if (ray_info.ndim != 3 || ray_info.shape[2] != 3) {
+            throw py::value_error("corner_rays must have shape (rows, columns, 3)");
+        }
+        if (ray_info.shape[0] < 2 || ray_info.shape[1] < 2) {
+            throw py::value_error("corner_rays must cover at least one pixel");
+        }
+        if (
+            start_info.ndim != 2 || start_info.shape[1] != 4
+            || end_info.ndim != 2 || end_info.shape[1] != 4
+            || start_info.shape[0] != end_info.shape[0]
+        ) {
+            throw py::value_error(
+                "angles_start and angles_end must have matching shape (frames, 4)"
+            );
+        }
+        if (minimum_cell < 1) {
+            throw py::value_error("minimum_cell must be positive");
+        }
+        const auto frames = static_cast<std::size_t>(start_info.shape[0]);
+        const auto rows = static_cast<std::size_t>(ray_info.shape[0] - 1);
+        const auto columns = static_cast<std::size_t>(ray_info.shape[1] - 1);
+        const auto *ray_data = static_cast<const double *>(ray_info.ptr);
+        const auto *start_data = static_cast<const double *>(start_info.ptr);
+        const auto *end_data = static_cast<const double *>(end_info.ptr);
+
+        py::array_t<bool> output(static_cast<py::ssize_t>(frames));
+        auto *reaches = static_cast<bool *>(output.request().ptr);
+        {
+            py::gil_scoped_release release;
+            for (std::size_t frame = 0; frame < frames; ++frame) {
+                const double *frame_start = start_data + frame * 4;
+                const double *frame_end = end_data + frame * 4;
+                bool still = true;
+                for (int index = 0; index < 4; ++index) {
+                    still = still && frame_start[index] == frame_end[index];
+                }
+                std::vector<CoordinateTransform> transforms;
+                for (const FrameRotation &rotation :
+                     frame_rotations(frame_start, frame_end)) {
+                    transforms.push_back(coordinate_transform(rotation));
+                }
+                const CoordinateTransform &centre_transform =
+                    transforms[transforms.size() / 2];
+                const PixelReach reach = still
+                    ? stationary_reach(centre_transform)
+                    : moving_reach(transforms);
+                reaches[frame] = cell_reaches_grid(
+                    0,
+                    rows,
+                    0,
+                    columns,
+                    columns,
+                    ray_data,
+                    transforms,
+                    centre_transform,
+                    still,
+                    reach,
+                    minimum_cell
+                );
+            }
+        }
+        return output;
+    }
+
 private:
+
     Grid grid_;
     CoordinateFrame frame_;
     double wavevector_;
@@ -1424,6 +1520,7 @@ class ReconstructionKernel {
             combined.valid_pixels += block.valid_pixels;
             combined.coordinate_evaluations += block.coordinate_evaluations;
             combined.skipped_pixels += block.skipped_pixels;
+            combined.skipped_bricks += block.skipped_bricks;
             combined.voxel_weights += block.voxel_weights;
             combined.maximum_weights_per_pixel = std::max(
                 combined.maximum_weights_per_pixel,
@@ -1442,6 +1539,7 @@ class ReconstructionKernel {
         details["valid_pixels"] = combined.valid_pixels;
         details["coordinate_evaluations"] = combined.coordinate_evaluations;
         details["skipped_pixels"] = combined.skipped_pixels;
+        details["skipped_bricks"] = combined.skipped_bricks;
         details["voxel_weights"] = combined.voxel_weights;
         details["maximum_weights_per_pixel"] =
             combined.maximum_weights_per_pixel;
@@ -1629,9 +1727,29 @@ class ReconstructionKernel {
         }
     }
 
-    PixelRays pixel_rays(
-        const std::size_t row,
-        const std::size_t column,
+    // The bilinear patch through the four corner rays of an arbitrary
+    // rectangular cell of the detector, not necessarily one pixel.
+    //
+    // Nothing in this construction, in ray_at(), or in the reach bound
+    // that pixel_misses_grid() applies to it is specific to a cell one
+    // pixel wide: the reach's curvature term is driven by
+    // squared_ray_diameter() of the cell's own corner rays, so it grows
+    // with the cell and stays rigorous at any size. That is what lets a
+    // whole brick be tested against the grid at the cost of one pixel --
+    // see the brick reject in accumulate_brick().
+    //
+    // It does rely on the detector's pixel-to-ray map being affine in
+    // pixel coordinates, so that a cell's interior rays really are the
+    // radial projections of this patch. That holds for a flat detector
+    // without a distortion spline, which is what
+    // DetectorCalibration.primBeamPoints() builds. A distorted detector
+    // would need a measured bound on the deviation added to the reach
+    // before a cell larger than one pixel could be rejected.
+    PixelRays cell_rays(
+        const std::size_t row_begin,
+        const std::size_t row_end,
+        const std::size_t column_begin,
+        const std::size_t column_end,
         const std::size_t columns,
         const double *rays
     ) const {
@@ -1640,10 +1758,10 @@ class ReconstructionKernel {
             const std::size_t offset = (r * stride + c) * 3;
             return Vec3{rays[offset], rays[offset + 1], rays[offset + 2]};
         };
-        const Vec3 r00 = value(row, column);
-        const Vec3 r10 = value(row + 1, column);
-        const Vec3 r01 = value(row, column + 1);
-        const Vec3 r11 = value(row + 1, column + 1);
+        const Vec3 r00 = value(row_begin, column_begin);
+        const Vec3 r10 = value(row_end, column_begin);
+        const Vec3 r01 = value(row_begin, column_end);
+        const Vec3 r11 = value(row_end, column_end);
         return {
             r00,
             {
@@ -1664,6 +1782,15 @@ class ReconstructionKernel {
         };
     }
 
+    PixelRays pixel_rays(
+        const std::size_t row,
+        const std::size_t column,
+        const std::size_t columns,
+        const double *rays
+    ) const {
+        return cell_rays(row, row + 1, column, column + 1, columns, rays);
+    }
+
     Vec3 ray_at(
         const PixelRays &rays,
         const double u,
@@ -2012,6 +2139,124 @@ class ReconstructionKernel {
             + reach.rotation_spread;
     }
 
+    // True only when an entire brick's footprint provably misses the
+    // grid, so none of its pixels could have produced a voxel.
+    //
+    // The same test the per-pixel path runs, one level up. Measured on
+    // the reference 39_1-rsmap job (6.2-megapixel detector, a grid
+    // covering ~1% of a reaching frame, 45x45 bricks): it rejects 98.7%
+    // of bricks on a frame that reaches the grid and 100% on one that
+    // does not, for eight coordinate evaluations against the 16,384 the
+    // brick's pixels would otherwise spend proving the same thing. The
+    // worst case -- nothing rejected anywhere -- costs those eight, or
+    // 0.05% of the brick.
+    bool brick_misses_grid(
+        const PixelRays &brick,
+        const std::vector<CoordinateTransform> &transforms,
+        const CoordinateTransform &centre_transform,
+        const bool stationary,
+        const PixelReach &reach,
+        BlockProfile *profile
+    ) const {
+        if (stationary) {
+            Vec3 footprint[4];
+            for (int corner = 0; corner < 4; ++corner) {
+                footprint[corner] = evaluate_stationary_sample(
+                    brick,
+                    (corner & 1) != 0 ? 1.0 : 0.0,
+                    (corner & 2) != 0 ? 1.0 : 0.0,
+                    centre_transform,
+                    profile
+                ).coordinate;
+            }
+            return pixel_misses_grid(footprint, 4, brick, reach);
+        }
+        Vec3 footprint[8];
+        for (int corner = 0; corner < 8; ++corner) {
+            footprint[corner] = evaluate_lattice_sample(
+                brick,
+                (corner & 1) != 0 ? 1.0 : 0.0,
+                (corner & 2) != 0 ? 1.0 : 0.0,
+                (corner & 4) != 0 ? 1.0 : 0.0,
+                transforms,
+                profile
+            ).coordinate;
+        }
+        return pixel_misses_grid(footprint, 8, brick, reach);
+    }
+
+    bool cell_reaches_grid(
+        const std::size_t row_begin,
+        const std::size_t row_end,
+        const std::size_t column_begin,
+        const std::size_t column_end,
+        const std::size_t columns,
+        const double *rays,
+        const std::vector<CoordinateTransform> &transforms,
+        const CoordinateTransform &centre_transform,
+        const bool stationary,
+        const PixelReach &reach,
+        const std::size_t minimum_cell
+    ) const {
+        const PixelRays cell = cell_rays(
+            row_begin, row_end, column_begin, column_end, columns, rays
+        );
+        if (
+            brick_misses_grid(
+                cell, transforms, centre_transform, stationary, reach, nullptr
+            )
+        ) {
+            return false;
+        }
+        const std::size_t cell_rows = row_end - row_begin;
+        const std::size_t cell_columns = column_end - column_begin;
+        // Small enough that subdividing would buy little: report it as
+        // reaching, which is the conservative answer.
+        if (cell_rows <= minimum_cell && cell_columns <= minimum_cell) {
+            return true;
+        }
+        const std::size_t row_middle = cell_rows > 1
+            ? row_begin + cell_rows / 2
+            : row_end;
+        const std::size_t column_middle = cell_columns > 1
+            ? column_begin + cell_columns / 2
+            : column_end;
+        for (const auto &child : {
+            std::pair<std::size_t, std::size_t>{row_begin, row_middle},
+            std::pair<std::size_t, std::size_t>{row_middle, row_end},
+        }) {
+            if (child.first >= child.second) {
+                continue;
+            }
+            for (const auto &span : {
+                std::pair<std::size_t, std::size_t>{column_begin, column_middle},
+                std::pair<std::size_t, std::size_t>{column_middle, column_end},
+            }) {
+                if (span.first >= span.second) {
+                    continue;
+                }
+                if (
+                    cell_reaches_grid(
+                        child.first,
+                        child.second,
+                        span.first,
+                        span.second,
+                        columns,
+                        rays,
+                        transforms,
+                        centre_transform,
+                        stationary,
+                        reach,
+                        minimum_cell
+                    )
+                ) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
     // True only when the pixel's whole footprint provably lies outside the
     // grid, so subdividing it could not produce a single valid voxel. The
     // subdivision this guards terminates on all-corners-in-one-voxel but
@@ -2760,6 +3005,18 @@ class ReconstructionKernel {
         const std::size_t brick_rows = brick.row_end - brick.row_begin;
         const std::size_t brick_columns = brick.column_end - brick.column_begin;
         const std::size_t row_stride = pixels.row_stride;
+        // Pure detector geometry, like centre_rays below: the frame's
+        // rotation enters only through the transform applied after it,
+        // so the brick's own patch is built once for every frame in the
+        // group rather than once per (brick, frame).
+        const PixelRays brick_rays = cell_rays(
+            brick.row_begin,
+            brick.row_end,
+            brick.column_begin,
+            brick.column_end,
+            columns,
+            rays
+        );
 
         if (max_depth_ == 0) {
             // A pixel's centre ray is pure detector geometry -- the frame's
@@ -2798,6 +3055,30 @@ class ReconstructionKernel {
             const double *const intensity = pixels.intensity[frame];
             const double *const variance = pixels.variance[frame];
             const bool *const mask = pixels.mask[frame];
+            // One test for the whole brick before any of its pixels is
+            // visited. A frame that does not reach the grid at all --
+            // about half of them on a small volume swept through a full
+            // rotation -- leaves here having spent eight coordinate
+            // evaluations instead of eight per pixel.
+            if (
+                brick_misses_grid(
+                    brick_rays,
+                    frame_transforms,
+                    centre_transform,
+                    stationary[frame] != 0,
+                    reach,
+                    profile
+                )
+            ) {
+                if (profile != nullptr) {
+                    // Counted as seen and skipped, so both totals stay
+                    // comparable with a run that visited every pixel.
+                    profile->pixels_seen += brick_rows * brick_columns;
+                    profile->skipped_pixels += brick_rows * brick_columns;
+                    ++profile->skipped_bricks;
+                }
+                continue;
+            }
             for (std::size_t row = brick.row_begin; row < brick.row_end; ++row) {
                 const std::size_t row_offset = row * row_stride;
                 for (
@@ -3423,6 +3704,14 @@ PYBIND11_MODULE(_reciprocal_reconstruction_cpp, module) {
             py::arg("work_block_pixels") = 4096,
             py::arg("memory_budget_bytes") = 512ULL * 1024ULL * 1024ULL
         )
+        .def(
+            "frames_reach_grid",
+            &ReconstructionKernel::frames_reach_grid,
+            py::arg("corner_rays"),
+            py::arg("angles_start"),
+            py::arg("angles_end"),
+            py::arg("minimum_cell") = 64
+        )
         .def(
             "accumulate",
             &ReconstructionKernel::accumulate,
diff --git a/orgui/datautils/xrayutils/test/test_reconstruction_group.py b/orgui/datautils/xrayutils/test/test_reconstruction_group.py
index e7c85b9..140f74c 100644
--- a/orgui/datautils/xrayutils/test/test_reconstruction_group.py
+++ b/orgui/datautils/xrayutils/test/test_reconstruction_group.py
@@ -234,6 +234,168 @@ def test_single_frame_group_reaches_the_same_voxels_as_accumulate():
             )
 
 
+def _partial_grid_case(frames, moving, max_depth, block=64):
+    """A grid covering only a corner of what the detector reaches.
+
+    The brick reject needs both kinds of brick present to be worth
+    testing: some that provably miss the grid and some that do not.
+    """
+    rays = _rays()
+    start, end = _angles(frames, moving)
+    minimum, step, shape = _grid(rays, start, end)
+    # Keep the low corner of the full footprint, a quarter of it per
+    # axis, so most of the detector maps outside.
+    partial_shape = np.maximum(1, shape // 4)
+    kernel = _kernel(minimum, step, partial_shape, max_depth, 1, block)
+    intensity, variance, mask = _payload(frames)
+    return kernel, rays, start, end, intensity, variance, mask
+
+
+@pytest.mark.parametrize("moving", [False, True])
+@pytest.mark.parametrize("max_depth", [0, 2, 3])
+def test_brick_reject_skips_bricks_without_changing_the_answer(
+    moving, max_depth
+):
+    """Rejecting a whole brick must be invisible in the output.
+
+    A brick is proved to miss the grid by the same test a pixel is, one
+    level up, so a rejected brick is one whose pixels would each have
+    been rejected in turn. Skipping it is therefore an optimization with
+    no scientific content -- which only means anything if it is checked
+    against the path that does not have it. ``accumulate`` partitions the
+    detector into runs of the flattened image rather than bricks and has
+    no brick reject, so it is an independent reference here.
+    """
+    case = _partial_grid_case(4, moving, max_depth)
+    kernel, rays, start, end, intensity, variance, mask = case
+
+    grouped = kernel.accumulate_group(
+        intensity, variance, mask, rays, start, end, True
+    )
+    profile = grouped["_profile"]
+    bricks_total = profile["skipped_bricks"] + 1
+    assert profile["skipped_bricks"] > 0, (
+        "the partial grid must leave some brick provably outside it, "
+        "or this test proves nothing"
+    )
+    assert grouped["chunk_id"].size > 0, (
+        "and some brick must still reach it"
+    )
+    assert bricks_total > 1
+
+    reference = _per_frame_reference(
+        kernel, rays, start, end, intensity, variance, mask
+    )
+    found = _as_mapping(grouped)
+    expected = _as_mapping(reference)
+    assert set(found) == set(expected)
+    for key, (weighted, variance_, weight, contributors) in expected.items():
+        got = found[key]
+        assert got[3] == contributors, key
+        assert got[0] == pytest.approx(weighted, rel=1e-12), key
+        assert got[1] == pytest.approx(variance_, rel=1e-12), key
+        assert got[2] == pytest.approx(weight, rel=1e-12), key
+
+
+@pytest.mark.parametrize("moving", [False, True])
+def test_frames_reach_grid_never_rejects_a_frame_that_maps_records(moving):
+    """The frame filter's claim, checked against what mapping produces.
+
+    ``frames_reach_grid`` decides from geometry alone, before any frame
+    is read, so the pipeline can skip a frame's read, correction and
+    kernel call outright. That is only safe because the claim is
+    one-directional: a rejected frame provably maps nothing. An accepted
+    frame may still map nothing, which costs only the work it would have
+    cost anyway.
+
+    A full rotation against a grid sized to one frame's footprint is the
+    case the filter exists for -- most sample angles carry the detector
+    nowhere near that volume.
+    """
+    rays = _rays()
+    frames = 48
+    start = np.zeros((frames, 4))
+    start[:, 0] = 0.10471975511965978
+    start[:, 1] = np.linspace(0.0, 2.0 * np.pi, frames, endpoint=False)
+    end = start.copy()
+    if moving:
+        end[:, 1] += np.deg2rad(0.1)
+    start = np.ascontiguousarray(start)
+    end = np.ascontiguousarray(end)
+
+    # A grid covering what the first frame reaches, and little else.
+    minimum, step, shape = _grid(
+        rays,
+        np.ascontiguousarray(start[:1]),
+        np.ascontiguousarray(end[:1]),
+    )
+    kernel = _kernel(minimum, step, shape, 2, 1, 256)
+
+    reaches = kernel.frames_reach_grid(rays, start, end)
+    assert reaches.shape == (frames,)
+    assert reaches.any(), "the grid was built from a frame that reaches it"
+    assert not reaches.all(), (
+        "a full rotation against a one-frame grid must leave some frame "
+        "provably outside it, or this test proves nothing"
+    )
+
+    intensity, variance, mask = _payload(1)
+    mapped = 0
+    for frame in range(frames):
+        batch = kernel.accumulate_group(
+            intensity,
+            variance,
+            mask,
+            rays,
+            np.ascontiguousarray(start[frame : frame + 1]),
+            np.ascontiguousarray(end[frame : frame + 1]),
+        )
+        if batch["chunk_id"].size:
+            mapped += 1
+            assert reaches[frame], (
+                f"frame {frame} mapped {batch['chunk_id'].size} records "
+                "but the filter would have skipped it"
+            )
+    assert mapped > 0
+
+
+@pytest.mark.parametrize("moving", [False, True])
+def test_brick_reject_costs_a_frame_that_misses_almost_nothing(moving):
+    """A frame that reaches no part of the grid must not be walked.
+
+    This is the case the reject exists for: on a small volume swept
+    through a full rotation about half the scan's frames reach it at all,
+    and each of the rest used to pay four or eight coordinate evaluations
+    for every one of its pixels to establish that. The cost is now one
+    test per brick, so the evaluation count must fall to a small multiple
+    of the brick count rather than of the pixel count.
+    """
+    rays = _rays()
+    start, end = _angles(2, moving)
+    minimum, step, shape = _grid(rays, start, end)
+    # Far outside anything the detector maps to, on every axis at once.
+    unreachable = np.asarray(minimum) + 1000.0 * np.asarray(
+        step
+    ) * np.asarray(shape)
+    kernel = _kernel(unreachable, step, shape, 3, 1, 64)
+    intensity, variance, mask = _payload(2)
+
+    batch = kernel.accumulate_group(
+        intensity, variance, mask, rays, start, end, True
+    )
+    profile = batch["_profile"]
+
+    assert batch["chunk_id"].size == 0
+    assert profile["skipped_bricks"] > 0
+    assert profile["skipped_pixels"] == profile["pixels_seen"]
+    # The whole point: proportional to bricks, not to pixels. A block of
+    # 64 pixels over a 24x28 detector is a handful of bricks per frame,
+    # so anything near the pixel count means the reject did not fire.
+    assert profile["coordinate_evaluations"] < profile["pixels_seen"], (
+        "a missing frame must not cost a per-pixel evaluation"
+    )
+
+
 @pytest.mark.parametrize("moving", [False, True])
 def test_group_is_independent_of_threads_and_brick_size(moving):
     """Splitting the group across workers or bricks changes nothing."""
diff --git a/orgui/datautils/xrayutils/test/test_reconstruction_pipeline.py b/orgui/datautils/xrayutils/test/test_reconstruction_pipeline.py
index 2fa8085..385e80c 100644
--- a/orgui/datautils/xrayutils/test/test_reconstruction_pipeline.py
+++ b/orgui/datautils/xrayutils/test/test_reconstruction_pipeline.py
@@ -785,6 +785,158 @@ def fake_sweep(
     assert len(set(compute_pool_sizes)) == len(compute_pool_sizes)
 
 
+def test_retired_groups_still_complete_their_checkpoint(tmp_path, monkeypatch):
+    """A frame skipped for geometry must still count toward its checkpoint.
+
+    A checkpoint flushes when its remaining-frame countdown reaches zero,
+    and a part is resumable only when its parts' ``frames_covered`` sum to
+    the planned frame count. Both count frames, not ``route()`` calls, so
+    a group that simply vanished would leave its checkpoint one short:
+    never flushed, never written, and on the next run not resumable
+    either. Retiring a group therefore announces it to the router with an
+    empty batch rather than dropping it.
+    """
+    frame_count = 8
+    reachable = 3
+    spec = _spec()
+    grid_name = spec.grids[0].grid_name
+    router = _router({grid_name: [(0, frame_count)]}, tmp_path=tmp_path)
+    bounds = np.zeros((frame_count, 2, 4), dtype=np.float64)
+    tile = (0, 1, 0, 1)
+
+    class _StubKernel:
+        """Reports only the first ``reachable`` frames as reaching."""
+
+        def frames_reach_grid(
+            self, corner_rays, angles_start, angles_end, minimum_cell=64
+        ):
+            reaches = np.zeros(angles_start.shape[0], dtype=bool)
+            reaches[:reachable] = True
+            return reaches
+
+    monkeypatch.setattr(
+        reconstruction_job_module,
+        "_build_kernels",
+        lambda *a, **k: {grid_name: _StubKernel()},
+    )
+
+    groups = [(frame,) for frame in range(frame_count)]
+    kept, completed = reconstruction_job_module._retire_unreachable_groups(
+        groups,
+        spec,
+        _FakeConfig(),
+        bounds,
+        [tile],
+        {tile: np.zeros((2, 2, 3), dtype=np.float64)},
+        router,
+        [grid_name],
+        completed_images=0,
+        total_images=frame_count,
+        progress=None,
+    )
+
+    assert kept == groups[:reachable]
+    assert completed == frame_count - reachable, (
+        "retired frames must be reported as already done, or progress "
+        "never reaches its total"
+    )
+    # Nothing is written yet: the checkpoint is still short the frames
+    # the caller is about to map.
+    assert router.written == []
+
+    # Map the survivors the way the schedulers would, and the checkpoint
+    # must now be complete and carry every frame.
+    from orgui.datautils.xrayutils.reconstruction import (
+        _empty_batch,
+        _read_checkpoint,
+    )
+
+    for group in kept:
+        router.route(grid_name, group[0], _empty_batch(), frames=len(group))
+
+    assert len(router.written) == 1
+    written = _read_checkpoint(router.written[0])
+    assert written["chunk_id"].size == 0
+    import h5py
+
+    with h5py.File(router.written[0], "r") as stored:
+        covered = int(stored.attrs["frames_covered"])
+    assert covered == frame_count, (
+        "every frame must be accounted for, skipped ones included, or a "
+        "resume will redo this checkpoint"
+    )
+
+
+def test_retiring_every_group_fails_instead_of_waiting_forever(
+    tmp_path, monkeypatch
+):
+    """A grid no frame reaches must raise, not hang.
+
+    The per-frame scheduler's completion signal is raised by a delivered
+    group, so starting it with nothing to deliver leaves the coordinator
+    waiting for a signal that can never come. Before the reach filter no
+    caller could reach that state; retiring every group is exactly how to
+    get there, so the empty case returns before the schedulers start and
+    lets the empty-result guard decide.
+    """
+    frame_count = 4
+    spec = _spec()
+    grid_name = spec.grids[0].grid_name
+    router = _router({grid_name: [(0, frame_count)]}, tmp_path=tmp_path)
+    tile = (0, 1, 0, 1)
+
+    class _NothingReaches:
+        def frames_reach_grid(
+            self, corner_rays, angles_start, angles_end, minimum_cell=64
+        ):
+            return np.zeros(angles_start.shape[0], dtype=bool)
+
+    monkeypatch.setattr(
+        reconstruction_job_module,
+        "_build_kernels",
+        lambda *a, **k: {grid_name: _NothingReaches()},
+    )
+    # The per-frame scheduler is the one at risk: the grouped one ends
+    # itself on an empty dispatch. Without this the test takes the
+    # grouped path and passes whether the guard is there or not.
+    monkeypatch.setattr(
+        reconstruction_job_module, "_choose_frames_per_group", lambda *a, **k: 1
+    )
+
+    failure = []
+
+    def run():
+        try:
+            _map_pending_ranges(
+                spec,
+                _SlowScan(frame_count, delay=0.0),
+                _FakeConfig(),
+                np.zeros((frame_count, 2, 4), dtype=np.float64),
+                [tile],
+                [(0, frame_count)],
+                router,
+                correction_pipeline=_correction,
+                effective_memory=256 * 1024**2,
+                threads_per_image=1,
+                accumulation_budget_bytes=None,
+                total_images=frame_count,
+                completed_images=0,
+                progress=None,
+            )
+        except BaseException as error:  # noqa: BLE001 -- reported below
+            failure.append(error)
+
+    runner = threading.Thread(target=run, daemon=True)
+    runner.start()
+    runner.join(timeout=60)
+    assert not runner.is_alive(), (
+        "_map_pending_ranges hung with nothing to map"
+    )
+    assert failure and isinstance(failure[0], RuntimeError), (
+        f"expected the empty-result guard to fire, got {failure!r}"
+    )
+
+
 def test_drain_surplus_sentinels_removes_only_sentinels():
     """The drain keeps queued work and reports what it took out."""
     from queue import Queue
diff --git a/orgui/reconstruction_job.py b/orgui/reconstruction_job.py
index c2e27d3..2902f06 100644
--- a/orgui/reconstruction_job.py
+++ b/orgui/reconstruction_job.py
@@ -35,6 +35,7 @@
     _calibration_probe_all_grids,
     _detector_corner_rays,
     _discover_checkpoint_state,
+    _empty_batch,
     _files_per_job,
     _finalize_reconstruction,
     _kernel_for_grid,
@@ -3123,6 +3124,112 @@ def _frame_groups(frame_range, router, grid_names, frames_per_group):
     return groups
 
 
+FRAME_SKIP_ENV_VAR = "ORGUI_NO_FRAME_SKIP"
+"""Set to disable retiring frames that provably reach no grid.
+
+An escape hatch and an A/B switch, not a tuning knob: the two arms must
+produce identical records, and this is how that is checked on real data.
+"""
+
+
+def _retire_unreachable_groups(
+    frame_groups,
+    spec,
+    config,
+    bounds,
+    detector_tiles,
+    ray_arrays,
+    router,
+    grid_names,
+    *,
+    completed_images,
+    total_images,
+    progress,
+):
+    """Drop frame groups that cannot reach any output grid.
+
+    A small volume swept through a full rotation is only crossed at some
+    sample angles, so a large share of a scan's frames contribute
+    nothing. Deciding that needs no pixel data -- only the exposure's
+    angle bounds, the detector's rays and the grid -- so it can be
+    settled here, before a single frame is read, and those frames then
+    cost no read, no correction and no kernel call at all.
+
+    The test is
+    :meth:`ReconstructionKernel.frames_reach_grid`, the same reject the
+    brick loop runs, applied to the whole tile and then quartered. It is
+    one-directional: a frame it rejects provably maps nothing, while a
+    frame it accepts may still map nothing and simply costs what it
+    always did. Verified on the reference job by mapping all 1516
+    rejected frames of 3651 and confirming every one produced zero
+    records (``doc/design/reciprocal_space_brick_reject.md``).
+
+    A retired group is still announced to ``router`` as covered, with an
+    empty batch. The checkpoint countdown and the ``frames_covered``
+    attribute that makes a part resumable both count frames, so a group
+    that vanished silently would leave its checkpoint short, unflushed
+    and unresumable for the rest of the run.
+
+    Groups are retired whole. A group whose frames are not all
+    unreachable is mapped as before, so grouping never costs coverage.
+
+    :param completed_images:
+        Frames already mapped, for the progress report.
+    :returns:
+        ``(groups_to_map, completed_images)`` with the retired groups'
+        frames added to ``completed_images``.
+    """
+    if not frame_groups or os.environ.get(FRAME_SKIP_ENV_VAR):
+        return frame_groups, completed_images
+    kernels = _build_kernels(spec, config.ub_calculator, threads=1)
+    probe = next(iter(kernels.values()), None)
+    if probe is None or not hasattr(probe, "frames_reach_grid"):
+        # An extension older than this filter: map everything, as before.
+        return frame_groups, completed_images
+
+    started = time.monotonic()
+    angles_start = np.ascontiguousarray(bounds[:, 0])
+    angles_end = np.ascontiguousarray(bounds[:, 1])
+    reaches = np.zeros(bounds.shape[0], dtype=bool)
+    for grid_name in grid_names:
+        kernel = kernels[grid_name]
+        for detector_tile in detector_tiles:
+            reaches |= kernel.frames_reach_grid(
+                ray_arrays[detector_tile], angles_start, angles_end
+            )
+
+    kept = []
+    retired_frames = 0
+    for group in frame_groups:
+        if reaches[list(group)].any():
+            kept.append(group)
+            continue
+        for grid_name in grid_names:
+            router.route(
+                grid_name, group[0], _empty_batch(), frames=len(group)
+            )
+        retired_frames += len(group)
+        completed_images += len(group)
+
+    if retired_frames:
+        logger.info(
+            "frame reach filter: %d of %d frame(s) reach no output grid "
+            "and will not be read (%.1f%%, decided in %.2f s)",
+            retired_frames,
+            retired_frames + sum(len(group) for group in kept),
+            100.0 * retired_frames / max(1, retired_frames
+                                         + sum(len(g) for g in kept)),
+            time.monotonic() - started,
+        )
+        if progress is not None:
+            progress(
+                completed_images,
+                total_images + 1,
+                f"Skipped {retired_frames} frame(s) that reach no grid",
+            )
+    return kept, completed_images
+
+
 def _map_frame_groups_streamed(
     spec,
     scan,
@@ -3721,8 +3828,34 @@ def layout_for(threads_per_image_seed):
         )
     ]
 
+    frame_groups, completed_images = _retire_unreachable_groups(
+        frame_groups,
+        spec,
+        config,
+        bounds,
+        detector_tiles,
+        ray_arrays,
+        router,
+        grid_names,
+        completed_images=completed_images,
+        total_images=total_images,
+        progress=progress,
+    )
+
     routed_before = getattr(router, "routed_records", 0)
 
+    if not frame_groups:
+        # Every group was retired, so there is nothing to schedule -- and
+        # the per-frame scheduler must not be started empty: its
+        # completion signal is raised by a delivered group, so with none
+        # to deliver the coordinator would wait for it forever. The
+        # checkpoints are already complete, having been routed above; all
+        # that is left is to decide whether an empty result is legitimate.
+        _fail_if_nothing_was_routed(
+            router, routed_before, total_images, progress
+        )
+        return
+
     if frames_per_group > 1:
         group_workers, group_threads, group_depth = _group_pipeline_layout(
             spec, tiles, scheduler_memory, seed_prepare_workers