Skip to content

Colormaps ​

A colormap turns a value into a colour: a heatmap colours each cell of a field with it, a field image a whole field on a linear, log or symlog scale, and its colour bar (ip_colormap_scale) shows the scale. FIGURE bundles the maps that scientific plotting has settled on (matplotlib's, cmocean's, ParaView's Cool to Warm, Fabio Crameri's), knows ImPlot's own, and loads the user's from a CSV table or a ParaView preset. All of them are chosen by name, reversed or cut into discrete bands. Contour lines take their colours from a colormap too, each level the colour of its value.

Four windows of vertical colour bars, each labelled with its colormap's name. Sequential: cividis, inferno, magma, batlow, thermal, haline, deep, turbo. Diverging: cool-warm, balance, curl, vik, roma. Cyclic: romaO, whose two ends have the same colour. Below, ImPlot's own sixteen: the qualitative Deep, Dark, Pastel and Paired in separate blocks of colour, then Viridis, Plasma, Hot, Cool, Pink, Jet, Twilight, RdBu, BrBG, PiYG, Spectral and Greys.
docs/examples/src/gallery.F90 (run with colormaps): every colormap FIGURE knows, from ip_colormap_names

Procedures ​

ProcedureNotes
ip_colormap(name [, levels] [, stat]) → integer(int32)the ImPlot id of the map name, for the colormap argument of ip_heatmap, ip_field_image, ip_colormap_scale and the legends; <name>_r reversed, levels discrete bands; -1 on a failure
ip_load_colormap(name, file [, stat])read a map from a CSV table or a ParaView JSON preset and register it as name
ip_colormap_names(names)the names ip_colormap knows, character(len=:), allocatable :: names(:)
ig_gradient_edit(id, colormap [, width] [, height] [, stat]) → logicala gradient editor of the map named colormap: its stops dragged, added, recoloured, removed; .true. on the frame the map changed (Editing a colormap)
ip_colormap_stops(name, positions, colours [, stat])the map's stops in order of position, real(real64), allocatable :: positions(:), colours(:,:): positions(k) in [0, 1], colours(3, k) the RGB of stop k, in [0, 1]; both of size 0 on a failure (Editing a colormap)
fortran
cmap = ip_colormap('vik', levels=10_int32)      ! diverging, ten bands: zero sits between two of them
if (ip_begin_plot('vorticity', width=300.0_real64, height=300.0_real64)) then
   call ip_heatmap('w', w, 0.0_real64, 1.0_real64, 0.0_real64, 1.0_real64, scale_min=-1.0_real64, &
                   scale_max=1.0_real64, colormap=cmap)
   call ip_end_plot()
endif
call ig_same_line()
call ip_colormap_scale('##w', -1.0_real64, 1.0_real64, height=300.0_real64, colormap=cmap)

A recipe for this: Colour a field with a map by name, reversed or in bands.

Names. Names are case-sensitive: the bundled maps are in lower case ('cividis', 'cool-warm', and Crameri's 'romaO'), ImPlot's own keep ImPlot's names ('Viridis', 'Jet'; the constants ImPlotColormap_* are their ids), a loaded map keeps the name it was given. So 'deep' is cmocean's sequential map and 'Deep' ImPlot's qualitative one. ip_colormap_names lists the bundled maps (alphabetical), then ImPlot's sixteen (in ImPlot's order), then the loaded ones (in load order); reversed and discrete maps are not listed.

fortran
call ip_colormap_names(names)
write(output_unit, '(I0,A)') size(names), ' colormaps, the first ones:'
write(output_unit, '(*(A,:,", "))') (trim(names(i)), i = 1, 6)

Registration. A map is registered with ImPlot (AddColormap) at its first use: ip_colormap called again with the same name and levels returns the same id. ImPlot keeps its colormaps for the life of its context and cannot replace one, so an id holds until app%destroy; after a new init* the maps are registered again at their next use, possibly under other ids. Ask ip_colormap every frame (the lookup is cheap) rather than keeping an id across an app%destroy. A map keeps its id when its colours are edited.

The default. ip_heatmap and ip_colormap_scale without colormap use ImPlot's Viridis, perceptually uniform: not ImPlot's current colormap, which holds the style's line colours. An id that is not registered (-1, a stale one) is refused with FIG_ERR_ARGUMENT.

Changed in v0.3.0

Up to v0.2.0, heatmaps and the colour scale without colormap took ImPlot's current colormap: with FIGURE's styles, the style's line colours, a few distinct hues that do not order values. From v0.3.0 they default to Viridis, so a heatmap drawn by v0.2.0 code changes colours. Code that wants a given map passes it: colormap=ip_colormap('Viridis'), or any other name.

The bundled maps ​

Each is a table of 256 RGB samples, embedded in the library at build time.

KindNameFrom
sequentialcividismatplotlib; designed for colour-vision deficiency (Nuñez, Anderton and Renslow)
sequentialinferno, magmamatplotlib (Smith and van der Walt)
sequentialbatlowCrameri's Scientific colour maps
sequentialthermal, haline, deepcmocean (Thyng): temperature, salinity, depth
sequentialturboGoogle (Mikhailov), through matplotlib: a rainbow, smoother than Jet but not uniform
divergingcool-warmMoreland's table of ParaView's "Cool to Warm"
divergingbalance, curlcmocean
divergingvik, romaCrameri's Scientific colour maps
cyclicromaOCrameri's Scientific colour maps: the two ends meet

ImPlot's own are Viridis, Plasma, Hot, Cool, Pink, Jet, Twilight (cyclic), Greys; the diverging RdBu, BrBG, PiYG and Spectral; and the qualitative Deep, Dark, Pastel and Paired, which are lists of distinct colours for categories, not scales.

How to choose ​

  • A quantity from low to high (temperature, density, a residual's magnitude): a sequential map. cividis, batlow, inferno, magma and Viridis change lightness evenly from one end to the other, so equal steps of value look like equal steps of colour, and they keep their order in greyscale and for the common colour-vision deficiencies.
  • A quantity with a meaningful zero or reference (vorticity, a velocity component, a difference from a baseline): a diverging map, with the reference at its centre: give scale_min = -scale_max. cool-warm, balance, vik.
  • An angle or a phase (wind direction, the phase of a wave): a cyclic map, whose ends meet, so that 359° and 1° look alike: romaO, Twilight.
  • Categories (zones, materials, the rank that owns a cell): a qualitative map with levels equal to the number of categories, or Deep.

The Scientific colour maps page of Fabio Crameri and the cmocean documentation discuss each map's use.

Why not Jet ​

Two plots of the same smooth bump, a Gaussian peak centred near (0.45, 0.55). On the left, in Jet, the bump shows a sharp cyan ring and a bright yellow ring around a red core, although the field has no edges. On the right, in cividis, the same bump brightens smoothly from dark blue to yellow, with no rings.
docs/examples/src/gallery.F90 (run with jet): one smooth field in Jet and in cividis

Jet (and other rainbows) changes lightness unevenly: it is darkest at its blue end, brightest in its yellow and cyan bands, darker again at the red end. The eye reads lightness as value, so a smooth field shows bands and edges where the data have none (the rings above), and the highest values look darker than those below them. Printed in greyscale, or seen with a red-green deficiency, the order of the colours is lost. Jet stays available ('Jet', for comparison with older pictures); FIGURE never uses it by default.

Discrete levels ​

levels cuts the map into that many bands of equal width, each with the map's colour at the band's centre, and no blending between them (ImPlot's qualitative kind): a heatmap then shows its contours as the edges between bands, and the colour bar shows the bands. levels is in [2, 256]. A diverging map with an even number of levels puts its reference value on an edge between two bands, with an odd number in the middle of one. Bands of a qualitative map (Deep) take its colours in order.

Reversed and discrete maps are registered under derived names: '<name>_r' and '<name>|<levels>'.

A colour-scale legend ​

ProcedureNotes
ip_colormap_legend(id, colormap, vmin, vmax [, levels] [, horizontal] [, width] [, height] [, label_format] [, scale] [, stat])A bar coloured by colormap from vmin to vmax, with ticks and their values: vertical (vmin at the bottom, values on the right) or horizontal=.true. (vmin at the left, values below); the ticks on scale (Scales).
ip_colormap_legend_edit(id, colormap, vmin, vmax [, ...as above]) → logicalThe same legend, whose range the user changes: dragged along the bar, zoomed by the wheel; vmin and vmax updated in place, .true. on the frame they change (Fields).
fortran
if (ip_begin_plot('pressure', width=560.0_real64, height=420.0_real64, equal=.true.)) then
   call ip_setup_axes('x', 'y')
   call ip_heatmap('##p', p, -1.0_real64 - 0.5_real64 * h, 1.0_real64 + 0.5_real64 * h, -1.0_real64 - 0.5_real64 * h, &
                   1.0_real64 + 0.5_real64 * h, scale_min=-1.0_real64, scale_max=1.0_real64,                          &
                   colormap=ip_colormap('balance', levels=8_int32))
   call ip_contour('p', p, -1.0_real64, 1.0_real64, -1.0_real64, 1.0_real64, levels=[-0.5_real64, 0.0_real64, &
                   0.5_real64], color=line_color)
   call ip_end_plot()
endif
call ig_same_line()
call ip_colormap_legend('p levels', ip_colormap('balance'), -1.0_real64, 1.0_real64, levels=8_int32, &
                        height=420.0_real64)                    ! the bands of the heatmap, their edges labelled
call ig_text('the same map, continuous, horizontal:')
call ip_colormap_legend('p continuous', ip_colormap('balance'), -1.0_real64, 1.0_real64, horizontal=.true., &
                        width=560.0_real64, label_format='%.1f')
A field drawn in eight bands of a diverging map from blue to red, with yellow contour lines at -0.5, 0 and 0.5; on its right a vertical legend of the same eight bands, their edges labelled -1, -0.75, ... 1; below, a horizontal continuous legend of the same map, labelled -1.0, -0.5, 0.0, 0.5, 1.0; above, the colour editor's picker open on a yellow
docs/examples/src/cb_legend.F90
  • An item of the window, not of a plot: put it beside a plot (ig_same_line), above or below it, in a side bar, in any window. id tells legends of one window apart and is not shown.
  • Discrete levels. With levels, the bar has that many bands of equal width, each the map's colour at its centre: the colours a heatmap drawn with ip_colormap(name, levels) takes (Discrete levels); the ticks mark the bands' edges. Without levels, the bar is continuous and the ticks fall on round values (steps of 1, 2, 2.5 or 5 times a power of ten), about every 40 pixels (100 when horizontal). Pass the continuous map's id with levels, as the example does: the bands are computed from it.
  • The scale runs from vmin to vmax, the values a heatmap's scale_min and scale_max map to the colormap's ends; vmin > vmax turns it over.
  • Sizes [pixels]: positive, given; negative, the space left in the window; absent, the default: vertical, 300 long and as wide as the bar (a field's height) and the longest label; horizontal, the space left and as tall as the bar and a line of labels. label_format is a C printf format (default '%g'; '' is the default too). A format with a conversion is checked: it must be one of a real (Formats); a format without one is text, printed as it is on every tick.
  • Band edges are labelled with their values. With levels, an edge's label takes the digits it needs to show the edge's value: label_format's precision is raised until the number printed is the edge (to 6 decimals for %f, as a contour line's label of ip_contour; 7 significant digits for %e and %g). With '%.0f' and bands of 87.5, the edges read 87.5 beside contour lines labelled 87.5, not 88; round edges keep the format's digits ('%.0f': 100). The text around the number is kept ('%.0f K'). A format with no f, e or g conversion is used as it is. The continuous bar's ticks, at round values, use label_format unchanged.
  • Bands and the bar sit on whole pixels, so neighbouring bands share their edge with no seam.
  • The scale (scale, 'linear' by default, 'log', 'symlog') places the ticks where a field drawn by ip_field_image with the same scale puts the values' colours (Scales). The bar's colours do not change: the colormap runs evenly along it, its values do not.
  • Unlike ip_colormap_scale (ImPlot's ColormapScale, vertical only, continuous colours), the legend is horizontal or vertical and shows discrete levels as bands.
  • Statuses: FIG_ERR_ARGUMENT for a colormap that is not registered, vmin equal to vmax or either not finite, either <= 0 on 'log', an unknown scale, levels outside [2, 256], a label_format with a conversion that is not one of a real ('%d', '%s', '%*f', '%lf', '%n', '%f %f'); FIG_ERR_STATE outside a frame and from a task.
  • Modes: the same in window, headless and remote mode.

Scales ​

A colormap orders colours from 0 to 1; a scale says which value goes where. ip_field_image and the legends take the same three, those of a plot axis:

ScaleA value v goes to the fractionFor
'linear'(v - vmin) / (vmax - vmin)most quantities
'log'(log10 v - log10 vmin) / (log10 vmax - log10 vmin)positive quantities over decades: a density, a residual, a spectrum's power. Values <= 0 have no place: a field shows them in its NaN colour; vmin and vmax must be above 0
'symlog'the same with s(v) = 2 asinh(v/2) (ImPlot's symmetric log): linear near 0, logarithmic beyond about ±2signed quantities over decades: vorticity, a pressure coefficient, a difference between two runs. With a diverging map and vmin = -vmax, 0 sits in the middle

On the legend, a log scale has its ticks at the decades (1, 10, 100; 2 and 5 times them too when the range holds fewer than two decades), a symlog scale at 0 and the signed decades; ticks too close for their labels are thinned (0 kept first, then the decades of largest magnitude, then the others). With levels, the band edges are equally spaced in the scale: on 'log' from 1 to 1000 in three bands, 1, 10, 100, 1000. The scale is in the units of the values: data spanning 1e-12 to 1e-9 on 'symlog' looks linear, since symlog's linear part reaches ±2 (scale the data first).

fortran
if (ip_begin_plot('density', 700.0_real64, 440.0_real64, equal=.true.)) then
   call ip_setup_axes('x [m]', 'y [m]')
   call ip_field_image('rho', rho, 0.0_real64, 4.0_real64, 0.0_real64, 3.0_real64, colormap=ip_colormap('inferno'), &
                       vmin=vmin, vmax=vmax, scale='log', changed=step)
   call ip_end_plot()
endif
call ig_same_line()
if (ip_colormap_legend_edit('rho legend', ip_colormap('inferno'), vmin, vmax, height=440.0_real64, &
                            scale='log', label_format='%g kg/m3')) then
   ! vmin and vmax changed: the next ip_field_image colours the field again
endif
if (ig_button('reset range')) then
   vmin = 0.1_real64
   vmax = 100.0_real64
endif
Four fields, each with its legend on the same scale: linear, two Gaussian bumps in cividis from 0 to 1.2; log, a density from 0.1 to 100 in inferno, the legend at the decades; symlog, a signed vorticity from -100 to 100 in balance, the legend at 0 and the signed decades; and a flow past a disc in vik, the disc of NaN values in grey.
docs/examples/src/gallery.F90 (run with field_scales)

User maps ​

fortran
open(newunit=u, file='ocean.csv', status='replace', action='write') ! a user map: r, g, b rows in [0, 255]
write(u, '(A)') '# deep to shallow', '8,29,88', '37,52,148', '34,94,168', '29,145,192', '65,182,196', '161,218,180'
close(u)
call ip_load_colormap('ocean', 'ocean.csv', stat=stat)
if (stat /= FIG_OK) write(output_unit, '(A)') figure_last_error()
fortran
if (ip_begin_plot('depth', width=300.0_real64, height=300.0_real64)) then
   call ip_heatmap('d', abs(w), 0.0_real64, 1.0_real64, 0.0_real64, 1.0_real64, colormap=ip_colormap('ocean_r'))
   call ip_end_plot()
endif

ip_load_colormap(name, file [, stat]) reads one of two formats, told apart by the first character of the file ([ or {: JSON):

  • A CSV table: one colour a row, r, g, b, separated by commas, semicolons, blanks or tabs. Components are in [0, 1], or in [0, 255] when one of them exceeds 1. # starts a comment, and a first line that is not numeric is a header (skipped). With four numbers a row, x, r, g, b, the first is the position of the colour (non-decreasing), and the map is resampled linearly to 256 uniform positions. From 2 to 65536 rows; the rows are the map's colours, first at the bottom of the scale.
  • A ParaView preset in JSON, as ParaView's "Export" of presets writes it (an array of presets) or one preset: the preset whose Name is name, or the only one. Its RGBPoints (x, r, g, b, ...) are sampled at 256 uniform positions over their range, interpolated in its ColorSpace as ParaView does: RGB, Lab (Lab/CIEDE2000 is interpolated in Lab), Diverging (Moreland's method), HSV (the shorter way round the hue circle) or Step (each colour up to the next point).

A loaded map is kept for the program's life, across app%destroy and a new init*, and may be loaded before init*. Its name must be new: neither a map ip_colormap knows nor the reverse of one (ImPlot cannot replace a colormap), not empty, without |, and not starting with 'FIGURE ' (the prefix of the style's own line colours).

What is not read. From a ParaView preset, only Name, ColorSpace and RGBPoints: the colour of NaNs, the opacity points, the annotations and an indexed preset (IndexedColors, refused) are not. A \u escape in a JSON string is read as ?.

Editing a colormap ​

docs/examples/src/cb_gradient.F90

ig_gradient_edit(id, colormap) is a widget of the current window that edits a map by its stops: colours at positions in [0, 1], the map linear between them. It is ImGuizmo's ImGradient (vendored, with FIGURE's patch, THIRD_PARTY.md) with FIGURE's strip of the map above it.

fortran
if (ig_gradient_edit('stops', 'cool-warm', width=-90.0_real64)) text = 'cool-warm changed' ! the field follows
call ig_same_line()
if (ig_button('Save')) then
   call save('cool-warm', 'my-cool-warm.csv')
   text = 'saved to my-cool-warm.csv'
endif
if (ip_begin_plot('pressure', width=480.0_real64, height=440.0_real64, equal=.true.)) then
   call ip_setup_axes('x', 'y')
   call ip_field_image('p', p, -1.0_real64, 1.0_real64, -1.0_real64, 1.0_real64, colormap=ip_colormap('cool-warm'), &
                       vmin=-1.0_real64, vmax=1.0_real64)
   call ip_end_plot()
endif
call ig_same_line()
call ip_colormap_legend('p', ip_colormap('cool-warm'), -1.0_real64, 1.0_real64, height=440.0_real64)
The mouseDoes
drag a stop's squaremoves the stop along the strip (it may pass others: the map takes the stops in order of position)
double click on the stops' rowadds a stop there, of the map's colour at that point
click a stopselects it: its colour button and Remove appear on the right
the colour buttonDear ImGui's colour picker for the stop
Removeremoves the stop (a map keeps two)
  • Each change resamples the map from its stops, constant before the first and after the last: its table (256 colours for a bundled or loaded map; the keys of one of ImPlot's own) and every variant registered (<name>_r, ip_colormap(name, levels)). Heatmaps, fields, legends and 3-D views drawn with the map show the new colours from the frame of the change on; fields and views are coloured again (their textures are cached by the map's colours too). The result is .true. on that frame.
  • The stops of a map not edited yet come from its colours: every key of a short table (ImPlot's own maps, a CSV of up to 16 rows); for a table of 256, some of its colours, each the farthest from the last between which the map is linear within 2 levels of 0-255 per channel: 10 to 21 stops for the bundled maps (cool-warm: 13; turbo: 21). So the first change also moves the map's colours by at most 2 levels where the user did not touch it.
  • An edit lasts for the program's life: a new init* registers the map again with its edited colours. Save it with ip_colormap_stops, as a CSV of x, r, g, b rows, which ip_load_colormap reads back as the same map:
fortran
subroutine save(name, file)
!< The map's stops as a CSV table of `x, r, g, b` rows, which `ip_load_colormap` reads back as the same map.
character(len=*), intent(in) :: name          !< Colormap.
character(len=*), intent(in) :: file          !< CSV file.
real(real64), allocatable    :: positions(:)  !< Stops: positions in [0, 1].
real(real64), allocatable    :: colours(:,:)  !< ... their colours, RGB in [0, 1].
integer(int32)               :: u, k          !< Unit, counter.

call ip_colormap_stops(name, positions, colours)
open(newunit=u, file=file, status='replace', action='write')
write(u, '(A)') 'x, r, g, b'
do k = 1_int32, size(positions, kind=int32)
   write(u, '(F9.6,3(", ",F9.6))') positions(k), colours(:, k)
enddo
close(u)
endsubroutine save
text
$ ./cb_gradient --test
cool-warm: 13 stops
its middle stop at  0.604, colour 0.950 0.791 0.711
dragged by 3% of the row, now at  0.633
after a double click: 14 stops
saved and read back: within 0 of 255 per channel
  • Which maps. Any continuous map: bundled, ImPlot's own, loaded. Not a reversed one (<name>_r: edit <name>, the reverse follows), not a qualitative one (Deep, Dark, Pastel, Paired: lists of colours, no gradient).
  • Sizes [pixels]: width positive given, else the space left plus it (default 0: all of it); height the strip and the stops' row together (default two rows of a frame). The selected stop's controls take the right end.
  • Statuses: FIG_ERR_ARGUMENT for an unknown name, a reversed or qualitative map; FIG_ERR_STATE outside a frame (for ip_colormap_stops: before init*) and from a task. The same in window, headless and remote mode.

Statuses and modes ​

StatusWhen
FIG_ERR_ARGUMENTip_colormap: an unknown name, levels outside [2, 256]; ip_load_colormap: a malformed file (the message gives the line), a name taken or not allowed, a preset name not in a file of several; ip_heatmap, ip_colormap_scale: a colormap id that is not registered; ig_gradient_edit, ip_colormap_stops: an unknown name, a reversed or qualitative map
FIG_ERR_FAILEDip_load_colormap: the file cannot be read
FIG_ERR_STATEip_colormap, ip_colormap_stops before init*, ig_gradient_edit outside a frame; any of them from a task

stat is optional: absent, a failure stops the program with the message (error stop); present, it receives the status, and figure_last_error the message (Error handling).

fortran
cmap = ip_colormap('jet', stat=stat)                ! names are case-sensitive: ImPlot's is 'Jet'
if (stat /= FIG_OK) write(output_unit, '(A)') figure_last_error()
text
$ ./cb_colormap
30 colormaps, the first ones:
balance, batlow, cividis, cool-warm, curl, deep
ip_colormap: unknown colormap 'jet' (ip_colormap_names lists them)

Modes. The same in window, headless and remote mode: the colours are computed by the program, and the remote client receives the drawn cells.

Memory. ImPlot expands a continuous map of 256 colours into a lookup table of 65026 entries, about 254 KiB per map registered (a discrete map: its levels only). Registered at their first use, maps the program never asks for cost nothing.

Licences ​

The bundled tables keep their upstream licences, all permissive: CC0 and the matplotlib licence (cividis, inferno, magma, turbo; turbo also Apache-2.0), MIT (cmocean, Crameri's), BSD-3-Clause (ParaView's Cool to Warm). The licence files are installed under share/licenses/ and must travel with a program built with FIGURE; THIRD_PARTY.md gives each source, its version and what a distribution must carry. The tables are written by scripts/gen_colormaps.py from the pinned sources.

Released under the MIT licence.