From 4ea6142642908044cdcd878b6f53d3aed916682f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 15 Oct 2019 14:48:56 +0200 Subject: [PATCH 01/87] Data Cube extension: Allow to be used in Collections and added new fields (`data_type` and `description`). --- CHANGELOG.md | 2 + extensions/README.md | 2 +- extensions/datacube/README.md | 35 +++-- .../datacube/examples/example-collection.json | 143 ++++++++++++++++++ .../datacube/examples/example-item.json | 118 +++++++++++++++ extensions/datacube/examples/example.json | 52 ------- extensions/datacube/json-schema/schema.json | 94 ++++++++---- 7 files changed, 354 insertions(+), 92 deletions(-) create mode 100644 extensions/datacube/examples/example-collection.json create mode 100644 extensions/datacube/examples/example-item.json delete mode 100644 extensions/datacube/examples/example.json diff --git a/CHANGELOG.md b/CHANGELOG.md index b5e245a93..65a46d341 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## Unreleased +- Data Cube extension: Allow to be used in Collections and added new fields (`data_type` and `description`). + ## [v0.8.0] - 2019-10-11 ### Changed diff --git a/extensions/README.md b/extensions/README.md index f5e75c0ff..825e451b0 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -49,7 +49,7 @@ An extension can add new fields to STAC entities (content extension), or can add | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------ | -------- | | [Asset Definition](asset/README.md) (-) | Collection | Provides a way to specify details about what assets may be found in Items belonging to a collection | *Proposal* | | [Checksum](checksum/README.md) (`checksum`) | Item +Catalog +Collection | Provides a way to specify file checksums for assets and links in Items, Catalogs and Collections. | *Proposal* | -| [Data Cube](datacube/README.md) (`cube`) | Item | Data Cube related metadata, especially to describe their dimensions. | *Proposal* | +| [Data Cube](datacube/README.md) (`cube`) | Item +Collection | Data Cube related metadata, especially to describe their dimensions. | *Proposal* | | [Datetime Range](datetime-range/README.md) (`dtr`) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | | [EO](eo/README.md) (`eo`) | Item | Covers electro-optical data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, off nadir, sun angle + elevation, gsd and more. | *Pilot* | | [Label](label/README.md) (`label`) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | diff --git a/extensions/datacube/README.md b/extensions/datacube/README.md index 4147ce296..d4a12649e 100644 --- a/extensions/datacube/README.md +++ b/extensions/datacube/README.md @@ -4,25 +4,30 @@ Data cube related metadata, especially to describe their dimensions. -- [Example](examples/example.json) +- Examples: + - [Item](examples/example-item.json) + - [Collection](example-collection.json) - [JSON Schema](json-schema/schema.json) ## Item Fields -| Field Name | Type | Description | -| --------------- | ------------------------------------------------------------ | ----------- | -| cube:dimensions | Map | Uniquely named dimensions of the data cube. | +| Field Name | Type | Description | +| --------------- | -------------------------------------------------- | ------------------------------------------- | +| cube:dimensions | Map | Uniquely named dimensions of the data cube. | -\* = One of the objects defined below: +### Dimension Object + +A *Dimension Object* comes in different flavors, each of them is defined below. The fields define mostly very similar fields, but they differ slightly depending on their use case. All objects share the fields `type` and `description` with the same definition, but `type` may be restricted to certain values. The definition of`axis` is shared between the spatial dimensions, but restricted to certain values, too. `extent`, `values` and `step` share the same definition, but differ in the supported data types (number or string) depending on the type of dimension. Whenever it's useful to specify these fields, the objects add the additional fields `reference_system`, `data_type` and `unit` with very similar definitions across the objects. ### Horizontal Spatial Dimension Object -A spatial dimension in one of the horizontal (x or y) directions. +A spatial dimension in one of the horizontal (x or y) directions. | Field Name | Type | Description | | ---------------- | -------------- | ------------------------------------------------------------ | | type | string | **REQUIRED.** Type of the dimension, always `spatial`. | | axis | string | **REQUIRED.** Axis of the spatial dimension (`x`, `y`). | +| description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | extent | [number] | **REQUIRED.** Extent (lower and upper bounds) of the dimension as two-dimensional array. Open intervals with `null` are not allowed. | | values | [number] | Optionally, a set of all potential values. | | step | number\|null | The space between the values. Use `null` for irregularly spaced steps. | @@ -36,40 +41,48 @@ A spatial dimension in vertical (z) direction. | ---------------- | ---------------- | ------------------------------------------------------------ | | type | string | **REQUIRED.** Type of the dimension, always `spatial`. | | axis | string | **REQUIRED.** Axis of the spatial dimension, always `z`. | +| description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | +| data_type | string | The data type for the dimension values, e.g. `string`, `boolean`, `number` or `integer`. | | extent | [number\|null] | If the dimension consists of [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values, the extent (lower and upper bounds) of the values as two-dimensional array. Use `null` for open intervals. | | values | [number\|string] | A set of all potential values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | | step | number\|null | If the dimension consists of [interval](https://en.wikipedia.org/wiki/Level_of_measurement#Interval_scale) values, the space between the values. Use `null` for irregularly spaced steps. | | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | | reference_system | string\|number | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/) or [PROJ definition](https://proj4.org/operations/projections/index.html). Defaults to EPSG code 4326. | -An Vertical Spatial Dimension Object MUST specify an `extent` or a set of `values`. It MAY specify both. +An Vertical Spatial Dimension Object MUST specify **at least** a `data_type`, an `extent` or a set of `values`. It is **recommended** to specify `data_type` and either `extent` or `values`. ### Temporal Dimension Object -A temporal dimension based on the ISO 8601 standard. The temporal reference system for the data is expected to be ISO 8601 compliant (Gregorian calendar / UTC). Data not compliant with ISO 8601 can be represented as an *Additional Dimension Object* with `type` set to `temporal`. +A temporal dimension based on the ISO 8601 standard. The temporal reference system for the data is expected to be ISO 8601 compliant (Gregorian calendar / UTC). Data not compliant with ISO 8601 can be represented as an *Additional Dimension Object* with `type` set to `temporal`. | Field Name | Type | Description | | ---------- | -------------- | ------------------------------------------------------------ | | type | string | **REQUIRED.** Type of the dimension, always `temporal`. | +| description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | extent | [string\|null] | **REQUIRED.** Extent (lower and upper bounds) of the dimension as two-dimensional array. The dates and/or times must be strings compliant to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). `null` is allowed for open date ranges. | | values | [string] | If the dimension consists of set of specific values they can be listed here. The dates and/or times must be strings compliant to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | | step | string\|null | The space between the temporal instances as [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations), e.g. `P1D`. Use `null` for irregularly spaced steps. | ### Additional Dimension Object -An additional dimension that is not `spatial`. +An additional dimension that is not `spatial`, but may be `temporal` if the data is not compliant with ISO 8601. | Field Name | Type | Description | | ---------------- | ---------------- | ------------------------------------------------------------ | | type | string | **REQUIRED.** Custom type of the dimension, never `spatial`. | +| description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | +| data_type | string | The data type for the dimension values, e.g. `string`, `boolean`, `number` or `integer`. | | extent | [number\|null] | If the dimension consists of [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values, the extent (lower and upper bounds) of the values as two-dimensional array. Use `null` for open intervals. | | values | [number\|string] | A set of all potential values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | | step | number\|null | If the dimension consists of [interval](https://en.wikipedia.org/wiki/Level_of_measurement#Interval_scale) values, the space between the values. Use `null` for irregularly spaced steps. | | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | | reference_system | string | The reference system for the data. | -An Additional Dimension Object MUST specify an `extent` or a set of `values`. It MAY specify both. +An Additional Dimension Object MUST specify **at least** a `data_type`, an `extent` or a set of `values`. It is **recommended** to specify `data_type` and either `extent` or `values`. ## Implementations -None yet, still in proposal stage. \ No newline at end of file +openEO has multiple implementations. Some example collections: +- [Sentinel-2 collection on openEO Google Earth Engine driver](https://earthengine.openeo.org/v0.4/collections/COPERNICUS/S2) (STAC 0.7.0) +- [MODIS ST Drought collection on EURAC WCPS driver](https://openeo.eurac.edu/collections/MODIS_ST_DROUGHT) (STAC 0.7.0) + diff --git a/extensions/datacube/examples/example-collection.json b/extensions/datacube/examples/example-collection.json new file mode 100644 index 000000000..adfe9e0a4 --- /dev/null +++ b/extensions/datacube/examples/example-collection.json @@ -0,0 +1,143 @@ +{ + "stac_version": "0.8.0", + "stac_extensions": [ + "datacube" + ], + "id": "Sentinel2-L1C", + "title": "Sentinel-2: MultiSpectral Instrument, Level-1C", + "description": "Multi-dimensional Sentinel-2 data cube in a STAC collection.", + "license": "proprietary", + "extent": { + "spatial": { + "bbox": [ + [-180,-56,180,83] + ] + }, + "temporal": { + "interval": [ + ["2015-06-23T00:00:00Z","2019-07-10T13:44:56Z"] + ] + } + }, + "cube:dimensions": { + "x": { + "type": "spatial", + "axis": "x", + "extent": [-180,180], + "reference_system": 3857 + }, + "y": { + "type": "spatial", + "axis": "y", + "extent": [-56,83], + "reference_system": 3857 + }, + "time": { + "type": "temporal", + "extent": ["2015-06-23T00:00:00Z","2019-07-10T13:44:56Z"], + "step": "P5D" + }, + "spectral": { + "type": "bands", + "values": ["B1","B2","B3","B4","B5","B6","B7","B8","B8A","B9","B10","B11","B12","QA10","QA20","QA60"] + } + }, + "summaries": { + "datetime": { + "min": "2015-06-23T00:00:00Z", + "max": "2019-07-10T13:44:56Z" + }, + "eo:gsd": [10,30,60], + "eo:platform": ["sentinel-2a","sentinel-2b"], + "eo:constellation": ["sentinel-2"], + "eo:instrument": ["msi"], + "eo:epsg": [3857], + "eo:bands": [ + [ + { + "name": "B1", + "common_name": "coastal", + "center_wavelength": 4.439, + "gsd": 60 + }, + { + "name": "B2", + "common_name": "blue", + "center_wavelength": 4.966, + "gsd": 10 + }, + { + "name": "B3", + "common_name": "green", + "center_wavelength": 5.6, + "gsd": 10 + }, + { + "name": "B4", + "common_name": "red", + "center_wavelength": 6.645, + "gsd": 10 + }, + { + "name": "B5", + "center_wavelength": 7.039, + "gsd": 20 + }, + { + "name": "B6", + "center_wavelength": 7.402, + "gsd": 20 + }, + { + "name": "B7", + "center_wavelength": 7.825, + "gsd": 20 + }, + { + "name": "B8", + "common_name": "nir", + "center_wavelength": 8.351, + "gsd": 10 + }, + { + "name": "B8A", + "center_wavelength": 8.648, + "gsd": 20 + }, + { + "name": "B9", + "center_wavelength": 9.45, + "gsd": 60 + }, + { + "name": "B10", + "center_wavelength": 1.3735, + "gsd": 60 + }, + { + "name": "B11", + "common_name": "swir16", + "center_wavelength": 1.6137, + "gsd": 20 + }, + { + "name": "B12", + "common_name": "swir22", + "center_wavelength": 2.2024, + "gsd": 20 + } + ] + ] + }, + "links": [ + { + "rel": "self", + "href": "https://example.sentinel2-hub.com/stac/example-collection.json" + }, + { + "rel": "license", + "href": "https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf", + "title": "Legal notice on the use of Copernicus Sentinel Data and Service Information" + } + ] +} \ No newline at end of file diff --git a/extensions/datacube/examples/example-item.json b/extensions/datacube/examples/example-item.json new file mode 100644 index 000000000..1b3c88369 --- /dev/null +++ b/extensions/datacube/examples/example-item.json @@ -0,0 +1,118 @@ +{ + "stac_version": "0.8.0", + "stac_extensions": [ + "datacube" + ], + "id": "datacube-123", + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + -122.308150179, + 37.488035566 + ], + [ + -122.597502109, + 37.538869539 + ], + [ + -122.576687533, + 37.613537207 + ], + [ + -122.2880486, + 37.562818007 + ], + [ + -122.308150179, + 37.488035566 + ] + ] + ] + }, + "bbox": [ + -122.59750209, + 37.48803556, + -122.2880486, + 37.613537207 + ], + "properties": { + "title": "Multi-dimensional data cube 123 in a STAC Item.", + "datetime": "2016-05-03T13:21:30.040Z", + "cube:dimensions": { + "x": { + "type": "spatial", + "axis": "x", + "extent": [ + -122.59750209, + -122.2880486 + ], + "reference_system": 4326 + }, + "y": { + "type": "spatial", + "axis": "y", + "extent": [ + 37.48803556, + 37.613537207 + ], + "reference_system": 4326 + }, + "pressure_levels": { + "type": "spatial", + "axis": "z", + "extent": [ + 0, + 1000 + ], + "step": 100, + "unit": "Pa" + }, + "metered_levels": { + "type": "spatial", + "axis": "z", + "values": [ + 0, + 10, + 25, + 50, + 100, + 1000 + ], + "unit": "m" + }, + "time": { + "type": "temporal", + "values": ["2016-05-03T13:21:30.040Z"] + }, + "spectral": { + "type": "bands", + "values": [ + "red", + "green", + "blue" + ] + } + } + }, + "assets": { + "data": { + "href": "http://cool-sat.com/catalog/datacube-123/data.nc", + "type": "application/netcdf", + "title": "netCDF Data cube" + }, + "thumbnail": { + "href": "http://cool-sat.com/catalog/datacube-123/thumbnail.png", + "type": "image/png", + "title": "Thumbnail" + } + }, + "links": [ + { + "rel": "self", + "href": "http://cool-sat.com/catalog/datacube-123/example-item.json" + } + ] +} \ No newline at end of file diff --git a/extensions/datacube/examples/example.json b/extensions/datacube/examples/example.json deleted file mode 100644 index d9dac4a5f..000000000 --- a/extensions/datacube/examples/example.json +++ /dev/null @@ -1,52 +0,0 @@ -{ - "stac_version": "0.8.0", - "stac_extensions": [ - "datacube" - ], - "id": "datacube", - "description": "Multi-dimensional data cube in a STAC collection.", - "links": [ - { - "rel": "self", - "href": "http://www.example.org/datacubes/catalog.json" - } - ], - "properties": { - "cube:dimensions": { - "x": { - "type": "spatial", - "axis": "x", - "extent": [-180,180], - "reference_system": 3857 - }, - "y": { - "type": "spatial", - "axis": "y", - "extent": [-85,85], - "reference_system": 3857 - }, - "pressure_levels": { - "type": "spatial", - "axis": "z", - "extent": [0,1000], - "step": 100, - "unit": "Pa" - }, - "metered_levels": { - "type": "spatial", - "axis": "z", - "values": [0,10,25,50,100,1000], - "unit": "m" - }, - "time": { - "type": "temporal", - "extent": ["2015-01-01T00:00:00Z","2018-12-31T00:00:00Z"], - "step": "P1D" - }, - "spectral": { - "type": "bands", - "values": ["red","green","blue"] - } - } - } -} \ No newline at end of file diff --git a/extensions/datacube/json-schema/schema.json b/extensions/datacube/json-schema/schema.json index 11b56f06b..33d2614e0 100644 --- a/extensions/datacube/json-schema/schema.json +++ b/extensions/datacube/json-schema/schema.json @@ -2,47 +2,61 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "stac-extension-datacube.json#", "title": "Data Cube Extension", - "description": "STAC Data Cube Extension to a STAC Item", - "allOf": [ + "description": "STAC Data Cube Extension to STAC Items and STAC Collections", + "oneOf": [ { - "$ref": "../../../item-spec/json-schema/item.json" + "allOf": [ + { + "$ref": "../../../item-spec/json-schema/item.json" + }, + { + "type": "object", + "required": [ + "properties" + ], + "properties": { + "properties": { + "$ref": "#/definitions/datacube" + } + } + } + ] }, { - "$ref": "#/definitions/datacube" + "allOf": [ + { + "$ref": "../../../collection-spec/json-schema/collection.json" + }, + { + "$ref": "#/definitions/datacube" + } + ] } ], "definitions": { "datacube": { "type": "object", "required": [ - "properties" + "cube:dimensions" ], "properties": { - "properties": { + "cube:dimensions": { "type": "object", - "required": [ - "cube:dimensions" - ], - "properties": { - "cube:dimensions": { - "type": "object", - "additionalProperties": { - "anyOf": [ - { - "$ref": "#/definitions/objects/additional_dimension" - }, - { - "$ref": "#/definitions/objects/horizontal_spatial_dimension" - }, - { - "$ref": "#/definitions/objects/vertical_spatial_dimension" - }, - { - "$ref": "#/definitions/objects/temporal_dimension" - } - ] + "additionalProperties": { + "anyOf": [ + { + "$ref": "#/definitions/objects/additional_dimension" + }, + { + "$ref": "#/definitions/objects/horizontal_spatial_dimension" + }, + { + "$ref": "#/definitions/objects/vertical_spatial_dimension" + }, + { + "$ref": "#/definitions/objects/temporal_dimension" } - } + ] } } } @@ -82,6 +96,9 @@ } ] }, + "description": { + "$ref": "#/definitions/fields/description" + }, "extent": { "$ref": "#/definitions/fields/extent_open" }, @@ -94,6 +111,9 @@ "unit": { "$ref": "#/definitions/fields/unit" }, + "data_type": { + "$ref": "#/definitions/fields/data_type" + }, "reference_system": { "type": "string" } @@ -114,6 +134,9 @@ "axis": { "$ref": "#/definitions/fields/axis_xy" }, + "description": { + "$ref": "#/definitions/fields/description" + }, "extent": { "$ref": "#/definitions/fields/extent_closed" }, @@ -154,6 +177,9 @@ "axis": { "$ref": "#/definitions/fields/axis_z" }, + "description": { + "$ref": "#/definitions/fields/description" + }, "extent": { "$ref": "#/definitions/fields/extent_open" }, @@ -166,6 +192,9 @@ "unit": { "$ref": "#/definitions/fields/unit" }, + "data_type": { + "$ref": "#/definitions/fields/data_type" + }, "reference_system": { "$ref": "#/definitions/fields/reference_system_spatial" } @@ -186,6 +215,9 @@ "type": "string", "const": "temporal" }, + "description": { + "$ref": "#/definitions/fields/description" + }, "values": { "type": "array", "minItems": 1, @@ -284,6 +316,12 @@ "number" ], "default": 4326 + }, + "description": { + "type": "string" + }, + "data_type": { + "type": "string" } } } From 9bc8b3c9089553863570122921de88483747c1fd Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 30 Oct 2019 15:38:18 +0100 Subject: [PATCH 02/87] Added WKT2/PROJJSON. --- extensions/datacube/README.md | 4 ++-- extensions/datacube/json-schema/schema.json | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/extensions/datacube/README.md b/extensions/datacube/README.md index d4a12649e..59cfe2c45 100644 --- a/extensions/datacube/README.md +++ b/extensions/datacube/README.md @@ -31,7 +31,7 @@ A spatial dimension in one of the horizontal (x or y) directions. | extent | [number] | **REQUIRED.** Extent (lower and upper bounds) of the dimension as two-dimensional array. Open intervals with `null` are not allowed. | | values | [number] | Optionally, a set of all potential values. | | step | number\|null | The space between the values. Use `null` for irregularly spaced steps. | -| reference_system | string\|number | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/) or [PROJ definition](https://proj4.org/operations/projections/index.html). Defaults to EPSG code 4326. | +| reference_system | string\|number\|object | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON](https://proj.org/schemas/v0.1/projjson.schema.json) or [PROJ definition](https://proj4.org/operations/projections/index.html). Defaults to EPSG code 4326. | ### Vertical Spatial Dimension Object @@ -47,7 +47,7 @@ A spatial dimension in vertical (z) direction. | values | [number\|string] | A set of all potential values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | | step | number\|null | If the dimension consists of [interval](https://en.wikipedia.org/wiki/Level_of_measurement#Interval_scale) values, the space between the values. Use `null` for irregularly spaced steps. | | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | -| reference_system | string\|number | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/) or [PROJ definition](https://proj4.org/operations/projections/index.html). Defaults to EPSG code 4326. | +| reference_system | string\|number\|object | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON](https://proj.org/schemas/v0.1/projjson.schema.json) or [PROJ definition](https://proj4.org/operations/projections/index.html). Defaults to EPSG code 4326. | An Vertical Spatial Dimension Object MUST specify **at least** a `data_type`, an `extent` or a set of `values`. It is **recommended** to specify `data_type` and either `extent` or `values`. diff --git a/extensions/datacube/json-schema/schema.json b/extensions/datacube/json-schema/schema.json index 33d2614e0..c858b2bf7 100644 --- a/extensions/datacube/json-schema/schema.json +++ b/extensions/datacube/json-schema/schema.json @@ -313,7 +313,8 @@ "reference_system_spatial": { "type": [ "string", - "number" + "number", + "object" ], "default": 4326 }, From a9942df5dd6731b1ae67cfe5f0acf21456dde3bc Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 1 Nov 2019 14:49:39 +0100 Subject: [PATCH 03/87] Updated links --- extensions/datacube/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/datacube/README.md b/extensions/datacube/README.md index 59cfe2c45..bd3b65ee8 100644 --- a/extensions/datacube/README.md +++ b/extensions/datacube/README.md @@ -31,7 +31,7 @@ A spatial dimension in one of the horizontal (x or y) directions. | extent | [number] | **REQUIRED.** Extent (lower and upper bounds) of the dimension as two-dimensional array. Open intervals with `null` are not allowed. | | values | [number] | Optionally, a set of all potential values. | | step | number\|null | The space between the values. Use `null` for irregularly spaced steps. | -| reference_system | string\|number\|object | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON](https://proj.org/schemas/v0.1/projjson.schema.json) or [PROJ definition](https://proj4.org/operations/projections/index.html). Defaults to EPSG code 4326. | +| reference_system | string\|number\|object | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON](https://proj.org/projjson.html) or [PROJ definition](https://proj.org/usage/quickstart.html). Defaults to EPSG code 4326. | ### Vertical Spatial Dimension Object @@ -47,7 +47,7 @@ A spatial dimension in vertical (z) direction. | values | [number\|string] | A set of all potential values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | | step | number\|null | If the dimension consists of [interval](https://en.wikipedia.org/wiki/Level_of_measurement#Interval_scale) values, the space between the values. Use `null` for irregularly spaced steps. | | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | -| reference_system | string\|number\|object | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON](https://proj.org/schemas/v0.1/projjson.schema.json) or [PROJ definition](https://proj4.org/operations/projections/index.html). Defaults to EPSG code 4326. | +| reference_system | string\|number\|object | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON](https://proj.org/projjson.html) or [PROJ definition](https://proj.org/usage/quickstart.html). Defaults to EPSG code 4326. | An Vertical Spatial Dimension Object MUST specify **at least** a `data_type`, an `extent` or a set of `values`. It is **recommended** to specify `data_type` and either `extent` or `values`. From ef0d6ada715a82831294aae39bb7110e939c37ef Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Thu, 7 Nov 2019 13:11:36 -0500 Subject: [PATCH 04/87] initial sat extension --- extensions/README.md | 1 + extensions/sar/README.md | 8 +- extensions/sat/README.md | 103 +++++++ extensions/sat/examples/example-landsat8.json | 263 ++++++++++++++++++ extensions/sat/json-schema/schema.json | 69 +++++ 5 files changed, 437 insertions(+), 7 deletions(-) create mode 100644 extensions/sat/README.md create mode 100644 extensions/sat/examples/example-landsat8.json create mode 100644 extensions/sat/json-schema/schema.json diff --git a/extensions/README.md b/extensions/README.md index f5e75c0ff..152d76a74 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -55,6 +55,7 @@ An extension can add new fields to STAC entities (content extension), or can add | [Label](label/README.md) (`label`) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | | [Point Cloud](pointcloud/README.md) (`pc`) | Item | Provides a way to describe point cloud datasets. The point clouds can come from either active or passive sensors, and data is frequently acquired using tools such as LiDAR or coincidence-matched imagery. | *Proposal* | | [SAR](sar/README.md) (`sar`) | Item | Covers synthetic-aperture radar data that represents a snapshot of the earth for a single date and time. | *Proposal* | +| [sat](sat/README.md) (-) | Item | Satellite related metadata for data collected from satellites. | *Proposal* | | [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* | diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 6f3d362de..3f918d20f 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -18,16 +18,12 @@ 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 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. | | sar:center_wavelength | number | The center wavelength of the instrument, in centimeters (cm). | | sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | | sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. | | sar:bands | [[Band Object](#band-object)] | This is a list of the available bands where each item is a [Band Object](#band-object). | -| sar:pass_direction | string\|null | **REQUIRED.** Direction of the orbit, either `ascending`, `descending` or `null` if not relevant. | | sar:type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | | sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | | sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | @@ -37,9 +33,7 @@ The exact metadata that would appear in a STAC Collection record will vary depen | sar:looks_azimuth | number | Number of azimuth looks, which is the number of groups of signal samples (looks) parallel to the flight path. | | sar:looks_equivalent_number | number | The equivalent number of looks (ENL). | | sar:observation_direction | string | Antenna pointing direction relative to the flight trajectory of the satellite, either `left` or `right`. -| sar:absolute_orbit | integer | An absolute orbit number associated with the acquisition. | -| sar:relative_orbit | integer | A relative orbit number associated with the acquisition. | -| 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: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). diff --git a/extensions/sat/README.md b/extensions/sat/README.md new file mode 100644 index 000000000..e04b98c64 --- /dev/null +++ b/extensions/sat/README.md @@ -0,0 +1,103 @@ +# sat Extension Specification (-) + +**Extension [Maturity Classification](../README.md#extension-maturity): Proposal** + +This document explains the fields of the sat 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#common-fields-and-standalone-collections). + +- [Example (Landsat 8)](examples/example-landsat8.json) +- [JSON Schema](json-schema/schema.json) + +## Item fields + +| Field Name | Type | Description | +| ---------------- | ------------------------ | ----------- | +| platform | string | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. | +| instrument | string | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | +| pass_direction | string\|null | Direction of the orbit, either `ascending` or `descending`. | +| constellation | string | Name of the constellation to which the platform belongs. | +| off_nadir | number | Viewing angle. The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | +| 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). | +| 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). | +| 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). | +| absolute_orbit | integer | An absolute orbit number associated with the acquisition. | +| relative_orbit | integer | A relative orbit number associated with the acquisition. | +| 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). | + +**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). + +**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. Examples include `oli_tirs` (Landsat-8), `msi` (Sentinel-2), +`aster` (Terra), and `modis` (Terra and Aqua). + +**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. + + +``` +Planet example: + +``` +{ + "stac_version": "0.8.1", + "stac_extensions": ["eo"], + "id": "20171110_121030_1013", + "type": "Feature", + ... + "properties": { + ... + "eo:bands": [ + { + "full_width_half_max": 0.08, + "center_wavelength": 0.63, + "common_name": "red" + }, + { + "full_width_half_max": 0.09, + "center_wavelength": 0.545, + "common_name": "green" + }, + { + "full_width_half_max": 0.06, + "center_wavelength": 0.485, + "common_name": "blue" + }, + { + "full_width_half_max": 0.08, + "center_wavelength": 0.82, + "common_name": "nir" + } + ] + }, + "assets": { + "analytic": { + "href": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTcxMTEwXzEyMTAxMF8xMDEzIiwgImMiOiAiUFNTY2VuZTRCYW5kIiwgInQiOiAiYW5hbHl0aWMiLCAiY3QiOiAiaXRlbS10eXBlIn0", + "title": "PSScene4Band GeoTIFF (COG)", + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "eo:bands": [0,1,2,3] + } + } +} +``` + +## Implementations + +A number of implementations listed on [STAC Implementations page](../../implementations.md) are making use of the core EO +properties, including the SpaceNet, CBERS, sat-api and Planet implementations. This is not marked as more mature because +the eo:bands portion is still being fleshed out. + +## Extensions + +The [extensions page](../README.md) gives an overview about related extensions. \ No newline at end of file diff --git a/extensions/sat/examples/example-landsat8.json b/extensions/sat/examples/example-landsat8.json new file mode 100644 index 000000000..d150dfa28 --- /dev/null +++ b/extensions/sat/examples/example-landsat8.json @@ -0,0 +1,263 @@ +{ + "stac_version": "0.8.1", + "stac_extensions": [ + "sat", + "eo" + ], + "id": "LC08_L1TP_107018_20181001_20181001_01_RT", + "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": { + "collection": "landsat-8-l1", + "datetime": "2018-10-01T01:08:32.033Z", + "eo:cloud_cover": 78, + "eo:sun_azimuth": 168.8989761, + "eo:sun_elevation": 26.32596431, + "eo:gsd": 30, + "platform": "landsat-8", + "instrument": "oli_tirs", + "constellation": "landsat", + "pass_direction": "ascending", + "off_nadir": 0, + "eo:bands": [ + { + "name": "B1", + "common_name": "coastal", + "gsd": 30, + "center_wavelength": 0.44, + "full_width_half_max": 0.02 + }, + { + "name": "B2", + "common_name": "blue", + "gsd": 30, + "center_wavelength": 0.48, + "full_width_half_max": 0.06 + }, + { + "name": "B3", + "common_name": "green", + "gsd": 30, + "center_wavelength": 0.56, + "full_width_half_max": 0.06 + }, + { + "name": "B4", + "common_name": "red", + "gsd": 30, + "center_wavelength": 0.65, + "full_width_half_max": 0.04 + }, + { + "name": "B5", + "common_name": "nir", + "gsd": 30, + "center_wavelength": 0.86, + "full_width_half_max": 0.03 + }, + { + "name": "B6", + "common_name": "swir16", + "gsd": 30, + "center_wavelength": 1.6, + "full_width_half_max": 0.08 + }, + { + "name": "B7", + "common_name": "swir22", + "gsd": 30, + "center_wavelength": 2.2, + "full_width_half_max": 0.2 + }, + { + "name": "B8", + "common_name": "pan", + "gsd": 15, + "center_wavelength": 0.59, + "full_width_half_max": 0.18 + }, + { + "name": "B9", + "common_name": "cirrus", + "gsd": 30, + "center_wavelength": 1.37, + "full_width_half_max": 0.02 + }, + { + "name": "B10", + "common_name": "lwir11", + "gsd": 100, + "center_wavelength": 10.9, + "full_width_half_max": 0.8 + }, + { + "name": "B11", + "common_name": "lwir12", + "gsd": 100, + "center_wavelength": 12, + "full_width_half_max": 1 + } + ] + }, + "assets": { + "ANG": { + "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_ANG.txt", + "title": "Angle coefficients file", + "type": "text/plain" + }, + "B1": { + "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_B1.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 0 + ], + "title": "Band 1 (coastal)" + }, + "B2": { + "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", + "eo:bands": [ + 1 + ], + "title": "Band 2 (blue)" + }, + "B3": { + "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", + "eo:bands": [ + 2 + ], + "title": "Band 3 (green)" + }, + "B4": { + "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", + "eo:bands": [ + 3 + ], + "title": "Band 4 (red)" + }, + "B5": { + "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_B5.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 4 + ], + "title": "Band 5 (nir)" + }, + "B6": { + "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_B6.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 5 + ], + "title": "Band 6 (swir16)" + }, + "B7": { + "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_B7.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 6 + ], + "title": "Band 7 (swir22)" + }, + "B8": { + "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_B8.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 7 + ], + "title": "Band 8 (pan)" + }, + "B9": { + "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_B9.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 8 + ], + "title": "Band 9 (cirrus)" + }, + "B10": { + "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_B10.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 9 + ], + "title": "Band 10 (lwir)" + }, + "B11": { + "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_B11.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 10 + ], + "title": "Band 11 (lwir)" + }, + "BQA": { + "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_BQA.TIF", + "title": "Band quality data", + "type": "image/tiff; application=geotiff" + }, + "MTL": { + "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_MTL.txt", + "title": "original metadata file", + "type": "text/plain" + }, + "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": "self", + "href": "https://odu9mlf7d6.execute-api.us-east-1.amazonaws.com/stage/search?id=LC08_L1TP_107018_20181001_20181001_01_RT" + }, + { + "rel": "parent", + "href": "https://odu9mlf7d6.execute-api.us-east-1.amazonaws.com/stage/stac/collections/landsat-8-l1" + }, + { + "rel": "root", + "href": "https://odu9mlf7d6.execute-api.us-east-1.amazonaws.com/stage/stac" + } + ] +} diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json new file mode 100644 index 000000000..ee28c7101 --- /dev/null +++ b/extensions/sat/json-schema/schema.json @@ -0,0 +1,69 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "schema.json#", + "title": "Sat Extension", + "description": "STAC Sat Extension to a STAC Item.", + "allOf": [ + { + "$ref": "../../../item-spec/json-schema/item.json#/definitions/core" + }, + { + "$ref": "#/definitions/sat" + } + ], + "definitions": { + "eo": { + "type": "object", + "required": [ + "properties" + ], + "properties": { + "properties": { + "type": "object", + "required": [ + "platform", + "instrument" + ], + "properties": { + "platform": { + "title": "Platform", + "type": "string" + }, + "constellation": { + "title": "Constellation", + "type": "string" + }, + "instrument": { + "title": "Instrument", + "type": "string" + }, + "off_nadir": { + "title": "Off Nadir", + "type": "number", + "minimum": 0, + "maximum": 90 + }, + "azimuth": { + "title": "Azimuth", + "type": "number", + "minimum": 0, + "maximum": 360 + }, + "sun_azimuth": { + "title": "Sun Azimuth", + "type": "number", + "minimum": 0, + "maximum": 360 + }, + "sun_elevation": { + "title": "Sun Elevation", + "type": "number", + "minimum": 0, + "maximum": 90 + } + } + } + } + } + } +} \ No newline at end of file From 71a60f4e47fd600a2127520d7b28b1b4caf14d84 Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Thu, 7 Nov 2019 13:37:49 -0500 Subject: [PATCH 05/87] updated sat fields --- extensions/sat/README.md | 65 ++++++++++++---------------------------- 1 file changed, 19 insertions(+), 46 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index e04b98c64..0d7dbeffc 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -12,28 +12,25 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | Field Name | Type | Description | | ---------------- | ------------------------ | ----------- | | platform | string | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. | -| instrument | string | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | -| pass_direction | string\|null | Direction of the orbit, either `ascending` or `descending`. | +| instruments | [string] | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | | constellation | string | Name of the constellation to which the platform belongs. | | off_nadir | number | Viewing angle. The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | +| 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). | | 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). | | 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). | | 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). | +| pass_direction | string\|null | Direction of the orbit, either `ascending` or `descending`. | | absolute_orbit | integer | An absolute orbit number associated with the acquisition. | | relative_orbit | integer | A relative orbit number associated with the acquisition. | -| 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). | + **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). - -**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. Examples include `oli_tirs` (Landsat-8), `msi` (Sentinel-2), -`aster` (Terra), and `modis` (Terra and Aqua). + +**instruments** is an array of all the sensors used in the creation of the data. 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 so would be specified as ['oli', 'TItirsRS']. Other instrument examples include `msi` (Sentinel-2), `aster` (Terra), and `modis` (Terra and Aqua). **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 @@ -45,58 +42,34 @@ is technically referring to a pair of sensors on two different satellites, whose 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. +**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. + +**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. + ``` Planet example: ``` { - "stac_version": "0.8.1", - "stac_extensions": ["eo"], - "id": "20171110_121030_1013", + "stac_version": "0.9.0", + "stac_extensions": [ + "sat" + ], + "id": "20171110", "type": "Feature", ... "properties": { - ... - "eo:bands": [ - { - "full_width_half_max": 0.08, - "center_wavelength": 0.63, - "common_name": "red" - }, - { - "full_width_half_max": 0.09, - "center_wavelength": 0.545, - "common_name": "green" - }, - { - "full_width_half_max": 0.06, - "center_wavelength": 0.485, - "common_name": "blue" - }, - { - "full_width_half_max": 0.08, - "center_wavelength": 0.82, - "common_name": "nir" - } - ] - }, - "assets": { - "analytic": { - "href": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTcxMTEwXzEyMTAxMF8xMDEzIiwgImMiOiAiUFNTY2VuZTRCYW5kIiwgInQiOiAiYW5hbHl0aWMiLCAiY3QiOiAiaXRlbS10eXBlIn0", - "title": "PSScene4Band GeoTIFF (COG)", - "type": "image/tiff; application=geotiff; profile=cloud-optimized", - "eo:bands": [0,1,2,3] - } + "platform": "mysatellite", + "instrument": "mycamera", + "constellation": "allmysatellites" } } ``` ## Implementations -A number of implementations listed on [STAC Implementations page](../../implementations.md) are making use of the core EO -properties, including the SpaceNet, CBERS, sat-api and Planet implementations. This is not marked as more mature because -the eo:bands portion is still being fleshed out. + ## Extensions From 33d67a48e62e0efe62856589fdffc3818b0b68a2 Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Thu, 7 Nov 2019 15:21:35 -0500 Subject: [PATCH 06/87] remove sat fields from sar extension --- extensions/sar/README.md | 18 ----------- extensions/sar/examples/envisat.json | 12 ++++---- extensions/sar/examples/sentinel1.json | 14 ++++----- extensions/sar/json-schema/schema.json | 42 -------------------------- 4 files changed, 13 insertions(+), 73 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 3f918d20f..6385c424d 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -35,26 +35,8 @@ The exact metadata that would appear in a STAC Collection record will vary depen | sar:observation_direction | string | Antenna pointing direction relative to the flight trajectory of the satellite, either `left` or `right`. -**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: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 index 1ed019ace..acedee060 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -1,7 +1,8 @@ { - "stac_version": "0.8.1", + "stac_version": "0.9.0", "stac_extensions": [ "datetime-range", + "sat", "sar" ], "id": "ASA_GM1_1PNPDE20090520_023957_000001022079_00118_37747_3607", @@ -23,9 +24,10 @@ "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", + "platform": "envisat", + "constellation": "envisat", + "instruments": ["asar"], + "pass_direction": "descending", "sar:instrument_mode": "GM", "sar:polarization": ["HH"], "sar:resolution_range": 1000, @@ -37,8 +39,6 @@ "sar:frequency_band": "C", "sar:center_wavelength": 5.623568898893265, "sar:center_frequency": 5.331, - "sar:pass_direction": "descending", - "sar:absolute_orbit": 37747, "sar:type": "GM1_1P", "sar:bands": [ { diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json index bed73cfaf..7c244b77c 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -3,7 +3,8 @@ "stac_extensions": [ "checksum", "datetime-range", - "sar" + "sar", + "sat" ], "id": "S1A_EW_GRDM_1SSH_20181103T235855_20181103T235955_024430_02AD5D_5616", "type": "Feature", @@ -24,9 +25,11 @@ "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", + "platform": "sentinel-1a", + "constellation": "sentinel-1", + "instruments": ["c-sar"], + "pass_direction": "ascending", + "relative_orbit": 33, "sar:instrument_mode": "EW", "sar:polarization": ["HH"], "sar:resolution_range": 50, @@ -39,9 +42,6 @@ "sar:frequency_band": "C", "sar:center_wavelength": 5.546576466235, "sar:center_frequency": 5.405, - "sar:pass_direction": "ascending", - "sar:absolute_orbit": 24430, - "sar:relative_orbit": 33, "sar:type": "GRD", "sar:bands": [ { diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index 9a278610f..e431b3370 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -21,27 +21,12 @@ "properties": { "type": "object", "required": [ - "sar:platform", - "sar:instrument", "sar:instrument_mode", "sar:frequency_band", "sar:polarization", - "sar:pass_direction", "sar:type" ], "properties": { - "sar:platform": { - "title": "Platform", - "type": "string" - }, - "sar:constellation": { - "title": "Constellation", - "type": "string" - }, - "sar:instrument": { - "title": "Instrument", - "type": "string" - }, "sar:instrument_mode": { "title": "Instrument Mode", "type": "string", @@ -130,18 +115,6 @@ } } }, - "sar:pass_direction": { - "title": "Pass direction", - "type": [ - "string", - "null" - ], - "enum": [ - "ascending", - "descending", - null - ] - }, "sar:type": { "title": "Product type", "type": "string", @@ -194,21 +167,6 @@ "left", "right" ] - }, - "sar:absolute_orbit": { - "title": "Absolute orbit numbers", - "type": "integer", - "minimum": 0 - }, - "sar:relative_orbit": { - "type": "integer", - "minimum": 1 - }, - "sar:incidence_angle": { - "title": "Center incidence angle", - "type": "number", - "minimum": 0, - "maximum": 90 } } } From 7764376db1fc489031648313612bf124e71c5740 Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Thu, 7 Nov 2019 15:29:41 -0500 Subject: [PATCH 07/87] update changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c50b0459..b268da2a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Removed - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support +- Dropped sar:absolute_orbit field from `sar` extension due to no known use case +- Removed satellite related fields from `sar` extension due to creation of `sat` extension: `sar:platform`, `sar:instrument`, `sar:constellation`, `sar:pass_direction`, `sar:incidence_angle` +- Removed satellite related fields from `eo` extension due to creation of `sat` extension ### Changed - The STAC API endpoint `/stac` has been merged with `/` From 6ec48e38204c7dcaa2e86f4c03afa742650d677e Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Thu, 7 Nov 2019 15:29:58 -0500 Subject: [PATCH 08/87] update sat extension --- extensions/sat/README.md | 13 +- extensions/sat/examples/example-landsat8.json | 203 ++---------------- extensions/sat/json-schema/schema.json | 24 ++- 3 files changed, 39 insertions(+), 201 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 0d7dbeffc..75698c4b5 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -15,13 +15,12 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | instruments | [string] | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | | constellation | string | Name of the constellation to which the platform belongs. | | off_nadir | number | Viewing angle. The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | -| 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). | +| 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). | | 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). | | 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). | | 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). | -| pass_direction | string\|null | Direction of the orbit, either `ascending` or `descending`. | -| absolute_orbit | integer | An absolute orbit number associated with the acquisition. | -| relative_orbit | integer | A relative orbit number associated with the acquisition. | +| pass_direction | string | Direction of the orbit, either `ascending` or `descending`. | +| relative_orbit | integer | The relative orbit number at the time of acquisition. | **platform** is the unique name of the specific platform the instrument is attached to. For satellites this would @@ -42,13 +41,11 @@ is technically referring to a pair of sensors on two different satellites, whose 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. -**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. - **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. ``` -Planet example: +Example: ``` { @@ -61,7 +58,7 @@ Planet example: ... "properties": { "platform": "mysatellite", - "instrument": "mycamera", + "instruments": ["mycamera1", "mycamera2"], "constellation": "allmysatellites" } } diff --git a/extensions/sat/examples/example-landsat8.json b/extensions/sat/examples/example-landsat8.json index d150dfa28..7c6bcc2e9 100644 --- a/extensions/sat/examples/example-landsat8.json +++ b/extensions/sat/examples/example-landsat8.json @@ -1,10 +1,10 @@ { - "stac_version": "0.8.1", + "stac_version": "0.9.0", "stac_extensions": [ - "sat", - "eo" + "sat" ], - "id": "LC08_L1TP_107018_20181001_20181001_01_RT", + "id": "LC08_L1TP_107018_20181001", + "collection": "landsat-8-l1", "type": "Feature", "bbox": [ 148.13933, @@ -40,201 +40,32 @@ ] }, "properties": { - "collection": "landsat-8-l1", + "datetime": "2018-10-01T01:08:32.033Z", - "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, - "eo:gsd": 30, + "sun_azimuth": 168.8989761, + "sun_elevation": 26.32596431, "platform": "landsat-8", "instrument": "oli_tirs", "constellation": "landsat", "pass_direction": "ascending", - "off_nadir": 0, - "eo:bands": [ - { - "name": "B1", - "common_name": "coastal", - "gsd": 30, - "center_wavelength": 0.44, - "full_width_half_max": 0.02 - }, - { - "name": "B2", - "common_name": "blue", - "gsd": 30, - "center_wavelength": 0.48, - "full_width_half_max": 0.06 - }, - { - "name": "B3", - "common_name": "green", - "gsd": 30, - "center_wavelength": 0.56, - "full_width_half_max": 0.06 - }, - { - "name": "B4", - "common_name": "red", - "gsd": 30, - "center_wavelength": 0.65, - "full_width_half_max": 0.04 - }, - { - "name": "B5", - "common_name": "nir", - "gsd": 30, - "center_wavelength": 0.86, - "full_width_half_max": 0.03 - }, - { - "name": "B6", - "common_name": "swir16", - "gsd": 30, - "center_wavelength": 1.6, - "full_width_half_max": 0.08 - }, - { - "name": "B7", - "common_name": "swir22", - "gsd": 30, - "center_wavelength": 2.2, - "full_width_half_max": 0.2 - }, - { - "name": "B8", - "common_name": "pan", - "gsd": 15, - "center_wavelength": 0.59, - "full_width_half_max": 0.18 - }, - { - "name": "B9", - "common_name": "cirrus", - "gsd": 30, - "center_wavelength": 1.37, - "full_width_half_max": 0.02 - }, - { - "name": "B10", - "common_name": "lwir11", - "gsd": 100, - "center_wavelength": 10.9, - "full_width_half_max": 0.8 - }, - { - "name": "B11", - "common_name": "lwir12", - "gsd": 100, - "center_wavelength": 12, - "full_width_half_max": 1 - } - ] + "off_nadir": 0 }, "assets": { - "ANG": { - "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_ANG.txt", - "title": "Angle coefficients file", - "type": "text/plain" - }, - "B1": { - "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_B1.TIF", - "type": "image/tiff; application=geotiff", - "eo:bands": [ - 0 - ], - "title": "Band 1 (coastal)" - }, - "B2": { + "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", - "eo:bands": [ - 1 - ], "title": "Band 2 (blue)" }, - "B3": { + "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", - "eo:bands": [ - 2 - ], "title": "Band 3 (green)" }, - "B4": { + "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", - "eo:bands": [ - 3 - ], "title": "Band 4 (red)" }, - "B5": { - "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_B5.TIF", - "type": "image/tiff; application=geotiff", - "eo:bands": [ - 4 - ], - "title": "Band 5 (nir)" - }, - "B6": { - "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_B6.TIF", - "type": "image/tiff; application=geotiff", - "eo:bands": [ - 5 - ], - "title": "Band 6 (swir16)" - }, - "B7": { - "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_B7.TIF", - "type": "image/tiff; application=geotiff", - "eo:bands": [ - 6 - ], - "title": "Band 7 (swir22)" - }, - "B8": { - "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_B8.TIF", - "type": "image/tiff; application=geotiff", - "eo:bands": [ - 7 - ], - "title": "Band 8 (pan)" - }, - "B9": { - "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_B9.TIF", - "type": "image/tiff; application=geotiff", - "eo:bands": [ - 8 - ], - "title": "Band 9 (cirrus)" - }, - "B10": { - "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_B10.TIF", - "type": "image/tiff; application=geotiff", - "eo:bands": [ - 9 - ], - "title": "Band 10 (lwir)" - }, - "B11": { - "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_B11.TIF", - "type": "image/tiff; application=geotiff", - "eo:bands": [ - 10 - ], - "title": "Band 11 (lwir)" - }, - "BQA": { - "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_BQA.TIF", - "title": "Band quality data", - "type": "image/tiff; application=geotiff" - }, - "MTL": { - "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_MTL.txt", - "title": "original metadata file", - "type": "text/plain" - }, "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", @@ -248,16 +79,8 @@ }, "links": [ { - "rel": "self", - "href": "https://odu9mlf7d6.execute-api.us-east-1.amazonaws.com/stage/search?id=LC08_L1TP_107018_20181001_20181001_01_RT" - }, - { - "rel": "parent", - "href": "https://odu9mlf7d6.execute-api.us-east-1.amazonaws.com/stage/stac/collections/landsat-8-l1" - }, - { - "rel": "root", - "href": "https://odu9mlf7d6.execute-api.us-east-1.amazonaws.com/stage/stac" + "rel": "collection", + "href": "http://landsat-stac.s3.amazonaws.com/landsat-8-l1/catalog.json" } ] } diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index ee28c7101..6f8e2200d 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -22,7 +22,7 @@ "type": "object", "required": [ "platform", - "instrument" + "instruments" ], "properties": { "platform": { @@ -33,9 +33,9 @@ "title": "Constellation", "type": "string" }, - "instrument": { + "instruments": { "title": "Instrument", - "type": "string" + "type": "array" }, "off_nadir": { "title": "Off Nadir", @@ -43,6 +43,12 @@ "minimum": 0, "maximum": 90 }, + "incidence_angle": { + "title": "Center incidence angle", + "type": "number", + "minimum": 0, + "maximum": 90 + }, "azimuth": { "title": "Azimuth", "type": "number", @@ -60,6 +66,18 @@ "type": "number", "minimum": 0, "maximum": 90 + }, + "relative_orbit": { + "type": "integer", + "minimum": 1 + }, + "pass_direction": { + "title": "Pass direction", + "type": "string", + "enum": [ + "ascending", + "descending" + ] } } } From bbe0b5c2a5374863a845141a2ac9967959ac910c Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Fri, 8 Nov 2019 16:15:34 -0500 Subject: [PATCH 09/87] add _angle to fields that are angles --- extensions/sat/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 75698c4b5..3b76f3be1 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -14,11 +14,11 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | platform | string | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. | | instruments | [string] | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | | constellation | string | Name of the constellation to which the platform belongs. | -| off_nadir | number | Viewing angle. The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | +| view_angle | number | Viewing angle. The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | | 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). | -| 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). | -| 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). | -| 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). | +| 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). | +| 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). | +| 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). | | pass_direction | string | Direction of the orbit, either `ascending` or `descending`. | | relative_orbit | integer | The relative orbit number at the time of acquisition. | From 749e97cad39692013915f460d3779d5e4ff3a9c4 Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Sat, 9 Nov 2019 01:51:40 -0500 Subject: [PATCH 10/87] add text about viewing and sun geometry --- extensions/sat/README.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 3b76f3be1..ab9d10012 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -22,7 +22,6 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | pass_direction | string | Direction of the orbit, either `ascending` or `descending`. | | relative_orbit | integer | The relative orbit number at the time of acquisition. | - **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, @@ -43,10 +42,20 @@ part of a constellation, but these combine to form the logical collection referr **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. +### Viewing and sun geometry -``` -Example: +The 2d angles (look_angle, incidence_angle, and sun_elevation) 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. These angles are illustrated below. + +The look angle (look_angle) and the incidence angle (incidence_angle) are related. When the look 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 look 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, look angle is preferred. + + +The azimuth angles 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", From ca37e5b01b1efd7b354b02588a5b9bd1981b2be8 Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Sat, 9 Nov 2019 01:56:18 -0500 Subject: [PATCH 11/87] sat extension geometry updates --- extensions/sat/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index ab9d10012..436283914 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -14,7 +14,7 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | platform | string | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. | | instruments | [string] | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | | constellation | string | Name of the constellation to which the platform belongs. | -| view_angle | number | Viewing angle. The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | +| off_nadir_angle | number | The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | | 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). | | 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). | | 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). | @@ -44,11 +44,11 @@ part of a constellation, but these combine to form the logical collection referr ### Viewing and sun geometry -The 2d angles (look_angle, incidence_angle, and sun_elevation) 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. These angles are illustrated below. +The 2d angles (off_nadir_angle, incidence_angle, and sun_elevation) 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. These angles are illustrated below. -The look angle (look_angle) and the incidence angle (incidence_angle) are related. When the look 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 look 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, look angle is preferred. +The off-nadir angle (off_nadir_angle) and the incidence angle (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 azimuth angles indicate the position of the viewed scene and the sun by the angle from true north, as shown below. From 6f87188597a74d50c0b2ee099d9d4ccd5e644399 Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Sat, 9 Nov 2019 02:07:05 -0500 Subject: [PATCH 12/87] change pass_direction to orbit state and explain what it is --- extensions/sat/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 436283914..b06f8198e 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -19,7 +19,7 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | 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). | | 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). | | 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). | -| pass_direction | string | Direction of the orbit, either `ascending` or `descending`. | +| orbit_state | string | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites | | relative_orbit | integer | The relative orbit number at the time of acquisition. | **platform** is the unique name of the specific platform the instrument is attached to. For satellites this would @@ -38,9 +38,11 @@ specific platform the data came from, for example, from either of the Sentinel-2 `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. +part of a constellation, but these combine to form the logical collection referred to as MODIS. -**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. +**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`. + +**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 From 74c9f94c42727d0c82682b0e06e79781fc006ef2 Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Sat, 9 Nov 2019 02:09:29 -0500 Subject: [PATCH 13/87] clarification on orbit state and daytime/nighttime --- extensions/sat/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index b06f8198e..c3fa9c9ad 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -40,7 +40,7 @@ is technically referring to a pair of sensors on two different satellites, whose 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. -**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`. +**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. **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. From f6c5159c18dfbec75648e339a18b36067e9aefb6 Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Sat, 9 Nov 2019 02:12:24 -0500 Subject: [PATCH 14/87] expand example for sat extension --- extensions/sat/README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index c3fa9c9ad..3f39578c2 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -70,7 +70,14 @@ Example: "properties": { "platform": "mysatellite", "instruments": ["mycamera1", "mycamera2"], - "constellation": "allmysatellites" + "constellation": "allmysatellites", + "off_nadir_angle": 0, + "incidence_angle": 90, + "sun_elevation_angle": 45.0, + "azimuth_angle": 23.9, + "sun_azimuth_angle": 56.4, + "orbit_state": "descending", + "relative_orbit": 4 } } ``` From 275b5b12e471c2a4bcbd96e3c0ecab48bc0a36bd Mon Sep 17 00:00:00 2001 From: matthewhanson Date: Mon, 11 Nov 2019 01:15:15 -0500 Subject: [PATCH 15/87] remove fields from eo extension that have been moved to sat extension --- extensions/eo/README.md | 29 --------------- extensions/eo/examples/example-landsat8.json | 12 +++---- extensions/eo/json-schema/schema.json | 38 -------------------- 3 files changed, 6 insertions(+), 73 deletions(-) diff --git a/extensions/eo/README.md b/extensions/eo/README.md index 6b58a51ef..e17f40a1b 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -26,16 +26,9 @@ 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 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](#band-object)] | **REQUIRED.** This is a list of the available bands where each item is a [Band Object](#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). | -| eo: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). | -| eo: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). | -| eo: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). | **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 @@ -48,28 +41,6 @@ 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: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. 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). If the data does not have a CRS, such as in the case of non-rectified imagery with Ground Control diff --git a/extensions/eo/examples/example-landsat8.json b/extensions/eo/examples/example-landsat8.json index 5a0687ecd..4e1985b71 100644 --- a/extensions/eo/examples/example-landsat8.json +++ b/extensions/eo/examples/example-landsat8.json @@ -5,6 +5,7 @@ "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC08_L1TP_107018_20181001_20181001_01_RT", + "collection": "landsat-8-l1", "type": "Feature", "bbox": [ 148.13933, @@ -40,17 +41,16 @@ ] }, "properties": { - "collection": "landsat-8-l1", "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, + "sun_azimuth": 168.8989761, + "sun_elevation": 26.32596431, "landsat:path": 107, "landsat:row": 18, "eo:gsd": 30, - "eo:platform": "landsat-8", - "eo:instrument": "oli_tirs", - "eo:off_nadir": 0, + "platform": "landsat-8", + "instrument": "oli_tirs", + "off_nadir": 0, "eo:bands": [ { "name": "B1", diff --git a/extensions/eo/json-schema/schema.json b/extensions/eo/json-schema/schema.json index 8c495e18f..06aa165db 100644 --- a/extensions/eo/json-schema/schema.json +++ b/extensions/eo/json-schema/schema.json @@ -22,8 +22,6 @@ "type": "object", "required": [ "eo:gsd", - "eo:platform", - "eo:instrument", "eo:bands" ], "properties": { @@ -31,18 +29,6 @@ "title": "Ground Sample Distance", "type": "number" }, - "eo:platform": { - "title": "Platform", - "type": "string" - }, - "eo:constellation": { - "title": "Constellation", - "type": "string" - }, - "eo:instrument": { - "title": "Instrument", - "type": "string" - }, "eo:bands": { "title": "Bands", "type": "array", @@ -87,30 +73,6 @@ "type": "number", "minimum": 0, "maximum": 100 - }, - "eo:off_nadir": { - "title": "Off Nadir", - "type": "number", - "minimum": 0, - "maximum": 90 - }, - "eo:azimuth": { - "title": "Azimuth", - "type": "number", - "minimum": 0, - "maximum": 360 - }, - "eo:sun_azimuth": { - "title": "Sun Azimuth", - "type": "number", - "minimum": 0, - "maximum": 360 - }, - "eo:sun_elevation": { - "title": "Sun Elevation", - "type": "number", - "minimum": 0, - "maximum": 90 } } } From c61d6485524cc4450891c5002143d37a6d41eb02 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 11 Nov 2019 12:52:22 +0100 Subject: [PATCH 16/87] Removed data_type field again, may add it again in a separate PR. --- CHANGELOG.md | 2 +- extensions/datacube/README.md | 8 +++----- extensions/datacube/json-schema/schema.json | 9 --------- 3 files changed, 4 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65a46d341..d307027e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## Unreleased -- Data Cube extension: Allow to be used in Collections and added new fields (`data_type` and `description`). +- Data Cube extension: Allow to be used in Collections and added new field `description`. ## [v0.8.0] - 2019-10-11 diff --git a/extensions/datacube/README.md b/extensions/datacube/README.md index bd3b65ee8..7fdfac9b3 100644 --- a/extensions/datacube/README.md +++ b/extensions/datacube/README.md @@ -17,7 +17,7 @@ Data cube related metadata, especially to describe their dimensions. ### Dimension Object -A *Dimension Object* comes in different flavors, each of them is defined below. The fields define mostly very similar fields, but they differ slightly depending on their use case. All objects share the fields `type` and `description` with the same definition, but `type` may be restricted to certain values. The definition of`axis` is shared between the spatial dimensions, but restricted to certain values, too. `extent`, `values` and `step` share the same definition, but differ in the supported data types (number or string) depending on the type of dimension. Whenever it's useful to specify these fields, the objects add the additional fields `reference_system`, `data_type` and `unit` with very similar definitions across the objects. +A *Dimension Object* comes in different flavors, each of them is defined below. The fields define mostly very similar fields, but they differ slightly depending on their use case. All objects share the fields `type` and `description` with the same definition, but `type` may be restricted to certain values. The definition of`axis` is shared between the spatial dimensions, but restricted to certain values, too. `extent`, `values` and `step` share the same definition, but differ in the supported data types (number or string) depending on the type of dimension. Whenever it's useful to specify these fields, the objects add the additional fields `reference_system` and `unit` with very similar definitions across the objects. ### Horizontal Spatial Dimension Object @@ -42,14 +42,13 @@ A spatial dimension in vertical (z) direction. | type | string | **REQUIRED.** Type of the dimension, always `spatial`. | | axis | string | **REQUIRED.** Axis of the spatial dimension, always `z`. | | description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| data_type | string | The data type for the dimension values, e.g. `string`, `boolean`, `number` or `integer`. | | extent | [number\|null] | If the dimension consists of [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values, the extent (lower and upper bounds) of the values as two-dimensional array. Use `null` for open intervals. | | values | [number\|string] | A set of all potential values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | | step | number\|null | If the dimension consists of [interval](https://en.wikipedia.org/wiki/Level_of_measurement#Interval_scale) values, the space between the values. Use `null` for irregularly spaced steps. | | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | | reference_system | string\|number\|object | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON](https://proj.org/projjson.html) or [PROJ definition](https://proj.org/usage/quickstart.html). Defaults to EPSG code 4326. | -An Vertical Spatial Dimension Object MUST specify **at least** a `data_type`, an `extent` or a set of `values`. It is **recommended** to specify `data_type` and either `extent` or `values`. +An Vertical Spatial Dimension Object MUST specify an `extent` or a set of `values`. ### Temporal Dimension Object @@ -71,14 +70,13 @@ An additional dimension that is not `spatial`, but may be `temporal` if the dat | ---------------- | ---------------- | ------------------------------------------------------------ | | type | string | **REQUIRED.** Custom type of the dimension, never `spatial`. | | description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| data_type | string | The data type for the dimension values, e.g. `string`, `boolean`, `number` or `integer`. | | extent | [number\|null] | If the dimension consists of [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values, the extent (lower and upper bounds) of the values as two-dimensional array. Use `null` for open intervals. | | values | [number\|string] | A set of all potential values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | | step | number\|null | If the dimension consists of [interval](https://en.wikipedia.org/wiki/Level_of_measurement#Interval_scale) values, the space between the values. Use `null` for irregularly spaced steps. | | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | | reference_system | string | The reference system for the data. | -An Additional Dimension Object MUST specify **at least** a `data_type`, an `extent` or a set of `values`. It is **recommended** to specify `data_type` and either `extent` or `values`. +An Additional Dimension Object MUST specify an `extent` or a set of `values`. ## Implementations diff --git a/extensions/datacube/json-schema/schema.json b/extensions/datacube/json-schema/schema.json index c858b2bf7..b6d87cd3c 100644 --- a/extensions/datacube/json-schema/schema.json +++ b/extensions/datacube/json-schema/schema.json @@ -111,9 +111,6 @@ "unit": { "$ref": "#/definitions/fields/unit" }, - "data_type": { - "$ref": "#/definitions/fields/data_type" - }, "reference_system": { "type": "string" } @@ -192,9 +189,6 @@ "unit": { "$ref": "#/definitions/fields/unit" }, - "data_type": { - "$ref": "#/definitions/fields/data_type" - }, "reference_system": { "$ref": "#/definitions/fields/reference_system_spatial" } @@ -320,9 +314,6 @@ }, "description": { "type": "string" - }, - "data_type": { - "type": "string" } } } From 38de323c5852c5768e4933d9104c6237188c81e1 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 11 Nov 2019 11:30:39 -0500 Subject: [PATCH 17/87] allow multiple roles in asset --- CHANGELOG.md | 2 +- api-spec/STAC-extensions.yaml | 8 +++++--- api-spec/STAC.yaml | 8 +++++--- api-spec/openapi/STAC.yaml | 8 +++++--- item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json | 4 ++-- item-spec/examples/digitalglobe-sample.json | 2 +- item-spec/examples/itemcollection-sample-full.json | 2 +- item-spec/examples/landsat8-sample.json | 4 ++-- item-spec/examples/planet-sample.json | 2 +- item-spec/examples/sample-full.json | 4 ++-- item-spec/examples/sample.json | 2 +- item-spec/examples/sentinel2-sample.json | 6 +++--- item-spec/item-spec.md | 2 +- item-spec/json-schema/item.json | 4 ++-- 14 files changed, 32 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7150da4b4..2a5f46668 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html). - [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)). - API `search` extension renamed to `context` extension. JSON object renamed from `search:metadata` to `context` -- Added attribute `role` to Asset, to be used similarly to Link `rel` +- Added attribute `roles` to Asset, to be used similarly to Link `rel` ## [v0.8.1] - 2019-11-01 diff --git a/api-spec/STAC-extensions.yaml b/api-spec/STAC-extensions.yaml index 1c458ddbf..9db9cde3d 100644 --- a/api-spec/STAC-extensions.yaml +++ b/api-spec/STAC-extensions.yaml @@ -1732,9 +1732,11 @@ components: type: string description: Media type of the asset example: image/png - role: - type: string - description: Purpose of the asset + roles: + type: array + items: + type: string + description: Purposes of the asset example: thumbnail itemProperties: type: object diff --git a/api-spec/STAC.yaml b/api-spec/STAC.yaml index 24a46d4ac..1607a1df7 100644 --- a/api-spec/STAC.yaml +++ b/api-spec/STAC.yaml @@ -1489,9 +1489,11 @@ components: type: string description: Media type of the asset example: image/png - role: - type: string - description: Purpose of the asset + roles: + type: array + items: + type: string + description: Purposes of the asset example: thumbnail itemProperties: type: object diff --git a/api-spec/openapi/STAC.yaml b/api-spec/openapi/STAC.yaml index b004855a7..9db307333 100644 --- a/api-spec/openapi/STAC.yaml +++ b/api-spec/openapi/STAC.yaml @@ -763,9 +763,11 @@ components: type: string description: Media type of the asset example: image/png - role: - type: string - description: Purpose of the asset + roles: + type: array + items: + type: string + description: Purposes of the asset example: thumbnail itemProperties: type: object 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 329b0a7d6..cf5a85cc2 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 @@ -70,13 +70,13 @@ "thumbnail": { "href": "https://s3.amazonaws.com/cbers-meta-pds/CBERS4/MUX/177/106/CBERS_4_MUX_20181029_177_106_L4/CBERS_4_MUX_20181029_177_106.jpg", "type": "image/jpeg", - "role": "thumbnail" + "roles": [ "thumbnail" ] }, "metadata": { "href": "s3://cbers-pds/CBERS4/MUX/177/106/CBERS_4_MUX_20181029_177_106_L4/CBERS_4_MUX_20181029_177_106_L4_BAND6.xml", "title": "INPE original metadata", "type": "text/xml", - "role": "metadata" + "roles": [ "metadata" ] }, "B5": { "href": "s3://cbers-pds/CBERS4/MUX/177/106/CBERS_4_MUX_20181029_177_106_L4/CBERS_4_MUX_20181029_177_106_L4_BAND5.tif", diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json index 30452fb6b..b96a9fa82 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -60,7 +60,7 @@ }, "thumbnail": { "href": "https://15NOV09180446-M1BS-056823192010_01_P002.JPG", - "role": "thumbnail" + "roles": [ "thumbnail" ] } }, "properties": { diff --git a/item-spec/examples/itemcollection-sample-full.json b/item-spec/examples/itemcollection-sample-full.json index e783d6af4..6017a27fa 100644 --- a/item-spec/examples/itemcollection-sample-full.json +++ b/item-spec/examples/itemcollection-sample-full.json @@ -73,7 +73,7 @@ "thumbnail": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png", "title": "Thumbnail", - "role": "thumbnail" + "roles": [ "thumbnail" ] } } } diff --git a/item-spec/examples/landsat8-sample.json b/item-spec/examples/landsat8-sample.json index 7c7e0586a..fbfac0d67 100644 --- a/item-spec/examples/landsat8-sample.json +++ b/item-spec/examples/landsat8-sample.json @@ -68,12 +68,12 @@ "thumbnail": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_thumb_large.jpg", "type": "image/jpeg", - "role": "thumbnail" + "roles": [ "thumbnail" ] }, "metadata": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_MTL.txt", "type": "mtl", - "role": "metadata" + "roles": ["metadata"] }, "B1": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B1.TIF", diff --git a/item-spec/examples/planet-sample.json b/item-spec/examples/planet-sample.json index 0717ca467..0510c35ed 100644 --- a/item-spec/examples/planet-sample.json +++ b/item-spec/examples/planet-sample.json @@ -91,7 +91,7 @@ "href": "https://api.planet.com/data/v1/item-types/PSScene4Band/items/20171110_121030_1013/thumb", "title": "Thumbnail", "status": "active", - "role": "thumbnail" + "roles": [ "thumbnail" ] }, "analytic": { "href": "https://api.planet.com/data/v1/assets/eyJpIjogIjIwMTcxMTEwXzEyMTAxMF8xMDEzIiwgImMiOiAiUFNTY2VuZTRCYW5kIiwgInQiOiAiYW5hbHl0aWMiLCAiY3QiOiAiaXRlbS10eXBlIn0", diff --git a/item-spec/examples/sample-full.json b/item-spec/examples/sample-full.json index 083d3390f..b07e0578e 100644 --- a/item-spec/examples/sample-full.json +++ b/item-spec/examples/sample-full.json @@ -64,7 +64,7 @@ "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png", "title": "Thumbnail", "type": "image/png", - "role": "thumbnail" + "roles": [ "thumbnail" ] }, "udm": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/UDM.tif", @@ -74,7 +74,7 @@ "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/extended-metadata.json", "title": "Extended Metadata", "type": "application/json", - "role": "thumbnail" + "roles": [ "thumbnail" ] }, "ephemeris": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/S3-20160503_132130_04.EPH", diff --git a/item-spec/examples/sample.json b/item-spec/examples/sample.json index 5a97195dc..a83e940dd 100644 --- a/item-spec/examples/sample.json +++ b/item-spec/examples/sample.json @@ -38,7 +38,7 @@ "thumbnail": { "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png", "title": "Thumbnail", - "role": "thumbnail" + "roles": [ "thumbnail" ] } } } \ No newline at end of file diff --git a/item-spec/examples/sentinel2-sample.json b/item-spec/examples/sentinel2-sample.json index 586f3ddfa..5b7650a4b 100644 --- a/item-spec/examples/sentinel2-sample.json +++ b/item-spec/examples/sentinel2-sample.json @@ -58,7 +58,7 @@ "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/metadata.xml", "title": "Tile metadata", "type": "application/xml", - "role": "metadata" + "roles": [ "metadata" ] }, "tileInfo": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/tileInfo.json", @@ -74,7 +74,7 @@ "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/qi/L2A_PVI.jp2", "title": "True color thumbnail", "type": "image/jp2", - "role": "thumbnail" + "roles": [ "thumbnail" ] }, "B02_10m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R10m/B02.jp2", @@ -279,7 +279,7 @@ "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/TCI.jp2", "title": "True Color Image (60m)", "type": "image/jp2", - "role": "overview" + "roles": [ "overview" ] }, "WVP_60m": { "href": "s3://sentinel-s2-l2a/tiles/35/V/MK/2018/6/5/0/R60m/WVP.jp2", diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index ecb1a196d..799e96524 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -167,7 +167,7 @@ or streamed. It is allowed to add additional fields. | href | string | **REQUIRED.** Link to the asset object. Relative and absolute links are both allowed. | | title | string | The displayed title for clients and users. | | type | string | [Media type](#media-types) of the asset. | -| role | string | The semantic purpose of the asset. | +| roles | [string] | The semantic purpose of the asset. | **role** is intended to be a value that describes semantic usage of an asset, similarly to the use of `rel` in Link. diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index f51de2b43..58b4146a3 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -209,8 +209,8 @@ "title": "Asset type", "type": "string" }, - "role": { - "title": "Asset role", + "roles": { + "title": "Asset roles", "type": "string" } } From 5afcff7bfb0a2986a30d07e1f5c834ac98e21286 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Wed, 13 Nov 2019 11:10:58 -0500 Subject: [PATCH 18/87] update roles example --- api-spec/STAC-extensions.yaml | 3 ++- api-spec/STAC.yaml | 3 ++- api-spec/openapi/STAC.yaml | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/api-spec/STAC-extensions.yaml b/api-spec/STAC-extensions.yaml index 9db9cde3d..c635db23e 100644 --- a/api-spec/STAC-extensions.yaml +++ b/api-spec/STAC-extensions.yaml @@ -1737,7 +1737,8 @@ components: items: type: string description: Purposes of the asset - example: thumbnail + example: + - thumbnail itemProperties: type: object required: diff --git a/api-spec/STAC.yaml b/api-spec/STAC.yaml index 1607a1df7..7e66541f4 100644 --- a/api-spec/STAC.yaml +++ b/api-spec/STAC.yaml @@ -1494,7 +1494,8 @@ components: items: type: string description: Purposes of the asset - example: thumbnail + example: + - thumbnail itemProperties: type: object required: diff --git a/api-spec/openapi/STAC.yaml b/api-spec/openapi/STAC.yaml index 9db307333..c927bf270 100644 --- a/api-spec/openapi/STAC.yaml +++ b/api-spec/openapi/STAC.yaml @@ -768,7 +768,8 @@ components: items: type: string description: Purposes of the asset - example: thumbnail + example: + - thumbnail itemProperties: type: object required: From 252c31649eefc088bcb868c6a5c09db22219df7b Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Wed, 13 Nov 2019 14:15:21 -0500 Subject: [PATCH 19/87] fix merge conflict --- extensions/sar/examples/envisat.json | 3 --- 1 file changed, 3 deletions(-) diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index 18090c21a..37365ede0 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -25,13 +25,10 @@ "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", -<<<<<<< HEAD "platform": "envisat", "constellation": "envisat", "instruments": ["asar"], "pass_direction": "descending", -======= ->>>>>>> dev "sar:instrument_mode": "GM", "sar:polarization": ["HH"], "sar:resolution_range": 1000, From 2af8b17ec5abfb3e06cde7407b605d3ed7d93dfa Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Wed, 13 Nov 2019 14:22:15 -0500 Subject: [PATCH 20/87] update some examples --- extensions/sar/examples/envisat.json | 4 ++-- extensions/sat/README.md | 21 ------------------- extensions/sat/examples/example-landsat8.json | 4 ++-- extensions/sat/json-schema/schema.json | 12 ----------- 4 files changed, 4 insertions(+), 37 deletions(-) diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index 37365ede0..6fb8d1a3c 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -23,8 +23,8 @@ }, "properties": { "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", + "start_datetime": "2009-05-20T02:40:01.042784Z", + "end_datetime": "2009-05-20T02:41:31.483865Z", "platform": "envisat", "constellation": "envisat", "instruments": ["asar"], diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 3f39578c2..0375c3391 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -11,9 +11,6 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | Field Name | Type | Description | | ---------------- | ------------------------ | ----------- | -| platform | string | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. | -| instruments | [string] | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | -| constellation | string | Name of the constellation to which the platform belongs. | | off_nadir_angle | number | The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | | 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). | | 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). | @@ -22,24 +19,6 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | orbit_state | string | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites | | relative_orbit | integer | The relative orbit number at the time of acquisition. | -**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). - -**instruments** is an array of all the sensors used in the creation of the data. 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 so would be specified as ['oli', 'TItirsRS']. Other instrument examples include `msi` (Sentinel-2), `aster` (Terra), and `modis` (Terra and Aqua). - -**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. - **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. **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. diff --git a/extensions/sat/examples/example-landsat8.json b/extensions/sat/examples/example-landsat8.json index 7c6bcc2e9..35ab883c9 100644 --- a/extensions/sat/examples/example-landsat8.json +++ b/extensions/sat/examples/example-landsat8.json @@ -1,7 +1,8 @@ { "stac_version": "0.9.0", "stac_extensions": [ - "sat" + "sat", + "instrument" ], "id": "LC08_L1TP_107018_20181001", "collection": "landsat-8-l1", @@ -40,7 +41,6 @@ ] }, "properties": { - "datetime": "2018-10-01T01:08:32.033Z", "sun_azimuth": 168.8989761, "sun_elevation": 26.32596431, diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index 6f8e2200d..38d6673f1 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -25,18 +25,6 @@ "instruments" ], "properties": { - "platform": { - "title": "Platform", - "type": "string" - }, - "constellation": { - "title": "Constellation", - "type": "string" - }, - "instruments": { - "title": "Instrument", - "type": "array" - }, "off_nadir": { "title": "Off Nadir", "type": "number", From 14a6b3b2ecff472585b238774a11ca4ae1df4f71 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Wed, 13 Nov 2019 14:48:16 -0500 Subject: [PATCH 21/87] sat ext readme updates --- extensions/sat/README.md | 6 +++--- extensions/sat/json-schema/schema.json | 21 +++++++++++---------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 0375c3391..46cf4ea7c 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -25,13 +25,13 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds ### Viewing and sun geometry -The 2d angles (off_nadir_angle, incidence_angle, and sun_elevation) 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. These angles are illustrated below. +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. These angles are illustrated below. -The off-nadir angle (off_nadir_angle) and the incidence angle (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 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 azimuth angles indicate the position of the viewed scene and the sun by the angle from true north, as shown below. +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. diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index 38d6673f1..4847b3056 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -25,7 +25,7 @@ "instruments" ], "properties": { - "off_nadir": { + "off_nadir_angle": { "title": "Off Nadir", "type": "number", "minimum": 0, @@ -37,20 +37,20 @@ "minimum": 0, "maximum": 90 }, - "azimuth": { - "title": "Azimuth", + "azimuth_angle": { + "title": "Azimuth angle", "type": "number", "minimum": 0, "maximum": 360 }, - "sun_azimuth": { - "title": "Sun Azimuth", + "sun_azimuth_angle": { + "title": "Sun Azimuth angle", "type": "number", "minimum": 0, "maximum": 360 }, - "sun_elevation": { - "title": "Sun Elevation", + "sun_elevation_angle": { + "title": "Sun Elevation angle", "type": "number", "minimum": 0, "maximum": 90 @@ -59,12 +59,13 @@ "type": "integer", "minimum": 1 }, - "pass_direction": { - "title": "Pass direction", + "orbit_state": { + "title": "Orbit State", "type": "string", "enum": [ "ascending", - "descending" + "descending", + "geostationary" ] } } From ff5c050c8651c1b31cb97eba06a05ff91a9ddfe8 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Mon, 18 Nov 2019 00:47:36 -0500 Subject: [PATCH 22/87] update sat_extension to use sat prefix and update examples --- api-spec/openapi/STAC.yaml | 10 +++--- catalog-spec/examples/summaries-s2.json | 4 +-- collection-spec/collection-spec.md | 14 ++++---- .../examples/landsat-collection.json | 2 +- collection-spec/examples/sentinel2.json | 4 +-- extensions/README.md | 4 +-- .../asset/examples/example-landsat8.json | 2 +- extensions/eo/examples/example-landsat8.json | 6 ++-- extensions/sat/README.md | 34 +++++++++---------- extensions/sat/examples/example-landsat8.json | 8 ++--- extensions/sat/json-schema/schema.json | 14 ++++---- .../examples/example-search.json | 2 +- .../CBERS_4_MUX_20181029_177_106_L4.json | 6 ++-- item-spec/examples/digitalglobe-sample.json | 6 ++-- item-spec/examples/landsat8-sample.json | 8 ++--- item-spec/examples/planet-sample.json | 6 ++-- item-spec/examples/sample-full.json | 6 ++-- 17 files changed, 68 insertions(+), 68 deletions(-) diff --git a/api-spec/openapi/STAC.yaml b/api-spec/openapi/STAC.yaml index 400f12810..1c9f9abea 100644 --- a/api-spec/openapi/STAC.yaml +++ b/api-spec/openapi/STAC.yaml @@ -241,10 +241,10 @@ components: - sentinel-2 'instruments': - msi - 'eo:off_nadir': + 'sat:off_nadir_angle': min: 0 max: 100 - 'eo:sun_elevation': + 'sat:sun_elevation_angle': min: 6.78 max: 89.9 'eo:bands': @@ -705,14 +705,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'eo:sun_azimuth': 168.7 + 'sat:sun_azimuth_angle': 168.7 'eo:cloud_cover': 0.12 - 'eo:off_nadir': 1.4 + 'sat:off_nadir_angle': 1.4 'platform': coolsat2 'instruments': - cool_sensor_v1 'eo:bands': [] - 'eo:sun_elevation': 33.4 + 'sat:sun_elevation_angle': 33.4 'eo:gsd': 0.512 collection: CS3 links: diff --git a/catalog-spec/examples/summaries-s2.json b/catalog-spec/examples/summaries-s2.json index 09b6ebae1..1d01990e6 100644 --- a/catalog-spec/examples/summaries-s2.json +++ b/catalog-spec/examples/summaries-s2.json @@ -14,11 +14,11 @@ "platform": ["sentinel-2a","sentinel-2b"], "constellation": ["sentinel-2"], "instruments": [["msi"]], - "eo:off_nadir": { + "sat:off_nadir_angle": { "min": 0.0, "max": 100 }, - "eo:sun_elevation": { + "sat:sun_elevation_angle": { "min": 6.78, "max": 89.9 }, diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index f45fa2a04..c6ef7ebb0 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -150,7 +150,7 @@ Implementors are free to add other derived statistical values to the object, for The `properties` field in STAC collections can be used in two ways, either to **move common fields in Items to the parent Collection** or to describe **standalone Collections** better that don't reference any items. Any field that can be used under an Items `properties` can be removed and added to the Collection `properties`. Since a Collection contains no properties itself, anything under properties are metadata fields that are common across all member Items. -To **move common fields in Items to the parent Collection**, the collection specification allows one to more fields that are common across all linked Items to be moved out of the respective Items and into the parent STAC Collection, from which the Items then inherit. 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 have an `eo:off_nadir` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellites that can be pointed will have varying `eo:off_nadir` values. This allows 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 `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 common fields. +To **move common fields in Items to the parent Collection**, the collection specification allows one to more fields that are common across all linked Items to be moved out of the respective Items and into the parent STAC Collection, from which the Items then inherit. 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 have an `sat:off_nadir_angle` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellites that can be pointed will have varying `sat:off_nadir_angle` values. This allows 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 `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 common fields. STAC Collections which don't link to any Item are called **standalone Collections**. To describe them with more fields than the Collection fields has to offer, it is allowed to re-use the metadata fields defined by content extensions for Items. Whenever suitable, the `properties` are used in the same way as if they were common fields across theoretical Items. This makes much sense for fields such as `platform` or `eo:epsg`, which are often the same for a whole collection, but doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection. The data provider is free to decide, which fields are reasoable to be used. @@ -171,7 +171,7 @@ An incomplete Collection: "eo:gsd": 30, "platform": "landsat-8", "instruments": ["oli", "tirs"], - "eo:off_nadir": 0, + "sat:off_nadir_angle": 0, "eo:bands": [ { "name": "B1", @@ -199,8 +199,8 @@ An incomplete item: "collection": "landsat-8-l1", "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, + "sat:sun_azimuth_angle": 168.8989761, + "sat:sun_elevation_angle": 26.32596431, "landsat:path": 107, "landsat:row": 18 }, @@ -222,15 +222,15 @@ The merged Item then looks like this: "collection": "landsat-8-l1", "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, + "sat:sun_azimuth_angle": 168.8989761, + "sat:sun_elevation_angle": 26.32596431, "landsat:path": 107, "landsat:row": 18, "eo:gsd": 30, "platform": "landsat-8", "constellation": "landsat-8", "instruments": ["oli", "tirs"], - "eo:off_nadir": 0, + "sat:off_nadir_angle": 0, "eo:bands": [ { "name": "B1", diff --git a/collection-spec/examples/landsat-collection.json b/collection-spec/examples/landsat-collection.json index 772f2bc2c..92dd7f91c 100644 --- a/collection-spec/examples/landsat-collection.json +++ b/collection-spec/examples/landsat-collection.json @@ -64,7 +64,7 @@ "eo:gsd": 30, "platform": "landsat-8", "instruments": ["oli", "tirs"], - "eo:off_nadir": 0, + "sat:off_nadir_angle": 0, "eo:bands": [ { "name": "B1", diff --git a/collection-spec/examples/sentinel2.json b/collection-spec/examples/sentinel2.json index cb349a115..e594d93f7 100644 --- a/collection-spec/examples/sentinel2.json +++ b/collection-spec/examples/sentinel2.json @@ -54,11 +54,11 @@ "platform": ["sentinel-2a","sentinel-2b"], "constellation": ["sentinel-2"], "instruments": [["msi"]], - "eo:off_nadir": { + "sat:off_nadir_angle": { "min": 0.0, "max": 100 }, - "eo:sun_elevation": { + "sat:sun_elevation_angle": { "min": 6.78, "max": 89.9 }, diff --git a/extensions/README.md b/extensions/README.md index c16056b9f..eb1b15597 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -51,12 +51,12 @@ An extension can add new fields to STAC entities (content extension), or can add | [Checksum](checksum/README.md) (`checksum`) | Item, Catalog, Collection | Provides a way to specify file checksums for assets and links in Items, Catalogs and Collections. | *Proposal* | | [Data Cube](datacube/README.md) (`cube`) | Item | Data Cube related metadata, especially to describe their dimensions. | *Proposal* | | [Datetime Range](datetime-range/README.md) (`dtr`) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | -| [EO](eo/README.md) (`eo`) | Item | Covers electro-optical data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, off nadir, sun angle + elevation, gsd and more. | *Pilot* | +| [EO](eo/README.md) (`eo`) | Item | Covers electro-optical data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, gsd and more. | *Pilot* | | [Instrument](instrument/README.md) (-) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | | [Label](label/README.md) (`label`) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | | [Point Cloud](pointcloud/README.md) (`pc`) | Item | Provides a way to describe point cloud datasets. The point clouds can come from either active or passive sensors, and data is frequently acquired using tools such as LiDAR or coincidence-matched imagery. | *Proposal* | | [SAR](sar/README.md) (`sar`) | Item | Covers synthetic-aperture radar data that represents a snapshot of the earth for a single date and time. | *Proposal* | -| [sat](sat/README.md) (-) | Item | Satellite related metadata for data collected from satellites. | *Proposal* | +| [sat](sat/README.md) (`sat`) | Item | Satellite related metadata for data collected from satellites. | *Proposal* | | [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* | diff --git a/extensions/asset/examples/example-landsat8.json b/extensions/asset/examples/example-landsat8.json index 50119fb60..d2374f113 100644 --- a/extensions/asset/examples/example-landsat8.json +++ b/extensions/asset/examples/example-landsat8.json @@ -66,7 +66,7 @@ "eo:gsd": 15, "platform": "landsat-8", "instruments": ["oli", "tirs"], - "eo:off_nadir": 0, + "sat:off_nadir_angle": 0, "eo:bands": [ { "name": "B1", diff --git a/extensions/eo/examples/example-landsat8.json b/extensions/eo/examples/example-landsat8.json index c66736206..b4f49a2af 100644 --- a/extensions/eo/examples/example-landsat8.json +++ b/extensions/eo/examples/example-landsat8.json @@ -44,14 +44,14 @@ "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "sun_azimuth": 168.8989761, - "sun_elevation": 26.32596431, + "sat:sun_azimuth_angle": 168.8989761, + "sat:sun_elevation_angle": 26.32596431, "landsat:path": 107, "landsat:row": 18, "eo:gsd": 30, "platform": "landsat-8", "instrument": ["oli", "tirs"], - "off_nadir": 0, + "sat:off_nadir_angle": 0, "eo:bands": [ { "name": "B1", diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 46cf4ea7c..9a31ee3b4 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -1,4 +1,4 @@ -# sat Extension Specification (-) +# sat Extension Specification (`sat`) **Extension [Maturity Classification](../README.md#extension-maturity): Proposal** @@ -11,17 +11,17 @@ This document explains the fields of the sat Extension to a STAC Item. Sat adds | Field Name | Type | Description | | ---------------- | ------------------------ | ----------- | -| off_nadir_angle | number | The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | -| 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). | -| 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). | -| 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). | -| 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). | -| orbit_state | string | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites | -| relative_orbit | integer | The relative orbit number at the time of acquisition. | +| 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. | -**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: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. -**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. +**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 @@ -50,13 +50,13 @@ Example: "platform": "mysatellite", "instruments": ["mycamera1", "mycamera2"], "constellation": "allmysatellites", - "off_nadir_angle": 0, - "incidence_angle": 90, - "sun_elevation_angle": 45.0, - "azimuth_angle": 23.9, - "sun_azimuth_angle": 56.4, - "orbit_state": "descending", - "relative_orbit": 4 + "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 } } ``` diff --git a/extensions/sat/examples/example-landsat8.json b/extensions/sat/examples/example-landsat8.json index 35ab883c9..f3ae4bfee 100644 --- a/extensions/sat/examples/example-landsat8.json +++ b/extensions/sat/examples/example-landsat8.json @@ -42,13 +42,13 @@ }, "properties": { "datetime": "2018-10-01T01:08:32.033Z", - "sun_azimuth": 168.8989761, - "sun_elevation": 26.32596431, + "sat:sun_azimuth_angle": 168.8989761, + "sat:sun_elevation_angle": 26.32596431, "platform": "landsat-8", "instrument": "oli_tirs", "constellation": "landsat", - "pass_direction": "ascending", - "off_nadir": 0 + "sat:orbit_state": "ascending", + "sat:off_nadir_angle": 0 }, "assets": { "blue": { diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index 4847b3056..cd59dd466 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -25,41 +25,41 @@ "instruments" ], "properties": { - "off_nadir_angle": { + "sat:off_nadir_angle": { "title": "Off Nadir", "type": "number", "minimum": 0, "maximum": 90 }, - "incidence_angle": { + "sat:incidence_angle": { "title": "Center incidence angle", "type": "number", "minimum": 0, "maximum": 90 }, - "azimuth_angle": { + "sat:azimuth_angle": { "title": "Azimuth angle", "type": "number", "minimum": 0, "maximum": 360 }, - "sun_azimuth_angle": { + "sat:sun_azimuth_angle": { "title": "Sun Azimuth angle", "type": "number", "minimum": 0, "maximum": 360 }, - "sun_elevation_angle": { + "sat:sun_elevation_angle": { "title": "Sun Elevation angle", "type": "number", "minimum": 0, "maximum": 90 }, - "relative_orbit": { + "sat:relative_orbit": { "type": "integer", "minimum": 1 }, - "orbit_state": { + "sat:orbit_state": { "title": "Orbit State", "type": "string", "enum": [ diff --git a/extensions/single-file-stac/examples/example-search.json b/extensions/single-file-stac/examples/example-search.json index 27d616f44..31e940388 100644 --- a/extensions/single-file-stac/examples/example-search.json +++ b/extensions/single-file-stac/examples/example-search.json @@ -394,7 +394,7 @@ "eo:gsd": 15, "platform": "landsat-8", "instruments": ["oli", "tirs"], - "eo:off_nadir": 0, + "sat:off_nadir_angle": 0, "eo:bands": [ { "name": "B1", 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 329b0a7d6..9d7c474c5 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 @@ -43,9 +43,9 @@ ], "properties": { "datetime": "2018-10-29T14:24:54Z", - "eo:sun_azimuth": 111.113, - "eo:sun_elevation": 65.8018, - "eo:off_nadir": -0.00751271, + "sat:sun_azimuth_angle": 111.113, + "sat:sun_elevation_angle": 65.8018, + "sat:off_nadir_angle": -0.00751271, "eo: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 0d1355bda..e63556e44 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -70,12 +70,12 @@ "DigitalGlobeProduct", "1BProduct" ], - "eo:sun_azimuth": 168.7, + "sat:sun_azimuth_angle": 168.7, "eo:cloud_cover": 50, - "eo:off_nadir": 18.4, + "sat:off_nadir_angle": 18.4, "eo:azimuth": 34.5, "platform": "worldview02", - "eo:sun_elevation": 33.4, + "sat:sun_elevation_angle": 33.4, "eo:gsd": 2.047, "eo:epsg": null, "dg:catalog_id": "103001004B316600", diff --git a/item-spec/examples/landsat8-sample.json b/item-spec/examples/landsat8-sample.json index 7c7e0586a..281381106 100644 --- a/item-spec/examples/landsat8-sample.json +++ b/item-spec/examples/landsat8-sample.json @@ -40,10 +40,10 @@ "collection": "L1T", "eo:gsd": 30.0, "eo:cloud_cover" : 10, - "eo:off_nadir" : 0.000, - "eo:azimuth": 0.00, - "eo:sun_azimuth" : 149.01607154, - "eo:sun_elevation" : 59.21424700, + "sat:off_nadir_angle" : 0.000, + "sat:azimuth_angle": 0.00, + "sat:sun_azimuth_angle" : 149.01607154, + "sat:sun_elevation_angle" : 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 0717ca467..1b219af33 100644 --- a/item-spec/examples/planet-sample.json +++ b/item-spec/examples/planet-sample.json @@ -62,9 +62,9 @@ "datetime": "2017-11-10T12:10:30.535417Z", "eo:cloud_cover": 23, "eo:gsd": 3.7, - "eo:sun_azimuth": 101.8, - "eo:sun_elevation": 58.8, - "eo:off_nadir": 1, + "sat:sun_azimuth": 101.8, + "sat:sun_elevation": 58.8, + "sat:off_nadir_angle": 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 776e83a55..9d7e6fc1e 100644 --- a/item-spec/examples/sample-full.json +++ b/item-spec/examples/sample-full.json @@ -33,13 +33,13 @@ "url": "https://cool-sat.com/" } ], - "eo:sun_azimuth": 168.7, + "sat:sun_azimuth_angle": 168.7, "eo:cloud_cover": 0.12, - "eo:off_nadir": 1.4, + "sat:off_nadir_angle": 1.4, "platform": "coolsat2", "instruments": ["cool_sensor_v1"], "eo:bands": [], - "eo:sun_elevation": 33.4, + "sat:sun_elevation_angle": 33.4, "eo:gsd": 0.512, "cs:type": "scene", "cs:anomalous_pixels": 0.14, From ef9036d3405991af607dbebce1b248faecee46ab Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 19 Nov 2019 11:19:17 +0100 Subject: [PATCH 23/87] Final edits --- CHANGELOG.md | 16 ++++++++++------ extensions/datacube/README.md | 6 +++--- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d8a62ddbd..ab0b6a1da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,16 +7,20 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## Unreleased ### Added -- Added the [Version Indicators extension](extensions/version/README.md) to add `version` and `deprecated` fields to STAC Items and Collections. -- Added Instrument extension which adds fields: `platform`, `instruments`, `constellation` (all moved from EO and SAR extensions), and `mission`. - ItemCollection requires `stac_version` field, `stac_extensions` has also been added. -- Data Cube extension: Can be used in Collections, added new field `description`. -- API: Added the [Item and Collection API Version extension](api-spec/extensions/version/README.md) to support versioning in the API specification +- Extensions: + - [Version Indicators extension](extensions/version/README.md), adds `version` and `deprecated` fields to STAC Items and Collections. + - Instrument extension, adds fields: `platform`, `instruments`, `constellation` (all moved from EO and SAR extensions), and `mission`. + - Data Cube extension can be used in Collections, added new field `description`. +- STAC API: + - Added the [Item and Collection API Version extension](api-spec/extensions/version/README.md) to support versioning in the API specification ### Removed - Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead. -- Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension. -- API: Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support +- Extensions: + - Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension. +- STAC API: + - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support ### Changed - Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html). diff --git a/extensions/datacube/README.md b/extensions/datacube/README.md index 7fdfac9b3..6518e6087 100644 --- a/extensions/datacube/README.md +++ b/extensions/datacube/README.md @@ -48,7 +48,7 @@ A spatial dimension in vertical (z) direction. | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | | reference_system | string\|number\|object | The spatial reference system for the data, specified as [EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html), [PROJJSON](https://proj.org/projjson.html) or [PROJ definition](https://proj.org/usage/quickstart.html). Defaults to EPSG code 4326. | -An Vertical Spatial Dimension Object MUST specify an `extent` or a set of `values`. +An Vertical Spatial Dimension Object MUST specify an `extent` or a set of `values`. It MAY specify both. ### Temporal Dimension Object @@ -64,7 +64,7 @@ A temporal dimension based on the ISO 8601 standard. The temporal reference syst ### Additional Dimension Object -An additional dimension that is not `spatial`, but may be `temporal` if the data is not compliant with ISO 8601. +An additional dimension that is not `spatial`, but may be `temporal` if the data is not compliant with ISO 8601. | Field Name | Type | Description | | ---------------- | ---------------- | ------------------------------------------------------------ | @@ -76,7 +76,7 @@ An additional dimension that is not `spatial`, but may be `temporal` if the dat | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | | reference_system | string | The reference system for the data. | -An Additional Dimension Object MUST specify an `extent` or a set of `values`. +An Additional Dimension Object MUST specify an `extent` or a set of `values`. It MAY specify both. ## Implementations From 24dca52566b4ee6906919455ef39e9e6eec3047f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 19 Nov 2019 12:11:22 +0100 Subject: [PATCH 24/87] Revert "Making the Commons extension Core as optional field in the collections (implements #392)" + adopting recent changes --- CHANGELOG.md | 3 +- collection-spec/README.md | 4 +- collection-spec/collection-spec.md | 115 ++--------- .../examples/landsat-collection.json | 3 +- collection-spec/examples/landsat-item.json | 2 + collection-spec/json-schema/collection.json | 5 +- extensions/README.md | 1 + .../asset/examples/example-landsat8.json | 3 +- extensions/commons/README.md | 131 +++++++++++++ .../commons/examples/landsat-collection.json | 165 ++++++++++++++++ extensions/commons/examples/landsat-item.json | 181 ++++++++++++++++++ extensions/commons/json-schema/schema.json | 31 +++ extensions/eo/README.md | 13 +- extensions/sar/README.md | 11 +- extensions/scientific/README.md | 3 +- item-spec/item-spec.md | 10 +- item-spec/json-schema/item.json | 1 + 17 files changed, 558 insertions(+), 124 deletions(-) create mode 100644 extensions/commons/README.md create mode 100644 extensions/commons/examples/landsat-collection.json create mode 100644 extensions/commons/examples/landsat-item.json create mode 100644 extensions/commons/json-schema/schema.json diff --git a/CHANGELOG.md b/CHANGELOG.md index c050f3366..7726788b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Added - Added a version extension to the API specification - -### Added - Added [Version Extension](extensions/version/README.md) to version and deprecate STAC Items and Collections. ### Removed @@ -29,6 +27,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - CollectionItem field `stac_version` is now required and field `stac_extensions` is defined in schema. - Sort Extension - added non-JSON query/form parameter format - Fields extension has a simplified format for GET parameters +- Collection field `property` and the merge ability moved to a new extension 'Commons' ### Fixed diff --git a/collection-spec/README.md b/collection-spec/README.md index 825da111e..ba9f9e4a5 100644 --- a/collection-spec/README.md +++ b/collection-spec/README.md @@ -32,8 +32,8 @@ Instruction on schema validation for STAC Items can be found in the [validation STAC Collections are defined for flexibility. They only require a handful of fields, and implementors are free to add most any JSON field or object that they want via extensions. -Many fields originating from the [STAC Item spec](../item-spec/item-spec.md) can be -reused with the `properties` field. +Many fields originating from the [STAC Item spec](../item-spec/item-spec.md) can already be +reused using the [Commons extension](../extensions/commons/README.md). This flexibility and extensibility is a design goal, so that it is quite easy to implement a collection and be able to adapt it to most any data model. diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index f45fa2a04..a25407c5b 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -34,9 +34,8 @@ Implementations are encouraged, however, as good effort will be made to not chan | license | string | **REQUIRED.** Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the `license` link relation type. | | providers | [[Provider Object](#provider-object) | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | | extent | [Extent Object](#extent-object) | **REQUIRED.** Spatial and temporal extents. | -| properties | Map | Common fields across referenced items. | | summaries | Map | A map of property summaries, either a set of values or statistics such as a range. | -| links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | +| links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | **stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. @@ -146,107 +145,19 @@ Implementors are free to add other derived statistical values to the object, for | min | number\|string | **REQUIRED.** Minimum value. | | max | number\|string | **REQUIRED.** Maximum value. | -## Common Fields and Standalone Collections - -The `properties` field in STAC collections can be used in two ways, either to **move common fields in Items to the parent Collection** or to describe **standalone Collections** better that don't reference any items. Any field that can be used under an Items `properties` can be removed and added to the Collection `properties`. Since a Collection contains no properties itself, anything under properties are metadata fields that are common across all member Items. - -To **move common fields in Items to the parent Collection**, the collection specification allows one to more fields that are common across all linked Items to be moved out of the respective Items and into the parent STAC Collection, from which the Items then inherit. 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 have an `eo:off_nadir` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellites that can be pointed will have varying `eo:off_nadir` values. This allows 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 `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 common fields. - -STAC Collections which don't link to any Item are called **standalone Collections**. To describe them with more fields than the Collection fields has to offer, it is allowed to re-use the metadata fields defined by content extensions for Items. Whenever suitable, the `properties` are used in the same way as if they were common fields across theoretical Items. This makes much sense for fields such as `platform` or `eo:epsg`, which are often the same for a whole collection, but doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection. The data provider is free to decide, which fields are reasoable to be used. - -### Merging common fields into a STAC Item - -To get the complete record of an Item (both individual and commons properties), the properties from the Collection can be merged with the Item. - -An incomplete Collection: -``` -{ - "stac_version": "0.8.1", - "id": "landsat-8-l1", - "title": "Landsat 8 L1", - "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", - "extent": {...}, - "license": "PDDL-1.0", - "properties": { - "eo:gsd": 30, - "platform": "landsat-8", - "instruments": ["oli", "tirs"], - "eo:off_nadir": 0, - "eo:bands": [ - { - "name": "B1", - "common_name": "coastal", - "gsd": 30, - "center_wavelength": 0.44, - "full_width_half_max": 0.02 - }, - ... - ] - }, - "links": [...] -} -``` - -An incomplete item: -``` -{ - "stac_version": "0.8.1", - "type": "Feature", - "id": "LC08_L1TP_107018_20181001_20181001_01_RT", - "bbox": [...], - "geometry": {...}, - "properties": { - "collection": "landsat-8-l1", - "datetime": "2018-10-01T01:08:32.033Z", - "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, - "landsat:path": 107, - "landsat:row": 18 - }, - "assets": {...}, - "links": [...] -} -``` - -The merged Item then looks like this: - -``` -{ - "stac_version": "0.8.1", - "type": "Feature", - "id": "LC08_L1TP_107018_20181001_20181001_01_RT", - "bbox": [], - "geometry": {}, - "properties": { - "collection": "landsat-8-l1", - "datetime": "2018-10-01T01:08:32.033Z", - "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, - "landsat:path": 107, - "landsat:row": 18, - "eo:gsd": 30, - "platform": "landsat-8", - "constellation": "landsat-8", - "instruments": ["oli", "tirs"], - "eo:off_nadir": 0, - "eo:bands": [ - { - "name": "B1", - "common_name": "coastal", - "gsd": 30, - "center_wavelength": 0.44, - "full_width_half_max": 0.02 - }, - ... - ] - }, - "assets": {...}, - "links": [...] -} -``` +## Standalone Collections + +STAC Collections which don't link to any Item are called **standalone Collections**. +To describe them with more fields than the Collection fields has to offer, it is allowed to re-use the metadata fields defined by content extensions for Items in the `summaries` field. +This makes much sense for fields such as `platform` or `eo:epsg`, which are often the same for a whole collection, but doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection. +The data provider is free to decide, which fields are reasoable to be used. ## Extensions +Important related extensions for the STAC Collection Specification: + +* [Commons extension](../extensions/commons/README.md), which primarily allows to add shared Item metadata to Collections, + but could also be used to describe Collections better that are not referring to Items by adding additional fields from Item extensions. + Please note that this extension is only in '[proposal](../extensions/README.md#extension-maturity)' stage. + The [extensions page](../extensions/README.md) gives a full overview about relevant extensions for STAC Collections. diff --git a/collection-spec/examples/landsat-collection.json b/collection-spec/examples/landsat-collection.json index 772f2bc2c..4a3cc0da4 100644 --- a/collection-spec/examples/landsat-collection.json +++ b/collection-spec/examples/landsat-collection.json @@ -1,8 +1,7 @@ { "stac_version": "0.8.1", "stac_extensions": [ - "eo", - "instrument" + "commons" ], "id": "landsat-8-l1", "title": "Landsat 8 L1", diff --git a/collection-spec/examples/landsat-item.json b/collection-spec/examples/landsat-item.json index cda8f8907..4b52572af 100644 --- a/collection-spec/examples/landsat-item.json +++ b/collection-spec/examples/landsat-item.json @@ -1,7 +1,9 @@ { "stac_version": "0.8.1", "stac_extensions": [ + "commons", "eo", + "instrument", "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC08_L1TP_107018_20181001_20181001_01_RT", diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index 48893e86d..6ee21bf29 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -37,6 +37,7 @@ "type": "string", "enum": [ "asset", + "commons", "checksum", "scientific" ] @@ -147,10 +148,6 @@ } } } - }, - "properties": { - "title": "Common properties", - "type": "object" } } } diff --git a/extensions/README.md b/extensions/README.md index fb3c8435e..5450c8b1a 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -49,6 +49,7 @@ An extension can add new fields to STAC entities (content extension), or can add | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------ | -------- | | [Asset Definition](asset/README.md) (-) | Collection | Provides a way to specify details about what assets may be found in Items belonging to a collection | *Proposal* | | [Checksum](checksum/README.md) (`checksum`) | Item, Catalog, Collection | Provides a way to specify file checksums for assets and links in Items, Catalogs and Collections. | *Proposal* | +| [Commons](commons/README.md) (-) | Item, Collection | Provides a way to specify data fields in a collection that are common across the STAC Items in that collection, so that each does not need to repeat all the same information. | *Proposal* | | [Data Cube](datacube/README.md) (`cube`) | Item | Data Cube related metadata, especially to describe their dimensions. | *Proposal* | | [Datetime Range](datetime-range/README.md) (`dtr`) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | | [EO](eo/README.md) (`eo`) | Item | Covers electro-optical data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, off nadir, sun angle + elevation, gsd and more. | *Pilot* | diff --git a/extensions/asset/examples/example-landsat8.json b/extensions/asset/examples/example-landsat8.json index 50119fb60..c3b302015 100644 --- a/extensions/asset/examples/example-landsat8.json +++ b/extensions/asset/examples/example-landsat8.json @@ -9,7 +9,8 @@ ], "stac_version": "0.8.1", "stac_extensions": [ - "asset" + "asset", + "commons" ], "extent": { "spatial": { diff --git a/extensions/commons/README.md b/extensions/commons/README.md new file mode 100644 index 000000000..82e50d9bb --- /dev/null +++ b/extensions/commons/README.md @@ -0,0 +1,131 @@ +# Commons Extension Specification + +**Extension [Maturity Classification](../README.md#extension-maturity): Proposal** + +A group of STAC Item objects from a single source can share a lot of common metadata. This is especially true with satellite imagery that uses the STAC EO Extension. Rather than including these common metadata fields on every Item, they can be provided into the [STAC Collection](../../collection-spec/README.md) that the STAC Items belong to. + +- [Examples](examples/): + - Landsat 8: An [Item](examples/landsat-item.json) that uses the Commons extension to place shared data in a [Collection](examples/landsat-collection.json). +- [JSON Schema](json-schema/schema.json) + +## Item fields + +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 can be removed and added to the Collection properties. 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 `eo:off_nadir` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellite that can be pointed will have varying `eo:off_nadir` values. The Commons extension allow the data provider to define the set of metadata that defines the colleciton. 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. + +A Collection may not link to any Items, it may just be a definition of a Collection, in which case the Commons extension could still be used by defining any properties that would be shared by any member Item. + +### Linking to a STAC Collection + +All Items are strongly recommended to link to a Collection (this is part of the STAC Item spec) and related references are specified in two places. + +One is a field called `collection` in a STAC Item which is the `id` of a STAC Collection record. The `collection` field provides an easy way for a user to search for any Items that belong in a specified Collection. + +A STAC Item must also provide a link to the STAC Collection using the `collection` rel type: + +``` +"links": [ + ... + { "rel": "collection", "href": "http://example.com/link/to/collection/record.json" } +] +``` + +### Using a STAC Collection + +To get the complete record of an Item (both individual and commons properties), the properties from the Collection can be merged with the Item. + +An incomplete Collection: +``` +{ + "stac_version": "0.8.1", + "stac_extensions": ["commons"], + "id": "landsat-8-l1", + "title": "Landsat 8 L1", + "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", + "extent": {...}, + "license": "PDDL-1.0", + "properties": { + "platform": "landsat-8", + "constellation": "landsat-8", + "instruments": ["oli", "tirs"], + "eo:gsd": 30, + "eo:off_nadir": 0, + "eo:bands": [ + { + "name": "B1", + "common_name": "coastal", + "gsd": 30, + "center_wavelength": 0.44, + "full_width_half_max": 0.02 + }, + ... + ] + }, + "links": [...] +} +``` + +An incomplete item: +``` +{ + "stac_version": "0.8.1", + "stac_extensions": ["commons", "eo", "instrument"], + "type": "Feature", + "id": "LC08_L1TP_107018_20181001_20181001_01_RT", + "bbox": [...], + "geometry": {...}, + "collection": "landsat-8-l1", + "properties": { + "datetime": "2018-10-01T01:08:32.033Z", + "eo:cloud_cover": 78, + "eo:sun_azimuth": 168.8989761, + "eo:sun_elevation": 26.32596431 + }, + "assets": {...}, + "links": [...] +} +``` + +The merged Item then looks like this: + +``` +{ + "stac_version": "0.8.1", + "stac_extensions": ["eo", "instrument"], + "type": "Feature", + "id": "LC08_L1TP_107018_20181001_20181001_01_RT", + "bbox": [...], + "geometry": {...}, + "collection": "landsat-8-l1", + "properties": { + "datetime": "2018-10-01T01:08:32.033Z", + "platform": "landsat-8", + "constellation": "landsat-8", + "instruments": ["oli", "tirs"], + "eo:cloud_cover": 78, + "eo:sun_azimuth": 168.8989761, + "eo:sun_elevation": 26.32596431, + "eo:gsd": 30, + "eo:off_nadir": 0, + "eo:bands": [ + { + "name": "B1", + "common_name": "coastal", + "gsd": 30, + "center_wavelength": 0.44, + "full_width_half_max": 0.02 + }, + ... + ] + }, + "assets": {...}, + "links": [...] +} +``` + +## Implementations + +[sat-api](https://github.com/sat-utils/sat-api/) has pioneered this functionality. You can see it in action at [https://sat-api.developmentseed.org/stac](https://sat-api.developmentseed.org/stac). \ No newline at end of file diff --git a/extensions/commons/examples/landsat-collection.json b/extensions/commons/examples/landsat-collection.json new file mode 100644 index 000000000..4a3cc0da4 --- /dev/null +++ b/extensions/commons/examples/landsat-collection.json @@ -0,0 +1,165 @@ +{ + "stac_version": "0.8.1", + "stac_extensions": [ + "commons" + ], + "id": "landsat-8-l1", + "title": "Landsat 8 L1", + "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", + "keywords": [ + "landsat" + ], + "extent": { + "spatial": { + "bbox": [ + [ + -180, + -90, + 180, + 90 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2013-06-01T00:00:00Z", + null + ] + ] + } + }, + "providers": [ + { + "name": "USGS", + "url": "https://landsat.usgs.gov/", + "roles": [ + "producer", + "licensor" + ] + }, + { + "name": "Planet Labs", + "url": "https://github.com/landsat-pds/landsat_ingestor", + "roles": [ + "processor" + ] + }, + { + "name": "AWS", + "url": "https://landsatonaws.com/", + "roles": [ + "host" + ] + }, + { + "name": "Development Seed", + "url": "https://developmentseed.org/", + "roles": ["processor"] + } + ], + "license": "PDDL-1.0", + "properties": { + "eo:gsd": 30, + "platform": "landsat-8", + "instruments": ["oli", "tirs"], + "eo:off_nadir": 0, + "eo:bands": [ + { + "name": "B1", + "common_name": "coastal", + "gsd": 30, + "center_wavelength": 0.44, + "full_width_half_max": 0.02 + }, + { + "name": "B2", + "common_name": "blue", + "gsd": 30, + "center_wavelength": 0.48, + "full_width_half_max": 0.06 + }, + { + "name": "B3", + "common_name": "green", + "gsd": 30, + "center_wavelength": 0.56, + "full_width_half_max": 0.06 + }, + { + "name": "B4", + "common_name": "red", + "gsd": 30, + "center_wavelength": 0.65, + "full_width_half_max": 0.04 + }, + { + "name": "B5", + "common_name": "nir", + "gsd": 30, + "center_wavelength": 0.86, + "full_width_half_max": 0.03 + }, + { + "name": "B6", + "common_name": "swir16", + "gsd": 30, + "center_wavelength": 1.6, + "full_width_half_max": 0.08 + }, + { + "name": "B7", + "common_name": "swir22", + "gsd": 30, + "center_wavelength": 2.2, + "full_width_half_max": 0.2 + }, + { + "name": "B8", + "common_name": "pan", + "gsd": 15, + "center_wavelength": 0.59, + "full_width_half_max": 0.18 + }, + { + "name": "B9", + "common_name": "cirrus", + "gsd": 30, + "center_wavelength": 1.37, + "full_width_half_max": 0.02 + }, + { + "name": "B10", + "common_name": "lwir11", + "gsd": 100, + "center_wavelength": 10.9, + "full_width_half_max": 0.8 + }, + { + "name": "B11", + "common_name": "lwir12", + "gsd": 100, + "center_wavelength": 12, + "full_width_half_max": 1 + } + ] + }, + "links": [ + { + "rel": "self", + "href": "https://example.com/stac/collections/landsat-8-l1" + }, + { + "rel": "parent", + "href": "https://example.com/stac" + }, + { + "rel": "root", + "href": "https://example.com/stac" + }, + { + "rel": "child", + "href": "https://example.com/stac/collections/landsat-8-l1/items" + } + ] + } \ No newline at end of file diff --git a/extensions/commons/examples/landsat-item.json b/extensions/commons/examples/landsat-item.json new file mode 100644 index 000000000..4b52572af --- /dev/null +++ b/extensions/commons/examples/landsat-item.json @@ -0,0 +1,181 @@ +{ + "stac_version": "0.8.1", + "stac_extensions": [ + "commons", + "eo", + "instrument", + "https://example.com/stac/landsat-extension/1.0/schema.json" + ], + "id": "LC08_L1TP_107018_20181001_20181001_01_RT", + "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 + ] + ] + ] + }, + "collection": "landsat-8-l1", + "properties": { + "datetime": "2018-10-01T01:08:32.033Z", + "eo:cloud_cover": 78, + "eo:sun_azimuth": 168.8989761, + "eo:sun_elevation": 26.32596431, + "landsat:path": 107, + "landsat:row": 18 + }, + "assets": { + "ANG": { + "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_ANG.txt", + "title": "Angle coefficients file", + "type": "text/plain" + }, + "B1": { + "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_B1.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 0 + ], + "title": "Band 1 (coastal)" + }, + "B2": { + "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", + "eo:bands": [ + 1 + ], + "title": "Band 2 (blue)" + }, + "B3": { + "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", + "eo:bands": [ + 2 + ], + "title": "Band 3 (green)" + }, + "B4": { + "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", + "eo:bands": [ + 3 + ], + "title": "Band 4 (red)" + }, + "B5": { + "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_B5.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 4 + ], + "title": "Band 5 (nir)" + }, + "B6": { + "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_B6.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 5 + ], + "title": "Band 6 (swir16)" + }, + "B7": { + "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_B7.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 6 + ], + "title": "Band 7 (swir22)" + }, + "B8": { + "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_B8.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 7 + ], + "title": "Band 8 (pan)" + }, + "B9": { + "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_B9.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 8 + ], + "title": "Band 9 (cirrus)" + }, + "B10": { + "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_B10.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 9 + ], + "title": "Band 10 (lwir)" + }, + "B11": { + "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_B11.TIF", + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 10 + ], + "title": "Band 11 (lwir)" + }, + "BQA": { + "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_BQA.TIF", + "title": "Band quality data", + "type": "image/tiff; application=geotiff" + }, + "MTL": { + "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_MTL.txt", + "title": "original metadata file", + "type": "text/plain" + }, + "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": { + "type": "text/html", + "title": "HTML index page" + } + }, + "links": [ + { + "rel": "self", + "href": "https:///search?id=LC08_L1TP_107018_20181001_20181001_01_RT" + }, + { + "rel": "parent", + "href": "https:///stac/collections/landsat-8-l1" + }, + { + "rel": "root", + "href": "https:///stac" + } + ] +} \ No newline at end of file diff --git a/extensions/commons/json-schema/schema.json b/extensions/commons/json-schema/schema.json new file mode 100644 index 000000000..b500a543c --- /dev/null +++ b/extensions/commons/json-schema/schema.json @@ -0,0 +1,31 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "schema.json#", + "title": "Commons Extension", + "description": "STAC Commons Extension for STAC Items and STAC Collections.", + "oneOf": [ + { + "$ref": "../../../item-spec/json-schema/item.json" + }, + { + "allOf": [ + { + "$ref": "../../../collection-spec/json-schema/collection.json" + }, + { + "type": "object", + "required": [ + "properties" + ], + "properties": { + "properties": { + "title": "Common fields", + "type": "object", + "additionalProperties": true + } + } + } + ] + } + ] + } \ No newline at end of file diff --git a/extensions/eo/README.md b/extensions/eo/README.md index ca5cfa3df..54b0b5ecb 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -14,9 +14,9 @@ natural focus, and encourage other sensors to make their own extensions. Once th these fields will evolve to higher level extensions. In the meantime other implementations are welcome to reuse the names and definitions here. -A lot of EO data will have common metadata across many Items. It is not necessary, but recommended -to place common fields in [STAC Collections](../../collection-spec/collection-spec.md#common-fields-and-standalone-collections). -The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. +A lot of EO data will have common metadata across many Items. +It is not necessary, but recommended to use the [Commons extension](../commons/README.md) +(see chapter "Placing common fields in Collections"). - [Example (Landsat 8)](examples/example-landsat8.json) - [JSON Schema](json-schema/schema.json) @@ -222,4 +222,9 @@ the eo:bands portion is still being fleshed out. ## Extensions -The [extensions page](../README.md) gives an overview about related extensions. \ No newline at end of file +The [extensions page](../README.md) gives an overview about related extensions. + +### Placing common fields in Collections +A lot of EO data will have common metadata across many Items. It is not necessary, but recommended +to use the [Commons extension](../commons/README.md) in combination with [STAC Collections](../../collection-spec/README.md). +The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 9f8253af1..cf8780838 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -5,9 +5,7 @@ This document explains the fields of the STAC Synthetic-Aperture Radar (SAR) Extension to a STAC Item. SAR data is considered to be data that represents a snapshot of the earth for a single date and time taken by a synthetic-aperture radar system such as Sentinel-1, RADARSAT or EnviSAT. -A lot of SAR data will have common metadata across many Items. It is not necessary, but recommended -to place common fields in [STAC Collections](../../collection-spec/collection-spec.md). -The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. +It is not necessary, but recommended to use the [Commons extension](../commons/README.md) (see chapter "Placing common fields in Collections"). - [Examples](examples/) (for example [Sentinel-1](examples/sentinel1.json) and [Envisat](examples/envisat.json)) - [JSON Schema](json-schema/schema.json) @@ -89,4 +87,9 @@ Asset definitions that contain band data should reference the band index. Each a The [extensions page](../README.md) gives an overview about related extensions, for example: -* the [Datetime Range Extension Specification](../datetime-range/README.md) to describe frame start and end time. \ No newline at end of file +* the [Datetime Range Extension Specification](../datetime-range/README.md) to describe frame start and end time. + +### Placing common fields in Collections +A lot of SAR data will have common metadata across many Items. It is not necessary, but recommended +to use the [Commons extension](../commons/README.md) in combination with [STAC Collections](../../collection-spec/README.md). +The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. \ No newline at end of file diff --git a/extensions/scientific/README.md b/extensions/scientific/README.md index 220d9bea7..07f3c725e 100644 --- a/extensions/scientific/README.md +++ b/extensions/scientific/README.md @@ -12,7 +12,8 @@ can be registered at registration agencies affiliated with the This extension applies to STAC Items and STAC Collections. As these scientific information are often closely bound to the collection level and therefore are shared across all items, -it is recommended to add the fields to a corresponding [STAC Collection](../../collection-spec/README.md). +it is recommended to use the [Commons extension](../commons/README.md) to add the fields to a corresponding +[STAC Collection](../../collection-spec/README.md). - Examples: [Collection](examples/collection.json), [Item](examples/item.json) - [JSON Schema](json-schema/schema.json) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index ecb1a196d..db31e2f99 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -131,8 +131,8 @@ The following types are commonly used as `rel` types in the Link Object of an It | self | STRONGLY RECOMMENDED. _Absolute_ URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | | root | URL to the root STAC [Catalog](../catalog-spec/README.md) or [Collection](../collection-spec/README.md). | | parent | URL to the parent STAC [Catalog](../catalog-spec/README.md) or [Collection](../collection-spec/README.md). | -| collection | STRONGLY RECOMMENDED. URL to a [Collection](../collection-spec/README.md), which may hold [common fields](../collection-spec/collection-spec.md#common-fields-and-standalone-collections) of this and other Items (see chapter '[Collections](#Collections)' for more explanations). _Absolute_ URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. | -| license | The license URL(s) for the item SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to supplement the STAC Item with the license text in a separate file and link to this file. | +| collection | STRONGLY RECOMMENDED. URL to a [Collection](../collection-spec/README.md), which may use the use the [Commons extension](../extensions/commons/README.md) to hold common fields of this and other Items (see chapter '[Collections](#Collections)' for more explanations). _Absolute_ URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. | +| license | The license URL(s) for the item SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to supplement the STAC Item with the license text in a separate file and link to this file. | | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | A more complete list of possible 'rel' types can be seen at the [IANA page of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). @@ -157,6 +157,9 @@ Linking back must happen in two places: ] ``` +Optionally, common information shared across items can be moved up into STAC Collections +using the [Commons extension](../extensions/commons/README.md) to avoid duplicating information. + ### Asset Object An asset is an object that contains a link to data associated with the Item that can be downloaded @@ -229,6 +232,9 @@ Both can still appear in old catalogues, but are deprecated and should be replac There are emerging best practices, which in time will evolve in to specification extensions for particular domains or uses. +Optionally, common information shared across items can be split up into STAC Collections using the +[Commons extension](../extensions/commons/README.md). + The [extensions page](../extensions/README.md) gives an overview about relevant extensions for STAC Items. ## Recommendations diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index f51de2b43..c30c43b52 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -48,6 +48,7 @@ "type": "string", "enum": [ "checksum", + "commons", "cube", "datetime-range", "eo", From dc77d3b07cc590d5c818f4fc9860e241688f889f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 19 Nov 2019 12:44:21 +0100 Subject: [PATCH 25/87] Removed summaries field from catalogs. --- CHANGELOG.md | 9 +- api-spec/STAC-extensions.yaml | 85 +++++----- api-spec/STAC.yaml | 85 +++++----- api-spec/openapi/STAC.yaml | 54 +++--- catalog-spec/catalog-spec.md | 19 --- catalog-spec/examples/summaries-s2.json | 176 -------------------- catalog-spec/json-schema/catalog.json | 36 ---- collection-spec/json-schema/collection.json | 33 ++++ 8 files changed, 142 insertions(+), 355 deletions(-) delete mode 100644 catalog-spec/examples/summaries-s2.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 7726788b8..a9b43a6ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,11 +10,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Added - Added a version extension to the API specification - Added [Version Extension](extensions/version/README.md) to version and deprecate STAC Items and Collections. +- Added Instrument extension which adds fields: `platform`, `instruments`, `constellation`, and `mission`. ### Removed - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support - Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead. - Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension. +- Removed `summaries` field from Catalogs. Use Collections instead. ### Changed - The STAC API endpoint `/stac` has been merged with `/` @@ -33,13 +35,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. n/a -### Added - -n/a - -### Added -- Added Instrument extension which adds fields: `platform`, `instruments`, `constellation`, and `mission`. - ## [v0.8.1] - 2019-11-01 ### Changed diff --git a/api-spec/STAC-extensions.yaml b/api-spec/STAC-extensions.yaml index 80c87b6fb..96b91b371 100644 --- a/api-spec/STAC-extensions.yaml +++ b/api-spec/STAC-extensions.yaml @@ -735,7 +735,47 @@ components: providers: $ref: '#/components/schemas/providers' summaries: - $ref: '#/components/schemas/summaries' + description: >- + Summaries are either a unique set of all available values *or* + statistics. Statistics by default only specify the range (minimum + and maximum values), but can optionally be accompanied by additional + statistical values. The range can specify the potential range of + values, but it is recommended to be as precise as possible. The set + of values must contain at least one element and it is strongly + recommended to list all values. It is recommended to list as many + properties as reasonable so that consumers get a full overview of + the Collection. Properties that are covered by the Collection + specification (e.g. `providers` and `license`) may not be repeated + in the summaries. + type: object + additionalProperties: + oneOf: + - type: array + title: Set of values + items: + description: A value of any type. + - type: object + title: Statistics + description: >- + By default, only ranges with a minimum and a maximum value can + be specified. Ranges can be specified for ordinal values only, + which means they need to have a rank order. Therefore, ranges + can only be specified for numbers and some special types of + strings. Examples: grades (A to F), dates or times. + Implementors are free to add other derived statistical values + to the object, for example `mean` or `stddev`. + required: + - min + - max + properties: + min: + anyOf: + - type: string + - type: number + max: + anyOf: + - type: string + - type: number example: stac_version: 0.8.1 stac_extensions: [] @@ -1164,8 +1204,6 @@ components: $ref: '#/components/schemas/stac_extensions' id: type: string - summaries: - $ref: '#/components/schemas/summaries' linestringGeoJSON: type: object required: @@ -1593,47 +1631,6 @@ components: format: uri - title: Reference to a core extension type: string - summaries: - description: >- - Summaries are either a unique set of all available values *or* - statistics. Statistics by default only specify the range (minimum and - maximum values), but can optionally be accompanied by additional - statistical values. The range can specify the potential range of values, - but it is recommended to be as precise as possible. The set of values - must contain at least one element and it is strongly recommended to list - all values. It is recommended to list as many properties as reasonable - so that consumers get a full overview of the Collection. Properties that - are covered by the Collection specification (e.g. `providers` and - `license`) may not be repeated in the summaries. - type: object - additionalProperties: - oneOf: - - type: array - title: Set of values - items: - description: A value of any type. - - type: object - title: Statistics - description: >- - By default, only ranges with a minimum and a maximum value can be - specified. Ranges can be specified for ordinal values only, which - means they need to have a rank order. Therefore, ranges can only - be specified for numbers and some special types of strings. - Examples: grades (A to F), dates or times. Implementors are free - to add other derived statistical values to the object, for example - `mean` or `stddev`. - required: - - min - - max - properties: - min: - anyOf: - - type: string - - type: number - max: - anyOf: - - type: string - - type: number itemCollection: description: >- A GeoJSON FeatureCollection augmented with foreign members that contain diff --git a/api-spec/STAC.yaml b/api-spec/STAC.yaml index d36d1ebe5..6a9dae6ab 100644 --- a/api-spec/STAC.yaml +++ b/api-spec/STAC.yaml @@ -444,7 +444,47 @@ components: providers: $ref: '#/components/schemas/providers' summaries: - $ref: '#/components/schemas/summaries' + description: >- + Summaries are either a unique set of all available values *or* + statistics. Statistics by default only specify the range (minimum + and maximum values), but can optionally be accompanied by additional + statistical values. The range can specify the potential range of + values, but it is recommended to be as precise as possible. The set + of values must contain at least one element and it is strongly + recommended to list all values. It is recommended to list as many + properties as reasonable so that consumers get a full overview of + the Collection. Properties that are covered by the Collection + specification (e.g. `providers` and `license`) may not be repeated + in the summaries. + type: object + additionalProperties: + oneOf: + - type: array + title: Set of values + items: + description: A value of any type. + - type: object + title: Statistics + description: >- + By default, only ranges with a minimum and a maximum value can + be specified. Ranges can be specified for ordinal values only, + which means they need to have a rank order. Therefore, ranges + can only be specified for numbers and some special types of + strings. Examples: grades (A to F), dates or times. + Implementors are free to add other derived statistical values + to the object, for example `mean` or `stddev`. + required: + - min + - max + properties: + min: + anyOf: + - type: string + - type: number + max: + anyOf: + - type: string + - type: number example: stac_version: 0.8.1 stac_extensions: [] @@ -873,8 +913,6 @@ components: $ref: '#/components/schemas/stac_extensions' id: type: string - summaries: - $ref: '#/components/schemas/summaries' linestringGeoJSON: type: object required: @@ -1299,47 +1337,6 @@ components: format: uri - title: Reference to a core extension type: string - summaries: - description: >- - Summaries are either a unique set of all available values *or* - statistics. Statistics by default only specify the range (minimum and - maximum values), but can optionally be accompanied by additional - statistical values. The range can specify the potential range of values, - but it is recommended to be as precise as possible. The set of values - must contain at least one element and it is strongly recommended to list - all values. It is recommended to list as many properties as reasonable - so that consumers get a full overview of the Collection. Properties that - are covered by the Collection specification (e.g. `providers` and - `license`) may not be repeated in the summaries. - type: object - additionalProperties: - oneOf: - - type: array - title: Set of values - items: - description: A value of any type. - - type: object - title: Statistics - description: >- - By default, only ranges with a minimum and a maximum value can be - specified. Ranges can be specified for ordinal values only, which - means they need to have a rank order. Therefore, ranges can only - be specified for numbers and some special types of strings. - Examples: grades (A to F), dates or times. Implementors are free - to add other derived statistical values to the object, for example - `mean` or `stddev`. - required: - - min - - max - properties: - min: - anyOf: - - type: string - - type: number - max: - anyOf: - - type: string - - type: number itemCollection: description: >- A GeoJSON FeatureCollection augmented with foreign members that contain diff --git a/api-spec/openapi/STAC.yaml b/api-spec/openapi/STAC.yaml index 400f12810..3dc20545d 100644 --- a/api-spec/openapi/STAC.yaml +++ b/api-spec/openapi/STAC.yaml @@ -190,7 +190,31 @@ components: providers: $ref: '#/components/schemas/providers' summaries: - $ref: '#/components/schemas/summaries' + description: >- + Summaries are either a unique set of all available values *or* statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. The range can specify the potential range of values, but it is recommended to be as precise as possible. The set of values must contain at least one element and it is strongly recommended to list all values. It is recommended to list as many properties as reasonable so that consumers get a full overview of the Collection. Properties that are covered by the Collection specification (e.g. `providers` and `license`) may not be repeated in the summaries. + type: object + additionalProperties: + oneOf: + - type: array + title: Set of values + items: + description: A value of any type. + - type: object + title: Statistics + description: >- + By default, only ranges with a minimum and a maximum value can be specified. Ranges can be specified for ordinal values only, which means they need to have a rank order. Therefore, ranges can only be specified for numbers and some special types of strings. Examples: grades (A to F), dates or times. Implementors are free to add other derived statistical values to the object, for example `mean` or `stddev`. + required: + - min + - max + properties: + min: + anyOf: + - type: string + - type: number + max: + anyOf: + - type: string + - type: number example: stac_version: 0.8.1 stac_extensions: [] @@ -578,32 +602,6 @@ components: format: uri - title: Reference to a core extension type: string - summaries: - description: >- - Summaries are either a unique set of all available values *or* statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. The range can specify the potential range of values, but it is recommended to be as precise as possible. The set of values must contain at least one element and it is strongly recommended to list all values. It is recommended to list as many properties as reasonable so that consumers get a full overview of the Collection. Properties that are covered by the Collection specification (e.g. `providers` and `license`) may not be repeated in the summaries. - type: object - additionalProperties: - oneOf: - - type: array - title: Set of values - items: - description: A value of any type. - - type: object - title: Statistics - description: >- - By default, only ranges with a minimum and a maximum value can be specified. Ranges can be specified for ordinal values only, which means they need to have a rank order. Therefore, ranges can only be specified for numbers and some special types of strings. Examples: grades (A to F), dates or times. Implementors are free to add other derived statistical values to the object, for example `mean` or `stddev`. - required: - - min - - max - properties: - min: - anyOf: - - type: string - - type: number - max: - anyOf: - - type: string - - type: number # This schema extends OAFeat.yaml#/components/schemas/landingPage to add and require additional fields. landingPage: type: object @@ -618,8 +616,6 @@ components: $ref: '#/components/schemas/stac_extensions' id: type: string - summaries: - $ref: '#/components/schemas/summaries' itemCollection: description: A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity type: object diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 48671d374..60d8f6d15 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -120,19 +120,12 @@ details on the two types and how you might use them see the [Static and Dynamic | id | string | **REQUIRED.** Identifier for the catalog. | | title | string | A short descriptive one-line title for the catalog. | | description | string | **REQUIRED.** Detailed multi-line description to fully explain the catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| summaries | Map | A map of property summaries, either a set of values or statistics such as a range. | | links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | **stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. **stac_extensions**: A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file. -**summaries**: You can optionally summarize the potential values that are available as part of the `properties` in STAC Items. -Summaries are used to inform users about values they can expect from items without having to crawl through them. It also helps do fully define collections, especially if they don't link to any Items. -Summaries are either a unique set of all values or statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. -The range can specify the potential range of values, but it is recommended to be as precise as possible. The set of values must contain at least one element and it is strongly recommended to list all values. -It is recommended to list as many properties as reasonable so that consumers get a full overview about the properties included in the Items. Nevertheless, it is not very useful to list all potential `title` values of the Items. Also, a range for the `datetime` property may be better suited to be included in the STAC Collection. In general, properties that are covered by the Collection specification (e.g. `providers` and `license`) may not be repeated in the summaries. - ### Link Object This object describes a relationship with another entity. Data providers are advised to be liberal @@ -165,18 +158,6 @@ The following types are commonly used as `rel` types in the Link Object of a STA **Note:** A link to at least one `item` or `child` catalog is **REQUIRED**. -### Stats Object - -For a good understanding of the summarized field, statistics can be added. By default, only ranges with a minimum and a maximum value can be specified. -Ranges can be specified for [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values only, which means they need to have a rank order. -Therefore, ranges can only be specified for numbers and some special types of strings. Examples: grades (A to F), dates or times. -Implementors are free to add other derived statistical values to the object, for example `mean` or `stddev`. - -| Field Name | Type | Description | -| ---------- | -------------- | ----------- | -| min | number\|string | **REQUIRED.** Minimum value. | -| max | number\|string | **REQUIRED.** Maximum value. | - ## Examples A catalog of diff --git a/catalog-spec/examples/summaries-s2.json b/catalog-spec/examples/summaries-s2.json deleted file mode 100644 index 09b6ebae1..000000000 --- a/catalog-spec/examples/summaries-s2.json +++ /dev/null @@ -1,176 +0,0 @@ -{ - "stac_version": "0.8.1", - "id": "summaries-s2", - "title": "S2 Summary", - "description": "This is a *sample* Sentinel-2 catalog with summaries.", - "summaries": { - "datetime": { - "min": "2015-06-23T00:00:00Z", - "max": "2019-07-10T13:44:56Z" - }, - "license": ["CC-BY-4.0","proprietary"], - "sci:citation": ["Copernicus Sentinel data [Year]"], - "eo:gsd": [10,30,60], - "platform": ["sentinel-2a","sentinel-2b"], - "constellation": ["sentinel-2"], - "instruments": [["msi"]], - "eo:off_nadir": { - "min": 0.0, - "max": 100 - }, - "eo:sun_elevation": { - "min": 6.78, - "max": 89.9 - }, - "eo:epsg": [32601,32602,32603,32604,32605,32606,32607,32608,32609,32610,32611,32612,32613,32614,32615,32616,32617,32618,32619,32620,32621,32622,32623,32624,32625,32626,32627,32628,32629,32630,32631,32632,32633,32634,32635,32636,32637,32638,32639,32640,32641,32642,32643,32644,32645,32646,32647,32648,32649,32650,32651,32652,32653,32654,32655,32656,32657,32658,32659,32660], - "eo:bands": [ - [ - { - "name": "B1", - "common_name": "coastal", - "center_wavelength": 4.439, - "gsd": 60 - }, - { - "name": "B2", - "common_name": "blue", - "center_wavelength": 4.966, - "gsd": 10 - }, - { - "name": "B3", - "common_name": "green", - "center_wavelength": 5.6, - "gsd": 10 - }, - { - "name": "B4", - "common_name": "red", - "center_wavelength": 6.645, - "gsd": 10 - }, - { - "name": "B5", - "center_wavelength": 7.039, - "gsd": 20 - }, - { - "name": "B6", - "center_wavelength": 7.402, - "gsd": 20 - }, - { - "name": "B7", - "center_wavelength": 7.825, - "gsd": 20 - }, - { - "name": "B8", - "common_name": "nir", - "center_wavelength": 8.351, - "gsd": 10 - }, - { - "name": "B8A", - "center_wavelength": 8.648, - "gsd": 20 - }, - { - "name": "B9", - "center_wavelength": 9.45, - "gsd": 60 - }, - { - "name": "B10", - "center_wavelength": 1.3735, - "gsd": 60 - }, - { - "name": "B11", - "common_name": "swir16", - "center_wavelength": 1.6137, - "gsd": 20 - }, - { - "name": "B12", - "common_name": "swir22", - "center_wavelength": 2.2024, - "gsd": 20 - } - ] - ], - "cube:dimensions": [ - { - "x": { - "type": "spatial", - "axis": "x", - "extent": [-180,180] - }, - "y": { - "type": "spatial", - "axis": "y", - "extent": [-56,83] - }, - "temporal": { - "type": "temporal", - "extent": ["2015-06-23T00:00:00Z","2019-07-10T13:44:56Z"] - }, - "spectral": { - "type": "bands", - "values": ["B1","B9","B10"] - } - }, - { - "x": { - "type": "spatial", - "axis": "x", - "extent": [-180,180] - }, - "y": { - "type": "spatial", - "axis": "y", - "extent": [-56,83] - }, - "temporal": { - "type": "temporal", - "extent": ["2015-06-23T00:00:00Z","2019-07-10T13:44:56Z"] - }, - "spectral": { - "type": "bands", - "values": ["B2","B3","B4","B8"] - } - }, - { - "x": { - "type": "spatial", - "axis": "x", - "extent": [-180,180] - }, - "y": { - "type": "spatial", - "axis": "y", - "extent": [-56,83] - }, - "temporal": { - "type": "temporal", - "extent": ["2015-06-23T00:00:00Z","2019-07-10T13:44:56Z"] - }, - "spectral": { - "type": "bands", - "values": ["B5","B6","B7","B8A","B11","B12"] - } - } - ] - }, - "links": [ - { - "href": "item.json", - "rel": "item" - }, - { - "rel": "license", - "href": "https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf", - "title": "Sentinel Data Terms and Conditions" - } - ] -} diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index 33d9fb415..472227132 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -50,45 +50,9 @@ "items": { "$ref": "#/definitions/link" } - }, - "summaries": { - "$ref": "#/definitions/summaries" } } }, - "summaries": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "title": "Stats", - "type": "object", - "required": [ - "min", - "max" - ], - "properties": { - "min": { - "title": "Minimum value", - "type": ["number", "string"] - }, - "max": { - "title": "Maximum value", - "type": ["number", "string"] - } - } - }, - { - "title": "Set of values", - "type": "array", - "minItems": 1, - "items": { - "description": "Any data type could occur." - } - } - ] - } - }, "link": { "type": "object", "required": [ diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index 6ee21bf29..6f0f62da3 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -148,6 +148,39 @@ } } } + }, + "summaries": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "title": "Stats", + "type": "object", + "required": [ + "min", + "max" + ], + "properties": { + "min": { + "title": "Minimum value", + "type": ["number", "string"] + }, + "max": { + "title": "Maximum value", + "type": ["number", "string"] + } + } + }, + { + "title": "Set of values", + "type": "array", + "minItems": 1, + "items": { + "description": "Any data type could occur." + } + } + ] + } } } } From 665eff8abfb6cc88daea299bb6244bafb15d73f3 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 19 Nov 2019 12:57:06 +0100 Subject: [PATCH 26/87] Fixed stac_extensions in several examples. --- collection-spec/examples/landsat-collection.json | 5 +---- collection-spec/examples/landsat-item.json | 1 + item-spec/examples/digitalglobe-sample.json | 1 + item-spec/examples/sentinel2-sample.json | 3 ++- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/collection-spec/examples/landsat-collection.json b/collection-spec/examples/landsat-collection.json index 772f2bc2c..c762f4b6d 100644 --- a/collection-spec/examples/landsat-collection.json +++ b/collection-spec/examples/landsat-collection.json @@ -1,9 +1,6 @@ { "stac_version": "0.8.1", - "stac_extensions": [ - "eo", - "instrument" - ], + "stac_extensions": [], "id": "landsat-8-l1", "title": "Landsat 8 L1", "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", diff --git a/collection-spec/examples/landsat-item.json b/collection-spec/examples/landsat-item.json index cda8f8907..ababff1e3 100644 --- a/collection-spec/examples/landsat-item.json +++ b/collection-spec/examples/landsat-item.json @@ -2,6 +2,7 @@ "stac_version": "0.8.1", "stac_extensions": [ "eo", + "instrument", "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC08_L1TP_107018_20181001_20181001_01_RT", diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json index 0d1355bda..13ce2d1d2 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -2,6 +2,7 @@ "stac_version": "0.8.1", "stac_extensions": [ "eo", + "instrument", "https://example.digitalglobe.com/stac/1.0/schema.json" ], "id": "103001004B316600_P002_MUL", diff --git a/item-spec/examples/sentinel2-sample.json b/item-spec/examples/sentinel2-sample.json index 60cf43bfe..b6e4ed6c8 100644 --- a/item-spec/examples/sentinel2-sample.json +++ b/item-spec/examples/sentinel2-sample.json @@ -1,7 +1,8 @@ { "stac_version": "0.8.1", "stac_extensions": [ - "eo" + "eo", + "instrument" ], "type": "Feature", "id": "S2A_OPER_MSI_L2A_TL_SGS__20180524T190423_A015250_T26SKD_N02.08", From bdb4daef5072e48b5a032c82023525bf439cc84f Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 11:02:34 -0500 Subject: [PATCH 27/87] update extension READMEs to reference the sat extension --- extensions/eo/README.md | 5 ++++- extensions/sar/README.md | 6 ++++-- extensions/sat/README.md | 4 +++- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/extensions/eo/README.md b/extensions/eo/README.md index e17f40a1b..ef7e9928a 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -218,4 +218,7 @@ the eo:bands portion is still being fleshed out. ## Extensions -The [extensions page](../README.md) gives an overview about related extensions. \ No newline at end of file +The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to EO data: + +* the [Instrument Extension Specification](../instrument/README.md) is required when using the EO extension, which contains fields about the sensor and platform used to collect the data. +* the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. \ No newline at end of file diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 6a681b081..b2bffe031 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -79,6 +79,8 @@ Asset definitions that contain band data should reference the band index. Each a ## Extensions -The [extensions page](../README.md) gives an overview about related extensions, for example: +The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to SAR data: -* the [Datetime Range Extension Specification](../datetime-range/README.md) to describe frame start and end time. \ No newline at end of file +* the [Instrument Extension Specification](../instrument/README.md) is required when using the SAR extension, which contains fields about the sensor and platform used to collect the data. +* the [Datetime Range Extension Specification](../datetime-range/README.md) to describe frame start and end time. +* the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. \ No newline at end of file diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 9a31ee3b4..6644f8505 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -67,4 +67,6 @@ Example: ## Extensions -The [extensions page](../README.md) gives an overview about related extensions. \ No newline at end of file +The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to sat data: + +* the [Instrument Extension Specification](../instrument/README.md), which contains fields about the sensor and platform used to collect the data. \ No newline at end of file From 8711135a783fb7822f29e84bb8e93be9584ddc6f Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 11:06:56 -0500 Subject: [PATCH 28/87] update extension readmes for sat --- extensions/eo/README.md | 4 ++-- extensions/sar/README.md | 5 +++-- extensions/sat/README.md | 2 +- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/extensions/eo/README.md b/extensions/eo/README.md index ef7e9928a..217b67af0 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -220,5 +220,5 @@ 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 [Instrument Extension Specification](../instrument/README.md) is required when using the EO extension, which contains fields about the sensor and platform used to collect the data. -* the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. \ No newline at end of file +* the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. +* the [Instrument Extension Specification](../instrument/README.md) is required when using the EO extension, which contains fields about the sensor and platform used to collect the data. It is required when using the Sat extension. \ No newline at end of file diff --git a/extensions/sar/README.md b/extensions/sar/README.md index b2bffe031..467854f80 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -81,6 +81,7 @@ Asset definitions that contain band data should reference the band index. Each a The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to SAR data: -* the [Instrument Extension Specification](../instrument/README.md) is required when using the SAR extension, which contains fields about the sensor and platform used to collect the data. + * the [Datetime Range Extension Specification](../datetime-range/README.md) to describe frame start and end time. -* the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. \ No newline at end of file +* the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. +* the [Instrument Extension Specification](../instrument/README.md) which contains fields about the sensor and platform used to collect the data. The Instrument extension is required when using the Sat extension. \ No newline at end of file diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 6644f8505..7ec94b8e4 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -69,4 +69,4 @@ Example: The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to sat data: -* the [Instrument Extension Specification](../instrument/README.md), which contains fields about the sensor and platform used to collect the data. \ No newline at end of file +* the [Instrument Extension Specification](../instrument/README.md), required when using the `sat` extension, which contains fields about the sensor and platform used to collect the data. \ No newline at end of file From e9af41511f709d0991485933889b77e445e9be28 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 11:07:15 -0500 Subject: [PATCH 29/87] update OpenAPI docs --- api-spec/STAC-extensions.yaml | 10 +++++----- api-spec/STAC.yaml | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/api-spec/STAC-extensions.yaml b/api-spec/STAC-extensions.yaml index 80c87b6fb..ca77b9cf1 100644 --- a/api-spec/STAC-extensions.yaml +++ b/api-spec/STAC-extensions.yaml @@ -786,10 +786,10 @@ components: - sentinel-2 instruments: - msi - 'eo:off_nadir': + 'sat:off_nadir_angle': min: 0 max: 100 - 'eo:sun_elevation': + 'sat:sun_elevation_angle': min: 6.78 max: 89.9 'eo:bands': @@ -1742,14 +1742,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'eo:sun_azimuth': 168.7 + 'sat:sun_azimuth_angle': 168.7 'eo:cloud_cover': 0.12 - 'eo:off_nadir': 1.4 + 'sat:off_nadir_angle': 1.4 platform: coolsat2 instruments: - cool_sensor_v1 'eo:bands': [] - 'eo:sun_elevation': 33.4 + 'sat:sun_elevation_angle': 33.4 'eo:gsd': 0.512 collection: CS3 links: diff --git a/api-spec/STAC.yaml b/api-spec/STAC.yaml index d36d1ebe5..0ab5d5391 100644 --- a/api-spec/STAC.yaml +++ b/api-spec/STAC.yaml @@ -495,10 +495,10 @@ components: - sentinel-2 instruments: - msi - 'eo:off_nadir': + 'sat:off_nadir_angle': min: 0 max: 100 - 'eo:sun_elevation': + 'sat:sun_elevation_angle': min: 6.78 max: 89.9 'eo:bands': @@ -1429,14 +1429,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'eo:sun_azimuth': 168.7 + 'sat:sun_azimuth_angle': 168.7 'eo:cloud_cover': 0.12 - 'eo:off_nadir': 1.4 + 'sat:off_nadir_angle': 1.4 platform: coolsat2 instruments: - cool_sensor_v1 'eo:bands': [] - 'eo:sun_elevation': 33.4 + 'sat:sun_elevation_angle': 33.4 'eo:gsd': 0.512 collection: CS3 links: From ee06385381f9b7970865f723f7482096774466c5 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 11:23:16 -0500 Subject: [PATCH 30/87] update sat extension schema and eo/sar READMEs --- extensions/eo/README.md | 2 ++ extensions/sar/README.md | 2 ++ extensions/sat/README.md | 2 ++ extensions/sat/json-schema/schema.json | 8 ++++---- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/extensions/eo/README.md b/extensions/eo/README.md index 217b67af0..cc04407a2 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -18,6 +18,8 @@ A lot of EO data will have common metadata across many Items. It is not necessar to place common fields in [STAC Collections](../../collection-spec/collection-spec.md#common-fields-and-standalone-collections). The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. +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` extension](../instrument/README.md). If the data has been collected on an airborne platform is is strongly recommended to use the [`instrument` extension](../instrument/README.md). + - [Example (Landsat 8)](examples/example-landsat8.json) - [JSON Schema](json-schema/schema.json) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 467854f80..be0d2b5cb 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -9,6 +9,8 @@ A lot of SAR data will have common metadata across many Items. It is not necessa to place common fields in [STAC Collections](../../collection-spec/collection-spec.md). The exact metadata that would appear in a STAC Collection record will vary depending on the dataset. +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` extension](../instrument/README.md). If the data has been collected on an airborne platform is is strongly recommended to use the [`instrument` extension](../instrument/README.md). + - [Examples](examples/) (for example [Sentinel-1](examples/sentinel1.json) and [Envisat](examples/envisat.json)) - [JSON Schema](json-schema/schema.json) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 7ec94b8e4..7d2568d58 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -4,6 +4,8 @@ This document explains the fields of the sat 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#common-fields-and-standalone-collections). +The `sat` extension requires the (`instrument` extension)[../instrument/README.md] + - [Example (Landsat 8)](examples/example-landsat8.json) - [JSON Schema](json-schema/schema.json) diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index cd59dd466..e34675e34 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -9,6 +9,9 @@ }, { "$ref": "#/definitions/sat" + }, + { + "$ref": "../instrument/json-schema/schema.json" } ], "definitions": { @@ -20,10 +23,7 @@ "properties": { "properties": { "type": "object", - "required": [ - "platform", - "instruments" - ], + "required": [], "properties": { "sat:off_nadir_angle": { "title": "Off Nadir", From e2b486598883f1dab8bd717a53cf29b57eaf6549 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 11:53:27 -0500 Subject: [PATCH 31/87] drop sar:center_wavelength --- extensions/sar/README.md | 1 - extensions/sar/json-schema/schema.json | 6 +----- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index be0d2b5cb..bce96c21e 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -22,7 +22,6 @@ If the data has been collected by a satellite, it is strongly recommended to use | ------------------------- | ------------- | ------------------------------------------------------------ | | 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. | -| sar:center_wavelength | number | The center wavelength of the instrument, in centimeters (cm). | | sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | | sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. | | sar:bands | [[Band Object](#band-object)] | This is a list of the available bands where each item is a [Band Object](#band-object). | diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index e431b3370..6b2d1cbd5 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -46,12 +46,8 @@ "Ka" ] }, - "sar:center_wavelength": { - "title": "Center Wavelength (cm)", - "type": "number" - }, "sar:center_frequency": { - "title": "Center Wavelength (GHz)", + "title": "Center Frequency (GHz)", "type": "number" }, "sar:polarization": { From 7ddc0201c31190ec80f36f80fb653d1146c0d19c Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 11:55:03 -0500 Subject: [PATCH 32/87] remove data_type from sar:bands --- extensions/sar/README.md | 1 - extensions/sar/examples/envisat.json | 3 --- extensions/sar/json-schema/schema.json | 12 ------------ 3 files changed, 16 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index bce96c21e..6c26b1028 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -65,7 +65,6 @@ The bands contained in SAR image are dependent on the `sar:type`. For example, s | ------------------- | ------------ | ----------- | | name | string | The name of the band. | | description | string | Description to fully explain the band, should include processing information. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| data_type | string | Specifies the type of the data contained in the band, for example `amplitude`, `intensity`, `phase`, `angle`, `sigma0`, `gamma0`. | | unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | | polarization | string\|null | The polarization of the band, either `HH`, `VV`, `HV`, `VH` or `null` if not applicable. | diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index 6fb8d1a3c..959888dda 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -38,19 +38,16 @@ "sar:looks_range": 3, "sar:looks_azimuth": 4, "sar:frequency_band": "C", - "sar:center_wavelength": 5.623568898893265, "sar:center_frequency": 5.331, "sar:type": "GM1_1P", "sar:bands": [ { "name": "amplitude", - "data_type": "amplitude", "polarization": "HH" }, { "name": "intensity", "description": "Equals the square of the amplitude band", - "data_type": "intensity", "polarization": "HH" } ] diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index 6b2d1cbd5..10a060188 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -78,18 +78,6 @@ "title": "Description of the band", "type": "string" }, - "data_type": { - "title": "Data type of the band", - "type": "string", - "examples": [ - "amplitude", - "intensity", - "phase", - "angle", - "sigma0", - "gamma0" - ] - }, "unit": { "title": "Unit of the band", "type": "string" From efabd1d59eeb3839952de21f2dde0fc181d870f6 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 11:56:58 -0500 Subject: [PATCH 33/87] remove unit from sar:bands --- extensions/sar/README.md | 1 - extensions/sar/json-schema/schema.json | 4 ---- 2 files changed, 5 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 6c26b1028..d14399032 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -65,7 +65,6 @@ The bands contained in SAR image are dependent on the `sar:type`. For example, s | ------------------- | ------------ | ----------- | | name | string | The name of the band. | | description | string | Description to fully explain the band, should include processing information. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| unit | string | The unit of measurement for the data, preferably the symbols from [SI](https://physics.nist.gov/cuu/Units/units.html) or [UDUNITS](https://ncics.org/portfolio/other-resources/udunits2/). | | polarization | string\|null | The polarization of the band, either `HH`, `VV`, `HV`, `VH` or `null` if not applicable. | ## Associating assets with bands diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index 10a060188..94c898fc0 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -78,10 +78,6 @@ "title": "Description of the band", "type": "string" }, - "unit": { - "title": "Unit of the band", - "type": "string" - }, "polarization": { "title": "Polarization of the band", "type": [ From 7b11a3395ba2c8e65c1bb1be9b0a701148ab1d3d Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 11:58:50 -0500 Subject: [PATCH 34/87] update changelog with SAR changes --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 77c42549c..fc513e49b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,7 +35,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead. - Extensions: - Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension. - - Dropped `sar:absolute_orbit` field from `sar` extension due to no known use case + - Removed `sar:absolute_orbit` and `sar:center_wavelength` fields from `sar` extension. + - Removed `data_type` and `unit` from the `sar:bands` object in the `sar` extension. - Removed `dtr` extension prefix from example and schema in [datetime-range extension](extensions/datetime-range/README.md) - STAC API: - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support From de8ba1e90bafaabd2206e68d49e0bfc752eff122 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 12:34:37 -0500 Subject: [PATCH 35/87] examples updates --- extensions/sar/examples/envisat.json | 2 +- extensions/sar/examples/sentinel1.json | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index 6fb8d1a3c..b2dfd59b4 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -28,7 +28,7 @@ "platform": "envisat", "constellation": "envisat", "instruments": ["asar"], - "pass_direction": "descending", + "sat_orbit_state": "descending", "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 index 29be0dc0b..683c725bb 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -29,7 +29,7 @@ "platform": "sentinel-1a", "constellation": "sentinel-1", "instruments": ["c-sar"], - "pass_direction": "ascending", + "sat:orbit_state": "ascending", "relative_orbit": 33, "sar:instrument_mode": "EW", "sar:polarization": ["HH"], @@ -41,7 +41,6 @@ "sar:looks_azimuth": 1, "sar:looks_equivalent_number": 2.7, "sar:frequency_band": "C", - "sar:center_wavelength": 5.546576466235, "sar:center_frequency": 5.405, "sar:type": "GRD", "sar:bands": [ From c9e553d5822524ea47145a74ff34f1293186aaf2 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 12:37:20 -0500 Subject: [PATCH 36/87] rename sat extension to Satellite extension --- extensions/README.md | 2 +- extensions/sat/README.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/extensions/README.md b/extensions/README.md index 59a11fe33..acd301901 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -56,7 +56,7 @@ An extension can add new fields to STAC entities (content extension), or can add | [Label](label/README.md) (`label`) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | | [Point Cloud](pointcloud/README.md) (`pc`) | Item | Provides a way to describe point cloud datasets. The point clouds can come from either active or passive sensors, and data is frequently acquired using tools such as LiDAR or coincidence-matched imagery. | *Proposal* | | [SAR](sar/README.md) (`sar`) | Item | Covers synthetic-aperture radar data that represents a snapshot of the earth for a single date and time. | *Proposal* | -| [sat](sat/README.md) (`sat`) | Item | Satellite related metadata for data collected from satellites. | *Proposal* | +| [Satellite](sat/README.md) (`sat`) | Item | Satellite related metadata for data collected from satellites. | *Proposal* | | [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* | diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 7d2568d58..d1a2d645c 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -1,10 +1,10 @@ -# sat Extension Specification (`sat`) +# Satellite Extension Specification (`sat`) **Extension [Maturity Classification](../README.md#extension-maturity): Proposal** -This document explains the fields of the sat 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#common-fields-and-standalone-collections). +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#common-fields-and-standalone-collections). -The `sat` extension requires the (`instrument` extension)[../instrument/README.md] +The Satellite extension requires the (Instrument extension)[../instrument/README.md]. - [Example (Landsat 8)](examples/example-landsat8.json) - [JSON Schema](json-schema/schema.json) From edce4e5983e26f9c73103fdf4c9fb2563f6d9464 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 12:41:14 -0500 Subject: [PATCH 37/87] remove reference to diagrams in sat extension --- extensions/sat/README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index d1a2d645c..a33aec964 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -27,16 +27,12 @@ The Satellite extension requires the (Instrument extension)[../instrument/README ### 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. These angles are illustrated below. +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: ``` From 2f0cb084a23cacf5b035d0e4ede2a2b76407d370 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 12:42:24 -0500 Subject: [PATCH 38/87] add instrument ext to example in sat ext readme --- extensions/sat/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index a33aec964..6cbc12f49 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -39,7 +39,8 @@ Example: { "stac_version": "0.9.0", "stac_extensions": [ - "sat" + "sat", + "instrument" ], "id": "20171110", "type": "Feature", From feaf131a8a6c0b789c22a92856f6c57c3c0845de Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 12:44:08 -0500 Subject: [PATCH 39/87] misc update --- extensions/sat/README.md | 2 +- extensions/sat/json-schema/schema.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 6cbc12f49..40151ab7c 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -62,7 +62,7 @@ Example: ## Implementations - +- No implementations yet ## Extensions diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index e34675e34..eaf67127c 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -5,7 +5,7 @@ "description": "STAC Sat Extension to a STAC Item.", "allOf": [ { - "$ref": "../../../item-spec/json-schema/item.json#/definitions/core" + "$ref": "../../../item-spec/json-schema/item.json" }, { "$ref": "#/definitions/sat" From d4b522a686e52a4de3a9819cbc84170c40deea7a Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 12:44:55 -0500 Subject: [PATCH 40/87] update schema --- extensions/sat/json-schema/schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index eaf67127c..49b614dac 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -15,7 +15,7 @@ } ], "definitions": { - "eo": { + "sat": { "type": "object", "required": [ "properties" From 696a395fbe3427be865e21d37e8065441716ea8c Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 12:49:13 -0500 Subject: [PATCH 41/87] update instrument schema --- extensions/instrument/json-schema/schema.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/instrument/json-schema/schema.json b/extensions/instrument/json-schema/schema.json index 29ee4b5c3..4163aeff5 100644 --- a/extensions/instrument/json-schema/schema.json +++ b/extensions/instrument/json-schema/schema.json @@ -5,10 +5,10 @@ "description": "STAC Instrument Extension to a STAC Item.", "allOf": [ { - "$ref": "../../../item-spec/json-schema/item.json#/definitions/core" + "$ref": "../../../item-spec/json-schema/item.json" }, { - "$ref": "#/definitions/sat" + "$ref": "#/definitions/instrument" } ], "definitions": { From 00a051ecc2eb22484618744b380c24567e67d80f Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 12:51:33 -0500 Subject: [PATCH 42/87] update sat extension example --- extensions/sat/examples/example-landsat8.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/sat/examples/example-landsat8.json b/extensions/sat/examples/example-landsat8.json index f3ae4bfee..7ade28245 100644 --- a/extensions/sat/examples/example-landsat8.json +++ b/extensions/sat/examples/example-landsat8.json @@ -45,7 +45,7 @@ "sat:sun_azimuth_angle": 168.8989761, "sat:sun_elevation_angle": 26.32596431, "platform": "landsat-8", - "instrument": "oli_tirs", + "instruments": ["oli", "tirs"], "constellation": "landsat", "sat:orbit_state": "ascending", "sat:off_nadir_angle": 0 From 06d1d0610598a701aef777979f847ed09ecec950 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 14:14:02 -0500 Subject: [PATCH 43/87] change sar:type to sar:product --- extensions/sar/README.md | 4 ++-- extensions/sar/examples/envisat.json | 2 +- extensions/sar/examples/sentinel1.json | 2 +- extensions/sar/json-schema/schema.json | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 2fbfd8118..453e802c4 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -23,7 +23,7 @@ If the data has been collected by a satellite, it is strongly recommended to use | sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | | sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. | | sar:bands | [[Band Object](#band-object)] | This is a list of the available bands where each item is a [Band Object](#band-object). | -| sar:type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | +| sar:product | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | | sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | | sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | | sar:pixel_spacing_range | number | The range azimuth, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | @@ -57,7 +57,7 @@ In SAR, you usually have frame start and end time. To describe this information ### Band Object -The bands contained in SAR image are dependent on the `sar:type`. For example, single look complex (SLC) data contain both phase and amplitude information of the signal. This may be provided for instance in form of complex number components (i and q bands) for each available polarization. Multilooked data (for example GRD in case of Sentinel-1) contain only amplitude and intensity bands for each polarization. Geocoded data contain radiometrically calibrated and terrain corrected data such as sigma0 or flattening gamma and may also contain angular information such as projected local incidence angle. Details about each band and the respective processing applied is given in its description. +The bands contained in SAR image are dependent on the `sar:product`. For example, single look complex (SLC) data contain both phase and amplitude information of the signal. This may be provided for instance in form of complex number components (i and q bands) for each available polarization. Multilooked data (for example GRD in case of Sentinel-1) contain only amplitude and intensity bands for each polarization. Geocoded data contain radiometrically calibrated and terrain corrected data such as sigma0 or flattening gamma and may also contain angular information such as projected local incidence angle. Details about each band and the respective processing applied is given in its description. | Field Name | Type | Description | | ------------------- | ------------ | ----------- | diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index f7963d119..a33f9f382 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -39,7 +39,7 @@ "sar:looks_azimuth": 4, "sar:frequency_band": "C", "sar:center_frequency": 5.331, - "sar:type": "GM1_1P", + "sar:product": "GM1_1P", "sar:bands": [ { "name": "amplitude", diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json index 683c725bb..4a7689e39 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -42,7 +42,7 @@ "sar:looks_equivalent_number": 2.7, "sar:frequency_band": "C", "sar:center_frequency": 5.405, - "sar:type": "GRD", + "sar:product": "GRD", "sar:bands": [ { "name": "band_1", diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index 94c898fc0..16a3e94dd 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -24,7 +24,7 @@ "sar:instrument_mode", "sar:frequency_band", "sar:polarization", - "sar:type" + "sar:product" ], "properties": { "sar:instrument_mode": { @@ -95,7 +95,7 @@ } } }, - "sar:type": { + "sar:product": { "title": "Product type", "type": "string", "examples": [ From d6c2e66dd269de1f04287b9ef9bcbe9a4b18339f Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 14:17:58 -0500 Subject: [PATCH 44/87] update CHANGELOG with SAR changes --- CHANGELOG.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index acee0d564..115a5688a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema. - Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / WKT2) for reference systems. - [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)). + - Changed `sar:type` to `sar:product` in the [SAR extension](extensions/sar/README.md).. - STAC API: - The endpoint `/stac` has been merged with `/` - The endpoint `/stac/search` is now called `/search` @@ -35,9 +36,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead. - Removed `summaries` field from Catalogs. Use Collections instead. - Extensions: - - Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension. - - Removed `sar:absolute_orbit` and `sar:center_wavelength` fields from `sar` extension. - - Removed `data_type` and `unit` from the `sar:bands` object in the `sar` extension. + - Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from the [SAR extension](extensions/sar/README.md).. + - Removed `sar:absolute_orbit` and `sar:center_wavelength` fields from the [SAR extension](extensions/sar/README.md). + - Removed `data_type` and `unit` from the `sar:bands` object in the [SAR extension](extensions/sar/README.md).. - Removed `dtr` extension prefix from example and schema in [datetime-range extension](extensions/datetime-range/README.md) - STAC API: - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support From 9628b076809babdd7b48a8917621e8ffeb6880c4 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 15:23:58 -0500 Subject: [PATCH 45/87] fix outdated examples with new field names --- collection-spec/examples/landsat-item.json | 4 ++-- extensions/README.md | 4 ++-- extensions/single-file-stac/examples/example-search.json | 6 +++--- item-spec/examples/planet-sample.json | 4 ++-- item-spec/examples/sentinel2-sample.json | 2 +- item-spec/item-spec.md | 2 +- 6 files changed, 11 insertions(+), 11 deletions(-) diff --git a/collection-spec/examples/landsat-item.json b/collection-spec/examples/landsat-item.json index 4b52572af..a34e21984 100644 --- a/collection-spec/examples/landsat-item.json +++ b/collection-spec/examples/landsat-item.json @@ -45,8 +45,8 @@ "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "eo:sun_azimuth": 168.8989761, - "eo:sun_elevation": 26.32596431, + "eo:sun_azimuth_angle": 168.8989761, + "eo:sun_elevation_angle": 26.32596431, "landsat:path": 107, "landsat:row": 18 }, diff --git a/extensions/README.md b/extensions/README.md index adcb3b8f8..52394bac4 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -115,8 +115,8 @@ An example of this can be seen in a Landsat example: "eo:off_nadir": -0.001, "eo:cloud_cover": 10.31, - "eo:sun_azimuth": 149.01607154, - "eo:sun_elevation": 59.21424700, + "eo:sun_azimuth_angle": 149.01607154, + "eo:sun_elevation_angle": 59.21424700, "eo:gsd": 30, "l8:data_type": "L1T", diff --git a/extensions/single-file-stac/examples/example-search.json b/extensions/single-file-stac/examples/example-search.json index 31e940388..a05c97ffb 100644 --- a/extensions/single-file-stac/examples/example-search.json +++ b/extensions/single-file-stac/examples/example-search.json @@ -40,7 +40,7 @@ }, "properties": { "datetime": "2018-02-08T18:02:15.719478+00:00", - "eo:sun_azimuth": 152.63804142, + "eo:sun_azimuth_angle": 152.63804142, "eo:sun_elevation": 31.82216637, "eo:cloud_cover": 19, "eo:row": "033", @@ -207,8 +207,8 @@ }, "properties": { "datetime": "2018-02-03T17:43:44.623405+00:00", - "eo:sun_azimuth": 153.39513457, - "eo:sun_elevation": 30.41894816, + "eo:sun_azimuth_angle": 153.39513457, + "eo:sun_elevation_angle": 30.41894816, "eo:cloud_cover": 36, "eo:row": "033", "eo:column": "034", diff --git a/item-spec/examples/planet-sample.json b/item-spec/examples/planet-sample.json index 1b219af33..b411624c5 100644 --- a/item-spec/examples/planet-sample.json +++ b/item-spec/examples/planet-sample.json @@ -62,8 +62,8 @@ "datetime": "2017-11-10T12:10:30.535417Z", "eo:cloud_cover": 23, "eo:gsd": 3.7, - "sat:sun_azimuth": 101.8, - "sat:sun_elevation": 58.8, + "sat:sun_azimuth_angle": 101.8, + "sat:sun_elevation_angle": 58.8, "sat:off_nadir_angle": 1, "pl:acquired": "2017-11-10T12:10:30.535417Z", "pl:anomalous_pixels": 0.14, diff --git a/item-spec/examples/sentinel2-sample.json b/item-spec/examples/sentinel2-sample.json index b6e4ed6c8..fccd12fa9 100644 --- a/item-spec/examples/sentinel2-sample.json +++ b/item-spec/examples/sentinel2-sample.json @@ -304,6 +304,6 @@ "platform": "sentinel-2", "eo:epsg": 32635, "eo:cloud_cover": 88.459539, - "eo:sun_azimuth" : 176.091667178268 + "eo:sun_azimuth_angle" : 176.091667178268 } } diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index db31e2f99..f62c1e81a 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -62,7 +62,7 @@ Items that are linked to, but the best practices around this are still emerging. The Properties object adds additional metadata to the GeoJSON Object. Additional fields can be introduced through extensions. It is generally allowed to add custom fields. -It is recommended to add multiple attributes for related values instead of a nested object, e.g., two fields `eo:cloud_cover` and `eo:sun_azimuth` 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`. +It is recommended to add multiple attributes for related values instead of a nested object, e.g., two fields `eo:cloud_cover` and `eo:sun_azimuth_angle` 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`. | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------ | From 31020bbdf2f462de6124d68f6061836de424ce56 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 16:14:34 -0500 Subject: [PATCH 46/87] update old eo fields to sat --- collection-spec/examples/landsat-item.json | 4 ++-- extensions/README.md | 6 +++--- extensions/single-file-stac/examples/example-search.json | 8 ++++---- item-spec/examples/digitalglobe-sample.json | 2 +- item-spec/examples/sentinel2-sample.json | 2 +- item-spec/item-spec.md | 2 +- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/collection-spec/examples/landsat-item.json b/collection-spec/examples/landsat-item.json index a34e21984..aee45dc71 100644 --- a/collection-spec/examples/landsat-item.json +++ b/collection-spec/examples/landsat-item.json @@ -45,8 +45,8 @@ "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "eo:sun_azimuth_angle": 168.8989761, - "eo:sun_elevation_angle": 26.32596431, + "sat:sun_azimuth_angle": 168.8989761, + "sat:sun_elevation_angle": 26.32596431, "landsat:path": 107, "landsat:row": 18 }, diff --git a/extensions/README.md b/extensions/README.md index 52394bac4..4edf6c16f 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -113,10 +113,10 @@ An example of this can be seen in a Landsat example: "dtr:start_datetime":"2018-01-01T13:21:30Z", "dtr:end_datetime":"2018-01-01T13:31:30Z", - "eo:off_nadir": -0.001, + "sat:off_nadir_angle": -0.001, "eo:cloud_cover": 10.31, - "eo:sun_azimuth_angle": 149.01607154, - "eo:sun_elevation_angle": 59.21424700, + "sat:sun_azimuth_angle": 149.01607154, + "sat:sun_elevation_angle": 59.21424700, "eo:gsd": 30, "l8:data_type": "L1T", diff --git a/extensions/single-file-stac/examples/example-search.json b/extensions/single-file-stac/examples/example-search.json index a05c97ffb..1d408da74 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", - "eo:sun_azimuth_angle": 152.63804142, - "eo:sun_elevation": 31.82216637, + "sat:sun_azimuth_angle": 152.63804142, + "sat: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", - "eo:sun_azimuth_angle": 153.39513457, - "eo:sun_elevation_angle": 30.41894816, + "sat:sun_azimuth_angle": 153.39513457, + "sat:sun_elevation_angle": 30.41894816, "eo:cloud_cover": 36, "eo:row": "033", "eo:column": "034", diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json index 7477bd931..cf8932456 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -74,7 +74,7 @@ "sat:sun_azimuth_angle": 168.7, "eo:cloud_cover": 50, "sat:off_nadir_angle": 18.4, - "eo:azimuth": 34.5, + "sat:azimuth": 34.5, "platform": "worldview02", "sat:sun_elevation_angle": 33.4, "eo:gsd": 2.047, diff --git a/item-spec/examples/sentinel2-sample.json b/item-spec/examples/sentinel2-sample.json index fccd12fa9..7fa507004 100644 --- a/item-spec/examples/sentinel2-sample.json +++ b/item-spec/examples/sentinel2-sample.json @@ -304,6 +304,6 @@ "platform": "sentinel-2", "eo:epsg": 32635, "eo:cloud_cover": 88.459539, - "eo:sun_azimuth_angle" : 176.091667178268 + "sat:sun_azimuth_angle" : 176.091667178268 } } diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index f62c1e81a..30d1ea754 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -62,7 +62,7 @@ Items that are linked to, but the best practices around this are still emerging. The Properties object adds additional metadata to the GeoJSON Object. Additional fields can be introduced through extensions. It is generally allowed to add custom fields. -It is recommended to add multiple attributes for related values instead of a nested object, e.g., two fields `eo:cloud_cover` and `eo:sun_azimuth_angle` 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`. +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 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`. | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------ | From 248ac35aa32d311925e1e4143af5ab3f3a3790b8 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 16:16:20 -0500 Subject: [PATCH 47/87] remove old dtr prefix from examples --- extensions/README.md | 6 +++--- extensions/sar/examples/sentinel1.json | 4 ++-- extensions/scientific/examples/item.json | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/extensions/README.md b/extensions/README.md index 4edf6c16f..8ad419bcf 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -51,7 +51,7 @@ An extension can add new fields to STAC entities (content extension), or can add | [Checksum](checksum/README.md) (`checksum`) | Item, Catalog, Collection | Provides a way to specify file checksums for assets and links in Items, Catalogs and Collections. | *Proposal* | | [Commons](commons/README.md) (-) | Item, Collection | Provides a way to specify data fields in a collection that are common across the STAC Items in that collection, so that each does not need to repeat all the same information. | *Proposal* | | [Data Cube](datacube/README.md) (`cube`) | Item, Collection | Data Cube related metadata, especially to describe their dimensions. | *Proposal* | -| [Datetime Range](datetime-range/README.md) (`dtr`) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | +| [Datetime Range](datetime-range/README.md) (-) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | | [EO](eo/README.md) (`eo`) | Item | Covers electro-optical data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, gsd and more. | *Pilot* | | [Instrument](instrument/README.md) (-) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | | [Label](label/README.md) (`label`) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | @@ -110,8 +110,8 @@ An example of this can be seen in a Landsat example: "properties": { "datetime":"2018-01-01T13:21:30Z", - "dtr:start_datetime":"2018-01-01T13:21:30Z", - "dtr:end_datetime":"2018-01-01T13:31:30Z", + "start_datetime":"2018-01-01T13:21:30Z", + "end_datetime":"2018-01-01T13:31:30Z", "sat:off_nadir_angle": -0.001, "eo:cloud_cover": 10.31, diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json index 683c725bb..e2234d8f3 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -24,8 +24,8 @@ }, "properties": { "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", + "start_datetime": "2018-11-03T23:58:55.121559Z", + "end_datetime": "2018-11-03T23:59:55.112875Z", "platform": "sentinel-1a", "constellation": "sentinel-1", "instruments": ["c-sar"], diff --git a/extensions/scientific/examples/item.json b/extensions/scientific/examples/item.json index 9560de0f8..e51f15426 100644 --- a/extensions/scientific/examples/item.json +++ b/extensions/scientific/examples/item.json @@ -20,8 +20,8 @@ "title": "MERRAclim. 2_5m_min_80s", "description": "MERRAclim Dataset. 19 global bioclimatic variables from the 1980s decade at 2.5 arcminutes resolution in GEOtiff format. The humidity version used is the min. The variables have been built using the same protocol as WorldClim with data from MERRA. Temperature layers (BIO1-BIO11) are in degree Celsius multiplied by 10, humidity layers (BIO12-BIO19) are in kg of water/kg of air multiplied by 100000.", "datetime": "1985-07-01T00:00:00Z", - "dtr:start_datetime": "1980-01-01T00:00:00Z", - "dtr:end_datetime": "1989-12-31T23:59:59Z", + "start_datetime": "1980-01-01T00:00:00Z", + "end_datetime": "1989-12-31T23:59:59Z", "sci:doi": "10.5061/dryad.s2v81.2/27.2", "sci:publications": [ { From d348737d367ae3aa177305790e45748698f6d81a Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 16:18:49 -0500 Subject: [PATCH 48/87] change sar:product to sar:product_type --- CHANGELOG.md | 2 +- extensions/sar/README.md | 4 ++-- extensions/sar/examples/envisat.json | 2 +- extensions/sar/examples/sentinel1.json | 2 +- extensions/sar/json-schema/schema.json | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 115a5688a..caba9a470 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,7 +23,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema. - Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / WKT2) for reference systems. - [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)). - - Changed `sar:type` to `sar:product` in the [SAR extension](extensions/sar/README.md).. + - Changed `sar:type` to `sar:product_type` in the [SAR extension](extensions/sar/README.md).. - STAC API: - The endpoint `/stac` has been merged with `/` - The endpoint `/stac/search` is now called `/search` diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 453e802c4..91e9af129 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -23,7 +23,7 @@ If the data has been collected by a satellite, it is strongly recommended to use | sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | | sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. | | sar:bands | [[Band Object](#band-object)] | This is a list of the available bands where each item is a [Band Object](#band-object). | -| sar:product | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | +| sar:product_type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | | sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | | sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | | sar:pixel_spacing_range | number | The range azimuth, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | @@ -57,7 +57,7 @@ In SAR, you usually have frame start and end time. To describe this information ### Band Object -The bands contained in SAR image are dependent on the `sar:product`. For example, single look complex (SLC) data contain both phase and amplitude information of the signal. This may be provided for instance in form of complex number components (i and q bands) for each available polarization. Multilooked data (for example GRD in case of Sentinel-1) contain only amplitude and intensity bands for each polarization. Geocoded data contain radiometrically calibrated and terrain corrected data such as sigma0 or flattening gamma and may also contain angular information such as projected local incidence angle. Details about each band and the respective processing applied is given in its description. +The bands contained in SAR image are dependent on the `sar:product_type`. For example, single look complex (SLC) data contain both phase and amplitude information of the signal. This may be provided for instance in form of complex number components (i and q bands) for each available polarization. Multilooked data (for example GRD in case of Sentinel-1) contain only amplitude and intensity bands for each polarization. Geocoded data contain radiometrically calibrated and terrain corrected data such as sigma0 or flattening gamma and may also contain angular information such as projected local incidence angle. Details about each band and the respective processing applied is given in its description. | Field Name | Type | Description | | ------------------- | ------------ | ----------- | diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index a33f9f382..7e774dd90 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -39,7 +39,7 @@ "sar:looks_azimuth": 4, "sar:frequency_band": "C", "sar:center_frequency": 5.331, - "sar:product": "GM1_1P", + "sar:product_type": "GM1_1P", "sar:bands": [ { "name": "amplitude", diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json index 4a7689e39..47dfad6b6 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -42,7 +42,7 @@ "sar:looks_equivalent_number": 2.7, "sar:frequency_band": "C", "sar:center_frequency": 5.405, - "sar:product": "GRD", + "sar:product_type": "GRD", "sar:bands": [ { "name": "band_1", diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index 16a3e94dd..ffc3752f4 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -24,7 +24,7 @@ "sar:instrument_mode", "sar:frequency_band", "sar:polarization", - "sar:product" + "sar:product_type" ], "properties": { "sar:instrument_mode": { @@ -95,7 +95,7 @@ } } }, - "sar:product": { + "sar:product_type": { "title": "Product type", "type": "string", "examples": [ From 2753f732b4a5e7dbf8bf0422353c7cffd2fbbd25 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 16:32:26 -0500 Subject: [PATCH 49/87] add asset description to asset objects --- item-spec/examples/landsat8-sample.json | 50 +++++++++++++++++++------ item-spec/item-spec.md | 12 +++--- item-spec/json-schema/item.json | 4 ++ 3 files changed, 49 insertions(+), 17 deletions(-) diff --git a/item-spec/examples/landsat8-sample.json b/item-spec/examples/landsat8-sample.json index 281381106..fe441948a 100644 --- a/item-spec/examples/landsat8-sample.json +++ b/item-spec/examples/landsat8-sample.json @@ -68,67 +68,93 @@ "thumbnail": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_thumb_large.jpg", "type": "image/jpeg", + "title": "Thumbnail", + "description": "A medium sized thumbnail", "role": "thumbnail" }, "metadata": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_MTL.txt", "type": "mtl", - "role": "metadata" + "role": "metadata", + "title": "Original Metadata", + "description": "The original MTL metadata file provided for each Landsat scene" }, "B1": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B1.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [0] + "eo:bands": [0], + "title": "Coastal Band (B1)", + "description": "Coastal Band Top Of the Atmosphere" }, "B2": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B2.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [1] + "eo:bands": [1], + "title": "Blue Band (B2)", + "description": "Blue Band Top Of the Atmosphere" }, "B3": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B3.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [2] + "eo:bands": [2], + "title": "Green Band (B3)", + "description": "Green Band (B3) Top Of the Atmosphere" }, "B4": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B4.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [3] + "eo:bands": [3], + "title": "Red Band (B4)", + "description": "Red Band (B4) Top Of the Atmosphere" }, "B5": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B5.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [4] + "eo:bands": [4], + "title": "NIR Band (B5)", + "description": "NIR Band (B5) Top Of the Atmosphere" }, "B6": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B6.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [5] + "eo:bands": [5], + "title": "SWIR Band (B6)", + "description": "SWIR Band at 1.6um (B6) Top Of the Atmosphere" }, "B7": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B7.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [6] + "eo:bands": [6], + "title": "SWIR Band (B7)", + "description": "SWIR Band at 2.2um (B7) Top Of the Atmosphere" }, "B8": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B8.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [7] + "eo:bands": [7], + "title": "Panchromatic Band (B8)", + "description": "Panchromatic Band (B8) Top Of the Atmosphere" }, "B9": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B9.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [8] + "eo:bands": [8], + "title": "Cirrus Band (B9)", + "description": "Cirrus Band (B9) Top Of the Atmosphere - for cirrus cloud detection" }, "B10": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B10.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [9] + "eo:bands": [9], + "title": "LWIR Band (B10)", + "description": "Long-wave IR Band at 11um (B10) Top Of the Atmosphere" }, "B11": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_B11.TIF", "type": "image/tiff; application=geotiff", - "eo:bands": [10] + "eo:bands": [10], + "title": "LWIR Band (B11)", + "description": "Long-wave IR Band at 12um (B11) Top Of the Atmosphere" } } } diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index db31e2f99..44fce4305 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -168,12 +168,14 @@ or streamed. It is allowed to add additional fields. | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------- | | href | string | **REQUIRED.** Link to the asset object. Relative and absolute links are both allowed. | -| title | string | The displayed title for clients and users. | -| type | string | [Media type](#media-types) of the asset. | -| role | string | The semantic purpose of the asset. | +| title | string | The displayed title for clients and users | +| description | string | A description of the Asset | +| type | string | [Media type](#media-types) of the asset | +| role | string | The semantic purpose of the asset | -**role** is intended to be a value that describes semantic usage of an asset, similarly to the use of `rel` in -Link. +**description** is more verbose than a simple title and could provide details on the asset, such as how it was processed + +**role** is intended to be a value that describes semantic usage of an asset, similarly to the use of `rel` in Link. #### Asset Role Types diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index c30c43b52..586f999f0 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -206,6 +206,10 @@ "title": "Asset title", "type": "string" }, + "description": { + "title": "Asset description", + "type": "string" + }, "type": { "title": "Asset type", "type": "string" From 59d6fd01bcd12ab7555f685e346fccc0eed34f62 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 16:40:46 -0500 Subject: [PATCH 50/87] update CHANGELOG with asset description --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b6e3d73a..3e6747171 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## Unreleased ### Added -- ItemCollection requires `stac_version` field, `stac_extensions` has also been added. +- ItemCollection requires `stac_version` field, `stac_extensions` has also been added +- A `description` field has been added to Item Assets - Extensions: - [Version Indicators extension](extensions/version/README.md), adds `version` and `deprecated` fields to STAC Items and Collections. - Instrument extension, adds fields: `platform`, `instruments`, `constellation` (all moved from EO and SAR extensions), and `mission`. From 90b20b42939b4dc382d7607ce1f1f228126fba71 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 16:43:15 -0500 Subject: [PATCH 51/87] update asset table --- item-spec/item-spec.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 44fce4305..c649b7d80 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -169,17 +169,13 @@ or streamed. It is allowed to add additional fields. | ---------- | ------ | ------------------------------------------------------------------------------------- | | href | string | **REQUIRED.** Link to the asset object. Relative and absolute links are both allowed. | | title | string | The displayed title for clients and users | -| description | string | A description of the Asset | +| description | string | A description of the Asset providing additional details, such as how it was processed | | type | string | [Media type](#media-types) of the asset | -| role | string | The semantic purpose of the asset | +| role | string | The semantic purpose of the asset, similar to the use of `rel` in links | -**description** is more verbose than a simple title and could provide details on the asset, such as how it was processed - -**role** is intended to be a value that describes semantic usage of an asset, similarly to the use of `rel` in Link. - #### Asset Role Types -Like the Link `rel` field, the `role` field can be given any value. These are a few standardized role names. +Like the Link `rel` field, the `role` field can be given any value, however here are a few standardized role names. | Role Name | Description | | --------- | ------------------------------------------------------------------------------------- | From 9493f3dfa572309c1e04d6f0f01718b382101582 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 16:52:06 -0500 Subject: [PATCH 52/87] update asset definition with role and description --- extensions/asset/README.md | 7 +- .../asset/examples/example-landsat8.json | 106 +++++++----------- extensions/asset/json-schema/schema.json | 8 ++ 3 files changed, 56 insertions(+), 65 deletions(-) diff --git a/extensions/asset/README.md b/extensions/asset/README.md index 261d3bb24..5dd236b89 100644 --- a/extensions/asset/README.md +++ b/extensions/asset/README.md @@ -29,8 +29,11 @@ An asset is an object that contains details about the datafiles that will be inc | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------- | -| title | string | **REQUIRED.** The displayed title for clients and users. This should provide enough information to a user to understand what the asset is | -| type | string | **REQUIRED.** [Media type](../../item-spec/item-spec.md#media-types) of the asset. +| title | string | The displayed title for clients and users | +| description | string | A description of the Asset providing additional details, such as how it was processed or created | +| type | string | [Media type](#media-types) of the asset | +| role | string | The semantic purpose of the asset, similar to the use of `rel` in links + Other custom fields, or fields from other extensions may also be included in the Asset object. diff --git a/extensions/asset/examples/example-landsat8.json b/extensions/asset/examples/example-landsat8.json index e78fcea1a..0f98ad168 100644 --- a/extensions/asset/examples/example-landsat8.json +++ b/extensions/asset/examples/example-landsat8.json @@ -149,103 +149,83 @@ ] }, "assets": { - "index": { - "type": "text/html", - "title": "HTML index page" - }, "thumbnail": { - "title": "Thumbnail image", - "type": "image/jpeg" + "type": "image/jpeg", + "title": "Thumbnail", + "description": "A medium sized thumbnail", + "role": "thumbnail" + }, + "metadata": { + "type": "mtl", + "role": "metadata", + "title": "Original Metadata", + "description": "The original MTL metadata file provided for each Landsat scene" }, "B1": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 0 - ], - "title": "Band 1 (coastal)" + "eo:bands": [0], + "title": "Coastal Band (B1)", + "description": "Coastal Band Top Of the Atmosphere" }, "B2": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 1 - ], - "title": "Band 2 (blue)" + "eo:bands": [1], + "title": "Blue Band (B2)", + "description": "Blue Band Top Of the Atmosphere" }, "B3": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 2 - ], - "title": "Band 3 (green)" + "eo:bands": [2], + "title": "Green Band (B3)", + "description": "Green Band (B3) Top Of the Atmosphere" }, "B4": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 3 - ], - "title": "Band 4 (red)" + "eo:bands": [3], + "title": "Red Band (B4)", + "description": "Red Band (B4) Top Of the Atmosphere" }, "B5": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 4 - ], - "title": "Band 5 (nir)" + "eo:bands": [4], + "title": "NIR Band (B5)", + "description": "NIR Band (B5) Top Of the Atmosphere" }, "B6": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 5 - ], - "title": "Band 6 (swir16)" + "eo:bands": [5], + "title": "SWIR Band (B6)", + "description": "SWIR Band at 1.6um (B6) Top Of the Atmosphere" }, "B7": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 6 - ], - "title": "Band 7 (swir22)" + "eo:bands": [6], + "title": "SWIR Band (B7)", + "description": "SWIR Band at 2.2um (B7) Top Of the Atmosphere" }, "B8": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 7 - ], - "title": "Band 8 (pan)" + "eo:bands": [7], + "title": "Panchromatic Band (B8)", + "description": "Panchromatic Band (B8) Top Of the Atmosphere" }, "B9": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 8 - ], - "title": "Band 9 (cirrus)" + "eo:bands": [8], + "title": "Cirrus Band (B9)", + "description": "Cirrus Band (B9) Top Of the Atmosphere - for cirrus cloud detection" }, "B10": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 9 - ], - "title": "Band 10 (lwir)" + "eo:bands": [9], + "title": "LWIR Band (B10)", + "description": "Long-wave IR Band at 11um (B10) Top Of the Atmosphere" }, "B11": { "type": "image/tiff; application=geotiff", - "eo:bands": [ - 10 - ], - "title": "Band 11 (lwir)" + "eo:bands": [10], + "title": "LWIR Band (B11)", + "description": "Long-wave IR Band at 12um (B11) Top Of the Atmosphere" }, - "ANG": { - "title": "Angle coefficients file", - "type": "text/plain" - }, - "MTL": { - "title": "original metadata file", - "type": "text/plain" - }, - "BQA": { - "title": "Band quality data", - "type": "image/tiff; application=geotiff" - } - }, "links": [] } \ No newline at end of file diff --git a/extensions/asset/json-schema/schema.json b/extensions/asset/json-schema/schema.json index d480732b6..da89de3be 100644 --- a/extensions/asset/json-schema/schema.json +++ b/extensions/asset/json-schema/schema.json @@ -38,9 +38,17 @@ "title": "Asset title", "type": "string" }, + "description": { + "title": "Asset description", + "type": "string" + }, "type": { "title": "Asset type", "type": "string" + }, + "role": { + "title": "Asset role", + "type": "string" } } } From c37c18b0bc7e67cedcb7c347cf1c0836adc573c0 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 16:53:38 -0500 Subject: [PATCH 53/87] update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e6747171..b13ba27f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - [Version Indicators extension](extensions/version/README.md), adds `version` and `deprecated` fields to STAC Items and Collections. - Instrument extension, adds fields: `platform`, `instruments`, `constellation` (all moved from EO and SAR extensions), and `mission`. - Data Cube extension can be used in Collections, added new field `description`. + - Added `description` and `role` fields to the Asset in the [Asset Extension](extensions/asset/README.md) - STAC API: - Added the [Item and Collection API Version extension](api-spec/extensions/version/README.md) to support versioning in the API specification From ccc3987dfd4d17892e823adaf1453d41927ecbf9 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 17:25:50 -0500 Subject: [PATCH 54/87] fix more examples --- extensions/single-file-stac/examples/example-search.json | 2 +- item-spec/examples/digitalglobe-sample.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/extensions/single-file-stac/examples/example-search.json b/extensions/single-file-stac/examples/example-search.json index 1d408da74..873758a36 100644 --- a/extensions/single-file-stac/examples/example-search.json +++ b/extensions/single-file-stac/examples/example-search.json @@ -41,7 +41,7 @@ "properties": { "datetime": "2018-02-08T18:02:15.719478+00:00", "sat:sun_azimuth_angle": 152.63804142, - "sat:sun_elevation": 31.82216637, + "sat:sun_elevation_angle": 31.82216637, "eo:cloud_cover": 19, "eo:row": "033", "eo:column": "037", diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json index cf8932456..7bbe454ae 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -74,7 +74,7 @@ "sat:sun_azimuth_angle": 168.7, "eo:cloud_cover": 50, "sat:off_nadir_angle": 18.4, - "sat:azimuth": 34.5, + "sat:azimuth_angle": 34.5, "platform": "worldview02", "sat:sun_elevation_angle": 33.4, "eo:gsd": 2.047, From 2cb53cc502ee9303318e97ec071b92da38a500ab Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 19 Nov 2019 21:00:44 -0500 Subject: [PATCH 55/87] remove sar:bands from SAR Extension --- extensions/checksum/examples/sentinel1.json | 4 +-- extensions/sar/README.md | 17 +----------- extensions/sar/examples/envisat.json | 16 +++-------- extensions/sar/examples/sentinel1.json | 10 ++----- extensions/sar/json-schema/schema.json | 30 --------------------- 5 files changed, 7 insertions(+), 70 deletions(-) diff --git a/extensions/checksum/examples/sentinel1.json b/extensions/checksum/examples/sentinel1.json index 260524332..d46840296 100644 --- a/extensions/checksum/examples/sentinel1.json +++ b/extensions/checksum/examples/sentinel1.json @@ -44,9 +44,7 @@ "href": "./measurement/s1a-ew-grd-hh-20181103t235855-20181103t235955-024430-02ad5d-001.tiff", "title": "Measurements", "type": "image/tiff", - "sar:bands": [ - 0 - ], + "sar:polarizations": ["HH"], "checksum:multihash": "90e40210163700a8a6501eccd00b6d3b44ddaed0" }, "thumbnail": { diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 91e9af129..f69424de0 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -22,7 +22,6 @@ If the data has been collected by a satellite, it is strongly recommended to use | 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. | | sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | | sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. | -| sar:bands | [[Band Object](#band-object)] | This is a list of the available bands where each item is a [Band Object](#band-object). | | sar:product_type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | | sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | | sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | @@ -55,24 +54,10 @@ properties. The table below shows the common name based on the wavelength and fr In SAR, you usually have frame start and end time. To describe this information it is recommended to use the [Datetime Range Extension Specification](../datetime-range/README.md). The center time of the frame should be specified with the `datetime` property for [STAC Items](../../item-spec/item-spec.md). -### Band Object - -The bands contained in SAR image are dependent on the `sar:product_type`. For example, single look complex (SLC) data contain both phase and amplitude information of the signal. This may be provided for instance in form of complex number components (i and q bands) for each available polarization. Multilooked data (for example GRD in case of Sentinel-1) contain only amplitude and intensity bands for each polarization. Geocoded data contain radiometrically calibrated and terrain corrected data such as sigma0 or flattening gamma and may also contain angular information such as projected local incidence angle. Details about each band and the respective processing applied is given in its description. - -| Field Name | Type | Description | -| ------------------- | ------------ | ----------- | -| name | string | The name of the band. | -| description | string | Description to fully explain the band, should include processing information. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| polarization | string\|null | The polarization of the band, either `HH`, `VV`, `HV`, `VH` or `null` if not applicable. | - -## Associating assets with bands - -Asset definitions that contain band data should reference the band index. Each asset should provide a `sar:bands` property that is an array of 0 based indexes to the correct [Band Objects](#band-object). - ### Item [`Asset Object`](../../item-spec/item-spec.md#asset-object) fields | Field Name | Type | Description | | ---------- | -------- | -------------------------------------------- | -| sar:bands | [number] | Lists the band names available in the asset. | +| sar:polarizations | [string] | Lists the polarizations available in the asset, in order. One of `HH`, `VV`, `HV`, `VH` | ## Extensions diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index 7e774dd90..45f0807e1 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -39,24 +39,14 @@ "sar:looks_azimuth": 4, "sar:frequency_band": "C", "sar:center_frequency": 5.331, - "sar:product_type": "GM1_1P", - "sar:bands": [ - { - "name": "amplitude", - "polarization": "HH" - }, - { - "name": "intensity", - "description": "Equals the square of the amplitude band", - "polarization": "HH" - } - ] + "sar:product_type": "GM1_1P" }, "assets": { "product": { "href": "ASA_GM1_1PNPDE20090520_023957_000001022079_00118_37747_3607.n1.gz", "type": "application/gzip", - "sar:bands": [0,1] + "description": "Amplitude and Intensity. Intensity equals the square of the amplitude band", + "sar:polarizations": ["HH", "HH"] } }, "links": [ diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json index 47dfad6b6..b38ac9d9a 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -42,13 +42,7 @@ "sar:looks_equivalent_number": 2.7, "sar:frequency_band": "C", "sar:center_frequency": 5.405, - "sar:product_type": "GRD", - "sar:bands": [ - { - "name": "band_1", - "polarization": "HH" - } - ] + "sar:product_type": "GRD" }, "assets": { "noises": { @@ -73,7 +67,7 @@ "href": "./measurement/s1a-ew-grd-hh-20181103t235855-20181103t235955-024430-02ad5d-001.tiff", "title": "Measurements", "type": "image/tiff", - "sar:bands": [0], + "sar:bands": ["HH"], "checksum:multihash": "90e40210163700a8a6501eccd00b6d3b44ddaed0" }, "thumbnail": { diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index ffc3752f4..2b213cf6b 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -65,36 +65,6 @@ ] } }, - "sar:bands": { - "title": "Bands", - "type": "array", - "items": { - "properties": { - "name": { - "title": "Name of the band", - "type": "string" - }, - "description": { - "title": "Description of the band", - "type": "string" - }, - "polarization": { - "title": "Polarization of the band", - "type": [ - "string", - "null" - ], - "enum": [ - "HH", - "VV", - "HV", - "VH", - null - ] - } - } - } - }, "sar:product_type": { "title": "Product type", "type": "string", From ea21ee7a1bc8169a948fdf56323eadba61e9e6b9 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Wed, 20 Nov 2019 17:46:38 -0500 Subject: [PATCH 56/87] Specify how to read no URL proprietary license Closes #664 --- collection-spec/collection-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 05a31b5df..e8a95efdd 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -130,7 +130,7 @@ The following types are commonly used as `rel` types in the Link Object of a Col | parent | URL to the parent STAC [Catalog](../catalog-spec/README.md) or Collection. Non-root collections should include a link to their parent. | | child | URL to a child STAC [Catalog](../catalog-spec/) or Collection. | | item | URL to a STAC [Item](../item-spec/item-spec.md). All items linked from a collection MUST refer back to its collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | -| license | The license URL(s) for the collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to supplement the STAC catalog with the license text in a separate file and link to this file. | +| license | The license URL(s) for the collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If no URLs are specified and the `license` field is set to `proprietary`, the collection is private, and consumers have not been granted any explicit right to use the data. If there is no public license URL available, it is RECOMMENDED to supplement the STAC catalog with the license text in a separate file and link to this file. | | derived_from | URL to a STAC Collection that was used as input data in the creation of this collection. See the note in [STAC Item](../item-spec/item-spec.md#relation-types) for more info. | **Note:** The [STAC Catalog specification](../catalog-spec/catalog-spec.md) requires a link to at least one `item` or `child` catalog. This is _not_ a requirement for collections, but _recommended_. In contrast to catalogs, it is **REQUIRED** that items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). From f3044e1cea05828a765a7194332bfe3c98653c6c Mon Sep 17 00:00:00 2001 From: James Santucci Date: Thu, 21 Nov 2019 09:51:14 -0500 Subject: [PATCH 57/87] Also update item spec --- item-spec/item-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index a6a8e7806..139d29f2e 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -67,7 +67,7 @@ It is recommended to add multiple attributes for related values instead of a nes | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------ | | datetime | string | **REQUIRED.** The searchable date and time of the assets, in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | -| license | string | Item's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the [`license` relation type](#relation-types). | +| license | string | Item's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the [`license` relation type](#relation-types). If no links are included and the `license` field is set to `proprietary`, the item is private, and consumers have not been granted any explicit right to use the data. | | providers | [[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | | title | string | A human readable title describing the item. | | created | string | Creation date and time of this metadata file. This is NOT the timestamp the asset was created. MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | From a3f0e0c0da4bf6435bbba59e6651eb459d61c213 Mon Sep 17 00:00:00 2001 From: James Santucci Date: Thu, 21 Nov 2019 11:16:43 -0500 Subject: [PATCH 58/87] Move proprietary explanation to field --- collection-spec/collection-spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 25854e58b..74edf11d5 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -31,7 +31,7 @@ Implementations are encouraged, however, as good effort will be made to not chan | title | string | A short descriptive one-line title for the collection. | | description | string | **REQUIRED.** Detailed multi-line description to fully explain the collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | keywords | [string] | List of keywords describing the collection. | -| license | string | **REQUIRED.** Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the `license` link relation type. | +| license | string | **REQUIRED.** Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the `license` link relation type. If no links are included and the `license` field is set to `proprietary`, the collection is private, and consumers have not been granted any explicit right to use the data. | | providers | [[Provider Object](#provider-object) | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | | extent | [Extent Object](#extent-object) | **REQUIRED.** Spatial and temporal extents. | | summaries | Map | A map of property summaries, either a set of values or statistics such as a range. | @@ -128,7 +128,7 @@ The following types are commonly used as `rel` types in the Link Object of a Col | parent | URL to the parent STAC [Catalog](../catalog-spec/README.md) or Collection. Non-root collections should include a link to their parent. | | child | URL to a child STAC [Catalog](../catalog-spec/) or Collection. | | item | URL to a STAC [Item](../item-spec/item-spec.md). All items linked from a collection MUST refer back to its collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | -| license | The license URL(s) for the collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If no URLs are specified and the `license` field is set to `proprietary`, the collection is private, and consumers have not been granted any explicit right to use the data. If there is no public license URL available, it is RECOMMENDED to supplement the STAC catalog with the license text in a separate file and link to this file. | +| license | The license URL(s) for the collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to supplement the STAC catalog with the license text in a separate file and link to this file. | | derived_from | URL to a STAC Collection that was used as input data in the creation of this collection. See the note in [STAC Item](../item-spec/item-spec.md#relation-types) for more info. | **Note:** The [STAC Catalog specification](../catalog-spec/catalog-spec.md) requires a link to at least one `item` or `child` catalog. This is _not_ a requirement for collections, but _recommended_. In contrast to catalogs, it is **REQUIRED** that items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). From 7a9c0813631eb77e39df5e15a5ec707af7866fc5 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 21 Nov 2019 17:41:04 +0100 Subject: [PATCH 59/87] Updated Changelog --- CHANGELOG.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b13ba27f9..ad118dd70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,9 +22,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Collection field `property` and the merge ability moved to a new extension 'Commons' - Added attribute `role` to Item assets, to be used similarly to Link `rel`. - Extensions: - - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema. - - Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / WKT2) for reference systems. - - [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)). + - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema. + - Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / WKT2) for reference systems. + - [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)). - STAC API: - The endpoint `/stac` has been merged with `/` - The endpoint `/stac/search` is now called `/search` @@ -45,7 +45,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Fixed -- Clarifications and typos +- The `license` field in Item and Collection spec explicitly mentions that the value `proprietary` without a link means that the data is private. +- Clarifications; typos fixed ## [v0.8.1] - 2019-11-01 From aac5bb1def69ceafe310953e063e5ec4a2d96fad Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 11:03:24 +0100 Subject: [PATCH 60/87] Update collection extensions --- collection-spec/collection-spec.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 74edf11d5..885980e9a 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -154,10 +154,11 @@ The data provider is free to decide, which fields are reasoable to be used. ## Extensions -Important related extensions for the STAC Collection Specification: +Commonly used extensions for the STAC Collection specification: -* [Commons extension](../extensions/commons/README.md), which primarily allows to add shared Item metadata to Collections, - but could also be used to describe Collections better that are not referring to Items by adding additional fields from Item extensions. - Please note that this extension is only in '[proposal](../extensions/README.md#extension-maturity)' stage. +* [Asset Definition](../extensions/asset/README.md): Allows to indicate the structure of the Item assets. +* [Commons extension](../extensions/commons/README.md): Allows to add shared Item metadata to Collections. +* [Scientific extension](../extensions/scientific/README.md): Add fields to indicate citations and DOIs. +* [Versioning Indicators extension](../extensions/version/README.md): Allows versioning by adding the fields `version` and `deprecated`. The [extensions page](../extensions/README.md) gives a full overview about relevant extensions for STAC Collections. From 9320da325c2863de21c0ce84275520872929383e Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 11:03:45 +0100 Subject: [PATCH 61/87] Formatting, minor clarifications. --- extensions/README.md | 6 +++--- extensions/commons/README.md | 4 ++-- extensions/instrument/README.md | 12 ++++++------ 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/extensions/README.md b/extensions/README.md index 8ad419bcf..2dfce572d 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -51,13 +51,13 @@ An extension can add new fields to STAC entities (content extension), or can add | [Checksum](checksum/README.md) (`checksum`) | Item, Catalog, Collection | Provides a way to specify file checksums for assets and links in Items, Catalogs and Collections. | *Proposal* | | [Commons](commons/README.md) (-) | Item, Collection | Provides a way to specify data fields in a collection that are common across the STAC Items in that collection, so that each does not need to repeat all the same information. | *Proposal* | | [Data Cube](datacube/README.md) (`cube`) | Item, Collection | Data Cube related metadata, especially to describe their dimensions. | *Proposal* | -| [Datetime Range](datetime-range/README.md) (-) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | +| [Datetime Range](datetime-range/README.md) (-) | Item | An extension to provide datetime ranges with a start and an end datetime stamp in a consistent way. | *Proposal* | | [EO](eo/README.md) (`eo`) | Item | Covers electro-optical data that represents a snapshot of the earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, gsd and more. | *Pilot* | -| [Instrument](instrument/README.md) (-) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | +| [Instrument](instrument/README.md) (-) | Item | Adds metadata specifying a platform and instrument used in a data collection mission. | *Proposal* | | [Label](label/README.md) (`label`) | Item | Items that relate labeled AOIs with source imagery | *Proposal* | | [Point Cloud](pointcloud/README.md) (`pc`) | Item | Provides a way to describe point cloud datasets. The point clouds can come from either active or passive sensors, and data is frequently acquired using tools such as LiDAR or coincidence-matched imagery. | *Proposal* | | [SAR](sar/README.md) (`sar`) | Item | Covers synthetic-aperture radar data that represents a snapshot of the earth for a single date and time. | *Proposal* | -| [Satellite](sat/README.md) (`sat`) | Item | Satellite related metadata for data collected from satellites. | *Proposal* | +| [Satellite](sat/README.md) (`sat`) | Item | Satellite related metadata for data collected from satellites. | *Proposal* | | [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* | diff --git a/extensions/commons/README.md b/extensions/commons/README.md index a54ec793a..cf098df02 100644 --- a/extensions/commons/README.md +++ b/extensions/commons/README.md @@ -10,9 +10,9 @@ A group of STAC Item objects from a single source can share a lot of common meta ## Item fields -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 can be removed and added to the Collection properties. Since a Collection contains no properties itself, anything under properties are metadata fields that are common across all member Items. +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 colleciton. 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 `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. 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. diff --git a/extensions/instrument/README.md b/extensions/instrument/README.md index d9646473c..47d8236bb 100644 --- a/extensions/instrument/README.md +++ b/extensions/instrument/README.md @@ -9,12 +9,12 @@ This document explains the fields of the Instrument Extension to a STAC Item, wh ## Item fields -| Field Name | Type | Description | -| ---------------- | ------------------------ | ----------- | -| platform | string | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. | -| instruments | [string] | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | -| constellation | string | Name of the constellation to which the platform belongs. | -| mission | string | Name of the mission for which data is collected. | +| Field Name | Type | Description | +| ------------- | -------- | ----------- | +| platform | string | **REQUIRED.** Unique name of the specific platform to which the instrument is attached. | +| instruments | [string] | **REQUIRED.** Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | +| constellation | string | Name of the constellation to which the platform belongs. | +| mission | string | Name of the mission for which data is collected. | **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 From 990a9c1bd5682ab520d700650e027670bd44e093 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 11:18:21 +0100 Subject: [PATCH 62/87] Clarify usage of Commons extension #671 --- extensions/commons/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/extensions/commons/README.md b/extensions/commons/README.md index cf098df02..8303691c5 100644 --- a/extensions/commons/README.md +++ b/extensions/commons/README.md @@ -4,6 +4,10 @@ A group of STAC Item objects from a single source can share a lot of common metadata. This is especially true with satellite imagery that uses the STAC EO Extension. Rather than including these common metadata fields on every Item, they can be provided into the [STAC Collection](../../collection-spec/README.md) that the STAC Items belong to. +This extensions makes most sense in **static catalogs** to move common information to a central place. This reduces duplication of metadata and makes updates to static catalogs easier. It also makes navigating a static catalog easier as user know in advance which common fields to expect although Items can better be summarized with the `summaries` field in Collections. Therefore it is recommended to use the summaries for this use case and only use the Commons extension to avoid data duplication. + +In **API implementations** the Commons extension should not be used as it leads to less intuitive search results. For example, a search result for Items may not include the fields a user has searched for as it has been moved to the Collection, which may lead to confusion. Also, data duplication in dynamically created responses is usually not an issue and APIs derived from static catalogs can simply merge the common fields back into the Items for the response. In this case the `stac_extensions` field should not contain the `commons` extension any longer. + - [Examples](examples/): - Landsat 8: An [Item](examples/landsat-item.json) that uses the Commons extension to place shared data in a [Collection](examples/landsat-collection.json). - [JSON Schema](json-schema/schema.json) From 0532cee749a9a549051d9fc46d7d246409e84939 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 11:47:13 +0100 Subject: [PATCH 63/87] 1. Simplified description for license in Collection and Items. SPDX expressions now disallowed (SPDX License Identifier still allowed), use `various` instead. Also ask for a license link if a SPDX license identifier has been specified. 2. Item field `bbox` refers to GeoJSON bbox spec directly. 3. Link directly to respective GeoJSON RFC chapters. --- catalog-spec/catalog-spec.md | 8 +++----- collection-spec/collection-spec.md | 10 +++++----- item-spec/item-spec.md | 26 ++++++++++++++------------ 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 60d8f6d15..f68a87a01 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -115,15 +115,13 @@ details on the two types and how you might use them see the [Static and Dynamic | Element | Type | Description | | ------------ | ------------- | ------------------------------------------------------------ | -| stac_version | string | **REQUIRED.** The STAC version the catalog implements. | +| stac_version | string | **REQUIRED.** The STAC version the catalog implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. | | stac_extensions | [string] | A list of extensions the Catalog implements. | | id | string | **REQUIRED.** Identifier for the catalog. | | title | string | A short descriptive one-line title for the catalog. | | description | string | **REQUIRED.** Detailed multi-line description to fully explain the catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | -**stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. - **stac_extensions**: A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file. ### Link Object @@ -141,8 +139,8 @@ with links. A more complete list of possible 'rel' types can be seen at the [IANA page of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) - for a discussion on that topic, as well as the [use of links](../best-practices.md#use-of-links) section of the - catalog best practices document. +for a discussion on that topic, as well as the [use of links](../best-practices.md#use-of-links) section of the +catalog best practices document. #### Relation types diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 885980e9a..3bbfae397 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -25,22 +25,22 @@ Implementations are encouraged, however, as good effort will be made to not chan | Element | Type | Description | | ------------ | ----------------- | ------------------------------------------------------------ | -| stac_version | string | **REQUIRED.** The STAC version the Collection implements. | +| stac_version | string | **REQUIRED.** The STAC version the Collection implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. | | stac_extensions | [string] | A list of extensions the Collection implements. | | id | string | **REQUIRED.** Identifier for the collection that is unique across the provider. | | title | string | A short descriptive one-line title for the collection. | | description | string | **REQUIRED.** Detailed multi-line description to fully explain the collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | keywords | [string] | List of keywords describing the collection. | -| license | string | **REQUIRED.** Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the `license` link relation type. If no links are included and the `license` field is set to `proprietary`, the collection is private, and consumers have not been granted any explicit right to use the data. | -| providers | [[Provider Object](#provider-object) | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | +| license | string | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. | +| providers | [[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | | extent | [Extent Object](#extent-object) | **REQUIRED.** Spatial and temporal extents. | | summaries | Map | A map of property summaries, either a set of values or statistics such as a range. | | links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | -**stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. - **stac_extensions**: A list of extensions the Collection implements. This does NOT declare the extensions of child Catalogs or Items. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. If the versions of the extension and the collection diverge, you can specify the URL of the JSON schema file. +**license**: Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/). Alternatively, use `proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply. In all cases links to the license texts SHOULD be added, see the `license` link relation type. If no link to a license is included and the `license` field is set to `proprietary`, the collection is private, and consumers have not been granted any explicit right to use the data. + **summaries**: You can optionally summarize the potential values that are available as part of the `properties` in STAC Items. Summaries are used to inform users about values they can expect from items without having to crawl through them. It also helps do fully define collections, especially if they don't link to any Items. Summaries are either a unique set of all values or statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 29b91dc22..194ea6f0c 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -39,8 +39,8 @@ inherited from GeoJSON. | stac_extensions | [string] | A list of extensions the Item implements. | | id | string | **REQUIRED.** Provider identifier. As most geospatial assets are already defined by some identification scheme by the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their IDs globally unique, including things like unique satellite IDs. | | type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. | -| geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) | **REQUIRED.** Defines the full footprint of the asset represented by this item, formatted according to [RFC 7946, section 3.1](https://tools.ietf.org/html/rfc7946). The footprint should be the default GeoJSON geometry, though additional geometries can be included. Coordinates are specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). | -| bbox | [number] | **REQUIRED.** Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array must be 2*n where n is the number of dimensions. The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters and the elevation of the northeasterly most extent is the maximum. This field enables more naive clients to easily index and search geospatially. STAC compliant APIs are required to compute intersection operations with the item's geometry field, not its bbox. | +| geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) | **REQUIRED.** Defines the full footprint of the asset represented by this item, formatted according to [RFC 7946, section 3.1](https://tools.ietf.org/html/rfc7946#section-3.1). The footprint should be the default GeoJSON geometry, though additional geometries can be included. Coordinates are specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). | +| bbox | [number] | **REQUIRED.** Bounding Box of the asset represented by this item, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). | | properties | [Properties Object](#properties-object) | **REQUIRED.** A dictionary of additional metadata for the item. | | links | [[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. A link with the `rel` set to `self` is strongly recommended. | | assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. Some pre-defined keys are listed in the chapter '[Asset types](#asset-types)'. | @@ -57,6 +57,8 @@ by multiple files - all should be linked to. It is generally recommended that di levels or formats are not exhaustively listed in an Item, but instead are represented by related Items that are linked to, but the best practices around this are still emerging. +**bbox**: Bounding Box of the asset represented by this item using either 2D or 3D geometries, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). The length of the array must be 2*n where n is the number of dimensions. The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters and the elevation of the northeasterly most extent is the maximum. This field enables more naive clients to easily index and search geospatially. STAC compliant APIs are required to compute intersection operations with the item's geometry field, not its bbox. + ### Properties Object The Properties object adds additional metadata to the GeoJSON Object. Additional fields can be introduced through @@ -67,8 +69,8 @@ It is recommended to add multiple attributes for related values instead of a nes | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------ | | datetime | string | **REQUIRED.** The searchable date and time of the assets, in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | -| license | string | Item's license(s) as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the [`license` relation type](#relation-types). If no links are included and the `license` field is set to `proprietary`, the item is private, and consumers have not been granted any explicit right to use the data. | -| providers | [[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | +| license | string | Item's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. Should be defined at the Collection level if possible. | +| providers | [[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. Should be defined at the Collection level if possible. | | title | string | A human readable title describing the item. | | created | string | Creation date and time of this metadata file. This is NOT the timestamp the asset was created. MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | | updated | string | Date and time this metadata file was updated last. This is NOT the timestamp the asset was updated last. MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | @@ -80,7 +82,7 @@ data, so use whatever single date and time is most useful for a user to search f extensions may further specify the meaning of the main `datetime` field, and many will also add more datetime fields. -**license** and **provider** should be defined at the Collection level if possible. +**license**: Items's license(s) as a SPDX [License identifier](https://spdx.org/licenses/). Alternatively, use `proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply. In all cases links to the license texts SHOULD be added, see the [`license` link relation type](#relation-types). If no link to a license is included and the `license` field is set to `proprietary`, the collection is private, and consumers have not been granted any explicit right to use the data. ### Provider Object @@ -165,13 +167,13 @@ using the [Commons extension](../extensions/commons/README.md) to avoid duplicat An asset is an object that contains a link to data associated with the Item that can be downloaded or streamed. It is allowed to add additional fields. -| Field Name | Type | Description | -| ---------- | ------ | ------------------------------------------------------------------------------------- | -| href | string | **REQUIRED.** Link to the asset object. Relative and absolute links are both allowed. | -| title | string | The displayed title for clients and users | -| description | string | A description of the Asset providing additional details, such as how it was processed | -| type | string | [Media type](#media-types) of the asset | -| role | string | The semantic purpose of the asset, similar to the use of `rel` in links | +| Field Name | Type | Description | +| ----------- | ------ | ----------- | +| href | string | **REQUIRED.** Link to the asset object. Relative and absolute links are both allowed. | +| title | string | The displayed title for clients and users. | +| description | string | A description of the Asset providing additional details, such as how it was processed. | +| type | string | [Media type](#media-types) of the asset. | +| role | string | The semantic purpose of the asset, similar to the use of `rel` in links. | #### Asset Role Types From ffcfd4223a87be89efd1f3baea3b56cbd784442f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 11:50:50 +0100 Subject: [PATCH 64/87] Aligned Asset Definition and Item Assets and fixed Asset Definition example. --- extensions/asset/README.md | 13 +- .../asset/examples/example-landsat8.json | 450 +++++++++--------- item-spec/item-spec.md | 2 +- 3 files changed, 245 insertions(+), 220 deletions(-) diff --git a/extensions/asset/README.md b/extensions/asset/README.md index 5dd236b89..820ab62ed 100644 --- a/extensions/asset/README.md +++ b/extensions/asset/README.md @@ -27,13 +27,12 @@ Additioanlly the remaining fields, `title` and `type` are required in the Asset An asset is an object that contains details about the datafiles that will be included in member Items. Assets included at the Collection level do not imply that all assets are available from all Items. However, it is recommended that the Asset Definition is a complete set of all assets that may be available from any member Items. -| Field Name | Type | Description | -| ---------- | ------ | ------------------------------------------------------------------------------------- | -| title | string | The displayed title for clients and users | -| description | string | A description of the Asset providing additional details, such as how it was processed or created | -| type | string | [Media type](#media-types) of the asset | -| role | string | The semantic purpose of the asset, similar to the use of `rel` in links - +| Field Name | Type | Description | +| ----------- | ------ | ----------- | +| title | string | The displayed title for clients and users. | +| description | string | A description of the Asset providing additional details, such as how it was processed or created. | +| type | string | [Media type](#media-types) of the asset. | +| role | string | The semantic purpose of the asset, similar to the use of `rel` in links. | Other custom fields, or fields from other extensions may also be included in the Asset object. diff --git a/extensions/asset/examples/example-landsat8.json b/extensions/asset/examples/example-landsat8.json index 0f98ad168..b0e4ff1b2 100644 --- a/extensions/asset/examples/example-landsat8.json +++ b/extensions/asset/examples/example-landsat8.json @@ -1,231 +1,257 @@ { - "id": "landsat-8-l1", - "title": "Landsat 8 L1", - "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", - "keywords": [ - "landsat", - "earth observation", - "usgs" - ], - "stac_version": "0.8.1", - "stac_extensions": [ - "asset", - "commons" - ], - "extent": { - "spatial": { - "bbox": [ - [ - -180, - -90, - 180, - 90 - ] + "id": "landsat-8-l1", + "title": "Landsat 8 L1", + "description": "Landat 8 imagery radiometrically calibrated and orthorectified using gound points and Digital Elevation Model (DEM) data to correct relief displacement.", + "keywords": [ + "landsat", + "earth observation", + "usgs" + ], + "stac_version": "0.8.1", + "stac_extensions": [ + "asset", + "commons" + ], + "extent": { + "spatial": { + "bbox": [ + [ + -180, + -90, + 180, + 90 ] - }, - "temporal": { - "interval": [ - [ - "2013-06-01T00:00:00Z", - null - ] + ] + }, + "temporal": { + "interval": [ + [ + "2013-06-01T00:00:00Z", + null ] - } + ] + } + }, + "providers": [ + { + "name": "USGS", + "roles": [ + "producer" + ], + "url": "https://landsat.usgs.gov/" }, - "providers": [ + { + "name": "Planet Labs", + "roles": [ + "processor" + ], + "url": "https://github.com/landsat-pds/landsat_ingestor" + }, + { + "name": "AWS", + "roles": [ + "host" + ], + "url": "https://landsatonaws.com/" + }, + { + "name": "Development Seed", + "roles": [ + "processor" + ], + "url": "https://github.com/sat-utils/sat-api" + } + ], + "license": "PDDL-1.0", + "properties": { + "eo:gsd": 15, + "platform": "landsat-8", + "instruments": [ + "oli", + "tirs" + ], + "sat:off_nadir_angle": 0, + "eo:bands": [ { - "name": "USGS", - "roles": [ - "producer" - ], - "url": "https://landsat.usgs.gov/" + "name": "B1", + "common_name": "coastal", + "gsd": 30, + "center_wavelength": 0.44, + "full_width_half_max": 0.02 }, { - "name": "Planet Labs", - "roles": [ - "processor" - ], - "url": "https://github.com/landsat-pds/landsat_ingestor" + "name": "B2", + "common_name": "blue", + "gsd": 30, + "center_wavelength": 0.48, + "full_width_half_max": 0.06 }, { - "name": "AWS", - "roles": [ - "host" - ], - "url": "https://landsatonaws.com/" + "name": "B3", + "common_name": "green", + "gsd": 30, + "center_wavelength": 0.56, + "full_width_half_max": 0.06 }, { - "name": "Development Seed", - "roles": [ - "processor" - ], - "url": "https://github.com/sat-utils/sat-api" - } - ], - "license": "PDDL-1.0", - "properties": { - "eo:gsd": 15, - "platform": "landsat-8", - "instruments": ["oli", "tirs"], - "sat:off_nadir_angle": 0, - "eo:bands": [ - { - "name": "B1", - "common_name": "coastal", - "gsd": 30, - "center_wavelength": 0.44, - "full_width_half_max": 0.02 - }, - { - "name": "B2", - "common_name": "blue", - "gsd": 30, - "center_wavelength": 0.48, - "full_width_half_max": 0.06 - }, - { - "name": "B3", - "common_name": "green", - "gsd": 30, - "center_wavelength": 0.56, - "full_width_half_max": 0.06 - }, - { - "name": "B4", - "common_name": "red", - "gsd": 30, - "center_wavelength": 0.65, - "full_width_half_max": 0.04 - }, - { - "name": "B5", - "common_name": "nir", - "gsd": 30, - "center_wavelength": 0.86, - "full_width_half_max": 0.03 - }, - { - "name": "B6", - "common_name": "swir16", - "gsd": 30, - "center_wavelength": 1.6, - "full_width_half_max": 0.08 - }, - { - "name": "B7", - "common_name": "swir22", - "gsd": 30, - "center_wavelength": 2.2, - "full_width_half_max": 0.2 - }, - { - "name": "B8", - "common_name": "pan", - "gsd": 15, - "center_wavelength": 0.59, - "full_width_half_max": 0.18 - }, - { - "name": "B9", - "common_name": "cirrus", - "gsd": 30, - "center_wavelength": 1.37, - "full_width_half_max": 0.02 - }, - { - "name": "B10", - "common_name": "lwir11", - "gsd": 100, - "center_wavelength": 10.9, - "full_width_half_max": 0.8 - }, - { - "name": "B11", - "common_name": "lwir12", - "gsd": 100, - "center_wavelength": 12, - "full_width_half_max": 1 - } - ] - }, - "assets": { - "thumbnail": { - "type": "image/jpeg", - "title": "Thumbnail", - "description": "A medium sized thumbnail", - "role": "thumbnail" - }, - "metadata": { - "type": "mtl", - "role": "metadata", - "title": "Original Metadata", - "description": "The original MTL metadata file provided for each Landsat scene" - }, - "B1": { - "type": "image/tiff; application=geotiff", - "eo:bands": [0], - "title": "Coastal Band (B1)", - "description": "Coastal Band Top Of the Atmosphere" - }, - "B2": { - "type": "image/tiff; application=geotiff", - "eo:bands": [1], - "title": "Blue Band (B2)", - "description": "Blue Band Top Of the Atmosphere" - }, - "B3": { - "type": "image/tiff; application=geotiff", - "eo:bands": [2], - "title": "Green Band (B3)", - "description": "Green Band (B3) Top Of the Atmosphere" - }, - "B4": { - "type": "image/tiff; application=geotiff", - "eo:bands": [3], - "title": "Red Band (B4)", - "description": "Red Band (B4) Top Of the Atmosphere" - }, - "B5": { - "type": "image/tiff; application=geotiff", - "eo:bands": [4], - "title": "NIR Band (B5)", - "description": "NIR Band (B5) Top Of the Atmosphere" + "name": "B4", + "common_name": "red", + "gsd": 30, + "center_wavelength": 0.65, + "full_width_half_max": 0.04 }, - "B6": { - "type": "image/tiff; application=geotiff", - "eo:bands": [5], - "title": "SWIR Band (B6)", - "description": "SWIR Band at 1.6um (B6) Top Of the Atmosphere" + { + "name": "B5", + "common_name": "nir", + "gsd": 30, + "center_wavelength": 0.86, + "full_width_half_max": 0.03 }, - "B7": { - "type": "image/tiff; application=geotiff", - "eo:bands": [6], - "title": "SWIR Band (B7)", - "description": "SWIR Band at 2.2um (B7) Top Of the Atmosphere" + { + "name": "B6", + "common_name": "swir16", + "gsd": 30, + "center_wavelength": 1.6, + "full_width_half_max": 0.08 }, - "B8": { - "type": "image/tiff; application=geotiff", - "eo:bands": [7], - "title": "Panchromatic Band (B8)", - "description": "Panchromatic Band (B8) Top Of the Atmosphere" + { + "name": "B7", + "common_name": "swir22", + "gsd": 30, + "center_wavelength": 2.2, + "full_width_half_max": 0.2 }, - "B9": { - "type": "image/tiff; application=geotiff", - "eo:bands": [8], - "title": "Cirrus Band (B9)", - "description": "Cirrus Band (B9) Top Of the Atmosphere - for cirrus cloud detection" + { + "name": "B8", + "common_name": "pan", + "gsd": 15, + "center_wavelength": 0.59, + "full_width_half_max": 0.18 }, - "B10": { - "type": "image/tiff; application=geotiff", - "eo:bands": [9], - "title": "LWIR Band (B10)", - "description": "Long-wave IR Band at 11um (B10) Top Of the Atmosphere" + { + "name": "B9", + "common_name": "cirrus", + "gsd": 30, + "center_wavelength": 1.37, + "full_width_half_max": 0.02 }, - "B11": { - "type": "image/tiff; application=geotiff", - "eo:bands": [10], - "title": "LWIR Band (B11)", - "description": "Long-wave IR Band at 12um (B11) Top Of the Atmosphere" + { + "name": "B10", + "common_name": "lwir11", + "gsd": 100, + "center_wavelength": 10.9, + "full_width_half_max": 0.8 }, + { + "name": "B11", + "common_name": "lwir12", + "gsd": 100, + "center_wavelength": 12, + "full_width_half_max": 1 + } + ] + }, + "assets": { + "thumbnail": { + "type": "image/jpeg", + "title": "Thumbnail", + "description": "A medium sized thumbnail", + "role": "thumbnail" + }, + "metadata": { + "type": "mtl", + "role": "metadata", + "title": "Original Metadata", + "description": "The original MTL metadata file provided for each Landsat scene" + }, + "B1": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 0 + ], + "title": "Coastal Band (B1)", + "description": "Coastal Band Top Of the Atmosphere" + }, + "B2": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 1 + ], + "title": "Blue Band (B2)", + "description": "Blue Band Top Of the Atmosphere" + }, + "B3": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 2 + ], + "title": "Green Band (B3)", + "description": "Green Band (B3) Top Of the Atmosphere" + }, + "B4": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 3 + ], + "title": "Red Band (B4)", + "description": "Red Band (B4) Top Of the Atmosphere" + }, + "B5": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 4 + ], + "title": "NIR Band (B5)", + "description": "NIR Band (B5) Top Of the Atmosphere" + }, + "B6": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 5 + ], + "title": "SWIR Band (B6)", + "description": "SWIR Band at 1.6um (B6) Top Of the Atmosphere" + }, + "B7": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 6 + ], + "title": "SWIR Band (B7)", + "description": "SWIR Band at 2.2um (B7) Top Of the Atmosphere" + }, + "B8": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 7 + ], + "title": "Panchromatic Band (B8)", + "description": "Panchromatic Band (B8) Top Of the Atmosphere" + }, + "B9": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 8 + ], + "title": "Cirrus Band (B9)", + "description": "Cirrus Band (B9) Top Of the Atmosphere - for cirrus cloud detection" + }, + "B10": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 9 + ], + "title": "LWIR Band (B10)", + "description": "Long-wave IR Band at 11um (B10) Top Of the Atmosphere" + }, + "B11": { + "type": "image/tiff; application=geotiff", + "eo:bands": [ + 10 + ], + "title": "LWIR Band (B11)", + "description": "Long-wave IR Band at 12um (B11) Top Of the Atmosphere" + }, "links": [] - } \ No newline at end of file + } +} \ No newline at end of file diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 194ea6f0c..dbf1c1b59 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -171,7 +171,7 @@ or streamed. It is allowed to add additional fields. | ----------- | ------ | ----------- | | href | string | **REQUIRED.** Link to the asset object. Relative and absolute links are both allowed. | | title | string | The displayed title for clients and users. | -| description | string | A description of the Asset providing additional details, such as how it was processed. | +| description | string | A description of the Asset providing additional details, such as how it was processed or created. | | type | string | [Media type](#media-types) of the asset. | | role | string | The semantic purpose of the asset, similar to the use of `rel` in links. | From 494b009d2939b172b05074eff7e4e74a23d5094b Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 12:11:13 +0100 Subject: [PATCH 65/87] Merge Catalog Types from STAC Catalogs into front page Design Overview. #678 --- README.md | 34 ++++++++++++++++++++++------------ catalog-spec/catalog-spec.md | 15 --------------- extensions/asset/README.md | 6 +++--- 3 files changed, 25 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 6295e9f4b..b4dd82459 100644 --- a/README.md +++ b/README.md @@ -82,30 +82,40 @@ An important core principle of the STAC design is to embrace best practices of m to leverage the reliability of flat files on object stores like [AWS S3](https://aws.amazon.com/s3/) and [Google Cloud Storage](https://cloud.google.com/storage/). This lead to designing a static catalog at the core of the STAC spec. +### Catalog Types + +STAC Catalogs generally fall into two different types: Static Catalogs and Dynamic Catalog APIs. + +The two catalog types both implement the same fields and links, and can be treated as the same by clients. +For more details on the two types see the chapters below. Additionally, consider the [Static and Dynamic Catalogs](../best-practices.md#static-and-dynamic-catalogs) +section of the best practices document on how you might use them best. + #### Static Catalog -A static catalog is an implementation of the STAC specification that does not respond dynamically to requests - it is simply -a set of files on a web server that link to one another in a way that can be crawled. A static catalog can only really be -crawled by search engines and active catalogs; it can not respond to queries. But it is incredibly reliable, as there are -no moving parts, no clusters or databases to maintain. The goal of STAC is to expose as much asset metadata online as -possible, so the static catalog offers a very lower barrier to entry for anyone with geospatial assets to make their data -searchable. +A static catalog is an implementation of the STAC specification that does not respond dynamically to requests. It is simply +a set of files on a web server that link to one another in a way that can be crawled, often stored in an cloud storage +service like [Amazon S3](https://aws.amazon.com/s3/) or [Google Cloud Storage](https://cloud.google.com/storage/). +The core JSON documents and link structures are encoded in the file, and work as long as things are structured properly. +A static catalog can only really be crawled by search engines and active catalogs; it can not respond to queries. +But it is incredibly reliable, as there are no moving parts, no clusters or databases to maintain. +The goal of STAC is to expose as much asset metadata online as possible, so the static catalog offers a very lower +barrier to entry for anyone with geospatial assets to make their data searchable. -#### Catalog API +#### Dynamic Catalog API -A catalog API is a RESTful API that responds to queries (like give me all imagery in Oahu gathered on January 15, 2017). -But its structure and responses are designed to mirror the static catalog, so the same client and crawler tools can consume -it. It generally indexes data for efficient responses, and aims to be easy for existing API's to implement as a more standard +A dynamic catalog API is implemented in software as a RESTful API that responds to queries (like give me all imagery in Oahu gathered on January 15, 2017). +Its structure and responses are usually generated dynamically and are designed to mirror the static catalog, so the same client and crawler tools can consume +it. It generally indexes data for efficient responses, and aims to be easy for existing APIs to implement as a more standard interface for clients to consume. It is specified in OpenAPI 3.0. An active catalog will often be populated by a static catalog, or at least may have a 'backup' of its fields stored as a cached static catalog. -#### Core Metadata and Extensions +### Core Metadata and Extensions The Item specification defines the core fields that all assets must make available for searching in a catalog. In addition there are some basic fields for describing collections of data. Vendors can extend those core fields for the metadata they want to make available, and the community has started to define shared extensions. -#### UML Diagram +### UML Diagram A UML diagram of the [STAC model](STAC-UML.pdf) is provided to help with navigating the specification. diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index f68a87a01..d70d8e48b 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -96,21 +96,6 @@ the [best practices document](../best-practices.md), and include things like cat publishing catalogs, and more. This specification is designed for maximum flexbility, but the best practices provide guidance for good recommendations when implementing. -### Catalog Types - -Though it is technically an implementation detail outside the scope of the core specification, it is worth mentioning -that implementations generally fall into two different 'types': - -* **Static Catalogs** can be implemented as simply files online, often stored in an cloud storage service like [Amazon S3](https://aws.amazon.com/s3/). -or [Google Cloud Storage](https://cloud.google.com/storage/). -The core JSON documents and link structures are encoded in the file, and work as long as things are structured properly. -* **Dynamic Catalogs** are implemented in software, returning the JSON documents and links dynamically. This is mostly -used when data holdings are already exposed through a dynamic interface, and STAC can be an alternate facade on the -same core database or search cluster. - -The two catalog types both implement the same fields and links, and can be treated as the same by clients. For more -details on the two types and how you might use them see the [Static and Dynamic Catalogs](../best-practices.md#static-and-dynamic-catalogs) section of the best practices document. - ## Catalog fields | Element | Type | Description | diff --git a/extensions/asset/README.md b/extensions/asset/README.md index 820ab62ed..3a082c3ec 100644 --- a/extensions/asset/README.md +++ b/extensions/asset/README.md @@ -19,9 +19,9 @@ An Asset Object defined at the Collection level is nearly the same as the [Asset The `href` field is not required, because collections don't point to any data by themselves. Additioanlly the remaining fields, `title` and `type` are required in the Asset Definition, in order for it to adequately describe Item assets. -| Field Name | Type | Description | -| ------------------ | ------ | ------------------------------------------------------------ | -| assets | Map | **REQUIRED.** A dictionary of assets that can be found in member Items | +| Field Name | Type | Description | +| ---------- | ------------------------------------------ | ----------- | +| assets | Map | **REQUIRED.** A dictionary of assets that can be found in member Items | ### Asset Object From 400998462f7cab5e02ffdf17238a4d42c9e7c7b3 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 13:49:55 +0100 Subject: [PATCH 66/87] Explain how to use stac_extensions #669 --- api-spec/extensions/README.md | 18 ++++++++++-------- catalog-spec/catalog-spec.md | 3 ++- collection-spec/collection-spec.md | 3 ++- item-spec/item-spec.md | 3 ++- item-spec/itemcollection-spec.md | 22 ++++++++++++---------- 5 files changed, 28 insertions(+), 21 deletions(-) diff --git a/api-spec/extensions/README.md b/api-spec/extensions/README.md index 0be0a7adc..e75843b9e 100644 --- a/api-spec/extensions/README.md +++ b/api-spec/extensions/README.md @@ -9,14 +9,16 @@ API Extensions given follow the same guidelines for Extension Maturity as given ## List of community extensions -| Extension Name | Description | Maturity | -| ------------- | ----------- | -------- | -| [Fields](fields/README.md) | Adds parameter to control which fields are returned in the response. | *Pilot* | -| [Query](query/README.md) | Adds parameter to search Item and Collection properties. | *Pilot* | -| [Context](context/README.md) | Adds search related metadata (context) to [ItemCollection](../../item-spec/itemcollection-spec.md). | *Proposal* | -| [Sort](sort/README.md) | Adds Parameter to control sorting of returns results. | *Pilot* | -| [Transaction](transaction/README.md) | Adds PUT and DELETE endpoints for the creation, editing, and deleting of items and Collections. | *Pilot* | -| [Items and Collections API Version](version/README.md) | Adds GET versions resource to collections and items endpoints and provides semantics for a versioning scheme for collections and items. | *Proposal* | +| Extension Name | Scope* | Description | Maturity | +| ------------------------------------------------------ | -------------- | ----------- | -------- | +| [Fields](fields/README.md) | *None* | Adds parameter to control which fields are returned in the response. | *Pilot* | +| [Query](query/README.md) | *None* | Adds parameter to search Item and Collection properties. | *Pilot* | +| [Context](context/README.md) | ItemCollection | Adds search related metadata (context) to [ItemCollection](../../item-spec/itemcollection-spec.md). | *Proposal* | +| [Sort](sort/README.md) | *None* | Adds Parameter to control sorting of returns results. | *Pilot* | +| [Transaction](transaction/README.md) | *None* | Adds PUT and DELETE endpoints for the creation, editing, and deleting of items and Collections. | *Pilot* | +| [Items and Collections API Version](version/README.md) | *None* | Adds GET versions resource to collections and items endpoints and provides semantics for a versioning scheme for collections and items. | *Proposal* | + +\* The scope refers to the STAC specifications an extension extends. As all extensions here are API extensions, the API is not mentioned explicitly as scope and only the core STAC specifications (Catalog, Collection, Item and ItemCollection) are listed. ## Third-party / vendor extensions diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index d70d8e48b..b6a1c51f3 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -107,7 +107,8 @@ guidance for good recommendations when implementing. | description | string | **REQUIRED.** Detailed multi-line description to fully explain the catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | -**stac_extensions**: A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file. +**stac_extensions**: A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. This does *not* apply for API extensions. If the versions of the extension and the catalog diverge, you can specify the URL of the JSON schema file. +This list must only contain extensions that extend the Catalog itself, see the the 'Scope' column in the list of extensions. ### Link Object diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 3bbfae397..dda883d44 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -37,7 +37,8 @@ Implementations are encouraged, however, as good effort will be made to not chan | summaries | Map | A map of property summaries, either a set of values or statistics such as a range. | | links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | -**stac_extensions**: A list of extensions the Collection implements. This does NOT declare the extensions of child Catalogs or Items. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. If the versions of the extension and the collection diverge, you can specify the URL of the JSON schema file. +**stac_extensions**: A list of extensions the Collection implements. This does NOT declare the extensions of child Catalogs or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `version` for the Versioning Indicators extension. This does *not* apply for API extensions. If the versions of the extension and the collection diverge, you can specify the URL of the JSON schema file. +This list must only contain extensions that extend the Collection itself, see the the 'Scope' column in the list of extensions. If an extension such as the Commons extension has influence on multiple parts of the whole catalog structure, it must be listed in all affected parts (e.g. Collection and Item for the Commons extension). If a structure such as the summaries or the Commons extension provide fields in their JSON structure, these extensions must not be listed here as they don't extend the Collection itself. For example, if a Collection includes the field `sat:platform` in the summaries, the Collection still does not list the `sat` extension in the `stac_extensions` field. **license**: Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/). Alternatively, use `proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply. In all cases links to the license texts SHOULD be added, see the `license` link relation type. If no link to a license is included and the `license` field is set to `proprietary`, the collection is private, and consumers have not been granted any explicit right to use the data. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index dbf1c1b59..e31757458 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -48,7 +48,8 @@ inherited from GeoJSON. **stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. -**stac_extensions**: A list of extensions the Item implements. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. If the versions of the extension and the item diverge, you can specify the URL of the JSON schema file. +**stac_extensions**: A list of extensions the Item implements. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. This does *not* apply for API extensions. If the versions of the extension and the item diverge, you can specify the URL of the JSON schema file. +This list must only contain extensions that extend the Item itself, see the the 'Scope' column in the list of extensions. If an extension such as the Commons extension has influence on multiple parts of the whole catalog structure, it must be listed in all affected parts (e.g. Collection and Item for the Commons extension). **assets** should include the main asset, as well as any 'sidecar' files that are related and help a client make sense of the data. Examples of this include extended metadata (in XML, JSON, etc.), diff --git a/item-spec/itemcollection-spec.md b/item-spec/itemcollection-spec.md index 17dddbb96..cdc4b0f73 100644 --- a/item-spec/itemcollection-spec.md +++ b/item-spec/itemcollection-spec.md @@ -4,7 +4,7 @@ This document explains the structure and content of a SpatioTemporal Asset Catal An **ItemCollection** is a [GeoJSON](http://geojson.org/) [FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that is augmented with [foreign members](https://tools.ietf.org/html/rfc7946#section-6) relevant to a STAC entity. -Similary to the relationship between a GeoJSON Feature and a STAC Item, a STAC ItemCollection should be a valid GeoJSON FeatureCollection to allow interoperability with existing tools that support GeoJSON. +Similarly to the relationship between a GeoJSON Feature and a STAC Item, a STAC ItemCollection should be a valid GeoJSON FeatureCollection to allow interoperability with existing tools that support GeoJSON. The same ItemCollection definition is currently only used by the [`/search`](../api-spec/README.md) endpoint. The search endpoint enables dynamic @@ -29,18 +29,20 @@ Implementations are encouraged, however, as good effort will be made to not chan This object describes a STAC ItemCollection. The fields `type` and `features` are inherited from GeoJSON FeatureCollection. -| Field Name | Type | Description | -| ---------- | -------------------------------------------------------------------------- | ----------- | -| stac_version | string | **REQUIRED.** The STAC version the ItemCollection implements. | -| stac_extensions | [string] | A list of extensions the ItemCollection implements. | -| type | string | **REQUIRED.** always "FeatureCollection" to provide compatibility with GeoJSON | -| features | [Item] | **REQUIRED** a possibly-empty array of Items | -| links | [Link] | an array of Links related to this ItemCollection | +| Field Name | Type | Description | +| --------------- | --------------------------------------- | ----------- | +| stac_version | string | **REQUIRED.** The STAC version the ItemCollection implements. | +| stac_extensions | [string] | A list of extensions the ItemCollection implements. | +| type | string | **REQUIRED.** Always "FeatureCollection" to provide compatibility with GeoJSON. | +| features | [STAC Item](item-spec.md) | **REQUIRED** A possibly-empty array of Items. | +| links | [Link Object](item-spec.md#link-object) | An array of Links related to this ItemCollection. | **stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. -**stac_extensions**: A list of extensions the ItemCollection implements. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example `single-file-stac` for the Single File STAC extension. If the versions of the extension and the item diverge, you can specify the URL of the JSON schema file. +**stac_extensions**: A list of extensions the ItemCollection implements. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `single-file-stac` for the Single File STAC extension. This does *not* apply for API extensions. If the versions of the extension and the item diverge, you can specify the URL of the JSON schema file. +This list must only contain extensions that extend the ItemCollection itself, see the the 'Scope' column in the list of extensions. It must not contain extensions that extend the Items, these must be specified in the Items directly. ## Extensions -The [Search Extension](../api-spec/extensions/search/README.md) adds additional fields to STAC ItemCollection relevant to their use as search results. +* The [Context Extension](../api-spec/extensions/search/README.md) adds additional fields to STAC ItemCollection relevant to their use as search results. +* The [Single File STAC Extension](../extensions/single-file-stac/README.md) provides a set of Collections and Items as a single file catalog. \ No newline at end of file From 6c0878fe79b136972cd589a628442807de1af47f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 13:57:33 +0100 Subject: [PATCH 67/87] Updated CHANGELOG --- CHANGELOG.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ad118dd70..a8bdd063f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Added - ItemCollection requires `stac_version` field, `stac_extensions` has also been added -- A `description` field has been added to Item Assets +- A `description` field has been added to Item assets (also Asset definitions extension). - Extensions: - [Version Indicators extension](extensions/version/README.md), adds `version` and `deprecated` fields to STAC Items and Collections. - Instrument extension, adds fields: `platform`, `instruments`, `constellation` (all moved from EO and SAR extensions), and `mission`. @@ -20,7 +20,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Changed - Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html). - Collection field `property` and the merge ability moved to a new extension 'Commons' -- Added attribute `role` to Item assets, to be used similarly to Link `rel`. +- Added attribute `role` to Item assets (also Asset definitions extension), to be used similarly to Link `rel`. - Extensions: - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema. - Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / WKT2) for reference systems. @@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Removed - Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead. - Removed `summaries` field from Catalogs. Use Collections instead. +- `license` field doesn't allow SPDX expressions any longer. Use `various` and links instead. - Extensions: - Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension. - Dropped `sar:absolute_orbit` field from `sar` extension due to no known use case @@ -45,7 +46,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Fixed -- The `license` field in Item and Collection spec explicitly mentions that the value `proprietary` without a link means that the data is private. +- The `license` field in Item and Collection spec explicitly mentions that the value `proprietary` without a link means that the data is private. +- Clarified how to fill `stac_extensions`. - Clarifications; typos fixed ## [v0.8.1] - 2019-11-01 From 9366a882a9333a9e886680817966eb631ef1a7c3 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 14:09:16 +0100 Subject: [PATCH 68/87] Removed asset types (replaced by role) and explained what the asset keys are. --- CHANGELOG.md | 1 + item-spec/item-spec.md | 16 ++++++---------- 2 files changed, 7 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ad118dd70..c7de85308 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Removed - Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead. - Removed `summaries` field from Catalogs. Use Collections instead. +- Asset Types in Items. Use the asset's `role` instead. - Extensions: - Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension. - Dropped `sar:absolute_orbit` field from `sar` extension due to no known use case diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 29b91dc22..6302fc23e 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -43,14 +43,18 @@ inherited from GeoJSON. | bbox | [number] | **REQUIRED.** Bounding Box of the asset represented by this item using either 2D or 3D geometries. The length of the array must be 2*n where n is the number of dimensions. The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters and the elevation of the northeasterly most extent is the maximum. This field enables more naive clients to easily index and search geospatially. STAC compliant APIs are required to compute intersection operations with the item's geometry field, not its bbox. | | properties | [Properties Object](#properties-object) | **REQUIRED.** A dictionary of additional metadata for the item. | | links | [[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. A link with the `rel` set to `self` is strongly recommended. | -| assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. Some pre-defined keys are listed in the chapter '[Asset types](#asset-types)'. | +| assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. | | collection | string | The `id` of the STAC Collection this Item references to (see [`collection` relation type](#relation-types)). This field is *required* if such a relation type is present. This field provides an easy way for a user to search for any Items that belong in a specified Collection. | **stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. **stac_extensions**: A list of extensions the Item implements. The list contains URLs to the JSON Schema files it can be validated against. For official extensions, a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. If the versions of the extension and the item diverge, you can specify the URL of the JSON schema file. -**assets** should include the main asset, as well as any 'sidecar' files that are related and help a +**assets**: Dictionary of asset objects that can be downloaded, each with a unique key. +In general, the keys don't have any meaning and are considered to be non-descriptive unique identifiers. +Providers may assign any meaning to the keys for their respective use cases, but must not expect that clients understand them. +To communicate the purpose of an asset better use the `role` field in the [Asset Object](#asset-object). +Assets should include the main asset, as well as any 'sidecar' files that are related and help a client make sense of the data. Examples of this include extended metadata (in XML, JSON, etc.), unusable data masks, satellite ephemeris data, etc. Some assets (like Landsat data) are represented by multiple files - all should be linked to. It is generally recommended that different processing @@ -183,14 +187,6 @@ Like the Link `rel` field, the `role` field can be given any value, however here | overview | An asset that represents a possibly larger view than the thumbnail of the Item , for example, a true color composite of multi-band data. | | metadata | A metadata sidecar file describing the data in this item, for example the Landsat-8 MTL file. | -#### Asset types - -The following types are common for assets and are used as the key for the Asset Object: - -| Type | Description | -| --------- | ----------- | -| thumbnail | STRONGLY RECOMMENDED. A downsampled image of the core asset, for direct display online in a web page or interactive search application. Even assets that are less easily translated in to a visual image should provide some visual representation, that users can browse. For example a SAR asset can render an elevation mask or hillshade for display. If at all possible it should be included for a better user experience in searching data. | - #### Media Types The media type of an Asset can be used by STAC browsers to better determine what to render and display From 42512605785d4ba619271f3c540737fbd3759e47 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 14:50:56 +0100 Subject: [PATCH 69/87] Added extension best practice for arrays and objects and specified that summarized arrays are merged (#660). --- collection-spec/collection-spec.md | 9 +- .../examples/landsat-collection.json | 2 +- collection-spec/examples/sentinel2.json | 152 +++++++++--------- extensions/README.md | 12 ++ 4 files changed, 94 insertions(+), 81 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 74edf11d5..3b200ee8b 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -43,9 +43,12 @@ Implementations are encouraged, however, as good effort will be made to not chan **summaries**: You can optionally summarize the potential values that are available as part of the `properties` in STAC Items. Summaries are used to inform users about values they can expect from items without having to crawl through them. It also helps do fully define collections, especially if they don't link to any Items. -Summaries are either a unique set of all values or statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. -The range can specify the potential range of values, but it is recommended to be as precise as possible. The set of values must contain at least one element and it is strongly recommended to list all values. -It is recommended to list as many properties as reasonable so that consumers get a full overview about the properties included in the Items. Nevertheless, it is not very useful to list all potential `title` values of the Items. Also, a range for the `datetime` property may be better suited to be included in the STAC Collection. In general, properties that are covered by the Collection specification (e.g. `providers` and `license`) may not be repeated in the summaries. +A summary for a field can be specified in two ways: + +1. A set of all distinct values in an array: The set of values must contain at least one element and it is strongly recommended to list all values. If the field summarizes an array (e.g. `instruments`), the field's array elements of each Item must be merged to a single array with unique elements. +2. Statistics in a [Stats Object](#stats-object): Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. The range specified by the minimum and maximum can specify the potential range of values, but it is recommended to be as precise as possible. + +It is recommended to list as many properties as reasonable so that consumers get a full overview about the properties included in the Items. Nevertheless, it is not very useful to list all potential `title` values of the Items. Also, a range for the `datetime` property may be better suited to be included in the STAC Collection's `extent` field. In general, properties that are covered by the Collection specification should not be repeated in the summaries. ### Extent Object diff --git a/collection-spec/examples/landsat-collection.json b/collection-spec/examples/landsat-collection.json index ca47fea4e..9f77fe4dd 100644 --- a/collection-spec/examples/landsat-collection.json +++ b/collection-spec/examples/landsat-collection.json @@ -60,10 +60,10 @@ ], "license": "PDDL-1.0", "properties": { - "eo:gsd": 30, "platform": "landsat-8", "instruments": ["oli", "tirs"], "sat:off_nadir_angle": 0, + "eo:gsd": 30, "eo:bands": [ { "name": "B1", diff --git a/collection-spec/examples/sentinel2.json b/collection-spec/examples/sentinel2.json index e594d93f7..1e825c531 100644 --- a/collection-spec/examples/sentinel2.json +++ b/collection-spec/examples/sentinel2.json @@ -49,11 +49,9 @@ "min": "2015-06-23T00:00:00Z", "max": "2019-07-10T13:44:56Z" }, - "sci:citation": ["Copernicus Sentinel data [Year]"], - "eo:gsd": [10,30,60], "platform": ["sentinel-2a","sentinel-2b"], "constellation": ["sentinel-2"], - "instruments": [["msi"]], + "instruments": ["msi"], "sat:off_nadir_angle": { "min": 0.0, "max": 100 @@ -62,82 +60,82 @@ "min": 6.78, "max": 89.9 }, + "sci:citation": ["Copernicus Sentinel data [Year]"], + "eo:gsd": [10,30,60], "eo:epsg": [32601,32602,32603,32604,32605,32606,32607,32608,32609,32610,32611,32612,32613,32614,32615,32616,32617,32618,32619,32620,32621,32622,32623,32624,32625,32626,32627,32628,32629,32630,32631,32632,32633,32634,32635,32636,32637,32638,32639,32640,32641,32642,32643,32644,32645,32646,32647,32648,32649,32650,32651,32652,32653,32654,32655,32656,32657,32658,32659,32660], "eo:bands": [ - [ - { - "name": "B1", - "common_name": "coastal", - "center_wavelength": 4.439, - "gsd": 60 - }, - { - "name": "B2", - "common_name": "blue", - "center_wavelength": 4.966, - "gsd": 10 - }, - { - "name": "B3", - "common_name": "green", - "center_wavelength": 5.6, - "gsd": 10 - }, - { - "name": "B4", - "common_name": "red", - "center_wavelength": 6.645, - "gsd": 10 - }, - { - "name": "B5", - "center_wavelength": 7.039, - "gsd": 20 - }, - { - "name": "B6", - "center_wavelength": 7.402, - "gsd": 20 - }, - { - "name": "B7", - "center_wavelength": 7.825, - "gsd": 20 - }, - { - "name": "B8", - "common_name": "nir", - "center_wavelength": 8.351, - "gsd": 10 - }, - { - "name": "B8A", - "center_wavelength": 8.648, - "gsd": 20 - }, - { - "name": "B9", - "center_wavelength": 9.45, - "gsd": 60 - }, - { - "name": "B10", - "center_wavelength": 1.3735, - "gsd": 60 - }, - { - "name": "B11", - "common_name": "swir16", - "center_wavelength": 1.6137, - "gsd": 20 - }, - { - "name": "B12", - "common_name": "swir22", - "center_wavelength": 2.2024, - "gsd": 20 - } - ] + { + "name": "B1", + "common_name": "coastal", + "center_wavelength": 4.439, + "gsd": 60 + }, + { + "name": "B2", + "common_name": "blue", + "center_wavelength": 4.966, + "gsd": 10 + }, + { + "name": "B3", + "common_name": "green", + "center_wavelength": 5.6, + "gsd": 10 + }, + { + "name": "B4", + "common_name": "red", + "center_wavelength": 6.645, + "gsd": 10 + }, + { + "name": "B5", + "center_wavelength": 7.039, + "gsd": 20 + }, + { + "name": "B6", + "center_wavelength": 7.402, + "gsd": 20 + }, + { + "name": "B7", + "center_wavelength": 7.825, + "gsd": 20 + }, + { + "name": "B8", + "common_name": "nir", + "center_wavelength": 8.351, + "gsd": 10 + }, + { + "name": "B8A", + "center_wavelength": 8.648, + "gsd": 20 + }, + { + "name": "B9", + "center_wavelength": 9.45, + "gsd": 60 + }, + { + "name": "B10", + "center_wavelength": 1.3735, + "gsd": 60 + }, + { + "name": "B11", + "common_name": "swir16", + "center_wavelength": 1.6137, + "gsd": 20 + }, + { + "name": "B12", + "common_name": "swir22", + "center_wavelength": 2.2024, + "gsd": 20 + } ] }, "links": [ diff --git a/extensions/README.md b/extensions/README.md index 8ad419bcf..d6ecc2d9e 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -134,6 +134,18 @@ An example of this can be seen in a Landsat example: } ``` +### Use of arrays and objects + +For content extensions, it is recommended to use use arrays only as true (potentially sorted) enumerations/lists without having additional meaning and to avoid objects whenever possible. + +For example, if one would like to define an extension to contain a start and a end date, there are multiple options (tl;dr: option **3** is recommended): + +1. Define an object, for example: `"date_range": {"start": "2018-01-01", "end": "2018-01-31"}`. This is **discouraged** as it is more complex to search in objects. +2. Define an two-element array where the first element is the start date and the second element is the end date, for example `"date_range": ["2018-01-01", "2018-01-31"]`. This is **discouraged** as it would conflict with Collection `summaries`, which always considers arrays as true (potentially sorted) enumeration without any additional meaning. +3. Define two separate fields, e.g. `"date_range_start": "2018-01-01", "date_range_end": "2018-01-31"`. This is **recommended** as it avoids the conflicts above and is usually better displayed in software that only understands GeoJSON but has no clue about STAC. This is due to the fact that most legacy software can not display arrays or objects GeoJSON `properties` properly. + +This rules only applies to the fields defined directly for the Item's `properties`. For fields and structures defined on other levels (e.g. in the root of an Item or in an array), extension authors can freely define the structure. So an array of objects such as the `eo:bands` are fine to use, but keep in mind that the drawbacks mentioned above usually still apply. + ### Directory Structure A STAC extension can have references to additional schemas within the extension schema. From 09bebbc3f8d53bb66f66e026c132ea22535e7c2e Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 14:54:44 +0100 Subject: [PATCH 70/87] Updated CHANGELOG --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ad118dd70..80ac856bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html). - Collection field `property` and the merge ability moved to a new extension 'Commons' - Added attribute `role` to Item assets, to be used similarly to Link `rel`. +- Collection `summaries` now merge array fields. - Extensions: - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema. - Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / WKT2) for reference systems. @@ -45,7 +46,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Fixed -- The `license` field in Item and Collection spec explicitly mentions that the value `proprietary` without a link means that the data is private. +- The `license` field in Item and Collection spec explicitly mentions that the value `proprietary` without a link means that the data is private. - Clarifications; typos fixed ## [v0.8.1] - 2019-11-01 From dd223a5ecbfdab51f06b09fbf512e581e34da5c5 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 25 Nov 2019 14:55:50 +0100 Subject: [PATCH 71/87] Fixed typo --- extensions/commons/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/commons/README.md b/extensions/commons/README.md index 8303691c5..916beab0f 100644 --- a/extensions/commons/README.md +++ b/extensions/commons/README.md @@ -4,7 +4,7 @@ A group of STAC Item objects from a single source can share a lot of common metadata. This is especially true with satellite imagery that uses the STAC EO Extension. Rather than including these common metadata fields on every Item, they can be provided into the [STAC Collection](../../collection-spec/README.md) that the STAC Items belong to. -This extensions makes most sense in **static catalogs** to move common information to a central place. This reduces duplication of metadata and makes updates to static catalogs easier. It also makes navigating a static catalog easier as user know in advance which common fields to expect although Items can better be summarized with the `summaries` field in Collections. Therefore it is recommended to use the summaries for this use case and only use the Commons extension to avoid data duplication. +This extension makes most sense in **static catalogs** to move common information to a central place. This reduces duplication of metadata and makes updates to static catalogs easier. It also makes navigating a static catalog easier as user know in advance which common fields to expect although Items can better be summarized with the `summaries` field in Collections. Therefore it is recommended to use the summaries for this use case and only use the Commons extension to avoid data duplication. In **API implementations** the Commons extension should not be used as it leads to less intuitive search results. For example, a search result for Items may not include the fields a user has searched for as it has been moved to the Collection, which may lead to confusion. Also, data duplication in dynamically created responses is usually not an issue and APIs derived from static catalogs can simply merge the common fields back into the Items for the response. In this case the `stac_extensions` field should not contain the `commons` extension any longer. From fda946fd61652771cac8445d136301978e7e9829 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Mon, 25 Nov 2019 12:04:41 -0500 Subject: [PATCH 72/87] sar wording change --- extensions/sar/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index f69424de0..516cdd783 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -57,7 +57,7 @@ In SAR, you usually have frame start and end time. To describe this information ### Item [`Asset Object`](../../item-spec/item-spec.md#asset-object) fields | Field Name | Type | Description | | ---------- | -------- | -------------------------------------------- | -| sar:polarizations | [string] | Lists the polarizations available in the asset, in order. One of `HH`, `VV`, `HV`, `VH` | +| sar:polarizations | [string] | Lists the polarizations available in the asset, in order. Any of `HH`, `VV`, `HV`, `VH` | ## Extensions From c96af8dd4990debb844d72650339eeb7dddab785 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 26 Nov 2019 00:02:18 +0100 Subject: [PATCH 73/87] Strongly recommend thumbnail --- item-spec/item-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 6302fc23e..d08ffd7bc 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -183,7 +183,7 @@ Like the Link `rel` field, the `role` field can be given any value, however here | Role Name | Description | | --------- | ------------------------------------------------------------------------------------- | -| thumbnail | An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `role` be unique tuple. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | +| thumbnail | STRONGLY RECOMMENDED. An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `role` be unique tuple. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | | overview | An asset that represents a possibly larger view than the thumbnail of the Item , for example, a true color composite of multi-band data. | | metadata | A metadata sidecar file describing the data in this item, for example the Landsat-8 MTL file. | From 82b10d8d47527e76ca084ded65847035035e9131 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 26 Nov 2019 14:55:37 +0100 Subject: [PATCH 74/87] Mention Fields API extension in Commons Extension. --- extensions/commons/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/commons/README.md b/extensions/commons/README.md index 916beab0f..2e12bd2d0 100644 --- a/extensions/commons/README.md +++ b/extensions/commons/README.md @@ -6,7 +6,7 @@ A group of STAC Item objects from a single source can share a lot of common meta This extension makes most sense in **static catalogs** to move common information to a central place. This reduces duplication of metadata and makes updates to static catalogs easier. It also makes navigating a static catalog easier as user know in advance which common fields to expect although Items can better be summarized with the `summaries` field in Collections. Therefore it is recommended to use the summaries for this use case and only use the Commons extension to avoid data duplication. -In **API implementations** the Commons extension should not be used as it leads to less intuitive search results. For example, a search result for Items may not include the fields a user has searched for as it has been moved to the Collection, which may lead to confusion. Also, data duplication in dynamically created responses is usually not an issue and APIs derived from static catalogs can simply merge the common fields back into the Items for the response. In this case the `stac_extensions` field should not contain the `commons` extension any longer. +In **API implementations** the Commons extension should not be used as it leads to less intuitive search results. For example, a search result for Items may not include the fields a user has searched for as it has been moved to the Collection, which may lead to confusion. Also, data duplication in dynamically created responses is usually not an issue and APIs derived from static catalogs can simply merge the common fields back into the Items for the response. In this case the `stac_extensions` field should not contain the `commons` extension any longer. To reduce the size of the response body, the [Fields API Extension](../../api-spec/extensions/fields/README.md) can be used. - [Examples](examples/): - Landsat 8: An [Item](examples/landsat-item.json) that uses the Commons extension to place shared data in a [Collection](examples/landsat-collection.json). From 5e6cfc3475789f46f6926e51be57c105d150fe48 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 26 Nov 2019 15:16:21 +0100 Subject: [PATCH 75/87] Clarified asset types in CHANGELOG --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b101d57aa..522948a02 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,7 +37,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Removed - Removed `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead. - Removed `summaries` field from Catalogs. Use Collections instead. -- Asset Types in Items. Use the asset's `role` instead. +- Asset Types (pre-defined values for the keys of individual assets, *not* media types) in Items. Use the asset's `role` instead. - Extensions: - Removed `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from SAR extension. - Dropped `sar:absolute_orbit` field from `sar` extension due to no known use case From 5a1169ed93ac3f4c2741cebbdd3c95f1b4b36170 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 26 Nov 2019 11:28:29 -0500 Subject: [PATCH 76/87] add product table suggestions --- extensions/sar/README.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 516cdd783..4785bc6f9 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -22,7 +22,7 @@ If the data has been collected by a satellite, it is strongly recommended to use | 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. | | sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | | sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. | -| sar:product_type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | +| sar:product_type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | | sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | | sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | | sar:pixel_spacing_range | number | The range azimuth, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | @@ -34,6 +34,20 @@ If the data has been collected by a satellite, it is strongly recommended to use **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:product_type**: The product type defines the type of procesed data contained in the assets. A generalized list of suggestions include: + +| sar:product_type | Data Type | Description | +|-------------------|----------------|----------------| +| SSC | complex | Single-look Slant-range Complex image (standard SLC) | +| MGD | amplitude | Multilooked Ground-range Detected Image (GRD for Sentinel-1) | +| GEC | amplitude | Geocoded Ellipsoid Corrected Image | +| GTC | amplitude | Geocoded Terrain Corrected Image | +| RTC | amplitude | Geocoded Radiometrically Terrain Corrected Image | +| SGC | complex | Single-look Ground projected Complex image (SLC in Sentinel-1) | + +This can vary by data provider, who all may use slightly different names. Sentinel-1 for instance uses `GRD` and `SLC`, which correspond to the more general names `MGD` and `SGC` in the table above. + + ### Common Frequency Band Names The `sar:frequency_band` is the name that is commonly used to refer to that band's spectral @@ -63,7 +77,6 @@ In SAR, you usually have frame start and end time. To describe this information The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to SAR data: - * the [Datetime Range Extension Specification](../datetime-range/README.md) to describe frame start and end time. * the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. * the [Instrument Extension Specification](../instrument/README.md) which contains fields about the sensor and platform used to collect the data. The Instrument extension is required when using the Sat extension. From 8eda2df830b155d43269793429e16b2f9f54f50d Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 26 Nov 2019 11:30:09 -0500 Subject: [PATCH 77/87] update sar product type examples --- extensions/sar/README.md | 2 +- extensions/sar/json-schema/schema.json | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index 4785bc6f9..e1cc0c4cf 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -22,7 +22,7 @@ If the data has been collected by a satellite, it is strongly recommended to use | 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. | | sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | | sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. | -| sar:product_type | string | **REQUIRED.** The product type, for example `RAW`, `GRD`, `OCN` or `SLC` for Sentinel-1. | +| sar:product_type | string | **REQUIRED.** The product type, for example `SSC`, `MGD`, or `SGC` | | sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | | sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | | sar:pixel_spacing_range | number | The range azimuth, which is the distance between adjacent pixels perpendicular to the flight path, in meters (m). Strongly RECOMMENDED to be specified for products of type `GRD`. | diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index 2b213cf6b..39ac233c8 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -69,10 +69,9 @@ "title": "Product type", "type": "string", "examples": [ - "RAW", - "GRD", - "OCN", - "SLC" + "SSC", + "MGD", + "SGC" ] }, "sar:resolution_range": { From 1ee08d69b3725801fd3c24a0ea6e0472ebebac38 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 26 Nov 2019 17:55:18 +0100 Subject: [PATCH 78/87] Clean-up catalog relations and links --- catalog-spec/catalog-spec.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index b6a1c51f3..ff75e7901 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -10,8 +10,8 @@ Catalogs are not intended to be queried. Their purpose is discovery: to be brows by machines to build a search index. A Catalog can be represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Catalog. -- [Examples](examples/) and [Implementations](../implementations.md) -- [JSON Schema](json-schema/catalog.json) - please see the [validation instructions](../validation/README.md) +- [Examples](examples/) +- [JSON Schema](json-schema/catalog.json) This Catalog specification primarily defines a structure for information to be discoverable. Any use that is publishing a set of related spatiotemporal assets is strongly recommended to also use the @@ -65,11 +65,6 @@ catalogs and items: - `Catalog` -> `Item` (this is a common structure for a catalog to list links to items) - `Catalog` -> `Catalog` (this is a common tree structure to group sets of items. Each catalog in this relationship may also include item links as well as catalog links) -- `Item` -> `Catalog` (example: an item may point to a catalog to describe a set of derived assets, - where it may be desirable to have the origin asset as a "parent", such as NDVI generated from - RGB/IR) -- `Item` -> `Item` (example: this relationship may be used to describe a 1-1 parent-child - relationship, such as a single derived item from one parent item) As all STAC Collections are also valid STAC Catalogs, all Catalogs described here could also be Collections. @@ -185,7 +180,4 @@ The `root` catalog in this example could hold a set of sub-catalogs with differe ## Extensions -There are emerging best practices, which in time will evolve in to specification extensions for -particular domains or uses. - The [extensions page](../extensions/) gives an overview about relevant extensions for STAC Catalogs. From b443651c5012ee7c639de5be597156bf65498057 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 26 Nov 2019 12:11:17 -0500 Subject: [PATCH 79/87] fix leftover merge conflict issue --- CHANGELOG.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8974e7033..114c9cbb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,12 +20,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Changed - Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html) - Collection field `property` and the merge ability moved to a new extension 'Commons' -<<<<<<< HEAD -- Added attribute `role` to Item assets, to be used similarly to Link `rel` -======= - Added attribute `role` to Item assets (also Asset definitions extension), to be used similarly to Link `rel`. - Collection `summaries` merge array fields now. ->>>>>>> dev - Extensions: - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema - Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / WKT2) for reference systems From 306c78c75e634a3db14ca19bdf252a81f21d395c Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 26 Nov 2019 18:21:17 +0100 Subject: [PATCH 80/87] Added JSON Schema for polarization in assets + made polarization plural --- extensions/sar/README.md | 10 ++++----- extensions/sar/examples/envisat.json | 2 +- extensions/sar/examples/sentinel1.json | 2 +- extensions/sar/json-schema/schema.json | 29 ++++++++++++++++++++++---- 4 files changed, 32 insertions(+), 11 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index e1cc0c4cf..550fcefce 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -21,7 +21,7 @@ If the data has been collected by a satellite, it is strongly recommended to use | 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. | | sar:center_frequency | number | The center frequency of the instrument, in gigahertz (GHz). | -| sar:polarization | [string] | **REQUIRED.** A single polarization or a polarization combination specified as array. | +| sar:polarizations | [string] | **REQUIRED.** Any combination of polarizations. | | sar:product_type | string | **REQUIRED.** The product type, for example `SSC`, `MGD`, or `SGC` | | sar:resolution_range | number | The range resolution, which is the maximum ability to distinguish two adjacent targets perpendicular to the flight path, in meters (m). | | sar:resolution_azimuth | number | The azimuth resolution, which is the maximum ability to distinguish two adjacent targets parallel to the flight path, in meters (m). | @@ -32,7 +32,7 @@ If the data has been collected by a satellite, it is strongly recommended to use | sar:looks_equivalent_number | number | The equivalent number of looks (ENL). | | sar:observation_direction | string | Antenna pointing direction relative to the flight trajectory of the satellite, either `left` or `right`. -**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:polarizations** 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:product_type**: The product type defines the type of procesed data contained in the assets. A generalized list of suggestions include: @@ -69,9 +69,9 @@ properties. The table below shows the common name based on the wavelength and fr In SAR, you usually have frame start and end time. To describe this information it is recommended to use the [Datetime Range Extension Specification](../datetime-range/README.md). The center time of the frame should be specified with the `datetime` property for [STAC Items](../../item-spec/item-spec.md). ### Item [`Asset Object`](../../item-spec/item-spec.md#asset-object) fields -| Field Name | Type | Description | -| ---------- | -------- | -------------------------------------------- | -| sar:polarizations | [string] | Lists the polarizations available in the asset, in order. Any of `HH`, `VV`, `HV`, `VH` | +| Field Name | Type | Description | +| ----------------- | -------- | -------------------------------------------- | +| sar:polarizations | [string] | Lists the polarizations available in the asset, in order. Any of `HH`, `VV`, `HV`, `VH`. | ## Extensions diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index 45f0807e1..12dd6697b 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -30,7 +30,7 @@ "instruments": ["asar"], "sat_orbit_state": "descending", "sar:instrument_mode": "GM", - "sar:polarization": ["HH"], + "sar:polarizations": ["HH"], "sar:resolution_range": 1000, "sar:resolution_azimuth": 1000, "sar:pixel_spacing_range": 500, diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json index 17cc87231..7e83c5dcf 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -32,7 +32,7 @@ "sat:orbit_state": "ascending", "relative_orbit": 33, "sar:instrument_mode": "EW", - "sar:polarization": ["HH"], + "sar:polarizations": ["HH"], "sar:resolution_range": 50, "sar:resolution_azimuth": 50, "sar:pixel_spacing_range": 25, diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index 39ac233c8..57e15e6a4 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -15,7 +15,8 @@ "sar": { "type": "object", "required": [ - "properties" + "properties", + "assets" ], "properties": { "properties": { @@ -23,7 +24,7 @@ "required": [ "sar:instrument_mode", "sar:frequency_band", - "sar:polarization", + "sar:polarizations", "sar:product_type" ], "properties": { @@ -50,11 +51,12 @@ "title": "Center Frequency (GHz)", "type": "number" }, - "sar:polarization": { - "title": "Polarization", + "sar:polarizations": { + "title": "Polarizations", "type": "array", "minItems": 1, "maxItems": 4, + "uniqueItems": true, "items": { "type": "string", "enum": [ @@ -119,6 +121,25 @@ } } } + }, + "asset": { + "type": "object", + "properties": { + "sar:polarizations": { + "title": "Polarizations", + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "HH", + "VV", + "HV", + "VH" + ] + } + } + } } } } From bd0f3937ed2f8f19d275d30c5abc8009d5a40e65 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 26 Nov 2019 12:23:08 -0500 Subject: [PATCH 81/87] update sar product table --- extensions/sar/README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/extensions/sar/README.md b/extensions/sar/README.md index e1cc0c4cf..70797ff13 100644 --- a/extensions/sar/README.md +++ b/extensions/sar/README.md @@ -34,18 +34,20 @@ If the data has been collected by a satellite, it is strongly recommended to use **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:product_type**: The product type defines the type of procesed data contained in the assets. A generalized list of suggestions include: +**sar:product_type**: The product type defines the type of procesed data contained in the assets. A list of suggestions include: | sar:product_type | Data Type | Description | |-------------------|----------------|----------------| | SSC | complex | Single-look Slant-range Complex image (standard SLC) | -| MGD | amplitude | Multilooked Ground-range Detected Image (GRD for Sentinel-1) | -| GEC | amplitude | Geocoded Ellipsoid Corrected Image | -| GTC | amplitude | Geocoded Terrain Corrected Image | -| RTC | amplitude | Geocoded Radiometrically Terrain Corrected Image | -| SGC | complex | Single-look Ground projected Complex image (SLC in Sentinel-1) | - -This can vary by data provider, who all may use slightly different names. Sentinel-1 for instance uses `GRD` and `SLC`, which correspond to the more general names `MGD` and `SGC` in the table above. +| MGD | amplitude | Multilooked Ground-range Detected image | +| GRD | amplitude | Multilooked Ground-range Detected image (used by Sentinel-1) +| GEC | amplitude | Geocoded Ellipsoid Corrected image | +| GTC | amplitude | Geocoded Terrain Corrected image | +| RTC | amplitude | Geocoded Radiometrically Terrain Corrected image | +| SGC | complex | Single-look Ground projected Complex image | +| SLC | complex | Single-look Ground projected Complex image (used by Sentinel-1) | + +This can vary by data provider, who all may use slightly different names. Sentinel-1 for instance uses `GRD`, wihch is the same as the more general `MGD` and `SLC` instead of `SGC`. ### Common Frequency Band Names From 64c3d828775aa393894a8cca68e3ccde153abb5f Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Tue, 26 Nov 2019 12:30:19 -0500 Subject: [PATCH 82/87] update changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 114c9cbb8..4c5b238e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,7 +26,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema - Data Cube extension: Changed allowed formats (removed PROJ string, addedPROJJSON / WKT2) for reference systems - [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)) - - Changed `sar:type` to `sar:product_type` in the [SAR extension](extensions/sar/README.md) + - Changed `sar:type` to `sar:product_type` and `sar:polarization` to `sar:polarizations` in the [SAR extension](extensions/sar/README.md) - STAC API: - The endpoint `/stac` has been merged with `/` - The endpoint `/stac/search` is now called `/search` From 7ba4c9fa479fd45feee447608550632507bee918 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 26 Nov 2019 18:53:37 +0100 Subject: [PATCH 83/87] Validate SAR and EO asset extensions correctly. --- extensions/eo/json-schema/schema.json | 22 +++++++++++++-- extensions/sar/json-schema/schema.json | 39 ++++++++++++++------------ item-spec/json-schema/item.json | 9 ++---- 3 files changed, 44 insertions(+), 26 deletions(-) diff --git a/extensions/eo/json-schema/schema.json b/extensions/eo/json-schema/schema.json index 06aa165db..b6b936b0e 100644 --- a/extensions/eo/json-schema/schema.json +++ b/extensions/eo/json-schema/schema.json @@ -5,7 +5,7 @@ "description": "STAC EO Extension to a STAC Item.", "allOf": [ { - "$ref": "../../../item-spec/json-schema/item.json#/definitions/core" + "$ref": "../../../item-spec/json-schema/item.json" }, { "$ref": "#/definitions/eo" @@ -15,7 +15,8 @@ "eo": { "type": "object", "required": [ - "properties" + "properties", + "assets" ], "properties": { "properties": { @@ -75,6 +76,23 @@ "maximum": 100 } } + }, + "assets": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "eo:bands": { + "title": "Band References", + "type": "array", + "minItems": 1, + "items": { + "type": "integer", + "minimum": 0 + } + } + } + } } } } diff --git a/extensions/sar/json-schema/schema.json b/extensions/sar/json-schema/schema.json index 57e15e6a4..bd8fcf5fa 100644 --- a/extensions/sar/json-schema/schema.json +++ b/extensions/sar/json-schema/schema.json @@ -5,7 +5,7 @@ "description": "STAC SAR Extension to a STAC Item", "allOf": [ { - "$ref": "../../../item-spec/json-schema/item.json#/definitions/core" + "$ref": "../../../item-spec/json-schema/item.json" }, { "$ref": "#/definitions/sar" @@ -120,23 +120,26 @@ ] } } - } - }, - "asset": { - "type": "object", - "properties": { - "sar:polarizations": { - "title": "Polarizations", - "type": "array", - "minItems": 1, - "items": { - "type": "string", - "enum": [ - "HH", - "VV", - "HV", - "VH" - ] + }, + "assets": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "sar:polarizations": { + "title": "Polarizations", + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "enum": [ + "HH", + "VV", + "HV", + "VH" + ] + } + } } } } diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index 586f999f0..0ae9a2421 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -85,12 +85,9 @@ "title": "Asset links", "description": "Links to assets", "type": "object", - "patternProperties": { - ".+": { - "$ref": "#/definitions/asset" - } - }, - "additionalProperties": false + "additionalProperties": { + "$ref": "#/definitions/asset" + } }, "properties": { "type": "object", From 80e1306448f1531909b5329d70675612dab0f41a Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 2 Dec 2019 10:17:50 -0500 Subject: [PATCH 84/87] fix changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e91a5df90..3fe2e3195 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,8 +20,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Changed - Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html) - Collection field `property` and the merge ability moved to a new extension 'Commons' +- Added attribute `roles` to Item assets (also Asset definitions extension), to be used similarly to Link `rel`. - Collection `summaries` merge array fields now. -- Added attribute `roles` to Item assets, to be used similarly to Link `rel`. - Extensions: - [datetime-range extension](extensions/datetime-range/README.md): Removed extension prefix from example and schema From 1455eb99e225a4277d0a227627940dd686b133fc Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 2 Dec 2019 10:20:36 -0500 Subject: [PATCH 85/87] fix roles json schema --- item-spec/json-schema/item.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index ae9c9c4f8..a7d3562d4 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -216,7 +216,10 @@ }, "roles": { "title": "Asset roles", - "type": "string" + "type": "array", + "items": { + "type": "string" + } } } } From 95ca2743b1597ca6f8d18ddfc3e142279c1e362b Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 2 Dec 2019 10:55:02 -0500 Subject: [PATCH 86/87] update asset extension role to roles --- extensions/asset/README.md | 2 +- extensions/asset/examples/example-landsat8.json | 4 ++-- extensions/asset/json-schema/schema.json | 9 ++++++--- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/extensions/asset/README.md b/extensions/asset/README.md index 3a082c3ec..07161a348 100644 --- a/extensions/asset/README.md +++ b/extensions/asset/README.md @@ -32,7 +32,7 @@ An asset is an object that contains details about the datafiles that will be inc | title | string | The displayed title for clients and users. | | description | string | A description of the Asset providing additional details, such as how it was processed or created. | | type | string | [Media type](#media-types) of the asset. | -| role | string | The semantic purpose of the asset, similar to the use of `rel` in links. | +| roles | [string] | The semantic roles of the asset, similar to the use of `rel` in links. | Other custom fields, or fields from other extensions may also be included in the Asset object. diff --git a/extensions/asset/examples/example-landsat8.json b/extensions/asset/examples/example-landsat8.json index b0e4ff1b2..7d72bb94e 100644 --- a/extensions/asset/examples/example-landsat8.json +++ b/extensions/asset/examples/example-landsat8.json @@ -156,11 +156,11 @@ "type": "image/jpeg", "title": "Thumbnail", "description": "A medium sized thumbnail", - "role": "thumbnail" + "roles": [ "thumbnail" ] }, "metadata": { "type": "mtl", - "role": "metadata", + "roles": [ "metadata" ], "title": "Original Metadata", "description": "The original MTL metadata file provided for each Landsat scene" }, diff --git a/extensions/asset/json-schema/schema.json b/extensions/asset/json-schema/schema.json index da89de3be..68798ffbc 100644 --- a/extensions/asset/json-schema/schema.json +++ b/extensions/asset/json-schema/schema.json @@ -46,9 +46,12 @@ "title": "Asset type", "type": "string" }, - "role": { - "title": "Asset role", - "type": "string" + "roles": { + "title": "Asset roles", + "type": "array", + "items": { + "type": "string" + } } } } From eb27865c6741053d83c3a666d6c5519d596e4245 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 2 Dec 2019 10:57:03 -0500 Subject: [PATCH 87/87] update other uses of asset role to roles --- CHANGELOG.md | 4 ++-- item-spec/item-spec.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fe2e3195..815da83c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - [Version Indicators extension](extensions/version/README.md), adds `version` and `deprecated` fields to STAC Items and Collections - Instrument extension, adds fields: `platform`, `instruments`, `constellation` (all moved from EO and SAR extensions), and `mission` - Data Cube extension can be used in Collections, added new field `description` - - Added `description` and `role` fields to the Asset in the [Asset Extension](extensions/asset/README.md) + - Added `description` and `roles` fields to the Asset in the [Asset Extension](extensions/asset/README.md) - STAC API: - Added the [Item and Collection API Version extension](api-spec/extensions/version/README.md) to support versioning in the API specification @@ -44,7 +44,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Removed `sar:absolute_orbit` and `sar:center_wavelength` fields from the [SAR extension](extensions/sar/README.md) - Removed `data_type` and `unit` from the `sar:bands` object in the [SAR extension](extensions/sar/README.md) - Removed `dtr` extension prefix from example and schema in [datetime-range extension](extensions/datetime-range/README.md) -- Asset Types (pre-defined values for the keys of individual assets, *not* media types) in Items. Use the asset's `role` instead. +- Asset Types (pre-defined values for the keys of individual assets, *not* media types) in Items. Use the asset's `roles` instead. - `license` field doesn't allow SPDX expressions any longer. Use `various` and links instead. - STAC API: - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 0d37f896c..b018b6663 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -54,7 +54,7 @@ This list must only contain extensions that extend the Item itself, see the the **assets**: Dictionary of asset objects that can be downloaded, each with a unique key. In general, the keys don't have any meaning and are considered to be non-descriptive unique identifiers. Providers may assign any meaning to the keys for their respective use cases, but must not expect that clients understand them. -To communicate the purpose of an asset better use the `role` field in the [Asset Object](#asset-object). +To communicate the purpose of an asset better use the `roles` field in the [Asset Object](#asset-object). Assets should include the main asset, as well as any 'sidecar' files that are related and help a client make sense of the data. Examples of this include extended metadata (in XML, JSON, etc.), unusable data masks, satellite ephemeris data, etc. Some assets (like Landsat data) are represented @@ -182,11 +182,11 @@ or streamed. It is allowed to add additional fields. #### Asset Role Types -Like the Link `rel` field, the `role` field can be given any value, however here are a few standardized role names. +Like the Link `rel` field, the `roles` field can be given any value, however here are a few standardized role names. | Role Name | Description | | --------- | ------------------------------------------------------------------------------------- | -| thumbnail | STRONGLY RECOMMENDED. An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `role` be unique tuple. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | +| thumbnail | STRONGLY RECOMMENDED. An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `roles` be unique tuples. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | | overview | An asset that represents a possibly larger view than the thumbnail of the Item , for example, a true color composite of multi-band data. | | metadata | A metadata sidecar file describing the data in this item, for example the Landsat-8 MTL file. |