diff --git a/karios/api/config.py b/karios/api/config.py index fd30d7e..d3b1751 100644 --- a/karios/api/config.py +++ b/karios/api/config.py @@ -43,21 +43,21 @@ class RuntimeConfiguration: Attributes: output_directory: Directory where results will be written - pixel_size: Optional pixel size in meters. Ignored if image resolution - can be read from input images - title_prefix: Optional prefix for chart titles (max 26 characters) gen_kp_mask: Whether to generate a TIFF mask based on key points gen_delta_raster: Whether to generate intermediate products (dx/dy raster) generate_kp_chips: Whether to generate KP chip images - dem_description: Optional DEM source description for plots enable_large_shift_detection: Whether to detect and correct large pixel shifts + pixel_size: Optional pixel size in meters. Ignored if image resolution + can be read from input images + title_prefix: Optional prefix for chart titles (max 26 characters) + dem_description: Optional DEM source description for plots """ output_directory: Path - pixel_size: Optional[float] - title_prefix: Optional[str] gen_kp_mask: bool gen_delta_raster: bool generate_kp_chips: bool - dem_description: Optional[str] enable_large_shift_detection: bool + pixel_size: Optional[float] = None + title_prefix: Optional[str] = None + dem_description: Optional[str] = None diff --git a/karios/report/commons.py b/karios/report/commons.py index c885f04..5bbba23 100644 --- a/karios/report/commons.py +++ b/karios/report/commons.py @@ -63,7 +63,7 @@ def mean_profile(values: Series, positions: Series, bin_size: int = 20) -> MeanP dic = {"val": values, "po": position_group} df = DataFrame.from_dict(dic) group = df.groupby("po") - groups_positions = np.int16(group["po"].mean() * bin_size + bin_size / 2) + groups_positions = (group["po"].first() * bin_size + bin_size // 2).astype(np.int32) nb_pos = group["val"].count() mean_values = group["val"].mean() values_std = group["val"].std() diff --git a/requirements_dev.txt b/requirements_dev.txt index 5609078..99136fd 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -2,7 +2,7 @@ # conda install -n karios -c conda-forge --file requirements_dev.txt bandit==1.7.5 isort==5.13.2 -black==24.4.2 +black==26.3.1 pre-commit==3.6.0 pydocstyle==6.3.0 pylint==3.0.3 diff --git a/site/source/_images/02_dx_sk_before.png b/site/source/_images/02_dx_sk_before.png new file mode 100644 index 0000000..b586be4 Binary files /dev/null and b/site/source/_images/02_dx_sk_before.png differ diff --git a/site/source/_images/03_dy_sk_before.png b/site/source/_images/03_dy_sk_before.png new file mode 100644 index 0000000..7723ab4 Binary files /dev/null and b/site/source/_images/03_dy_sk_before.png differ diff --git a/site/source/_images/04_ce_sk_before.png b/site/source/_images/04_ce_sk_before.png new file mode 100644 index 0000000..d05c717 Binary files /dev/null and b/site/source/_images/04_ce_sk_before.png differ diff --git a/site/source/_images/ov_sks_before.png b/site/source/_images/ov_sks_before.png new file mode 100644 index 0000000..42d6f2c Binary files /dev/null and b/site/source/_images/ov_sks_before.png differ diff --git a/site/source/_includes/endnote.md b/site/source/_includes/endnote.md new file mode 100644 index 0000000..a6e231c --- /dev/null +++ b/site/source/_includes/endnote.md @@ -0,0 +1,3 @@ +```{note} +* You can cite KARIOS Tool by using [Saunier, S., Canonicy, P., Louis, J., Debaecker, V., & Albinet, C. (2024). KARIOS : A fast & efficient open source tool for geometric deformation analysis (1.0). The Very High-resolution Radar & Optical Data Assessment (2023) Workshop (VH RODA), ESA-ESRIN, Frascati (Italy)](https://doi.org/10.5281/zenodo.10598328) +* Many thanks to Telespazio for this open source tool. diff --git a/site/source/_static/_images/02_dx_sk_before.png b/site/source/_static/_images/02_dx_sk_before.png new file mode 100644 index 0000000..b586be4 Binary files /dev/null and b/site/source/_static/_images/02_dx_sk_before.png differ diff --git a/site/source/_static/_images/03_dy_sk_before.png b/site/source/_static/_images/03_dy_sk_before.png new file mode 100644 index 0000000..7723ab4 Binary files /dev/null and b/site/source/_static/_images/03_dy_sk_before.png differ diff --git a/site/source/_static/_images/04_ce_sk_before.png b/site/source/_static/_images/04_ce_sk_before.png new file mode 100644 index 0000000..d05c717 Binary files /dev/null and b/site/source/_static/_images/04_ce_sk_before.png differ diff --git a/site/source/_static/_images/ov_sks_before.png b/site/source/_static/_images/ov_sks_before.png new file mode 100644 index 0000000..42d6f2c Binary files /dev/null and b/site/source/_static/_images/ov_sks_before.png differ diff --git a/site/source/_static/css/custom.css b/site/source/_static/css/custom.css index 35f750d..1387d97 100644 --- a/site/source/_static/css/custom.css +++ b/site/source/_static/css/custom.css @@ -12,22 +12,21 @@ src: url('_fonts/TekneLDOVariable.ttf') format('woff'); } -/* @font-face { -font-family: 'Public Sans Thin'; -font-style: normal; -font-weight: normal; -src: local('Public Sans Thin'), url('_static/fonts/PublicSans-Thin.woff') format('woff'); +@font-face { + font-family: 'Public Sans Thin'; + font-style: normal; + font-weight: normal; + src: local('Public Sans Thin'), url('_static/fonts/PublicSans-Thin.woff') format('woff'); } @font-face { -font-family: 'Public Sans Medium'; -font-style: normal; -font-weight: normal; -src: local('Public Sans Medium'), url('_static/fonts/PublicSans-Medium.woff') format('woff'); -} */ - + font-family: 'Public Sans Medium'; + font-style: normal; + font-weight: normal; + src: local('Public Sans Medium'), url('_static/fonts/PublicSans-Medium.woff') format('woff'); +} -html { +*/ html { --pst-font-family-base-system: 'Public Sans Regular'; --pst-color-primary: #37424a !important; --pst-color-secondary: #6B92B2 !important; diff --git a/site/source/algorithm.PNG b/site/source/algorithm.PNG new file mode 100644 index 0000000..91b38cd Binary files /dev/null and b/site/source/algorithm.PNG differ diff --git a/site/source/case_study/01_overview_3m.png b/site/source/case_study/01_overview_3m.png new file mode 100644 index 0000000..a9b4c73 Binary files /dev/null and b/site/source/case_study/01_overview_3m.png differ diff --git a/site/source/case_study/01_overview_filter.png b/site/source/case_study/01_overview_filter.png new file mode 100644 index 0000000..4a157a2 Binary files /dev/null and b/site/source/case_study/01_overview_filter.png differ diff --git a/site/source/case_study/02_dx_3m.png b/site/source/case_study/02_dx_3m.png new file mode 100644 index 0000000..d4f9dfb Binary files /dev/null and b/site/source/case_study/02_dx_3m.png differ diff --git a/site/source/case_study/02_dx_filter.png b/site/source/case_study/02_dx_filter.png new file mode 100644 index 0000000..826d55f Binary files /dev/null and b/site/source/case_study/02_dx_filter.png differ diff --git a/site/source/case_study/02_dx_sk_before.png b/site/source/case_study/02_dx_sk_before.png new file mode 100644 index 0000000..b586be4 Binary files /dev/null and b/site/source/case_study/02_dx_sk_before.png differ diff --git a/site/source/case_study/03_dy_3m.png b/site/source/case_study/03_dy_3m.png new file mode 100644 index 0000000..baba7d6 Binary files /dev/null and b/site/source/case_study/03_dy_3m.png differ diff --git a/site/source/case_study/03_dy_filter.png b/site/source/case_study/03_dy_filter.png new file mode 100644 index 0000000..ca63dc1 Binary files /dev/null and b/site/source/case_study/03_dy_filter.png differ diff --git a/site/source/case_study/03_dy_sk_before.png b/site/source/case_study/03_dy_sk_before.png new file mode 100644 index 0000000..7723ab4 Binary files /dev/null and b/site/source/case_study/03_dy_sk_before.png differ diff --git a/site/source/case_study/04_ce_3m.png b/site/source/case_study/04_ce_3m.png new file mode 100644 index 0000000..bdd4c19 Binary files /dev/null and b/site/source/case_study/04_ce_3m.png differ diff --git a/site/source/case_study/04_ce_filter.png b/site/source/case_study/04_ce_filter.png new file mode 100644 index 0000000..227a4c4 Binary files /dev/null and b/site/source/case_study/04_ce_filter.png differ diff --git a/site/source/case_study/04_ce_sk_before.png b/site/source/case_study/04_ce_sk_before.png new file mode 100644 index 0000000..d05c717 Binary files /dev/null and b/site/source/case_study/04_ce_sk_before.png differ diff --git a/site/source/case_study/align.png b/site/source/case_study/align.png new file mode 100644 index 0000000..3e7db5b Binary files /dev/null and b/site/source/case_study/align.png differ diff --git a/site/source/case_study/ccm.md b/site/source/case_study/ccm.md new file mode 100644 index 0000000..969e437 --- /dev/null +++ b/site/source/case_study/ccm.md @@ -0,0 +1,9 @@ +(ccm)= + +# CCM Processing + +```{note} +Coming soon +``` + +```{include} ../_includes/endnote.md \ No newline at end of file diff --git a/site/source/case_study/chris.png b/site/source/case_study/chris.png new file mode 100644 index 0000000..87388cf Binary files /dev/null and b/site/source/case_study/chris.png differ diff --git a/site/source/case_study/edap.md b/site/source/case_study/edap.md new file mode 100644 index 0000000..e797c6c --- /dev/null +++ b/site/source/case_study/edap.md @@ -0,0 +1,9 @@ +(edap)= + +# EDAP Processing + +```{note} +Coming soon +``` + +```{include} ../_includes/endnote.md \ No newline at end of file diff --git a/site/source/case_study/formule1.png b/site/source/case_study/formule1.png new file mode 100644 index 0000000..e0b374b Binary files /dev/null and b/site/source/case_study/formule1.png differ diff --git a/site/source/case_study/global_greenland.png b/site/source/case_study/global_greenland.png new file mode 100644 index 0000000..6bb4352 Binary files /dev/null and b/site/source/case_study/global_greenland.png differ diff --git a/site/source/case_study/global_poland.png b/site/source/case_study/global_poland.png new file mode 100644 index 0000000..fb74958 Binary files /dev/null and b/site/source/case_study/global_poland.png differ diff --git a/site/source/case_study/global_toulouse.png b/site/source/case_study/global_toulouse.png new file mode 100644 index 0000000..34fb558 Binary files /dev/null and b/site/source/case_study/global_toulouse.png differ diff --git a/site/source/case_study/greenland1.png b/site/source/case_study/greenland1.png new file mode 100644 index 0000000..0028850 Binary files /dev/null and b/site/source/case_study/greenland1.png differ diff --git a/site/source/case_study/greenland2.png b/site/source/case_study/greenland2.png new file mode 100644 index 0000000..a04cf6f Binary files /dev/null and b/site/source/case_study/greenland2.png differ diff --git a/site/source/case_study/greenland3.png b/site/source/case_study/greenland3.png new file mode 100644 index 0000000..f35933d Binary files /dev/null and b/site/source/case_study/greenland3.png differ diff --git a/site/source/case_study/greenland4.png b/site/source/case_study/greenland4.png new file mode 100644 index 0000000..5cf0ecc Binary files /dev/null and b/site/source/case_study/greenland4.png differ diff --git a/site/source/case_study/index.md b/site/source/case_study/index.md index e915f0c..76ca149 100644 --- a/site/source/case_study/index.md +++ b/site/source/case_study/index.md @@ -10,64 +10,79 @@ it works in MD with myst_parser by enabling myst extension fieldlist :hidden: :maxdepth: 2 -prisma -sen2like +skysat +proba mss -``` - -This show how KARIOS is useful for our works. - - +``` :::::{grid} 2 ::::{grid-item} -:::{card} PRISMA -:link: prisma +:::{card} SKYSAT / LiDAR Processing +:link: skysat :link-type: ref -```{todo} -Write short description -``` +KARIOS matching process between Skysat and LiDAR high resolution images using downsampling and Laplacian optimization + ::: :::: ::::{grid-item} -:::{card} Sen2like -:link: sen2like +:::{card} PROBA/CHRIS Processing +:link: proba :link-type: ref -```{todo} -Write short description -``` +CHRIS images registration using template matching and TPS low/native resolution refinement + ::: :::: ::::{grid-item} -:::{card} MSS -:link: mss +:::{card} MSS Processing +:link: mss_cs :link-type: ref -```{todo} -Write short description -``` +Landsat MSS geometric correction using TPS + ::: :::: -::::: + +::::{grid-item} +:::{card} CCM Copernicus +:link: ccm +:link-type: ref + +```{note} +Coming soon +``` +::: +:::: + + + + +::::{grid-item} +:::{card} EDAP Processing +:link: edap +:link-type: ref + +```{note} +Coming soon +``` +::: +:::: + + +:::: \ No newline at end of file diff --git a/site/source/case_study/lap_3m.png b/site/source/case_study/lap_3m.png new file mode 100644 index 0000000..390e487 Binary files /dev/null and b/site/source/case_study/lap_3m.png differ diff --git a/site/source/case_study/lap_after.png b/site/source/case_study/lap_after.png new file mode 100644 index 0000000..f66c804 Binary files /dev/null and b/site/source/case_study/lap_after.png differ diff --git a/site/source/case_study/lap_before.png b/site/source/case_study/lap_before.png new file mode 100644 index 0000000..8cad777 Binary files /dev/null and b/site/source/case_study/lap_before.png differ diff --git a/site/source/case_study/mss.md b/site/source/case_study/mss.md index 24bfa8c..bef7ae9 100644 --- a/site/source/case_study/mss.md +++ b/site/source/case_study/mss.md @@ -1,7 +1,195 @@ -(mss)= +(mss_cs)= -# MSS +# MSS Processing -```{todo} -TBW -``` \ No newline at end of file +## Introduction + +The KARIOS tool can be easily integrated into a more complex geometric calibration processing in charge of Landsat MSS L1C product refinement [RD-11](rd-11). +This case shows how KARIOS results are used to estimate the deformation model, subsequently used for warping to Sentinel 2 reference image grid. Furthermore, KARIOS is used to check the quality of resulting L1C refined image. An in depth analysis, based on large dataset confirms that the proposed approach is relevant. + +The land monitoring community expects consistent and harmonised long-term datasets, in order to derive Essential Climate Variables (ECV). +Within this context, in complement to Thematic Mapper (TM) and Enhanced Thematic Mapper (ETM) data, the ESA archive includes also Landsat Multi +Spectral Scanner (MSS) data, which represent an outstanding source of historical data [RD-1](rd-01). +In the last decades, many efforts spent in the consolidation of this ESA archive, focusing on raw data repatriation, definition of new product type and bulk +processing of the full archive (ESA SLAP [RD-2](rd-02), [RD-3](rd-03), [RD-4](rd-04)). +Nonetheless, in the era of data cube, the MSS data is now requiring challenging algorithm developments to ensure that all threshold requirements, as defined +by the CEOS Analysis Ready Data For Land (CARD4L) Surface Reflectance (SR) Product Family Specifications (PFS), ([RD-5](rd-05)), are met. + +```{figure} mss.png +:name: mss +:width: 600px + +MSS Processing overview +``` + +## 1. MSS Geometric Correction + +The status is that the geometric accuracy of delivered Landsat +MSS ESA/SLAP products is not sufficient to reach CEOS ARD +compliancy at threshold level, because their multi temporal +registration accuracy is not sub-pixel. The bad precision of the +geolocation is a major contributor to uncertainty loss, It +prevents to reach 0.5 pixel RMSE multi temporal accuracy. + +The current ESA-MSS geo-processing is correct and include +state of art geometric calibration algorithm (bundle block +adjustment). + +The objective is to apply a poly-harmonic splines geometric transformation model to MSS data to account for local deformation. Also, a way forward might be to correct for local geometric distortions by using Radial Basis Functions (RBF) as proposed +in ([RD-6](rd-06), [RD-7](rd-07)). +The poly-harmonic splines are a linear combination of RBFs plus a 2nd degree polynomial term : + +```{figure} formule1.png +:name: formule1 +:width: 300px + +``` +Where : + +* N represents the total number of cells +* Ci the cell center coordinate +* Wi the weighting factor to be estimated +* The model is applied for co-registration of MSS L1C data to a common reference map. +* The model is calibrated by using reference GCP set (control point) defined for every cell (ci) +* Cells are selected into input images, the number / dimension of cells play an important role in the final result. + +The following chart summarizes the RBF chain : + +```{figure} rbf.png +:name: rbf +:width: 300px + +``` + +* Data Preparation: clipping over the same geo extent +* Matching: Collect Dense GCPs by using KARIOS applied on image twin (MSS Image, S2 image) +* Poly Harmonic Model Calibration: process GCPs grid, select GCPs relevant for calibration, and apply least square. +* Warping: transform input MSS image with polyharmonic model and generate output MSS Geo re-calibrated product +* Validation: use KARIOS, to check co-registration between S2 reference and output image. + +## 2. Example results + +These plots show the difference between the KARIOS results before and after the correction, against a S2 reference image, for products located in South of France, Greenland and Poland : + +### 2.1 South of France + +```{figure} toulousemss.png +:name: toulousemss +:width: 600px + +Geometric errors overview - Landsat MSS / S2 (South of France) +``` +```{figure} toulousemss2.png +:name: toulousemss2 +:width: 600px + +DY pixel shift (mean/STD) - Landsat MSS / S2 (South of France) +``` +```{figure} toulousemss3.png +:name: toulousemss3 +:width: 600px + +Geometric errors distribution - Landsat MSS / S2 (South of France) +``` +```{figure} toulousemss4.png +:name: toulousemss4 +:width: 600px + +Radial error shift by altitude distribution - Landsat MSS / S2 (South of France) +``` + +### 2.2 Greenland + +```{figure} greenland1.png +:name: greenland1 +:width: 600px + +Geometric errors overview - Landsat MSS / S2 (Greenland) +``` +```{figure} greenland2.png +:name: greenland2 +:width: 600px + +DY pixel shift (mean/STD) - Landsat MSS / S2 (Greenland) +``` +```{figure} greenland3.png +:name: greenland3 +:width: 600px + +Geometric errors distribution - Landsat MSS / S2 (Greenland) +``` +```{figure} greenland4.png +:name: greenland4 +:width: 600px + +Radial error shift by altitude distribution - Landsat MSS / S2 (Greenland) +``` + +### 2.3 Poland + +```{figure} poland1.png +:name: poland1 +:width: 600px + +Geometric errors overview - Landsat MSS / S2 (Poland) +``` +```{figure} poland2.png +:name: poland2 +:width: 600px + +DY pixel shift (mean/STD) - Landsat MSS / S2 (Poland) +``` +```{figure} poland3.png +:name: poland3 +:width: 600px + +Geometric errors distribution - Landsat MSS / S2 (Poland) +``` +```{figure} poland4.png +:name: poland4 +:width: 600px + +Radial error shift by altitude distribution - Landsat MSS / S2 (Poland) +``` + +## 3. Global results + +These plots show the circular error results for all tested products (about 100 products per site) before and after correction : + +### 3.1 South of France + +```{figure} global_toulouse.png +:name: global_toulouse +:width: 600px + +Circular error plot - All products - Landsat MSS / S2 (South of France) +``` + +### 3.2 Greenland + +```{figure} global_greenland.png +:name: global_greenland +:width: 600px + +Circular error plot - All products - Landsat MSS / S2 (Greenland) +``` + +### 3.3 Poland + +```{figure} global_poland.png +:name: global_poland +:width: 600px + +Circular error plot - All products - Landsat MSS / S2 (Poland) +``` + +```{warning} + +The scale is different in the before/after plots. +``` + +## Conclusion + +The results show a significant improvement in the global RMSE, in particular in the south of France and Poland dataset. For Greenland, the improvement is more limited as the mountainous terrain and the high ice coverage hinders the possibility to have a good KARIOS matching. Many parameters have been studied (number of cells, etc) with most of them being KARIOS parameters, which plays a key role in the geometric process. + +```{include} ../_includes/endnote.md \ No newline at end of file diff --git a/site/source/case_study/mss.png b/site/source/case_study/mss.png new file mode 100644 index 0000000..af3c513 Binary files /dev/null and b/site/source/case_study/mss.png differ diff --git a/site/source/case_study/ov_sks_before.png b/site/source/case_study/ov_sks_before.png new file mode 100644 index 0000000..42d6f2c Binary files /dev/null and b/site/source/case_study/ov_sks_before.png differ diff --git a/site/source/case_study/poland1.png b/site/source/case_study/poland1.png new file mode 100644 index 0000000..1a590e9 Binary files /dev/null and b/site/source/case_study/poland1.png differ diff --git a/site/source/case_study/poland2.png b/site/source/case_study/poland2.png new file mode 100644 index 0000000..54e5971 Binary files /dev/null and b/site/source/case_study/poland2.png differ diff --git a/site/source/case_study/poland3.png b/site/source/case_study/poland3.png new file mode 100644 index 0000000..64c8686 Binary files /dev/null and b/site/source/case_study/poland3.png differ diff --git a/site/source/case_study/poland4.png b/site/source/case_study/poland4.png new file mode 100644 index 0000000..b23578a Binary files /dev/null and b/site/source/case_study/poland4.png differ diff --git a/site/source/case_study/prisma.md b/site/source/case_study/prisma.md deleted file mode 100644 index 32d24b5..0000000 --- a/site/source/case_study/prisma.md +++ /dev/null @@ -1,7 +0,0 @@ -(prisma)= - -# PRISMA - -```{todo} -TBW -``` diff --git a/site/source/case_study/proba.md b/site/source/case_study/proba.md new file mode 100644 index 0000000..2bd07f8 --- /dev/null +++ b/site/source/case_study/proba.md @@ -0,0 +1,117 @@ +(proba)= + +# PROBA/CHRIS Processing + +## Introduction + +The KARIOS tool can be easily integrated into a more complex geometric calibration processing. + +This is what has been proposed as prototype in the context of PROBA-1/CHRIS Heritage Mission (ESA/ QA4EO 2 project) [RD-10](rd-10). +With the objective of creating a multi-temporal dataset, achieving a good registration of input PROBA-1 images against a reference map is mandatory. + +There were several concerns regarding geometric quality of PROBA-1 images. +The a priori geolocation accuracy of input image is rarely below 5.0 km and cannot be improved due to missing telemetry. +Input images are generally strongly distorted. + +The general process is summarized in this chart : + +```{figure} chris.png +:name: chris +:width: 600px + +CHRIS Process Summary +``` + +## 1. Coarse Registration​ + +A template matching algorithm can be used, followed by a re-alignment and scaling process. +With an ORB matching process, translation, scale and rotation values are estimated and applied to the CHRIS template. The result template will then we compared to a S2 reference with KARIOS. + +```{figure} tm.png +:name: tm +:width: 600px + +CHRIS Template Matching (left) and comparison with S2 (right) +``` +```{figure} align.png +:name: align +:width: 600px + +Alignment of the template over the reference +``` + +## 2. High Resolution KARIOS matching + +Now that the image is aligned with the reference, KARIOS can be performed, initially at native resolution (18m) : + +```{figure} spain_18_before.png +:name: spain_18_before +:width: 600px + +Geometric errors overview - CHRIS / S2 LiDAR before TPS correction (18m) +``` + +```{figure} spain_18_before_4.png +:name: spain_18_before_4 +:width: 600px + +Geometric errors distribution - CHRIS / S2 LiDAR before TPS correction (18m) +``` + +## 3. Low Resolution KARIOS matching + +The results show that the matching has only been performed partially. The corners near the center are captured whereas the ones in the upper and lower part of the image are not detected as the difference is too high. Thus, the final result is not meaningful for the whole image, and the TPS correction should not applied as the process depends on the detected corners. A downsampling can be performed to allow better matching (bi-cubic). A resolution of 48m is a good compromise between matching and not lowering too much information. + +```{figure} spain_48_before.png +:name: spain_48_before +:width: 600px + +Geometric errors overview - CHRIS / S2 LiDAR before TPS correction (48m) +``` + +```{figure} spain_48_before_4.png +:name: spain_48_before_4 +:width: 600px + +Geometric errors distribution - CHRIS / S2 LiDAR before TPS correction (48m) +``` + +The corners now cover the entire image and show all the CHRIS deformations, though the point density is lower. The TPS correction can be applied by using a warping at full resolution. + +## 3. Full Resolution​ Refinement + +The TPS algorithm yields the following results : + +```{figure} spain_18_after.png +:name: spain_18_after +:width: 600px + +Geometric errors overview - CHRIS / S2 LiDAR after TPS correction (18m) +``` + +```{figure} spain_18_after_4.png +:name: spain_18_after_4 +:width: 600px + +Geometric errors distribution - CHRIS / S2 LiDAR after TPS correction (18m) +``` + +The RMSE has been reduced, but the final matching could be improved. A second TPS correction process can be applied to the result image : + +```{figure} spain_18_after_2.png +:name: spain_18_after_2 +:width: 600px + +Geometric errors overview - CHRIS / S2 LiDAR after additional TPS correction (18m) +``` + +```{figure} spain_18_after_4_2.png +:name: spain_18_after_4_2 +:width: 600px + +Geometric errors distribution - CHRIS / S2 LiDAR after additional TPS correction (18m) +``` + +The results now show a significant improvement in terms of metrics and the two images can now be compared with a full coverage at native resolution. + +```{include} ../_includes/endnote.md \ No newline at end of file diff --git a/site/source/case_study/rbf.png b/site/source/case_study/rbf.png new file mode 100644 index 0000000..4bfa3ad Binary files /dev/null and b/site/source/case_study/rbf.png differ diff --git a/site/source/case_study/sen2like.md b/site/source/case_study/sen2like.md deleted file mode 100644 index 3c83fa3..0000000 --- a/site/source/case_study/sen2like.md +++ /dev/null @@ -1,7 +0,0 @@ -(sen2like)= - -# Sen2Like - -```{todo} -TBW -``` \ No newline at end of file diff --git a/site/source/case_study/skysat.md b/site/source/case_study/skysat.md new file mode 100644 index 0000000..dc1029d --- /dev/null +++ b/site/source/case_study/skysat.md @@ -0,0 +1,175 @@ +(skysat)= + +# SKYSAT / LiDAR Processing + +## Introduction + +The KARIOS tool can be used for matching images from different sensor types, in the herein page the Geometric Registration of a Skysat image against a reference LIDAR image is reported. + +This use case shows that KARIOS intermediate results should be carefully checked in order to define the most appropriate matching configuration (input parameters). Futhermore, beside configuration, image pre processing is also required. + +## 1. Initial results + +The two images are first compared without any preprocessing, with a basic configuration : + +```{figure} ov_sks_before.png +:name: fig-overview +:width: 600px + +Geometric errors overview - Skysat / USGS LiDAR before opimization +``` +```{figure} 02_dx_sk_before.png +:name: dx +:width: 600px + +DX pixel shift (mean/STD) - Skysat / USGS LiDAR before opimization +``` +```{figure} 03_dy_sk_before.png +:name: dy +:width: 600px + +DY pixel shift (mean/STD) - Skysat / USGS LiDAR before opimization +``` +```{figure} 04_ce_sk_before.png +:name: ce +:width: 600px + +Geometric errors distribution - Skysat / USGS LiDAR before opimization +``` + +```{warning} + +* Prefer performing the match on large areas +* Always use images with int value +``` + +These results look good but are misleading as the algorithm does not provide a relevant matching. +Manual measurements show a geometric shift which is close to 10m. + +## 2. Laplacian optimization + +KARIOS tool matching approach is based on Kanade-Lucas-Tomasi feature +detector algorithm. The two input intensity value images (Reference / Monitored) are filtered +with Laplacian operator (high-pass filter, 2nd order derivation). Corners from Laplacian images +are matched together using optical flow algorithms.​ + +The same Laplacian filter is applied to both input images, even if the image spatial resolution is +different.​ + +A visual check of input Laplacian images is therefore recommended in order to evaluate If +image corners can be matched : + +```{figure} lap_before.png +:name: lap_before +:width: 600px + +Computed laplacian - Skysat / USGS LiDAR before opimization +``` +In case the of Skysat (on the left) and LIDAR (on the right), significant differences are observed. In the LIDAR image, edges are +very sharp compared to the ones in Skysat image, which are more blurred. Both images are also quite noisy. + +A solution consists in applying a low-pass filtering (Gaussian filters, Median filters) to both images in order to +get more comparable Laplacian image set​. The laplacian kernel size can also be optimized in the KARIOS parameters. + +```{figure} lap_after.png +:name: lap_after +:width: 600px + +Computed laplacian - Skysat / USGS LiDAR after opimization + +``` +As observed visually, the best configuration is to have: +* Gaussian kernel size = 17​ +* Laplacian kernal size = 13​ + +Nevertheless, the KARIOS results show that the algorithm still does not captures the real geometric difference : + +```{figure} 01_overview_filter.png +:name: 01_overview_filter +:width: 600px + +Geometric errors overview - Skysat / USGS LiDAR after laplacian opimization +``` +```{figure} 02_dx_filter.png +:name: 02_dx_filter +:width: 600px + +DX pixel shift (mean/STD) - Skysat / USGS LiDAR after laplacian opimization +``` +```{figure} 03_dy_filter.png +:name: 03_dy_filter +:width: 600px + +DY pixel shift (mean/STD) - Skysat / USGS LiDAR after laplacian opimization +``` +```{figure} 04_ce_filter.png +:name: 04_ce_filter +:width: 600px + +Geometric errors distribution - Skysat / USGS LiDAR after laplacian opimization +``` + +## 3. Downsampling + + +A second option consists in sampling the images to a lower spatial resolution, e.g 3.0 m pixel +spacing (the original resolution was 0.5 m) + +Indeed, KARIOS matching does not work at full resolution​ because of image quality issue​s, spatial resolution differences​ and geometric deformations. + +Downsampling gives a smaller and more simple laplacian : + +```{figure} lap_3m.png +:name: lap_3m +:width: 600px + +Computed laplacian - Skysat / USGS LiDAR at 3 meters +``` + +```{warning} +This comparison shows the whole product, where previous laplacians were on a small part of the image. +``` +This provides the following KARIOS results : + +```{figure} 01_overview_3m.png +:name: 01_overview_3m +:width: 600px + +Geometric errors overview - Skysat / USGS LiDAR at 3 meters +``` +```{figure} 02_dx_3m.png +:name: 02_dx_3m +:width: 600px + +DX pixel shift (mean/STD) - Skysat / USGS LiDAR at 3 meters +``` +```{figure} 03_dy_3m.png +:name: 03_dy_3m +:width: 600px + +DY pixel shift (mean/STD) - Skysat / USGS LiDAR at 3 meters +``` +```{figure} 04_ce_3m.png +:name: 04_ce_3m +:width: 600px + +Geometric errors distribution - Skysat / USGS LiDAR at 3 meters +``` + +The deformation can now be detected by the matching algorithm. +In the end, downsampling is a good approach​ which provides accuracy within pixel, but precision is degraded​. +Results are consistent with the geometric deformations observed. + +## Conclusion + +* KARIOS has been used to assess SKS image against LIDAR Image​. + +* Pre-processing and downsampling are required to in order to fully assess SKS geometry​. + +* Automatic image Matching and manual image measurements are matching.​ + +* Within the uncertainty budget, similar results (and shape) areachieved against S2 data.​ + +* When correcting SKS image for static error (about 5.0 m in both directions), uncertainty (RMSE) reaches 7.0 m. + +```{include} ../_includes/endnote.md \ No newline at end of file diff --git a/site/source/case_study/spain_18_after.png b/site/source/case_study/spain_18_after.png new file mode 100644 index 0000000..2babed0 Binary files /dev/null and b/site/source/case_study/spain_18_after.png differ diff --git a/site/source/case_study/spain_18_after_2.png b/site/source/case_study/spain_18_after_2.png new file mode 100644 index 0000000..fc0c128 Binary files /dev/null and b/site/source/case_study/spain_18_after_2.png differ diff --git a/site/source/case_study/spain_18_after_4.png b/site/source/case_study/spain_18_after_4.png new file mode 100644 index 0000000..63911d1 Binary files /dev/null and b/site/source/case_study/spain_18_after_4.png differ diff --git a/site/source/case_study/spain_18_after_4_2.png b/site/source/case_study/spain_18_after_4_2.png new file mode 100644 index 0000000..951a4ac Binary files /dev/null and b/site/source/case_study/spain_18_after_4_2.png differ diff --git a/site/source/case_study/spain_18_before.png b/site/source/case_study/spain_18_before.png new file mode 100644 index 0000000..a1d79be Binary files /dev/null and b/site/source/case_study/spain_18_before.png differ diff --git a/site/source/case_study/spain_18_before_4.png b/site/source/case_study/spain_18_before_4.png new file mode 100644 index 0000000..49a3964 Binary files /dev/null and b/site/source/case_study/spain_18_before_4.png differ diff --git a/site/source/case_study/spain_48_before.png b/site/source/case_study/spain_48_before.png new file mode 100644 index 0000000..fe0f0bf Binary files /dev/null and b/site/source/case_study/spain_48_before.png differ diff --git a/site/source/case_study/spain_48_before_4.png b/site/source/case_study/spain_48_before_4.png new file mode 100644 index 0000000..3aaf6dc Binary files /dev/null and b/site/source/case_study/spain_48_before_4.png differ diff --git a/site/source/case_study/tm.png b/site/source/case_study/tm.png new file mode 100644 index 0000000..73c199b Binary files /dev/null and b/site/source/case_study/tm.png differ diff --git a/site/source/case_study/toulousemss.png b/site/source/case_study/toulousemss.png new file mode 100644 index 0000000..3d7670f Binary files /dev/null and b/site/source/case_study/toulousemss.png differ diff --git a/site/source/case_study/toulousemss2.png b/site/source/case_study/toulousemss2.png new file mode 100644 index 0000000..ce0c053 Binary files /dev/null and b/site/source/case_study/toulousemss2.png differ diff --git a/site/source/case_study/toulousemss3.png b/site/source/case_study/toulousemss3.png new file mode 100644 index 0000000..e8d3cd9 Binary files /dev/null and b/site/source/case_study/toulousemss3.png differ diff --git a/site/source/case_study/toulousemss4.png b/site/source/case_study/toulousemss4.png new file mode 100644 index 0000000..80c78eb Binary files /dev/null and b/site/source/case_study/toulousemss4.png differ diff --git a/site/source/conf.py b/site/source/conf.py index 69ce170..b3ca778 100644 --- a/site/source/conf.py +++ b/site/source/conf.py @@ -22,7 +22,7 @@ "sphinx_design", "sphinx.ext.todo", "sphinx.ext.githubpages", - "sphinxcontrib.images", + # "sphinxcontrib.images", ] templates_path = ["_templates"] diff --git a/site/source/cookbook/config.md b/site/source/cookbook/config.md index a30532f..209516d 100644 --- a/site/source/cookbook/config.md +++ b/site/source/cookbook/config.md @@ -1,13 +1,88 @@ +(config)= + # Influence of settings -```{todo} -Define content -``` +This section presents the parameters that can be found and modified on the processing configuration_file.yaml file that can be added in the command line input (--conf). Otherwise, a default configuration file will be applied. These parameters are critical for the KLT matching and can greatly change the outputs. + +## 1. KLT parameters + +### 1.1 minDistance + +Minimum Euclidean distance (in pixels) between detected feature points (corners). + +With small values, features can be very close to each other which implies more corners, especially in textured areas. There could be a risk of redundancy and more similar points (can be good for dense matching, but heavier to track). + +For larger values, features are more spread out. There will be fewer points, more spatially uniform coverage, which is good enough for global alignment and computational time, but less interesting for very fine local deformation. + +### 1.2 blocksize + +Size of the neighborhood (in pixels) used for computing the covariance matrix for corner detection. + +With small values, the model will be sensitive to very fine details and noise which is good for high‑resolution, sharp imagery. + +For larger values, corners are more stable and less noisy, but it might miss very small features. + +### 1.3 maxCorners + +Maximum number of corners (features) to detect. + +Can be used to reduce the number of detected points for dense areas when computational power / processing time is an issue. + +### 1.4 matching_winsize + +Size of the search window (in pixels) used when matching/tracking features between images. + +With small windows, the process will be faster and precise when images are already quite aligned. But it might fail if displacement is too large. + +For larger windows, the model will be able to handle large displacements between images, making it more robust when initial alignment is rough. But it gets more computationally expensive and can increase risk of mismatches if texture is repetitive. + +### 1.5 qualityLevel + +Threshold for selecting strong corners, expressed as a fraction of the best corner response (between 0 and 1). + +With high values, only very strong corners are kept which provides fewer but more reliable features. + +With low values, there will be many more corners, including weak ones which could be provide noisy but denser outputs. + +### 1.6 xStart + +Horizontal offset (in pixels) from which to start processing in the image. + +### 1.7 tile_size + +Size (in pixels) of the processing tile, usually in width/height. + +Large images can be too big to process fully, so this allows to process the image in (tile_size) x (tile_size pixel) chunks. Feature detection and matching are done per tile, which reduces memory usage and can parallelize processing. + +Smaller tiles means less memory, but more edge effects and overhead. +Larger tiles means better global context, but heavier on RAM. + +### 1.8 laplacian_kernel_size + +Kernel size for the Laplacian filter. + +Used for edge enhancement, focus/texture measure and pre‑filtering before feature detection. + +Smaller kernel will make the model more sensitive to fine edges and noise, whereas large kernels will give +a smoother response and emphasize broader structures, better for high resolution imagery. + +### 1.9 outliers_filtering + +Kernel size for the Laplacian filter. + +Whether to filter out mismatched or inconsistent feature matches after KLT tracking. + +When true, bad matches (e.g. due to occlusions, parallax, moving objects, repetitive patterns) are removed. +When false, all matches are kept, including bad matches, which can be risky for the model. + +## Accuracy analysis + +confidence_threshold : parameter that controls the points which are used for the circular error plot and stats. -## Chapter 1 +A higher value will provide more relevant points with a high confidence value, which can lead to more precise statistics but visually less smooth with fewer points. -### Chapter 1.1 +A lower value will take a lot of points in consideration which can include less relevant results but with nicer display. -### Chapter 1.2 +This value does not impact the tracking. -## Chapter 2 \ No newline at end of file +```{include} ../_includes/endnote.md \ No newline at end of file diff --git a/site/source/cookbook/csv_file.png b/site/source/cookbook/csv_file.png new file mode 100644 index 0000000..6c74ac7 Binary files /dev/null and b/site/source/cookbook/csv_file.png differ diff --git a/site/source/cookbook/dem_plot.png b/site/source/cookbook/dem_plot.png new file mode 100644 index 0000000..5322c99 Binary files /dev/null and b/site/source/cookbook/dem_plot.png differ diff --git a/site/source/cookbook/index.md b/site/source/cookbook/index.md index a861bd6..32eb81b 100644 --- a/site/source/cookbook/index.md +++ b/site/source/cookbook/index.md @@ -4,12 +4,39 @@ ```{toctree} :hidden: -:maxdepth: 1 +:maxdepth: 2 output config ``` -Here you will learn how to understand the [output data and plots](output) generated by KARIOS and how settings affect the output of KARIOS. +Here you will learn how to understand the output data and plots generated by KARIOS and how settings affect the output of KARIOS. + +:::::{grid} 2 + +::::{grid-item} +:::{card} Understand KARIOS output data and plots +:link: output +:link-type: ref + +Detailed description of KARIOS outputs and plots + +::: +:::: + + + +::::{grid-item} +:::{card} Influence of settings +:link: config +:link-type: ref + +Understand the influence of KARIOS parameters + +::: +:::: + +:::: + diff --git a/site/source/cookbook/kp_delta.png b/site/source/cookbook/kp_delta.png new file mode 100644 index 0000000..be11d4e Binary files /dev/null and b/site/source/cookbook/kp_delta.png differ diff --git a/site/source/cookbook/lap_3m.png b/site/source/cookbook/lap_3m.png new file mode 100644 index 0000000..390e487 Binary files /dev/null and b/site/source/cookbook/lap_3m.png differ diff --git a/site/source/cookbook/output.md b/site/source/cookbook/output.md index 5ae38a1..e8482b8 100644 --- a/site/source/cookbook/output.md +++ b/site/source/cookbook/output.md @@ -1,44 +1,100 @@ -# Understand KARIOS outputs data and plots +(output)= -```{todo} -Write intro -``` +# Understand KARIOS output data and plots -## Error overview maps +This section reviews all the outputs generated by KARIOS, including plots and intermediate products. -```{todo} -Write description -``` +## 1. Plots -```{thumbnail} 01_overview.png -``` +### 1.1 Error overview maps + +The error overview maps show the monitored image, reference on the left and the keypoints map on the right. For each point, the radial error in pixel (top) and the angle error (bottom) are displayed. ![overview](01_overview.png) -## X/Y pixel shift by rows and columns +### 1.2 X/Y pixel shift by rows and columns -```{todo} -Write description -``` +These outputs show the pixel shift mean and standard deviation by rows and columns, for both x and y directions. ![dx](02_dx.png) ![dy](03_dy.png) -## Geometric Error Distribution +### 1.3 Geometric Error Distribution + +This output provides : + +* The circular error graph that gives a global view on the pixel shift distribution and the geometric shift tendencies, as well as the histograms in both directions with mean/sigma values. +* The global statistics: min, max, mean, STD, RMSE. +* The radial error plot with circular error (90%/95%). -```{todo} -Write description -``` ![geo](04_ce.png) -## Files +### 1.4 Geometric shift by altitudes distribution + +This output provides the evolution of the mean / STD / RMSE of the deviation against elevation values, groupped as bins. These plots are generated if the DEM is provided in the KARIOS command line (--dem) and contain : + +* A plot for the dx deviation +* A plot for the dy deviation +* A plot for radial error + + +![dem_plot](dem_plot.png) + +## 2. Files + +### 2.1 TXT File + +This file contains all the global useful information to be easily extracted : + +* Monitored image name +* Reference image name +* Total number of valid pixels +* Pixel sampling +* Confidence threshold for accuracy analysis +* Min/max values in x/y +* Median/Mean/STD values in x/y -```{todo} -Write description +![txt_file](txt_file.png) + +### 2.2 CSV File + +This file contains for every detected corner : + +* The x/y coordinates +* The shift along x/y in meters +* The confidence score + +![csv_file](csv_file.png) + +### 2.3 Key points mask + +This mask is a GeoTIFF file containing for each detected keypoint : + +* dx/dy shift in pixel +* Confidence score +* Radial error +* Angle error +* ZNCC score if available + +This file is also available as a JSON file that can be viewed on QGIS : + +![kp_delta](kp_delta.png) + +### 2.4 Laplacian images + +The Laplacian image is the 2D second derivative of the input images (monitored and reference) which is used in the KLT process as the basis to detect corners. It can be useful to examine these images to see if they are similar and comparable, as they are determinant for corners detection. + +This output can be activated by using --generate-intermediate-product. + +```{figure} lap_3m.png +:name: lap +:width: 600px + +Computed laplacian - Skysat / USGS LiDAR at 3 meters ``` -### CSV File +```{include} ../_includes/endnote.md + -### Key points mask diff --git a/site/source/cookbook/txt_file.png b/site/source/cookbook/txt_file.png new file mode 100644 index 0000000..206c353 Binary files /dev/null and b/site/source/cookbook/txt_file.png differ diff --git a/site/source/disparity_map.PNG b/site/source/disparity_map.PNG new file mode 100644 index 0000000..3fb2cff Binary files /dev/null and b/site/source/disparity_map.PNG differ diff --git a/site/source/error_overview.PNG b/site/source/error_overview.PNG new file mode 100644 index 0000000..5030221 Binary files /dev/null and b/site/source/error_overview.PNG differ diff --git a/site/source/index.rst b/site/source/index.rst index 8bace99..e958a5f 100644 --- a/site/source/index.rst +++ b/site/source/index.rst @@ -16,8 +16,8 @@ .bd-header-article{display: none;} /* hide breadcrumbs*/ -.. important:: - Site under construction +.. .. important:: +.. Site under construction .. This title is not displayed due to custom css above (h1) @@ -33,8 +33,8 @@ Welcome to Karios's documentation! :maxdepth: 1 :caption: Contents: - case_study/index quickstart + case_study/index cookbook/index references diff --git a/site/source/quickstart.md b/site/source/quickstart.md index 28103ce..70225fd 100644 --- a/site/source/quickstart.md +++ b/site/source/quickstart.md @@ -52,7 +52,7 @@ pip install . Karios is now installed in its conda envronement, you are ready to use it. :::{note} -The conda environment stay active until you close your terminal session. You need to activate it every time you start a new session and want to use KARIOS in the terminal session. +The conda environment stays active until you close your terminal session. You need to activate it every time you start a new session to use KARIOS. ::: ### Verify Installation @@ -104,7 +104,7 @@ Recommendation: ## CLI Usage :::{important} -**All commands below suppose that the karios conda environment is activated** +**All commands below suppose that the karios conda environment is activated.** ::: ### Command Structure @@ -175,33 +175,33 @@ karios process monitored.tif reference.tif mask.tif dem.tif \ | Option | Type | Description | |--------|------|------------| | `--conf` | FILE | Configuration file path. Default is the built-in configuration.
[default: /karios/configuration/processing_configuration.json] | -| `--resume` | Flag | Do not run KLT matcher, only accuracy analysis and report generation | -| `--input-pixel-size`, `-pxs` | FLOAT | Input image pixel size in meter. Ignored if image resolution can be read from input image | +| `--resume` | Flag | Do not run KLT matcher, only accuracy analysis and report generation. | +| `--input-pixel-size`, `-pxs` | FLOAT | Input image pixel size in meter. Ignored if image resolution can be read from input image. | #### Output Options | Option | Type | Description | |--------|------|------------| | `--out` | PATH | Output results folder path [default: results] | -| `--title-prefix`, `-tp` | TEXT | Add prefix to title of generated output charts.
(limited to 26 characters) | -| `--generate-key-points-mask`, `-kpm` | FLAG | Generate a tiff mask based on KP from KTL | -| `--generate-intermediate-product`, `-gip` | FLAG | Generate a two-bands tiff based on KP with band 1 dx and band 2 dy | -| `--generate-kp-chips`, `-gkc` | FLAG | Generate chip images centered on key points of monitored and reference products | -| `--dem-description` | TEXT | DEM source name. Added in generated DEM plots.
Example: "COPERNICUS DEM resampled to 10m" | +| `--title-prefix`, `-tp` | TEXT | Add prefix to title of generated output charts.
(limited to 26 characters). | +| `--generate-key-points-mask`, `-kpm` | FLAG | Generate a tiff mask based on KP from KTL. | +| `--generate-intermediate-product`, `-gip` | FLAG | Generate a two-bands tiff based on KP with band 1 (dx) and band 2 (dy).| +| `--generate-kp-chips`, `-gkc` | FLAG | Generate chip images centered on key points of monitored and reference products. | +| `--dem-description` | TEXT | DEM source name. Added in generated DEM plots.
Example: "COPERNICUS DEM resampled to 10m." | #### Advanced Options | Option | Type | Description | |--------|------|------------| -| `--enable-large-shift-detection` | FLAG | Enable detection and correction of large pixel shifts | +| `--enable-large-shift-detection` | FLAG | Enable detection and correction of large pixel shifts. | #### Logging Options | Option | Type | Description | |--------|------|------------| -| `--debug`, `-d` | FLAG | Enable Debug mode | -| `--no-log-file` | FLAG | Do not log in file (not compatible with `--log-file-path`) | -| `--log-file-path` | PATH | Log file path [default: karios.log] | +| `--debug`, `-d` | FLAG | Enable Debug mode. | +| `--no-log-file` | FLAG | Do not log in file (not compatible with `--log-file-path`). | +| `--log-file-path` | PATH | Log file path [default: karios.log]. | ## Configuration @@ -216,34 +216,32 @@ The processing configuration defines algorithm parameters and is loaded from JSO ``` This configuration includes: -- **KLT matching parameters**: Corner detection, window sizes, quality thresholds -- **Accuracy analysis settings**: Confidence thresholds for statistical calculations -- **Plot configurations**: Figure sizes, color maps, axis limits -- **Large shift detection**: Bias correction thresholds +- **KLT matching parameters**: Corner detection, window sizes, quality thresholds. +- **Accuracy analysis settings**: Confidence thresholds for statistical calculations. +- **Plot configurations**: Figure sizes, color maps, axis limits. +- **Large shift detection**: Bias correction thresholds. When using the CLI, runtime configuration is automatically created from command-line arguments. ### Parameter Details - `processing_configuration.shift_image_processing` (Large Shift Matching processing parameters) - - `bias_correction_min_threshold`: Pixel threshold for applying large shift correction + - `bias_correction_min_threshold`: Pixel threshold for applying large shift correction. - `processing_configuration.klt_matching` (Matching processing parameters) - - `xStart`: X margin to skip during matching - - `tile_size`: Tile size for memory-efficient processing - - `laplacian_kernel_size`: Aperture size for Laplacian filtering - - > The following parameter allows to control how to find the most prominent corners in the - reference image, as described by the OpenCV documentation goodFeaturesToTrack, after applying Laplacian. - - - `minDistance`: Minimum distance between detected corners - - `blocksize`: Block size for derivative computation + - `xStart`: X margin to skip during matching. + - `tile_size`: Tile size for memory-efficient processing. + - `laplacian_kernel_size`: Aperture size for Laplacian filtering. + - `minDistance`: Minimum distance between detected corners. + - `blocksize`: Block size for derivative computation. - `maxCorners`: Maximum corners to extract per tile. `0` implies that no limit on the maximum is set and all detected corners are returned. - - `qualityLevel`: Minimum corner quality threshold - - `matching_winsize`: Search window size during matching - - `outliers_filtering`: Enable/disable outlier filtering + > The following parameter allows to control how to find the most prominent corners in the + reference image, as described by the OpenCV documentation goodFeaturesToTrack, after applying Laplacian. + - `qualityLevel`: Minimum corner quality threshold. + - `matching_winsize`: Search window size during matching. + - `outliers_filtering`: Enable/disable outlier filtering. -Refer to section [KLT param leverage](#klt-param-leverage) for details +Refer to section [KLT param leverage](#klt-param-leverage) for details. - `processing_configuration.accuracy_analysis` - `confidence_threshold`: Minimum confidence score for statistical analysis. If `None`, not applied. @@ -251,28 +249,28 @@ Refer to section [KLT param leverage](#klt-param-leverage) for details Plot configuration parameters for `overview`, `shift`, `dem`, and `ce` plots control figure sizes, color maps, and axis limits. - `plot_configuration.overview` (overview plot parameters) - - `fig_size` : Size of the generated figure in inches - - `shift_colormap` : matplotlib color map name for the KP shift error scatter plot - - `shift_auto_axes_limit` : auto compute KP shift error colorbar scale - - `shift_axes_limit` : KP shift error colorbar maximum limit, N/A if `shift_auto_axes_limit` is `true` - - `theta_colormap` : matplotlib color map name for the KP theta error scatter plot + - `fig_size` : size of the generated figure + - `shift_colormap` : matplotlib color map name for the KP shift error scatter plot. + - `shift_auto_axes_limit` : auto compute KP shift error colorbar scale. + - `shift_axes_limit` : KP shift error colorbar maximum limit, N/A if `shift_auto_axes_limit` is `true`. + - `theta_colormap` : matplotlib color map name for the KP theta error scatter plot. - `plot_configuration.shift` (shift by row/col group plot parameters) - - `fig_size` : Size of the generated figure in inches - - `scatter_colormap` : matplotlib color map name for the KP shift scatter plot - - `scatter_auto_limit` : auto compute KP shift scatter plot limit - - `scatter_min_limit` : KP shift scatter plot minimum limit, N/A if `scatter_auto_limit` is `true` - - `scatter_max_limit` : KP shift scatter plot maximum limit, N/A if `scatter_auto_limit` is `true` - - `histo_mean_bin_size` : KP shift histogram bin size (number of image row/col for the histogram bin) + - `fig_size` : size of the generated figure. + - `scatter_colormap` : matplotlib color map name for the KP shift scatter plot. + - `scatter_auto_limit` : auto compute KP shift scatter plot limit. + - `scatter_min_limit` : KP shift scatter plot minimum limit, N/A if `scatter_auto_limit` is `true`. + - `scatter_max_limit` : KP shift scatter plot maximum limit, N/A if `scatter_auto_limit` is `true`. + - `histo_mean_bin_size` : KP shift histogram bin size (number of image row/col for the histogram bin). - `plot_configuration.dem` (shift by altitude group plot parameters) - - `fig_size` : Size of the generated figure in inches - - `show_fliers` : draw fliers of box plot - - `histo_mean_bin_size`: KP altitude histogram bin size (altitude ranges size) + - `fig_size` : size of the generated figure. + - `show_fliers` : draw fliers of box plot. + - `histo_mean_bin_size`: KP altitude histogram bin size (altitude ranges size). - `plot_configuration.ce` (Circular error plot parameters) - - `fig_size` : Height size of the generated figure in inches, width is 5/3 of the height - - `ce_scatter_colormap` : matplotlib color map name for the KP shift density scatter plot + - `fig_size` : height size of the generated figure, width is 5/3 of the height. + - `ce_scatter_colormap` : matplotlib color map name for the KP shift density scatter plot. ### Outputs @@ -300,7 +298,7 @@ KARIOS generates several types of outputs: #### Configuration -- Copy of the processing configuration used +- Copy of the processing configuration used. ## Output File Formats @@ -322,10 +320,10 @@ KARIOS generates a CSV file containing all key points detected by the KLT matche | `zncc_score` | Zero-mean Normalized Cross-Correlation score | -1.0 to 1.0 | Optional: only if large shift detection is disabled | **Notes:** -- The CSV uses semicolon (`;`) as separator -- `zncc_score` is only computed for a selection of key points with KLT score above the confidence threshold -- `zncc_score` provides additional matching quality assessment using normalized cross-correlation -- All coordinates are in image pixel space (not geographic coordinates) +- The CSV uses semicolon (`;`) as separator. +- `zncc_score` is only computed for a selection of key points with KLT score above the confidence threshold. +- `zncc_score` provides additional matching quality assessment using normalized cross-correlation. +- All coordinates are in image pixel space (not geographic coordinates). ### GeoJSON Output @@ -374,13 +372,13 @@ When input images are georeferenced, KARIOS generates a GeoJSON file (`kp_delta. | `zncc_score` | Cross-correlation score | -1.0 to 1.0 | Optional, can be `null` | **Coordinate System:** -- Point coordinates are in the same coordinate reference system as the input images -- Coordinates are transformed from pixel space to geographic space using the image's geotransform -- The CRS is specified in the `crs` object using the EPSG code from the reference image +- Point coordinates are in the same coordinate reference system as the input images. +- Coordinates are transformed from pixel space to geographic space using the image's geotransform. +- The CRS is specified in the `crs` object using the EPSG code from the reference image. ## Chip Images (Optional) -When enabled with `--generate-kp-chips`, KARIOS generates small image patches (chips) centered on key points for visual inspection and quality assessment. +When called with `--generate-kp-chips`, KARIOS generates small image patches (chips) centered on key points for visual inspection and quality assessment. ```bash karios process monitored.tif reference.tif --generate-kp-chips @@ -421,13 +419,13 @@ results/ | `*_chips.vrt` | Virtual raster mosaics for easy visualization in GIS software | :::{note} -- Chips near image boundaries are automatically excluded -- Coordinate pairs (x,y) in filenames refer to the key point location in the reference image -- Chips are extracted at the detected displacement location in the monitored image -- VRT files enable easy visualization of all chips as a single mosaic in QGIS or similar tools +- Chips near image boundaries are automatically excluded. +- Coordinate pairs (x,y) in filenames refer to the key point location in the reference image. +- Chips are extracted at the detected displacement location in the monitored image. +- VRT files enable easy visualization of all chips as a single mosaic in QGIS or similar tools. ::: -## KLT param leverage +## KLT parameters leverage ### maxCorners & tile_size @@ -435,23 +433,23 @@ In order to have a lower memory usage during KLT process, it is possible to defi For example, a tile_size of 10000 for an image having a size of 20000 x 20000 pixels will result in 4 tiles to process. -In this context, the KLT process will look in each tile for `maxCorners`. +In this context, the KLT process will look into each tile for `maxCorners`. While an image of 20000 x 20000 pixels results in 4 equals tiles, an image of 20000 x 15000 pixels will also result in 4 tiles, but with different size, two of 10000 x 10000 pixels and two of 10000 x 5000 pixels. -The consequence is that the density for matching point will not be the same each tile, the bigger tiles will have a lower matching point density than the smallest. +The consequence is that the density for matching points will not be the same for each tile, the bigger tiles will have a lower matching point density than the smaller. -You should also consider that the image can contain empty parts where KLT will not find any matching point. So tiles having large empty parts will also results in a higher matching point density. +You should also consider that the image can contain empty parts where KLT will not find any matching point. So tiles having large empty parts will also result in a higher matching point density. -In order to avoid density differences in the final result, you can define a `tile_size` larger than the image with a high `maxCorners`, or a small `tile_size` and `maxCorners` in order to have tiles with almost same size. +In order to avoid density differences in the final result, you can define a `tile_size` larger than the image with a high `maxCorners`, or a small `tile_size` and `maxCorners` in order to have tiles with almost the same size. -For example, for image of 20000 x 15000 pixels, you should consider a `tile_size` of 20000 (1 tile), or 5000 (12 equal tiles) +For example, for an image of 20000 x 15000 pixels, you should consider a `tile_size` of 20000 (1 tile), or 5000 (12 equal tiles). ## About shift by altitude plot This output uses box plot to show statistics of KP on altitudes groups. -_The box extends from the first quartile (Q1) to the third quartile (Q3) of the data, with a line at the median. The whiskers extend from the box to the farthest data point lying within 1.5x the inter-quartile range (IQR) from the box. Flier points are those past the end of the whiskers. See https://en.wikipedia.org/wiki/Box_plot for reference._ +_The box extends from the first quartile (Q1) to the third quartile (Q3) of the data, with a line at the median. The whiskers extend from the box to the farthest data point lying within 1.5x the inter-quartile range (IQR) from the box. Flier points are those past the end of the whiskers. See [Box plot documentation [RD-12]](rd-12) for reference._ ``` Q1-1.5IQR Q1 median Q3 Q3+1.5IQR @@ -462,7 +460,6 @@ flier <-----------> fliers IQR ``` -> credits https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html ## Input Data Relationships @@ -511,7 +508,7 @@ KariosException: Monitored image geo info not compatible with reference image KariosException: Mask geo info not compatible with monitored image ``` -**Solution**: Ensure mask has the same geometry as monitored image +**Solution**: Ensure mask has the same geometry as monitored image. ### Performance Optimization @@ -531,7 +528,7 @@ KariosException: Mask geo info not compatible with monitored image ### Large Shift Detection -When enabled with `--enable-large-shift-detection`, KARIOS can detect and compensate for large pixel offsets between images: +When called with `--enable-large-shift-detection`, KARIOS can detect and compensate for large pixel offsets between images: ```bash karios process monitored.tif reference.tif --enable-large-shift-detection @@ -544,7 +541,7 @@ karios process monitored.tif reference.tif --enable-large-shift-detection - Detection of systematic offsets :::{important} -Experimental feature that may use significant memory for large images. +This is still an experimental feature that may use significant memory for large images. ::: ### Resume Functionality diff --git a/site/source/references.md b/site/source/references.md index e816f73..a0c90a5 100644 --- a/site/source/references.md +++ b/site/source/references.md @@ -1,5 +1,69 @@ # References -```{todo} -Define content -``` \ No newline at end of file +(rd-01)= +## RD‑01 +Christopher J. Crawford and Al, «The 50-year Landsat collection 2 archive, Science of Remote Sensing ». Science of Remote +Sensing, Volume 8, 2023, [Article link](https://doi.org/10.1016/j.srs.2023.100103) + +(rd-02)= +## RD‑02 +* ESA Systematic Landsat Archive Processing (SLAP) project : [Webpage link](https://earth.esa.int/eogateway/activities/slap) +* S. Saunier, «Bulk processing of the Landsat MSS/TM/ETM+ archive of the European Space Agency: an insight into the level 1 +MSS processing». Proceeding of Image and Signal Processing for Remote Sensing XXIII, J. A. Benediktsson, Warsaw, Poland: SPIE, oct. +2017, p. 1. [Article link](https://doi.org/10.1117/12.2278633) + +(rd-03)= +## RD‑03 +S. Saunier et al., « European Space agency (ESA) Landsat MSS/TM/ETM+/OLI archive: 42 years of our history ». Proceeding of +multi temporal Conference (Brugge, Belgium), june 2017. [Article link](http://ieeexplore.ieee.org/document/8035252) + +(rd-04)= +## RD‑04 +CEOS Analysis Ready Data For Land – Product Family Specification, Surface Reflectance, v5.0, December 2020, +[PDF link](https://ceos.org/ard/files/PFS/SR/v5.0/CARD4L_Product_Family_Specification_Surface_Reflectance-v5.0.pdf) + +(rd-05)= +## RD‑05 +ESA Landsat : [Online Catalogue link](https://landsat-diss.eo.esa.int/socat/LandsatMSS) + +(rd-06)= +## RD‑06 +Yan, L., et D.P. Roy, «Improving Landsat Multispectral Scanner (MSS) Geolocation by Least-Squares-Adjustment Based Time- +Series Co-Registration». Remote Sensing of Environment 252: 112181. [Article link](https://doi.org/10.1016/j.rse.2020.112181) + +(rd-07)= +## RD‑07 +S. Saunier et al., On the use of Radial Basis Functions to improve geometric accuracy of the ESA Landsat MSS historical archive. +VH RODA 2024, [Article link](https://zenodo.org/records/14960373) + +(rd-08)= +## RD‑08 +EDAP Webpage : +[Link](https://earth.esa.int/eogateway/activities/edap) + +(rd-09)= +## RD‑09 +Kanade–Lucas–Tomasi : [Wikipedia link](https://en.wikipedia.org/wiki/Kanade%E2%80%93Lucas%E2%80%93Tomasi_feature_tracker) + +(rd-10)= +## RD‑10 +PROBA-1 performance specifications : [Link](https://www.eoportal.org/satellite-missions/proba-1#performance-specifications) + +(rd-11)= +## RD‑11 +ESA Landsat Archive: [Online Archive link](https://landsat-diss.eo.esa.int/oads/access/collection/LandsatMSS) + +(rd-12)= +## RD‑12 +* Box_plot: [Box plot link](https://en.wikipedia.org/wiki/Box_plot) +* Matplot lib Box_plot: [Box plot matplotlib link](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.boxplot.html) + \ No newline at end of file diff --git a/site/source/statistical_report.PNG b/site/source/statistical_report.PNG new file mode 100644 index 0000000..39f685e Binary files /dev/null and b/site/source/statistical_report.PNG differ diff --git a/site/source/welcome.md b/site/source/welcome.md index 7b1a608..ba0fc6d 100644 --- a/site/source/welcome.md +++ b/site/source/welcome.md @@ -1,28 +1,72 @@ ```{rst-class} font-weight-bold big-font -Python application based on KLT Algorithm for Registration of Images from Observing Systems (KARIOS). Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Python application based on KLT Algorithm for Registration of Images from Observing Systems (KARIOS). ``` -# Case studies +# Introduction -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +In general, quality assessment processes are fundamental to appreciate how well data is fit for Earth Observation application purposes. Those assessments dedicated to geometric accuracy are rarely open to community. As a consequence, it is difficult to inter-compare data based on the same processes and compare results based on harmonized mapping accuracy metrics. -Visit [Case studies page](case_study/index) +To overcome this situation, thanks to funding of [ESA / EDAP project [RD-8]](rd-08), the KARIOS initiative has been launched and a user tool is now available. -# Getting started +The KARIOS tool has been designed to analyse geometric deformations within optical and radar images. For this purpose, the tool performs image matching and generate several key graphical representations and compute accuracy statistics. + +Image matching process does not follow traditional approach because it is based on feature point matching (corner). A [KLT implementation [RD-9]](rd-09) available in OpenCV library is used in KARIOS. Also, the candidate point selection is done with GoodFeaturesToTrack function and matching is done with calcOpticalFlowPyrLK function. -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +As shown in the following picture, KARIOS makes KLT algorithm compatible with remote sensing images embedding suitable pre-processing (image filtering) and post-processing (outlier filtering). - +```{figure} algorithm.png +:name: algorithm +:width: 600px -```{todo} -**TO BE REFINED : Install / Limitations / Configure ?** +KARIOS process overview ``` +As an optional and experimental feature, KARIOS has the capability to detect large shifts between images. If a large shift is detected, the monitored image is shifted according to the offsets found, and the KLT matching is applied. + +To enable large shift detection, use --enable-large-shift-detection program argument. Please note that it could use lot of memory in case of large images such as Sentinel2 10 m bands, e.g. 11GB for band B04. + +Furthermore, KARIOS analyses displacements between the two input image grids in both line (along-track) and pixel (across-track) directions, providing user with the three following items: + +```{figure} error_overview.png +:name: error_overview +:width: 600px + +Error overview +``` +```{figure} statistical_report.png +:name: statistical_report +:width: 600px + +Statistical report +``` +```{figure} disparity_map.png +:name: disparity_map +:width: 600px + +Disparity map +``` + +The geometric accuracy report includes the following accuracy metrics, in both directions when relevant: + +* Root Mean Square Error +* Minimum / Maximum Error +* Mean Error +* Standard deviation Error +* Circular Error @90 percentile + +The Circular Error (CE) at the 90% level confidence graphic is used for horizontal accuracy in image products. + +This representation is relevant for images expressed within cartographic system grid. +Thanks to the CE representation, it is straightforward to evaluate mapping accuracy, considering reference data with known accuracy. + +In case of images with no cartographic system grid, the CE graphic representation becomes less informative. +The CE graphic is still generated, and equally spaced sample data is assumed. +This hypothesis is not obvious, when details on image grids are unknown. + +# Getting started + :::::{grid} 1 3 3 3 :gutter: 2 @@ -46,22 +90,27 @@ Install KARIOS. :::{card} {fas}`rocket` Launch :link: quickstart.html#usage -A sample of how to run KARIOS. +A few examples showing how to run KARIOS. ::: :::: ::::: -# Cookbook +# Case studies -Learn how to configure KARIOS to achieve your goal. +This section contains multiple examples of KARIOS usages, featuring different imaging sources (Landsat MSS, PROBA/CHRIS, SKYSAT, ...) showing how to use and analyse the tool's results. -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. +Visit [Case studies page](case_study/index) + + +# Cookbook + +Learn how to understand KARIOS outputs and configure the parameters to achieve your goal. Visit [Case Cookbook page](cookbook/index) # References -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. - Visit [References page](references) + +```{include} ./_includes/endnote.md