NCL Website header
NCL Home > Documentation > Graphics > Graphical Interfaces


Chooses a color index for a scalar value, given a color map and a range of values.

Available in version 6.2.0 and later.


load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"

	function get_color_index (
		color_map  ,           
		levels [*] : numeric,  
		value  [1] : numeric   

	return_val [1] :  integer



An NCL predefined color map (like "rainbow", "BlueRed", "matlab_jet"), an RGB array, or an RGBA array.


An array of monotonically increasing numeric values of which to compare the scalar value to.


A scalar value that you want to calculate the appropriate color index for, based on the given levels.

Return value

A scalar integer index into the given color map.


This function uses the same spanning algorithm that NCL uses to choose colors for a filled contour or vector plot, given a particular color map and an array of levels. It uses the number of levels you have to create a "nice" span across the color map such that it starts at the very first color and ends at the very last color, using close to equal spacing. It determines which range the given scalar value falls in, and calculates the appropriate color index to return.

Here's what the return color indexes mean, given n values in levels:

color index 0 : value < levels(0)
color index 1 : levels(0) ≤ value < levels(1)
color index 2 : levels(1) ≤ value < levels(2)
color index n-1 : levels(n-2) ≤ value < levels(n-1)
color index n : levels(n-1) > value

The color index value returned will start at 2 or 0, depending on whether you give it a predefined color map or an array of RGB/RGBA values. If you give it a predefined color map, then the first two indexes, 0 and 1, are not considered, and the index value will start at 2. If you give it an RGB/RGBA array, then it assumes you want to start at the first index (index 0).

The color index values will always end at clen-1, where clen is the number of colors in the given color map.

If you want to get the full array of color index values based on a set of levels, use span_color_indexes.

If you want the RGB or RGBA value returned rather than the color index value, use get_color_rgba.

See Also

span_color_indexes, span_color_rgba, get_color_rgba, span_named_colors


Example 1

Example 2