Repository navigation
Description
The colormap field is currently defined only through a link to TiTiler's documentation (as raised in #34), and #25 suggests moving colormap_name to matplotlib's names. This proposal builds on and connects the two: the spec says how to specify a color map and says that names are simply references to color maps. The proposal is flexible about where the name-to-colormap lookups are defined: a STAC backend can choose to stay lightweight and only provide the colormap names (relying on the client being conformant and therefore having its own defined list of matplotlib names), or the STAC backend can take on the responsibility to predefine and supply these as colormap objects (which take precedence) to enforce their own definition of color names. An added benefit of this approach is that it also allows a STAC backend to provide any custom color maps not limited to matplotlib (e.g. since matplotlib colormaps can be approximated in different ways). Below is suggested spec text, for discussion. The matplotlib version containing the list of minimal supported colormap names should be agreed and specified.
Suggested spec text
Fields (changed rows)
| Field Name | Type | Description |
|---|---|---|
colormap_name |
string | Name of a predefined colour map. See Colour maps. |
colormap |
Colour Map Object, optional, takes precedence over colormap_name |
An explicit colour map. See Colour maps. |
Colour maps
A render can give a colour scale as colormap_name, as colormap, or both.
- Name only: the client draws the named colour map, based on its own list of defined matplotlib colormaps.
colormap, with or without a name: the client MUST draw the object as given. When both are given, the name is just metadata. A backend can use this to enforce an exact look.
Predefined names
Clients MUST support the colour maps of matplotlib X.Y which can be reliably be reproduced using linear interpolation or distinct categorical lookup, including their reversed _r variants. This excludes those defined by functions (afmhot, cubehelix, flag, gist_gray, gist_heat, gist_yarg, gnuplot, gnuplot2, ocean, prism, rainbow).
Each name is equivalent to a Colour Map Object:
- Continuous colour maps (e.g.
viridis,RdBu) aretype: linearobjects, which get interpolated across the range inrescale. - Qualitative colour maps (e.g.
Set3,tab10) aretype: discreteobjects with an orderedcolorslist, which gets nearest neighbour resampling across the range inrescale.
Clients reproduce these colour maps as closely as they choose.
Backends MAY use additional names that they document. How such names are shared is outside this extension. A client that does not recognise a name uses its own default; backends that want to provide their own custom names or ensure that matplotlib names are reproduced reliable should also give colormap objects.
Colour Map Object
| Field Name | Type | Description |
|---|---|---|
type |
string | REQUIRED. linear or discrete. |
colors |
array | linear: colours, or [position, colour] pairs. discrete: an ordered list of colours. |
values |
object | discrete: colours keyed by data value. |
linearmaps colours acrossrescale. Flat list of colours are evenly spaced; list of position-color pairs give positions from 0 to 1 in ascending order. Colours are interpolated linearly in sRGB.discretemaps exact data values to colours, either through exactvalueslookup, or through an orderedcolorslist drawn as equal-width steps across rescale (the colors are resampled to nearest neighbour rather than interpolated).
Colours are #RRGGBB or #RRGGBBAA hex strings. Values not covered by a discrete map, and nodata, are transparent.
{ "type": "linear", "colors": ["#053061", "#f7f7f7", "#67001f"] }
{ "type": "linear", "colors": [[0, "#053061"], [0.4, "#f7f7f7"], [1, "#67001f"]] }
{ "type": "discrete", "values": { "1": "#1a9850", "2": "#d73027" } }
{ "type": "discrete", "colors": ["#8dd3c7", "#ffffb3", "#bebada"] }Client requirements
- Linear interpolation between colours, for
linearmaps and for predefined continuous names.discretemaps are value lookups or discrete colors stretched through nearest neighbour. - Would need to be able to parse and process the colormap objects defined in this standard, since the STAC backend requires being able to handle explicit
colormapfields. - Have a local definition of the minimum list of matplotlib colors defined in this standard. It's up to the client how to turn these names into colors that get rendered, but since the interpolation and colormap objects already need to be supported, easiest would be that the client has a lookup for name-to-colormap objects in a small JS file.
Notes
- The colormap objects and types follow rio-tiler's colour map forms, so each converts directly to titiler's parameters.
- An earlier version also included rio-tiler's
intervaltype, but dropped in favor of keeping the standard to only basic visualizations in first round. - In practice the full set of predefined names is small: excluding function-based ones, matplotlib 3.11 has 78 base colour maps, needing 2–64 positioned stops each, about 5 KB gzipped as JSON.
- This proposal keeps the current spec table's rule that
colormapoverridescolormap_name(titiler's code currently does the reverse). - If accepted, this proposal would come along with some other breaking changes (Clarify colormap_name requirements and usage #25, Update documentation for
bidxband index clarification #35) in a new major version. Current clients supporting this STAC render standard do not seem to check for the version, so it would be important to outreach to various supporting clients incl. TiTiler to encourage version dependent behavior.
Open questions
- This is a major departure from the contents of
colormap, so a question is whether to replace the old definition ofcolormapor make it a new field, as a way to allow some backwards compatibility for old clients? I would favor replacing the definition, since the suggested switch to matplotlib names are a break change with major version bump either way. - What to do with values outside
rescale? Either clamp too low or too high values to their start/end color, or not draw them (which would make them in a duplicate/another way to specify nodata). I think clamping would be best as a simple way to adjust for extreme outliers. - Should the standard allow case-insensitive names for the required matplotlib names? Tools such as titiler accepts only lowercase so would need to lowercase the names before passing on which i think is fine.
- The
discretecolormap type would overlap/compete withcolor_hintfor items that also have theclassification:classesattribute. These could disagree, but maybe that's ok, and probably best to have all rendering things defined inside the render extension/not care about what's defined outside the standard?
Activity