From 32f144b674c842a858c19b23e30c1393b717a456 Mon Sep 17 00:00:00 2001
From: Matthias Mohr <webmaster@mamo-net.de>
Date: Tue, 27 Aug 2024 23:43:25 +0200
Subject: [PATCH] Deprecate percentages in favor of statistics
---
CHANGELOG.md | 12 ++++++++++++
README.md | 29 +++++++++++++++++------------
examples/item.json | 28 +++++++++++++++-------------
examples/item2.json | 26 ++++++++++++++------------
json-schema/schema.json | 12 ------------
5 files changed, 58 insertions(+), 49 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 939e76a..ecf2309 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `s2:snow_ice_percentage` in favor of `eo:snow_cover`
- `s2:generation_time` in favor of `processing:datetime`
- `s2:processing_baseline` in favor of `processing:version`
+- `s2:water_percentage` in favor of an entry in `statistics`
+- `s2:vegetation_percentage` in favor of an entry in `statistics`
+- `s2:thin_cirrus_percentage` in favor of an entry in `statistics`
+- `s2:cloud_shadow_percentage` in favor of an entry in `statistics`
+- `s2:nodata_pixel_percentage` in favor of an entry in `statistics`
+- `s2:unclassified_percentage` in favor of an entry in `statistics`
+- `s2:dark_features_percentage` in favor of an entry in `statistics`
+- `s2:not_vegetated_percentage` in favor of an entry in `statistics`
+- `s2:degraded_msi_data_percentage` in favor of an entry in `statistics`
+- `s2:high_proba_clouds_percentage` in favor of an entry in `statistics`
+- `s2:medium_proba_clouds_percentage` in favor of an entry in `statistics`
+- `s2:saturated_defective_pixel_percentage` in favor of an entry in `statistics`
### Removed
diff --git a/README.md b/README.md
index d2506c9..8de156c 100644
--- a/README.md
+++ b/README.md
@@ -39,18 +39,18 @@ The fields in the table below can be used in these parts of STAC documents:
| s2:datastrip_id | string | Datastrip Identifier |
| s2:datatake_type | string | Datatake Type |
| s2:reflectance_conversion_factor | number | Reflectance Conversion Factor |
-| s2:water_percentage | number | Water Percentage |
-| s2:vegetation_percentage | number | Vegetation Percentage |
-| s2:thin_cirrus_percentage | number | Thin Cirrus Percentage |
-| s2:cloud_shadow_percentage | number | Cloud Shadow Percentage |
-| s2:nodata_pixel_percentage | number | No Data Pixel Percentage |
-| s2:unclassified_percentage | number | Unclassified Percentage |
-| s2:dark_features_percentage | number | Dark Features Percentage |
-| s2:not_vegetated_percentage | number | Not Vegetated Percentage |
-| s2:degraded_msi_data_percentage | number | Degraded MSI Data Percentage |
-| s2:high_proba_clouds_percentage | number | High Probability Clouds Percentage |
-| s2:medium_proba_clouds_percentage | number | Medium Probability Clouds Percentage |
-| s2:saturated_defective_pixel_percentage | number | Saturated Defective Pixel Percentage |
+| s2:water_percentage | number | **DEPRECATED** in favor of `statistics`. Water Percentage |
+| s2:vegetation_percentage | number | **DEPRECATED** in favor of `statistics`. Vegetation Percentage |
+| s2:thin_cirrus_percentage | number | **DEPRECATED** in favor of `statistics`. Thin Cirrus Percentage |
+| s2:cloud_shadow_percentage | number | **DEPRECATED** in favor of `statistics`. Cloud Shadow Percentage |
+| s2:nodata_pixel_percentage | number | **DEPRECATED** in favor of `statistics`. No Data Pixel Percentage |
+| s2:unclassified_percentage | number | **DEPRECATED** in favor of `statistics`. Unclassified Percentage |
+| s2:dark_features_percentage | number | **DEPRECATED** in favor of `statistics`. Dark Features Percentage |
+| s2:not_vegetated_percentage | number | **DEPRECATED** in favor of `statistics`. Not Vegetated Percentage |
+| s2:degraded_msi_data_percentage | number | **DEPRECATED** in favor of `statistics`. Degraded MSI Data Percentage |
+| s2:high_proba_clouds_percentage | number | **DEPRECATED** in favor of `statistics`. High Probability Clouds Percentage |
+| s2:medium_proba_clouds_percentage | number | **DEPRECATED** in favor of `statistics`. Medium Probability Clouds Percentage |
+| s2:saturated_defective_pixel_percentage | number | **DEPRECATED** in favor of `statistics`. Saturated Defective Pixel Percentage |
| s2:product_type | string | **DEPRECATED** in favor of `product:type`. Product Type |
| s2:snow_ice_percentage | number | **DEPRECATED** in favor of `eo:snow_cover`. Snow and Ice Percentage |
| s2:generation_time | datetime | **DEPRECATED** in favor of `processing:datetime`. Generation Time |
@@ -60,6 +60,11 @@ The fields in the table below can be used in these parts of STAC documents:
| s2:mean_solar_zenith | number | **DEPRECATED** in favor of `view:sun_elevation`. Mean Solar Zenith |
| s2:mean_solar_azimuth | number | **DEPRECATED** in favor of `view:sun_azimuth`. Mean Solar Azimuth |
+The fields with the `_percentage` suffix should be provided in the `statistics` field as defined in
+[common metadata](https://github.com/radiantearth/stac-spec/blob/dev/commons/common-metadata.md#statistics-object).
+Ideally remove the `s2:` prefix and the `_percentage` suffix and use the remainders as the key name in the Statistics Object,
+so for example `high_proba_clouds` instead of `s2:high_proba_clouds_percentage`.
+
## Relation types
None
diff --git a/examples/item.json b/examples/item.json
index 9dd29fa..19bb970 100644
--- a/examples/item.json
+++ b/examples/item.json
@@ -714,21 +714,23 @@
"s2:datatake_type": "INS-NOBS",
"processing:datetime": "2023-11-07T18:21:59.14490Z",
"sat:relative_orbit": 139,
- "s2:water_percentage": 95.782292,
"eo:snow_cover": 0,
"processing:version": "05.09",
- "s2:vegetation_percentage": 0,
- "s2:thin_cirrus_percentage": 0.774645,
- "s2:cloud_shadow_percentage": 0,
- "s2:nodata_pixel_percentage": 99.062872,
- "s2:unclassified_percentage": 0,
- "s2:dark_features_percentage": 0,
- "s2:not_vegetated_percentage": 0.000708,
- "s2:degraded_msi_data_percentage": 0,
- "s2:high_proba_clouds_percentage": 0.699942,
- "s2:reflectance_conversion_factor": 1.01678413954947,
- "s2:medium_proba_clouds_percentage": 2.742413,
- "s2:saturated_defective_pixel_percentage": 0
+ "statistics": {
+ "water": 95.782292,
+ "vegetation": 0,
+ "thin_cirrus": 0.774645,
+ "cloud_shadow": 0,
+ "nodata_pixel": 99.062872,
+ "unclassified": 0,
+ "dark_features": 0,
+ "not_vegetated": 0.000708,
+ "degraded_msi_data": 0,
+ "high_proba_clouds": 0.699942,
+ "reflectance_conversion_factor": 1.01678413954947,
+ "medium_proba_clouds": 2.742413,
+ "saturated_defective_pixel": 0
+ }
},
"stac_extensions": [
"https://stac-extensions.github.io/sentinel-2/v1.0.0/schema.json",
diff --git a/examples/item2.json b/examples/item2.json
index f3f002d..2524799 100644
--- a/examples/item2.json
+++ b/examples/item2.json
@@ -44,18 +44,20 @@
"s2:datastrip_id": "S2A_OPER_MSI_L2A_DS_ESRI_20201007T160858_S20190212T192646_N02.12",
"s2:tile_id": "S2A_OPER_MSI_L2A_TL_ESRI_20201007T160858_A019029_T07HFE_N02.12",
"s2:reflectance_conversion_factor": 1.02763689829235,
- "s2:degraded_msi_data_percentage": 0,
- "s2:nodata_pixel_percentage": 96.769553,
- "s2:saturated_defective_pixel_percentage": 0,
- "s2:dark_features_percentage": 0,
- "s2:cloud_shadow_percentage": 0,
- "s2:vegetation_percentage": 0.000308,
- "s2:not_vegetated_percentage": 0.069531,
- "s2:water_percentage": 48.349833,
- "s2:unclassified_percentage": 0,
- "s2:medium_proba_clouds_percentage": 14.61311,
- "s2:high_proba_clouds_percentage": 24.183494,
- "s2:thin_cirrus_percentage": 12.783723,
+ "statistics": {
+ "degraded_msi_data": 0,
+ "nodata_pixel": 96.769553,
+ "saturated_defective_pixel": 0,
+ "dark_features": 0,
+ "cloud_shadow": 0,
+ "vegetation": 0.000308,
+ "not_vegetated": 0.069531,
+ "water": 48.349833,
+ "unclassified": 0,
+ "medium_proba_clouds": 14.61311,
+ "high_proba_clouds": 24.183494,
+ "thin_cirrus": 12.783723
+ },
"datetime": "2019-02-12T19:26:51.024000Z"
},
"geometry": {
diff --git a/json-schema/schema.json b/json-schema/schema.json
index 602fa89..cfb45af 100644
--- a/json-schema/schema.json
+++ b/json-schema/schema.json
@@ -57,18 +57,6 @@
{ "required": ["s2:product_uri"] },
{ "required": ["s2:datastrip_id"] },
{ "required": ["s2:datatake_type"] },
- { "required": ["s2:water_percentage"] },
- { "required": ["s2:vegetation_percentage"] },
- { "required": ["s2:thin_cirrus_percentage"] },
- { "required": ["s2:cloud_shadow_percentage"] },
- { "required": ["s2:nodata_pixel_percentage"] },
- { "required": ["s2:unclassified_percentage"] },
- { "required": ["s2:dark_features_percentage"] },
- { "required": ["s2:not_vegetated_percentage"] },
- { "required": ["s2:degraded_msi_data_percentage"] },
- { "required": ["s2:high_proba_clouds_percentage"] },
- { "required": ["s2:medium_proba_clouds_percentage"] },
- { "required": ["s2:saturated_defective_pixel_percentage"] },
{ "required": ["s2:reflectance_conversion_factor"] }
]
},