Skip to content

Fix broken links and update NDVI documentation #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
emmanuelmathot merged 4 commits into from
Sep 22, 2026
Merged

Fix broken links and update NDVI documentation #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c71b787
Fix broken links in documentation and update placeholders for titiler…
emmanuelmathot Sep 21, 2026
ba730b0
Update documentation and examples for Sentinel-2 NDVI calculations an…
emmanuelmathot Sep 21, 2026
41ebd3b
fixed ttiler previews
emmanuelmathot Sep 21, 2026
a6ff9b2
Update examples/item-sentinel2.json
emmanuelmathot Sep 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
66 changes: 38 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -117,15 +117,15 @@ 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":{
"renders":{
"sir":
{
"title": "Shortwave Infra-red",
"assets": [ "swir22", "nir", "red" ],
"assets": [ "B12", "B08", "B04" ],
"rescale": [[0,5000],[0,7000],[0,9000]],
"resampling": "nearest"
}
Expand All @@ -135,19 +135,24 @@ 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://<titiler-endpoint>/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)

![etna](images/etna.png)

#### 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.

Expand All @@ -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]]
},
}
Expand All @@ -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://<titiler-endpoint>/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.

Expand All @@ -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]]
}
}
Expand All @@ -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://<titiler-endpoint>/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"
}
```
Expand Down
72 changes: 55 additions & 17 deletions examples/item-sentinel2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,14 @@
]
],
"resampling": "nearest"
},
"ndvi": {
"title": "Normalized Difference Vegetation Index",
"assets": [
"ndvi"
],
"resampling": "average",
"colormap_name": "ylgn"
}
}
},
Expand All @@ -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)",
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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",
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -650,4 +688,4 @@
"title": "Sentinel-2 L2A Cogs Collection"
}
]
}
}
Binary file added images/ndvi.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading