color procs

This page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? mk_html_help

at the IDL command line prompt.

Last modified: Tue Dec 20 11:48:25 2005.


List of Routines


Routine Descriptions

BGFILL

[Next Routine] [List of Routines]
 NAME:
       BGFILL
     
 PURPOSE:
       Fills the background of a plot window with a specified color.
     
 CALLING SEQUENCE:
       BGFILL, BGCOLOR
     
 INPUTS:
       BGCOLOR - Color table index (8-bit color) or 24-bit color
                 index of the color with which you would like to 
                 fill the background.

 OUTPUTS:
       None.

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
        Display device is filled with the input color.

 RESTRICTIONS:
       The /NOERASE keyword MUST be sent to any plotting routine that
       you call after using this routine!
       This causes problems if you are using !p.multi values
       other than zero.  See example below for how to do this.

 EXAMPLE:
       Fill the background with the color in the 0th index of the
       color table, then plot a line:

        IDL> bgfill, 0
        IDL> plot, findgen(30), /NOERASE

       In order to use !p.multi with this method, you must explicitly
       place each plot with a !p.multi assignment (since you must include 
       the /NOERASE keyword when starting a new plot!)  Remember the
       first element of !p.multi is the number of empty sectors remaining
       on the page and the default order of placement (the 5th element of
       !p.multi) is left-right and top-bottom. Here's an example:

        IDL> bgfill, 0
        IDL> !p.multi=[4,2,2]
        IDL> plot, findgen(30), /NOERASE
        IDL> !p.multi=[3,2,2]
        IDL> plot, findgen(30)^2, /NOERASE
        IDL> !p.multi=[2,2,2]
        IDL> plot, findgen(30)^3, /NOERASE

 NOTES:
       Note that in order for this to work, you need to set the
       /NOERASE keyword to any plotting routine you call directly
       after using this routine!

 MODIFICATION HISTORY:
       01 Mar 2002  Written by Tim Robishaw, Berkeley

(See /dzd2/heiles/idl/gen/color/bgfill.pro)


COLOR24

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       COLOR24

 PURPOSE:
       Return the 24-bit color index for an RGB triplet.

 CALLING SEQUENCE:
       RESULT = COLOR24(R, G, B)

 INPUTS:
       R - 8-bit red color index.
       G - 8-bit green color index.
       B - 8-bit blue color index.

 KEYWORD PARAMETERS:
       None.

 OUTPUTS:
       RESULT - the 24-bit color index for the RGB triplet.

 COMMON BLOCKS:
       None.

 EXAMPLE:
       Return the 24-bit color index for pure green:

       IDL> print, color24(0,255,0)

 MODIFICATION HISTORY:
   02 Mar 2003  Written by Tim Robishaw, Berkeley

(See /dzd2/heiles/idl/gen/color/color24.pro)


CT_FIDDLE -- FIDDLE INDEPENDENTLY R,G,B COLORTABLES IN DIRECT COLOR.

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
       ct_fiddle -- fiddle independently r,g,b colortables in direct color.

 PURPOSE:
       To fiddle with the color table.  The user can select which channels 
       of the color table to manipulate.  The user can change the gamma 
       correction and the range of the color table indices.

 CALLING SEQUENCE:
	CT_FIDDLE [, CHANNELS] [, LOW=value] [, HIGH=value] [,
	GAMMA=value] [, GRANGE=[min,max]]

 OPTIONAL INPUTS:
       CHANNELS: A string argument.  CHANNELS sets which color
                 channels ('R' for red, 'G' for green, 'B' for blue) 
                 will be manipulated in the color table.  The user
                 can manipulate one, two or all channels.  To fiddle
                 with the red and blue channels simultaneously,
                 set channels equal to the string 'rb'.

 KEYWORD PARAMETERS:
	LOW = The lowest pixel value to use.  If this parameter is omitted,
	      0 is assumed.  Appropriate values range from 0 to the number 
	      of available colors-1.

	HIGH = The highest pixel value to use.  If this parameter is omitted,
	       the number of colors-1 is assumed.  Appropriate values range 
	       from 0 to the number of available colors-1.

	GAMMA =	Gamma correction factor.  If this value is omitted, 1.0 is 
		assumed.  Gamma correction works by raising the color indices
		to the Gamma power, assuming they are scaled into the range 
		0 to 1.

       GRANGE = The desired range of the gamma axis, a 2-element
                vector.  The first element is the axis minimum, and 
                the second is the maximum. The default is [0.1,10.0].

 OUTPUTS:
       None.

 COMMON BLOCKS:
	COLORS:	The common block that contains R, G, and B color
		tables loaded by LOADCT, HSV, HLS and others.

 SIDE EFFECTS:
	Image display color tables are changed.

 RESTRICTIONS:
       If using TrueColor visual class, color decomposition must be 
       switched off in order for this routine to work.

 EXAMPLE:
       Load the BLUE/GREEN/RED/YELLOW color table and fiddle with 
       the red and blue channels:

       IDL> loadct, 4
       % LOADCT: Loading table BLUE/GREEN/RED/YELLOW
       IDL> ct_fiddle, 'rb'

 MODIFICATION HISTORY:
   08 May 2004  Written by Tim Robishaw, Berkeley
   Heavily modified version of Carl Heiles's DIDDLE.

(See /dzd2/heiles/idl/gen/color/ct_fiddle.pro)


CT_REVERSE

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	CT_REVERSE

 PURPOSE:
	Reverse the image display color tables over a specified range.

 CATEGORY:
	Image processing, point operations.

 CALLING SEQUENCE:
	CT_REVERSE, Low, High [, /OVERWRITE]

 OPTIONAL INPUTS:
	Low:	The lowest pixel value to use.  If this parameter is omitted,
		0 is assumed.  Appropriate values range from 0 to the number 
		of available colors-1.

	High:	The highest pixel value to use.  If this parameter is omitted,
		the number of colors-1 is assumed.  Appropriate values range 
		from 0 to the number of available colors-1.

 KEYWORD PARAMETERS:
       /OVERWRITE: The original color table stored in the "colors"
                   common block is overwritten with the reversed
                   color table.

 OUTPUTS:
	No explicit outputs.

 COMMON BLOCKS:
	COLORS:	The common block that contains R, G, and B color
		tables loaded by LOADCT, HSV, HLS and others.

 SIDE EFFECTS:
	Image display color tables are loaded.

 RESTRICTIONS:
	Common block COLORS must be loaded before calling CT_REVERSE.

 EXAMPLE:
	Load the STD GAMMA-II color table by entering:

		LOADCT, 5

	Create and display an image by entering:

		TVSCL, DIST(300)

       Now reverse the color table:
               CT_REVERSE

       Now reverse just the color table indices between 50 and 100:
               CT_REVERSE, 50, 100

 MODIFICATION HISTORY:
       19 Mar 2004  Written by Tim Robishaw, Berkeley
       Added /OVERWRITE keyword. TR, 07 May 2004

(See /dzd2/heiles/idl/gen/color/ct_reverse.pro)


CT_STRETCH

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
	CT_STRETCH

 PURPOSE:
	Stretch the image display color tables so the full range 
	runs from one color index to another.

 CATEGORY:
	Image processing, point operations.

 CALLING SEQUENCE:
	CT_STRETCH, Low, High [, Gamma] [, /CHOP] [, /OVERWRITE]

 INPUTS:
	Low:	The lowest pixel value to use.  If this parameter is omitted,
		0 is assumed.  Appropriate values range from 0 to the number 
		of available colors-1.

	High:	The highest pixel value to use.  If this parameter is omitted,
		the number of colors-1 is assumed.  Appropriate values range 
		from 0 to the number of available colors-1.

 OPTIONAL INPUTS:
	Gamma:	Gamma correction factor.  If this value is omitted, 1.0 is 
		assumed.  Gamma correction works by raising the color indices
		to the Gamma power, assuming they are scaled into the range 
		0 to 1.

 KEYWORD PARAMETERS:
	/CHOP:	If this keyword is set, color values above the upper threshold
		are set to color index 0.  Normally, values above the upper 
		threshold are set to the maximum color index.

       /OVERWRITE: The original color table stored in the "colors"
                   common block is overwritten with the reversed
                   color table.

 OUTPUTS:
	No explicit outputs.

 COMMON BLOCKS:
	COLORS:	The common block that contains R, G, and B color
		tables loaded by LOADCT, HSV, HLS and others.

 SIDE EFFECTS:
	Image display color tables are loaded.

 RESTRICTIONS:
	Common block COLORS must be loaded before calling CT_STRETCH.

 PROCEDURE:
	New R, G, and B vectors are created by linearly interpolating
	the vectors in the common block from Low to High.  Vectors in the 
	common block are not changed.

	If NO parameters are supplied, the original color tables are
	restored.

 EXAMPLE:
	Load the STD GAMMA-II color table by entering:

		LOADCT, 5

	Create and display an image by entering:

		TVSCL, DIST(300)

	Now adjust the color table with CT_STRETCH.  Make the entire 
       color table fit in the range 0 to 70 by entering:

		CT_STRETCH, 0, 70

	Notice that pixel values above 70 are now colored white.
	Restore the original color table by entering:

		CT_STRETCH

       To reverse the color table:
               CT_STRETCH, !D.TABLE_SIZE-1, 0

       To reverse the color table over only the range 50 to 120:
               CT_STRETCH, 120, 50

 NOTES: 
       RSI's STRETCH routine didn't cut the mustard.  (a) If the
       color table hasn't been loaded, it creates a color table with
       maximum values of (!D.TABLE_SIZE-1) rather than 255; (b) it
       uses LONG() to interpolate the color table rather than
       BYTSCL().
 
 MODIFICATION HISTORY:
       19 Mar 2004  Written by Tim Robishaw, Berkeley
	Most of documentation from DMS, RSI.
       Added /OVERWRITE keyword. TR, 07 May 2004

(See /dzd2/heiles/idl/gen/color/ct_stretch.pro)


GETCOLOR -- RETURN THE COLOR TABLE INDEX OF THE COLOR CORRESPONDING TO THE COLOR NAME

[Previous Routine] [Next Routine] [List of Routines]
 NAME:
GETCOLOR -- return the color table index of the color corresponding to the color name 
     
 PURPOSE:
       This function returns the color table index of the color
       corresponding to the color name which is input.  If the
       line plot color names and color table indices are not
       provided, SETCOLORS is called to set up basic line plot
       colors. Designed to work correctly on both X Window and 
       PostScript devices.
     
 CALLING SEQUENCE:
      color = getcolor(colorname, names, tableindx)

      OR

      color = getcolor(colorname[, DECOMPOSED=decomposed]) 
     
 INPUTS:
       COLORNAME: A string whose value is the name of a line plot
                  color.  Must not be an array.
     
 OPTIONAL INPUTS:
       COLORNAMES: An array of strings which correspond to line
                   plot colors that are available to the user.

       TABLEINDICES: An array of the color table indices (8-bit) or 
                     24-bit integers corresponding to the line plot colors.
     
 OUTPUTS:
       Function value returned = color table index of input color name.

 KEYWORDS:
       DECOMPOSED = Set this keyword to explicitly use decomposed color
                    on 24-bit machines. Has no effect on devices which 
                    do not support decomposed color. Set this keyword
                    to 0 to turn off decomposed color on 24-bit
                    devices. If COLORNAMES and TABLEINDICES are set,
                    this keyword has no effect.

 COMMON BLOCKS:
       None.

 SIDE EFFECTS:
       If the line plot color name COLORNAME is not found in the
       list of available line plot colors COLORNAMES, the value of
       the system plot color, !p.color, is returned.  If only
       COLORNAME is input and color decomposition is not on, the line 
       plot colors are added to the top of the current color table.

 RESTRICTIONS:
       Only supported by IDL v5.2 or higher. 

 PROCEDURES CALLED:
       FILE_WHICH
       SETCOLORS

 EXAMPLE:
       Once an array of line plot color names and their corresponding
       color table indices (8-bit) or 24-bit integers have been
       established, use GETCOLOR to obtain one of these values:

       IDL> setcolors, NAMES=cnames, VALUES=cindx
       IDL> plot, findgen(30), color=getcolor('orange',cnames,cindx)

       If no line plot color information exists, call GETCOLOR with
       only a color name and SETCOLORS will be called to establish
       a set of basic colors:

       IDL> plot, findgen(30), color=getcolor('cyan')

       If referencing many colors, this is much slower than the
       the previous example.  However, it's likely that if you're
       plotting something, you're not aiming for speed anyway!

 RELATED PROCEDURES:
       SETCOLORS

 MODIFICATION HISTORY:
   Written Tim Robishaw, Berkeley 13 Aug 2001

(See /dzd2/heiles/idl/gen/color/getcolor.pro)


SETCOLORS

[Previous Routine] [List of Routines]
 NAME: 
       SETCOLORS
     
 PURPOSE: 
       To set up device independent line plot colors. Designed to
       work correctly on both X Window and PostScript devices.
     
 CALLING SEQUENCE:
       SETCOLORS [, NAMES=string array][, VALUES=array][, 
                 NPLOTCOLORS=variable][, TABLESIZE=variable][,
                 DECOMPOSED={0|1}][,/SYSTEM_VARIABLES][,
                 /GETINFO][,/SILENT][,/TEST][,/START][,
                 PLOTCOLORS=string array, R_PLOT=array, G_PLOT=array, 
                 B_PLOT=array][,/PSEUDO256]
     
 INPUTS: 
       None.

 OPTIONAL INPUTS:
       (You can provide your own set of line plot colors, but you
        must provide all four of the following keywords and they
        must all have the same size! (See EXAMPLE.) If omitted,
        a set of 12 basic colors is used.)

       PLOTCOLORS = A string array of user-defined line plot color names.

       R_PLOT = The RED values of line plot colors.

       G_PLOT = The GREEN values of line plot colors.

       B_PLOT = The BLUE values of line plot colors.
     
 OUTPUTS:
       None.

 OPTIONAL OUTPUTS:
       NAMES = Returns a string array of the line plot color names.

       VALUES = Returns an array of the color table indices (8-bit) or 
                24-bit integers corresponding to the line plot colors.

       NPLOTCOLORS = Returns the number of line plot colors defined.

       TABLESIZE = Returns the number of color table indices.

 KEYWORDS:
       DECOMPOSED = Set this keyword to explicitly use decomposed color
                    on 24-bit machines. Has no effect on devices which 
                    do not support decomposed color. Set this keyword
                    to 0 to turn off decomposed color on 24-bit devices.

       /SYSTEM_VARIABLES: Define system variables with the name of each
                          color and the value of the color table index
                          or the 24-bit integer corresponding to each
                          color, i.e. for 24-bit color, !orange=32767L.
                          This is very useful since system variables have
                          global scope, therefore these colors can be
                          used in any procedure once defined.

       /GETINFO: Do not do anything to the color table, just print
                 out IDL color information.

       /SILENT: Do not print out IDL color information. Default is to 
                print info.

       /TEST: Display the entire color table and the names of
              the line plot colors in their respective colors.

       /START: Put the line plot colors at the start of the color 
               table. Default is to store them at the top.

       /NOCOLORS: Do not load line plot colors into color table!
                  Has no effect if color undecomposed.

       /PSEUDO256: Default is to establish PseudoColor visual using
                   only the available color indices when the first
                   window is created.  This keyword forces IDL to
                   use all 256 colors.

 COMMON BLOCKS:
       COLORS: The IDL color common block.

 SIDE EFFECTS:
       The color table may be modified.  If a window is not open, a
       pixmap is created then destroyed to establish the visual class
       and depth.  If the /TEST keyword is set and the device is X
       Windows, a free window is created to display the color table
       and line plot colors.

 RESTRICTIONS:
       Only supported by IDL v5.2 or higher. 

 PROCEDURES CALLED:
       None.

 EXAMPLE:
       To view the color table and line plot names and colors:

       IDL> setcolors, /test


       To define system variables with the names of each color
       and values of the corresponding color table index or 24-bit
       long integer:

       IDL> setcolors, /SYSTEM_VARIABLES


       To use the line plot colors (set DECOMPOSED=1 if 24-bit display):

       IDL> setcolors, NAMES=cnames, VALUES=cindx
       IDL> plot, findgen(30), co=cindx[(where(cnames eq 'yellow'))[0]]
       *OR*
       IDL> plot, findgen(30), co=getcolor('yellow',cnames,cindx)


       If you'd like to display an image but you've added line plot
       colors to the color table, you need to scale the image to
       avoid using the plotcolors:

       IDL> setcolors, NPLOTCOLORS=nplotcolors, TABLESIZE=tablesize
       IDL> tv, bytscl(image, top=tablesize-nplotcolors-1)
       If you load the line plot colors at the start of the color table:

       IDL> setcolors, NPLOTCOLORS=nplotcolors, TABLESIZE=tablesize, /START
       IDL> tv, bytscl(image, top=tablesize-nplotcolors-1)+nplotcolors

       (Do not use TVSCL!  "If color is important to you (and it almost
        always is), then you probably never want to use the TVScl command.
        Instead, you will want to scale your image data yourself, and use
        the TV command to display it." - David W. Fanning)


       To load your own line plot colors:

       IDL> setcolors, PLOTCOLORS=['red','yellow','blue','green'], $
       IDL> R_PLOT=[255,255,0,0], G_PLOT=[0,255,0,255], $
       IDL> B_PLOT=[0,0,255,0], NAMES=cnames, VALUES=cindx

       (Color 'WHITE' will be appended to the top of the color table
        to protect !p.color/!p.background.  If /START is set, color
        'BLACK' is appended to bottom of color table.)


       If you want to make a grayscale image and add colored
       annotation (when color decomposition is off):

       IDL> setcolors, NPLOTCOLORS=nplotcolors, TABLESIZE=tablesize, $
       IDL> NAMES=cnames, VALUES=cindx
       IDL> tv, bytscl(image, top=tablesize-nplotcolors-1)
       IDL> xyouts, 200, 150, 'M31', /dev, $
       IDL> co=cindx[(where(cnames eq 'cyan'))[0]]
       *OR*
       IDL> xyouts, 200, 150, 'M31', /dev, co=getcolor('cyan',cnames,cindx)

       WARNING!  After opening a PostScript file you should run
       SETCOLORS!  If you're using a 24-bit visual device,
       the system variables and color indices will be 24-bit longword
       integers (with values greater than 256) but PostScript is an
       8-bit device with only 256 colors available, so right after opening
       a PostScript file, you should run SETCOLORS to re-establish the
       color system variables color indices. Likewise, when you close
       a PostScript image, you should run SETCOLORS again in order to
       re-establish the colors for X Windows.

 NOTES:
       Once a window is open, the visual class is established for the IDL
       session.  There is no way to change it once it is established.
       However, if no window is open (there's no way to tell if one has
       been opened in the past) we open a pixmap and delete it just to
       establish the visual class and depth.

       I thought at first it would be convenient to store the color table
       indices of each color in a variable named after the corresponding
       color and storing each color variable in a common block.  However, I
       was convinced by two very bright folks that common blocks should be
       avoided, especially for this use.

 RELATED PROCEDURES:
       GETCOLOR

 MODIFICATION HISTORY:
       Written by Tim Robishaw, Berkeley 13 Aug 2001
       Added /NOCOLORS keyword. TR, Berkeley 03 Oct 2001
       Added /SYSTEM_VARIABLES keyword. TR, 07 Feb 2002
       Added /PSEUDO256 keyword. TR, 15 Feb 2002
       Removed IDL's STRETCH. TR, 19 Mar 2004
       Made sue r,g,b_curr get defined. TR, 07 May 2004

(See /dzd2/heiles/idl/gen/color/setcolors.pro)