fortocorrpy 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,157 @@
1
+ """Topographic correction methods, implemented per the source literature.
2
+
3
+ Six methods operate on the observed (sloped) reflectance ``rho_T`` and share
4
+ the local illumination condition ``cos i``. Cosine, C, SCS, SCS+C and ER refer
5
+ the result to horizontal-terrain illumination ``cos i_h = cos(theta_s)``; SE
6
+ removes the fitted illumination trend and re-centres on the regression-sample
7
+ mean instead. The regression coefficients, where a method uses them, are
8
+ estimated from the forest sample upstream; the formulas themselves run over
9
+ the whole raster.
10
+
11
+ Methods and formulas (see DESIGN_SPEC, "Correction methods")
12
+ ------------------------------------------------------------
13
+ * ``cosine`` : rho_H = rho_T * cos(theta_s) / cos i
14
+ * ``scs`` : rho_H = rho_T * (cos(alpha) * cos(theta_s)) / cos i
15
+ * ``c`` : rho_H = rho_T * (cos(theta_s) + C) / (cos i + C)
16
+ * ``scsc`` : rho_H = rho_T * (cos(alpha) * cos(theta_s) + C) / (cos i + C)
17
+ * ``se`` : rho_H = rho_T - (a * cos i + b) + mean(rho)
18
+ * ``er`` : rho_H = rho_T - a * (cos i - cos(theta_s))
19
+
20
+ Two groups by structure:
21
+
22
+ * Denominator-form (cosine, scs, c, scsc): ``cos i`` is in the denominator, so
23
+ the correction factor diverges as it approaches zero.
24
+ * Subtractive-form (se, er): no denominator, so they do not diverge.
25
+
26
+ With ``shadow=True``, self-shadow (``cos i <= 0``) is NaN for every method.
27
+
28
+ Coefficient requirement
29
+ ------------------------
30
+ ``cosine`` and ``scs`` need no regression; they may be called with
31
+ ``coeff=None``. ``c`` and ``scsc`` need ``C``; ``se`` and ``er`` need the slope
32
+ ``a``. The pipeline decides whether to run the regression at all based on the
33
+ selected methods.
34
+
35
+ ``cos i = -C`` guard: ``c`` and ``scsc`` divide by ``cos i + C``. A minimal
36
+ numerical guard against a near-zero denominator is applied: pixels whose
37
+ denominator falls below 1e-6 in magnitude become NaN. The floor is a fixed
38
+ conservative value rather than one derived from the band's noise level; it
39
+ prevents blow-up without affecting well-illuminated pixels.
40
+ """
41
+
42
+ from __future__ import annotations
43
+
44
+ import numpy as np
45
+
46
+ from .config import DENOMINATOR_METHODS
47
+
48
+ __all__ = ["correct"]
49
+
50
+ # Denominators with absolute value below this are treated as singular (NaN),
51
+ # guarding the cos i + C and cos i divisions against blow-up.
52
+ _DENOM_FLOOR = 1e-6
53
+
54
+
55
+ def _safe_divide(numerator, denominator):
56
+ """Divide, returning NaN where the denominator is near zero."""
57
+ denom = np.asarray(denominator, dtype=np.float32)
58
+ out = np.full(np.broadcast(numerator, denom).shape, np.nan, dtype=np.float32)
59
+ ok = np.abs(denom) >= _DENOM_FLOOR
60
+ np.divide(numerator, denom, out=out, where=ok)
61
+ return out
62
+
63
+
64
+ def correct(method, reflectance, cos_i, cos_theta_s, *, cos_alpha=None,
65
+ coeff=None, shadow=True):
66
+ r"""Apply one correction method to a single band.
67
+
68
+ Parameters
69
+ ----------
70
+ method : str
71
+ One of ``cosine``, ``scs``, ``c``, ``scsc``, ``se``, ``er``.
72
+ reflectance : numpy.ndarray
73
+ Single-band observed reflectance ``rho_T``.
74
+ cos_i : numpy.ndarray
75
+ Local illumination condition, same shape as ``reflectance``.
76
+ cos_theta_s : float or numpy.ndarray
77
+ Horizontal reference ``cos(theta_s)``; scalar or per-pixel.
78
+ cos_alpha : numpy.ndarray, optional
79
+ Cosine of slope angle, pre-computed once from
80
+ ``np.cos(alpha)``. Required for ``scs`` and ``scsc`` (the
81
+ slope-TC group), unused otherwise.
82
+ coeff : BandCoefficients, optional
83
+ Regression coefficients for this band. Required for ``c``, ``scsc``
84
+ (uses ``C``) and ``se``, ``er`` (uses slope ``a``). May be ``None`` for
85
+ ``cosine`` and ``scs``.
86
+ shadow : bool, default True
87
+ If True, self-shadow pixels (``cos i <= 0``) are NaN for every method.
88
+
89
+ Returns
90
+ -------
91
+ numpy.ndarray
92
+ Corrected reflectance ``rho_H``, ``float32``, same shape as
93
+ ``reflectance``.
94
+ """
95
+ rho = np.asarray(reflectance, dtype=np.float32)
96
+ ci = np.asarray(cos_i, dtype=np.float32)
97
+ cos_ts = np.asarray(cos_theta_s, dtype=np.float32)
98
+
99
+ if method == "cosine":
100
+ rho_h = rho * _safe_divide(cos_ts, ci)
101
+
102
+ elif method == "scs":
103
+ if cos_alpha is None:
104
+ raise ValueError("scs requires cos_alpha (cosine of slope)")
105
+ cos_a = np.asarray(cos_alpha, dtype=np.float32)
106
+ rho_h = rho * _safe_divide(cos_a * cos_ts, ci)
107
+
108
+ elif method == "c":
109
+ if coeff is None:
110
+ raise ValueError("c (C-correction) requires coeff with C")
111
+ c = np.float32(coeff.c)
112
+ if not np.isfinite(c):
113
+ # slope a = 0: no illumination trend to correct. Use identity here,
114
+ # but still let the self-shadow mask below apply.
115
+ rho_h = rho.astype(np.float32).copy()
116
+ else:
117
+ rho_h = rho * _safe_divide(cos_ts + c, ci + c)
118
+
119
+ elif method == "scsc":
120
+ if cos_alpha is None:
121
+ raise ValueError("scsc requires cos_alpha (cosine of slope)")
122
+ if coeff is None:
123
+ raise ValueError("scsc requires coeff with C")
124
+ cos_a = np.asarray(cos_alpha, dtype=np.float32)
125
+ c = np.float32(coeff.c)
126
+ if not np.isfinite(c):
127
+ # slope a = 0: identity here, but the self-shadow mask below applies.
128
+ rho_h = rho.astype(np.float32).copy()
129
+ else:
130
+ rho_h = rho * _safe_divide(cos_a * cos_ts + c, ci + c)
131
+
132
+ elif method == "se":
133
+ if coeff is None:
134
+ raise ValueError("se requires coeff with slope, intercept, and mean_reflectance")
135
+ a = np.float32(coeff.slope)
136
+ b = np.float32(coeff.intercept)
137
+ mean_rho = np.float32(coeff.mean_reflectance)
138
+ # Statistical-Empirical: remove the regression trend, re-centre on the
139
+ # sample-mean reflectance.
140
+ rho_h = rho - (a * ci + b) + mean_rho
141
+
142
+ elif method == "er":
143
+ if coeff is None:
144
+ raise ValueError("er requires coeff with slope a")
145
+ a = np.float32(coeff.slope)
146
+ # Empirical Rotation: remove the regression trend, re-centre on the
147
+ # horizontal reference cos(theta_s). The intercept cancels.
148
+ rho_h = rho - a * (ci - cos_ts)
149
+
150
+ else:
151
+ raise ValueError(f"unknown method: {method!r}")
152
+
153
+ # Self-shadow: NaN for every method.
154
+ if shadow:
155
+ rho_h = np.where(ci > 0.0, rho_h, np.nan)
156
+
157
+ return rho_h.astype(np.float32, copy=False)
@@ -0,0 +1,109 @@
1
+ """fortocorrpy: topographic correction of optical satellite imagery.
2
+
3
+ A satellite- and format-agnostic toolkit for topographic correction (TC) of
4
+ optical imagery over mountainous terrain. It applies several correction
5
+ methods through one interface and, optionally, reports the standard
6
+ reflectance-level metrics for each method in the same call, so methods can be
7
+ compared without re-running bespoke evaluation code.
8
+
9
+ Quick start
10
+ -----------
11
+ Single image:
12
+
13
+ >>> from fortocorrpy import Config, correct_image, io
14
+ >>> from datetime import datetime, timezone
15
+ >>>
16
+ >>> cfg = Config(
17
+ ... mask_source="ndvi",
18
+ ... methods=("cosine", "scsc", "er"),
19
+ ... )
20
+ >>> result = correct_image(
21
+ ... image_path="scene.tif",
22
+ ... datetime_utc=datetime(2024, 6, 21, 3, 0, tzinfo=timezone.utc),
23
+ ... dem_path="dem.tif",
24
+ ... forest_path="ndvi.tif",
25
+ ... config=cfg,
26
+ ... evaluate=True,
27
+ ... )
28
+ >>>
29
+ >>> if not result.mask_result.skipped:
30
+ ... for method, arr in result.corrected.items():
31
+ ... io.write_geotiff(
32
+ ... f"scene_{method}.tif", arr, result.grid,
33
+ ... band_indices=result.band_indices,
34
+ ... )
35
+
36
+ Time series on one pixel lattice. The images may be different overlapping
37
+ windows; one DEM and one forest raster cover the reference grid:
38
+
39
+ >>> images = ["scene_01.tif", "scene_02.tif", "scene_03.tif"]
40
+ >>> times = [dt_01, dt_02, dt_03]
41
+ >>> results = correct_image(images, times, "dem.tif", "ndvi.tif", cfg)
42
+
43
+ Within one image the band loop is sequential. Across images, set
44
+ ``Config.n_workers`` above 1 to process several at once in a thread pool. Pass
45
+ ``stream=True`` to receive the results one at a time, in input order, instead
46
+ of the whole list at the end, so a long series can be consumed and released one
47
+ image at a time rather than held in full. Images on different pixel lattices
48
+ are not a batch: call ``correct_image`` once per lattice.
49
+ """
50
+
51
+ from __future__ import annotations
52
+
53
+ __version__ = "1.0.0"
54
+
55
+ # High-level entry point and configuration (the common API).
56
+ from .config import (
57
+ Config, METHODS, REGRESSION_METHODS, SLOPE_TC_METHODS,
58
+ DENOMINATOR_METHODS,
59
+ )
60
+ from .pipeline import correct_image, CorrectionResult
61
+
62
+ # Result/record types returned by the pipeline and lower-level functions.
63
+ from .masking import MaskResult
64
+ from .linear_C import BandCoefficients
65
+ from .evaluation import BandMetrics
66
+ from .io import ImageGrid
67
+
68
+ # Submodules, for direct use of the lower-level building blocks.
69
+ from . import (
70
+ io,
71
+ solar,
72
+ terrain,
73
+ illum,
74
+ masking,
75
+ linear_C,
76
+ T_correct,
77
+ evaluation,
78
+ pipeline,
79
+ config,
80
+ )
81
+
82
+ __all__ = [
83
+ "__version__",
84
+ # high-level
85
+ "Config",
86
+ "correct_image",
87
+ "CorrectionResult",
88
+ # constants
89
+ "METHODS",
90
+ "REGRESSION_METHODS",
91
+ "SLOPE_TC_METHODS",
92
+ "DENOMINATOR_METHODS",
93
+ # record types
94
+ "MaskResult",
95
+ "BandCoefficients",
96
+ "BandMetrics",
97
+ "ImageGrid",
98
+ # submodules
99
+ "io",
100
+ "solar",
101
+ "terrain",
102
+ "illum",
103
+ "masking",
104
+ "linear_C",
105
+ "T_correct",
106
+ "evaluation",
107
+ "pipeline",
108
+ "config",
109
+ ]
fortocorrpy/config.py ADDED
@@ -0,0 +1,194 @@
1
+ """Central configuration for the topographic-correction pipeline.
2
+
3
+ :class:`Config` holds the method choices, thresholds, sampling settings and
4
+ bulk-processing options. Every field has a default, and validation runs at
5
+ construction time so an invalid value is reported before a long batch run
6
+ rather than inside it.
7
+
8
+ Settings files are not read here. A caller keeping parameters in JSON or
9
+ similar converts them to a mapping and passes ``Config(**mapping)``.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from dataclasses import dataclass, field
15
+ from typing import Sequence
16
+
17
+ __all__ = ["Config", "METHODS", "REGRESSION_METHODS", "SLOPE_TC_METHODS",
18
+ "DENOMINATOR_METHODS"]
19
+
20
+ # Correction-method keys.
21
+ METHODS = ("cosine", "scs", "c", "scsc", "se", "er")
22
+
23
+ # Methods whose coefficients come from the reflectance-cos i regression.
24
+ # Naming the set here rather than inlining it keeps the three method groups in
25
+ # one place, so adding a method means adding it to the groups it belongs to.
26
+ REGRESSION_METHODS = ("c", "scsc", "se", "er")
27
+
28
+ # Methods whose formula uses cos(alpha) separately from cos i.
29
+ # These require the slope raster to survive until the correction step.
30
+ SLOPE_TC_METHODS = ("scs", "scsc")
31
+
32
+ # Methods whose formula has cos i in the denominator.
33
+ DENOMINATOR_METHODS = ("cosine", "scs", "c", "scsc")
34
+
35
+
36
+ @dataclass
37
+ class Config:
38
+ """Settings for a topographic correction run, single image or bulk.
39
+
40
+ Parameters
41
+ ----------
42
+ mask_source : {'ndvi', 'landcover'}
43
+ Source used to identify the target (forest) cover for the regression
44
+ sample. ``'ndvi'`` thresholds an external growing-season NDVI raster;
45
+ ``'landcover'`` selects a class from an external land-cover raster.
46
+ ndvi_threshold : float
47
+ Lower NDVI bound for forest, used when ``mask_source='ndvi'``.
48
+ forest_class : int or None
49
+ Land-cover class value treated as forest, used when
50
+ ``mask_source='landcover'``.
51
+ slope_min_deg : float
52
+ Minimum slope (degrees) for a pixel to enter the regression sample.
53
+ cos_i_threshold : float
54
+ Lower bound on cos i for the regression sample. ``0.0`` excludes
55
+ self-shadow (cos i <= 0).
56
+ aspect_quadrant_edges : sequence of float
57
+ Aspect bin edges (degrees, clockwise from North) used to label
58
+ quadrants for the four-direction sample check. The default splits
59
+ N, E, S, W centred on the cardinal directions.
60
+ min_samples_per_quadrant : int
61
+ Minimum number of sample pixels required in every aspect quadrant.
62
+ If any quadrant falls short, the scene is skipped.
63
+ sample_seed : int or None
64
+ Seed for the per-quadrant random draw that balances the regression
65
+ sample across aspect quadrants. A fixed seed makes the draw (and thus
66
+ the resulting coefficients) reproducible: the same seed always selects
67
+ the same sample. ``None`` draws a different sample each run.
68
+ methods : sequence of str
69
+ Correction methods to apply. Must be a subset of :data:`METHODS`.
70
+ shadow : bool
71
+ If True (default), self-shadow pixels (cos i <= 0) are NaN for every
72
+ method.
73
+ band_indices : sequence of int or None
74
+ Zero-based indices of the reflectance bands to correct. ``None`` means
75
+ all bands in the image.
76
+ n_workers : int
77
+ Number of threads for bulk processing. ``1`` (default) processes
78
+ images sequentially. Values above 1 process images in parallel using
79
+ a thread pool; each worker opens its own file handles and allocates
80
+ its own arrays, so peak memory is roughly ``n_workers`` times the
81
+ single-image footprint. Set to the number of available cores or fewer.
82
+ stream : bool
83
+ When a bulk call hands results back. ``False`` (default) processes the
84
+ whole list and returns it, so every corrected array is alive at once:
85
+ the cost is ``images x methods x bands x rows x cols x 4`` bytes.
86
+ ``True`` returns a generator that yields the results one at a time, in
87
+ input order, so the caller can consume and release each before the
88
+ next arrives and peak memory follows ``n_workers`` instead of the
89
+ length of the list. Ignored for a single image.
90
+
91
+ The setting changes the type of the return value, not the results
92
+ themselves. Iterating works either way; only indexing
93
+ (``results[0]``) and ``len()`` need the list form, which ``list(...)``
94
+ restores.
95
+ """
96
+
97
+ # --- forest (target) identification ---
98
+ mask_source: str = "ndvi"
99
+ ndvi_threshold: float = 0.5
100
+ forest_class: int | None = None
101
+
102
+ # --- illumination / sample geometry ---
103
+ slope_min_deg: float = 5.0
104
+ cos_i_threshold: float = 0.0
105
+
106
+ # --- four-direction (aspect quadrant) balance ---
107
+ aspect_quadrant_edges: Sequence[float] = field(
108
+ default_factory=lambda: (45.0, 135.0, 225.0, 315.0)
109
+ )
110
+ min_samples_per_quadrant: int = 200
111
+ sample_seed: int | None = 42
112
+
113
+ # --- correction methods ---
114
+ methods: Sequence[str] = field(default_factory=lambda: ("scsc",))
115
+ shadow: bool = True
116
+
117
+ # --- band selection ---
118
+ band_indices: Sequence[int] | None = None
119
+
120
+ # --- parallelism / result delivery ---
121
+ n_workers: int = 1
122
+ stream: bool = False
123
+
124
+ def __post_init__(self) -> None:
125
+ self._validate()
126
+
127
+ def _validate(self) -> None:
128
+ if self.mask_source not in ("ndvi", "landcover"):
129
+ raise ValueError(
130
+ f"mask_source must be 'ndvi' or 'landcover', got "
131
+ f"{self.mask_source!r}"
132
+ )
133
+ if self.mask_source == "landcover" and self.forest_class is None:
134
+ raise ValueError(
135
+ "forest_class must be set when mask_source='landcover'"
136
+ )
137
+
138
+ if self.slope_min_deg < 0.0:
139
+ raise ValueError(
140
+ f"slope_min_deg must be non-negative, got {self.slope_min_deg}"
141
+ )
142
+
143
+ if self.cos_i_threshold < 0.0:
144
+ raise ValueError(
145
+ f"cos_i_threshold must be >= 0.0 to exclude self-shadow, "
146
+ f"got {self.cos_i_threshold}"
147
+ )
148
+ if self.min_samples_per_quadrant < 1:
149
+ raise ValueError(
150
+ f"min_samples_per_quadrant must be >= 1, got "
151
+ f"{self.min_samples_per_quadrant}"
152
+ )
153
+
154
+ edges = tuple(self.aspect_quadrant_edges)
155
+ if len(edges) != 4:
156
+ raise ValueError(
157
+ "aspect_quadrant_edges must contain exactly four edges"
158
+ )
159
+ if any(not 0.0 <= e < 360.0 for e in edges):
160
+ raise ValueError(
161
+ "aspect_quadrant_edges must all lie in [0, 360)"
162
+ )
163
+ if any(edges[i] >= edges[i + 1] for i in range(3)):
164
+ raise ValueError(
165
+ "aspect_quadrant_edges must be strictly increasing"
166
+ )
167
+
168
+ if not self.methods:
169
+ raise ValueError("methods must contain at least one method")
170
+ unknown = [m for m in self.methods if m not in METHODS]
171
+ if unknown:
172
+ raise ValueError(
173
+ f"unknown correction method(s): {unknown}; "
174
+ f"valid methods are {METHODS}"
175
+ )
176
+
177
+ if self.n_workers < 1:
178
+ raise ValueError(
179
+ f"n_workers must be >= 1, got {self.n_workers}"
180
+ )
181
+
182
+ @property
183
+ def needs_regression(self) -> bool:
184
+ """True if any selected method requires the reflectance-cos i regression."""
185
+ return any(m in REGRESSION_METHODS for m in self.methods)
186
+
187
+ @property
188
+ def needs_slope_at_correction(self) -> bool:
189
+ """True if any selected method uses cos(alpha) at the correction step.
190
+
191
+ Determines whether the slope raster must survive until T_correct
192
+ (slope-TC group) or may be released after cos i is formed.
193
+ """
194
+ return any(m in SLOPE_TC_METHODS for m in self.methods)
@@ -0,0 +1,177 @@
1
+ """Reflectance-based evaluation of topographic-correction quality.
2
+
3
+ Correction and its assessment run in one call: the pipeline can apply several
4
+ methods and report how each one performed over the same sample, so the methods
5
+ are directly comparable.
6
+
7
+ Metrics
8
+ -------
9
+ Over the evaluation sample, for one band:
10
+
11
+ * ``correlation``: Pearson correlation between ``cos i`` and reflectance.
12
+ Topographic effect shows up as a positive correlation (brighter on
13
+ sun-facing slopes); a good correction drives it toward 0.
14
+ * ``slope``: ordinary-least-squares slope of reflectance on ``cos i``.
15
+ Like the correlation, it should fall toward 0 after correction.
16
+ * ``std``: standard deviation of reflectance. Removing slope-driven
17
+ brightness variation typically reduces it.
18
+ * ``mean``: mean reflectance. A correction should largely preserve overall
19
+ brightness, so the mean should stay close to its pre-correction value.
20
+
21
+ before / after and multiple methods
22
+ -----------------------------------
23
+ The pre-correction ("before") metrics depend only on the original
24
+ reflectance, so they are computed once and shared across methods. The
25
+ post-correction ("after") metrics are computed per method, per band, since
26
+ each method yields different corrected reflectance. The pipeline pairs them so
27
+ the reduction in correlation/slope is directly visible.
28
+
29
+ Evaluation sample
30
+ -----------------
31
+ Metrics are computed over the forest regression sample (the mask from
32
+ :mod:`fortocorrpy.masking`), consistent with how the coefficients were fit.
33
+ NaN pixels (self-shadow, invalid) are excluded.
34
+ """
35
+
36
+ from __future__ import annotations
37
+
38
+ from dataclasses import dataclass
39
+
40
+ import numpy as np
41
+
42
+ __all__ = ["BandMetrics", "band_metrics", "evaluate_before", "evaluate_after"]
43
+
44
+
45
+ @dataclass
46
+ class BandMetrics:
47
+ """Reflectance-based metrics for one band over the evaluation sample.
48
+
49
+ Attributes
50
+ ----------
51
+ correlation : float
52
+ Pearson correlation between ``cos i`` and reflectance.
53
+ slope : float
54
+ OLS slope of reflectance regressed on ``cos i``.
55
+ std : float
56
+ Standard deviation of reflectance.
57
+ mean : float
58
+ Mean reflectance.
59
+ n_samples : int
60
+ Number of valid sample pixels used.
61
+ """
62
+
63
+ correlation: float
64
+ slope: float
65
+ std: float
66
+ mean: float
67
+ n_samples: int
68
+
69
+
70
+ def band_metrics(cos_i, reflectance, mask):
71
+ """Compute the standard metrics for one band over the masked sample.
72
+
73
+ Parameters
74
+ ----------
75
+ cos_i : numpy.ndarray
76
+ Illumination condition raster.
77
+ reflectance : numpy.ndarray
78
+ Single-band reflectance raster, same shape as ``cos_i``.
79
+ mask : numpy.ndarray
80
+ Boolean evaluation-sample mask (typically the forest regression mask).
81
+
82
+ Returns
83
+ -------
84
+ BandMetrics
85
+ Correlation, slope, std, mean, and the sample size. Fields are ``nan``
86
+ when undefined (e.g. fewer than two valid pixels, or zero variance in
87
+ ``cos i``).
88
+ """
89
+ m = np.asarray(mask, dtype=bool)
90
+ # Extract masked pixels first (small array), then promote to float64
91
+ # for numerical stability. Avoids creating a full-raster float64 copy.
92
+ x = np.asarray(cos_i)[m].astype(np.float64)
93
+ y = np.asarray(reflectance)[m].astype(np.float64)
94
+
95
+ # Drop pixels where either is NaN (self-shadow / invalid).
96
+ good = np.isfinite(x) & np.isfinite(y)
97
+ x = x[good]
98
+ y = y[good]
99
+ n = x.size
100
+
101
+ if n < 2:
102
+ return BandMetrics(
103
+ correlation=float("nan"), slope=float("nan"),
104
+ std=float("nan"), mean=float("nan"), n_samples=int(n),
105
+ )
106
+
107
+ mean = float(y.mean())
108
+ std = float(y.std(ddof=0))
109
+
110
+ x_mean = x.mean()
111
+ dx = x - x_mean
112
+ sxx = float(np.dot(dx, dx))
113
+
114
+ if sxx == 0.0:
115
+ correlation = float("nan")
116
+ slope = float("nan")
117
+ else:
118
+ dy = y - y.mean()
119
+ sxy = float(np.dot(dx, dy))
120
+ slope = sxy / sxx
121
+ sy = float(np.dot(dy, dy))
122
+ correlation = sxy / np.sqrt(sxx * sy) if sy > 0.0 else float("nan")
123
+
124
+ return BandMetrics(
125
+ correlation=float(correlation), slope=float(slope),
126
+ std=std, mean=mean, n_samples=int(n),
127
+ )
128
+
129
+
130
+ def evaluate_before(cos_i, reflectance, mask):
131
+ """Per-band metrics on the original (pre-correction) reflectance.
132
+
133
+ Computed once and shared across methods, since the input reflectance does
134
+ not depend on the correction method.
135
+
136
+ Parameters
137
+ ----------
138
+ cos_i : numpy.ndarray
139
+ Illumination condition raster.
140
+ reflectance : numpy.ndarray
141
+ Reflectance stack ``(bands, rows, cols)`` or a single band.
142
+ mask : numpy.ndarray
143
+ Boolean evaluation-sample mask.
144
+
145
+ Returns
146
+ -------
147
+ list of BandMetrics
148
+ One entry per band, in band order.
149
+ """
150
+ refl = np.asarray(reflectance)
151
+ if refl.ndim == 2:
152
+ refl = refl[np.newaxis, ...]
153
+ return [band_metrics(cos_i, refl[b], mask) for b in range(refl.shape[0])]
154
+
155
+
156
+ def evaluate_after(cos_i, corrected, mask):
157
+ """Per-band metrics on corrected reflectance for one method.
158
+
159
+ Parameters
160
+ ----------
161
+ cos_i : numpy.ndarray
162
+ Illumination condition raster.
163
+ corrected : numpy.ndarray
164
+ Corrected reflectance stack ``(bands, rows, cols)`` for one method, or
165
+ a single band.
166
+ mask : numpy.ndarray
167
+ Boolean evaluation-sample mask (same as used for ``before``).
168
+
169
+ Returns
170
+ -------
171
+ list of BandMetrics
172
+ One entry per band, in band order.
173
+ """
174
+ corr = np.asarray(corrected)
175
+ if corr.ndim == 2:
176
+ corr = corr[np.newaxis, ...]
177
+ return [band_metrics(cos_i, corr[b], mask) for b in range(corr.shape[0])]