# coyote: CGCOLOR

- coyote/Graphics
- [Source code]

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 <http://colorbrewer2.org/>`.
      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 <http://www.idlcoyote.com/documents/programs.php>`
      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 <http://www.sron.nl/~pault/>`. 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.
          Ran into an ATV image that was less than 5 pixels on a side! More fooling around to avoid calling
               cgSnapshot when it might fail. 29 March 2016. DWF.
          Don't call cgSnapshot on X-windows when there is no backing store (Retain = 2) as this often
               yields spurious results.     12 Oct 2016 W. Landsman

Copyright

      Copyright (c) 2009-2016, 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.