Skip to content

Proposal: Self-contained colour render definitions #39

Open

Description

@karimbahgat

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) are type: linear objects, which get interpolated across the range in rescale.
  • Qualitative colour maps (e.g. Set3, tab10) are type: discrete objects with an ordered colors list, which gets nearest neighbour resampling across the range in rescale.

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.
  • linear maps colours across rescale. 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.
  • discrete maps exact data values to colours, either through exact values lookup, or through an ordered colors list 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 linear maps and for predefined continuous names. discrete maps 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 colormap fields.
  • 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 interval type, 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 colormap overrides colormap_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 bidx band 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 of colormap or 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 discrete colormap type would overlap/compete with color_hint for items that also have the classification:classes attribute. 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions