diff --git a/CHANGELOG.md b/CHANGELOG.md index b8979eb5..0c6d276f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,6 +38,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Several typos and minor language changes - Clarified that collection IDs should be unique across all collections in the corresponding root catalog - Clarified which media types should be used for the hierarchical relation types +- Restructured asset role types and clarified usage of the roles `thumbnail`, `overview` and `visual` ([#1272](https://github.com/radiantearth/stac-spec/pull/1272)) - Clarified that JSON Schema draft-07 is the default version for Collection summaries and other versions may not be supported ## [v1.0.0] - 2021-05-25 diff --git a/best-practices.md b/best-practices.md index dbf52061..894264bf 100644 --- a/best-practices.md +++ b/best-practices.md @@ -25,9 +25,6 @@ - [Formats with no registered media type](#formats-with-no-registered-media-type) - [Asset Roles](#asset-roles) - [List of Asset Roles](#list-of-asset-roles) - - [Thumbnail](#thumbnail) - - [Overview](#overview) - - [Visual](#visual) - **[Catalog & Collection Best Practices](#catalog--collection-practices)** - [Static and Dynamic Catalogs](#static-and-dynamic-catalogs) - [Static Catalogs](#static-catalogs) @@ -372,72 +369,52 @@ recommended to use at least one role for every asset available, and using multip both `data` and `reflectance` if your main data asset is processed to reflectance, or `metadata` and `cloud` for an asset that is a cloud mask, since a mask is considered a form of metadata (it's information about the data). Or if a single asset represents several types of 'unusable data' it might include `metadata`, `cloud`, `cloud-shadow` and `snow-ice`. If there is not a clear -role in the [Asset Role Types](item-spec/item-spec.md#asset-role-types) or the following list then just pick a sensible name for -the role. And you are encouraged to add it to the list below and/or in an extension if you think the new role will have broader -applicability. +role then just pick a sensible name for the role. You are encouraged to add it to the list below and/or +in an extension if you think the new role will have broader applicability. #### List of Asset Roles -In addition to the thumbnail, data and overview [roles listed](item-spec/item-spec.md#asset-role-types) in the Item spec, there -are a number of roles that are emerging in practice, but don't have enough widespread use to justify standardizing them. So if -you want to re-use other roles then try to find them on the list below, and also feel free to suggest more to include here. - -The 'source' field lists where the role comes from. The ones that say Item Spec are the only 'official' roles that are fully -standardized. In time others on this list may migrate to a more 'official' list. Those that say 'best practice' are just from this -doc, the listing is the table below. The ones from extensions are mostly just 'best practices' in the extensions, as there are few -actual role requirements. - -| Role Name | Source | Description | -| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| thumbnail | [Item Spec](item-spec/item-spec.md#asset-role-types) | 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. | -| data | [Item Spec](item-spec/item-spec.md#asset-role-types) | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | -| metadata | [Item Spec](item-spec/item-spec.md#asset-role-types) | A metadata sidecar file describing the data in this item, for example the Landsat-8 MTL file. | -| overview | Best Practice | An asset that represents a possibly larger view than the thumbnail of the Item, for example, a true color composite of multi-band data. | -| visual | Best Practice | An asset that is a full resolution version of the data, processed for visual use (RGB only, often sharpened ([pan-sharpened](https://en.wikipedia.org/wiki/Pansharpened_image) and/or using an [unsharp mask](https://en.wikipedia.org/wiki/Unsharp_masking))). | -| date | Best Practice | An asset that provides per-pixel acquisition timestamps, typically serving as metadata to another asset | -| graphic | Best Practice | Supporting plot, illustration, or graph associated with the Item | -| data-mask | Best Practice | File indicating if corresponding pixels have Valid data and various types of invalid data | -| snow-ice | Best Practice | Points to a file that indicates whether a pixel is assessed as being snow/ice or not. | -| land-water | Best Practice | Points to a file that indicates whether a pixel is assessed as being land or water. | -| water-mask | Best Practice | Points to a file that indicates whether a pixel is assessed as being water (e.g. flooding map). | iso-19139 | Best Practice | Points to an [ISO 19139](https://www.iso.org/standard/67253.html) metadata xml file | -| iso-19115 | Best Practice | Points to an [ISO 19115](https://www.iso.org/standard/53798.html) metadata file | -| reflectance, temperature, saturation, cloud, cloud-shadow | [EO Extension](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) in EO for more information, and the definitive list of roles related to EO. | -| incidence-angle, azimuth, sun-azimuth, sun-elevation, terrain-shadow, terrain-occlusion, terrain-illumination | [View Extension](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) in View for more information, and the definitive list of roles related to viewing angles. | -| local-incidence-angle, noise-power, amplitude, magnitude, sigma0, beta0, gamma0, date-offset, covmat, prd | [SAR Extension](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) in SAR for more information. , and the definitive list of roles related to SAR. | - -Some of the particular asset roles also have some best practices: - -##### Thumbnail - -Thumbnails are typically used to give quick overview, often embedded in a list of items. So think small with these, as -keeping the size down helps it load fast, and the typical display of a thumbnail won't benefit from a large size. Often 256 by -256 pixels is used as a default. Generally they should be no more than 600 by 600 pixels. Some implementors provide different sizes -of thumbnails - using something like thumbnail-small and thumbnail-large, with a small one being 100x100 pixels or less, for truly -fast rendering in a small image. Be sure to name one just 'thumbnail' though, as that's the default most STAC clients will look for. - -Thumbnails should be PNG, JPEG, or WebP, so that they can easily display in browsers, and they should be a true color composite -(red, green, and blue bands) if there are multiple bands. - -If your data for the Item does not come with a thumbnail already we do recommend generating one, which can be done quite easily. -[GDAL](https://gdal.org/) and [Rasterio](https://rasterio.readthedocs.io/en/latest/) both make this very easy - if you need help -just ask on the [STAC Gitter](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby). - -##### Overview - -An overview is a high-definition browse image of the dataset, giving the user more of a sense of the data than a thumbnail could. -It's something that can be easily displayed on a map without tiling, or viewed at full screen resolution (but not zoomed in). Similar -to a thumbnail it should be PNG, JPEG or WebP, for easy display in browsers, and should be a true color composite -(red, green, and blue bands) if there are multiple bands. The sizes could range from the high end of a thumbnail (600 by 600 pixels) -to a few thousand pixels on each side. - -###### Visual - -A visual asset is a full-resolution version of the data, but one that is optimized for display purposes. It can be in any file format, -but Cloud Optimized GeoTIFF's are preferred, since the inner pyramids and tiles enable faster display of the full resolution data. -It is typically an composite of red, blue and green bands, often with a nice color curve and sharpening for enhanced display. It should -be possible to open up on non-specialist software and display just fine. It can complement assets where one band is per file (like landsat), -by providing the key display bands combined, or can complement assets where many non-visible bands are included, by being a lighter weight -file that just has the bands needed for display +There are a number of roles that are commonly used in practice, which we recommend to reuse as much as possible. +If you can't find suitable roles, feel free to suggest more. + +| Role Name | Description | +| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| data | The data itself, excluding the metadata. | +| metadata | Metadata sidecar files describing the data, for example a Landsat-8 MTL file. | +| thumbnail | An asset that represents a thumbnail of the Item or Collection, typically a RGB or grayscale image primarily for human consumption, low resolution, restricted spatial extent, and displayable in a web browser without scripts or extensions. | +| overview | An asset that represents a more detailed overview of the Item or Collection, typically a RGB or grayscale image primarily for human consumption, medium resolution, full spatial extent, in a file format that's can be visualized easily (e.g., Cloud-Optimized GeoTiff). | +| visual | An asset that represents a detailed overview of the Item or Collection, typically a RGB or grayscale image primarily for human consumption, high or native resolution (often sharpened), full spatial extent, in a file format that's can be visualized easily (e.g., Cloud-Optimized GeoTiff). | +| date | An asset that provides per-pixel acquisition timestamps, typically serving as metadata to another asset | +| graphic | Supporting plot, illustration, or graph associated with the Item | +| data-mask | File indicating if corresponding pixels have Valid data and various types of invalid data | +| snow-ice | Points to a file that indicates whether a pixel is assessed as being snow/ice or not. | +| land-water | Points to a file that indicates whether a pixel is assessed as being land or water. | +| water-mask | Points to a file that indicates whether a pixel is assessed as being water (e.g. flooding map). | +| iso-19115 | Points to an [ISO 19115](https://www.iso.org/standard/53798.html) metadata file | + +Additional roles are defined in the various extensions, for example: + +- [EO Extension](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) +- [View Extension](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) +- [SAR Extension](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) + +The roles `thumbnail`, `overview` and `visual` are very similar. To make choosing the right role easier, please consult the table below. + +They should usually be a RGB or grayscale image, which are primarily intended for human consumption, e.g., through a web browser. +It can complement assets where one band is per file (like Landsat), by providing the key display bands combined, +or can complement assets where many non-visible bands are included, by being a lighter weight file that just has the bands needed for display. + +Roles should also be combined, e.g., `thumbnail` and `overview` if the recommendations are all met. + +If your data for the Item does not come with a thumbnail already we do recommend generating one, which can be done quite easily with [GDAL](https://gdal.org/) or [Rasterio](https://rasterio.readthedocs.io/en/latest/). + +| Role | thumbnail | overview | visual | +| ------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| Resolution | Low | Medium | Native / High | +| *Recommended* Image dimensions | < 600x600 px | < 5000x500 px | any size | +| *Recommended* File Formats | PNG, JPEG, GIF, WebP | PNG, JPEG, WebP, COG | COG, other cloud-native and/or tiled file formats with pyramids, ... | +| Spatial extent | Limited | Full | Full | +| Use case | Quick overview, often in lists of items/collections | Display for a single Item/Collection, sometimes shown on a web map | Display for a single Item/Collection, often shown on a map, may be displayed in GIS software | ## Catalog & Collection Practices @@ -684,14 +661,14 @@ with the `type` field) to communicate the structure and content of related entit Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) as much as possible. The following table describes a number of the common official relations that are used in production STAC implementations. -| Type | Description | -| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. | -| canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. | -| via | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel metadata XML, etc) | -| prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | -| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | -| preview | Refers to a resource that serves as a preview (see [RFC 6903, sec. 3](https://tools.ietf.org/html/rfc6903#section-3)), usually a lower resolution thumbnail. In STAC this would usually be the same URL as the [thumbnail](#thumbnail) asset, but adding it as a link in addition enables OGC API clients that can't read assets to make use of it. It also adds support for thumbnails to STAC Catalogs as they can't list assets. | +| Type | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. | +| canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. | +| via | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel metadata XML, etc) | +| prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | +| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | +| preview | Refers to a resource that serves as a preview (see [RFC 6903, sec. 3](https://tools.ietf.org/html/rfc6903#section-3)), usually a lower resolution thumbnail. In STAC this would usually be the same URL as the [thumbnail](#list-of-asset-roles) asset, but adding it as a link in addition enables OGC API clients that can't read assets to make use of it. It also adds support for thumbnails to STAC Catalogs as they can't list assets. | Being liberal with the `links` also means that it's ok to have repeated links with the same `href`. For example the `parent` and `root` relation types will point at the same file when the child is directly below the root, and it is diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index b139f553..76b56e25 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -300,7 +300,21 @@ or streamed. The definition provided here, at the Collection level, is the same | 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. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | type | string | [Media type](../item-spec/item-spec.md#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. | -| roles | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. | +| roles | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-roles) of the asset, similar to the use of `rel` in links. | + +#### Asset Roles + +The `roles` field is used to describe the purpose of each asset. It is recommended to include one for every asset, to give users +a sense of why they might want to make use of the asset. There are some emerging standards that enable clients to take particular +action when they encounter particular roles, listed below. But implementors are encouraged to come up with their own terms to +describe the role. + +Like the `rel` field in Link Objects, the `roles` field can be given any value. +However, there are a few standardized role names that can be found in the [best practices](../best-practices.md#list-of-asset-roles). +Commonly used are `thumbnail` and `overview`. + +Note that multiple roles per asset are encouraged: pick all the ones that apply. +For more information on how to use roles see the [Asset Roles](../best-practices.md#asset-roles) section of the Best Practices document. ### Range Object diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index c1fde3aa..42cfdb50 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -18,7 +18,6 @@ - [Asset Object](#asset-object) - [Asset Media Type](#asset-media-type) - [Asset Roles](#asset-roles) - - [Asset Role Types](#asset-role-types) - [Additional Fields for Assets](#additional-fields-for-assets) - [Media Type for STAC Item](#media-type-for-stac-item) - [Extensions](#extensions) @@ -259,26 +258,17 @@ a sense of why they might want to make use of the asset. There are some emerging action when they encounter particular roles, listed below. But implementors are encouraged to come up with their own terms to describe the role. -##### Asset Role Types - -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 | 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. | -| data | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | -| metadata | A metadata sidecar file describing the data in this Item, for example the Landsat-8 MTL file. | +Like the `rel` field in Link Objects, the `roles` field can be given any value. +However, there are a few standardized role names that can be found in the [best practices](../best-practices.md#list-of-asset-roles). +Commonly used are `thumbnail`, `overview`, `data` and `metadata`. It is STRONGLY RECOMMENDED to add to each STAC Item - a thumbnail with the role `thumbnail` for preview purposes -- one or more data file although it doesn't need to use the suggested role `data` +- one or more data files with the role `data` -Note that multiple roles per asset are encouraged: pick all the ones that apply. So many should have the 'data' role, and then -another role to describe how the data is used. For more information on how to use roles see the [Asset -Roles](../best-practices.md#asset-roles) section of the Best Practices document. It includes a [list of asset -roles](../best-practices.md#list-of-asset-roles) that include many more ideas on roles to use. As they reach more widespread -adoption we will include them here. +Note that multiple roles per asset are encouraged: pick all the ones that apply. +So many should have the `data` role, and then another role to describe how the data is used. +For more information on how to use roles see the [Asset Roles](../best-practices.md#asset-roles) section of the Best Practices document. #### Additional Fields for Assets