Colormap builder

A simple tool to create custom colormaps for matplotlib.

---

Here, we present the basic usage of the library and the installation instructions. For additional information, check the project's documentation for more detailed information about the library. Especially the examples gallery with tutorials for using this library.

Usage

Matplotlib allows creating different types colormaps using the ListedColormap or LinearSegmentedColormap classes. However, they are either limited in scope (ListedColormap or LinearSegmentedColormap.from_list) or require defining the mapping for each primary color (r,g,b).

The cmap_builder.build_cmap() function exposes a simple interface to create complex colormaps simply by specifying the colors at different points across the color scale. This approach defining colormaps was inspired mainly by the legs module in the domutils package.

The colormap definition required by build_cmap is a list of (data value, color, [next_color]) tuples like the following:

cmap_def = [
    (x0, color_0, [next_color_0])  # next_color_0 ignored if provided.
    (x1, color_1, [next_color_1])
    ...
    (xi, color_i, [next_color_i])
    ..
    (xn, color_n, [next_color_n])  # next_color_n is ignored if provided.
]

where color_i represents the color immediately before the xi the data value. The optional next_color_i entry can specify the color immediately after the xi data value. This allows creating color maps with sharp color transitions. Here, the xi values are not restricted to the [0,1] interval in the matplotlib tools. Instead, any data interval is supported for the xi. Hence, we can use the same units as the data we want to plot, making the definition of colormaps easier.

Example

For example, the following code creates a colormap that:

• From 0 to 2 varies from dark to light green.
• From 2, 4 varies from dark to light purple.
• From 4-8 varying from dark to light orange.
• From 8-9 varies from dark to light yellow.
• From 9-10 varies from dark to light green.

from cmap_builder import build_cmap
cmap_def = [
    # (value, color)
    (0, "red_dark"),
    (2, "red_light", "orange_light"),
    (4, "orange_dark", "blue_light"),
    (8, "blue_dark", "purple_light"),
    (9, "purple_dark", "green_light"),
    (10, "green_dark"),
]

my_cmap, my_ticks, my_norm = build_cmap(
    "my_colormap", # Name of the colormap
    cmap_def, # Colormap definition
    uniform=True, 
    N=700,  # color palette quantization levels.
)

# uniform=True creates a norm that maps the input values to equally 
# spaced color segments 

For more information, check the project's example gallery containing tutorials for using this library.

Installation

You can install the package directly from GitHub using:

pip install git+https://github.com/aperezhortal/cmap_builder.git

Alternatively, you can install the package from the source by cloning the project and then running:

pip install .  # Regular installation
# or 
pip install -e .  # Install in development mode]()