From 82a701e8ae1e617399ed9d4e58aaeb495ea7611d Mon Sep 17 00:00:00 2001 From: torse Date: Thu, 19 Jan 2023 12:08:32 +0100 Subject: [PATCH 01/10] Add eo:snow_cover definition (#9) Co-authored-by: hein_to Co-authored-by: Matthias Mohr --- CHANGELOG.md | 1 + README.md | 6 ++++++ examples/item.json | 5 +++-- json-schema/schema.json | 8 +++++++- 4 files changed, 17 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 155f1cb..1245122 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added `solar_illumination` field for the solar illumination value of the asset. +`eo:snow_cover` field for the snow cover value of the entire scene. ### Changed diff --git a/README.md b/README.md index 188277e..6e70e31 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,12 @@ Estimate of cloud cover as a percentage (0-100) of the entire scene. If not avai this value should be used in Item Properties rather than Item Assets, as an Item from an electro-optical source is a single snapshot of the Earth, so the cloud cover value would apply to all assets. +#### eo:snow_cover + +Estimate of snow and ice covered surfaces as a percentage (0-100) of the entire scene. If not available, the field should not be provided. Generally, +this value should be used in Item Properties rather than Item Assets, as an Item from an electro-optical source is a single snapshot +of the Earth, so the snow cover value would apply to all assets. + ### Band Object | Field Name | Type | Description | diff --git a/examples/item.json b/examples/item.json index a8381c9..f70d9cd 100644 --- a/examples/item.json +++ b/examples/item.json @@ -47,7 +47,8 @@ "cool_sensor_v1" ], "gsd": 0.66, - "eo:cloud_cover": 1.2 + "eo:cloud_cover": 1.2, + "eo:snow_cover": 0 }, "links": [], "assets": { @@ -126,4 +127,4 @@ ] } } -} \ No newline at end of file +} diff --git a/json-schema/schema.json b/json-schema/schema.json index a4aee57..7cb0a24 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -126,6 +126,12 @@ "minimum": 0, "maximum": 100 }, + "eo:snow_cover": { + "title": "Snow and Ice Cover", + "type": "number", + "minimum": 0, + "maximum": 100 + }, "eo:bands": { "$ref": "#/definitions/bands" } @@ -186,4 +192,4 @@ } } } -} \ No newline at end of file +} From f576a82d29af033d4d1aa3bdb4e6399fbdfd6589 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 19 Jan 2023 12:11:51 +0100 Subject: [PATCH 02/10] Improve JSON Schema (#21) --- CHANGELOG.md | 8 ++++++-- json-schema/schema.json | 14 +++++++++++--- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1245122..4568623 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,17 +8,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -`solar_illumination` field for the solar illumination value of the asset. -`eo:snow_cover` field for the snow cover value of the entire scene. +- `solar_illumination` field for the solar illumination value of the band. +- `eo:snow_cover` field for the snow and ice cover value of the entire scene. ### Changed +- Defined minimum values for `center_wavelength` and `full_width_half_max` (> 0) + ### Deprecated ### Removed ### Fixed +- Added `description` to the JSON Schema. + ## [v1.0.0] - 2021-03-30 Initial independent release, see [previous history](https://github.com/radiantearth/stac-spec/commits/v1.0.0-rc.2/extensions/eo) diff --git a/json-schema/schema.json b/json-schema/schema.json index 7cb0a24..fb269a9 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -176,17 +176,25 @@ "lwir12" ] }, + "description": { + "title": "Description of the band", + "type": "string", + "minLength": 1 + }, "center_wavelength": { "title": "Center Wavelength", - "type": "number" + "type": "number", + "minimumExclusive": 0 }, "full_width_half_max": { "title": "Full Width Half Max (FWHM)", - "type": "number" + "type": "number", + "minimumExclusive": 0 }, "solar_illumination": { "title": "Solar Illumination", - "type": "number" + "type": "number", + "minimum": 0 } } } From b9d903722a2f413756f4d697531677d7f1eb9b0a Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 19 Jan 2023 12:29:27 +0100 Subject: [PATCH 03/10] Improve examples #6 #10 (#23) * Added collection example #6 * Fixed wavelength and FWHM values in the examples #10 --- CHANGELOG.md | 3 + README.md | 1 + examples/collection.json | 166 +++++++++++++++++++++++++++++++++++++++ examples/item.json | 52 ++++++++---- 4 files changed, 206 insertions(+), 16 deletions(-) create mode 100644 examples/collection.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 4568623..0a72c18 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `solar_illumination` field for the solar illumination value of the band. - `eo:snow_cover` field for the snow and ice cover value of the entire scene. +- Example for a Collection ### Changed @@ -21,6 +22,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- Updated Item example to STAC v1.0.0 +- Fixed wavelength and FWHM values in the examples - Added `description` to the JSON Schema. ## [v1.0.0] - 2021-03-30 diff --git a/README.md b/README.md index 6e70e31..38b851d 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ with the EO extension, to provide information about the platform (satellite, aer For defining view geometry of data, it is strongly recommended to use the [`view` extension](https://github.com/stac-extensions/view). - Examples: + - [Collection example](examples/collection.json) - [Item example](examples/item.json) - [JSON Schema](json-schema/schema.json) - [Changelog](./CHANGELOG.md) diff --git a/examples/collection.json b/examples/collection.json new file mode 100644 index 0000000..96f251e --- /dev/null +++ b/examples/collection.json @@ -0,0 +1,166 @@ +{ + "id": "eo-collection", + "type": "Collection", + "stac_extensions": [ + "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json", + "https://stac-extensions.github.io/eo/v1.0.0/schema.json" + ], + "stac_version": "1.0.0", + "description": "A simple Collection demonstrating EO extension fields in a Collection.", + "title": "Simple EO Collection", + "extent": { + "spatial": { + "bbox": [ + [ + 172.91173669923782, + 1.3438851951615003, + 172.95469614953714, + 1.3690476620161975 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2020-12-11T22:38:32.125Z", + "2020-12-14T18:02:31.437Z" + ] + ] + } + }, + "license": "CC-BY-4.0", + "summaries": { + "platform": [ + "cool_sat1", + "cool_sat2" + ], + "constellation": [ + "ion" + ], + "instruments": [ + "cool_sensor_v1", + "cool_sensor_v2" + ], + "eo:cloud_cover": { + "minimum": 0, + "maximum": 50 + }, + "eo:bands": [ + { + "name": "band1", + "common_name": "blue", + "center_wavelength": 0.47, + "full_width_half_max": 0.07, + "solar_illumination": 1959.66 + }, + { + "name": "band2", + "common_name": "green", + "center_wavelength": 0.56, + "full_width_half_max": 0.08, + "solar_illumination": 1823.24 + }, + { + "name": "band3", + "common_name": "red", + "center_wavelength": 0.645, + "full_width_half_max": 0.09, + "solar_illumination": 1512.06 + }, + { + "name": "band4", + "common_name": "nir", + "center_wavelength": 0.8, + "full_width_half_max": 0.152, + "solar_illumination": 1041.63 + } + ] + }, + "links": [ + { + "rel": "root", + "href": "./collection.json", + "type": "application/json", + "title": "Simple Example Collection" + }, + { + "rel": "item", + "href": "./item.json", + "type": "application/geo+json", + "title": "20201211_223832_CS2" + } + ], + "item_assets": { + "analytic": { + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "4-Band Analytic", + "roles": [ + "data" + ], + "eo:bands": [ + { + "name": "band1", + "common_name": "blue", + "center_wavelength": 0.47, + "full_width_half_max": 0.7, + "solar_illumination": 1959.66 + }, + { + "name": "band2", + "common_name": "green", + "center_wavelength": 0.56, + "full_width_half_max": 0.08, + "solar_illumination": 1823.24 + }, + { + "name": "band3", + "common_name": "red", + "center_wavelength": 0.645, + "full_width_half_max": 0.9, + "solar_illumination": 1512.06 + }, + { + "name": "band4", + "common_name": "nir", + "center_wavelength": 0.8, + "full_width_half_max": 0.152, + "solar_illumination": 1041.63 + } + ] + }, + "thumbnail": { + "title": "Thumbnail", + "type": "image/png", + "roles": [ + "thumbnail" + ] + }, + "visual": { + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "title": "3-Band Visual", + "roles": [ + "visual" + ], + "eo:bands": [ + { + "name": "band3", + "common_name": "red", + "center_wavelength": 0.645, + "full_width_half_max": 0.09 + }, + { + "name": "band2", + "common_name": "green", + "center_wavelength": 0.56, + "full_width_half_max": 0.08 + }, + { + "name": "band1", + "common_name": "blue", + "center_wavelength": 0.47, + "full_width_half_max": 0.07 + } + ] + } + } +} diff --git a/examples/item.json b/examples/item.json index f70d9cd..715ec1e 100644 --- a/examples/item.json +++ b/examples/item.json @@ -1,5 +1,5 @@ { - "stac_version": "1.0.0-rc.1", + "stac_version": "1.0.0", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json" ], @@ -50,7 +50,27 @@ "eo:cloud_cover": 1.2, "eo:snow_cover": 0 }, - "links": [], + "collection": "eo-collection", + "links": [ + { + "rel": "root", + "href": "./collection.json", + "type": "application/json", + "title": "Simple Example Collection" + }, + { + "rel": "parent", + "href": "./collection.json", + "type": "application/json", + "title": "Simple Example Collection" + }, + { + "rel": "collection", + "href": "./collection.json", + "type": "application/json", + "title": "Simple Example Collection" + } + ], "assets": { "analytic": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic.tif", @@ -63,29 +83,29 @@ { "name": "band1", "common_name": "blue", - "center_wavelength": 470, - "full_width_half_max": 70, + "center_wavelength": 0.47, + "full_width_half_max": 0.07, "solar_illumination": 1959.66 }, { "name": "band2", "common_name": "green", - "center_wavelength": 560, - "full_width_half_max": 80, + "center_wavelength": 0.56, + "full_width_half_max": 0.08, "solar_illumination": 1823.24 }, { "name": "band3", "common_name": "red", - "center_wavelength": 645, - "full_width_half_max": 90, + "center_wavelength": 0.645, + "full_width_half_max": 0.09, "solar_illumination": 1512.06 }, { "name": "band4", "common_name": "nir", - "center_wavelength": 800, - "full_width_half_max": 152, + "center_wavelength": 0.8, + "full_width_half_max": 0.152, "solar_illumination": 1041.63 } ] @@ -109,20 +129,20 @@ { "name": "band3", "common_name": "red", - "center_wavelength": 645, - "full_width_half_max": 90 + "center_wavelength": 0.645, + "full_width_half_max": 0.09 }, { "name": "band2", "common_name": "green", - "center_wavelength": 560, - "full_width_half_max": 80 + "center_wavelength": 0.56, + "full_width_half_max": 0.08 }, { "name": "band1", "common_name": "blue", - "center_wavelength": 470, - "full_width_half_max": 70 + "center_wavelength": 0.47, + "full_width_half_max": 0.07 } ] } From 892f0210e6d8e0a2dcc919f1d951b04e8bd995e1 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sat, 28 Jan 2023 13:33:37 +0100 Subject: [PATCH 04/10] Add missing eo:snow_cover to table --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 38b851d..f28adf6 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ For defining view geometry of data, it is strongly recommended to use the [`view | -------------- | ------------------------------ | ----------- | | eo:bands | \[[Band Object](#band-object)] | An array of available bands where each object is a [Band Object](#band-object). If given, requires at least one band. | | eo:cloud_cover | number | Estimate of cloud cover | +| eo:snow_cover | number | Estimate of snow and ice cover | ### Additional Field Information From 0aaf8e499065c85b00098cdfaa2f9547b1de2f0e Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 10 Feb 2023 16:35:00 +0100 Subject: [PATCH 05/10] Update version number to v1.1.0 for the next release (#24) --- CHANGELOG.md | 9 ++++----- README.md | 2 +- examples/collection.json | 2 +- examples/item.json | 2 +- json-schema/schema.json | 4 ++-- package.json | 6 +++--- 6 files changed, 12 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a72c18..a8e0d79 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [v1.1.0] - 2023-02-08 + ### Added - `solar_illumination` field for the solar illumination value of the band. @@ -16,10 +18,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Defined minimum values for `center_wavelength` and `full_width_half_max` (> 0) -### Deprecated - -### Removed - ### Fixed - Updated Item example to STAC v1.0.0 @@ -34,5 +32,6 @@ Initial independent release, see [previous history](https://github.com/radiantea - `common_name` is validated as an enum (no other values allowed) -[Unreleased]: +[Unreleased]: +[v1.1.0]: [v1.0.0]: diff --git a/README.md b/README.md index f28adf6..8a2ce2a 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Electro-Optical Extension Specification - **Title:** Electro-Optical -- **Identifier:** +- **Identifier:** - **Field Name Prefix:** eo - **Scope:** Item, Collection - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Stable diff --git a/examples/collection.json b/examples/collection.json index 96f251e..2ac841f 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -3,7 +3,7 @@ "type": "Collection", "stac_extensions": [ "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json", - "https://stac-extensions.github.io/eo/v1.0.0/schema.json" + "https://stac-extensions.github.io/eo/v1.1.0/schema.json" ], "stac_version": "1.0.0", "description": "A simple Collection demonstrating EO extension fields in a Collection.", diff --git a/examples/item.json b/examples/item.json index 715ec1e..4c61901 100644 --- a/examples/item.json +++ b/examples/item.json @@ -1,7 +1,7 @@ { "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/eo/v1.0.0/schema.json" + "https://stac-extensions.github.io/eo/v1.1.0/schema.json" ], "type": "Feature", "id": "20201211_223832_CS2", diff --git a/json-schema/schema.json b/json-schema/schema.json index fb269a9..415fc86 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://stac-extensions.github.io/eo/v1.0.0/schema.json#", + "$id": "https://stac-extensions.github.io/eo/v1.1.0/schema.json#", "title": "EO Extension", "description": "STAC EO Extension for STAC Items.", "oneOf": [ @@ -112,7 +112,7 @@ "stac_extensions": { "type": "array", "contains": { - "const": "https://stac-extensions.github.io/eo/v1.0.0/schema.json" + "const": "https://stac-extensions.github.io/eo/v1.1.0/schema.json" } } } diff --git a/package.json b/package.json index feffca7..1bc9818 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,11 @@ { "name": "stac-extensions", - "version": "1.0.0", + "version": "1.1.0", "scripts": { "test": "npm run check-markdown && npm run check-examples", "check-markdown": "remark . -f -r .github/remark.yaml", - "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/eo/v1.0.0/schema.json=./json-schema/schema.json", - "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/eo/v1.0.0/schema.json=./json-schema/schema.json" + "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/eo/v1.1.0/schema.json=./json-schema/schema.json", + "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/eo/v1.1.0/schema.json=./json-schema/schema.json" }, "dependencies": { "remark-cli": "^8.0.0", From b4f74a350c6ced21d63217d2adb45eeb5096089e Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 10 Feb 2023 16:36:51 +0100 Subject: [PATCH 06/10] Update release date --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a8e0d79..69fb881 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -## [v1.1.0] - 2023-02-08 +## [v1.1.0] - 2023-02-10 ### Added From 3e5c9239a74276feaf49efa5274c252e977f9ebc Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 21 Dec 2023 14:56:25 +0100 Subject: [PATCH 07/10] Clarify unit for coverages in table --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8a2ce2a..20722a4 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,8 @@ For defining view geometry of data, it is strongly recommended to use the [`view | Field Name | Type | Description | | -------------- | ------------------------------ | ----------- | | eo:bands | \[[Band Object](#band-object)] | An array of available bands where each object is a [Band Object](#band-object). If given, requires at least one band. | -| eo:cloud_cover | number | Estimate of cloud cover | -| eo:snow_cover | number | Estimate of snow and ice cover | +| eo:cloud_cover | number | Estimate of cloud cover, in % | +| eo:snow_cover | number | Estimate of snow and ice cover, in % | ### Additional Field Information From 81bb3b13dfed92e1a2d8776b2c9fe5f23e28a3ec Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Mon, 8 Jul 2024 13:17:42 +0200 Subject: [PATCH 08/10] EO extension for STAC 1.1 (#29) * EO extension for STAC 1.1 Co-authored-by: Matthias Mohr --- CHANGELOG.md | 22 +++ README.md | 183 +++++++++++----------- examples/collection.json | 86 +++++------ examples/item.json | 57 +++---- json-schema/schema.json | 324 ++++++++++++++++++++++----------------- 5 files changed, 365 insertions(+), 307 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 69fb881..5c3e1df 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- `eo:cloud_cover` and `eo:snow_cover` can be used in bands +- `eo:common_name`, `eo:center_wavelength`, `eo:full_width_half_max` and `eo:solar_illumination` can be used in Assets and Item Properties + +### Changed + +- `eo:bands` is now using the more general `bands` construct from STAC common metadata +- The following fields in the Band Object have been moved/renamed: + - `name` was *not* renamed, but has been moved to STAC common metadata + - `description` was *not* renamed, but has been moved to STAC common metadata + - `common_name` has been renamed to `eo:common_name` + - `center_wavelength` has been renamed to `eo:center_wavelength` + - `full_width_half_max` has been renamed to `eo:full_width_half_max` + - `solar_illumination` has been renamed to `eo:solar_illumination` +- The bands in Item Properties are not meant to be the union of the asset bands any longer + You usually don't list bands in Item Properties any longer unless all assets have the same bands. + +### Removed + +- `eo:bands` - use `bands` instead + ## [v1.1.0] - 2023-02-10 ### Added diff --git a/README.md b/README.md index 20722a4..21574ee 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,10 @@ could consist of multiple spectral bands in any part of the electromagnetic spec data include sensors with visible, short-wave and mid-wave IR bands (e.g., the OLI instrument on Landsat-8), long-wave IR bands (e.g. TIRS aboard Landsat-8). -It is strongly recommended to use [Instrument Fields](https://github.com/radiantearth/stac-spec/tree/master/item-spec/common-metadata.md#instrument) +It is strongly recommended to use [Instrument Fields](https://github.com/radiantearth/stac-spec/tree/master/item-spec/common-metadata.md#instrument) with the EO extension, to provide information about the platform (satellite, aerial, etc) used to capture the images. -For defining view geometry of data, it is strongly recommended to use the [`view` extension](https://github.com/stac-extensions/view). +For defining view geometry of data, it is strongly recommended to use the [View Extension](https://github.com/stac-extensions/view). - Examples: - [Collection example](examples/collection.json) @@ -27,100 +27,96 @@ For defining view geometry of data, it is strongly recommended to use the [`view - [JSON Schema](json-schema/schema.json) - [Changelog](./CHANGELOG.md) -## Item Properties or Asset Fields +## Fields -| Field Name | Type | Description | -| -------------- | ------------------------------ | ----------- | -| eo:bands | \[[Band Object](#band-object)] | An array of available bands where each object is a [Band Object](#band-object). If given, requires at least one band. | -| eo:cloud_cover | number | Estimate of cloud cover, in % | -| eo:snow_cover | number | Estimate of snow and ice cover, in % | +The fields in the table below can be used in these parts of STAC documents: -### Additional Field Information +- [ ] Catalogs +- [ ] Collections +- [x] Item Properties (incl. Summaries in Collections) +- [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections) +- [x] Bands +- [ ] Links -#### eo:bands +| Field Name | Type | Description | +| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| eo:cloud_cover | number | Estimate of cloud cover, in %. | +| eo:snow_cover | number | Estimate of snow and ice cover, in %. | +| eo:common_name | string | The name commonly used to refer to the band to make it easier to search for bands across instruments. See the [list of accepted common names](#common-band-names). | +| eo:center_wavelength | number | The center wavelength of the band, in micrometers (μm). | +| eo:full_width_half_max | number | Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm). | +| eo:solar_illumination | number | The solar illumination of the band, as measured at half the maximum transmission, in W/m2/micrometers. | -The `eo:bands` array is used to describe the available [spectral -bands](https://www.sciencedirect.com/topics/earth-and-planetary-sciences/spectral-band) in an Asset. This enables clients to read -the file and understand which band is 'red' and which is 'nir' (near infrared) so that it can perform an -[NDVI](https://en.wikipedia.org/wiki/Normalized_difference_vegetation_index) operation, for example. Each Asset should specify -its own band object. If the individual bands are repeated in different assets they should all use the same values and -include the optional [`name`](#name) field to enable clients to easily combine and summarize the bands. - -The `eo:bands` array may optionally be used in the Item Properties to summarize the available bands in the assets. This should -be a 'union' of all the possible bands represented in assets. It should be considered merely informative - clients should rely -on the `eo:bands` of each asset. An Item is only allowed to use `eo:bands` in its Properties if it has at least one asset with -a defined bands array. +*At least one of the fields must be specified.* -**NOTE**: In STAC versions 0.9.x and prior, `eo:bands` could only be used by an Asset putting the Band Object definitions in -an Item Properties and referencing these via array index. 1.0.0-beta.1 introduced the current behavior. +### Coverages #### eo:cloud_cover -Estimate of cloud cover as a percentage (0-100) of the entire scene. If not available, the field should not be provided. Generally, -this value should be used in Item Properties rather than Item Assets, as an Item from an electro-optical source is a single snapshot -of the Earth, so the cloud cover value would apply to all assets. - -#### eo:snow_cover - -Estimate of snow and ice covered surfaces as a percentage (0-100) of the entire scene. If not available, the field should not be provided. Generally, -this value should be used in Item Properties rather than Item Assets, as an Item from an electro-optical source is a single snapshot -of the Earth, so the snow cover value would apply to all assets. +Estimate of cloud cover as a percentage (0-100) of the entire scene. If not available, the field should not be provided. Generally, +this value should be used in Item Properties rather than Item Assets, as an Item from an electro-optical source is a single snapshot +of the Earth, so the cloud cover value would apply to all assets. -### Band Object +##### eo:snow_cover -| Field Name | Type | Description | -| ------------------- | ------ | ----------- | -| name | string | The name of the band (e.g., "B01", "B8", "band2", "red"). | -| common_name | string | The name commonly used to refer to the band to make it easier to search for bands across instruments. See the [list of accepted common names](#common-band-names). | -| description | string | Description to fully explain the band. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| center_wavelength | number | The center wavelength of the band, in micrometers (μm). | -| full_width_half_max | number | Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm). | -| solar_illumination | number | The solar illumination of the band, as measured at half the maximum transmission, in W/m2/micrometers. | +Estimate of snow and ice covered surfaces as a percentage (0-100) of the entire scene. If not available, the field should not be provided. Generally, +this value should be used in Item Properties rather than Item Assets, as an Item from an electro-optical source is a single snapshot +of the Earth, so the snow cover value would apply to all assets. -*At least one of the fields must be specified.* +### Spectral Bands -#### name +> \[!NOTE] +> This extension formerly had a field `eo:bands`, which has been removed in favor of a general field `bands` +> in STAC common metadata. The structure is the same, it's an array of Band Objects. +> The fields in the Band Object may change, fields from the EO extension will have a `eo:` prefix, but some more +> general fields like `description` have been moved to common metadata and don't need a prefix and as such don't change. +> Please note that bands in Item Properties are not the union of all bands in the assets any longer. +> If you specify bands in the Item Properties, the bands apply to all assets unless you have a bands object at the asset level. -This is typically the name the data provider uses for the band. It should be treated like an 'id', to identify that a particular -band used in several assets represents the same band (all the other fields should be the same as well). It is also recommended that -clients use this name for display, potentially in conjunction with the common name. +The presence of one of the `eo:` fields in a Band Object makes the band +"[spectral](https://www.sciencedirect.com/topics/earth-and-planetary-sciences/spectral-band)". +This enables clients to read the file and understand which band is 'red' and which is 'nir' (near infrared) so that it can perform an +[NDVI](https://en.wikipedia.org/wiki/Normalized_difference_vegetation_index) operation, for example. +Each Asset should specify its own band object. +If the individual bands are repeated in different assets they should all use the same values and +include the optional bands `name` field to enable clients to easily combine and summarize the bands. -#### center_wavelength and full_width_half_max +#### eo:center_wavelength and eo:full_width_half_max -These fields are a common way to approximately describe a spectral band. In most cases even these numbers are not as useful as the -`common_name` that should be supplied with the spectral bands, where they exist. For non-standard bands (such as with hyperspectral sensors) +These fields are a common way to approximately describe a spectral band. In most cases even these numbers are not as useful as the +`eo:common_name` that should be supplied with the spectral bands, where they exist. For non-standard bands (such as with hyperspectral sensors) the wavelength fields indicate where the band is. -Another common way to define a spectral band with a minimum and maximum wavelength, where outside these bounds the transmission is 0%, -and non-zero inside the bounds (e.g., 80%). The maximum transmission of a band is not captured in any of these metrics, +Another common way to define a spectral band with a minimum and maximum wavelength, where outside these bounds the transmission is 0%, +and non-zero inside the bounds (e.g., 80%). The maximum transmission of a band is not captured in any of these metrics, nor is it important in most cases. -However, spectral transmission for a filter does not go from 0% to a constant max value (e.g., 80%) then back to 0%. Such a filter is -referred to as a "top-hat" filter due to it's shape, but does not exist in reality. Thus, the minimum and maximum wavelengths are -typically selected to be the point at which transmission drops below some threshold, and this threshold is often half of the maximum +However, spectral transmission for a filter does not go from 0% to a constant max value (e.g., 80%) then back to 0%. Such a filter is +referred to as a "top-hat" filter due to it's shape, but does not exist in reality. Thus, the minimum and maximum wavelengths are +typically selected to be the point at which transmission drops below some threshold, and this threshold is often half of the maximum transmission. Thus if a filter's maximum transmission is 80%, the min and max thresholds would be the points where the transmission drops below 40%. -The `center_wavelength` of a band is the midpoint between the min and max wavelengths: +The `eo:center_wavelength` of a band is the midpoint between the min and max wavelengths: ```python center_wavelength = (min_wavelength + max_wavelength) / 2 ``` -The `full_width_half_max` (FWHM) is the difference between the min and max wavelengths, +The `eo:full_width_half_max` (FWHM) is the difference between the min and max wavelengths, thus representing the width of the band at half it's maximum transmission. ```python full_width_half_max = max_wavelength - min_wavelength ``` -For example, if we were given a band described as (0.4um - 0.5um) the `center_wavelength` would be 0.45um -and the `full_width_half_max` would be 0.1um. +For example, if we were given a band described as (0.4um - 0.5um) the `eo:center_wavelength` would be 0.45um +and the `eo:full_width_half_max` would be 0.1um. In some cases the full transmission profile is needed, such as when harmonizing between two sensor modalities. It is recommended - that the full spectral profile be included as a link or an asset (preferably at the + that the full spectral profile be included as a link or an asset (preferably at the [Collection](https://github.com/radiantearth/stac-spec/tree/master/collection-spec/collection-spec.md) level). -#### solar_illumination +#### eo:solar_illumination In satellite-based remote sensing applications, the calibration of the sensor recorded top-of-atmosphere reflectance to radiance, or vice-versa, is carried out using a reference spectral solar irradiance value. @@ -134,47 +130,47 @@ For instance, this value is used for optical calibration of an asset (e.g. [ESUN #### Common Band Names -The band's `common_name` is the name that is commonly used to refer to that band's spectral +The band's `eo:common_name` is the name that is commonly used to refer to that band's spectral properties. The table below shows the allowed common names based on the average band range for the band numbers of several popular instruments. -| Common Name | Band Range (μm) | Landsat 5/7 | Landsat 8 | Sentinel 2 | MODIS | NAIP | -| ----------- | --------------- | ----------- | --------- | ---------- | ----- | ---- | -| coastal | 0.40 - 0.45 | | 1 | 1 | | | -| blue | 0.45 - 0.50 | 1 | 2 | 2 | 3 | 3 | -| green | 0.50 - 0.60 | 2 | 3 | 3 | 4 | 2 | -| red | 0.60 - 0.70 | 3 | 4 | 4 | 1 | 1 | -| yellow | 0.58 - 0.62 | | | | | | -| pan | 0.50 - 0.70 | 8 (*L7 only*) | 8 | | | | -| rededge | 0.70 - 0.79 | | | 5, 6, 7 | | | -| nir | 0.75 - 1.00 | 4 | | 8 | 2 | 4 | -| nir08 | 0.75 - 0.90 | | 5 | 8a | | | -| nir09 | 0.85 - 1.05 | | | 9 | | | -| cirrus | 1.35 - 1.40 | | 9 | 10 | 26 | | -| swir16 | 1.55 - 1.75 | 5 | 6 | 11 | 6 | | -| swir22 | 2.10 - 2.30 | 7 | 7 | 12 | 7 | | -| lwir | 10.5 - 12.5 | 6 | | | | | -| lwir11 | 10.5 - 11.5 | | 10 | | 31 | | -| lwir12 | 11.5 - 12.5 | | 11 | | 32 | | - -The difference between the `nir`, `nir08`, and `nir09` bands are that the `nir` band is a wider band that covers -most of the spectral range of 0.75μm to 1.0μm. `nir08` and `nir09` are narrow bands centered 0.85μm and 0.95μm +| Common Name | Band Range (μm) | Landsat 5/7 | Landsat 8 | Sentinel 2 | MODIS | NAIP | +| ----------- | --------------- | ------------- | --------- | ---------- | ----- | ---- | +| coastal | 0.40 - 0.45 | | 1 | 1 | | | +| blue | 0.45 - 0.50 | 1 | 2 | 2 | 3 | 3 | +| green | 0.50 - 0.60 | 2 | 3 | 3 | 4 | 2 | +| red | 0.60 - 0.70 | 3 | 4 | 4 | 1 | 1 | +| yellow | 0.58 - 0.62 | | | | | | +| pan | 0.50 - 0.70 | 8 (*L7 only*) | 8 | | | | +| rededge | 0.70 - 0.79 | | | 5, 6, 7 | | | +| nir | 0.75 - 1.00 | 4 | | 8 | 2 | 4 | +| nir08 | 0.75 - 0.90 | | 5 | 8a | | | +| nir09 | 0.85 - 1.05 | | | 9 | | | +| cirrus | 1.35 - 1.40 | | 9 | 10 | 26 | | +| swir16 | 1.55 - 1.75 | 5 | 6 | 11 | 6 | | +| swir22 | 2.10 - 2.30 | 7 | 7 | 12 | 7 | | +| lwir | 10.5 - 12.5 | 6 | | | | | +| lwir11 | 10.5 - 11.5 | | 10 | | 31 | | +| lwir12 | 11.5 - 12.5 | | 11 | | 32 | | + +The difference between the `nir`, `nir08`, and `nir09` bands are that the `nir` band is a wider band that covers +most of the spectral range of 0.75μm to 1.0μm. `nir08` and `nir09` are narrow bands centered 0.85μm and 0.95μm respectively. The same goes for the difference between `lwir`, `lwir11` and `lwir12`. ## Best Practices One of the emerging best practices is to use [Asset Roles](https://github.com/radiantearth/stac-spec/tree/master/item-spec/item-spec.md#asset-roles) -to provide clients with more information about the assets in an item. The following list includes a shared vocabulary for some common EO assets. +to provide clients with more information about the assets in an item. The following list includes a shared vocabulary for some common EO assets. This list should not be considered definitive, and implementors are welcome to use other asset roles. If consensus and tooling consolidates around these role names then they will be specified in the future as more standard than just 'best practices'. -| Role Name | Description | -| --------- | ---------------------------------------------------------------------- | -| reflectance | An asset the provides [reflectance](https://www.l3harrisgeospatial.com/Support/Self-Help-Tools/Help-Articles/Help-Articles-Detail/ArtMID/10220/ArticleID/19247/3377) values, instead of just radiance. | -| temperature | An asset that provides actual temperature measurements. | -| saturation | Points to a file that indicates where pixels in the input spectral bands are saturated. | -| cloud | Points to a file that indicates whether a pixel is assessed as being cloud | -| cloud-shadow | Points to a file that indicates whether a pixel is assessed as being cloud shadow. | +| Role Name | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| reflectance | An asset the provides [reflectance](https://www.l3harrisgeospatial.com/Support/Self-Help-Tools/Help-Articles/Help-Articles-Detail/ArtMID/10220/ArticleID/19247/3377) values, instead of just radiance. | +| temperature | An asset that provides actual temperature measurements. | +| saturation | Points to a file that indicates where pixels in the input spectral bands are saturated. | +| cloud | Points to a file that indicates whether a pixel is assessed as being cloud | +| cloud-shadow | Points to a file that indicates whether a pixel is assessed as being cloud shadow. | ## Contributing @@ -186,16 +182,18 @@ for running tests are copied here for convenience. ### Running tests -The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. +The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need `npm`, which is a standard part of any [node.js installation](https://nodejs.org/en/download/). -First you'll need to install everything with npm once. Just navigate to the root of this repository and on +First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run: + ```bash npm install ``` Then to check markdown formatting and test the examples against the JSON schema, you can run: + ```bash npm test ``` @@ -203,6 +201,7 @@ npm test This will spit out the same texts that you see online, and you can then go and fix your markdown or examples. If the tests reveal formatting problems with the examples, you can fix them with: + ```bash npm run format-examples ``` diff --git a/examples/collection.json b/examples/collection.json index 2ac841f..797e49f 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -45,34 +45,34 @@ "minimum": 0, "maximum": 50 }, - "eo:bands": [ + "bands": [ { "name": "band1", - "common_name": "blue", - "center_wavelength": 0.47, - "full_width_half_max": 0.07, - "solar_illumination": 1959.66 + "eo:common_name": "blue", + "eo:center_wavelength": 0.47, + "eo:full_width_half_max": 0.07, + "eo:solar_illumination": 1959.66 }, { "name": "band2", - "common_name": "green", - "center_wavelength": 0.56, - "full_width_half_max": 0.08, - "solar_illumination": 1823.24 + "eo:common_name": "green", + "eo:center_wavelength": 0.56, + "eo:full_width_half_max": 0.08, + "eo:solar_illumination": 1823.24 }, { "name": "band3", - "common_name": "red", - "center_wavelength": 0.645, - "full_width_half_max": 0.09, - "solar_illumination": 1512.06 + "eo:common_name": "red", + "eo:center_wavelength": 0.645, + "eo:full_width_half_max": 0.09, + "eo:solar_illumination": 1512.06 }, { "name": "band4", - "common_name": "nir", - "center_wavelength": 0.8, - "full_width_half_max": 0.152, - "solar_illumination": 1041.63 + "eo:common_name": "nir", + "eo:center_wavelength": 0.8, + "eo:full_width_half_max": 0.152, + "eo:solar_illumination": 1041.63 } ] }, @@ -97,34 +97,34 @@ "roles": [ "data" ], - "eo:bands": [ + "bands": [ { "name": "band1", - "common_name": "blue", - "center_wavelength": 0.47, - "full_width_half_max": 0.7, - "solar_illumination": 1959.66 + "eo:common_name": "blue", + "eo:center_wavelength": 0.47, + "eo:full_width_half_max": 0.7, + "eo:solar_illumination": 1959.66 }, { "name": "band2", - "common_name": "green", - "center_wavelength": 0.56, - "full_width_half_max": 0.08, - "solar_illumination": 1823.24 + "eo:common_name": "green", + "eo:center_wavelength": 0.56, + "eo:full_width_half_max": 0.08, + "eo:solar_illumination": 1823.24 }, { "name": "band3", "common_name": "red", - "center_wavelength": 0.645, - "full_width_half_max": 0.9, - "solar_illumination": 1512.06 + "eo:center_wavelength": 0.645, + "eo:full_width_half_max": 0.9, + "eo:solar_illumination": 1512.06 }, { "name": "band4", - "common_name": "nir", - "center_wavelength": 0.8, - "full_width_half_max": 0.152, - "solar_illumination": 1041.63 + "eo:common_name": "nir", + "eo:center_wavelength": 0.8, + "eo:full_width_half_max": 0.152, + "eo:solar_illumination": 1041.63 } ] }, @@ -141,24 +141,24 @@ "roles": [ "visual" ], - "eo:bands": [ + "bands": [ { "name": "band3", - "common_name": "red", - "center_wavelength": 0.645, - "full_width_half_max": 0.09 + "eo:common_name": "red", + "eo:center_wavelength": 0.645, + "eo:full_width_half_max": 0.09 }, { "name": "band2", - "common_name": "green", - "center_wavelength": 0.56, - "full_width_half_max": 0.08 + "eo:common_name": "green", + "eo:center_wavelength": 0.56, + "eo:full_width_half_max": 0.08 }, { "name": "band1", - "common_name": "blue", - "center_wavelength": 0.47, - "full_width_half_max": 0.07 + "eo:common_name": "blue", + "eo:center_wavelength": 0.47, + "eo:full_width_half_max": 0.07 } ] } diff --git a/examples/item.json b/examples/item.json index 4c61901..98794a3 100644 --- a/examples/item.json +++ b/examples/item.json @@ -79,34 +79,35 @@ "roles": [ "data" ], - "eo:bands": [ + "eo:cloud_cover": 1.2, + "bands": [ { "name": "band1", - "common_name": "blue", - "center_wavelength": 0.47, - "full_width_half_max": 0.07, - "solar_illumination": 1959.66 + "eo:common_name": "blue", + "eo:center_wavelength": 0.47, + "eo:full_width_half_max": 0.07, + "eo:solar_illumination": 1959.66 }, { "name": "band2", - "common_name": "green", - "center_wavelength": 0.56, - "full_width_half_max": 0.08, - "solar_illumination": 1823.24 + "eo:common_name": "green", + "eo:center_wavelength": 0.56, + "eo:full_width_half_max": 0.08, + "eo:solar_illumination": 1823.24 }, { "name": "band3", - "common_name": "red", - "center_wavelength": 0.645, - "full_width_half_max": 0.09, - "solar_illumination": 1512.06 + "eo:common_name": "red", + "eo:center_wavelength": 0.645, + "eo:full_width_half_max": 0.09, + "eo:solar_illumination": 1512.06 }, { "name": "band4", - "common_name": "nir", - "center_wavelength": 0.8, - "full_width_half_max": 0.152, - "solar_illumination": 1041.63 + "eo:common_name": "nir", + "eo:center_wavelength": 0.8, + "eo:full_width_half_max": 0.152, + "eo:solar_illumination": 1041.63 } ] }, @@ -125,26 +126,26 @@ "roles": [ "visual" ], - "eo:bands": [ + "bands": [ { "name": "band3", - "common_name": "red", - "center_wavelength": 0.645, - "full_width_half_max": 0.09 + "eo:common_name": "red", + "eo:center_wavelength": 0.645, + "eo:full_width_half_max": 0.09 }, { "name": "band2", - "common_name": "green", - "center_wavelength": 0.56, - "full_width_half_max": 0.08 + "eo:common_name": "green", + "eo:center_wavelength": 0.56, + "eo:full_width_half_max": 0.08 }, { "name": "band1", - "common_name": "blue", - "center_wavelength": 0.47, - "full_width_half_max": 0.07 + "eo:common_name": "blue", + "eo:center_wavelength": 0.47, + "eo:full_width_half_max": 0.07 } ] } } -} +} \ No newline at end of file diff --git a/json-schema/schema.json b/json-schema/schema.json index 415fc86..eb1e639 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -3,116 +3,170 @@ "$id": "https://stac-extensions.github.io/eo/v1.1.0/schema.json#", "title": "EO Extension", "description": "STAC EO Extension for STAC Items.", + "type": "object", + "required": [ + "stac_extensions" + ], + "properties": { + "stac_extensions": { + "type": "array", + "contains": { + "const": "https://stac-extensions.github.io/eo/v1.1.0/schema.json" + } + } + }, "oneOf": [ { "$comment": "This is the schema for STAC Items.", - "allOf": [ - { + "type": "object", + "required": [ + "type", + "properties", + "assets" + ], + "properties": { + "type": { + "const": "Feature" + }, + "properties": { + "$ref": "#/definitions/fields" + }, + "assets": { "type": "object", - "required": [ - "type", - "properties", - "assets" - ], + "additionalProperties": { + "$ref": "#/definitions/fields" + } + } + }, + "anyOf": [ + { "properties": { - "type": { - "const": "Feature" - }, "properties": { - "$ref": "#/definitions/fields" - }, - "assets": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } - } - }, - "$comment": "The if-then-else below checks whether the eo:bands is given in assets or not. If yes, allows eo:bands in properties (else), otherwise, disallows eo:bands in properties (then).", - "if": { - "required": [ - "assets" - ], - "properties": { - "assets": { - "type": "object", - "additionalProperties": { - "properties": { - "eo:bands": false - } - } - } - } - }, - "then": { - "properties": { - "properties": { - "properties": { - "eo:bands": false - } - } - } - }, - "else": { - "properties": { - "properties": { - "properties": { - "eo:bands": { - "$ref": "#/definitions/bands" - } - } - } + "$ref": "#/definitions/require_any" } } }, { - "$ref": "#/definitions/stac_extensions" + "$ref": "#/definitions/require_in_assets" } ] }, { "$comment": "This is the schema for STAC Collections.", - "allOf": [ + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Collection" + }, + "assets": { + "$ref": "#/definitions/fields" + }, + "item_assets": { + "$ref": "#/definitions/fields" + } + }, + "anyOf": [ + { + "$ref": "#/definitions/require_in_item_assets" + }, + { + "$ref": "#/definitions/require_in_assets" + }, { - "type": "object", - "required": [ - "type" - ], "properties": { - "type": { - "const": "Collection" - }, - "assets": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } - }, - "item_assets": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } + "summaries": { + "$ref": "#/definitions/require_any" } } - }, - { - "$ref": "#/definitions/stac_extensions" } ] } ], "definitions": { - "stac_extensions": { - "type": "object", + "require_any": { + "anyOf": [ + { + "required": [ + "eo:cloud_cover" + ] + }, + { + "required": [ + "eo:snow_cover" + ] + }, + { + "required": [ + "eo:common_name" + ] + }, + { + "required": [ + "eo:center_wavelength" + ] + }, + { + "required": [ + "eo:full_width_half_max" + ] + }, + { + "required": [ + "eo:solar_illumination" + ] + }, + { + "$ref": "#/definitions/require_in_bands" + } + ] + }, + "require_in_bands": { "required": [ - "stac_extensions" + "bands" ], "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "const": "https://stac-extensions.github.io/eo/v1.1.0/schema.json" + "bands": { + "not": { + "additionalProperties": { + "not": { + "$ref": "#/definitions/require_any" + } + } + } + } + } + }, + "require_in_assets": { + "required": [ + "assets" + ], + "properties": { + "assets": { + "not": { + "additionalProperties": { + "not": { + "$ref": "#/definitions/require_any" + } + } + } + } + } + }, + "require_in_item_assets": { + "required": [ + "item_assets" + ], + "properties": { + "item_assets": { + "not": { + "additionalProperties": { + "not": { + "$ref": "#/definitions/require_any" + } + } } } } @@ -120,6 +174,12 @@ "fields": { "type": "object", "properties": { + "bands": { + "type": "array", + "items": { + "$ref": "#/definitions/fields" + } + }, "eo:cloud_cover": { "title": "Cloud Cover", "type": "number", @@ -132,72 +192,48 @@ "minimum": 0, "maximum": 100 }, - "eo:bands": { - "$ref": "#/definitions/bands" + "eo:common_name": { + "title": "Common Name of the band", + "type": "string", + "enum": [ + "coastal", + "blue", + "green", + "red", + "rededge", + "yellow", + "pan", + "nir", + "nir08", + "nir09", + "cirrus", + "swir16", + "swir22", + "lwir", + "lwir11", + "lwir12" + ] + }, + "eo:center_wavelength": { + "title": "Center Wavelength", + "type": "number", + "minimumExclusive": 0 + }, + "eo:full_width_half_max": { + "title": "Full Width Half Max (FWHM)", + "type": "number", + "minimumExclusive": 0 + }, + "eo:solar_illumination": { + "title": "Solar Illumination", + "type": "number", + "minimum": 0 } }, "patternProperties": { "^(?!eo:)": {} }, "additionalProperties": false - }, - "bands": { - "title": "Bands", - "type": "array", - "minItems": 1, - "items": { - "title": "Band", - "type": "object", - "minProperties": 1, - "properties": { - "name": { - "title": "Name of the band", - "type": "string" - }, - "common_name": { - "title": "Common Name of the band", - "type": "string", - "enum": [ - "coastal", - "blue", - "green", - "red", - "rededge", - "yellow", - "pan", - "nir", - "nir08", - "nir09", - "cirrus", - "swir16", - "swir22", - "lwir", - "lwir11", - "lwir12" - ] - }, - "description": { - "title": "Description of the band", - "type": "string", - "minLength": 1 - }, - "center_wavelength": { - "title": "Center Wavelength", - "type": "number", - "minimumExclusive": 0 - }, - "full_width_half_max": { - "title": "Full Width Half Max (FWHM)", - "type": "number", - "minimumExclusive": 0 - }, - "solar_illumination": { - "title": "Solar Illumination", - "type": "number", - "minimum": 0 - } - } - } } } -} +} \ No newline at end of file From 8a2cc4c4829a9b246edb305927c39b17b7a23bcb Mon Sep 17 00:00:00 2001 From: Denis Rykov Date: Mon, 8 Jul 2024 13:29:42 +0200 Subject: [PATCH 09/10] cloud_cover and snow_cover calculation guidelines (#26) * cloud_cover and snow_cover calculation guidelines Co-authored-by: Matthias Mohr --- CHANGELOG.md | 4 ++++ README.md | 20 +++++++++----------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c3e1df..133f05d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `eo:bands` - use `bands` instead +### Fixed + +- Clarified how the coverages `eo:cloud_cover` and `eo:snow_cover` should be computed + ## [v1.1.0] - 2023-02-10 ### Added diff --git a/README.md b/README.md index 21574ee..3342bca 100644 --- a/README.md +++ b/README.md @@ -40,8 +40,8 @@ The fields in the table below can be used in these parts of STAC documents: | Field Name | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| eo:cloud_cover | number | Estimate of cloud cover, in %. | -| eo:snow_cover | number | Estimate of snow and ice cover, in %. | +| eo:cloud_cover | number | Estimate of cloud cover as a percentage (0-100). | +| eo:snow_cover | number | Estimate of snow and ice cover as a percentage (0-100). | | eo:common_name | string | The name commonly used to refer to the band to make it easier to search for bands across instruments. See the [list of accepted common names](#common-band-names). | | eo:center_wavelength | number | The center wavelength of the band, in micrometers (μm). | | eo:full_width_half_max | number | Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm). | @@ -51,17 +51,15 @@ The fields in the table below can be used in these parts of STAC documents: ### Coverages -#### eo:cloud_cover +This extension defines some common coverage types (cloud and snow/ice cover) as a percentages (0-100) of the entire scene: +- `eo:cloud_cover` +- `eo:snow_cover` -Estimate of cloud cover as a percentage (0-100) of the entire scene. If not available, the field should not be provided. Generally, -this value should be used in Item Properties rather than Item Assets, as an Item from an electro-optical source is a single snapshot -of the Earth, so the cloud cover value would apply to all assets. +It is important to consider only the valid data regions, excluding any "nodata" areas while calculating both the coverages. +If such information is not available or can't be calculated, the fields should not be provided. -##### eo:snow_cover - -Estimate of snow and ice covered surfaces as a percentage (0-100) of the entire scene. If not available, the field should not be provided. Generally, -this value should be used in Item Properties rather than Item Assets, as an Item from an electro-optical source is a single snapshot -of the Earth, so the snow cover value would apply to all assets. +Usually, the properties should be used in Item Properties rather than Item Assets, +as an Item from an electro-optical source is a single snapshot of the Earth, so the coverages usually apply to all assets. ### Spectral Bands From 31b43f86e81d123a3161c0f4481f02d094bd2ef4 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 8 Jul 2024 17:07:52 +0200 Subject: [PATCH 10/10] Fix JSON Schema for recent bands PR --- CHANGELOG.md | 7 ++--- json-schema/schema.json | 58 ++++++++++++++--------------------------- 2 files changed, 23 insertions(+), 42 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 133f05d..6bb1ef1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,5 @@ # Changelog + All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), @@ -9,14 +10,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - `eo:cloud_cover` and `eo:snow_cover` can be used in bands -- `eo:common_name`, `eo:center_wavelength`, `eo:full_width_half_max` and `eo:solar_illumination` can be used in Assets and Item Properties +- `eo:common_name`, `eo:center_wavelength`, `eo:full_width_half_max` and `eo:solar_illumination` + can be used in Assets and Item Properties ### Changed - `eo:bands` is now using the more general `bands` construct from STAC common metadata - The following fields in the Band Object have been moved/renamed: - - `name` was *not* renamed, but has been moved to STAC common metadata - - `description` was *not* renamed, but has been moved to STAC common metadata + - `name` and `description` were *not* renamed, but have been moved to STAC common metadata - `common_name` has been renamed to `eo:common_name` - `center_wavelength` has been renamed to `eo:center_wavelength` - `full_width_half_max` has been renamed to `eo:full_width_half_max` diff --git a/json-schema/schema.json b/json-schema/schema.json index eb1e639..4728eb4 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -42,7 +42,7 @@ { "properties": { "properties": { - "$ref": "#/definitions/require_any" + "$ref": "#/definitions/require_any_or_bands" } } }, @@ -78,7 +78,7 @@ { "properties": { "summaries": { - "$ref": "#/definitions/require_any" + "$ref": "#/definitions/require_any_or_bands" } } } @@ -86,55 +86,35 @@ } ], "definitions": { - "require_any": { + "require_any_or_bands": { "anyOf": [ { - "required": [ - "eo:cloud_cover" - ] - }, - { - "required": [ - "eo:snow_cover" - ] - }, - { - "required": [ - "eo:common_name" - ] - }, - { - "required": [ - "eo:center_wavelength" - ] - }, - { - "required": [ - "eo:full_width_half_max" - ] - }, - { - "required": [ - "eo:solar_illumination" - ] + "$ref": "#/definitions/require_any" }, { "$ref": "#/definitions/require_in_bands" } ] }, + "require_any": { + "anyOf": [ + {"required": ["eo:cloud_cover"]}, + {"required": ["eo:snow_cover"]}, + {"required": ["eo:common_name"]}, + {"required": ["eo:center_wavelength"]}, + {"required": ["eo:full_width_half_max"]}, + {"required": ["eo:solar_illumination"]} + ] + }, "require_in_bands": { "required": [ "bands" ], "properties": { "bands": { - "not": { - "additionalProperties": { - "not": { - "$ref": "#/definitions/require_any" - } - } + "type": "array", + "contains": { + "$ref": "#/definitions/require_any" } } } @@ -148,7 +128,7 @@ "not": { "additionalProperties": { "not": { - "$ref": "#/definitions/require_any" + "$ref": "#/definitions/require_any_or_bands" } } } @@ -164,7 +144,7 @@ "not": { "additionalProperties": { "not": { - "$ref": "#/definitions/require_any" + "$ref": "#/definitions/require_any_or_bands" } } }