Skip to content

Commit

Permalink
EO extension for STAC 1.1
Browse files Browse the repository at this point in the history
  • Loading branch information
@emmanuelmathot
emmanuelmathot committed Nov 13, 2023
1 parent b4f74a3 commit 368b77f
Show file tree
Hide file tree
Showing 5 changed files with 383 additions and 244 deletions.
121 changes: 59 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Electro-Optical Extension Specification

- **Title:** Electro-Optical
- **Identifier:** <https://stac-extensions.github.io/eo/v1.1.0/schema.json>
- **Identifier:** <https://stac-extensions.github.io/eo/v2.0.0/schema.json>
- **Field Name Prefix:** eo
- **Scope:** Item, Collection
- **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Stable
Expand All @@ -11,6 +11,9 @@
This document explains the fields of the Electro-Optical (EO) Extension to the
[SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.

> \[!IMPORTANT]
> From version 2.0.0, the EO extension is only applicable to STAC resources from specification 1.1.0 or earlier.
EO data is considered to be data that represents a snapshot of the Earth for a single date and time. It
could consist of multiple spectral bands in any part of the electromagnetic spectrum. Examples of EO
data include sensors with visible, short-wave and mid-wave IR bands (e.g., the OLI instrument on
Expand All @@ -27,17 +30,30 @@ 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

The fields in the table below can be used in these parts of STAC documents:

| 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 |
- [ ] Catalogs
- [ ] Collections
- [ ] Item Properties (incl. Summaries in Collections)
- [ ] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
- [X] Bands
- [ ] Links

### Additional Field Information
| Field Name | Type | Description |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| eo:cloud_cover | number | Estimate of cloud cover |
| eo:snow_cover | number | Estimate of snow and ice cover |
| 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:description | string | Description to fully explain the band. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
| 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. |

#### eo:bands
*At least one of the fields must be specified.*

### eo:bands

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
Expand All @@ -54,7 +70,7 @@ a defined bands array.
**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.

#### eo:cloud_cover
### 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
Expand All @@ -66,29 +82,10 @@ Estimate of snow and ice covered surfaces as a percentage (0-100) of the entire
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 |
| ------------------- | ------ | ----------- |
| 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. |

*At least one of the fields must be specified.*

#### name

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.

#### 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)
`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%,
Expand All @@ -100,27 +97,27 @@ referred to as a "top-hat" filter due to it's shape, but does not exist in reali
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
[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.
Expand All @@ -134,28 +131,28 @@ 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 | |
| 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
Expand All @@ -168,13 +165,13 @@ to provide clients with more information about the assets in an item. The follow
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

Expand Down
88 changes: 44 additions & 44 deletions examples/collection.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.1.0/schema.json"
"https://stac-extensions.github.io/eo/v2.0.0/schema.json"
],
"stac_version": "1.0.0",
"description": "A simple Collection demonstrating EO extension fields in a Collection.",
Expand Down Expand Up @@ -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
}
]
},
Expand All @@ -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
}
]
},
Expand All @@ -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
}
]
}
Expand Down
Loading

0 comments on commit 368b77f

Please sign in to comment.