Using getcolors

Question

How do you use the vcs.getcolors function?

Answer

The VCS command vcs.getcolors linearly maps color indices over a range of color indices to a list of levels. Say we have the following list of levels. The corresponding mapping of color indices is then:

>>> levels = [-4.0, -2.0, 0.0, 2.0, 4.0, 6.0]
>>> print vcs.getcolors(levels)
[16, 127, 128, 184, 239]

The default is for getcolors to scale within the range of color indices of 16 to 239, inclusive. Sometimes it's good to avoid the first few color indices, since elements may default to those values: the default text-table, for instance, has color = 1. Color indices 240 to 255 do not change with different color maps and are not user-changable, so usually you will not scale a color range spanning those values.

The getcolors command works quite well with its default settings, but you might want more control. There are three keywords of interest: colors, split, and white. The command's docstring explanation of split is concise but a little opaque, so I give a longer explanation here.

Keyword colors is the list of all the color indices available to getcolors. Its default is set to range(16,240). The output of getcolors will span the entire list specified by keyword colors, and the first and last color index in colors will be used as the first and last elements in the output of getcolors:

>>> levels = [-4.0, -2.0, 0.0, 2.0, 4.0, 6.0]
>>> print vcs.getcolors(levels, colors=range(30,70))
[30, 49, 50, 60, 69]

Keyword split allows you to create a "split" list of color indices where the first half of the range of color indices (specified by the colors keyword) are for negative values and the second half of the range are for positive values, i.e. negative values are linearly mapped to the first half of the range of color indices and positive values are linearly mapped to the second half:

Let's look at some examples of using split:

>>> levels = [-0.3, -0.2, -0.1, 0.0, 0.1, 0.2, 0.3]
>>> print vcs.getcolors(levels, split=0)
[16, 61, 105, 150, 194, 239]
>>> print vcs.getcolors(levels, split=1)
[16, 72, 127, 128, 184, 239]
>>> print vcs.getcolors(levels, split=2)
[16, 72, 127, 128, 184, 239]

When split is 0, the linear mapping between levels and color indices uses the full range (16 to 239, inclusive) of color indices. When split is 2, negative values are linearly mapped using the first half of the indice range (16 to 127) and posative values are linearly mapped using the second half of the indice range (128 to 239). When split is 1 we get the same output as when split is 2 since levels has both positive and negative numbers.

When you have all positive levels, you get the following:

>>> levels = range(10)
>>> print vcs.getcolors(levels, split=0)
[16, 44, 72, 100, 128, 155, 183, 211, 239]
>>> print vcs.getcolors(levels, split=1)
[16, 44, 72, 100, 128, 155, 183, 211, 239]
>>> print vcs.getcolors(levels, split=2)
[128, 142, 156, 170, 184, 197, 211, 225, 239]

When you force this split, only color indices from 128 to 239 are used, since all levels are positive; split = 0 and split = 1 are identical, while split = 2 is different.

Finally, if a split is applied, and one of the intervals specified by the levels list goes through 0, that interval is set to the color index given in keyword white (default value is 240). Thus in the example below, the interval between -0.1 and 0.1 is set to 240 (for both split equal to 1 or 2 cases):

>>> levels = [-0.3, -0.2, -0.1, 0.1, 0.2, 0.3]
>>> print vcs.getcolors(levels, split=1)
[16, 127, 240, 128, 239]

The Python help command (e.g. help(vcs.getcolors)) gives some more information. Descriptions of these VCS function are also found in the Quick Start document (v1.0 has a few typos though).

---

Notes: This discussion applies to CDAT 3.3.