Merge pull request #516 from philvarner/eo-clarifications

Clarify EO items platform, constellation, and instrument
radiantearth · Aug 8, 2019 · 1b8eb94 · 1b8eb94
2 parents ee026bf + 649178f
commit 1b8eb94
Show file tree

Hide file tree

Showing 10 changed files with 59 additions and 30 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 	- Query parameter `time` was renamed to `datetime` and accepts slightly different values.
 	- WFS links have additional fields `hreflang` and `length`.
 	- WFS Collections have additional fields `crs` and `itemType`.
+- Clarified meaning of SAR and EO platform, constellation, and instrument
 
 ### Added
 

diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md
@@ -156,7 +156,7 @@ An incomplete Collection:
   "properties": {
     "eo:gsd": 30,
     "eo:platform": "landsat-8",
-    "eo:instrument": "OLI_TIRS",
+    "eo:instrument": "oli_tirs",
     "eo:off_nadir": 0,
     "eo:bands": [
       {
@@ -213,7 +213,7 @@ The merged Item then looks like this:
     "eo:gsd": 30,
     "eo:platform": "landsat-8",
     "eo:constellation": "landsat-8",
-    "eo:instrument": "OLI_TIRS",
+    "eo:instrument": "oli_tirs",
     "eo:off_nadir": 0,
     "eo:bands": [
       {

diff --git a/collection-spec/examples/landsat-collection.json b/collection-spec/examples/landsat-collection.json
@@ -53,16 +53,15 @@
       {
         "name": "Development Seed",
         "url": "https://developmentseed.org/",
-        "roles": [
-          "processor"
-        ]
+        "roles": ["processor"]
+        }
       }
     ],
     "license": "PDDL-1.0",
     "properties": {
       "eo:gsd": 30,
       "eo:platform": "landsat-8",
-      "eo:instrument": "OLI_TIRS",
+      "eo:instrument": "oli_tirs",
       "eo:off_nadir": 0,
       "eo:bands": [
         {

diff --git a/extensions/eo/README.md b/extensions/eo/README.md
@@ -26,10 +26,10 @@ The exact metadata that would appear in a STAC Collection record will vary depen
 | Field Name       | Type                     | Description |
 | ---------------- | ------------------------ | ----------- |
 | eo:gsd           | number                   | **REQUIRED.** Ground Sample Distance at the sensor. |
-| eo:platform      | string                   | **REQUIRED.** Unique name of the specific platform the instrument is attached to. For satellites this would be the name of the satellite (e.g., landsat-8, sentinel-2A), whereas for drones this would be a unique name for the drone. |
-| eo:constellation | string                   | Name of the constellation that the platform belongs to. See below for details. |
+| eo:platform      | string                   | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. |
 | eo:instrument    | string                   | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). |
 | eo:bands         | [Band Object]            | **REQUIRED.** This is a list of the available bands where each item is a Band Object. |
+| eo:constellation | string                   | Name of the constellation to which the platform belongs. |
 | eo:epsg          | integer\|null            | [EPSG code](http://www.epsg-registry.org/) of the datasource, `null` if no EPSG code. |
 | eo:cloud_cover   | number                   | Estimate of cloud cover as a percentage (0-100) of the entire scene. If not available the field should not be provided. |
 | eo:off_nadir     | number                   | Viewing angle. The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). |
@@ -48,12 +48,27 @@ PlanetScope Ortho Tile Product has an `eo:gsd` of 3.7 (or 4 if rounding), even t
 3.125.   For example, one might choose for WorldView-2 the 
 Multispectral 20° off-nadir value of 2.07 and for WorldView-3 the Multispectral 20° off-nadir value of 1.38.
 
-**eo:constellation** is the name of the group of satellites that have similar payloads and have their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and radiometric characteristics. Examples are the Sentinel-2 [constellation](https://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Sentinel-2/Satellite_constellation), which has S2A and S2B and RapidEye. This field allows users to search for Sentinel-2 data, for example, without needing to specify which specific platform the data came from.
-
+**eo:platform** is the unique name of the specific platform the instrument is attached to. For satellites this would 
+be the name of the satellite, whereas for drones this would be a unique name for the drone. Examples include 
+`landsat-8` (Landsat-8), `sentinel-2a` and `sentinel-2b` (Sentinel-2), `terra` and `aqua` (part of NASA EOS, 
+carrying the MODIS instruments), `mycorp-uav-034` (hypothetical drone name), and `worldview02` 
+(Maxar/DigitalGlobe WorldView-2).
+
 **eo:instrument** is the name of the sensor used, although for Items which contain data from
 multiple sensors this could also name multiple sensors. For example, data from the Landsat-8
 platform is collected with the OLI sensor as well as the TIRS sensor, but the data is distributed
-together and commonly referred to as OLI_TIRS.
+together and commonly referred to as OLI_TIRS. Examples include `oli_tirs` (Landsat-8), `msi` (Sentinel-2), 
+`aster` (Terra), and `modis` (Terra and Aqua).
+
+**eo:constellation** is the name of a logical collection one or more platforms that have similar payloads and have 
+their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and 
+radiometric characteristics. This field allows users to search for related data sets without needing to specify which 
+specific platform the data came from, for example, from either of the Sentinel-2 satellites. Examples include `landsat-8` 
+(Landsat-8, a constellation consisting of a single platform), `sentinel-2` ([Sentinel-2](https://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Sentinel-2/Satellite_constellation)), 
+`rapideye` (operated by Planet Labs), and `modis` (NASA EOS satellites Aqua and Terra).  In the case of `modis`, this
+is technically referring to a pair of sensors on two different satellites, whose data is combined into a series of 
+related products. Additionally, the Aqua satellite is technically part of the A-Train constellation and Terra is not 
+part of a constellation, but these combine to form the logical collection referred to as MODIS. 
 
 **eo:epsg** - A Coordinate Reference System (CRS) is the native reference system (sometimes called a
 'projection') used by the data, and can usually be referenced using an [EPSG code](http://epsg.io).

diff --git a/extensions/eo/examples/example-landsat8.json b/extensions/eo/examples/example-landsat8.json
@@ -44,7 +44,7 @@
         "landsat:row": 18,
         "eo:gsd": 30,
         "eo:platform": "landsat-8",
-        "eo:instrument": "OLI_TIRS",
+        "eo:instrument": "oli_tirs",
         "eo:off_nadir": 0,
         "eo:bands": [
             {

diff --git a/extensions/sar/README.md b/extensions/sar/README.md
@@ -18,8 +18,8 @@ The exact metadata that would appear in a STAC Collection record will vary depen
 
 | Field Name                | Type          | Description                                                  |
 | ------------------------- | ------------- | ------------------------------------------------------------ |
-| sar:platform              | string        | **REQUIRED.** Unique name of the specific platform the instrument is attached to. For satellites this would be the name of the satellite (e.g., sentinel-1A). |
-| sar:constellation         | string        | Name of the constellation that the platform belongs to. See below for details. |
+| sar:platform              | string        | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. |
+| sar:constellation         | string        | Name of the constellation to which the platform belongs. |
 | sar:instrument            | string        | **REQUIRED.** Name of the sensor used, although for Items which contain data from multiple sensors this could also name multiple sensors. |
 | sar:instrument_mode       | string        | **REQUIRED.** The name of the sensor acquisition mode that is commonly used. This should be the short name, if available. For example, `WV` for "Wave mode" of Sentinel-1 and Envisat ASAR satellites. |
 | sar:frequency_band        | string        | **REQUIRED.** The common name for the frequency band to make it easier to search for bands across instruments. See section "Common Frequency Band Names" for a list of accepted names. |
@@ -41,14 +41,26 @@ The exact metadata that would appear in a STAC Collection record will vary depen
 | sar:relative_orbit        | integer       | A relative orbit number associated with the acquisition. See below for details. |
 | sar:incidence_angle       | number        | The center incidence angle is the angle defined by the incident radar beam at the scene center and the vertical (normal) to the intercepting surface. Measured in degrees (0-90). |
 
-**sar:absolute_orbit** usually corresponds to the number of orbits elapsed since satellite launch (e.g. ALOS, ERS-1/2, JERS-1, RADARSAT-1 and Sentinel-1). For airborne SAR such as UAVSAR it can be the [Flight ID](http://uavsar.jpl.nasa.gov/cgi-bin/data.pl) or a similar concept. The center orbit number should be specified if readily available, otherwise the orbit number at the start of the flight can be used instead.
-
-**sar:relative_orbit** is a count of orbits from 1 to the number of orbits contained in a repeat cycle, where relative orbit 1 starts from a defined reference for a given satellite. This property is usually not set for airborne SAR such as UAVSAR. The center orbit number should be specified if readily available, otherwise the orbit number at the start of the flight can be used instead.
+**sar:platform** is the unique name of the specific platform the instrument is attached to. For satellites this would 
+be the name of the satellite, whereas for drones this would be a unique name for the drone. Examples include `sentinel-1a` (Sentinel-1) and `envisat` (Envisat).
+
+**sar:constellation** is the name of a logical collection one or more platforms that have similar payloads and have 
+their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and 
+radiometric characteristics. This field allows users to search for related data sets without needing to specify from 
+which specific platform the data came. One example is 
+the constellation `sentinel-1` (Sentinel-1) consisting of two satellites Sentinel-1A and Sentinel-1B. If a system 
+consists of only a single satellite, the constellation name is the same as the satellite name, e.g., `envisat` 
+(Envisat). 
 
-**sar:constellation** is the name of the group of satellites that have similar payloads and have their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and radiometric characteristics. Examples are the Sentinel-1 [constellation](https://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Sentinel-1/Satellite_constellation), which has S1A, S1B, S1C and S1D and RADARSAT, which has RADARSAT-1 and RADARSAT-2. This field allows users to search for Sentinel-1 data, for example, without needing to specify which specific platform the data came from.
+**sar:instrument** is the name of the sensor used, although for Items which contain data from multiple sensors this 
+could also name multiple sensors. Examples include `c-sar` (Sentinel-1) and `asar` (Envisat).
 
 **sar:polarization** specifies a single polarization or a polarization combination. For single polarized radars one of `HH`, `VV`, `HV` or `VH` must be set. Fully polarimetric radars add all four polarizations to the array. Dual polarized radars and alternating polarization add the corresponding polarizations to the array, for instance for `HH+HV` add both `HH` and `HV`.
 
+**sar:absolute_orbit** usually corresponds to the number of orbits elapsed since satellite launch (e.g. ALOS, ERS-1/2, JERS-1, RADARSAT-1 and Sentinel-1). For airborne SAR such as UAVSAR it can be the [Flight ID](http://uavsar.jpl.nasa.gov/cgi-bin/data.pl) or a similar concept. The center orbit number should be specified if readily available, otherwise the orbit number at the start of the flight can be used instead.
+
+**sar:relative_orbit** is a count of orbits from 1 to the number of orbits contained in a repeat cycle, where relative orbit 1 starts from a defined reference for a given satellite. This property is usually not set for airborne SAR such as UAVSAR. The center orbit number should be specified if readily available, otherwise the orbit number at the start of the flight can be used instead.
+
 ### Common Frequency Band Names
 
 The `sar:freuency_band` is the name that is commonly used to refer to that band's spectral

diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json
@@ -18,9 +18,9 @@
     "datetime": "2009-05-20T02:40:46.763325Z",
     "dtr:start_datetime": "2009-05-20T02:40:01.042784Z",
     "dtr:end_datetime": "2009-05-20T02:41:31.483865Z",
-    "sar:platform": "Envisat",
-    "sar:constellation": "Envisat",
-    "sar:instrument": "ASAR",
+    "sar:platform": "envisat",
+    "sar:constellation": "envisat",
+    "sar:instrument": "asar",
     "sar:instrument_mode": "GM",
     "sar:polarization": ["HH"],
     "sar:resolution_range": 1000,

diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json
@@ -18,9 +18,9 @@
     "datetime": "2018-11-03T23:58:55.617217Z",
     "dtr:start_datetime": "2018-11-03T23:58:55.121559Z",
     "dtr:end_datetime": "2018-11-03T23:59:55.112875Z",
-    "sar:platform": "Sentinel-1A",
-    "sar:constellation": "Sentinel-1",
-    "sar:instrument": "C-SAR",
+    "sar:platform": "sentinel-1a",
+    "sar:constellation": "sentinel-1",
+    "sar:instrument": "c-sar",
     "sar:instrument_mode": "EW",
     "sar:polarization": ["HH"],
     "sar:resolution_range": 50,

diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json
@@ -68,27 +68,27 @@
     "eo:cloud_cover": 50,
     "eo:off_nadir": 18.4,
     "eo:azimuth": 34.5,
-    "eo:platform": "WORLDVIEW02",
+    "eo:platform": "worldview02",
     "eo:sun_elevation": 33.4,
     "eo:gsd": 2.047,
     "eo:epsg": null,
     "dg:catalog_id": "103001004B316600",
     "dg:soli": "056823192",
     "dg:part": 2,
-    "dg:platform": "WORLDVIEW02",
+    "dg:platform": "worldview02",
     "dg:product_level": "LV1B",
-    "dg:product": "WORLDVIEW02_LV1B",
+    "dg:product": "worldview02_lv1b",
     "datetime": "2015-11-09T18:04:46.000Z"
   },
   "collection": "dg_worldview02",
    "links": [
       {
         "rel": "self",
-        "href": "https://s3.amazonaws.com/digitalglobe-catalog-spec/collections/dg_worldview02_LV1B/103001004B316600_P002_MUL"
+        "href": "https://s3.amazonaws.com/digitalglobe-catalog-spec/collections/dg_worldview02_lv1b/103001004B316600_P002_MUL"
       },
       {
         "rel": "collection",
-        "href": "https://s3.amazonaws.com/digitalglobe-catalog-spec/collections/dg_worldview02_LV1B.json"
+        "href": "https://s3.amazonaws.com/digitalglobe-catalog-spec/collections/dg_worldview02_lv1b.json"
       }
     ]
 }
diff --git a/item-spec/examples/sample-full.json b/item-spec/examples/sample-full.json
@@ -31,7 +31,9 @@
     "eo:sun_azimuth": 168.7,
     "eo:cloud_cover": 0.12,
     "eo:off_nadir": 1.4,
-    "eo:platform": "COOLSAT2",
+    "eo:platform": "coolsat2",
+    "eo:instrument": "cool_sensor_v1",
+    "eo:bands": [],
     "eo:sun_elevation": 33.4,
     "eo:gsd": 0.512,
     "cs:type": "scene",