Misleading explicit_color_map documentation

[bartwalczak]

Hi,

If you follow the explicit_color_map documentation example as it is written, you will get the following error

time="2023-05-13T13:50:48Z" level=info msg=request URI="/v1/tc/singleband/tiff_orig/0/EMEP/PM10/A/2019/4/10/6.png?stretch_range=[0,27042.123]&colormap=explicit&explicit_color_map={0:(0,128,0,255),1:(255,43,36,255)}" method=GET status=500
marshmallow.exceptions.ValidationError: {'_schema': ['Could not decode value {0:(0,128,0,255),1:(255,43,36,255)} for explicit_color_map as JSON']}

The valid example should be a proper JSON:

 {"0":[0,128,0,255],"1":[255,43,36,255]}

And if Python data types are used, they should be marked as such. Otherwise this is misleading if one is making a request not using Python.

[bartwalczak]

However, despite being properly parsed, this request does not seem to render the explicit color map - all pixel values are returned as transparent.

What am I missing?

[dionhaefner]

Thanks for the report. This will be fixed in #307.

However, despite being properly parsed, this request does not seem to render the explicit color map - all pixel values are returned as transparent.

Sounds like there is a misunderstanding regarding what an explicit color map means. This feature is really for categorical data, i.e., 1-to-1 mappings of raster values to colors. The keys of the given mapping relate to the values of the raster. So a query like this pretty much never makes sense:

?stretch_range=[0,27042.123]&colormap=explicit&explicit_color_map={"0":[0,128,0,255],"1":[255,43,36,255]}

Because the stretch_range argument suggests that you have a continuous range of values, but you're using a discrete mapping.

See also this tutorial on explicit color maps.

[bartwalczak]

Thanks. Does this mean that there is no way to create a dynamic threshold map in Terracotta? I know that I can create a custom map file and upload it to the server, but I wanted to offer a relative scale based on percentiles for each file (and there is over a hundred of them).

[dionhaefner]

Correct, we only support linear transformations via stretch_range.

I suggest you rescale the rasters offline before ingestion. If that is not an option, you could use the /compute endpoint to transform the raster on the fly, but then you're still limited to simple algebraic expressions (which may suffice if using just a few percentiles).

[bartwalczak]

Thanks a lot for your support.

[dionhaefner]

Happy to help.