.\

cgcolor.pro

Graphics

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.

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()

Author information

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

Copyright

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.

top cgColor

result = cgColor( [theColour] [, colorIndex] [, /ALLCOLORS] [, /BREWER] [, /CHECK_CONNECTION] [, COLORSTRUCTURE=structure] [, /CANCEL] [, /DECOMPOSED] [, FILENAME=string] [, NAMES=boolian] [, NCOLORS=integer] [, /NODISPLAY] [, /ROW] [, /SELECTCOLOR] [, /TRIPLE] [, _REF_EXTRA=_REF_EXTRA])

The purpose of this function is to obtain drawing colors by name and in a device and color model independent way.

Return value

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.

Parameters

theColour optional required 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

  Black   Charcoal   Crimson   Dark Orchid   Edge   Goldenrod   Hot Pink   Light Coral   Lime Green   Moccasin   Orchid   Plum   Royal Blue   Selected   Snow   Thistle   White

TAN1 BLK1 GRN1 BLU1 ORG1 RED1 PUR1 PBG1 YGB1 RYB1 TG1

 color of the pixel Otherwise, this The color OPPOSITE

the color names available set the NAMES keyword. Colors available are these: class="code-output">  Active            Almond     Antique White        Aquamarine             Beige            Bisque Blue       Blue Violet             Brown         Burlywood        Cadet Blue Chartreuse         Chocolate             Coral   Cornflower Blue          Cornsilk Cyan    Dark Goldenrod         Dark Gray        Dark Green        Dark Khaki Dark Red       Dark Salmon   Dark Slate Blue         Deep Pink       Dodger Blue Face         Firebrick      Forest Green             Frame              Gold Gray             Green      Green Yellow         Highlight          Honeydew Indian Red             Ivory             Khaki          Lavender        Lawn Green Light Cyan        Light Gray      Light Salmon   Light Sea Green      Light Yellow Linen           Magenta            Maroon       Medium Gray     Medium Orchid Navy             Olive        Olive Drab            Orange        Orange Red Pale Goldenrod        Pale Green            Papaya              Peru              Pink Powder Blue            Purple               Red              Rose        Rosy Brown Saddle Brown            Salmon       Sandy Brown         Sea Green          Seashell Shadow            Sienna          Sky Blue        Slate Blue        Slate Gray Spring Green        Steel Blue               Tan              Teal              Text Tomato         Turquoise            Violet        Violet Red             Wheat Yellow Here are the Brewer color names: class="code-output">  WT1        WT2       WT3       WT4       WT5       WT6       WT7       WT8 TAN2      TAN3      TAN4      TAN5      TAN6      TAN7      TAN8 BLK2      BLK3      BLK4      BLK5      BLK6      BLK7      BLK8 GRN2      GRN3      GRN4      GRN5      GRN6      GRN7      GRN8 BLU2      BLU3      BLU4      BLU5      BLU6      BLU7      BLU8 ORG2      ORG3      ORG4      ORG5      ORG6      ORG7      ORG8 RED2      RED3      RED4      RED5      RED6      RED7      RED8 PUR2      PUR3      PUR4      PUR5      PUR6      PUR7      PUR8 PBG2      PBG3      PBG4      PBG5      PBG6      PBG7      PBG8 YGB2      YGB3      YGB4      YGB5      YGB6      YGB7      YGB8 RYB2      RYB3      RYB4      RYB5      RYB6      RYB7      RYB8 TG2       TG3       TG4       TG5       TG6       TG7       TG8 Here are color names for colors appropriate for color blind users: class="code-output">  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 in the upper-right corner of the display, if a window is open. color is "black" in PostScript and "white" everywhere else. 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.



              
              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.



              
              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.



              
              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.


      

      
        File attributes

        
          
            Modification date:
            Fri Mar 27 11:07:37 2015
          

          
            Lines:
            942
          

          
          
            Docformat:
            rst rst

Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015

.\