Roles best practice

best-practices.md

@@ -20,6 +20,9 @@
   - [Working with Media Types](#working-with-media-types)
     - [Common Media Types in STAC](#common-media-types-in-stac)
     - [Formats with no registered media type](#formats-with-no-registered-media-type)
+  - [Asset Roles](#asset-roles)
+    - [List of Asset Roles](#list-of-asset-roles)
+    - [Thumbnails](#thumbnails)
 - **[Catalog & Collection Best Practices](#catalog--collection-practices)**
   - [Static and Dynamic Catalogs](#static-and-dynamic-catalogs)
     - [Static Catalogs](#static-catalogs)
@@ -38,8 +41,6 @@
     - [Ingestion and links](#ingestion-and-links)
     - [Keep catalogs in sync with cloud notification and queue services](#keep-catalogs-in-sync-with-cloud-notification-and-queue-services)
 
----------
-
 This document makes a number of recommendations for creating real world SpatioTemporal Asset Catalogs. None of them 
 are required to meet the core specification, but following these practices will make life easier for client tooling
 and for users. They come about from practical experience of implementors and introduce a bit more 'constraint' for
@@ -274,6 +275,61 @@ register the media type with IANA, so that other STAC clients can find it easily
 [acceptable to not register](https://stackoverflow.com/questions/29121241/custom-content-type-is-registering-with-iana-mandatory) 
 it. It is relatively easy to [register](https://www.iana.org/form/media-types) a `vnd` media type.
 
+## Asset Roles
+
+[Asset roles](item-spec/item-spec.md#asset-roles) are used to describe what each asset is used for. They are particular useful 
+when several assets have the same media type, such as when an Item has a multispectral analytic asset, a 3-band full resolution 
+visual asset, a down-sampled preview asset, and a cloud mask asset, all stored as Cloud Optimized GeoTIFF (COG) images. It is 
+recommended to use at least one role for every asset available, and using multiple roles often makes sense. For example you'd use
+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. 
+
+### 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 the 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). |
+| reflectance, temperature, saturation, cloud, cloud-shadow | [EO Extension](extensions/eo/README.md#best-practices) | See the [table](extensions/eo/README.md#best-practices) in EO for more information. |
+| incidence-angle, azimuth, sun-azimuth, sun-elevation, terrain-shadow, terrain-occlusion, terrain-illumination | [View Extension](extensions/view/README.md#best-practices) | See the [table](extensions/view/README.md#best-practices) in View for more information. |
+| local-incidence-angle, noise-power, amplitude, magnitude, sigma0, beta0, gamma0, date-offset, covmat, prd | [SAR Extension](extensions/sar/README.md#best-practices) | See the [table](extensions/sar/README.md#best-practices) in SAR for more information. |
+
+Some of the particular asset roles also have some best practices:
+
+### Thumbnails
+
+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 1000 by 1000 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.
+
+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).
+
 ## Catalog & Collection Practices
 
 ### Static and Dynamic Catalogs

extensions/eo/README.md

@@ -136,3 +136,18 @@ The [extensions page](../README.md) gives an overview about related extensions.
 
 * the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite.
 * the [View Geometry Extension Specification](../view/README.md) to describe angles of sensors collecting earth observation data from above the earth.
+
+## Best Practices
+
+One of the emerging best practices is to use [Asset Roles](../../item-spec/item-spec.md#asset-roles) to provide clients with more 
+information about the assets in an item. The following list includes a shared vocabulary for some common EO assets. This list should
+not be considered definitive, and implementors are welcome to use other asset roles. If consensus and tooling consolidates around
+these role names then they will be specified in the future as more standard than just 'best practices'.
+
+| Role Name | Description                                                            |
+| --------- | ---------------------------------------------------------------------- |
+| reflectance | An asset the provides [reflectance](https://www.l3harrisgeospatial.com/Support/Self-Help-Tools/Help-Articles/Help-Articles-Detail/ArtMID/10220/ArticleID/19247/3377) values, instead of just radiance. |
+| temperature | An asset that provides actual temperature measurements. |
+| saturation |  Points to a file that indicates where pixels in the input spectral bands are saturated. |
+| cloud | Points to a file that indicates whether a pixel is assessed as being cloud |
+| cloud-shadow | Points to a file that indicates whether a pixel is assessed as being cloud shadow. |

extensions/sar/README.md

@@ -86,3 +86,24 @@ The center time of the frame should be specified with the `datetime` property fo
 The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to SAR data:
 
 * the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite.
+
+## Best Practices
+
+One of the emerging best practices is to use [Asset Roles](../../item-spec/item-spec.md#asset-roles) to provide clients with more 
+information about the assets in an item. The following list includes a shared vocabulary for some common EO assets. This list should
+not be considered definitive, and implementors are welcome to use other asset roles. If consensus and tooling consolidates around
+these role names then they will be specified in the future as more standard than just 'best practices'.
+
+| Role Name | Description                                                            |
+| --------- | ---------------------------------------------------------------------- |
+| local-incidence-angle | Points to the local incidence angle file. |
+| ellipsoid-incidence-angle | Points to the ellipsoid incidence angle file. |
+| noise-power | Points to the noise power file. |
+| amplitude | Points to the intensity file with focused SAR data that has been ground range detected (e.g. GRD). |
+| magnitude | Points to the intensity file where data are represented as complex numbers containing amplitude and phase information (e.g SLC). |
+| sigma0 | Points to the radar backscatter file where data is referenced in ground surface. It is often derived from an `amplitude` or a `magnitude` role asset. |
+| beta0 | Points to the radar backscatter file where data is referenced in the slant range plane and is radiometrically calibrated.  It is often derived from an `amplitude` or a `magnitude` role asset. |
+| gamma0 | Points to the radar backscatter file where data is referenced in the plane perpendicular to the line of sight. It is often derived from an `amplitude` or a `magnitude` role asset. |
+| date-offset | Points to the date-offset file. |
+| covmat | Points to the Points to the Normalized Polarimetric Radar Covariance Matrix (CovMat) file. |
+| prd | Points to the Polarimetric Radar Decomposition (PRD) file. |

extensions/view/README.md

@@ -63,3 +63,22 @@ Example:
 ## Extensions
 
 The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to View Geometry data.
+
+## Best Practices
+
+One of the emerging best practices is to use [Asset Roles](../../item-spec/item-spec.md#asset-roles) to provide clients with more 
+information about the assets in an item. The following list includes a shared vocabulary for some common EO assets. This list should
+not be considered definitive, and implementors are welcome to use other asset roles. If consensus and tooling consolidates around
+these role names then they will be specified in the future as more standard than just 'best practices'. The roles listed below
+all tend to be additional files that contain specific values for every single pixel. It is recommended to use them all with the role
+of 'metadata'.
+
+| Role Name | Description                                                            |
+| --------- | ---------------------------------------------------------------------- |
+| incidence-angle | Points to a file with per-pixel incidence angles. |
+| azimuth | Points to a file with per-pixel azimuth angles. |
+| sun-azimuth | Points to a file with per-pixel sun azimuth angles. |
+| sun-elevation | Points to a file with per-pixel sun elevation angles. |
+| terrain-shadow | Points to a file that indicates whether a pixel is not directly illuminated due to terrain shadowing. |
+| terrain-occlusion | Points to a file that indicates whether a pixel is not visible to the sensor due to terrain occlusion during off-nadir viewing. |
+| terrain-illumination | Points to a file with coefficients used for terrain illumination correction are provided for each pixel. |

item-spec/item-spec.md

@@ -180,7 +180,7 @@ or streamed. It is allowed to add additional fields.
 | 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](#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](#asset-role-types) of the asset, similar to the use of `rel` in links. |
+| roles       | \[string] | The [semantic roles](#asset-roles) of the asset, similar to the use of `rel` in links. |
 
 [Additional fields](#additional-fields) *may* be added to the assets, though this
 is recommended only in special cases. See [Additional Fields for Assets](#additional-fields-for-assets)) for more information.
@@ -194,22 +194,33 @@ would be appropriate; if it is an XML, then `text/xml` is appropriate. For more
 list of [common media types](../best-practices.md#common-media-types-in-stac) used in STAC see the [best practice on 
 working with media types](../best-practices.md#working-with-media-types).
 
-#### Asset Role Types
+#### Asset Roles
 
-Like the Link `rel` field, the `roles` field can be given any value, however here are a few standardized role names.
+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.
+
+##### 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. |
-| visual    | 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))). |
 
 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`
 
+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.
+
 #### Additional Fields for Assets
 
 As detailed above, Items contain properties, which are the main source of metadata for searching across Items. Many content