From f4b6e76fef7473538e615dd80f57fe4794c4851f Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Mon, 21 Sep 2026 23:27:00 +0200 Subject: [PATCH 1/3] Update CHANGELOG and README to clarify colormap_name requirements and usage --- CHANGELOG.md | 7 +++++++ README.md | 13 ++++++++++++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b7a6d4..272dbb5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- **BREAKING** (to be released as a new major version): `colormap_name` MUST now be a standard + [matplotlib colormap](https://matplotlib.org/stable/users/explain/colors/colormaps.html) name (e.g. `viridis`, + `YlGn`), to give the field a well-known, renderer-agnostic naming convention instead of an arbitrary free-form + string ([#14](https://github.com/stac-extensions/render/issues/14)) + ### Fixed - Document that `expression` accepts `string`, `object`, or `array`, matching the schema ([#8](https://github.com/stac-extensions/render/issues/8)) diff --git a/README.md b/README.md index a919f80..b87dcaa 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ The fields in the table below can be used in these parts of STAC documents: | title | string | Optional title of the rendering | | 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_name | string | Name of a standard [matplotlib colormap](https://matplotlib.org/stable/users/explain/colors/colormaps.html) (e.g. `viridis`, `YlGn`) to apply to 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 | | 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. | @@ -115,6 +115,17 @@ by simply specifying the `url` and `assets` query parameters. | `resampling` | `resampling` | Resampling method to use when reprojecting the raster. | | `bidx` | `bidx` | Dataset band indexes | +Titiler delegates colormaps to [rio-tiler](https://github.com/cogeotiff/rio-tiler)'s built-in registry +(`rio_tiler.colormap.cmap`), which is derived from matplotlib's colormaps but is not an exact match: + +- Names are **lowercased** (`colormap_name: "YlGn"` must be sent to titiler as `ylgn`). +- Reversed colormaps use matplotlib's `_r` suffix convention (e.g. `viridis_r`). +- The registry also includes some non-matplotlib colormaps (e.g. from [cmocean](https://matplotlib.org/cmocean/)), + and does not guarantee coverage of every matplotlib colormap name. + +A client sending `colormap_name` to titiler MUST lowercase the value first, and SHOULD verify the resulting +name is one titiler actually supports (`GET /colorMaps` lists the registered names) before assuming a match. + #### 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 05ec23c1a6763781fe0c49fdaef53dcc17d5fe69 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Tue, 22 Sep 2026 12:56:18 +0200 Subject: [PATCH 2/3] Update README.md Co-authored-by: Matthias Mohr --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b87dcaa..52f9599 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ The fields in the table below can be used in these parts of STAC documents: | title | string | Optional title of the rendering | | 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 | Name of a standard [matplotlib colormap](https://matplotlib.org/stable/users/explain/colors/colormaps.html) (e.g. `viridis`, `YlGn`) to apply to a raster band. | +| colormap_name | string | Name of a standard [matplotlib colormap](https://matplotlib.org/stable/users/explain/colors/colormaps.html) (e.g. `viridis`, `YlGn`) to apply to a raster band. Third party colormaps are not supported, use `colormap` instead. | | 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 | | 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. | From 82c25043eabcdf7a1eaa624a0d4044d7bf0dc971 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Tue, 6 Oct 2026 14:17:51 -0600 Subject: [PATCH 3/3] Update README.md Co-authored-by: Matthias Mohr --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 29a1b94..f5f2751 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ The fields in the table below can be used in these parts of STAC documents: | assets | \[string] | **REQUIRED**. Array of asset keys [referencing the assets](#assets-reference) that are used to make the rendering | | title | string | Optional title of the rendering | | rescale | \[float] | 2 dimensions array of delimited Min,Max range per band. If not provided, the data will not be rescaled. | | -| colormap_name | string | Name of a standard [matplotlib colormap](https://matplotlib.org/stable/users/explain/colors/colormaps.html) (e.g. `viridis`, `YlGn`) to apply to a raster band. Third party colormaps are not supported, use `colormap` instead. | +| colormap_name | string | Name of a standard [matplotlib colormap](https://matplotlib.org/3.11.2/users/explain/colors/colormaps.html) (e.g. `viridis`, `YlGn`) to apply to a raster band. Third party colormaps are not supported, use `colormap` instead. | | 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 | | nodata | float, string | Nodata value to use for this render, overriding any nodata value already defined on the referenced assets (e.g. via the [raster](https://github.com/stac-extensions/raster) extension). If not set, implementations SHOULD fall back to the asset's own nodata value. |