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.
- fortocorrpy/T_correct.py +157 -0
- fortocorrpy/__init__.py +109 -0
- fortocorrpy/config.py +194 -0
- fortocorrpy/evaluation.py +177 -0
- fortocorrpy/illum.py +119 -0
- fortocorrpy/io.py +573 -0
- fortocorrpy/linear_C.py +137 -0
- fortocorrpy/masking.py +224 -0
- fortocorrpy/pipeline.py +426 -0
- fortocorrpy/solar.py +241 -0
- fortocorrpy/terrain.py +151 -0
- fortocorrpy-1.0.0.dist-info/METADATA +174 -0
- fortocorrpy-1.0.0.dist-info/RECORD +15 -0
- fortocorrpy-1.0.0.dist-info/WHEEL +4 -0
- fortocorrpy-1.0.0.dist-info/licenses/LICENSE +21 -0
fortocorrpy/T_correct.py
ADDED
|
@@ -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)
|
fortocorrpy/__init__.py
ADDED
|
@@ -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])]
|