Changeset 133 for trunk/SRC/Colors/getcolor.pro

Timestamp:

07/07/06 11:57:27 (18 years ago)

Author:

navarro

Message:

english and nicer header (1)

Location:

trunk/SRC/Colors

Files:

• . (added)
• getcolor.pro (moved) (moved from trunk/SRC/ToBeReviewed/COULEURS/getcolor.pro) (10 diffs)

trunk/SRC/Colors/getcolor.pro

@@ -1 +1 @@
 ;+
-; NAME:
-;       GETCOLOR
-;
-; PURPOSE:
-;       The original purpose of this function was to enable the
-;       user to specify one of the 16 colors supported by the
-;       McIDAS color map by name. Over time, however, the function
-;       has become a general purpose function for handling and
-;       supporting drawing colors in a device-independent way.
-;       In particular, I have been looking for ways to write color
-;       handling code that will work transparently on both 8-bit and
-;       24-bit machines. On 24-bit machines, the code should work the
-;       same where color decomposition is turned on or off.
+;
+; @file_comments 
+; The original purpose of this function was to enable the
+; user to specify one of the 16 colors supported by the
+; McIDAS color map by name. Over time, however, the function
+; has become a general purpose function for handling and
+; supporting drawing colors in a device-independent way.
+; In particular, I have been looking for ways to write color
+; handling code that will work transparently on both 8-bit and
+; 24-bit machines. On 24-bit machines, the code should work the
+; same where color decomposition is turned on or off.
 ;
 ;       (The 16 supported colors in GETCOLOR come from the McIDAS color
 ;       table offered on the IDL newsgroup by Liam Gumley.)
 ;
-; CATEGORY:
-;       Graphics, Color Specification.
-;
-; CALLING SEQUENCE:
-;       result = GETCOLOR(color)
-;
-; OPTIONAL INPUT PARAMETERS:
-;       COLOR: A string with the "name" of the color. Valid names are:
+; @categories Graphics, Color Specification.
+;
+; @param thisColor {in}{optional} A string with the "name" of the color. Valid names are:
 ;           black
 ;           magenta
@@ -53 +46 @@
 ;           IDL 5.2 or higher.
 ;
-;       INDEX: The color table index where the specified color should be loaded.
+; @param index {in}{optional} The color table index where the specified color should be loaded.
 ;           If this parameter is passed, then the return value of the function is the
 ;           index number and not the color triple. (If color decomposition is turned
@@ -69 +62 @@
 ;           TVLCT, colors, 100
 ;
-;
-; INPUT KEYWORD PARAMETERS:
-;
-;       NAMES: If this keyword is set, the return value of the function is
+; @keyword NAMES If this keyword is set, the return value of the function is
 ;              a 16-element string array containing the names of the colors.
 ;              These names would be appropriate, for example, in building
@@ -80 +70 @@
 ;                 listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
 ;
-;       LOAD:  If this keyword is set, all 16 colors are automatically loaded
+; @keyword LOAD  If this keyword is set, all 16 colors are automatically loaded
 ;              starting at the color index specified by the START keyword.
 ;              Note that setting this keyword means that the return value of the
@@ -92 +82 @@
 ;              byte array or a long integer value.
 ;
-;       START: The starting color index number if the LOAD keyword is set. This keyword
+; @keyword START The starting color index number if the LOAD keyword is set. This keyword
 ;              value is ignored unless the LOAD keyword is also set. The keyword is also
 ;              ignored if the TRUE keyword is set or if color decomposition in on in
@@ -98 +88 @@
 ;              !D.TABLE_SIZE - 17.
 ;
-;       TRUE:  If this keyword is set, the specified color triple is returned
+; @keyword TRUE  If this keyword is set, the specified color triple is returned
 ;              as a 24-bit integer equivalent. The lowest 8 bits correspond to
 ;              the red value; the middle 8 bits to the green value; and the
@@ -105 +95 @@
 ;              were set.
 ;
-; COMMON BLOCKS:
-;       None.
-;
-; SIDE EFFECTS:
-;       None.
-;
-; RESTRICTIONS:
-;       The TRUE keyword causes the START keyword to be ignored.
+; @restrictions The TRUE keyword causes the START keyword to be ignored.
 ;       The NAMES keyword causes the COLOR, INDEX, START, and TRUE parameters to be ignored.
 ;       The COLOR parameter is ignored if the LOAD keyword is used.
@@ -119 +102 @@
 ;       returned if color decomposition is ON.
 ;
-; EXAMPLE:
-;       To load a yellow color in color index 100 and plot in yellow, type:
-;
-;          yellow = GETCOLOR('yellow', 100)
-;          PLOT, data, COLOR=yellow
+; 
+; @examples To load a yellow color in color index 100 and plot in yellow, type:
+;
+;          IDL> yellow = GETCOLOR('yellow', 100)
+;          IDL> PLOT, data, COLOR=yellow
 ;
 ;       or,
 ;
-;          PLOT, data, COLOR=GETCOLOR('yellow', 100)
+;          IDL> PLOT, data, COLOR=GETCOLOR('yellow', 100)
 ;
 ;       To do the same thing on a 24-bit color system with decomposed color on, type:
 ;
-;          PLOT, data, COLOR=GETCOLOR('yellow', /TRUE)
+;          IDL> PLOT, data, COLOR=GETCOLOR('yellow', /TRUE)
 ;
 ;       or in IDL 5.2 and higher,
 ;
-;          DEVICE, Decomposed=1
-;          PLOT, data, COLOR=GETCOLOR('yellow')
+;          IDL> DEVICE, Decomposed=1
+;          IDL> PLOT, data, COLOR=GETCOLOR('yellow')
 ;
 ;       To load all 16 colors into the current color table, starting at
 ;       color index 200, type:
 ;
-;          TVLCT, GETCOLOR(), 200
+;          IDL> TVLCT, GETCOLOR(), 200
 ;
 ;       To add the color names to a list widget:
 ;
-;           listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
+;           IDL> listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
 ;
 ;       To load all 16 colors and have the color indices returned in a structure:
 ;
-;           DEVICE, Decomposed=0
-;           colors = GetColor(/Load, Start=1)
-;           HELP, colors, /Structure
+;           IDL> DEVICE, Decomposed=0
+;           IDL> colors = GetColor(/Load, Start=1)
+;           IDL> HELP, colors, /Structure
 ;           PLOT, data, COLOR=colors.yellow
 ;
 ;       To get the direct color values as 24-bit integers in color structure fields:
 ;
-;           DEVICE, Decomposed=1
-;           colors = GetColor(/Load)
-;           PLOT, data, COLOR=colors.yellow
+;           IDL> DEVICE, Decomposed=1
+;           IDL> colors = GetColor(/Load)
+;           IDL> PLOT, data, COLOR=colors.yellow
 ;
 ;       Note that the START keyword value is ignored if on a 24-bit device,
@@ -164 +147 @@
 ;       writing code like this:
 ;
-;           colors = GetColor(/Load)
-;           PLOT, data, Color=colors.yellow
-;
-; MODIFICATION HISTORY:
-;       Written by: David Fanning, 10 February 96.
+;           IDL> colors = GetColor(/Load)
+;           IDL> PLOT, data, Color=colors.yellow;           IDL> DEVICE, Decomposed=0
+;           IDL> colors = GetColor(/Load, Start=1)
+;           IDL> HELP, colors, /Structure
+;           PLOT, data, COLOR=colors.yellow
+;
+;       To get the direct color values as 24-bit integers in color structure fields:
+;
+;           IDL> DEVICE, Decomposed=1
+;           IDL> colors = GetColor(/Load)
+;           IDL> PLOT, data, COLOR=colors.yellow
+;
+;       Note that the START keyword value is ignored if on a 24-bit device,
+;       so it is possible to write completely device-independent code by
+;       writing code like this:
+;
+;           IDL> colors = GetColor(/Load)
+;           IDL> PLOT, data, Color=colors.yellow
+;
+; @history Written by: David Fanning, 10 February 96.
 ;       Fixed a bug in which N_ELEMENTS was spelled wrong. 7 Dec 96. DWF
 ;       Added the McIDAS colors to the program. 24 Feb 99. DWF
@@ -176 +174 @@
 ;       Added automatic recognition of DECOMPOSED=1 state. 7 June 99. DWF
 ;       Added LOAD AND START keywords. 7 June 99. DWF.
+;
+; @version $Id$
 ;-
-
-
-
-FUNCTION COLOR24, number
-;
-  compile_opt idl2, strictarrsubs
-;
-
-   ; This FUNCTION accepts a [red, green, blue] triple that
-   ; describes a particular color and returns a 24-bit long
-   ; integer that is equivalent to that color. The color is
-   ; described in terms of a hexidecimal number (e.g., FF206A)
-   ; where the left two digits represent the blue color, the
-   ; middle two digits represent the green color, and the right
-   ; two digits represent the red color.
-   ;
-   ; The triple can be either a row or column vector of 3 elements.
-
-ON_ERROR, 1
-
-IF N_ELEMENTS(number) NE 3 THEN $
-   MESSAGE, 'Augument must be a three-element vector.'
-
-IF MAX(number) GT 255 OR MIN(number) LT 0 THEN $
-   MESSAGE, 'Argument values must be in range of 0-255'
-
-base16 = [[1L, 16L], [256L, 4096L], [65536L, 1048576L]]
-
-num24bit = 0L
-
-FOR j=0,2 DO num24bit = num24bit + ((number[j] MOD 16) * base16[0,j]) + $
-   (Fix(number[j]/16) * base16[1,j])
-
-RETURN, num24bit
-END ; ************************  of COLOR24  ******************************
-
-
 
 FUNCTION GETCOLOR, thisColor, index, TRUE=truecolor, $