Color specification formats

It is possible to use named colors and other color specification formats in place of color index values when setting various types of color resources. There are four different types of resources for setting single or arrays of color values: NhlTColorIndex, NhlTColorIndexGenArray, NhlTColorMap, and NhlTColorDefinitionGenArray. Setting color values for each of these types of resources is covered below.

For complete examples showing how to use named colors, see the Quick Start Guide examples cn05, cn14, cn17, xy07, and xy16.

NhlTColorIndex

The accepted formats for a color resource of type NhlTColorIndex are:

n an integer color index
"(/x,y,z/)"
(/x,y,z/) an RGB triplet with values from 0.0 to 1.0 inclusive
"color_name" a color name (from the last column in rgb.txt)
"enumerated_name" one of the strings "transparent", "background", or "foreground"

For example, if you want to set the font color for the main title (tiMainFontColor), and color index 2 is red, you can set it by using any one of the following calls from an NCL script:

    "tiMainFontColor" : 2
    "tiMainFontColor" : "red"
    "tiMainFontColor" : "(/1.,0.,0./)"
    "tiMainFontColor" : (/1.,0.,0./)

In an HLU C program, you would use one of the following lines:

    NhlRLSetInteger(srlist,NhlNtiMainFontColor,2);
    NhlRLSetString(srlist,NhlNtiMainFontColor,"(/1.,0.,0./)");
    NhlRLSetString(srlist,NhlNtiMainFontColor,"red");

and in a resource file you would use (note the lack of double quotes):

    *tiMainFontColor : 2
    *tiMainFontColor : red
    *tiMainFontColor : (/1.,0.,0./)

NhlTColorIndexGenArray
The accepted format for a resource of type NhlTColorIndexGenArray is an array of NhlTColorIndex elements. You can mix different color specification types, but if you do this, each type must be enclosed in double quotes.
For example, if you want to set the fill colors for various contour levels (resource cnFillColors), and your color map is defined as follows:
```
(/(/1.,1.,1./),(/0.,0.,0./),(/1.,0.,0./),(/0.,1.,0./),(/0.,0.,1./),\
  (/0.,1.,1./),(/1.,0.,1./),(/1.,1.,0./)/)
```
(which translates to white, black, red, green, blue, cyan, magenta, and yellow) then either of the two NCL code settings will produce identical results:
```
    "cnFillColors" : (/2,3,4,5,6,7,-1/)
    "cnFillColors" : (/"(/1.,0.,0./)","(/0.,1.,0./)","blue","(/0.,1.,1./)",\
                       "(/1.,0.,1./)","yellow","transparent"/)
```

NhlTColorMap

The accepted formats for a resource of type NhlTColorMap are:

(/(/x1,y1,z1/),(/x2,y2,z2/),...,(/xn,yn,zn/)/) a 2-dimensional (n x 3) array of RGB triplets with values from 0.0 to 1.0 inclusive
"(/x,y,z/)"
"color_name"
a 1-dimensional array of any combination of these strings
"color_map_name" a single string with a color map name (see the "Color tables" section for a list of the valid names)

Here's an NCL example of how to define a color map (resource wkColorMap) using a combination of the different formats described above:

wks = create "x11" xWorkstationClass defaultapp
  "wkColorMap" : (/"(/0.0,0.0,0.0/)","(/1.0,1.0,1.0/)","(/1.0,0.0,0.0/)",\
                   "(/0.7,0.1,1.0/)","(/0.2,1.0,0.1/)","(/1.0,1.0,0.2/)",\
                   "(/0.3,0.4,0.8/)","(/0.4,0.5,0.9/)","(/0.5,0.8,0.9/)",\
                   "HotPink","DeepSkyBlue","YellowGreen","Grey56"/)
end create

Note that you can mix color specification types, but you must enclose each one in double quotes when you mix them. The above color map could have also been specified with the following code segment:

wks = create "x11" xWorkstationClass defaultapp
  "wkColorMap" : (/"white","black","red","(/0.7,0.1,1.0/)",\
                   "(/0.2,1.0,0.1/)","(/1.0,1.0,0.2/)","(/0.3,0.4,0.8/)",\
                   "(/0.4,0.5,0.9/)","(/0.5,0.8,0.9/)","HotPink",\
                   "DeepSkyBlue","YellowGreen","Grey56"/)
end create

or with pure RGB values (no quotes are needed here because there are no named colors being referenced):

wks = create "x11" xWorkstationClass defaultapp
  "wkColorMap" : (/(/0.000,0.000,0.000/),(/1.000,1.000,1.000/),\
                   (/1.000,0.000,0.000/),(/0.700,0.100,1.000/),\
                   (/0.200,1.000,0.100/),(/1.000,1.000,0.200/),\
                   (/0.300,0.400,0.800/),(/0.400,0.500,0.900/),\
                   (/0.500,0.800,0.900/),(/1.000,0.412,0.706/),\
                   (/0.000,0.749,1.000/),(/0.604,0.804,0.196/),\
                   (/0.561,0.561,0.561/)/)
end create

The RGB values for "HotPink", "DeepSkyBlue", "YellowGreen", and "Grey56" were calculated from the file $NCARG_ROOT/lib/ncarg/database/rgb.txt, which contains integer RGB values for each named color. To convert these integer values to float values that range from 0.0 to 1.0, divide each one by 255.

NhlTColorDefinitionGenArray
The accepted formats for a resource of type NhlTColorDefinitionGenArray are:

"(/x,y,z/)"
(/x,y,z/) an RGB triplet with values from 0.0 to 1.0 inclusive
"color_name" a color name (from the last column in rgb.txt)

For example, to set the resources wkBackgroundColor and wkForegroundColor to white and black respectively, you might use one of the following types of NCL code snippets:
```
wks = create "x11" xWorkstationClass defaultapp
  "wkBackgroundColor" : "white"
  "wkForegroundColor" : "black"
end create
```
or
```
wks = create "x11" xWorkstationClass defaultapp
  "wkBackgroundColor" : (/1.,1.,1./)
  "wkForegroundColor" : (/0.,0.,0./)
end create
```

Important notes about color specification formats

When you access a color by anything other than an integer index value, the current color map is searched for the closest match to that color. This means that if you access a color that doesn't have a close match in your color map, you may not get the color you are expecting.

If you create two workstations each with a different colormap, and then set up one or more plots using named colors, then when you call the procedure for changing the workstation and redraw the plots, the colors may not come out as you expected in the second workstation. For an example, try running the following NCL script:

begin
  wks1 = create "wks1" xWorkstationClass defaultapp
    "wkColorMap" : (/"white","black","blue","red","green"/)
  end create

  wks2 = create "wks2" xWorkstationClass defaultapp
    "wkColorMap" : (/"white","black","red","green","blue"/)
  end create

  text = create "text" textItemClass wks1
    "txString"    : "hello, world"
    "txFontColor" : "blue"
  end create

  draw(text)
  frame(wks1)
  NhlChangeWorkstation(text,wks2)
  draw(text)
  frame(wks2)
end

In the second workstation, the text should be red instead of blue, because in the second color map, red is occupying the same location in the color map that blue occupied for the first color map. To get around this problem, you need to make sure that named colors occupy the same locations in the color maps, or else you have to call setvalues on text and set txFontColor to "blue" again.

Tables of named colors

To see the valid 650 named colors, see the ASCII file $NCARG_ROOT/lib/ncarg/database/rgb.txt or click on any one of the 15 tables below to see the color names and their associated colors:

MIT copyright

****************************************************************************
        Copyright    Massachusetts Institute of Technology    1985

Permission to use, copy, modify, distribute, and sell this software
and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of M.I.T. not be used in
advertising or publicity pertaining to distribution of the software
without specific, written prior permission.  M.I.T. makes no
representations about the suitability of this software for any
purpose.  It is provided "as is" without express or implied warranty.
****************************************************************************

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?

$Revision: 1.4 $ $Date: 1999/04/28 16:42:06 $

n	an integer color index
"(/x,y,z/)" (/x,y,z/)	an RGB triplet with values from 0.0 to 1.0 inclusive
"color_name"	a color name (from the last column in rgb.txt)
"enumerated_name"	one of the strings "transparent", "background", or "foreground"

(/(/x1,y1,z1/),(/x2,y2,z2/),...,(/xn,yn,zn/)/)	a 2-dimensional (n x 3) array of RGB triplets with values from 0.0 to 1.0 inclusive
"(/x,y,z/)" "color_name"	a 1-dimensional array of any combination of these strings
"color_map_name"	a single string with a color map name (see the "Color tables" section for a list of the valid names)