add Custom Colormap querystring option

[vincentsarago]

closes #153

This PR does:

• rename color_map query parameter to colormap_name
• add colormap option.

The colormap option accepts JSON encoded object in form of:

{
    "1": {RGB(A)}
}

the {RBG(A)} value can either be a list of R,G,B (and Alpha) values or an hex color representation

cc @kylebarron @blazetopher

[vincentsarago]

breaking change

[vincentsarago]

should we also accept base64 encoded string?

[geospatial-jeff]

neither are great, but I think base64 is less weird than JSON for get requests

[vincentsarago]

another way maybe would be to pass a list of value like

colormap=1,#FFFF00&colormap=2,#FF00FF

#equivalent of

colormap={"1": "#FFFF00", "2":"#FF00FF"}

[vincentsarago]

following some discussion on slack,

Right now a user could define a discrete colormap by passing a JSON encoded object in form of

colormap={"1": "#FFFF00", "2":"#FF00FF"}

I understand that this is quite uncommon for GET request to receive dict in a query parameter, but we don't really have a choice (because we can't store a colormap somewhere.

we need a way to pass a list of key/value, and for now this PR uses a JSON dict.

List seems to be an accepted type for query parameter, using the form opt=1&opt=2 (FastAPI will resolve this to opt=[1, 2]. So maybe a form like colormap=1,#FFFF00&colormap=2,#FF00FF would be better 🤷

Options

• JSON encoded object {note: would need to be decoded and re-encoded in tilejson endpoint)

...preview.png?colormap={"1": "#FFFF00", "2":"#FF00FF"} (should be url encoded)

• base64 encoded dict (seems to be a nice option but pretty custom)

...preview.png?colormap=dsaidhauhdasiojhd928e1uqwijs09qus0x8ahxas

• List defined colormap value (restricted to hex color definition and custom key/color 1,#fff form)

...preview.png?colormap=1,#FFFF00&colormap=2,#FF00FF

👂

[vincentsarago]

Note: the # shouldn't be used in a non-encoded url

[vincentsarago]

Option 1

JSON encoded object {note: would need to be decoded and re-encoded in tilejson endpoint)

 ...preview.png?colormap={"1": "#FFFF00", "2":"#FF00FF"} (should be url encoded)

Option 2

base64 encoded dict (seems to be a nice option but pretty custom)

...preview.png?colormap=dsaidhauhdasiojhd928e1uqwijs09qus0x8ahxas

Option 3

List defined colormap value (restricted to hex color definition and custom key/color 1,#fff form)

 ...preview.png?colormap=1,FFFF00&colormap=2,FF00FF

I think it's fine to go with option 1. It's not the best solution but:

• Starlette will take care of the urlencode/decode part, so we don't really need to worry in the API
• using base64 encoded dict in query string is not something widely used/accepted
• The third option looks more like proper HTTP query string but still custom because we will need to encode 2,FF00FF

Notes:
I also though about something like

colormap=FFFF00&colormap_stop=1,&colormap= FF00FF&colormap_stop=2

which will 💯 match the specs but still really verbose and not as easy as option 1

cc @kylebarron @geospatial-jeff @ingalls