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.
Files changed (37) hide show
  1. fortocorrpy-1.0.0/CITATION.cff +55 -0
  2. fortocorrpy-1.0.0/DESIGN_SPEC.md +326 -0
  3. fortocorrpy-1.0.0/EXAMPLE/data/4_bands.tif +0 -0
  4. fortocorrpy-1.0.0/EXAMPLE/data/DEM.tif +0 -0
  5. fortocorrpy-1.0.0/EXAMPLE/data/LC.tif +0 -0
  6. fortocorrpy-1.0.0/EXAMPLE/data/NDVI.tif +0 -0
  7. fortocorrpy-1.0.0/EXAMPLE/data/sensing_time.json +3 -0
  8. fortocorrpy-1.0.0/EXAMPLE/example.py +209 -0
  9. fortocorrpy-1.0.0/LICENSE +21 -0
  10. fortocorrpy-1.0.0/PKG-INFO +174 -0
  11. fortocorrpy-1.0.0/README.md +140 -0
  12. fortocorrpy-1.0.0/docs/api_reference.md +155 -0
  13. fortocorrpy-1.0.0/docs/methods.md +119 -0
  14. fortocorrpy-1.0.0/docs/usage.md +249 -0
  15. fortocorrpy-1.0.0/pyproject.toml +78 -0
  16. fortocorrpy-1.0.0/src/fortocorrpy/T_correct.py +157 -0
  17. fortocorrpy-1.0.0/src/fortocorrpy/__init__.py +109 -0
  18. fortocorrpy-1.0.0/src/fortocorrpy/config.py +194 -0
  19. fortocorrpy-1.0.0/src/fortocorrpy/evaluation.py +177 -0
  20. fortocorrpy-1.0.0/src/fortocorrpy/illum.py +119 -0
  21. fortocorrpy-1.0.0/src/fortocorrpy/io.py +573 -0
  22. fortocorrpy-1.0.0/src/fortocorrpy/linear_C.py +137 -0
  23. fortocorrpy-1.0.0/src/fortocorrpy/masking.py +224 -0
  24. fortocorrpy-1.0.0/src/fortocorrpy/pipeline.py +426 -0
  25. fortocorrpy-1.0.0/src/fortocorrpy/solar.py +241 -0
  26. fortocorrpy-1.0.0/src/fortocorrpy/terrain.py +151 -0
  27. fortocorrpy-1.0.0/tests/conftest.py +64 -0
  28. fortocorrpy-1.0.0/tests/test_T_correct.py +226 -0
  29. fortocorrpy-1.0.0/tests/test_config.py +100 -0
  30. fortocorrpy-1.0.0/tests/test_evaluation.py +80 -0
  31. fortocorrpy-1.0.0/tests/test_illum.py +97 -0
  32. fortocorrpy-1.0.0/tests/test_io.py +277 -0
  33. fortocorrpy-1.0.0/tests/test_linear_C.py +80 -0
  34. fortocorrpy-1.0.0/tests/test_masking.py +195 -0
  35. fortocorrpy-1.0.0/tests/test_pipeline.py +530 -0
  36. fortocorrpy-1.0.0/tests/test_solar.py +114 -0
  37. 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
@@ -0,0 +1,3 @@
1
+ {
2
+ "sensing_time": "2024-08-14T02:27:09+00:00"
3
+ }
@@ -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.