diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b7a6d4..e0bdf88 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed - Document that `expression` accepts `string`, `object`, or `array`, matching the schema ([#8](https://github.com/stac-extensions/render/issues/8)) +- Update broken titiler `colormap`/`color_formula` doc links and replace the dead `api.cogeo.xyz` demo host. + Rework the NDVI example around the still-live Sentinel-2 item, since the Landsat-8 example's source imagery + was removed from the public `landsat-pds` bucket ([#13](https://github.com/stac-extensions/render/issues/13)) ## [2.0.0] - 2024-11-19 diff --git a/README.md b/README.md index a919f80..6c5f7e5 100644 --- a/README.md +++ b/README.md @@ -41,8 +41,8 @@ The fields in the table below can be used in these parts of STAC documents: | rescale | \[float] | 2 dimensions array of delimited Min,Max range per band. If not provided, the data will not be rescaled. | | nodata | float, string | Nodata value to use for the referenced assets. | | colormap_name | string | Color map identifier that must be applied for a raster band | -| colormap | object | [Color map JSON definition](https://developmentseed.org/titiler/advanced/rendering/#custom-colormaps) that must be applied for a raster band | -| color_formula | string | [Color formula](https://developmentseed.org/titiler/advanced/rendering/#color-formula) that must be applied for a raster band | +| colormap | object | [Color map JSON definition](https://developmentseed.org/titiler/user_guide/rendering/#custom-colormaps) that must be applied for a raster band | +| color_formula | string | [Color formula](https://developmentseed.org/titiler/user_guide/rendering/#color-formula) that must be applied for a raster band | | resampling | string | Resampling algorithm to apply to the referenced assets. See [GDAL resampling algorithm](https://gdal.org/programs/gdalwarp.html#cmdoption-gdalwarp-r) for some examples. | | expression | string, object, array | Band arithmetic formula to apply to the referenced assets. The format is defined by the rendering application, e.g. a [TiTiler](https://developmentseed.org/titiler/) band math string or a [MapLibre](https://maplibre.org/maplibre-style-spec/expressions/) style expression array. | | minmax_zoom | \[int] | Zoom levels range applicable for the visualization | @@ -117,7 +117,7 @@ by simply specifying the `url` and `assets` query parameters. #### Shortwave Infra-red visual thermal signature example -From the [Sentinel-2 item](https://github.com/stac-extensions/virtual-assets/blob/main/examples/item-sentinel2.json): +From the [Sentinel-2 item](examples/item-sentinel2.json): ```json "properties":{ @@ -125,7 +125,7 @@ From the [Sentinel-2 item](https://github.com/stac-extensions/virtual-assets/blo "sir": { "title": "Shortwave Infra-red", - "assets": [ "swir22", "nir", "red" ], + "assets": [ "B12", "B08", "B04" ], "rescale": [[0,5000],[0,7000],[0,9000]], "resampling": "nearest" } @@ -135,11 +135,16 @@ From the [Sentinel-2 item](https://github.com/stac-extensions/virtual-assets/blo | Query key | value | Example value | | --------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------- | -| url | STAC Item URL | `https://raw.githubusercontent.com/stac-extensions/raster/main/examples/item-sentinel2.json` | -| assets | Assets keys defined in the `assets` fields | `B12,B8A,B04` | +| url | STAC Item URL | `https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-sentinel2.json` | +| assets | Assets keys defined in the `assets` fields | `B12,B08,B04` | | rescale | Delimited Min,Max bounds defined in `rescale` field | `0,5000,0,7000,0,9000` | -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`](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) +Example URL, using a self-hosted or public [titiler](https://github.com/developmentseed/titiler) instance +(the `assets` and `rescale` parameters are repeated, one per band): + +```text +https:///stac/bbox/13.86148243891681,36.95257399124932,15.111074610520053,37.94752813015372/512x512.png?url=https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-sentinel2.json&assets=B12&assets=B08&assets=B04&resampling_method=nearest&rescale=0,5000&rescale=0,7000&rescale=0,9000&return_mask=true +``` **Result**: Lava thermal signature of Mount Etna eruption (February 2021) @@ -147,7 +152,7 @@ URL: [`https://api.cogeo.xyz/stac/crop/14.869,37.682,15.113,37.862/256x256.png?u #### Normalized Difference Vegetation Index (NDVI) example -From the [Landsat-8 example](examples/item-landsat8.json) \[[article](https://www.usgs.gov/core-science-systems/nli/landsat/landsat-normalized-difference-vegetation-index?qt-science_support_page_related_con=0#qt-science_support_page_related_con)]: +From the [Sentinel-2 item](examples/item-sentinel2.json): This example uses the [virtual assets](https://github.com/stac-extensions/virtual-assets) to define the NDVI asset first because in this use case, the NDVI asset could also be downloaded as a standalone asset. @@ -157,14 +162,14 @@ the NDVI asset could also be downloaded as a standalone asset. { "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", + "href": "https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-sentinel2.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"}], + { "key": "B04", "href": "https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-sentinel2.json#/assets/B04"}, + { "key": "B08", "href": "https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-sentinel2.json#/assets/B08"}], "title": "Normalized Difference Vegetation Index", "vrt:algorithm": "band_arithmetic", "vrt:algorithm_opts": { - "expression": "(B05–B04)/(B05+B04)", + "expression": "(B08-B04)/(B08+B04)", "rescale": [[-1,1]] }, } @@ -185,21 +190,26 @@ the NDVI asset could also be downloaded as a standalone asset. If this case, the parameters to titiler must be extracted from both the virtual asset definition and the render object. -| Query key | value | Example value | -| ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| url | STAC Item URL | `https://raw.githubusercontent.com/stac-extensions/raster/main/examples/item-landsat8.json` | -| expression | Band math formula as defined in field `vrt:algorithm` | `(B5–B4)/(B5+B4)` | -| rescale | Delimited Min,Max bounds defined in `rescale` field | `-1,1` | -| colormap | Color map JSON definition as defined in `colormap_name` | `ylgn` | -| resampling_method | Resampling method to use when reprojecting the raster as defined in `resampling` | `average` | - -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`](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) +| Query key | value | Example value | +| ----------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------| +| url | STAC Item URL | `https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-sentinel2.json` | +| assets | Assets used in the expression, in the order they are referenced | `B08,B04` | +| expression | Band math formula as defined in field `vrt:algorithm` | `(B08-B04)/(B08+B04)` | +| rescale | Delimited Min,Max bounds defined in `rescale` field | `-1,1` | +| colormap_name | Color map name as defined in `colormap_name` | `ylgn` | +| resampling_method | Resampling method to use when reprojecting the raster as defined in `resampling` | `average` | + +Example URL, using a self-hosted or public [titiler](https://github.com/developmentseed/titiler) instance. +titiler combines multiple `assets` positionally, so the `expression` sent to titiler must reference them as +`b1`, `b2`, ... in the order given by `assets` (here `b1` = `B08`, `b2` = `B04`), rather than by their asset names: + +```text +https:///stac/preview.png?url=https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-sentinel2.json&assets=B08&assets=B04&expression=(b1-b2)/(b1%2Bb2)&max_size=512&width=512&resampling_method=average&rescale=-1,1&colormap_name=ylgn&return_mask=true +``` -Result: Landsat Surface Reflectance Normalized Difference Vegetation Index (NDVI) path 44 row 33. +**Result**: Sentinel-2 Normalized Difference Vegetation Index (NDVI), tile 33SVB (Sicily, Italy). -![sacramento](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) +![ndvi](images/ndvi.png) Obviously, the same rendering can be applied to local source assets without using the virtual asset. @@ -209,10 +219,10 @@ Obviously, the same rendering can be applied to local source assets without usin "ndvi": { "title": "Normalized Difference Vegetation Index", - "assets": [ "B05", "B04" ], + "assets": [ "B08", "B04" ], "resampling": "average", "colormap_name": "ylgn", - "expression": "(B05–B04)/(B05+B04)", + "expression": "(B08-B04)/(B08+B04)", "rescale": [[-1,1]] } } @@ -236,7 +246,7 @@ 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", + "href": "https:///stac/preview.png?url=https://raw.githubusercontent.com/stac-extensions/render/main/examples/item-sentinel2.json&assets=B08&assets=B04&expression=(b1-b2)/(b1%2Bb2)&max_size=512&width=512&resampling_method=average&rescale=-1,1&colormap_name=ylgn&return_mask=true", "render": "ndvi" } ``` diff --git a/examples/item-sentinel2.json b/examples/item-sentinel2.json index 8dd3407..340930b 100644 --- a/examples/item-sentinel2.json +++ b/examples/item-sentinel2.json @@ -84,6 +84,14 @@ ] ], "resampling": "nearest" + }, + "ndvi": { + "title": "Normalized Difference Vegetation Index", + "assets": [ + "ndvi" + ], + "resampling": "average", + "colormap_name": "ylgn" } } }, @@ -95,7 +103,7 @@ "roles": [ "metadata" ], - "href": "metadata.xml" + "href": "https://roda.sentinel-hub.com/sentinel-s2-l2a/tiles/33/S/VB/2021/2/21/0/metadata.xml" }, "B01": { "title": "Band 1 (coastal)", @@ -112,7 +120,7 @@ "full_width_half_max": 0.027 } ], - "href": "B01.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B01.tif", "proj:shape": [ 1830, 1830 @@ -160,7 +168,7 @@ "full_width_half_max": 0.098 } ], - "href": "B02.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B02.tif", "proj:shape": [ 10980, 10980 @@ -208,7 +216,7 @@ "full_width_half_max": 0.045 } ], - "href": "B03.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B03.tif", "proj:shape": [ 10980, 10980 @@ -256,7 +264,7 @@ "full_width_half_max": 0.038 } ], - "href": "B04.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B04.tif", "proj:shape": [ 10980, 10980 @@ -303,7 +311,7 @@ "full_width_half_max": 0.019 } ], - "href": "B05.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B05.tif", "proj:shape": [ 5490, 5490 @@ -350,7 +358,7 @@ "full_width_half_max": 0.018 } ], - "href": "B06.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B06.tif", "proj:shape": [ 5490, 5490 @@ -397,7 +405,7 @@ "full_width_half_max": 0.028 } ], - "href": "B07.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B07.tif", "proj:shape": [ 5490, 5490 @@ -429,7 +437,7 @@ "full_width_half_max": 0.145 } ], - "href": "B08.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B08.tif", "proj:shape": [ 10980, 10980 @@ -446,6 +454,36 @@ 1 ] }, + "ndvi": { + "roles": [ + "virtual", + "data", + "index" + ], + "type": "image/tiff; application=geotiff; profile=cloud-optimized", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A#/assets/ndvi", + "vrt:hrefs": [ + { + "key": "B04", + "href": "#/assets/B04" + }, + { + "key": "B08", + "href": "#/assets/B08" + } + ], + "title": "Normalized Difference Vegetation Index", + "vrt:algorithm": "band_arithmetic", + "vrt:algorithm_opts": { + "expression": "(B08-B04)/(B08+B04)", + "rescale": [ + [ + -1, + 1 + ] + ] + } + }, "B8A": { "title": "Band 8A", "type": "image/tiff; application=geotiff; profile=cloud-optimized", @@ -460,7 +498,7 @@ "full_width_half_max": 0.033 } ], - "href": "B8A.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B8A.tif", "proj:shape": [ 5490, 5490 @@ -491,7 +529,7 @@ "full_width_half_max": 0.026 } ], - "href": "B09.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B09.tif", "proj:shape": [ 1830, 1830 @@ -523,7 +561,7 @@ "full_width_half_max": 0.143 } ], - "href": "B11.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B11.tif", "proj:shape": [ 5490, 5490 @@ -555,7 +593,7 @@ "full_width_half_max": 0.242 } ], - "href": "B12.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B12.tif", "proj:shape": [ 5490, 5490 @@ -578,7 +616,7 @@ "roles": [ "data" ], - "href": "AOT.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/AOT.tif", "proj:shape": [ 1830, 1830 @@ -601,7 +639,7 @@ "roles": [ "data" ], - "href": "WVP.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/WVP.tif", "proj:shape": [ 10980, 10980 @@ -624,7 +662,7 @@ "roles": [ "data" ], - "href": "SCL.tif", + "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/SCL.tif", "proj:shape": [ 5490, 5490 @@ -650,4 +688,4 @@ "title": "Sentinel-2 L2A Cogs Collection" } ] -} \ No newline at end of file +} diff --git a/images/ndvi.png b/images/ndvi.png new file mode 100644 index 0000000..ace453a Binary files /dev/null and b/images/ndvi.png differ