coyote: CGCOLOR

Description
The purpose of this function is to obtain drawing colors
by name and in a device/decomposition independent way.
The color names and values may be read in as a file, or 192 color
names and values are supplied with the program. These colors were
obtained from the file rgb.txt, found on most X-Window distributions,
and from colors in the `Brewer color tables `.
Representative colors were chosen from across the color spectrum. 
If the color names '0', '1', '2', ..., '255' are used, they will
correspond to the colors in the current color table in effect at
the time the `cgColor` program is called.
Please note that all Coyote Graphics routines use cgColor internally to specify
their colors in a color-model independent way. It is not necessary to call
cgColor yourself unless you are using it with a traditional IDL command (e.g., Plot).
For example::
    Plot, data, Color=cgColor('dodger blue')
But, it is not needed with Coyote Graphics commands::
    cgPlot, data, Color='dodger blue'
The program requires the `Coyote Library `
to be installed on your machine.
Categories
Graphics
Examples
To get drawing colors in a device-decomposed independent way::
    axisColor = cgColor("Green", !D.Table_Size-2)
    backColor = cgColor("Charcoal", !D.Table_Size-3)
    dataColor = cgColor("Yellow", !D.Table_Size-4)
    Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
    OPlot, Findgen(11), Color=dataColor
To set the viewport color in object graphics::
    theView = Obj_New('IDLgrView', Color=cgColor('Charcoal', /Triple))
To change the viewport color later::
    theView->SetProperty, Color=cgColor('Antique White', /Triple)
To load the drawing colors "red", "green", and "yellow" at indices 100-102, type this::
    IDL> TVLCT, cgColor(["red", "green", "yellow"], /Triple), 100
To interactively choose a color, set the SELECTCOLOR keyword::
    IDL> color = cgColor(/SelectColor)
The cgPickColorName program is a good way to learn the names of the colors available::
    IDL> color = cgPickColorName()
image:: cgpickcolorname.png
Author
FANNING SOFTWARE CONSULTING::
   David W. Fanning 
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: david@idlcoyote.com
   Coyote's Guide to IDL Programming: http://www.idlcoyote.com
History
Change History::
   Written by: David W. Fanning
   Modified FSC_COLOR to create cgColor 9 February 2011. DWF.
   Modified to allow a three-element color triple to be used in place of the color
      name parameter. This allows one user-defined color to be used. 4 Dec 2011. DWF.
   Modified to allow byte and 16-bit integer values to be used to specify colors
      in the current color table. 5 Dec 2011. DWF.
   Modified to allow the "opposite" pixel to be determined in the Z-graphics buffer. 24 Dec 2011. DWF.
   Modified the code to handle long integers depending on the current color mode and the
       number of values passed in. 10 January 2012. DWF.
   Made sure the return values are BYTES not INTEGERS, in cases where this is expected. 10 Jan 2012. DWF.
   Added "Background" as a color name. The opposite of "Opposite". 1 Feb 2012. DWF.
   When returning a vector of color values, now making sure to return a byte array if 
        in indexed color mode. 27 Feb 2012. DWF.
   Added Compile Opt id2 to all file modules. 22 July 2012. DWF.
   Added "opposite" and "background" colors to Brewer colors. 14 August 2012. DWF.
   Some versions of IDL report the size of widget windows incorrectly, so instead of
         sampling the very top-right pixel, I now back off a little. 1 Nov 2012. DWF.
   For numerical values less than 256, in indexed color state, I now return the values
         directly to the user. This should significantly speed up many Coyote Graphics
         processes. 14 December 2012. DWF.
   Removed cgColor_Color24 module in favor of using Coyote Library routine cgColor24. 5 Jan 2013. DWF.
   The keyword ROW was being ignored if multiple colors were specified with TRIPLE keyword. Fixed. 10 July 2013. DWF.
   Another fix to handle Windows 8 computers that report their window size incorrectly. 21 Oct 2013. DWF.
   Added 12 colors suggested by Paul Krummel for people with color blindness. See the last line in 
         Figure 3 of `this reference `. 16 Jan 2015. DWF.
   Getting reports that Mac computers are now reporting inaccurate draw widget sizes (similar to Windows
         computers). So, I changed the algorithm for picking the "opposite" or "background" color.
         Previously, I read the color from the open graphics window. Now, I only do that if you ask for
         the "OPPOSITE" or "BACKGROUND" color. Otherwise, I assume the background color is "white". If you 
         do ask for the color, I read the open graphics window at a location 5 pixels removed from what
         is "supposed" to be the upper-right corner of the window (often reported incorrectly). If I have
         any problems reading this pixel, I report the background color as "white". 27 Feb 2015. DWF.
Copyright
Copyright (c) 2009-2015, Fanning Software Consulting, Inc.
purpose of this function is to obtain drawing colors
ame and in a device and color model independent way.
Returns
The return value depends on the color mode in effect at the time
the program is called and which keyword is used with the program.
In normal operation, if the graphics device is using indexed color
mode, the program will load a color at a unique (or specified)
index and return that index number. If the graphics device is using
decomposed color mode, the program will create a 24-bit color value
that can be used to specify the particular color desired. In this
case, no color is loaded in the color table. This is the preferred
mode for working with colors in IDL.
Params
theColour: required, optional, type=varies
    Normally the name of the color desired. However, this can also be
    a string index number (e.g., '215') or a byte or short integer
    value (e.g, 215B or 215S). If this is the case, the color
    in the current color table at this index number is used for the 
    color that is returned. The value may also be a vector of color names. 
    The color may also be a three-element byte or integer array specifying a 
    user-defined color triple. Only one color triple is allowed.
    To see a list of the color names available set the NAMES keyword. Colors available are these::
       Active            Almond     Antique White        Aquamarine             Beige            Bisque
       Black               Blue       Blue Violet             Brown         Burlywood        Cadet Blue
       Charcoal       Chartreuse         Chocolate             Coral   Cornflower Blue          Cornsilk
       Crimson              Cyan    Dark Goldenrod         Dark Gray        Dark Green        Dark Khaki
       Dark Orchid      Dark Red       Dark Salmon   Dark Slate Blue         Deep Pink       Dodger Blue
       Edge                 Face         Firebrick      Forest Green             Frame              Gold
       Goldenrod            Gray             Green      Green Yellow         Highlight          Honeydew
       Hot Pink       Indian Red             Ivory             Khaki          Lavender        Lawn Green
       Light Coral    Light Cyan        Light Gray      Light Salmon   Light Sea Green      Light Yellow
       Lime Green          Linen           Magenta            Maroon       Medium Gray     Medium Orchid
       Moccasin             Navy             Olive        Olive Drab            Orange        Orange Red
       Orchid     Pale Goldenrod        Pale Green            Papaya              Peru              Pink
       Plum          Powder Blue            Purple               Red              Rose        Rosy Brown
       Royal Blue   Saddle Brown            Salmon       Sandy Brown         Sea Green          Seashell
       Selected           Shadow            Sienna          Sky Blue        Slate Blue        Slate Gray
       Snow         Spring Green        Steel Blue               Tan              Teal              Text
       Thistle            Tomato         Turquoise            Violet        Violet Red             Wheat
       White              Yellow
    Here are the Brewer color names::
       WT1        WT2       WT3       WT4       WT5       WT6       WT7       WT8
       TAN1      TAN2      TAN3      TAN4      TAN5      TAN6      TAN7      TAN8
       BLK1      BLK2      BLK3      BLK4      BLK5      BLK6      BLK7      BLK8
       GRN1      GRN2      GRN3      GRN4      GRN5      GRN6      GRN7      GRN8
       BLU1      BLU2      BLU3      BLU4      BLU5      BLU6      BLU7      BLU8
       ORG1      ORG2      ORG3      ORG4      ORG5      ORG6      ORG7      ORG8
       RED1      RED2      RED3      RED4      RED5      RED6      RED7      RED8
       PUR1      PUR2      PUR3      PUR4      PUR5      PUR6      PUR7      PUR8
       PBG1      PBG2      PBG3      PBG4      PBG5      PBG6      PBG7      PBG8
       YGB1      YGB2      YGB3      YGB4      YGB5      YGB6      YGB7      YGB8
       RYB1      RYB2      RYB3      RYB4      RYB5      RYB6      RYB7      RYB8
       TG1        TG2       TG3       TG4       TG5       TG6       TG7       TG8
    Here are color names for colors appropriate for color blind users::
       CG1 CG2 CG3 CG4 CG5 CG6 CG7 CG8 CG9 CG10 CG11 CG12
    The color name "OPPOSITE" is also available. It chooses a color "opposite" to the 
    color of the pixel in the upper-right corner of the display, if a window is open.
    Otherwise, this color is "black" in PostScript and "white" everywhere else.
    The color OPPOSITE is used if this parameter is absent or a color name is mis-spelled.
     The color name "BACKGROUND" can similarly be used to select the color of the pixel
     in the upper-right corner of the display, if a window is open.
colorindex: in, optional, type=byte
    The color table index where the color should be loaded. Colors are
    loaded into the color table only if using indexed color mode in the
    current graphics device. If this parameter is missing, the color will
    be loaded at a unique color index number, if necessary.
Keywords
allcolors: in, optional, type=boolean, default=0
   Set this keyword to return indices, or 24-bit values, or color
   triples, for all the known colors, instead of for a single color.
brewer: in, optional, type=boolean, default=0
   An obsolete keyword. If used, only Brewer colors are loaded into the color
   vectors internally.
cancel: out, optional, type=boolean, default=0
   This keyword is always set to 0, unless that SELECTCOLOR keyword is used.
   Then it will correspond to the value of the CANCEL output keyword in cgPickColorName.
check_connection: in, optional, type=boolean, default=0
    An obsolete keyword now completely ignored.
colorstructure: out, optional, type=structure
   This output keyword (if set to a named variable) will return a
   structure in which the fields will be the known color names (without spaces)
   and the values of the fields will be either color table index numbers or
   24-bit color values. If you have specified a vector of color names, then
   this will be a structure containing just those color names as fields.
decomposed: in, optional, type=boolean
   Set this keyword to 0 or 1 to force the return value to be
   a color table index or a 24-bit color value, respectively. This
   keyword is normally set by the color state of the current graphics device.
filename: in, optional, type=string
   The  name of an ASCII file that can be opened to read in color values and color 
   names. There should be one color per row in the file. Please be sure there are 
   no blank lines in the file. The format of each row should be::
      redValue  greenValue  blueValue  colorName
   Color values should be between 0 and 255. Any kind of white-space
   separation (blank characters, commas, or tabs) are allowed. The color
   name should be a string, but it should NOT be in quotes. A typical
   entry into the file would look like this::
      255   255   0   Yellow
names: in, optional, type=boolian, default=0
   If this keyword is set, the return value of the function is a string array 
   containing the names of the colors. These names would be appropriate, for example, 
   in building a list widget with the names of the colors. If the NAMES
   keyword is set, the COLOR and INDEX parameters are ignored.
ncolors: out, optional, type=integer
   Returns the number of colors that cgColor "knows" about. Currently ncolors=193.
nodisplay: in, optional, type=boolean, default=0
   An obsolete keyword, now totally ignored.
row: in, optional, type=boolean
   If this keyword is set, the return value of the function when the TRIPLE
   keyword is set is returned as a row vector, rather than as the default
   column vector. This is required, for example, when you are trying to
   use the return value to set the color for object graphics objects. This
   keyword is completely ignored, except when used in combination with the
   TRIPLE keyword.
selectcolor: in, optional, type=boolean
  Set this keyword if you would like to select the color name with
  the cgPickColorName program. Selecting this keyword automaticallys sets
  the INDEX positional parameter. If this keyword is used, any keywords
  appropriate for cgPickColorName can also be used. If this keyword is used,
  the first positional parameter can be a color name that will appear in
  the SelectColor box.
triple: in, optional, type=boolean
   Setting this keyword will force the return value of the function to
   always be a color triple, regardless of color decomposition state or
   visual depth of the machine. The value will be a three-element column
   vector unless the ROW keyword is also set.
_ref_extra: in, optional
   Any keyword parameter appropriate for cgPickColorName can be used.
  These include BOTTOM, COLUMNS, GROUP_LEADER, INDEX, and TITLE.