fortocorrpy 1.0.0__tar.gz
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-1.0.0/CITATION.cff +55 -0
- fortocorrpy-1.0.0/DESIGN_SPEC.md +326 -0
- fortocorrpy-1.0.0/EXAMPLE/data/4_bands.tif +0 -0
- fortocorrpy-1.0.0/EXAMPLE/data/DEM.tif +0 -0
- fortocorrpy-1.0.0/EXAMPLE/data/LC.tif +0 -0
- fortocorrpy-1.0.0/EXAMPLE/data/NDVI.tif +0 -0
- fortocorrpy-1.0.0/EXAMPLE/data/sensing_time.json +3 -0
- fortocorrpy-1.0.0/EXAMPLE/example.py +209 -0
- fortocorrpy-1.0.0/LICENSE +21 -0
- fortocorrpy-1.0.0/PKG-INFO +174 -0
- fortocorrpy-1.0.0/README.md +140 -0
- fortocorrpy-1.0.0/docs/api_reference.md +155 -0
- fortocorrpy-1.0.0/docs/methods.md +119 -0
- fortocorrpy-1.0.0/docs/usage.md +249 -0
- fortocorrpy-1.0.0/pyproject.toml +78 -0
- fortocorrpy-1.0.0/src/fortocorrpy/T_correct.py +157 -0
- fortocorrpy-1.0.0/src/fortocorrpy/__init__.py +109 -0
- fortocorrpy-1.0.0/src/fortocorrpy/config.py +194 -0
- fortocorrpy-1.0.0/src/fortocorrpy/evaluation.py +177 -0
- fortocorrpy-1.0.0/src/fortocorrpy/illum.py +119 -0
- fortocorrpy-1.0.0/src/fortocorrpy/io.py +573 -0
- fortocorrpy-1.0.0/src/fortocorrpy/linear_C.py +137 -0
- fortocorrpy-1.0.0/src/fortocorrpy/masking.py +224 -0
- fortocorrpy-1.0.0/src/fortocorrpy/pipeline.py +426 -0
- fortocorrpy-1.0.0/src/fortocorrpy/solar.py +241 -0
- fortocorrpy-1.0.0/src/fortocorrpy/terrain.py +151 -0
- fortocorrpy-1.0.0/tests/conftest.py +64 -0
- fortocorrpy-1.0.0/tests/test_T_correct.py +226 -0
- fortocorrpy-1.0.0/tests/test_config.py +100 -0
- fortocorrpy-1.0.0/tests/test_evaluation.py +80 -0
- fortocorrpy-1.0.0/tests/test_illum.py +97 -0
- fortocorrpy-1.0.0/tests/test_io.py +277 -0
- fortocorrpy-1.0.0/tests/test_linear_C.py +80 -0
- fortocorrpy-1.0.0/tests/test_masking.py +195 -0
- fortocorrpy-1.0.0/tests/test_pipeline.py +530 -0
- fortocorrpy-1.0.0/tests/test_solar.py +114 -0
- fortocorrpy-1.0.0/tests/test_terrain.py +87 -0
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use this software, please cite it as below."
|
|
3
|
+
title: "fortocorrpy: Topographic correction of optical satellite imagery over rugged terrain"
|
|
4
|
+
abstract: >-
|
|
5
|
+
fortocorrpy performs topographic correction of optical surface-reflectance
|
|
6
|
+
imagery over rugged terrain. It implements six correction
|
|
7
|
+
methods (cosine, C-correction, SCS, SCS+C, statistical-empirical, and
|
|
8
|
+
empirical rotation) within a single interface, with forest masking from an
|
|
9
|
+
NDVI raster or a land-cover raster and four-aspect regression balancing,
|
|
10
|
+
and optionally reports reflectance-level evaluation metrics for each method
|
|
11
|
+
in the same call. Correction is driven by the image grid geometry, a DEM,
|
|
12
|
+
and the acquisition time; images on a common pixel lattice can be corrected
|
|
13
|
+
in a single call, with the terrain data computed once and a shared forest
|
|
14
|
+
source reused across them. Built on NumPy, rasterio, and pyproj.
|
|
15
|
+
type: software
|
|
16
|
+
version: 1.0.0
|
|
17
|
+
date-released: "2026-11-15"
|
|
18
|
+
license: MIT
|
|
19
|
+
repository-code: "https://github.com/KNU-GEL/fortocorrpy"
|
|
20
|
+
identifiers:
|
|
21
|
+
- type: url
|
|
22
|
+
value: "https://github.com/JaebeomK/fortocorrpy"
|
|
23
|
+
authors:
|
|
24
|
+
- family-names: Kim
|
|
25
|
+
given-names: Jaebeom
|
|
26
|
+
affiliation: "Kangwon National University"
|
|
27
|
+
- family-names: Moon
|
|
28
|
+
given-names: Minkyu
|
|
29
|
+
affiliation: "Kangwon National University"
|
|
30
|
+
keywords:
|
|
31
|
+
- topographic correction
|
|
32
|
+
- topographic normalization
|
|
33
|
+
- remote sensing
|
|
34
|
+
- satellite imagery
|
|
35
|
+
- rugged terrain
|
|
36
|
+
- reflectance
|
|
37
|
+
- SCS+C
|
|
38
|
+
- illumination
|
|
39
|
+
- forest
|
|
40
|
+
preferred-citation:
|
|
41
|
+
type: article
|
|
42
|
+
title: "fortocorrpy: A Sensor-Independent Python Package for Multi-Method Topographic Correction of Optical Satellite Imagery"
|
|
43
|
+
authors:
|
|
44
|
+
- family-names: Kim
|
|
45
|
+
given-names: Jaebeom
|
|
46
|
+
- family-names: Cho
|
|
47
|
+
given-names: Nanghyen
|
|
48
|
+
- family-names: Moon
|
|
49
|
+
given-names: Minkyu
|
|
50
|
+
journal: "Remote Sensing"
|
|
51
|
+
year: 2026
|
|
52
|
+
volume: 18
|
|
53
|
+
issue: 22
|
|
54
|
+
start: 3922
|
|
55
|
+
doi: "10.3390/rs18223922"
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
# fortocorrpy Design Specification
|
|
2
|
+
|
|
3
|
+
Version 1.0.0. Requires Python 3.9 or later, with numpy, rasterio and pyproj.
|
|
4
|
+
|
|
5
|
+
The as-built design. Usage is in `docs/usage.md`, the background to the formulas
|
|
6
|
+
in `docs/methods.md`.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. Purpose and inputs
|
|
11
|
+
|
|
12
|
+
Removes the topographic effect from each pixel of an optical satellite image.
|
|
13
|
+
Six published methods are available through one interface, applied singly or
|
|
14
|
+
together, with reflectance-level metrics optionally reported alongside so that
|
|
15
|
+
methods can be compared.
|
|
16
|
+
|
|
17
|
+
Four things are required of the input.
|
|
18
|
+
|
|
19
|
+
- A QC-processed reflectance image. Cloud, cloud shadow and other invalid pixels
|
|
20
|
+
must already be set to nodata; the package performs no quality assessment of
|
|
21
|
+
its own.
|
|
22
|
+
- A projected CRS in metres. Slope and aspect use the pixel size as a horizontal
|
|
23
|
+
distance.
|
|
24
|
+
- A DEM covering the reference grid. Slope and aspect read a 3x3 neighbourhood,
|
|
25
|
+
so a DEM that stops inside the grid leaves the slope and aspect invalid for one
|
|
26
|
+
pixel inside that boundary.
|
|
27
|
+
- A UTC acquisition time, passed as a `datetime`. The package does not read
|
|
28
|
+
product metadata files.
|
|
29
|
+
|
|
30
|
+
Any raster rasterio can read is accepted as input; output is always GeoTIFF.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## 2. Correction methods
|
|
35
|
+
|
|
36
|
+
The six formulas follow their source literature. Slope and aspect use the Horn
|
|
37
|
+
(1981) weighted 3x3 finite difference. Coefficients are estimated from a forest
|
|
38
|
+
sample, and the correction is applied to every valid pixel it can be applied to.
|
|
39
|
+
|
|
40
|
+
### 2.1 Notation and conventions
|
|
41
|
+
|
|
42
|
+
| symbol | meaning |
|
|
43
|
+
|----------|------------------------------------|
|
|
44
|
+
| θ_s, φ_s | solar zenith and azimuth angle |
|
|
45
|
+
| α, β | slope and aspect |
|
|
46
|
+
| i | local incidence angle |
|
|
47
|
+
| ρ_T, ρ_H | observed and corrected reflectance |
|
|
48
|
+
| a, b | regression slope and intercept |
|
|
49
|
+
| C | b / a |
|
|
50
|
+
| ρ̄ | sample-mean reflectance |
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
cos i = cos θ_s · cos α + sin θ_s · sin α · cos(φ_s − β)
|
|
54
|
+
cos i_h = cos θ_s
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
All angles are radians internally, and φ_s and β are both compass bearings, zero
|
|
58
|
+
at north and increasing clockwise. The thresholds a user sets are the exception:
|
|
59
|
+
`slope_min_deg` and `aspect_quadrant_edges` are degrees, converted where they are
|
|
60
|
+
consumed.
|
|
61
|
+
|
|
62
|
+
### 2.2 The six formulas
|
|
63
|
+
|
|
64
|
+
| key | method | formula | regression | cos α | source |
|
|
65
|
+
|----------|-----------------------|-------------------------------------------|------------|-------|---------------------|
|
|
66
|
+
| `cosine` | Cosine | ρ_T · cos θ_s / cos i | no | no | Teillet et al. 1982 |
|
|
67
|
+
| `c` | C-correction | ρ_T · (cos θ_s + C) / (cos i + C) | yes | no | Teillet et al. 1982 |
|
|
68
|
+
| `scs` | SCS | ρ_T · (cos α · cos θ_s) / cos i | no | yes | Gu & Gillespie 1998 |
|
|
69
|
+
| `scsc` | SCS+C | ρ_T · (cos α · cos θ_s + C) / (cos i + C) | yes | yes | Soenen et al. 2005 |
|
|
70
|
+
| `se` | Statistical-Empirical | ρ_T − (a · cos i + b) + ρ̄ | yes | no | Teillet et al. 1982 |
|
|
71
|
+
| `er` | Empirical Rotation | ρ_T − a · (cos i − cos θ_s) | yes | no | Tan et al. 2013 |
|
|
72
|
+
|
|
73
|
+
### 2.3 The groups that drive branching
|
|
74
|
+
|
|
75
|
+
`REGRESSION_METHODS` (`c`, `scsc`, `se`, `er`) need coefficients, so a regression
|
|
76
|
+
is fitted per band.
|
|
77
|
+
|
|
78
|
+
`SLOPE_TC_METHODS` (`scs`, `scsc`) use cos α, so α is kept until the correction
|
|
79
|
+
step.
|
|
80
|
+
|
|
81
|
+
`DENOMINATOR_METHODS` (`cosine`, `scs`, `c`, `scsc`) put cos i in a denominator.
|
|
82
|
+
|
|
83
|
+
All four guard the denominator itself: below 1e-6 in magnitude it yields a
|
|
84
|
+
missing value rather than an extreme one. For `cosine` and `scs` the denominator
|
|
85
|
+
is cos i, for `c` and `scsc` it is cos i + C, which is why they also have to
|
|
86
|
+
guard `cos i = −C`. With `shadow` set, every method is missing where cos i ≤ 0.
|
|
87
|
+
|
|
88
|
+
A regression can fail to be defined even when the sample is large enough. Where
|
|
89
|
+
`cos i` has no variance over the sample the slope `a` is undefined, and the fit
|
|
90
|
+
returns `a = 0`, `C = nan`. The four regression methods then reduce to the
|
|
91
|
+
identity: no brightness trend with illumination was observed, so there is
|
|
92
|
+
nothing to correct. `cosine` and `scs` do not use the coefficients and are
|
|
93
|
+
unaffected. Coefficients are per band and shared by every selected method, so
|
|
94
|
+
this does not differ between the regression methods, and the image is not
|
|
95
|
+
treated as a failure.
|
|
96
|
+
|
|
97
|
+
### 2.4 Adding a method
|
|
98
|
+
|
|
99
|
+
Add the key to `METHODS`, add the formula branch to `T_correct.correct`, and add
|
|
100
|
+
the key to whichever groups it belongs to: `REGRESSION_METHODS` if it uses
|
|
101
|
+
regression coefficients, `SLOPE_TC_METHODS` if it uses cos α,
|
|
102
|
+
`DENOMINATOR_METHODS` if it puts cos i in a denominator. No other module changes.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 3. Design principles
|
|
107
|
+
|
|
108
|
+
1. Each module's responsibility is complete within that module.
|
|
109
|
+
2. Settings are gathered into one object.
|
|
110
|
+
3. File access belongs to `io`, and all data are aligned to one reference grid.
|
|
111
|
+
4. The correction function returns arrays; writing is a separate function.
|
|
112
|
+
5. Memory is managed explicitly.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 4. Module layout
|
|
117
|
+
|
|
118
|
+
Eleven modules, with one-way dependencies. `config` is referenced by all of them,
|
|
119
|
+
`io` is called only by `pipeline`, and the computation modules between them are
|
|
120
|
+
pure functions over arrays that do not call one another. `pipeline` assembles.
|
|
121
|
+
|
|
122
|
+
`config` owns the settings and their validation. It provides `Config`,
|
|
123
|
+
`METHODS`, `REGRESSION_METHODS`, `SLOPE_TC_METHODS` and `DENOMINATOR_METHODS`.
|
|
124
|
+
It does not read files or hold paths.
|
|
125
|
+
|
|
126
|
+
`io` owns all disk access. It provides `ImageGrid`, `read_grid`, `read_image`,
|
|
127
|
+
`read_image_on_grid`, `read_bands`, `valid_from_band`, `grids_match`,
|
|
128
|
+
`lattice_offset`, `align_to_grid` and `write_geotiff`. It does not compute
|
|
129
|
+
anything.
|
|
130
|
+
|
|
131
|
+
`solar` owns the solar position, derived from a grid and a time. It provides
|
|
132
|
+
`solar_angles`, `solar_position`, `pixel_lonlat` and `julian_day`. It does not
|
|
133
|
+
know about terrain.
|
|
134
|
+
|
|
135
|
+
`terrain` owns slope and aspect, derived from a DEM. It provides `horn_gradient`
|
|
136
|
+
and `slope_aspect`. It does not align the DEM or form `cos i`.
|
|
137
|
+
|
|
138
|
+
`illum` owns the illumination condition. It provides `cos_incidence` and
|
|
139
|
+
`cos_horizontal`. It does not threshold or mask.
|
|
140
|
+
|
|
141
|
+
`masking` owns the sample and the skip decision. It provides `MaskResult`,
|
|
142
|
+
`forest_mask` and `build_sample_mask`. It does not fit anything.
|
|
143
|
+
|
|
144
|
+
`linear_C` owns the per-band regression. It provides `BandCoefficients`,
|
|
145
|
+
`fit_band` and `fit_bands`. It does not re-check sample eligibility.
|
|
146
|
+
|
|
147
|
+
`T_correct` owns the six formulas. It provides `correct`. It does not choose
|
|
148
|
+
methods or build samples.
|
|
149
|
+
|
|
150
|
+
`evaluation` owns the reflectance-level metrics. It provides `BandMetrics`,
|
|
151
|
+
`band_metrics`, `evaluate_before` and `evaluate_after`. It does not judge what
|
|
152
|
+
the metrics mean.
|
|
153
|
+
|
|
154
|
+
`pipeline` owns the assembly, the branching and the release of memory. It
|
|
155
|
+
provides `correct_image` and `CorrectionResult`. It does no numerical work.
|
|
156
|
+
|
|
157
|
+
`__init__` owns the public surface: the re-exports and `__version__`.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## 5. Configuration
|
|
162
|
+
|
|
163
|
+
`Config` is a dataclass validated on construction. It holds settings, never
|
|
164
|
+
paths. Every field has a default, so only what a purpose requires is changed.
|
|
165
|
+
|
|
166
|
+
| field | default | consumed by | usually |
|
|
167
|
+
|----------------------------|-----------------------|-------------------------|------------------------------------|
|
|
168
|
+
| `methods` | `("scsc",)` | `pipeline`, `T_correct` | set per study |
|
|
169
|
+
| `mask_source` | `"ndvi"` | `masking` | set per dataset |
|
|
170
|
+
| `ndvi_threshold` | `0.5` | `masking` | set per dataset |
|
|
171
|
+
| `forest_class` | `None` | `masking` | set when `mask_source="landcover"` |
|
|
172
|
+
| `band_indices` | `None` | `io`, `pipeline` | set per dataset |
|
|
173
|
+
| `slope_min_deg` | `5.0` | `masking` | left at the default |
|
|
174
|
+
| `cos_i_threshold` | `0.0` | `masking` | left at the default |
|
|
175
|
+
| `shadow` | `True` | `T_correct` | left at the default |
|
|
176
|
+
| `aspect_quadrant_edges` | `(45, 135, 225, 315)` | `masking` | left at the default |
|
|
177
|
+
| `min_samples_per_quadrant` | `200` | `masking` | left at the default |
|
|
178
|
+
| `sample_seed` | `42` | `masking` | left at the default |
|
|
179
|
+
| `n_workers` | `1` | `pipeline` | set per machine |
|
|
180
|
+
| `stream` | `False` | `pipeline` | set per memory budget |
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
The properties `needs_regression` and `needs_slope_at_correction` derive the
|
|
184
|
+
branching of Section 2.3 from `methods`.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 6. Inputs and grid alignment
|
|
189
|
+
|
|
190
|
+
One reference grid per call, and everything is placed on it. The grid is
|
|
191
|
+
described by `io.ImageGrid` (transform, CRS, width, height, count, nodata, dtype)
|
|
192
|
+
and is taken from the image, or from `reference_path` when one is given. The
|
|
193
|
+
aligned DEM, slope and aspect, the solar angles, `cos i`, the sample mask and
|
|
194
|
+
every corrected array sit on it, and it is returned with the result.
|
|
195
|
+
|
|
196
|
+
Two notions are distinguished.
|
|
197
|
+
|
|
198
|
+
Two grids are the same grid when their CRS and pixel geometry agree, their
|
|
199
|
+
dimensions are equal, and their origins fall within tolerance of each other.
|
|
200
|
+
|
|
201
|
+
They share a lattice when their CRS and pixel geometry agree and their origins
|
|
202
|
+
differ by a whole number of pixels within tolerance. Their dimensions may differ.
|
|
203
|
+
|
|
204
|
+
The tolerances are relative for pixel size and rotation (1e-9), and a fraction of
|
|
205
|
+
a pixel for the origin (1e-4, three millimetres on a 30 m grid). Below that is
|
|
206
|
+
coordinate noise; a larger difference is a different lattice. Exact equality is
|
|
207
|
+
not used, because the same grid written by two tools can differ in the last
|
|
208
|
+
decimal.
|
|
209
|
+
|
|
210
|
+
| input | rule |
|
|
211
|
+
|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
|
|
212
|
+
| DEM, forest source | reprojected and resampled onto the reference grid regardless of CRS or resolution; the DEM must cover the grid completely |
|
|
213
|
+
| image on the same grid | read as is |
|
|
214
|
+
| image on the same lattice, overlapping | the overlapping window is placed by slicing; the area it does not cover is left missing |
|
|
215
|
+
| image on the same lattice, not overlapping | refused |
|
|
216
|
+
| image on another lattice | refused, never resampled to fit |
|
|
217
|
+
|
|
218
|
+
Ancillary data may be resampled; reflectance may not, because it is what the
|
|
219
|
+
correction acts on.
|
|
220
|
+
|
|
221
|
+
Ancillary data are aligned to exactly the reference grid, so any margin beyond it
|
|
222
|
+
is not used. The slope and aspect of the grid's own outermost row and column are
|
|
223
|
+
therefore extrapolated by edge replication, whatever the extent of the DEM. What
|
|
224
|
+
the DEM must do is cover the grid without gaps.
|
|
225
|
+
|
|
226
|
+
Validity comes from the image's own nodata. Nodata becomes NaN on read, and a
|
|
227
|
+
pixel is valid where every selected band is finite. The area an image does not
|
|
228
|
+
cover, and the pixels a denominator method cannot correct, arrive through the
|
|
229
|
+
same channel, so there is one notion of invalid. `io.valid_from_band` reads a
|
|
230
|
+
single band and gives the same answer only under the usual condition that QC was
|
|
231
|
+
applied across all bands together.
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## 7. Correction
|
|
236
|
+
|
|
237
|
+
```
|
|
238
|
+
correct_image(image_path, datetime_utc, dem_path, forest_path, config,
|
|
239
|
+
*, evaluate=False, reference_path=None)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Passing the image paths and acquisition times as lists invokes bulk processing.
|
|
243
|
+
The two lists must be the same length, as must the forest source when it is given
|
|
244
|
+
as a list. The DEM is always a single path. `reference_path` names an image
|
|
245
|
+
covering the whole area whose grid every result is produced on; without it the
|
|
246
|
+
first image's grid is used. With `evaluate=True` the reflectance-level metrics
|
|
247
|
+
are computed before and after correction over the regression sample.
|
|
248
|
+
|
|
249
|
+
Processing begins with grid alignment, derives slope and aspect from the DEM and
|
|
250
|
+
the solar geometry from the acquisition time, and combines them into `cos i`.
|
|
251
|
+
The forest sample and the skip decision are built for every image. Where a
|
|
252
|
+
selected method needs coefficients, a regression is then fitted per band and the
|
|
253
|
+
selected methods share those coefficients. Bands are the outer loop and methods
|
|
254
|
+
the inner one, so one regression per band serves every method.
|
|
255
|
+
|
|
256
|
+
Results are returned in memory rather than written. A single request returns one
|
|
257
|
+
`CorrectionResult`; a list request returns a list of them, or a generator over
|
|
258
|
+
the same results when `stream` is set.
|
|
259
|
+
|
|
260
|
+
| field | contents |
|
|
261
|
+
|-----------------------------------|-----------------------------------------------------------------------------------------|
|
|
262
|
+
| `corrected` | the corrected array per method; `None` when skipped or errored |
|
|
263
|
+
| `coefficients` | the regression coefficients per band; elements are `None` when no regression was needed |
|
|
264
|
+
| `mask_result` | the sampling outcome and the skip decision; `None` on error |
|
|
265
|
+
| `band_indices` | where each output band sat in the input stack |
|
|
266
|
+
| `grid` | the reference grid the correction ran on |
|
|
267
|
+
| `metrics_before`, `metrics_after` | the before and after metrics, with `evaluate=True` |
|
|
268
|
+
| `error` | the failure, when the image could not be processed |
|
|
269
|
+
|
|
270
|
+
An image whose sample falls short is left uncorrected for every selected method
|
|
271
|
+
and carries only the diagnostics on `mask_result`; an image that could not be
|
|
272
|
+
processed carries only `error`. Neither carries corrected arrays. A
|
|
273
|
+
failure is recorded on the result only for a list request, so that one bad image
|
|
274
|
+
does not cost the rest; a single request raises, having nothing else to protect.
|
|
275
|
+
|
|
276
|
+
What a bulk call shares and what it derives per image:
|
|
277
|
+
|
|
278
|
+
| derived | scope |
|
|
279
|
+
|---------------------------------|-----------------------------------------|
|
|
280
|
+
| the reference grid | once |
|
|
281
|
+
| slope and aspect | once |
|
|
282
|
+
| the forest source | once, or per image when given as a list |
|
|
283
|
+
| solar geometry | per image |
|
|
284
|
+
| the sample and the coefficients | per image |
|
|
285
|
+
|
|
286
|
+
`n_workers` sets how many images are processed concurrently in a thread pool and
|
|
287
|
+
`stream` sets when results are returned. Both follow the input order: `stream`
|
|
288
|
+
turns the list into a generator without reordering it, so a result waits if an
|
|
289
|
+
earlier image is still running. Each worker holds its own file handles and
|
|
290
|
+
arrays, while the slope, aspect and forest arrays derived once are shared
|
|
291
|
+
read-only.
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
## 8. Writing
|
|
296
|
+
|
|
297
|
+
`io.write_geotiff` writes the output. It takes an array together with the grid
|
|
298
|
+
and band indices carried on the result, and produces a GeoTIFF with the CRS,
|
|
299
|
+
transform and dimensions of that grid, which are the first image's only when
|
|
300
|
+
`reference_path` was not used. Each band records its original position in
|
|
301
|
+
the input stack as its description, so a band subset stays identifiable.
|
|
302
|
+
|
|
303
|
+
An array whose rows and columns do not match the grid is refused, as is a
|
|
304
|
+
`band_indices` without one entry per band: the grid's CRS and transform are
|
|
305
|
+
written as they are, so an array of another size would be georeferenced into the
|
|
306
|
+
wrong place.
|
|
307
|
+
|
|
308
|
+
Because the correction returns arrays, they may be passed to a subsequent step
|
|
309
|
+
without being written at all, and any intermediate product sharing the grid can
|
|
310
|
+
be written by the same function.
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
## 9. Memory
|
|
315
|
+
|
|
316
|
+
An image is held whole; there is no block processing, so an image too large for
|
|
317
|
+
memory must be split by the caller. What is managed instead is the number of
|
|
318
|
+
arrays alive at once. A file is opened once and the required bands read together,
|
|
319
|
+
continuous raster arrays are float32 as a rule (masks are boolean), and
|
|
320
|
+
intermediates are released at the step where they stop being needed. Slope is
|
|
321
|
+
kept to the correction step only when a selected method requires it.
|
|
322
|
+
|
|
323
|
+
In bulk, `stream` removes the accumulation of the list. Disabled, every corrected
|
|
324
|
+
array stays alive until the call returns; enabled, results are yielded one at a
|
|
325
|
+
time in input order and the caller can release each after use, so memory follows
|
|
326
|
+
the number in flight rather than the length of the list.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
"""
|
|
2
|
+
fortocorrpy usage example: full topographic-correction workflow + verification outputs
|
|
3
|
+
|
|
4
|
+
This folder (EXAMPLE) layout:
|
|
5
|
+
example.py <- this script
|
|
6
|
+
data/ <- input data (4_bands.tif, DEM.tif, NDVI.tif, LC.tif, sensing_time.json)
|
|
7
|
+
output/ <- created automatically on run; results are saved here
|
|
8
|
+
|
|
9
|
+
Reads inputs (image, DEM, forest, acquisition time) and writes the products of
|
|
10
|
+
the correction pipeline. Intermediate rasters are computed via the public
|
|
11
|
+
modules (solar, terrain, illum) without modifying the package.
|
|
12
|
+
|
|
13
|
+
Toggle options (True/False) at the top to choose what to output:
|
|
14
|
+
1) Intermediate GeoTIFFs : SZA, SAA, slope, aspect, cos_i
|
|
15
|
+
2) Scatter PNGs : cos i vs reflectance (before + 6 methods, 2x2 per band)
|
|
16
|
+
3) Numeric CSVs : coefficients CSV (C etc.) + evaluation CSV (cos i-reflectance, before/after)
|
|
17
|
+
4) Corrected GeoTIFFs : 6-method corrected results
|
|
18
|
+
|
|
19
|
+
Run: python example.py
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
import os
|
|
23
|
+
import csv
|
|
24
|
+
import json
|
|
25
|
+
import numpy as np
|
|
26
|
+
from datetime import datetime
|
|
27
|
+
import matplotlib
|
|
28
|
+
matplotlib.use("Agg")
|
|
29
|
+
import matplotlib.pyplot as plt
|
|
30
|
+
|
|
31
|
+
from fortocorrpy import (Config, correct_image, io, terrain, solar, illum)
|
|
32
|
+
|
|
33
|
+
# ============================================================
|
|
34
|
+
# Paths (relative to this script's location)
|
|
35
|
+
# Anyone can take the EXAMPLE folder and run example.py:
|
|
36
|
+
# it reads data/ in the same folder and creates output/ for results.
|
|
37
|
+
# ============================================================
|
|
38
|
+
HERE = os.path.dirname(os.path.abspath(__file__))
|
|
39
|
+
DATA_DIR = os.path.join(HERE, "data")
|
|
40
|
+
OUT_DIR = os.path.join(HERE, "output") # created automatically
|
|
41
|
+
|
|
42
|
+
IMAGE_PATH = os.path.join(DATA_DIR, "4_bands.tif")
|
|
43
|
+
DEM_PATH = os.path.join(DATA_DIR, "DEM.tif")
|
|
44
|
+
FOREST_PATH = os.path.join(DATA_DIR, "NDVI.tif") # must match mask_source
|
|
45
|
+
SENSING_JSON = os.path.join(DATA_DIR, "sensing_time.json")
|
|
46
|
+
|
|
47
|
+
MASK_SOURCE = "ndvi" # 'ndvi' or 'landcover'
|
|
48
|
+
METHODS = ("cosine", "scs", "c", "scsc", "se", "er")
|
|
49
|
+
BAND_NAMES = ["Blue", "Green", "Red", "NIR"]
|
|
50
|
+
|
|
51
|
+
# ============================================================
|
|
52
|
+
# Output options (set only what you need to True)
|
|
53
|
+
# ============================================================
|
|
54
|
+
SAVE_INTERMEDIATE_TIFF = True # SZA, SAA, slope, aspect, cos_i GeoTIFFs
|
|
55
|
+
SAVE_SCATTER_PNG = True # cos i vs reflectance scatter (before + 6 methods)
|
|
56
|
+
SAVE_METRICS_CSV = True # coefficients CSV + evaluation CSV
|
|
57
|
+
SAVE_CORRECTED_TIFF = True # 6-method corrected images
|
|
58
|
+
|
|
59
|
+
# Output file names (variables)
|
|
60
|
+
F_SZA = os.path.join(OUT_DIR, "SZA.tif")
|
|
61
|
+
F_SAA = os.path.join(OUT_DIR, "SAA.tif")
|
|
62
|
+
F_SLOPE = os.path.join(OUT_DIR, "slope.tif")
|
|
63
|
+
F_ASPECT = os.path.join(OUT_DIR, "aspect.tif")
|
|
64
|
+
F_COSI = os.path.join(OUT_DIR, "cos_i.tif")
|
|
65
|
+
F_COEF_CSV = os.path.join(OUT_DIR, "coefficients.csv")
|
|
66
|
+
F_METRIC_CSV = os.path.join(OUT_DIR, "evaluation_metrics.csv")
|
|
67
|
+
def f_scatter(tag): # tag = 'before' or a method name
|
|
68
|
+
return os.path.join(OUT_DIR, f"cosi_{tag}.png")
|
|
69
|
+
def f_corrected(method):
|
|
70
|
+
return os.path.join(OUT_DIR, f"corrected_{method}.tif")
|
|
71
|
+
# ============================================================
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def load_sensing_time():
|
|
75
|
+
with open(SENSING_JSON, "r", encoding="utf-8-sig") as f:
|
|
76
|
+
text = json.load(f)["sensing_time"]
|
|
77
|
+
# datetime.fromisoformat only accepts a "Z" suffix from Python 3.11 on.
|
|
78
|
+
if text.endswith(("Z", "z")):
|
|
79
|
+
text = text[:-1] + "+00:00"
|
|
80
|
+
return datetime.fromisoformat(text)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def scatter_panel(ax, x, y, title):
|
|
84
|
+
m = np.isfinite(x) & np.isfinite(y)
|
|
85
|
+
x = x[m]; y = y[m]
|
|
86
|
+
if x.size < 2:
|
|
87
|
+
ax.set_title(title + " (no data)"); return
|
|
88
|
+
a, b = np.polyfit(x, y, 1)
|
|
89
|
+
r = np.corrcoef(x, y)[0, 1]
|
|
90
|
+
ax.scatter(x, y, s=2, alpha=0.3, color="#2c6fbb")
|
|
91
|
+
xs = np.array([x.min(), x.max()])
|
|
92
|
+
ax.plot(xs, a * xs + b, "r-", lw=1)
|
|
93
|
+
ax.set_title(title, fontsize=10)
|
|
94
|
+
ax.set_xlabel("cos i", fontsize=8); ax.set_ylabel("reflectance", fontsize=8)
|
|
95
|
+
ax.text(0.05, 0.95, f"slope={a:.4f}\nr={r:.3f}", transform=ax.transAxes,
|
|
96
|
+
va="top", ha="left", fontsize=8,
|
|
97
|
+
bbox=dict(boxstyle="round", fc="white", ec="gray", alpha=0.9))
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def scatter_figure(cos_i, refl_stack, mask, band_indices, suptitle, out_png):
|
|
101
|
+
fig, axes = plt.subplots(2, 2, figsize=(10, 9))
|
|
102
|
+
ci = cos_i[mask]
|
|
103
|
+
for k, bidx in enumerate(band_indices):
|
|
104
|
+
ax = axes[k // 2, k % 2]
|
|
105
|
+
name = BAND_NAMES[bidx] if bidx < len(BAND_NAMES) else f"band{bidx}"
|
|
106
|
+
scatter_panel(ax, ci, refl_stack[k][mask], name)
|
|
107
|
+
for k in range(len(band_indices), 4):
|
|
108
|
+
axes[k // 2, k % 2].axis("off")
|
|
109
|
+
fig.suptitle(suptitle, fontsize=13)
|
|
110
|
+
fig.tight_layout(rect=[0, 0, 1, 0.97])
|
|
111
|
+
fig.savefig(out_png, dpi=150); plt.close(fig)
|
|
112
|
+
print(f" PNG: {out_png}")
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def main():
|
|
116
|
+
os.makedirs(OUT_DIR, exist_ok=True)
|
|
117
|
+
when = load_sensing_time()
|
|
118
|
+
print("Acquisition (sensing) time:", when)
|
|
119
|
+
|
|
120
|
+
need_eval = SAVE_METRICS_CSV or SAVE_SCATTER_PNG
|
|
121
|
+
cfg = Config(mask_source=MASK_SOURCE, methods=METHODS)
|
|
122
|
+
|
|
123
|
+
print("Running correction (6 methods)...")
|
|
124
|
+
result = correct_image(
|
|
125
|
+
image_path=IMAGE_PATH, datetime_utc=when, dem_path=DEM_PATH,
|
|
126
|
+
forest_path=FOREST_PATH, config=cfg, evaluate=need_eval,
|
|
127
|
+
)
|
|
128
|
+
if result.mask_result.skipped:
|
|
129
|
+
print("skipped: not enough samples.", result.mask_result.quadrant_counts); return
|
|
130
|
+
mask = result.mask_result.mask
|
|
131
|
+
band_indices = result.band_indices
|
|
132
|
+
print("Samples per quadrant:", result.mask_result.quadrant_counts)
|
|
133
|
+
|
|
134
|
+
# --- Intermediate values (public modules) ---
|
|
135
|
+
# result.grid is the grid the correction ran on; write every product on it.
|
|
136
|
+
grid = result.grid
|
|
137
|
+
refl0 = io.read_image_on_grid(IMAGE_PATH, grid)
|
|
138
|
+
dem = io.align_to_grid(DEM_PATH, grid, resampling="bilinear")
|
|
139
|
+
hx, hy = grid.pixel_size
|
|
140
|
+
alpha, beta = terrain.slope_aspect(dem, hx, hy)
|
|
141
|
+
theta_s, phi_s = solar.solar_angles(when, grid.transform, grid.crs, grid.shape)
|
|
142
|
+
cos_i, _ = illum.cos_incidence(theta_s, phi_s, alpha, beta)
|
|
143
|
+
|
|
144
|
+
# --- 1) Intermediate GeoTIFFs ---
|
|
145
|
+
if SAVE_INTERMEDIATE_TIFF:
|
|
146
|
+
print("\n[Intermediate GeoTIFFs]")
|
|
147
|
+
# The package works in radians; the angle products are written in
|
|
148
|
+
# degrees, which is what these file names imply.
|
|
149
|
+
for arr, fp in [(np.degrees(theta_s), F_SZA), (np.degrees(phi_s), F_SAA),
|
|
150
|
+
(np.degrees(alpha), F_SLOPE), (np.degrees(beta), F_ASPECT),
|
|
151
|
+
(cos_i, F_COSI)]:
|
|
152
|
+
io.write_geotiff(fp, arr, grid)
|
|
153
|
+
print(f" TIFF: {fp}")
|
|
154
|
+
|
|
155
|
+
# --- 2) Scatter PNGs ---
|
|
156
|
+
if SAVE_SCATTER_PNG:
|
|
157
|
+
print("\n[Scatter PNGs]")
|
|
158
|
+
scatter_figure(cos_i, refl0, mask, band_indices,
|
|
159
|
+
"cos i vs reflectance (BEFORE)", f_scatter("before"))
|
|
160
|
+
for method in METHODS:
|
|
161
|
+
scatter_figure(cos_i, result.corrected[method], mask, band_indices,
|
|
162
|
+
f"cos i vs reflectance (AFTER: {method})", f_scatter(method))
|
|
163
|
+
|
|
164
|
+
# --- 3) Numeric CSVs (coefficients + evaluation) ---
|
|
165
|
+
if SAVE_METRICS_CSV:
|
|
166
|
+
print("\n[Numeric CSVs]")
|
|
167
|
+
# Coefficients CSV: coefficients is per-band list[BandCoefficients]
|
|
168
|
+
# (regression fit once, shared across methods)
|
|
169
|
+
with open(F_COEF_CSV, "w", newline="", encoding="utf-8") as fcsv:
|
|
170
|
+
w = csv.writer(fcsv)
|
|
171
|
+
w.writerow(["band", "a_slope", "b_intercept", "C", "mean_reflectance", "n_samples"])
|
|
172
|
+
coeffs = result.coefficients
|
|
173
|
+
if coeffs is not None:
|
|
174
|
+
for k, bc in enumerate(coeffs):
|
|
175
|
+
name = BAND_NAMES[band_indices[k]] if band_indices[k] < len(BAND_NAMES) else f"band{band_indices[k]}"
|
|
176
|
+
w.writerow([name, f"{bc.slope:.6f}", f"{bc.intercept:.6f}",
|
|
177
|
+
f"{bc.c:.6f}", f"{bc.mean_reflectance:.6f}", bc.n_samples])
|
|
178
|
+
print(f" CSV: {F_COEF_CSV}")
|
|
179
|
+
|
|
180
|
+
# Evaluation CSV (before + each method)
|
|
181
|
+
with open(F_METRIC_CSV, "w", newline="", encoding="utf-8") as fcsv:
|
|
182
|
+
w = csv.writer(fcsv)
|
|
183
|
+
w.writerow(["method", "band", "slope", "correlation", "mean", "std", "n"])
|
|
184
|
+
def write_metrics(method, mlist):
|
|
185
|
+
for k, m in enumerate(mlist):
|
|
186
|
+
name = BAND_NAMES[band_indices[k]] if band_indices[k] < len(BAND_NAMES) else f"band{band_indices[k]}"
|
|
187
|
+
w.writerow([method, name, f"{m.slope:.6f}", f"{m.correlation:.6f}",
|
|
188
|
+
f"{m.mean:.6f}", f"{m.std:.6f}", m.n_samples])
|
|
189
|
+
if result.metrics_before is not None:
|
|
190
|
+
write_metrics("before", result.metrics_before)
|
|
191
|
+
if result.metrics_after is not None:
|
|
192
|
+
for method, mlist in result.metrics_after.items():
|
|
193
|
+
write_metrics(method, mlist)
|
|
194
|
+
print(f" CSV: {F_METRIC_CSV}")
|
|
195
|
+
|
|
196
|
+
# --- 4) Corrected GeoTIFFs ---
|
|
197
|
+
if SAVE_CORRECTED_TIFF:
|
|
198
|
+
print("\n[Corrected GeoTIFFs]")
|
|
199
|
+
for method in METHODS:
|
|
200
|
+
fp = f_corrected(method)
|
|
201
|
+
io.write_geotiff(fp, result.corrected[method], grid,
|
|
202
|
+
band_indices=band_indices)
|
|
203
|
+
print(f" TIFF: {fp}")
|
|
204
|
+
|
|
205
|
+
print(f"\nDone. Output folder: {OUT_DIR}")
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
if __name__ == "__main__":
|
|
209
|
+
main()
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jaebeom Kim and Minkyu Moon
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|