add details & example with 'eo:bands' for special JSON schema conside…

…ration (relates to stac-extensions/eo#12)"
crim-ca · Apr 4, 2024 · 03e7e06 · 03e7e06
1 parent 269bd73
commit 03e7e06
Show file tree

Hide file tree

Showing 6 changed files with 577 additions and 108 deletions.
diff --git a/README.md b/README.md
@@ -226,6 +226,21 @@ representing bands information, including notably the `nodata` value,
 the `data_type` (see also [Data Type Enum](#data-type-enum)),
 and [Common Band Names][stac-band-names].
 
+> [!NOTE]
+> Due to how the schema for [`eo:bands`][stac-eo-band] is defined, it is not sufficient to *only* provide
+> the `eo:bands` property at the STAC Item level. The schema validation of the EO extension explicitly looks
+> for a corresponding set of bands under an Asset, and if none is found, it disallows `eo:bands` in the Item properties.
+> Therefore, `eo:bands` should either be specified *only* under the Asset containing the `mlm:model` role
+> (see [Model Asset](#model-asset)), or define them *both* under the Asset and Item properties. If the second
+> approach is selected, it is recommended that the `eo:bands` under the Asset contains only the `name` or the
+> `common_name` property, such that all other details about the bands are defined at the Item level.
+> <br><br>
+> For more details, refer to [stac-extensions/eo#12](https://github.com/stac-extensions/eo/issues/12).
+> <br>
+> For an example, please refer to [examples/example_eo_bands.json](examples/example_eo_bands.json).
+> Notably in this example, the `assets.weights.eo:bands` property provides the `name` to fulfill the Asset requirement,
+> while all additional band details are provided in `properties.eo:bands`.
+
 Only bands used as input to the model should be included in the MLM `bands` field.
 To avoid duplicating the information, MLM only uses the `name` of whichever "Band Object" is defined in the STAC Item.
 

diff --git a/examples/example.json b/examples/example.json
@@ -2,8 +2,9 @@
   "stac_version": "1.0.0",
   "stac_extensions": [
     "https://stac-extensions.github.io/mlm/v1.0.0/schema.json",
-    "https://stac-extensions.github.io/eo/v1.1.0/schema.json",
-    "https://stac-extensions.github.io/raster/v1.1.0/schema.json"
+    "https://stac-extensions.github.io/raster/v1.1.0/schema.json",
+    "https://stac-extensions.github.io/file/v1.0.0/schema.json",
+    "https://stac-extensions.github.io/ml-aoi/v0.2.0/schema.json"
   ],
   "type": "Feature",
   "id": "resnet-18_sentinel-2_all_moco_classification",
@@ -41,6 +42,7 @@
     58.21798141355221
   ],
   "properties": {
+    "description": "Sourced from torchgeo python library, identifier is ResNet18_Weights.SENTINEL2_ALL_MOCO",
     "datetime": null,
     "start_datetime": "1900-01-01T00:00:00Z",
     "end_datetime": "9999-12-31T23:59:59Z",
@@ -50,11 +52,10 @@
     ],
     "mlm:framework": "pytorch",
     "mlm:framework_version": "2.1.2+cu121",
-    "mlm:file_size": 43000000,
+    "file:size": 43000000,
     "mlm:memory_size": 1,
     "mlm:total_parameters": 11700000,
     "mlm:pretrained_source": "EuroSat Sentinel-2",
-    "mlm:summary": "Sourced from torchgeo python library, identifier is ResNet18_Weights.SENTINEL2_ALL_MOCO",
     "mlm:accelerator": "cuda",
     "mlm:accelerator_constrained": false,
     "mlm:accelerator_summary": "Unknown",
@@ -243,99 +244,6 @@
         "post_processing_function": null
       }
     ],
-    "eo:bands": [
-      {
-        "name": "coastal",
-        "common_name": "coastal",
-        "description": "Coastal aerosol (band 1)",
-        "center_wavelength": 0.443,
-        "full_width_half_max": 0.027
-      },
-      {
-        "name": "blue",
-        "common_name": "blue",
-        "description": "Blue (band 2)",
-        "center_wavelength": 0.49,
-        "full_width_half_max": 0.098
-      },
-      {
-        "name": "green",
-        "common_name": "green",
-        "description": "Green (band 3)",
-        "center_wavelength": 0.56,
-        "full_width_half_max": 0.045
-      },
-      {
-        "name": "red",
-        "common_name": "red",
-        "description": "Red (band 4)",
-        "center_wavelength": 0.665,
-        "full_width_half_max": 0.038
-      },
-      {
-        "name": "rededge1",
-        "common_name": "rededge",
-        "description": "Red edge 1 (band 5)",
-        "center_wavelength": 0.704,
-        "full_width_half_max": 0.019
-      },
-      {
-        "name": "rededge2",
-        "common_name": "rededge",
-        "description": "Red edge 2 (band 6)",
-        "center_wavelength": 0.74,
-        "full_width_half_max": 0.018
-      },
-      {
-        "name": "rededge3",
-        "common_name": "rededge",
-        "description": "Red edge 3 (band 7)",
-        "center_wavelength": 0.783,
-        "full_width_half_max": 0.028
-      },
-      {
-        "name": "nir",
-        "common_name": "nir",
-        "description": "NIR 1 (band 8)",
-        "center_wavelength": 0.842,
-        "full_width_half_max": 0.145
-      },
-      {
-        "name": "nir08",
-        "common_name": "nir08",
-        "description": "NIR 2 (band 8A)",
-        "center_wavelength": 0.865,
-        "full_width_half_max": 0.033
-      },
-      {
-        "name": "nir09",
-        "common_name": "nir09",
-        "description": "NIR 3 (band 9)",
-        "center_wavelength": 0.945,
-        "full_width_half_max": 0.026
-      },
-      {
-        "name": "cirrus",
-        "common_name": "cirrus",
-        "description": "SWIR - Cirrus (band 10)",
-        "center_wavelength": 1.375,
-        "full_width_half_max": 0.026
-      },
-      {
-        "name": "swir16",
-        "common_name": "swir16",
-        "description": "SWIR 1 (band 11)",
-        "center_wavelength": 1.61,
-        "full_width_half_max": 0.143
-      },
-      {
-        "name": "swir22",
-        "common_name": "swir22",
-        "description": "SWIR 2 (band 12)",
-        "center_wavelength": 2.19,
-        "full_width_half_max": 0.242
-      }
-    ],
     "raster:bands": [
       {
         "name": "coastal",
@@ -458,15 +366,16 @@
     {
       "rel": "derived_from",
       "href": "https://earth-search.aws.element84.com/v1/collections/sentinel-2-l2a",
-      "type": "application/json"
+      "type": "application/json",
+      "ml-aoi:split": "train"
     }
   ],
   "assets": {
     "weights": {
       "href": "https://huggingface.co/torchgeo/resnet18_sentinel2_all_moco/resolve/main/resnet18_sentinel2_all_moco-59bfdff9.pth",
       "title": "Pytorch weights checkpoint",
       "description": "A Resnet-18 classification model trained on normalized Sentinel-2 imagery with Eurosat landcover labels with torchgeo",
-      "type": ".pth",
+      "type": "application/octet-stream; application=pytorch",
       "roles": [
         "mlm:model",
         "mlm:weights"
@@ -476,7 +385,7 @@
       "href": "https://github.com/microsoft/torchgeo/blob/61efd2e2c4df7ebe3bd03002ebbaeaa3cfe9885a/torchgeo/models/resnet.py#L207",
       "title": null,
       "description": null,
-      "type": null,
+      "type": "text/x-python",
       "roles": [
         "mlm:model",
         "code",