48. gui.colorscale — Mapping numerical values into colors.

This module contains some definitions useful in the mapping of numerical values into colors. This is typically used to provide a visual representation of numerical values (e.g. a temperature plot). See the ‘postproc’ plugin for some applications in the representation of results from Finite Element simulation programs.

• ColorScale: maps scalar float values into colors.

• ColorLegend: subdivides a ColorScale into a number of subranges (which are graphically represented by the pyformex.opengl.decors.ColorLegend class).

• Palette: a dict with some predefined palettes that can be used to create ColorScale instances. The values in the dict are tuples of three colors, the middle one possibly being None (see ColorScale initialization for more details). The keys are strings that can be used in the ColorScale initialization instead of the corresponding value. Currently, the following palettes are defined: ‘RAINBOW’, ‘IRAINBOW’, ‘HOT’, ‘RGB’, ‘BGR’, RWB’, ‘BWR’, ‘RWG’, ‘GWR’, ‘GWB’, ‘BWG’, ‘BW’, ‘WB’, ‘PLASMA’, ‘VIRIDIS’, ‘INFERNO’, ‘MAGMA’.

48.1. Classes defined in module gui.colorscale

class gui.colorscale.ColorScale(palet='RAINBOW', minval=0.0, maxval=1.0, midval=None, exp=1.0, exp2=None)

Mapping floating point values into colors.

The ColorScale maps a range of float values minval..maxval or minval..midval..maxval into the corresponding color from the specified palette.

Parameters:

• palet: the color palette to be used. It is either a string or a tuple of three colors. If a string, is should be one of the keys of the colorscale.Palette dict (see above). The full list of available strings can be seen in the ColorScale example. If a tuple of three colors, the middle one may be specified as None, in which case it will be set to the mean value of the two other colors. Each color is a tuple of 3 float values, corresponding to the RGB components of the color. Although OpenGL RGB values are limited to the range 0.0 to 1.0, it is perfectly legal to specify color component values outside this range here. OpenGL will however clip the resulting colors to the 0..1 range. This feature can effectively be used to construct color ranges displaying a wider variation of colors. for example, the built in ‘RAINBOW’ palette has a value ((-2., 0., 2.), (0., 2., 0.), (2., 0., -2.)). After clipping these will correspond to the colors blue, yellow, red respecively.

• minval: float: the minimum value of the scalar range. This value and all lower values will be mapped to the first color of the palette.

• maxval: float: the maximum value of the scalar range. This value and all higher values will be mapped to the last (third) color of the palette.

• midval: float: a value in the scalar range that will correspond to the middle color of the palette. It defaults to the mean value of minval and maxval. It can be specified to allow unequal scaling of both subranges of the scalar values. This is often used to set a middle value 0.0 when the values can have both negative and positive values but with rather different maximum values in both directions.

• exp, exp2: float: exponent to allow non-linear mapping. The defaults provide a linear mapping between numerical values and colors, or rather a bilinear mapping if the (midval,middle color) is not a linear combination of the endpoint mappings. Still, there are cases where the user wants a nonlinear mapping, e.g. to have more visual accuracy in the higher or lower (absolute) values of the (sub)range(s). Therefore, the values are first linearly scaled to the -1..1 range, and then mapped through the nonlinear function arraytools.stuur(). The effect is that with both exp > 1.0, more colors are used in the neighbourhood of the lowest value, while with exp < 1.0, more colors are use around the highest value. When both exp and exp2, the first one holds for the upper halfrange, the second for the lower one. Setting both values > 1.0 thus has the effect of using more colors around the midval.

See example: ColorScale

scale(val)

Scale a value to the range -1…1.

Parameters:

• val: float: numerical value to be scaled.

If the ColorScale has only one exponent, values in the range self.minval..self.maxval are scaled to the range -1..+1.

If two exponents were specified, scaling is done independently in the intervals minval..midval and midval..maxval, mapped resp. using exp2 and exp onto the intervals -1..0 and 0..1.

color(val)

Return the color representing a value val.

Parameters:

• val: float: numerical value to be scaled.

The returned color is a tuple of three float RGB values. Values may be out of the range 0..1 if any of the palette defining colors is.

The resulting color is obtained by first scaling the value to the -1..1 range using the scale method, and then using that result to linearly interpolate between the color values of the palette.

class gui.colorscale.ColorLegend(colorscale, n)

A colorlegend divides a ColorScale in a number of subranges.

Parameters:

• colorscale: a ColorScale instance

• n: a positive integer

For a ColorScale without midval, the full range is divided in n subranges; for a scale with midval, each of the two ranges is divided in n/2 subranges. In each case the legend has n subranges limited by n+1 values. The n colors of the legend correspond to the middle value of each subrange.

See also opengl.decors.ColorLegend.

overflow(oflow=None)

Raise a runtime error if oflow is None, else return oflow.

color(val)

Return the color representing a value val.

The color is that of the subrange holding the value. If the value matches a subrange limit, the lower range color is returned. If the value falls outside the colorscale range, a runtime error is raised, unless the corresponding underflowcolor or overflowcolor attribute has been set, in which case this attirbute is returned. Though these attributes can be set to any not None value, it will usually be set to some color value, that will be used to show overflow values. The returned color is a tuple of three RGB values in the range 0-1.