NAME: FSC_COLOR PURPOSE: 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 88 color names and values are supplied from the program. These were obtained from the file rgb.txt, found on most X-Window distributions. Representative colors were chose from across the color spectrum. To see a list of colors available, type: Print, FSC_Color(/Names), Format='(6A15)'. AUTHOR: FANNING SOFTWARE CONSULTING: David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: davidf@dfanning.com Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Graphics, Color Specification. CALLING SEQUENCE: color = FSC_COLOR(theColor, theColorIndex) NORMAL CALLING SEQUENCE FOR DEVICE-INDEPENDENT COLOR: If you write your graphics code *exactly* as it is written below, then the same code will work in all graphics devices I have tested. These include the PRINTER, PS, and Z devices, as well as X, WIN, and MAC. In practice, graphics code is seldom written like this. (For a variety of reasons, but laziness is high on the list.) So I have made the program reasonably tolerant of poor programming practices. I just point this out as a place you might return to before you write me a nice note saying my program "doesn't work". :-) axisColor = FSC_COLOR("Green", !D.Table_Size-2) backColor = FSC_COLOR("Charcoal", !D.Table_Size-3) dataColor = FSC_COLOR("Yellow", !D.Table_Size-4) thisDevice = !D.Name Set_Plot, 'toWhateverYourDeviceIsGoingToBe', /Copy Device, .... ; Whatever you need here to set things up properly. IF (!D.Flags AND 256) EQ 0 THEN $ POLYFILL, [0,1,1,0,0], [0,0,1,1,0], /Normal, Color=backColor Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData, $ NoErase= ((!D.Flags AND 256) EQ 0) OPlot, Findgen(11), Color=dataColor Device, .... ; Whatever you need here to wrap things up properly. Set_Plot, thisDevice OPTIONAL INPUT PARAMETERS: theColor: A string with the "name" of the color. To see a list of the color names available set the NAMES keyword. This may also be a vector of color names. Colors available are these: Almond Antique White Aquamarine Beige Bisque Black Blue Blue Violet Brown Burlywood Charcoal Chartreuse Chocolate Coral Cornsilk Cyan Dark Goldenrod Dark Gray Dark Green Dark Khaki Dark Orchid Dark Salmon Deep Pink Dodger Blue Firebrick Forest Green Gold Goldenrod Gray Green Green Yellow Honeydew Hot Pink Indian Red Ivory Khaki Lavender Lawn Green Light Coral Light Cyan Light Gray Light Salmon 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 Sienna Sky Blue Slate Gray Snow Spring Green Steel Blue Tan Thistle Tomato Turquoise Violet Violet Red Wheat White Yellow Also, these system color names are available in IDL 5.6 and higher: Frame, Text, Active, Shadow, Highlight, Edge, Selected, Face. The color WHITE is used if this parameter is absent or a color name is mis-spelled. To see a list of the color names available in the program, type this: Print, FSC_COLOR(/Names), Format='(6A15)' theColorIndex: The color table index (or vector of indices the same length as the color name vector) where the specified color is loaded. The color table index parameter should always be used if you wish to obtain a color value in a color-decomposition-independent way in your code. See the NORMAL CALLING SEQUENCE for details. If theColor is a vector, and theColorIndex is a scalar, then the colors will be loaded starting at theColorIndex. RETURN VALUE: The value that is returned by FSC_COLOR depends upon the keywords used to call it, on the version of IDL you are using,and on the depth of the display device when the program is invoked. In general, the return value will be either a color index number where the specified color is loaded by the program, or a 24-bit color value that can be decomposed into the specified color on true-color systems. (Or a vector of such numbers.) If you are running IDL 5.2 or higher, the program will determine which return value to use, based on the color decomposition state at the time the program is called. If you are running a version of IDL before IDL 5.2, then the program will return the color index number. This behavior can be overruled in all versions of IDL by setting the DECOMPOSED keyword. If this keyword is 0, the program always returns a color index number. If the keyword is 1, the program always returns a 24-bit color value. If the TRIPLE keyword is set, the program always returns the color triple, no matter what the current decomposition state or the value of the DECOMPOSED keyword. Normally, the color triple is returned as a 1 by 3 column vector. This is appropriate for loading into a color index with TVLCT: IDL> TVLCT, FSC_Color('Yellow', /Triple), !P.Color But sometimes (e.g, in object graphics applications) you want the color returned as a row vector. In this case, you should set the ROW keyword as well as the TRIPLE keyword: viewobj= Obj_New('IDLgrView', Color=FSC_Color('charcoal', /Triple, /Row)) If the ALLCOLORS keyword is used, then instead of a single value, modified as described above, then all the color values are returned in an array. In other words, the return value will be either an NCOLORS-element vector of color table index numbers, an NCOLORS-element vector of 24-bit color values, or an NCOLORS-by-3 array of color triples. If the NAMES keyword is set, the program returns a vector of color names known to the program. If the color index parameter is not used, and a 24-bit value is not being returned, then colorIndex is typically set to !D.Table_Size-1. However, this behavior is changed on 8-bit devices (e.g., the PostScript device, or the Z-graphics buffer) and on 24-bit devices that are *not* using decomposed color. On these devices, the colors are loaded at an offset of !D.Table_Size - ncolors - 2, and the color index parameter reflects the actual index of the color where it will be loaded. This makes it possible to use a formulation as below: Plot, data, Color=FSC_Color('Dodger Blue') on 24-bit displays *and* in PostScript output! Note that if you specify a color index (the safest thing to do), then it will always be honored. INPUT KEYWORD PARAMETERS: ALLCOLORS: Set this keyword to return indices, or 24-bit values, or color triples, for all the known colors, instead of for a single color. DECOMPOSED: 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. FILENAME: The string 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: If this keyword is set, the return value of the function is a ncolors-element 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. listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16) ROW: 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: Set this keyword if you would like to select the color name with the PICKCOLORNAME program. Selecting this keyword automaticallys sets the INDEX positional parameter. If this keyword is used, any keywords appropriate for PICKCOLORNAME can also be used. If this keyword is used, the first positional parameter can be either a color name or the color table index number. The program will figure out what you want. TRIPLE: 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. In addition, any keyword parameter appropriate for PICKCOLORNAME can be used. These include BOTTOM, COLUMNS, GROUP_LEADER, INDEX, and TITLE. OUTPUT KEYWORD PARAMETERS: CANCEL: 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 PICKCOLORNAME. COLORSTRUCTURE: 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. NCOLORS: The number of colors recognized by the program. It will be 88 by default. COMMON BLOCKS: None. SIDE EFFECTS: None. ADDITIONAL PROGRAMS REQUIRED: PICKCOLORNAME: This file can be found in the Coyote Library: http://www.dfanning.com/programs/pickcolorname.pro EXAMPLE: To get drawing colors in a device-decomposed independent way: axisColor = FSC_COLOR("Green", !D.Table_Size-2) backColor = FSC_COLOR("Charcoal", !D.Table_Size-3) dataColor = FSC_COLOR("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=FSC_Color('Charcoal', /Triple)) To change the viewport color later: theView->SetProperty, Color=FSC_Color('Antique White', /Triple) To load the drawing colors "red", "green", and "yellow" at indices 100-102, type this: IDL> TVLCT, FSC_Color(["red", "green", and "yellow"], /Triple), 100 MODIFICATION HISTORY: Written by: David W. Fanning, 19 October 2000. Based on previous GetColor program. Fixed a problem with loading colors with TVLCT on a PRINTER device. 13 Mar 2001. DWF. Added the ROW keyword. 30 March 2001. DWF. Added the PICKCOLORNAME code to the file, since I keep forgetting to give it to people. 15 August 2001. DWF. Added ability to specify color names and indices as vectors. 5 Nov 2002. DWF. Fixed a problem with the TRIPLE keyword when specifying a vector of color names. 14 Feb 2003. DWF. Fixed a small problem with the starting index when specifying ALLCOLORS. 24 March 2003. DWF. Added system color names. 23 Jan 2004. DWF Added work-around for WHERE function "feature" when theColor is a one-element array. 22 July 2004. DWF. Added support for 8-bit graphics devices when color index is not specified. 25 August 2004. DWF. Fixed a small problem with creating color structure when ALLCOLORS keyword is set. 26 August 2004. DWF. Extended the color index fix for 8-bit graphics devices on 25 August 2004 to 24-bit devices running with color decomposition OFF. I've concluded most of the people using IDL don't have any idea how color works, so I am trying to make it VERY simple, and yet still maintain the power of this program. So now, in general, for most simple plots, you don't have to use the colorindex parameter and you still have a very good chance of getting what you expect in a device-independent manner. Of course, it would be *nice* if you could use that 24-bit display you paid all that money for, but I understand your reluctance. :-) 11 October 2004. DWF. Have renamed the first positional parameter so that this variable doesn't change while the program is running. 7 December 2004. DWF. Fixed an error I introduced on 7 December 2004. Sigh... 7 January 2005. DWF.