Color Ramp

src/colorramp.ts

A color ramp is a color gradient defined in a specific interval, for instance in [0, 1], and for any value within this interval will retrieve a color. They are defined by at least a color at each bound and usualy additional colors within the range.

Color ramps are super useful to represent numerical data in a visual way: the temperature, the population density, the average commute time, etc.

Example

To use an already existing color ramp and access some of its values:

Creating a new one consists in defining all the colors for each color stops. The values can be in the range of interest and do not have to be in [0, 1]. For example, let's recreate a Viridis color ramp but with a range going from 0 to 100:

When defining a new ramp, the colors can be a RGB array ([number, number, number]) or a RGBA array ([number, number, number, number]).

View more Color Ramp examples

Parameters

Methods

Non-linear color ramps

In this section we will see how to use the resample function of a color ramp to improve the visualization of data from a point layer.

We are using a large dataset containing all the public schools in the US. We are using the PORTLAND color ramp:

For the purpose of visualising the number of students, we are going to scale the PORTLAND color ramp on the range 300 to 4000 as most schools will contains more than 300 students and less than 4000.

Linear

We used the following color ramp definition:

Here is how the data looks like over a New York City:

It's not entirely bad, but only the very large schools stand out and it's quite difficult, without looking at the numbers, to differentiate all the blue dots just from their color variations.

Generally speaking in data visualisation, small variations matter towards the lower bound and large variations matter towards the upper bound. For this particular dataset, we would like a schools with 300 students to show differently from a school with 500 (IOW, a small difference of 200 in the lower bound), but we would like a school with 3800 students to look roughly the same as one with 4000 students (IOW, a small difference on the upper bound). And this is where non linear rescaling or color ramps comes into play!

Non-linear: ease-out square-root

Easing-out is a way to say that something accelerates a lot at the beginning of a given interval and slows down towards the end, while still increasing all the way (aka. monotonically increasing).

To perform the nonlinear rescaling of color ramps, MapTiler SDK performs some intermediate range changes so that only the range [0, 1] is actually relevant to observe (but then rescaled to its original range). Here is how the square root function looks like, naturally being of the ease-out kind:

To obtain a PORTLAND color ramp scaled with the square root method, we can do:

This results in the following version of PORTLAND:

As we can see if we compare with its linear version, this resampled color ramp is slightly left-skewed and shows much faster variations towards the beginning of the range. That's exactly what we want to leverage to better visualise the differences between schools with fewer number of students.

Here is how the same data looks like now:

It's no longer about blue dots everywhere! We can now fairly easily differentiate a school with 400 students than one with 800.

Non-linear going too far: ease-out exponential

Some functions have a much steeper slope than the square root function and would emphasise the differences even more on the lower bound, maybe a bit too much, at the expense of clarity for the rest of the range.

For very specific usages, the SDK features an exponential resampling. Here is how its function looks like on [0, 1] range:

As we can see, starting from x = 0.5 there is very little variation left.

Here is how to create the corresponding PORTLAND color ramp:

The color ramp created looks very left-skewed:

And the map visualisation:

The South Bronx (north of Manhattan) contains many smaller schools that now look like they no longer have this blue color representative of the lower bound from the Portland color ramp. This is basically means we crossed a line in terms of resampling function and that our color ramp is no longer suitable for our purpose.

Of course, knowing that the granularity of the color ramp on the second half is very poor, we can change its range, maybe double it to [300, 8000]:

And we would still obtain a decent visualisation:

But then, the process is backward and means the data range is adapted based on the capabilities and limitations of the color ramp. This adds an unnecessary overhead.

Builtin color ramps

The SDK includes many built-in ready to use color ramps as well as extra logic to manipulate them and create new ones, here is the full list:

Types and Interfaces

ColorStop

  {
    value: number, // The "value" at which this ColorStop should be applied.
    color: string // GB[A] - Array of 3-4 numbers. 0-255 per channel.
  }