diff --git a/CHANGELOG.md b/CHANGELOG.md index 328a32624..4e5668c99 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - [Basics](item-spec/common-metadata.md#basics) added to Common Metadata definitions with new `description` field for Item properties. - Clarification text on HTTP verbs in STAC API +- [View Geometry Extension](extensions/view/README.md) ### Changed - Item `title` definition moved from core Item fields to [Common Metadata Basics](item-spec/common-metadata.md#basics) @@ -17,6 +18,13 @@ fields. No change is required for STAC Items. - `putFeature` can return a `PreconditionFailed` to provide more explicit information when the resource has changed in the server - [Sort extension](api-spec/extensions/sort) now uses "+" and "-" prefixes for GET requests to denote sort order. - Clarified how `/search` links must be added to `/` and changed that links to both GET and POST must be provided now that the method can be specified in links. +- Moved angle definitions between extensions `view` and `sat` + - `sat:off_nadir_angle` -> `view:off_nadir` + - `sat:azimuth_angle` -> `view:azimuth` + - `sat:incidence_angle` -> `view:incidence_angle` + - `sat:sun_azimuth_angle` -> `view:sun_azimuth` + - `sat:sun_elevation_angle` -> `view:sun_elevation` + ### Removed diff --git a/api-spec/STAC-extensions.yaml b/api-spec/STAC-extensions.yaml index cabeb5879..b70b97ffe 100644 --- a/api-spec/STAC-extensions.yaml +++ b/api-spec/STAC-extensions.yaml @@ -835,10 +835,10 @@ components: - sentinel-2 instruments: - msi - 'sat:off_nadir_angle': + 'view:off_nadir': min: 0 max: 100 - 'sat:sun_elevation_angle': + 'view:sun_elevation': min: 6.78 max: 89.9 'eo:bands': @@ -1699,6 +1699,7 @@ components: stac_version: 0.9.0-rc1 stac_extensions: - eo + - view - 'https://example.com/cs-extension/1.0/schema.json' type: Feature id: CS3-20160503_132131_05 @@ -1730,14 +1731,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'sat:sun_azimuth_angle': 168.7 + 'view:sun_azimuth': 168.7 'eo:cloud_cover': 0.12 - 'sat:off_nadir_angle': 1.4 + 'view:off_nadir': 1.4 platform: coolsat2 instruments: - cool_sensor_v1 'eo:bands': [] - 'sat:sun_elevation_angle': 33.4 + 'view:sun_elevation': 33.4 'eo:gsd': 0.512 collection: CS3 links: diff --git a/api-spec/STAC.yaml b/api-spec/STAC.yaml index fb5dedb96..edb7fb939 100644 --- a/api-spec/STAC.yaml +++ b/api-spec/STAC.yaml @@ -539,10 +539,10 @@ components: - sentinel-2 instruments: - msi - 'sat:off_nadir_angle': + 'view:off_nadir': min: 0 max: 100 - 'sat:sun_elevation_angle': + 'view:sun_elevation': min: 6.78 max: 89.9 'eo:bands': @@ -1381,6 +1381,7 @@ components: stac_version: 0.9.0-rc1 stac_extensions: - eo + - view - 'https://example.com/cs-extension/1.0/schema.json' type: Feature id: CS3-20160503_132131_05 @@ -1412,14 +1413,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'sat:sun_azimuth_angle': 168.7 + 'view:sun_azimuth': 168.7 'eo:cloud_cover': 0.12 - 'sat:off_nadir_angle': 1.4 + 'view:off_nadir': 1.4 platform: coolsat2 instruments: - cool_sensor_v1 'eo:bands': [] - 'sat:sun_elevation_angle': 33.4 + 'view:sun_elevation': 33.4 'eo:gsd': 0.512 collection: CS3 links: diff --git a/api-spec/openapi/STAC.yaml b/api-spec/openapi/STAC.yaml index 41fdf1603..1d6ddb5c3 100644 --- a/api-spec/openapi/STAC.yaml +++ b/api-spec/openapi/STAC.yaml @@ -340,10 +340,10 @@ components: - sentinel-2 'instruments': - msi - 'sat:off_nadir_angle': + 'view:off_nadir': min: 0 max: 100 - 'sat:sun_elevation_angle': + 'view:sun_elevation': min: 6.78 max: 89.9 'eo:bands': @@ -740,6 +740,7 @@ components: stac_version: 0.9.0-rc1 stac_extensions: - eo + - view - 'https://example.com/cs-extension/1.0/schema.json' type: Feature id: CS3-20160503_132131_05 @@ -771,14 +772,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'sat:sun_azimuth_angle': 168.7 + 'view:sun_azimuth': 168.7 'eo:cloud_cover': 0.12 - 'sat:off_nadir_angle': 1.4 + 'view:off_nadir': 1.4 'platform': coolsat2 'instruments': - cool_sensor_v1 'eo:bands': [] - 'sat:sun_elevation_angle': 33.4 + 'view:sun_elevation': 33.4 'eo:gsd': 0.512 collection: CS3 links: diff --git a/collection-spec/examples/landsat-collection.json b/collection-spec/examples/landsat-collection.json index 8e18ee857..7bff70123 100644 --- a/collection-spec/examples/landsat-collection.json +++ b/collection-spec/examples/landsat-collection.json @@ -1,7 +1,9 @@ { "stac_version": "0.9.0-rc1", "stac_extensions": [ - "commons" + "commons", + "view", + "eo" ], "id": "landsat-8-l1", "title": "Landsat 8 L1", @@ -62,7 +64,7 @@ "properties": { "platform": "landsat-8", "instruments": ["oli", "tirs"], - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:gsd": 30, "eo:bands": [ { diff --git a/collection-spec/examples/landsat-item.json b/collection-spec/examples/landsat-item.json index 000281f73..6a4938551 100644 --- a/collection-spec/examples/landsat-item.json +++ b/collection-spec/examples/landsat-item.json @@ -3,6 +3,7 @@ "stac_extensions": [ "commons", "eo", + "view", "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC08_L1TP_107018_20181001_20181001_01_RT", @@ -44,8 +45,8 @@ "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, "landsat:path": 107, "landsat:row": 18 }, diff --git a/collection-spec/examples/sentinel2.json b/collection-spec/examples/sentinel2.json index efe9e716f..980fcdc04 100644 --- a/collection-spec/examples/sentinel2.json +++ b/collection-spec/examples/sentinel2.json @@ -52,11 +52,11 @@ "platform": ["sentinel-2a","sentinel-2b"], "constellation": ["sentinel-2"], "instruments": ["msi"], - "sat:off_nadir_angle": { + "view:off_nadir": { "min": 0.0, "max": 100 }, - "sat:sun_elevation_angle": { + "view:sun_elevation": { "min": 6.78, "max": 89.9 }, diff --git a/extensions/README.md b/extensions/README.md index a36c45f33..926c6e70e 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -60,6 +60,7 @@ An extension can add new fields to STAC entities (content extension), or can add | [Scientific](scientific/README.md) (`sci`) | Item, Collection | Scientific metadata is considered to be data that indicate from which publication data originates and how the data itself should be cited or referenced. | *Proposal* | | [Single File STAC](single-file-stac/README.md) (-) | ItemCollection | An extension to provide a set of Collections and Items as a single file catalog. | *Proposal* | | [Versioning Indicators](version/README.md) (-) | Item, Collection | Provides fields and link relation types to provide a version and indicate deprecation. | *Proposal* | +| [View Geometry](view/README.md) | Item | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data | *Proposal* | ## Third-party / vendor extensions @@ -113,10 +114,10 @@ An example of this can be seen in a Landsat example: "start_datetime":"2018-01-01T13:21:30Z", "end_datetime":"2018-01-01T13:31:30Z", - "sat:off_nadir_angle": -0.001, + "view:off_nadir": -0.001, "eo:cloud_cover": 10.31, - "sat:sun_azimuth_angle": 149.01607154, - "sat:sun_elevation_angle": 59.21424700, + "view:sun_azimuth": 149.01607154, + "view:sun_elevation": 59.21424700, "eo:gsd": 30, "l8:data_type": "L1T", diff --git a/extensions/asset/examples/example-landsat8.json b/extensions/asset/examples/example-landsat8.json index 03414efe7..b03a9b261 100644 --- a/extensions/asset/examples/example-landsat8.json +++ b/extensions/asset/examples/example-landsat8.json @@ -70,7 +70,7 @@ "oli", "tirs" ], - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", diff --git a/extensions/commons/README.md b/extensions/commons/README.md index a5973920d..92998a201 100644 --- a/extensions/commons/README.md +++ b/extensions/commons/README.md @@ -16,7 +16,7 @@ In **API implementations** the Commons extension should not be used as it leads Unlike other extensions the Commons extension does not add any fields to a STAC Item, instead it allows one to move fields out of Item and into the parent STAC Collection, from which any member Item will inherit. Any field under an Items `properties` field can be removed and added to the Collection `properties` field. Since a Collection contains no properties itself, anything under properties are metadata fields that are common across all member Items. -This provides maximum flexibility to data providers, as the set of common metadata fields can vary between different types of data. For instance, Landsat and Sentinel data always has a `sat:off_nadir_angle` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellite that can be pointed will have varying `sat:off_nadir_angle` values. The Commons extension allow the data provider to define the set of metadata that defines the collection. While some metadata fields are more likely to be part of the common set, such as or `instrument` rather than `eo:cloud_cover`, it depends on how the data provider chooses to organize their data. +This provides maximum flexibility to data providers, as the set of common metadata fields can vary between different types of data. For instance, Landsat and Sentinel data always has a `view:off_nadir` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellite that can be pointed will have varying `view:off_nadir` values. The Commons extension allow the data provider to define the set of metadata that defines the collection. While some metadata fields are more likely to be part of the common set, such as or `instrument` rather than `eo:cloud_cover`, it depends on how the data provider chooses to organize their data. If a metadata field is specified in the Collection properties, it will be ignored in any Item that links to that Collection. This is important because a Collection is the metadata that is common across all Item objects. If a field is variable at all, it should not be part of the Commons. @@ -56,7 +56,7 @@ An incomplete Collection: "constellation": "landsat-8", "instruments": ["oli", "tirs"], "eo:gsd": 30, - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", @@ -75,7 +75,7 @@ An incomplete item: ``` { "stac_version": "0.9.0-rc1", - "stac_extensions": ["commons", "eo", "sat"], + "stac_extensions": ["commons", "eo", "view"], "type": "Feature", "id": "LC08_L1TP_107018_20181001_20181001_01_RT", "bbox": [...], @@ -84,8 +84,8 @@ An incomplete item: "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431 + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431 }, "assets": {...}, "links": [...] @@ -97,7 +97,7 @@ The merged Item then looks like this: ``` { "stac_version": "0.9.0-rc1", - "stac_extensions": ["eo", "sat"], + "stac_extensions": ["eo", "view"], "type": "Feature", "id": "LC08_L1TP_107018_20181001_20181001_01_RT", "bbox": [...], @@ -109,10 +109,10 @@ The merged Item then looks like this: "constellation": "landsat-8", "instruments": ["oli", "tirs"], "eo:cloud_cover": 78, - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, "eo:gsd": 30, - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", diff --git a/extensions/commons/examples/landsat-collection.json b/extensions/commons/examples/landsat-collection.json index 7645cce15..54a53fa0d 100644 --- a/extensions/commons/examples/landsat-collection.json +++ b/extensions/commons/examples/landsat-collection.json @@ -63,7 +63,7 @@ "eo:gsd": 30, "platform": "landsat-8", "instruments": ["oli", "tirs"], - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", diff --git a/extensions/commons/examples/landsat-item.json b/extensions/commons/examples/landsat-item.json index 50e03da60..580a6a4f5 100644 --- a/extensions/commons/examples/landsat-item.json +++ b/extensions/commons/examples/landsat-item.json @@ -45,8 +45,8 @@ "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, "landsat:path": 107, "landsat:row": 18 }, diff --git a/extensions/eo/README.md b/extensions/eo/README.md index ad7f59d76..a1b920f7d 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -20,6 +20,8 @@ It is not necessary, but recommended to use the [Commons extension](../commons/R If the data has been collected by a satellite, it is strongly recommended to use the [`sat` extension](../sat/README.md), which in turn requires the [Instrument Fields](../../item-spec/common-metadata.md#instrument). If the data has been collected on an airborne platform it is strongly recommended to use the [Instrument Fields](../../item-spec/common-metadata.md#instrument). +For defining view geometry of data, it is strongly recommended to use the [`view` extension](../view/README.md). + - [Example (Landsat 8)](examples/example-landsat8.json) - [JSON Schema](json-schema/schema.json) @@ -31,6 +33,9 @@ If the data has been collected by a satellite, it is strongly recommended to use | eo:bands | [[Band Object](#band-object)] | **REQUIRED.** This is a list of the available bands where each item is a [Band Object](#band-object). | | 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. | + +### Ground Sampling Distance + **eo:gsd** is the nominal Ground Sample Distance for the data, as measured in meters on the ground. There are many definitions of GSD. The value of this attribute should be related to the spatial resolution at the sensor, rather than the pixel size of images after orthorectification, pansharpening, or scaling. @@ -204,6 +209,7 @@ the eo:bands portion is still being fleshed out. The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to EO data: * the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. +* the [View Geometry Extension Specification](../view/README.md) to describe angles of sensors collecting earth observation data from above the earth. ### Placing common fields in Collections A lot of EO data will have common metadata across many Items. It is not necessary, but recommended diff --git a/extensions/eo/examples/example-landsat8.json b/extensions/eo/examples/example-landsat8.json index 741159c36..ea3298545 100644 --- a/extensions/eo/examples/example-landsat8.json +++ b/extensions/eo/examples/example-landsat8.json @@ -2,6 +2,7 @@ "stac_version": "0.9.0-rc1", "stac_extensions": [ "eo", + "view", "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC08_L1TP_107018_20181001_20181001_01_RT", @@ -44,9 +45,9 @@ "platform": "landsat-8", "instrument": ["oli", "tirs"], "datetime": "2018-10-01T01:08:32.033Z", - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, - "sat:off_nadir_angle": 0, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, + "view:off_nadir": 0, "landsat:path": 107, "landsat:row": 18, "eo:gsd": 30, diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 5a620666b..2359bb821 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -2,7 +2,7 @@ **Extension [Maturity Classification](../README.md#extension-maturity): Proposal** -This document explains the fields of the Satellite Extension to a STAC Item. Sat adds metadata related to a satellite that carries an instrument for collecting data. It will often be combined with other extensions that describe the actual data, such as the `eo` or `sar` extensions. In many instances, satellite data will share common properties about the spacecraft across all of the Items. It is not necessary, but recommended to place common fields in [STAC Collections](../../collection-spec/collection-spec.md) using the [Commons extension](../commons/). +This document explains the fields of the Satellite Extension to a STAC Item. Sat adds metadata related to a satellite that carries an instrument for collecting data. It will often be combined with other extensions that describe the actual data, such as the `eo`, `os` or `sar` extensions. In many instances, satellite data will share common properties about the spacecraft across all of the Items. It is not necessary, but recommended to place common fields in [STAC Collections](../../collection-spec/collection-spec.md) using the [Commons extension](../commons/). The Satellite extension requires the [Instrument Fields](../../item-spec/common-metadata.md#instrument). @@ -13,52 +13,13 @@ The Satellite extension requires the [Instrument Fields](../../item-spec/common- | Field Name | Type | Description | | ---------------- | ------------------------ | ----------- | -| sat:off_nadir_angle | number | The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | -| sat:incidence_angle | number | The incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90). | -| sat:azimuth_angle | number | Viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360). | -| sat:sun_azimuth_angle | number | Sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360). | -| sat:sun_elevation_angle | number | Sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90). | -| sat:orbit_state | string | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites | -| sat:relative_orbit | integer | The relative orbit number at the time of acquisition. | +| sat:orbit_state | string | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites | +| sat:relative_orbit | integer | The relative orbit number at the time of acquisition. | **sat:orbit_state** indicates the type and current state of orbit. Satellites are either geosynchronous in which case they have one state: `geostationary`, or they are sun synchronous (i.e., polar orbiting satellites) in which case they are either `ascending` or `descending`. For sun synchronous satellites it is daytime during one of these states, and nighttime during the other. **sat: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 specific reference location of the sub-satellite point (the point on the earth directly below the satellite). It resets to 1 when the sub-satellite point revisits the refernece location. -### Viewing and sun geometry - -The angles `off_nadir_angle`, `incidence_angle`, and `sun_elevation_angle` are angles measured on a 2d plane formed: satellite location, sub-satellite point on the earth, the sun, and the center of the viewed area. - -The off-nadir angle and the incidence angle are related. When the off-nadir angle is low (high incidence angle) then the two angles sum to about 90, so one can be calculated from the other. However, at high off-nadir angles with high altitude sensors the curvature of the earth has an impact and their sum will be less than 90. If only providing one of the two angles, the off-nadir angle is preferred. - -The angles `azimuth_angle` and `sun_azimuth_angle` indicate the position of the viewed scene and the sun by the angle from true north, as shown below. - - -Example: -``` -{ - "stac_version": "0.9.0-rc1", - "stac_extensions": [ - "sat" - ], - "id": "20171110", - "type": "Feature", - ... - "properties": { - "platform": "mysatellite", - "instruments": ["mycamera1", "mycamera2"], - "constellation": "allmysatellites", - "sat:off_nadir_angle": 0, - "sat:incidence_angle": 90, - "sat:sun_elevation_angle": 45.0, - "sat:azimuth_angle": 23.9, - "sat:sun_azimuth_angle": 56.4, - "sat:orbit_state": "descending", - "sat:relative_orbit": 4 - } -} -``` - ## Implementations - No implementations yet diff --git a/extensions/sat/examples/example-landsat8.json b/extensions/sat/examples/example-landsat8.json index 58d140de9..ae192df02 100644 --- a/extensions/sat/examples/example-landsat8.json +++ b/extensions/sat/examples/example-landsat8.json @@ -1,7 +1,8 @@ { "stac_version": "0.9.0-rc1", "stac_extensions": [ - "sat" + "sat", + "view" ], "id": "LC08_L1TP_107018_20181001", "collection": "landsat-8-l1", @@ -41,13 +42,13 @@ }, "properties": { "datetime": "2018-10-01T01:08:32.033Z", - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, "platform": "landsat-8", "instruments": ["oli", "tirs"], "constellation": "landsat", "sat:orbit_state": "ascending", - "sat:off_nadir_angle": 0 + "view:off_nadir": 0 }, "assets": { "blue": { diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index f4a3b17b5..03da5a238 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -25,36 +25,6 @@ "type": "object", "required": [], "properties": { - "sat:off_nadir_angle": { - "title": "Off Nadir", - "type": "number", - "minimum": 0, - "maximum": 90 - }, - "sat:incidence_angle": { - "title": "Center incidence angle", - "type": "number", - "minimum": 0, - "maximum": 90 - }, - "sat:azimuth_angle": { - "title": "Azimuth angle", - "type": "number", - "minimum": 0, - "maximum": 360 - }, - "sat:sun_azimuth_angle": { - "title": "Sun Azimuth angle", - "type": "number", - "minimum": 0, - "maximum": 360 - }, - "sat:sun_elevation_angle": { - "title": "Sun Elevation angle", - "type": "number", - "minimum": 0, - "maximum": 90 - }, "sat:relative_orbit": { "type": "integer", "minimum": 1 diff --git a/extensions/single-file-stac/examples/example-search.json b/extensions/single-file-stac/examples/example-search.json index 2dd26e83c..dbe76e368 100644 --- a/extensions/single-file-stac/examples/example-search.json +++ b/extensions/single-file-stac/examples/example-search.json @@ -40,8 +40,8 @@ }, "properties": { "datetime": "2018-02-08T18:02:15.719478+00:00", - "sat:sun_azimuth_angle": 152.63804142, - "sat:sun_elevation_angle": 31.82216637, + "view:sun_azimuth": 152.63804142, + "view:sun_elevation": 31.82216637, "eo:cloud_cover": 19, "eo:row": "033", "eo:column": "037", @@ -207,8 +207,8 @@ }, "properties": { "datetime": "2018-02-03T17:43:44.623405+00:00", - "sat:sun_azimuth_angle": 153.39513457, - "sat:sun_elevation_angle": 30.41894816, + "view:sun_azimuth": 153.39513457, + "view:sun_elevation": 30.41894816, "eo:cloud_cover": 36, "eo:row": "033", "eo:column": "034", @@ -394,7 +394,7 @@ "eo:gsd": 15, "platform": "landsat-8", "instruments": ["oli", "tirs"], - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", diff --git a/extensions/view/README.md b/extensions/view/README.md new file mode 100644 index 000000000..1c96b73ea --- /dev/null +++ b/extensions/view/README.md @@ -0,0 +1,59 @@ +# View Geometry Extension Specification (`view`) + +**Extension [Maturity Classification](../README.md#extension-maturity): Proposal** + +This document explains the fields of the View Geometry Extension to a STAC Item. View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data. It will often be combined with other extensions that describe the actual data, such as the `eo`, `sat` or `sar` extensions. It is not necessary, but recommended to place common fields in [STAC Collections](../../collection-spec/collection-spec.md) using the [Commons extension](../commons/). + +- [Example (Landsat 8)](../eo/examples/example-landsat8.json) +- [JSON Schema](json-schema/schema.json) + +## Item fields + +| Field Name | Type | Description | +| ---------------- | ------------------------ | ----------- | +| view:off_nadir | number | The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | +| view:incidence_angle | number | The incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90). | +| view:azimuth | number | Viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360). | +| view:sun_azimuth | number | Sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360). | +| view:sun_elevation | number | Sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90). | + +The angles `off_nadir`, `incidence_angle`, and `sun_elevation` are angles measured on a 2d plane formed: sensor location, sub-sensor point on the earth, the sun, and the center of the viewed area. + +The off-nadir angle and the incidence angle are related. When the off-nadir angle is low (high incidence angle) then the two angles sum to about 90, so one can be calculated from the other. However, at high off-nadir angles with high altitude sensors the curvature of the earth has an impact and their sum will be less than 90. If only providing one of the two angles, the off-nadir angle is preferred. + +The angles `azimuth` and `sun_azimuth` indicate the position of the viewed scene and the sun by the angle from true north, as shown below. + + +Example: +``` +{ + "stac_version": "0.9.0-rc1", + "stac_extensions": [ + "view", + "sat" + ], + "id": "20171110", + "type": "Feature", + ... + "properties": { + "platform": "mysatellite", + "instruments": ["mycamera1", "mycamera2"], + "constellation": "allmysatellites", + "view:off_nadir": 0, + "view:incidence_angle": 90, + "view:azimuth": 23.9, + "view:sun_elevation": 45.0, + "view:sun_azimuth": 56.4, + "sat:orbit_state": "descending", + "sat:relative_orbit": 4 + } +} +``` + +## Implementations + +- No implementations yet + +## Extensions + +The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to View Geometry data. \ No newline at end of file diff --git a/extensions/view/examples/example-landsat8.json b/extensions/view/examples/example-landsat8.json new file mode 100644 index 000000000..58b852446 --- /dev/null +++ b/extensions/view/examples/example-landsat8.json @@ -0,0 +1,88 @@ +{ + "stac_version": "0.9.0-rc1", + "stac_extensions": [ + "sat", + "view" + ], + "id": "LC08_L1TP_107018_20181001", + "collection": "landsat-8-l1", + "type": "Feature", + "bbox": [ + 148.13933, + 59.51584, + 152.52758, + 60.63437 + ], + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + 152.52758, + 60.63437 + ], + [ + 149.1755, + 61.19016 + ], + [ + 148.13933, + 59.51584 + ], + [ + 151.33786, + 58.97792 + ], + [ + 152.52758, + 60.63437 + ] + ] + ] + }, + "properties": { + "datetime": "2018-10-01T01:08:32.033Z", + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, + "view:off_nadir": 0, + "view:incidence_angle": 0, + "view:azimuth": 23.4, + "platform": "landsat-8", + "instruments": ["oli", "tirs"], + "constellation": "landsat", + "sat:orbit_state": "ascending" + }, + "assets": { + "blue": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_B2.TIF", + "type": "image/tiff; application=geotiff", + "title": "Band 2 (blue)" + }, + "green": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_B3.TIF", + "type": "image/tiff; application=geotiff", + "title": "Band 3 (green)" + }, + "red": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_B4.TIF", + "type": "image/tiff; application=geotiff", + "title": "Band 4 (red)" + }, + "thumbnail": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_thumb_large.jpg", + "title": "Thumbnail image", + "type": "image/jpeg" + }, + "index": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/index.html", + "type": "text/html", + "title": "HTML index page" + } + }, + "links": [ + { + "rel": "collection", + "href": "http://landsat-stac.s3.amazonaws.com/landsat-8-l1/catalog.json" + } + ] +} diff --git a/extensions/view/json-schema/schema.json b/extensions/view/json-schema/schema.json new file mode 100644 index 000000000..7bba8abda --- /dev/null +++ b/extensions/view/json-schema/schema.json @@ -0,0 +1,60 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "schema.json#", + "title": "View Geometry Extension", + "description": "STAC View Geometry Extension to a STAC Item.", + "allOf": [ + { + "$ref": "../../../item-spec/json-schema/item.json" + }, + { + "$ref": "#/definitions/view" + } + ], + "definitions": { + "view": { + "type": "object", + "required": [ + "properties" + ], + "properties": { + "properties": { + "type": "object", + "required": [], + "properties": { + "view:off_nadir": { + "title": "Off Nadir", + "type": "number", + "minimum": 0, + "maximum": 90 + }, + "view:incidence_angle": { + "title": "Center incidence angle", + "type": "number", + "minimum": 0, + "maximum": 90 + }, + "view:azimuth": { + "title": "Azimuth angle", + "type": "number", + "minimum": 0, + "maximum": 360 + }, + "view:sun_azimuth": { + "title": "Sun Azimuth", + "type": "number", + "minimum": 0, + "maximum": 360 + }, + "view:sun_elevation": { + "title": "Sun Elevation", + "type": "number", + "minimum": 0, + "maximum": 90 + } + } + } + } + } + } +} \ No newline at end of file diff --git a/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json b/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json index e89b67743..ca04f5068 100755 --- a/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json +++ b/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json @@ -3,6 +3,7 @@ "stac_extensions": [ "eo", "proj", + "view", "https://example.com/stac/cbers-extension/1.0/schema.json" ], "id": "CBERS_4_MUX_20181029_177_106_L4", @@ -44,9 +45,9 @@ ], "properties": { "datetime": "2018-10-29T14:24:54Z", - "sat:sun_azimuth_angle": 111.113, - "sat:sun_elevation_angle": 65.8018, - "sat:off_nadir_angle": -0.00751271, + "view:sun_azimuth": 111.113, + "view:sun_elevation": 65.8018, + "view:off_nadir": -0.00751271, "proj:epsg": 32763, "cbers:data_type": "L4", "cbers:path": 177, diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json index 0e7f1c589..df2c08544 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -3,6 +3,7 @@ "stac_extensions": [ "eo", "proj", + "view", "https://example.digitalglobe.com/stac/1.0/schema.json" ], "id": "103001004B316600_P002_MUL", @@ -71,12 +72,12 @@ "DigitalGlobeProduct", "1BProduct" ], - "sat:sun_azimuth_angle": 168.7, + "view:sun_azimuth": 168.7, "eo:cloud_cover": 50, - "sat:off_nadir_angle": 18.4, - "sat:azimuth_angle": 34.5, + "view:off_nadir": 18.4, + "view:azimuth": 34.5, "platform": "worldview02", - "sat:sun_elevation_angle": 33.4, + "view:sun_elevation": 33.4, "eo:gsd": 2.047, "proj:epsg": null, "dg:catalog_id": "103001004B316600", diff --git a/item-spec/examples/landsat8-sample.json b/item-spec/examples/landsat8-sample.json index 02e7f84d2..056a86799 100644 --- a/item-spec/examples/landsat8-sample.json +++ b/item-spec/examples/landsat8-sample.json @@ -2,6 +2,7 @@ "stac_version": "0.9.0-rc1", "stac_extensions": [ "eo", + "view", "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC81530252014153LGN00", @@ -40,10 +41,10 @@ "collection": "L1T", "eo:gsd": 30.0, "eo:cloud_cover" : 10, - "sat:off_nadir_angle" : 0.000, - "sat:azimuth_angle": 0.00, - "sat:sun_azimuth_angle" : 149.01607154, - "sat:sun_elevation_angle" : 59.21424700, + "view:off_nadir" : 0.000, + "view:azimuth": 0.00, + "view:sun_azimuth" : 149.01607154, + "view:sun_elevation" : 59.21424700, "landsat:wrs_path": 153, "landsat:wrs_row": 25, "landsat:earth_sun_distance": 1.0141560, diff --git a/item-spec/examples/planet-sample.json b/item-spec/examples/planet-sample.json index c850ed208..d8729c87a 100644 --- a/item-spec/examples/planet-sample.json +++ b/item-spec/examples/planet-sample.json @@ -2,6 +2,7 @@ "stac_version": "0.9.0-rc1", "stac_extensions": [ "eo", + "view", "https://example.planet.com/stac/1.0/schema.json" ], "links": [ @@ -62,9 +63,9 @@ "datetime": "2017-11-10T12:10:30.535417Z", "eo:cloud_cover": 23, "eo:gsd": 3.7, - "sat:sun_azimuth_angle": 101.8, - "sat:sun_elevation_angle": 58.8, - "sat:off_nadir_angle": 1, + "view:sun_azimuth": 101.8, + "view:sun_elevation": 58.8, + "view:off_nadir": 1, "pl:acquired": "2017-11-10T12:10:30.535417Z", "pl:anomalous_pixels": 0.14, "pl:columns": 9111, diff --git a/item-spec/examples/sample-full.json b/item-spec/examples/sample-full.json index 7bea47ada..d363bdc05 100644 --- a/item-spec/examples/sample-full.json +++ b/item-spec/examples/sample-full.json @@ -2,6 +2,7 @@ "stac_version": "0.9.0-rc1", "stac_extensions": [ "eo", + "view", "https://example.com/cs-extension/1.0/schema.json" ], "type": "Feature", @@ -35,13 +36,13 @@ ], "created": "2016-05-04T00:00:01Z", "updated": "2017-01-01T00:30:55Z", - "sat:sun_azimuth_angle": 168.7, + "view:sun_azimuth": 168.7, "eo:cloud_cover": 0.12, - "sat:off_nadir_angle": 1.4, + "view:off_nadir": 1.4, "platform": "coolsat2", "instruments": ["cool_sensor_v1"], "eo:bands": [], - "sat:sun_elevation_angle": 33.4, + "view:sun_elevation": 33.4, "eo:gsd": 0.512, "cs:type": "scene", "cs:anomalous_pixels": 0.14, diff --git a/item-spec/examples/sentinel2-sample.json b/item-spec/examples/sentinel2-sample.json index b14a527e5..0a2500a60 100644 --- a/item-spec/examples/sentinel2-sample.json +++ b/item-spec/examples/sentinel2-sample.json @@ -2,6 +2,7 @@ "stac_version": "0.9.0-rc1", "stac_extensions": [ "eo", + "view", "proj" ], "type": "Feature", @@ -304,6 +305,6 @@ "platform": "sentinel-2", "proj:epsg": 32635, "eo:cloud_cover": 88.459539, - "sat:sun_azimuth_angle" : 176.091667178268 + "view:sun_azimuth" : 176.091667178268 } } diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index fcb703fd5..7369db060 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -88,7 +88,7 @@ throughout all domains. These optional fields are included for STAC Items by def such as EO, SAR and point clouds. * [Custom Extensions](../extensions/README.md#extending-stac) - It is generally allowed to add custom fields but it is recommended to add multiple attributes for related values instead of a nested object, -e.g., two fields `eo:cloud_cover` and `sat:sun_azimuth_angle` instead of a field `eo` with an object +e.g., two fields `eo:cloud_cover` and `eo:gsd` instead of a field `eo` with an object value containing the two fields. The convention (as used within Extensions) is for related attributes to use a common prefix on the attribute names to group them, e.g. `eo`. A nested data structure should only be used when the data itself is nested, as with `eo:bands`. diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index 3aba3106c..4c1b2015d 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -79,7 +79,8 @@ "sar", "sat", "scientific", - "version" + "version", + "view" ] } ]