load_colormap

Synopsis

Create a colormap for images from arrays or a file.

load_colormap(r, g, b [,slot])
load_colormap(r, g, b, alpha [,slot])
load_colormap(img [,slot])
load_colormap(filename [,slot])

Description

ChIPS comes pre-loaded with a set of standard colormaps; see the colormap section of "ahelp chipsopt". The load_colormap command allows the user to load their own colormap files for displaying images.

The colormap determines how a pixel's value is converted into a color. It is used by an image and any associated colorbar. The user specifies values in a colormap table, then ChIPS takes the values associated with the image and maps them to that table. If there are more colors in the image than in the table - or vice versa - it will linearly interpolate between table elements to find an appropriate color.

Using arrays or an image to define the color table

The colormap can also be created directly. The load_colormap() routine accepts either one- or two-dimensional arrays - either Python on NumPy - and uses them to create the table. Values should be in the range 0 to 1, inclusive; any values outside this range will result in an error.

chips> r = [0, 1]
chips> g = [0, 1]
chips> b = [1, 0]
chips> load_colormap(r, g, b)

creates a colormap that varies from blue - the first row has red=0, green=0, blue=1 - to yellow (red=1, green=1, blue=0). This can also be given as a 2D array - e.g.

chips> rgb = np.asarray([[0, 0, 1], [1, 1, 0]])
chips> load_colormap(rgb)

A fourth column gives the alpha value (if not given a value of 1 is assumed for each row); so for example the following two arrays use the same colors as the XImtool example below; the first (rgb) is fully opaque whereas the second (rgba) sets the transparancy to 0.6 for each color.

chips> rgb = np.asarray([[0,0,0], [1,0,0], [0,1,0], [0,0,1], [1,1,1]])
chips> rgba = np.asarray([[0,0,0,0.6], [1,0,0,0.6], [0,1,0,0.6],
[0,0,1,0.6], [1,1,1,0.6]])

External color tables

ChIPS is compatible with both DS9 and XImtool formats, and supports alpha channels in both. The SAOimage Color Mapping page has a detailed description of ds9 colormaps. In the ds9.SAO format, alpha channel can be specified by adding an "ALPHA" entry to the map and specifying ranges in the same manner as they're specified for the other colors. For XImtool lookup map format, alpha can be added by simply adding a fourth column to the map.

Example ds9 format colormap

unix% cat rgba.sao

PSEUDOCOLOR
RED:
(0,1)(.33,1)(.33,0)(1,0)
GREEN:
(0,0)(.33,0)(.33,1)(.66,1)(.66,0)(1,0)
BLUE:
(0,0)(.66,0)(.66,1)(1,1)
ALPHA:
(0,0)(.1,.75)(.5,.9)(.9,1)

which can be loaded by saying

chips> load_colormap('rgba.sao', chips_usercmap2)

Example XImtool lookup table colormap

unix% cat rgb.lut 

0 0 0 1
1 0 0 1
0 1 0 1
0 0 1 1
1 1 1 1

which can be loaded by saying

chips> load_colormap('rgb.lut', chips_usercmap3)

Changing the colormap for a single slot

Loading a colormap into a particular slot, such as chips_usercmap1, will only change the display of any images created after the load_colormap call. To change any existing images, call set_image to re-set the 'colormap' field. As an example:

chips> add_image(np.arange(12).reshape(4,3))
chips> set_plot_aspect_ratio('fit')
chips> set_image(['colormap', chips_usercmap1])
chips> load_colormap([0,1],[1,0.5],[0.2,0.8])

At this point the image does not use the new colormap; to do so say:

chips> set_image(['colormap', chips_usercmap1])

Interpolation

The default behavior is to interpolate between the colors in the table, so that a colormap can be defined with just two elements. This interpolation can be turned off by changing the 'colormap_interpolation' setting of the image to False. The number of colors used for the interpolation is controlled by the image's 'colormap_size' setting. See "ahelp set_image" for more information.

Examples

Example 1

chips> add_image(np.arange(25).reshape(5,5))
chips> r = np.asarray([254, 252, 250, 247, 197, 122])
chips> g = np.asarray([235, 197, 159, 104, 27, 1])
chips> b = np.asarray([226, 192, 181, 161, 138, 119])
chips> load_colormap(r/255.0, g/255.0, b/255.0)
chips> set_image(["colormap", "usercmap1"])
chips> add_colorbar(0.5, 1.05)

Here we use the 'RDPu' 6-class sequential color scheme from Color Brewer and load it into the default user color map slot ("usercmap1" or chips_usercmap1).

Since these color schemes are intended to visualize discrete sets we can turn off the interpolation scheme by saying:

chips> set_image(['colormap_interpolate', False])

Example 2

This example shows an implementation of the CubeHelix color scheme from A colour scheme for the display of astronomical intensity images and then a recreation of their Figure 1.

rots = -1.5
start = 0.5
hue = 1.0
gamma = 1.0
nlev = 256
index = np.arange(nlev, dtype=np.float32)
fract = index / (nlev-1)
angle = 2 * np.pi * (start/3.0 + 1 + rots * fract)
fract = fract**gamma
amp = hue * fract * (1-fract) / 2.0
cosa = np.cos(angle)
sina = np.sin(angle)
r = fract + amp * (-0.14861*cosa + 1.78277*sina)
g = fract + amp * (-0.29227*cosa -0.90649*sina)
b = fract + amp * 1.97294 * cosa
r = np.clip(r, 0, 1)
g = np.clip(g, 0, 1)
b = np.clip(b, 0, 1)

With the above commands, the three arrays can be used to set the colormap by saying:

load_colormap(r, g, b)

and then, to create Figure 1, we use the following commands.

set_preferences(['curve.symbol.style', 'none', 'curve.line.thickness',
2])
add_window(8, 10, 'inches')
add_curve(index, r, ['*.color', 'red'])
add_curve(index, g, ['*.color', 'green'])
add_curve(index, b, ['*.color', 'blue'])
add_line(0, 0, nlev-1, 1, ['thickness', 2])
set_plot_aspect_ratio('1:1')
set_axis(['pad', 0])
set_plot_xlabel('level')
set_plot_ylabel('intensity')
add_plot(0.15, 0.05, 0.9, 0.15, ['style', 'boxed'])
add_image(index, ['depth', 50, 'colormap', 'usercmap1'])
set_data_aspect_ratio('')
limits(Y_AXIS, 0.5, 1.5)
hide_axis()

Example 3

chips> add_image("image.fits")
chips> load_colormap("rgba2.sao")
chips> set_image("colormap=usercmap1")

Add an image. Load colormap "rgba2.sao" into the default slot (usercmap1); set the image to use that colormap.

Example 4

chips> load_colormap("/data/cmap.lut", chips_usercmap2)
chips> add_image("img2.fits", "colormap=usercmap2")

Load a colormap into the second user slot, chips_usercmap2. Specify in the add_image command that that colormap should be used.

How to choose a look-up table

Usefuls resource for look-up tables include Cynthia Brewer's Color Brewer web site and the Cube Helix color scheme by Dave Green. For a general discussion on problems with some color schemes see Why Should Engineers and Scientists Be Worried About Color? and Dear NASA: No More Rainbow Color Scales, Please.

Changes in CIAO 4.7

The load_colormap command will now raise an error if any value for the red, green, blue, or alpha channels is invalid; that is if it lies outside the range 0 to 1.

Bugs

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.

See Also

contrib

chips_helix, imextent

images

add_image, current_image, delete_image, display_image, get_image, hide_image, print_image, remove_image_channel, set_image, shuffle_image