Introduce colormaps

[michalsustr]

Introduce colormaps and a default colormap.

There are two principal uses of colormaps:

1. Heatmaps
2. Picking plot item colors (lines, markers, etc.)

Definition

Let's define colormap as a mapping from the unit interval to RGB space (Color32).

Within this unit interval, there are at least two "anchor" points, for $t=0$ and $t=1$.
There can be more anchors at distinct $t$.

Interpolation

The colormap interpolates between the anchor points. The interpolation can be specified as one of:

• RGB
• HSL / HSV / HSB
• CIELAB
• LCH
• OKLab / OKLCH

Exploration with chatgpt.

Sampling

These can be either "finite" to cycle through the colormap, or "infinite", covering the unit interval.

The finite case $N$ can simply go through the unit interval in round-robin fashion: $t=(i \mod N / N)$

The "infinite" case can use

• Sobol / Kronecker/ Van der Corput sequence. Exploration with chatgpt

Principal uses

1. Heatmaps

One has to first normalize the input data to unit interval to get the color. This normalization will be typically linear or logarithmic, for on a given segment (for min/max over displayed data).

For coloring values (i.e. the heatmap implementation), one has to normalize the input data to unit interval before getting the color.

2. Plot item colors

We use the sampling algorithm here and get a color via a next call.

Colormap API

• new with vec of Color32 anchor points -- make them uniformly distributed. At least 2 points! Makes sampling to be finite N by default.
• new_with_positions allow pass vec of [Color32, t=f32] values. Check ordering, and boundary points! Makes sampling to be
• with_interpolation - set
• with_sampling - specify
• get(&self, t: f32) -> Color32:
• next(&mut self, id: egui::Id) -> Color32: - use an internal counter to get the next color, by using specified sampling. Use the passed id to make sure the assigned colors are stable.

Integration

Specify colormap in the Plot builder. Do not require plot lines/points to specify colors, but they can override them.

Demo

Allow changing the color maps and sampling, show both a plot with some lines/points (left), and a heatmap (right).

[kitizz]

Happy to start work on this! Feel free to assign it to me

[kitizz]

Something I think missing from the initial design notes:
There needs to be a story for including the colormap "weight" value in the point data. Two general approaches that come to mind:

1. Add a new member to PlotPoint

pub struct PlotPoint {
    pub x: f64,

    pub y: f64,

    // ColorMap sample point.
    pub c: f64,
}

Could be Option if that that's preferred. But c==0.0 by default doesn't seem too controversial to me.

Advantages:

• Easy addition
• All point-level data lives in the same place

Disadvantages:

• Potential bloat-creep in the PlotPoint struct

2. Add a parallel PlotPointMeta struct

If there are plans to add much more metadata that a user can optionally attach to a point, perhaps it makes sense to break it out into its own struct.

Advantages:

• PlotPoint stays lightweight

Disadvantages:

• Introduces a whole surface area of user-sourced bugs than can only be caught at runtime (eg. PlotPoint and PlotPointMeta vecs out of sync)

Recommendation

I strongly prefer (1). It will need benchmarking, but I predict the performance implications will be negligible. And it is otherwise a much easier API for users, and much easier for devs to maintain.

[michalsustr]

Interesting idea with the weights!

Just to be sure we have the same understanding, the idea behind weights is to make a single line "colorful" as in the gradient line fill in the demo (lines demo), correct? So basically allow to express the "z-coordinate" through color. This could be useful for things like iso-lines (contour) projection like this matplotlib example.

Some things to consider:

1. How will this show up as a single PlotItem (Line) color in e.g. legend?
2. What should be the precise mathematical definition? Just $c = t$ and use the "global" colormap? Or maybe we should provide a custom colormap per line here?

I think 1. for now is preferable. Even better is #222

[kitizz]

Your understanding is correct. It's fairly in-line with the python plotting libraries I'm familiar with (matplotlib, plotly, bokeh). Tying the color of the line/points to a specific x, y is overly restrictive and doesn't allow a line to cross over itself with a different color. It is very common to have measured values attached to a spatial point (eg. depth in an image, temperature in a room).

How will this show up as a single PlotItem (Line) color in e.g. legend?

Oooh, good point! Two options that come to mind:

• apply the colormap gradient to the legend icon (only if this is relatively cheap to do)
• use the median weight value to sample the colormap

What should be the precise mathematical definition?

IMO, the plot item (or a higher-level colormap wrapper) should have a cmin and cmax range that maps to [0, 1]. This would be aligned with other plotting tools I'm used to. We could future proof that with an enum that could allow non-linear maps, which would be extremely handy for certain kinds of data without needing to redefine the ColorMap itself.

enum WeightMap {  // Terrible name! But I'll sit here for 15min if I don't just choose something 😁
    Linear{min: f32, max: f32},
    Log{min: f32, max: f32},
    Cubic{min: f32, max: f32, slope:: f32},  // I dunno, just making up examples. Kind of like cubic_in_out for animations.
}

Asking the user to ensure c = t ∈ [0, 1] is certainly a viable option. My preference for "WeightMap" comes from the fact that egui and egui_plot are so good at removing friction from building functional and good-looking tools. Asking the user to map their point values to [0, 1] feels like a point of friction. And I suspect that calculating (c - cmin)/(cmax - cmin) at draw-time will have negligible performance impact.

[kitizz]

Before I start work on this, I'd like to nail down one or two exemplar code snippets that we'd like the user to be able to write.

Here's one based on the discussion so far (I'm not attached to it):

let points: Vec<PlotPoint> = my_data.iter().map(|data| PlotPoint{x: data.x, y: data.y, c: data.temp}).collect();
let colormap = ColorMap::magma();
let weightmap = WeightMap::linear(-10.0, 35.0);  // Because celsius 😋
let line = Line::new("temperature", PlotPoints::Owned(points)).colormap(colormap, weightmap);

[michalsustr]

apply the colormap gradient to the legend icon (only if this is relatively cheap to do)

We could probably render some gradient in a tiny rectangle. But not supported now.

For start, just using t=0.5 middle point is IMO good enough (so this issue doesn't grow too big), this can be sprinkled with magic dust later. :)

the plot item (or a higher-level colormap wrapper) should have a cmin and cmax range that maps to [0, 1]. This would be aligned with other plotting tools I'm used to.

Agreed, and if user provides values outside the interval, they will be cropped to 0 or 1 respectively.

How about rather than WeightMap we pass a normalization function made in a factory? Then we don't need to deal with enums.

// in a egui_plot/norm.rs
pub fn clamped_min_max(cmin: f64, cmax: f64) -> impl Fn(f64) -> f64 {
    let (min, max) = if cmin <= cmax {
        (cmin, cmax)
    } else {
        (cmax, cmin)
    };

    // Avoid division by zero
    if min == max {
        return move |_| 0.0;
    }

    move |c| {
        if c <= min {
            0.0
        } else if c >= max {
            1.0
        } else {
            (c - min) / (max - min)
        }
    }
}

// Example
let points: Vec<PlotPoint> = my_data.iter().map(|data| PlotPoint{x: data.x, y: data.y, c: data.temp}).collect();
let colormap = ColorMap::magma();
let line = Line::new("temperature", PlotPoints::Owned(points)).color_map(colormap).color_norm(norm::clamped_min_max(-10., 35.));

Also, I would just make color_norm=clamped_min_max by default, so no need to specify it.

[kitizz]

How about rather than WeightMap we pass a normalization function made in a factory?

Gah, yes, way better.

I'm assuming, then, that c_min and c_max are by default calculated from the data points? Then maybe needs another builder function for .color_range(c_min, c_max) to override that.

Otherwise, that all sounds good to me ☺️

Might take me a week to get around to something presentable

[michalsustr]

Ah yes, I forgot building the function itself :D Updated the example. And yes, would be calculated from the data points by default.

Great, looking forward!