Rendering Extension Specification

• Title: Rendering
• Identifier: https://stac-extensions.github.io/render/v2.0.0/schema.json
• Field Name Prefix: renders
• Scope: Item, Collection
• Extension Maturity Classification: Pilot
• Owner: @emmanuelmathot @abarciauskas-bgse @smohiudd

This document explains the Rendering Extension to the SpatioTemporal Asset Catalog (STAC) specification.

Rendering extension aims at providings consumers with the possible rendering of an item or a collection (e.g. on a online map)

• Examples:
  • Landsat-8 example: Shows the basic usage of the extension in a landsat-8 STAC Item
  • Sentinel-2 example: Shows the basic usage of the extension in a Sentinel-2 STAC Item
  • Collection example: Shows the basic usage of the extension in a collection
• JSON Schema
• Changelog

Fields

The fields in the table below can be used in these parts of STAC documents:

• [ ] Catalogs
• [x] Collections
• [x] Item Properties (incl. Summaries in Collections)
• [ ] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
• [ ] Links

Render Object

The render object is open ended, so additional fields can be provided according to the needs of the rendering application.

Assets reference

The assets field is a list of asset keys referencing the assets that are used to make the rendering. The assets MUST be local assets defined in the same item.

[!NOTE] When it is intended to use assets from external items or specific bands in an asset, it is recommended to define a virtual asset and then reference its key in the assets field. See the NDVI example.

Positioning

The positioning of the source assets is defined by their position in the assets array. Typically, in the case of the composition of a RGB image, the first pointer would be the red band, the second the green band and the third the blue band.

"assets": [ "red", "green", "blue" ]

Rescaling

A rescaling of the values from the source asset(s) to the destination asset can be defined using the vrt:rescale field. It is specified as a 2 dimensions array of delimited Min,Max range per band.

"rescale": [
  [0, 10000], // band 1
  [0, 10000], // band 2
  [0, 10000]  // band 3
]

A prescaling can also be performed according to the offset and scale fields value of the raster extension.

Dynamic tile servers integration

The render objects are designed to be used by dynamic tile servers to produce RGB tiles from a STAC Item. They are generic enough to be used by any dynamic tile server. In the following sections, some tilers integration are described.

Titiler

titiler offers a native STAC reader.

The following table describes the titiler query parameters that could be used and the corresponding extension fields.

Either the client building titiler url can use the information in the virtual asset to build the query parameters or the dynamic tile server could use the information in the virtual asset to build the query parameters by simply specifying the url and assets query parameters.

Shortwave Infra-red visual thermal signature example

From the Sentinel-2 item:

"properties":{
  "renders":{
    "sir":
    {
      "title": "Shortwave Infra-red",
      "assets": [ "swir22", "nir",  "red" ],
      "rescale": [[0,5000],[0,7000],[0,9000]],
      "resampling": "nearest"
    }
  }
}

URL: https://api.cogeo.xyz/stac/crop/14.869,37.682,15.113,37.862/256x256.png?url=https://raw.githubusercontent.com/stac-extensions/raster/main/examples/item-sentinel2.json&assets=B12,B8A,B04&resampling_method=average&rescale=0,5000,0,7000,0,9000&return_mask=true

Result: Lava thermal signature of Mount Etna eruption (February 2021)

Normalized Difference Vegetation Index (NDVI) example

From the Landsat-8 example [article]: This example uses the virtual assets to define the NDVI asset first because in this use case, the NDVI asset could also be downloaded as a standalone asset.

"assets":{
  "ndvi": 
  {
    "roles": [ "virtual", "data", "index" ],
    "type": "image/vnd.stac.geotiff; cloud-optimized=true",
    "href": "https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-landsat8.json#/assets/ndvi",
    "vrt:hrefs": [
      { "key": "B04", "href": "https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-landsat8.json#/assets/B04"}, 
      { "key": "B05", "href": "https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-landsat8.json#/assets/B05"}],
    "title": "Normalized Difference Vegetation Index",
    "vrt:algorithm": "band_arithmetic",
    "vrt:algorithm_opts": {
      "expression": "(B05–B04)/(B05+B04)",
      "rescale": [[-1,1]]
    },
  }
},
"properties":{
  "renders":{
    "ndvi":
    {
      "title": "Normalized Difference Vegetation Index",
      "assets": [ "ndvi" ],
      "resampling": "average",
      "colormap_name": "ylgn"
    }
  }
}

If this case, the parameters to titiler must be extracted from both the virtual asset definition and the render object.

URL:

https://api.cogeo.xyz/stac/preview.png?url=https://raw.githubusercontent.com/stac-extensions/raster/main/examples/item-landsat8.json&expression=(B5–B4)/(B5+B4)&max_size=512&width=512&resampling_method=average&rescale=-1,1&color_map=ylgn&return_mask=true

Result: Landsat Surface Reflectance Normalized Difference Vegetation Index (NDVI) path 44 row 33.

Obviously, the same rendering can be applied to local source assets without using the virtual asset.

"properties":{
  "renders":{
    "ndvi":
    {
      "title": "Normalized Difference Vegetation Index",
      "assets": [ "B05", "B04" ],
      "resampling": "average",
      "colormap_name": "ylgn",
      "expression": "(B05–B04)/(B05+B04)",
      "rescale": [[-1,1]]
    }
  }
}

Links

It is highly suggested to have a web map link in the links section of the STAC Item as described in the Web Map Link extension to allow application to find the tiling endpoint of the dynamic tile server.

Additional Attributes

A web map link can be extended with the attribute render with a value corresponding to the key of the render object in the renders field in order to provide a cross link to the render object.

{
  "rel": "xyz",
  "type": "image/png",
  "title": "NDVI",
  "href": "https://api.cogeo.xyz/stac/preview.png?url=https://raw.githubusercontent.com/stac-extensions/raster/main/examples/item-landsat8.json&expression=(B5–B4)/(B5+B4)&max_size=512&width=512&resampling_method=average&rescale=-1,1&color_map=ylgn&return_mask=true",
  "render": "ndvi"
}

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples