ewoksxes 0.0.1__tar.gz

ewoksxes-0.0.1/LICENSE.md

@@ -0,0 +1,20 @@
+# MIT License
+
+**Copyright (c) 2025 European Synchrotron Radiation Facility**
+
+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.

ewoksxes-0.0.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: ewoksxes
+Version: 0.0.1
+Summary: Data processing workflows for XES
+Author-email: ESRF <dau-pydev@esrf.fr>
+License: # MIT License
+        
+        **Copyright (c) 2025 European Synchrotron Radiation Facility**
+        
+        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.
+        
+Project-URL: Homepage, https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes/
+Project-URL: Documentation, https://ewoksxes.readthedocs.io/
+Project-URL: Repository, https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes/
+Project-URL: Issues, https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes/issues
+Project-URL: Changelog, https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes/-/blob/main/CHANGELOG.md
+Keywords: xes,ewoks
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: ewoks
+Requires-Dist: scipy
+Requires-Dist: h5py
+Requires-Dist: fabio
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pyqt6; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ewoksxes[test]; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: ewoksxes[test]; extra == "doc"
+Requires-Dist: sphinx>=4.5; extra == "doc"
+Requires-Dist: sphinx-autodoc-typehints>=1.16; extra == "doc"
+Requires-Dist: pydata-sphinx-theme; extra == "doc"
+Dynamic: license-file
+
+# ewoksxes
+
+The **ewoksxes** project is a Python library designed to provide workflow tasks for X-ray Emission Spectroscopy Data Processing using Ewoks (Extensible Workflow System).
+
+## Installation
+
+By default, at the ESRF, `ewoksxes` should be installed on Ewoks workers using an Ansible script by the DAU team.
+If you wish to install `ewoksxes` manually, ensure you have Python 3.10+ and `pip` installed. You can install the library directly from PyPI:
+
+```sh
+pip install ewoksxes
+```
+
+Alternatively, to install from source, clone this repository and run:
+
+```sh
+git clone https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes.git
+cd ewoksxes
+pip install -e .
+```
+
+## Quickstart Guide
+
+### Running an `ewoksxes` Workflow
+
+Most of the time, the workflow will be automatically ran from the Bliss control system.
+However if you wish to execute the workflow by hand, you can use the following:
+
+`ewoks execute workflow.json`
+
+Some examples of workflow are found in `ewoksxes/workflows`
+
+## How-To Guides
+
+For detailed instructions on various tasks, please refer to the How-To Guides in the documentation, which cover topics such as:
+
+- Configuration of XES workflows
+- Running workflows locally for testing
+- Using the API to run specific tasks (e.g., calibration, combining spectra)
+
+## Documentation
+
+Comprehensive documentation, including an API reference, tutorials, and conceptual explanations, can be found in the [doc directory](./doc) or online at the [ReadTheDocs page](https://ewoksxes.readthedocs.io).
+
+## Contributing
+
+Contributions are welcome! To contribute, please:
+
+1. Clone the repository and create a new branch for your feature or fix.
+2. Write tests and ensure that the code is well-documented.
+3. Submit a merge request for review.
+
+See the [`CONTRIBUTING.md`](./CONTRIBUTING.md) file for more details.
+
+## License
+
+This project is licensed under the MIT License. See the [`LICENSE.md`](./LICENSE.md) file for details.
+
+## Support
+
+If you have any questions or issues, please open an issue on the GitLab repository or contact the support team via a [data processing request ticket](https://requests.esrf.fr/plugins/servlet/desk/portal/41).

ewoksxes-0.0.1/README.md

@@ -0,0 +1,61 @@
+# ewoksxes
+
+The **ewoksxes** project is a Python library designed to provide workflow tasks for X-ray Emission Spectroscopy Data Processing using Ewoks (Extensible Workflow System).
+
+## Installation
+
+By default, at the ESRF, `ewoksxes` should be installed on Ewoks workers using an Ansible script by the DAU team.
+If you wish to install `ewoksxes` manually, ensure you have Python 3.10+ and `pip` installed. You can install the library directly from PyPI:
+
+```sh
+pip install ewoksxes
+```
+
+Alternatively, to install from source, clone this repository and run:
+
+```sh
+git clone https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes.git
+cd ewoksxes
+pip install -e .
+```
+
+## Quickstart Guide
+
+### Running an `ewoksxes` Workflow
+
+Most of the time, the workflow will be automatically ran from the Bliss control system.
+However if you wish to execute the workflow by hand, you can use the following:
+
+`ewoks execute workflow.json`
+
+Some examples of workflow are found in `ewoksxes/workflows`
+
+## How-To Guides
+
+For detailed instructions on various tasks, please refer to the How-To Guides in the documentation, which cover topics such as:
+
+- Configuration of XES workflows
+- Running workflows locally for testing
+- Using the API to run specific tasks (e.g., calibration, combining spectra)
+
+## Documentation
+
+Comprehensive documentation, including an API reference, tutorials, and conceptual explanations, can be found in the [doc directory](./doc) or online at the [ReadTheDocs page](https://ewoksxes.readthedocs.io).
+
+## Contributing
+
+Contributions are welcome! To contribute, please:
+
+1. Clone the repository and create a new branch for your feature or fix.
+2. Write tests and ensure that the code is well-documented.
+3. Submit a merge request for review.
+
+See the [`CONTRIBUTING.md`](./CONTRIBUTING.md) file for more details.
+
+## License
+
+This project is licensed under the MIT License. See the [`LICENSE.md`](./LICENSE.md) file for details.
+
+## Support
+
+If you have any questions or issues, please open an issue on the GitLab repository or contact the support team via a [data processing request ticket](https://requests.esrf.fr/plugins/servlet/desk/portal/41).

ewoksxes-0.0.1/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = [
+    "setuptools>=61",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ewoksxes"
+version = "0.0.1"
+keywords = [
+    "xes",
+    "ewoks"
+]
+
+authors = [{name = "ESRF", email = "dau-pydev@esrf.fr"}]
+description = "Data processing workflows for XES"
+readme = {file = "README.md", content-type = "text/markdown"}
+license = {file = "LICENSE.md"}
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "ewoks",
+    "scipy",
+    "h5py",
+    "fabio",
+]
+
+[project.urls]
+Homepage = "https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes/"
+Documentation = "https://ewoksxes.readthedocs.io/"
+Repository = "https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes/"
+Issues = "https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes/issues"
+Changelog = "https://gitlab.esrf.fr/workflow/ewoksapps/ewoksxes/-/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+test = [
+    "pytest >=7",
+    "pyqt6",
+]
+dev = [
+    "ewoksxes[test]",
+    "ruff",
+]
+doc = [
+    "ewoksxes[test]",
+    "sphinx >=4.5",
+    "sphinx-autodoc-typehints >=1.16",
+    "pydata-sphinx-theme",
+]
+
+[tool.setuptools]
+package-dir = {""= "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"ewoksxes.tests.data" = ["*.h5", "*.edf", "*.npy"]
+"ewoksxes.workflows" = ["*.json"]
+"*" = ["*.ows", "*.png", "*.svg"]
+
+[project.entry-points."ewoks.tasks.class"]
+"ewoksxes.tasks.*" = "ewoksxes"
+
+[tool.coverage.run]
+omit = [
+    "*/tests/*"
+]
+
+[tool.bandit.assert_used]
+skips = ["*/test_*.py"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "S",    # flake8-bandit
+    "W",    # pycodestyle warnings
+]
+
+[tool.ruff.lint.per-file-ignores]
+"**/test_*.py" = ["S101"]   # Allow asserts
+
+[tool.ruff.lint.isort]
+known-first-party = ["ewoksxes"]

ewoksxes-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ewoksxes-0.0.1/src/ewoksxes/tasks/__init__.py

@@ -0,0 +1,19 @@
+from .calibrate_energy import CalibrateEnergy
+from .combine_spectra import CombineSpectra
+from .compute_flat_and_mask import ComputeFlatAndMask
+from .compute_roi import ComputeROI
+from .fit_polynomial_2d import FitPolynomial2D
+from .flat_field_correction import FlatFieldCorrection
+from .load_raw_data import LoadRawDataAverage
+from .save_flat_and_mask import SaveFlatAndMask
+
+__all__ = [
+    "CalibrateEnergy",
+    "CombineSpectra",
+    "ComputeFlatAndMask",
+    "ComputeROI",
+    "FitPolynomial2D",
+    "FlatFieldCorrection",
+    "LoadRawDataAverage",
+    "SaveFlatAndMask",
+]

ewoksxes-0.0.1/src/ewoksxes/tasks/calibrate_energy.py

@@ -0,0 +1,69 @@
+import logging
+
+import numpy as np
+from ewokscore import Task
+
+logger = logging.getLogger(__name__)
+
+
+class CalibrateEnergy(
+    Task,
+    input_names=["spectra", "kb_px", "vtc_px", "e_kb", "e_vtc"],
+    output_names=["energies", "spectra", "slope", "intercept"],
+):
+    """
+    Two-point linear calibration from pixel -> energy for each ROI.
+
+    Inputs
+    ------
+    spectra : list[np.ndarray]
+        One 1D spectrum per ROI.
+    kb_px : list[float] | np.ndarray
+        Pixel index of the Kβ reference for each ROI.
+    vtc_px : list[float] | np.ndarray
+        Pixel index of the VTC reference for each ROI.
+    e_kb : float
+        Known energy of the Kβ line (eV).
+    e_vtc : float
+        Known energy of the VTC line (eV).
+
+    Outputs
+    -------
+    energies : list[np.ndarray]
+        Energy axis per ROI (same length as its spectrum).
+    spectra : list[np.ndarray]
+        Pass-through of the input spectra (pipeline convenience).
+    slope : np.ndarray
+        ΔE / Δpixel per ROI.
+    intercept : np.ndarray
+        Intercept per ROI so that E = slope * x + intercept.
+    """
+
+    def run(self):
+        spectra = list(self.inputs.spectra)
+        kb = np.asarray(self.inputs.kb_px, dtype=float).ravel()
+        vtc = np.asarray(self.inputs.vtc_px, dtype=float).ravel()
+        e_kb = float(self.inputs.e_kb)
+        e_vtc = float(self.inputs.e_vtc)
+
+        if len(spectra) != kb.size or kb.size != vtc.size:
+            raise ValueError(
+                "Lengths must match: len(spectra) == len(kb_px) == len(vtc_px)"
+            )
+
+        dv = vtc - kb
+        if np.any(dv == 0.0):
+            raise ValueError("kb_px and vtc_px must differ for every ROI")
+
+        slope = (e_vtc - e_kb) / dv  # shape (n_rois,)
+        intercept = e_kb - slope * kb  # shape (n_rois,)
+
+        energies = []
+        for s, m, b in zip(spectra, slope, intercept):
+            x = np.arange(s.shape[0], dtype=float)
+            energies.append(m * x + b)
+
+        self.outputs.energies = energies
+        self.outputs.spectra = spectra
+        self.outputs.slope = slope
+        self.outputs.intercept = intercept

ewoksxes-0.0.1/src/ewoksxes/tasks/combine_spectra.py

@@ -0,0 +1,117 @@
+import logging
+
+import numpy as np
+from ewokscore import Task
+from scipy.interpolate import interp1d
+
+logger = logging.getLogger(__name__)
+
+
+class CombineSpectra(
+    Task,
+    input_names=["energies", "spectra", "energy_range", "n_points"],
+    optional_input_names=["normalize", "norm_range"],
+    output_names=["energy", "summed_spectrum"],
+):
+    """
+    Optionally normalize spectra, then interpolate each onto a common energy axis
+    and sum them.
+
+    Inputs
+    ------
+    - energies: list of 1D energy arrays (or lists), one per spectrum
+    - spectra:       list of 1D spectra (same length as energies)
+    - energy_range:  (emin, emax)  -> the range of the FINAL output energy axis
+    - n_points:      int >= 2      -> number of points on the FINAL output energy axis
+
+    Optional
+    --------
+    - normalize:  bool (default False). When True, each spectrum is normalized by
+                  its integral over 'norm_range' before interpolation/summing.
+    - norm_range: (emin, emax) normalization window (required when normalize=True)
+
+    Outputs
+    -------
+    - energy:           np.ndarray of length n_points, spanning [emin, emax]
+    - summed_spectrum:  np.ndarray of same length, sum of all interpolated spectra
+    """
+
+    def run(self):
+        raw_energies = self.inputs.energies
+        raw_spectra = self.inputs.spectra
+        energy_range = self.inputs.energy_range
+        n_points = self.inputs.n_points
+
+        # Validate and USE energy_range as the FINAL axis range
+        try:
+            emin, emax = energy_range
+        except (TypeError, ValueError):
+            raise ValueError(f"energy_range must be (emin, emax); got {energy_range}")
+        if emin >= emax:
+            raise ValueError(f"Invalid energy_range: {energy_range}")
+        if not isinstance(n_points, int) or n_points < 2:
+            raise ValueError(f"n_points must be integer >= 2, got {n_points}")
+
+        # Convert to arrays
+        energies_list = [np.asarray(e, dtype=float) for e in raw_energies]
+        spectra = [np.asarray(s, dtype=float) for s in raw_spectra]
+
+        if len(energies_list) != len(spectra):
+            raise ValueError("energies_list and spectra must have the same length")
+
+        # Optional normalization
+        if bool(self.get_input_value("normalize", False)):
+            norm_range = self.get_input_value("norm_range", None)
+            if norm_range is None or len(norm_range) != 2:
+                raise ValueError(
+                    "When normalize=True, norm_range=(emin, emax) must be "
+                    f"provided; got {norm_range}"
+                )
+            nmin, nmax = float(norm_range[0]), float(norm_range[1])
+
+            for idx, (energies, spectrum) in enumerate(zip(energies_list, spectra)):
+                mask = (energies >= nmin) & (energies <= nmax)
+                if not np.any(mask):
+                    logger.warning(
+                        f"Spectrum {idx}: no points in norm_range {nmin}-{nmax}; "
+                        "leaving spectrum unchanged"
+                    )
+                    continue
+                norm_factor = np.trapezoid(spectrum[mask], energies[mask])
+                if norm_factor == 0 or not np.isfinite(norm_factor):
+                    logger.warning(
+                        f"Spectrum {idx}: invalid normalization factor "
+                        f"{norm_factor}; leaving spectrum unchanged"
+                    )
+                    continue
+                spectra[idx] = spectrum / norm_factor
+            logger.info("CombineSpectra: normalization completed.")
+
+        # Build FINAL energy axis USING energy_range
+        energy = np.linspace(emin, emax, n_points, dtype=float)
+        summed = np.zeros_like(energy)
+
+        # Interpolate & sum
+        for idx, (energies, spectrum) in enumerate(zip(energies_list, spectra)):
+            if energies.shape[0] != spectrum.shape[0]:
+                common = min(energies.shape[0], spectrum.shape[0])
+                logger.warning(
+                    f"Spectrum {idx} length {spectrum.shape[0]} and energies "
+                    f"{energies.shape[0]} mismatch; trimming to first {common} "
+                    "points for interpolation."
+                )
+                energies_to_use = energies[:common]
+                spectrum_to_use = spectrum[:common]
+            else:
+                energies_to_use = energies
+                spectrum_to_use = spectrum
+
+            interp = interp1d(
+                energies_to_use, spectrum_to_use, bounds_error=False, fill_value=0.0
+            )
+            summed += interp(energy)
+            logger.info(f"CombineSpectra: added spectrum {idx} to sum.")
+
+        self.outputs.energy = energy
+        self.outputs.summed_spectrum = summed
+        logger.info("CombineSpectra completed.")

ewoksxes-0.0.1/src/ewoksxes/tasks/compute_flat_and_mask.py

@@ -0,0 +1,176 @@
+import logging
+
+import numpy as np
+from ewokscore import Task
+
+from .utils import poly2d_eval
+
+logger = logging.getLogger(__name__)
+
+
+def _expand_columns(mask: np.ndarray, expand: int) -> np.ndarray:
+    """Binary dilate a column mask by ±expand columns (no extra deps)."""
+    if expand <= 0:
+        return mask
+    out = mask.copy()
+    for k in range(1, expand + 1):
+        out[:, k:] |= mask[:, :-k]
+        out[:, :-k] |= mask[:, k:]
+    return out
+
+
+def _expand_rows(mask: np.ndarray, expand: int) -> np.ndarray:
+    """Binary dilate a row mask by ±expand rows (no extra deps)."""
+    if expand <= 0:
+        return mask
+    out = mask.copy()
+    for k in range(1, expand + 1):
+        out[k:, :] |= mask[:-k, :]
+        out[:-k, :] |= mask[k:, :]
+    return out
+
+
+class ComputeFlatAndMask(
+    Task,
+    input_names=["image", "coeffs"],
+    optional_input_names=[
+        # base validity thresholds
+        "min_intensity",  # discard pixels with raw <= this (default: 0.0)
+        "min_fitted",  # discard where fitted surface <= this (default: 1e-6)
+        # gap detection via residual ratio
+        "ratio_threshold",  # ratio=image/fitted below this => bad (default: 0.2)
+        # fraction of bad pixels in a column to flag gap (default: 0.8)
+        "column_fraction_threshold",
+        "row_fraction_threshold",  # same for rows (default: 0.95)
+        "detect_columns",  # default True
+        "detect_rows",  # default False (usually gaps are vertical)
+        "gap_expand",  # dilate gap bands by this many pixels (default: 1)
+        # flat output
+        "invert",  # output flat = fitted/image if True (default True)
+        "clip_flat",  # optional clip for flat magnitudes, e.g. (0.25, 4.0)
+    ],
+    output_names=["flat", "mask"],
+):
+    """
+    Compute flat-field and detect gap bands *automatically* from the 2D fit residuals.
+
+    Pipeline:
+      1) Evaluate fitted surface S = poly2d(x,y; coeffs).
+      2) Build a base invalid mask:
+           - image <= min_intensity OR ~finite OR S <= min_fitted
+      3) Residual ratio R = image / S on valid base pixels; elsewhere treat as 0.
+      4) Candidate bad pixels = base_invalid OR (R <= ratio_threshold).
+      5) Gap detection (bands):
+           - per-column bad fraction; mark columns >= column_fraction_threshold as gaps.
+           - optional per-row bad fraction for horizontal bands.
+           - optional dilation by 'gap_expand' px.
+      6) Final valid mask = NOT(gap_bands) AND NOT(base_invalid)
+      7) Flat:
+           - if invert: flat = S / image on valid pixels (else flat = image / S)
+           - fill invalid pixels with 1.0 (so correction leaves them unchanged;
+             mask will zero them later).
+           - optional clipping.
+
+    Outputs:
+      - flat (float32, finite)
+      - mask (float32, 1 valid / 0 invalid). Gaps are 0 in the mask.
+    """
+
+    def run(self):
+        img = np.asarray(self.inputs.image, dtype=np.float64)
+        coeffs = np.asarray(self.inputs.coeffs, dtype=np.float64)
+
+        # --- Parameters & defaults
+        min_intensity = float(self.get_input_value("min_intensity", 0.0))
+        min_fitted = float(self.get_input_value("min_fitted", 1e-6))
+
+        ratio_thr = float(self.get_input_value("ratio_threshold", 0.2))
+        col_fr_thr = float(self.get_input_value("column_fraction_threshold", 0.8))
+        row_fr_thr = float(self.get_input_value("row_fraction_threshold", 0.95))
+        detect_columns = bool(self.get_input_value("detect_columns", True))
+        detect_rows = bool(self.get_input_value("detect_rows", False))
+        gap_expand = int(self.get_input_value("gap_expand", 1))
+
+        invert = bool(self.get_input_value("invert", True))
+        clip_flat = self.get_input_value("clip_flat", None)  # e.g., (0.25, 4.0) or None
+
+        H, W = img.shape
+        y = np.arange(H, dtype=np.float64)
+        x = np.arange(W, dtype=np.float64)
+        X, Y = np.meshgrid(x, y)
+
+        # --- Evaluate fitted surface
+        fitted = poly2d_eval((X, Y), coeffs)
+
+        # --- Base invalid mask
+        base_invalid = (
+            (img <= min_intensity)
+            | ~np.isfinite(img)
+            | (fitted <= min_fitted)
+            | ~np.isfinite(fitted)
+        )
+
+        # --- Residual ratio
+        ratio = np.zeros_like(img, dtype=np.float64)
+        good = ~base_invalid
+        ratio[good] = img[good] / np.maximum(fitted[good], min_fitted)
+        candidate_bad = base_invalid | (ratio <= ratio_thr)
+
+        # --- Gap detection (bands)
+        gap_bands = np.zeros_like(candidate_bad, dtype=bool)
+
+        if detect_columns:
+            col_bad_frac = candidate_bad.mean(axis=0)  # per-column fraction bad
+            gap_cols = col_bad_frac >= col_fr_thr
+            if gap_cols.any():
+                gap_bands[:, gap_cols] = True
+            logger.info(
+                "Detected %d gap columns (thr=%.2f)",
+                int(gap_cols.sum()),
+                col_fr_thr,
+            )
+
+        if detect_rows:
+            row_bad_frac = candidate_bad.mean(axis=1)  # per-row fraction bad
+            gap_rows = row_bad_frac >= row_fr_thr
+            if gap_rows.any():
+                gap_bands[gap_rows, :] = True
+            logger.info(
+                "Detected %d gap rows (thr=%.2f)",
+                int(gap_rows.sum()),
+                row_fr_thr,
+            )
+
+        # --- Expand/dilate gap bands to cover edges
+        if detect_columns and gap_expand > 0:
+            gap_bands = _expand_columns(gap_bands, gap_expand)
+        if detect_rows and gap_expand > 0:
+            gap_bands = _expand_rows(gap_bands, gap_expand)
+
+        # --- Final valid mask
+        valid = (~gap_bands) & (~base_invalid)
+
+        # --- Flat computation
+        # invert=True  => flat = fitted / image (typical: multiply raw by flat)
+        # invert=False => flat = image / fitted
+        eps = 1e-12
+        flat = np.ones_like(img, dtype=np.float64)
+        if invert:
+            flat[valid] = fitted[valid] / np.maximum(img[valid], eps)
+        else:
+            flat[valid] = img[valid] / np.maximum(fitted[valid], eps)
+
+        if clip_flat is not None:
+            lo, hi = clip_flat
+            flat = np.clip(flat, lo, hi)
+
+        # Fill invalids with 1.0 (so downstream (image*flat*mask) → masked zeros)
+        flat[~valid] = 1.0
+
+        self.outputs.flat = flat.astype(np.float32)
+        self.outputs.mask = valid.astype(np.float32)
+        logger.info(
+            "ComputeFlatAndMask: valid=%.2f%%, gaps=%.2f%%",
+            100.0 * valid.mean(),
+            100.0 * gap_bands.mean(),
+        )