List routines by category:
Atmospheric Sciences |
Benchmarking |
Color |
Date/Time |
Doc |
File & I/O |
BPCH Format |
Scientific Data Formats |
GAMAP Examples |
GAMAP Internals |
GAMAP Utilities |
GAMAP Data Manipulation |
GAMAP Models &
Grids |
GAMAP Plotting |
General |
Graphics |
Math & Units |
Plotting |
Regridding |
Strings |
Structures |
Time Series
List routines by alphabetical order:
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z
NAME:
CINDEX
PURPOSE:
This is a program for viewing the current colors in the
colortable with their index numbers overlayed on each color.
CINDEX Draws a NROW x NCOL set of small rectangles, each of
which displays one of the colors in the color table. It also
writes the color index number on top of each rectangle.
CATEGORY:
Color
CALLING SEQUENCE:
CINDEX
INPUTS:
None
KEYWORD PARAMETERS:
NCOL -> Specify the number of columns in the plot.
Default is 16.
NROW -> Specify the number of columns in the plot. If not
specified, then CINDEX will compute the minimum number
of rows that are needed to display all of the colors,
given the setting of NCOL.
TITLE -> Specify the title for the plot window.
/ALL -> Set this switch to plot all 256 colors on a 16x16 grid.
Colors that are not defined will be rendered as white.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
(1)
MYCT, /WhGrYlRd
CINDEX
; Displays the colors of the MYCT color table
; WHITE-GREEN-YELLOW-RED (spectral). The drawing
; colors and all 20 colors of this table are shown.
(2)
MYCT, /WhGrYlRd
CINDEX, /ALL
; Same as above, but plots the colors on a
; 16 x 16 grid.
MODIFICATION HISTORY:
INITIAL REVISION: David Fanning, RSI, May 1995
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Added NCOL, ROW, TITLE, ALL keywords to
allow the user to specify these settings
instead of having these be hardwired.
bmy, 21 Apr 2008: GAMAP VERSION 2.12
- Now use NAME and INDEX tags from !MYCT
to define the default title string.
(See /n/home09/ryantosca/IDL/gamap2/color/cindex.pro)
NAME:
COLORBAR
PURPOSE:
Draw a colorbar (legend) with labels
CATEGORY:
Color
CALLING SEQUENCE:
COLORBAR [ , Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
ANNOTATION -> Array with string label values. If specified,
ANNOTATION will override the default label values, and
will also override the LABEL keyword.
BOTOUTOFRANGE, TOPOUTOFRANGE -> a color index value for data
that falls below (or above) the normal plot range. If
given, an extra box will be drawn to the left (or right)
of the colorbar, and the colorbar will shrink in size.
A default label '<' (or '>') will be placed below.
NOTE: these options are only available for horizontal
colorbars.
BOR_LABEL, TOR_LABEL -> label values for BOTOUTOFRANGE and
TOPOUTOFRANGE that replace the defaults.
BOTTOM -> First color index to use. Default is !MYCT.BOTTOM.
NOTE: In practice you shouldn't have to specify BOTTOM,
as the value from !MYCT.BOTTOM will reflect the settings
of the current colortable.
C_COLORS -> Array of color indices for "discrete" color bars
e.g. in filled contour plots. You must also use the
C_LEVELS keyword, otherwise there will most likely be
a mismatch between your plot colors and your colorbar
colors. COLORBAR normally limits the number of labels
it prints to 10. Use the SKIP keyword to force a different
behaviour. If C_COLORS is not undefined it overrides the
settings from NCOLORS, and BOTTOM.
C_LEVELS -> Array with label values for "discrete" colorbars.
Use the LABEL or ANNOTATION keyword for continuous
colorbars. C_LEVELS must have the same number of elements
as C_COLORS and assigns one label to each color change
(LABEL distributes the labels evenly). Use the SKIP
keyword to skip labels. As default, COLORBAR limits the
number of labels printed to 10.
AUTOSCALELEVELS -> Set this switch to automatically scale
labels (specified by C_LEVELS, LABEL, MAX, or MIN)
by powers of 10. This reduces the length of each tick label
and helps prevent overlapping numbers in the colorbar.
CHARSIZE -> Specifies the character size for colorbar labels.
Default is !P.CHARSIZE.
COLOR -> The drawing color for boxes and labels.
Default is !MYCT.BLACK.
DIVISIONS -> Number of labels to put on the colorbar.
Note that this keyword is overwritten by LABEL.
The labels will be equally spaced and the /LOG option
will be honored.
FLAGVAL -> If set, will place a tick mark with label at a
user-defined value. You can use this to denote where
0 or 1 falls w/in a color range, for example.
FORMAT -> Output format of the labels. Default is determined
according to the range given in min and max. Label
strings will be trimmed, so you can safely specify
'(f14.2)' for example.
LABEL -> Array containing label values (must be numeric).
Normally, it is easier to generate labels with the
DIVISIONS options, but this allows tighter control
(e.g. 1,2,5,10,20 labels on logarithmic scales).
Default (if no DIVISIONS are given): MIN and MAX.
NOTE: ANNOTATION will
/LOG -> Set this switch to invoke logarithmic spacing of
labels. The colors are *always* linearily distributed.
MAX -> Maximum value to plot. Default is NCOLORS.
MIN -> Minimum value to plot. Default is BOTTOM.
/NOGAP -> if 0 then there is a gap b/w the triangle or
rectangle OutOfRange boxes and the bar, else no
gap. Defalut is to have a gap. If /TRIANGLE and no
OutOfRange boxes are set then default is No Gap.
NCOLORS -> Number of colors to use in the colorbar. Default
is !MYCT.NCOLORS. NOTE: In practice you shouldn't have
to specify NCOLORS, as the value from !MYCT.NCOLORS will
reflect the settings of the current colortable.
ORIENTATION -> Specifies the orientation of the colorbar
labels. This keyword has the same behavior as the
ORIENTATION option in XYOUTS (i.e. ORIENTATION=0 means
normal "left-right" text, ORIENTATION=-90 means "top-
bottom" text, etc.)
POSITION -> A position value or 4-element vector. If POSITION
contains only one element, it will be centered at the
bottom or right side of the page and extend over 60% of
the total plotting area.
SCIENTIFIC -> If set, will call STRSCI to put the colorbar
labels in scientific notation format (e.g. in the form
A x 10^B). STRSCI will use the format string specified
in the FORMAT keyword.
SKIP -> Print only every Nth discrete label. The default is
computed such that COLORBAR will print no more than 10
labels.
TITLE -> A title string for the colorbar. (This works similarly
to the XTITLE or YTITLE options to the PLOT command.)
TICKLEN -> A number between 0 and 1 which defines the length
of the tick marks as a fraction of the size of the plot
box. Default is 0.25.
/TRIANGLE -> to plot triangles at the end of the color bar. If
OutOfRange boxes are requested, then the triangles
replace the rectangle.
UNIT -> A unit string that will be added to the right of the
labels. If /VERTICAL is set, then the unit string will
be placed at the top of the labels.
UPOS -> Specifies the position (relative to the size of the
colorbar) where the unit string will be placed. The
default is 1.15. To print the unit string closer to the
end of the colorbar, reduce this value until the desired
appearance is obtained.
/VERTICAL -> Set this keyword to produce a vertical colorbar
(default is horizontal). Note that out-of-range boxes are
only implemented for horizontal color bars.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
====================================
STRSCI (function) TRIANGLE
REQUIREMENTS:
Assumes that we are using a MYCT-defined colortable.
NOTES:
(1) This routine was designed after David Fanning's colorbar
routine and adapted to our needs. Some of the postscript
handling of DF was removed, positioning is a little easier
but maybe a little less flexible; out-of-range boxes have
been added.
(2) The !MYCT system variable contains the properties of the
current MYCT-defined colortable. You normally should not
have to explicity pass BOTTOM or NCOLORS, as these
keywords will be initialized from the values from !MYCT.
EXAMPLES:
COLORBAR, MIN=MIN( DATA, MAX=M ), MAX=M
; Draw a horizontal colorbar with all available colors
; Default placement is at the bottom of the page.
; will be placed at the bottom of the page
COLORBAR, MIN=0.1, MAX=10, /LOG, UNIT='[ppt]', $
LABELS=[0.1, 0.5, 1, 5, 10 ],
POSITION=[0.3. 0.3, 0.3, 0.3]
; Draw another colorbar above the first one,
; use logarithmic scale
COLORBAR, MIN=0.1, MAX=10, /LOG, UNIT='[ppt]', $
LABELS=[0.1, 0.5, 1, 5, 10 ],
POSITION=[0.1, 0.1, 0.1, 0.1], /VERTICAL
; Draw vertical colorbar closer to the left edge of
; the plot. Otherwise options are the same as in the
; previous example.
COLORBAR, MIN=0, MAX=100, $
DIVISIONS=5, TOPOUTOFRANGE=!MYCT.WHITE
; Draw horizontal colorbar with out-of-range box
; (colored white) to the right of the max value.
COLORBAR, MIN=0, MAX=100, $
DIVISIONS=5, TOPOUTOFRANGE=!MYCT.WHITE, $
ANNOTATION=[ '0', '2,500', '5,000', '7,500', '10,000' ]
; Same example as above, but this time we use the
; ANNOTATION keyword to override the default labels
; with string labels.
MODIFICATION HISTORY:
mgs, 02 Jun 1998: VERSION 1.00
mgs, 14 Nov 1998: - changed default format to f14.2 from f6.2
mgs, 19 Nov 1998: - added cbdefaultformat function to better handle
default labeling format.
mgs, 28 Nov 1998: - default labelling format now exponential for
values gt 1.e6
mgs, 19 May 1999: - unit string placed a little further right
in horizontal colorbars.
mgs, 27 May 1999: - added functionality for discrete colorbars
(C_COLORS, C_LEVELS, and SKIP keywords)
bmy, 02 Jun 1999: - added /SCIENTIFIC keyword
- updated comments
mgs, 03 Jun 1999: - fixed discrete labeling x positions
bmy, 27 Jul 2000: TOOLS VERSION 1.46
- added ORIENTATION keyword so that the user
can control the vertical colorbar labels
bmy, 27 Sep 2002: TOOLS VERSION 1.51
- Now use 2 decimal places for exponential
default format instead of 3
bmy, 18 Oct 2002: TOOLS VERSION 1.52
- now use _EXTRA=e to pass commands to
XYOUTS (i.e. to set label thickness)
bmy, 26 Nov 2002: - Added ANNOTATION keyword to print
string labels instead of numeric labels
bmy, 26 Nov 2003: TOOLS VERSION 2.01
- make sure MINV, MAXV, and DIVISIONS
are scalars so as not to generate the
color bar labels incorrectly.
bmy, 21 May 2004: TOOLS VERSION 2.02
- If SKIP is passed, make sure that it is
never less than 1.
- added TICKLEN and FLAGVAL keywords
- now add ticks where labels are printed
- Cosmetic changes, updated comments
bmy, 07 Mar 2007: TOOLS VERSION 2.06
- Updated documentation and examples
dbm & bmy, 13 Jun 2007: - Now define default colors for contour plots
if C_LEVELS is passed but C_COLORS isn't
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
cdh & phs, 19 Nov 2007: GAMAP VERSION 2.11
- Added out of range boxes options for
vertical bar
- Added TRIANGLE and NoGAP keyword
- Set default for case of /TRIANGLE, but no
OutOfRange boxes.
phs, 21 Apr 2008: GAMAP VERSION 2.12
- Bug fix default MAXV should be NCOLORS+BOTTOM
cdh, 16 Apr 2013: Fill MinV and MaxV values from C_Levels
(See /n/home09/ryantosca/IDL/gamap2/color/colorbar.pro)
NAME:
COLORBAR_NDIV
PURPOSE:
Returns the maximum number of colorbar divisions possible
(up to a user-defined limit) such that tickmarks are placed
in between colors.
CATEGORY:
Color
CALLING SEQUENCE:
Result = COLORBAR_NDIV( NCOLORS [, Keywords ] )
INPUTS:
NCOLORS -> (OPTIONAL) Specifies the number of colors
in the color table. Default is !MYCT.NCOLORS.
KEYWORD PARAMETERS:
MAXDIV -> Specifies the maximum number of divisions
for the colorbar. Default is 6.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
None
NOTES:
None
EXAMPLES:
DIV = COLORBAR_NDIV( 20, MAXDIV=8 )
TVMAP, ..., DIVISONS=DIV, ...
; Computes the number of color bar divisions for
; a colortable with 20 colors. DIV will not exceed
; the value of MAXDIV (in this case =8). The value
; of DIV is then passed to the TVMAP routine (which
; in turn passes it to the COLORBAR routine).
MODIFICATION HISTORY:
phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/color/colorbar_ndiv.pro)
NAME:
COMPRESS_DIV_CT
PURPOSE:
Compresses a diverging color table with even number of colors
into NCOLORS. If the /MIDCOLORPRESENT keyword is specified,
COMPRESS_DIV_CT will also place white or yellow spaces in
the middle of the color table.
CATEGORY:
Color
CALLING SEQUENCE:
COMPRESS_DIV_CT, R, G, B [, Keywords ]
INPUTS:
R, G, B -> The vectors containing the red, blue, and
green color values that define the color table.
KEYWORD PARAMETERS:
NCOLORS -> Requested number of colors to be returned.
If NCOLORS is omitted, then COMPRESS_DIV_CT will
return without doing anything.
/MIDCOLORPRESENT -> Set this switch to add 1 or 2 extra
white or yellow color spaces in the color table.
/WHITE -> If /MIDCOLORPRESENT is set, this switch will
cause 1 (if NCOLORS is odd) or 2 (if NCOLORS is even)
extra white color spaces to be placed
at the center of the color table.
/YELLOW -> If /MIDCOLORPRESENT is set, this switch will
cause 1 (if NCOLORS is odd) or 2 (if NCOLORS is even)
extra white color spaces to be placed
at the center of the color table. ;
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
Designed for use with MYCT. You shouldn't normally
have to call COMPRESS_DIV_CT directly.
NOTES:
None
EXAMPLE:
LOADCT, 63, FILE=FILE_WHICH( 'gamap_colors.tbl' )
TVLCT, R, G, B, /Get
; Load the ColorBrewer "RdBu" table
; and return the color vectors
COMPRESS_DIV_CT, R, G, B, $
NCOLORS=20, /MIDCOLORPRESENT, /WHITE
; Compress the color table down to 20 colors and
; insert 2 white spaces at the middle of the table.
MODIFICATION HISTORY:
phs, 21 Apr 2008: GAMAP VERSION 2.12
(See /n/home09/ryantosca/IDL/gamap2/color/compress_div_ct.pro)
NAME:
CUSTOM_COLORTABLE
PURPOSE:
Defines various customized color tables for use with MYCT.
Color tables may be stretched to more than the original #
of colors, or compressed to less than the original # of
colors. You may add more color tables as necessary.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% AS OF GAMAP v2-12, CUSTOM_COLORTABLE IS DEPRECATED. %%
%% MYCT NOW LOADS IDL AND ColorBrewer COLORTABLES FROM %%
%% THE "gamap_colors.tbl" FILE. (phs, bmy, 4/21/08) %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
CATEGORY:
Color
CALLING SEQUENCE:
CUSTOM_COLORTABLE, R, G, B [ , Keywords ]
INPUTS:
None
KEYWORD PARAMETERS
/BuWhRd -> Set this switch to load the BLUE-WHITE-RED
(diverging) color table from Harvard University. This
color table is a concatenation of the WHITE-BLUE and
WHITE-RED ColorBrewer colortables. The center color
is white. (Original # of colors = 19)
/BuWhWhRd -> Set this switch to load the BLUE-WHITE-WHITE-RED
(diverging) color table. This is a concatenation of
the WhBu and WhRd colortables from ColorBrewer. The two
center colors in this colortable are white, which makes
it easier to align colorbar tickmarks at the divisions
between colors. (Original # of colors = 20)
/BuYlRd -> Set this switch to load the BLUE-YELLOW-RED
(diverging) color table from ColorBrewer. (Original
# of colors = 12)
/BuYlYlRd -> Set this switch to load the BLUE-YELLOW-YELLOW-RED
(diverging) color table from ColorBrewer. The two center
colors in this colortable are light yellow, which makes
it easier to align colorbar tickmarks at the divisions
between colors. Use this colortable instead of /BuWhWhRd
if you need to denote "missing data" values by white.
(Original # of colors = 12)
/DIAL -> Set this switch to load the DIAL/LIDAR (diverging)
color table from Ed Browell. (Original # of colors = 27)
/DIFF -> Synonym for /BuWhRd. Kept for backwards compatibility.
/ModSpec -> Set this switch to load the MODIFIED SPECTRUM
(diverging) color table from ColorBrewer. (Original #
of colors = 11)
NAME -> Returns to the calling program the name of the color
table that we have selected.
NCOLORS -> The number of colors that you would like to be
included in the colortable. If NCOLORS is greater than
the native number of colors for the given colortable,
the colortable will be stretched to produce a finer
gradation of colors. Conversely, if NCOLORS is less
than the native number of colors, then the colortable
will be compressed to produce a coarser gradation of
colors.
/NOLOAD -> If set, then CUSTOM_COLORTABLE will just return R,
G, B to the calling program without loading the colortable.
/TRUNCATE -> When NCOLORS is less than the number of colors
in the given color table, setting /TRUNCATE will cause
CUSTOM_COLORTABLE to truncate the color table to NCOLORS
rather than trying to compress it via interpolation.
/UserDef -> Set this switch to load a user-defined colortable.
In order to use this option, you must first add the R, G,
B color vectors into internal routine DEFINE_UserDef.
/WhBu -> Set this switch to load the WHITE-BLUE (spectral)
color table from ColorBrewer. (original # of colors = 10)
/WhGrYlRd -> Set this switch to load the WHITE-GREEN-YELLOW-RED
(spectral) color table from A. van Donkelaar. (Original
# of colors = 20)
/WhGyBk -> Set this switch to load the WHITE-GRAY-BLACK
(spectral) color table from ColorBrewer. (Original #
of colors = 10)
/WhRd -> Set this switch to load the WHITE-RED (spectral) color
table from ColorBrewer. (original # of colors = 10)
OUTPUTS:
R -> Returns to the calling program the red color
vector that defines the customized colortable.
G -> Returns to the calling program the green color
vector that defines the customized colortable.
B -> Returns to the calling program the blue color
vector that defines the customized colortable.
SUBROUTINES:
Internal Subroutines Included:
================================================
DEFINE_BuWhRd DEFINE_BuWhWhRd DEFINE_BuYlRd
DEFINE_BuYlYlRd DEFINE_DIAL DEFINE_MODSPEC
DEFINE_WhBu DEFINE_WhGrYlRd DEFINE_WhRd
DEFINE_WhGyBk
REQUIREMENTS:
None
NOTES:
(1) For contour plots, the native resolution of the
custom colortables should be sufficient.
(2) For smoothed pixel plots, NCOLORS=100 or higher will
eliminate the streaking caused by TVIMAGE's smoothing
algorithm.
(3) Some color tables were adapted from the ColorBrewer
package (see license info below).
(4) We will use the ColorBrewer color abbreviations:
Bk = Black Br = Brown Bu = Blue
Gr = Green Gy = Gray Or = Orange
Pi = Pink Pu = Purple Rd = Red
Wh = White Yl = Yellow
(5) An MS Excel spreadsheet with all ColorBrewer color tables
is available for download from:
www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_RGB.html
EXAMPLES:
CUSTOM_COLORTABLE, R, G, B, /NOLOAD, /DIAL
; Returns the red, green, blue color vectors for the
; DIAL colortable at native resolution (26 colors)
CUSTOM_COLORTABLE, NCOLORS=120, /DIAL
; Loads the DIAL colortable and stretches it
; from 26 to 120 colors.
CUSTOM_COLORTABLE, /WhGrYlRd
; Loads the WHITE-GREEN-YELLOW-RED (spectral)
; color table with 20 colors.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Adapted from "dial_ct.pro"
- Now can compress the colortable if
NCOLORS is less than N_ORIG
- Added /BuWhWhRd keyword for selecting
the BLUE-WHITE-WHITE-RED colortable
- Added /BuYlYlRd keyword for selecting
the BLUE-YELLOW-YELLOW-RED colortable
- /DIFF is now a synonym for /BuWhWhRd
- Added /UserDef keyword and internal
routine DEFINE_UserDef for selecting
a user-defined color table.
phs, 12 Feb 2008: GAMAP VERSION 2.12
- Now create /BuWhRd as a concatenation of
the /WhBu and /WhRd colortables.
- Updated the interpolation for case of
NCOLORS lt NORIG. It works fine with all
the 4 diverging colortables, and keeps the
doubling of the middle range color if NCOLORS
is even and BuWhWhRd or BuYlYlRd is used.
bmy, 18 Apr 2008: - Bug fix: don't overwrite colortable name
for BuWhRd colortable
(See /n/home09/ryantosca/IDL/gamap2/color/custom_colortable.pro)
NAME:
DOCUMENT_COLOR_TABLE
PURPOSE:
Displays all of the color tables within a standard IDL
*.tbl file. Can display output to the Xwindow device,
or create PostScript and PDF output.
CATEGORY:
Color
CALLING SEQUENCE:
DOCUMENT_COLOR_TABLE [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
FILE -> Name of the the color table (*.tbl) file to read.
Default is "gamap_colors.tbl".
/PS -> Set this switch to print output to a PostScript
document instead of plotting to the screen.
/PDF -> Set this switch to create a PostScript document
and then also create a PDF document.
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
The Unix utility "ps2pdf" must be installed on your system
for the /PDF keyword to work. The ps2pdf utility should come
standard with most Unix or Linux builds.
NOTES:
None
EXAMPLES
DOCUMENT_COLOR_TABLE
; Prints out the color tables to the screen.
; Will set a 900x900 pixel window by default.
DOCUMENT_COLOR_TABLE, /PS
; Prints color tables to a PostScript file
; called "table_info.ps".
DOCUMENT_COLOR_TABLE, /PDF
; Prints out the color tables to a PostScript file
; "table_info.ps", then also creates a PDF file
; "table_info.pdf" using "ps2pdf".
MODIFICATION HISTORY:
phs, 21 Apr 2008: VERSION 1.00
phs, 25 Mar 2009: GAMAP VERSION 2.13
- Added FUN keyword
(See /n/home09/ryantosca/IDL/gamap2/color/document_color_table.pro)
NAME:
GAMAP_COLORS
PURPOSE:
Concatenates several different color tables (including
IDL standard color tables and the ColorBrewer color
tables) into single file for for use with GAMAP.
CATEGORY:
Color
CALLING SEQUENCE:
GAMAP_COLORS
INPUTS:
OUTFILENAME -> Name of the color table file to modify.
Default is "gamap_colors.tbl". GAMAP_COLORS will
locate this file with FILE_WHICH.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MYCT
REQUIREMENTS:
None
NOTES:
IDL's MODIFYCT function may require that the file to be
modified already be on disk.
EXAMPLE:
GAMAP_COLORS, 'new_gamap_colors.tbl'
; Will modify the colortable file
; 'new_gamap_colors.tbl'.
MODIFICATION HISTORY:
bmy, 18 Apr 2008: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/color/gamap_colors.pro)
NAME:
HCOLORBAR
PURPOSE:
Plot a horizontal colorbar.
%%% NOTE: This is obsolete, you should use COLORBAR instead! %%%
CATEGORY:
Color
CALLING SEQUENCE:
HCOLORBAR, CX, CY, [,keywords]
INPUTS:
CX -> [Min X, Max X] vector in NORMAL coords
CY -> [Min Y, Max Y] vector in NORMAL coords
KEYWORD PARAMETERS:
COLORS -> array of color levels
LABELS -> string array of labels for the color levels
OUTPUTS:
None
SUBROUTINES:
None
REQUIREMENTS:
HCOLORBAR assumes n_elements(COLORS) >= n_elements(LABELS)+1
NOTES:
(1) HCOLORBAR is more or less obsolete. You should use
the COLORBAR routine instead. However, there may be
some applications where HCOLORBAR is required, so we
keep this routine for backwards compatibility with
older IDL code.
(2) The colorbar will be plotted as follows:
LABELS(0) LABELS(1) LABELS(NL-1)
+-----------+-----------+----------- // --------------+------------+
| COLORS(0) | COLORS(1) | COLORS(2) // COLORS(NL-1) | COLORS(NL) |
+-----------+-----------+----------- // --------------+------------+
COLORS(0) = color index for data < first contour level
COLORS(1) = color index for data between 1st and 2nd levels
...
COLORS(NL) = color index for data >= the last contour level
LABELS(0) = label for the first contour level
LABELS(1) = label for the 2nd contour level, etc...
...
LABELS(NL) = label for data >= the last contour level
EXAMPLE:
HCOLORBAR, [0.025, 0.275], [0.680, 0.690], $
COLORS=[0,1,2,3,4,5], LABELS=['1','2','3','4','5']
MODIFICATION HISTORY:
bmy, 10 Nov 1994: VERSION 1.00
bmy, 24 Jun 1997: VERSION 1.01
bmy, 30 Sep 1997: TOOLS VERSION 1.10
bmy, 20 Nov 1997: TOOLS VERSION 1.11
bmy, 02 Aug 1999: TOOLS VERSION 1.43
- minor bug fix
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Updated comments, cosmetic changes
(See /n/home09/ryantosca/IDL/gamap2/color/hcolorbar.pro)
NAME:
MYCT
PURPOSE:
Define a set of standard drawing colors and load a colortable
on top of these. The color table can be manipulated in various
ways (see KEYWORD PARAMETERS).
The standard MYCT drawing colors are as follows. These
were implemented by Chris Holmes, based on the ColorBrewer
definitions. These colors are less saturated than the
traditional MYCT drawing colors, and are easier to read
on the screen:
0 : white 9 : lightblue
1 : black 10 : lightorange
2 : red 11 : lightpurple
3 : green 12 : 85% grey
4 : blue 13 : 67% grey
5 : orange 14 : 50% grey
6 : purple 15 : 33% grey
7 : lightred 16 : 15% grey
8 : lightgreen 17 : white
However, if you use the /BRIGHT_COLORS keyword to MYCT, you
may still use the traditional MYCT drawing colors (which were
created by Martin Schultz). These are defined as follows:
0 : white 9 : lightgreen
1 : black 10 : lightblue
2 : red 11 : black
3 : green 12 : 85% grey
4 : blue 13 : 67% grey
5 : yellow 14 : 50% grey
6 : magenta 15 : 33% grey
7 : cyan 16 : 15% grey
8 : lightred 17 : white
With MYCT, you may load any of the standard IDL color tables
or any of the ColorBrewer color tables. For backwards
compatibility, MYCT also supports several customized color
tables that used to be defined with the CUSTOM_COLORTABLE
routine.
MYCT reads color table definitions from an IDL *.tbl file.
The default file name is "gamap_colors.tbl". You may specify
a different file with the CTFILE keyword (see below). Also,
if you wish to add a custom color table, the best way to
proceed is to create your own *.tbl file with your custom
color table definitions. See the routine GAMAP_COLORS for
more information.
CATEGORY:
Color
CALLING SEQUENCE:
MYCT, [ TABLE ] [ , keywords ]
INPUTS:
TABLE (optional) -> Number or name of the IDL color table
to be used. If no number or name is provided, the
routine will default to color table 0 (which for the
"gamap_colors.tbl" file is B-W LINEAR). The MYCT
drawing colors will be loaded first, and the color
table will be loaded on top of that. You can choose
the bottom color index for the color table with the
BOTTOM keyword. MYCT will ensures that the system
variable !D.N_COLORS is set correctly.
KEYWORD PARAMETERS:
/BRIGHT_COLORS -> Selects the older set of MYCT drawing colors
to be loaded at the bottom of the colortable. Default is
to select the newer set of MYCT drawing colors, which
are less saturated and easier to read on the screen.
BOTTOM -> specify where to start color table (see BOTTOM keyword
in LOADCT). Default is number of standard drawing colors+1
or 0 (if NO_STD is set). If BOTTOM is less than the number
of standard drawing colors (17), no standard colors will be
defined (equivalent to setting NO_STD). RANGE has no
effect on the DIAL/LIDAR colortable. Default is 18.
NOTE: You should not normally have to change this value.
CTFILE -> Specify a file containing the color table
definitions. Default is "gamap_colors.tbl", which is
a combination of the standard IDL color tables plus
the ColorBrewer color tables. (See routine GAMAP_COLORS.)
NCOLORS -> number of color indices to be used by the color table.
Default is !D.N_COLORS-BOTTOM.
/NO_STD -> prevents definition of standard drawing colors.
RANGE -> a two element vector which specifies the range of colors
from the color table to be used (fraction 0-1). The colortable
is first loaded into the complete available space, then
the selected portion is interpolated in order to achieve the
desired number of colors. RANGE is only effective when
a TABLE parameter is given. RANGE has no effect on the
customized colortables.
/REVERSE -> Set this switch to reverse the color table.
/REVERSE works for both IDL and custom color tables.
SATURATION -> factor to scale saturation values of the extra
color table. Saturation ranges from 0..1 (but the factor
is free choice as long as positive). SATURATION has no
effect on the customized colortables. Default is 1.
USERDEF -> set to load the user defined colortable. The table
is defined in the Define_UserDef routine. It can be
loaded in three different ways:
MyCt, -1
MyCt, /user
MyCt, 'user'
In the later version, the string is not case sensitive,
and can be any string that contains the word "user".
VALUE -> factor to scale the "value" of the added colortable.
(i.e. this is like the contrast knobon a TV set). Value
ranges from 0..1; 0 = black, 1 = white. Default is 1.
/USE_CURRENT -> By default, MYCT will reset the color table
to all white before loading a new colortable. Set
/USE_CURRENT to prevent this from happening.
/VERBOSE -> Set this switch to print out information about
the color table that has just been selected.
/XINTERACTIVE -> to call XLOADCT instead of LOADCT for
interactivity. Has no effect if a custom colortable is
loaded.
The following keywords are kept for backwards compatibility.
These will replicate the color tables that used to be defined
with the now obsolete CUSTOM_COLORTABLE routine.
/BuWhRd -> Loads 19-color BLUE-WHITE-RED color table
/BuWhWhRd -> Loads 20-color BLUE-WHITE-WHITE-RED color table
/BuYlRd -> Loads 11-color BLUE-YELLOW-RED color table
/BuYlYlRd -> Loads 12-color BLUE-YELLOW-YELLOW-RED color table
/DIAL -> Loads the 26-color DIAL/LIDAR color table
(cf. E. Browell)
/DIFF -> Synonym for /BuWhRd.
/ModSpec -> Loads the 11 color MODIFIED SPECTRUM color table
/WhBu -> Loads the 10-color WHITE-BLUE color table
/WhGrYlRd -> Loads the 20-color WHITE_GREEN-YELLOW-RED color table
(cf. Aaron van Donkelaar)
/WhGyBk -> Loads the 10-color the WHITE-GRAY-BLACK color
/WhRd -> Loads the 10-color the WHITE-RED color table
OUTPUTS:
None
SUBROUTINES:
Internal Subroutines Provided:
===============================
MYCT_Drawing_Colors
External Subroutines Required:
===============================
COMPRESS_DIV_CT
DATATYPE (function)
XCOLORS
REQUIREMENTS:
None
NOTES:
(1) It is recommended to use the COLOR keyword in all PLOT
commands. This will ensure correct colors on (hopefully)
all devices. In order to get 256 colors on a postscript
printer use DEVICE,/COLOR,BITS_PER_PIXEL=8
(2) MYCT will also save several parameters in the MYCT system
variable, so that graphics programs can access them.
(3) MYCT uses the "gamap_colors.tbl" file. This file
contains all of the IDL standard color table definitions
all of the olorBrewer color table definitions, and some
extra colortables. If you wish to add a color table
you should probably use routine GAMAP_COLORS to create
a new *.tbl file. Then call MYCT and specify the name
of the new *.tbl file with the CTFILE keyword.
(4) We will use the ColorBrewer color abbreviations:
Bk = Black Br = Brown Bu = Blue
Gr = Green Gy = Gray Or = Orange
Pi = Pink Pu = Purple Rd = Red
Wh = White Yl = Yellow
(5) An MS Excel spreadsheet with all ColorBrewer color tables
is available for download from:
www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_RGB.html
(6) NOTE: Use a temporary hack to center the ColorBrewer
diverging color tables. (phs, 4/23/08)
EXAMPLES:
MYCT, 8, /NO_STD
; load IDL colortable green-white (#8)
; identical result as loadct,3
MYCT, 'EOS B', NCOLORS=20
; change first 17 colors to standard drawing colors
; and add EOS-B (#27) color table in indices 18-36
MYCT, 0, NCOLORS=20, /REVERSE, /NO_STD, /Use_Current
; add reversed grey scale table on top
MYCT, 'EOS B', NCOLORS=40, /NO_STD, /Use_Current, $
RANGE=[0.1,0.7], SATURATION=0.7
; add a less saturated version of a fraction
; of the EOS-B color table in the next 40 indices
; NOTE that color indices above 97 will still contain
; the upper portion of the green-white color table.
MYCT, 0 /REVERSE
; On b/w terminals MYCT can be used to reverse
; the IDL black & white (#0) colortable
MYCT, /DIAL, NCOLORS=120
; Loads the DIAL LIDAR color table with 120 colors
MYCT, /BuYlYlRd
MYCT, 'RdBu', /MIDCOLORPRESENT, /YELLOW, NCOLORS=20
; Both of these commands do the same thing: loads
; the ColorBrewer "RdBu" colortable and inserts yellow
; into the 2 middle colors. This is a good choice
; if you are creating an absolute or % difference plot.
MODIFICATION HISTORY:
mgs, 06 Feb 1997: VERSION 1.00
mgs, 03 Aug 1997: - added input parameter and template
mgs, 26 Mar 1998: - added NCOLORS keyword
mgs, 06 Apr 1998: - added BOTTOM, RANGE, and RGB keywords
mgs, 04 May 1998: - added test for null device
mgs, 03 Jun 1998: - return if !D.N_COLORS is less than 3 (b/w)
mgs, 16 Jun 1998: - bug fix: range check now after tvlct
mgs, 18 Jul 1998: - bug re-visited, added HLS keyword and changed
default to HSV. Also added SATURATION and
VALUE keywords.
mgs, 12 Aug 1998: - re-written with bug fixes and more concise.
removed RGB and HLS keywords, added REVERSE
and NO_STD keywords.
mgs, 14 Jan 1999: - limit oldcolors and ncolors to MaxColors (256)
on PC with TrueColor Graphics to ensure
compatibility with Unix.
bmy, 26 Sep 2002: TOOLS VERSION 1.51
- added /DIAL keyword to specify the DIAL/LIDAR
colortable from Ed Browell et al.
- now save MYCT parameters into a system variable
so that plotting routines can access them.
bmy, 22 Oct 2002: TOOLS VERSION 1.52
- fixed minor bugs in defining the !MYCT variable
bmy, 28 May 2004: TOOLS VERSION 2.02
- removed TESTMYCT routine, it's obsolete
- Bug fix: make sure RANGE is defined before
saving it to the !MYCT variable
bmy, 09 Jun 2005: TOOLS VERSION 2.04
- Added default value for RANGE keyword
bmy, 05 Oct 2006: TOOLS VERSION 2.05
- Now also define the DIFFERENCE color table
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now calls CUSTOM_COLORTABLE to define
several custom colortables
- Now allow /REVERSE to reverse custom
color table indices
- Added /VERBOSE keyword for printing info
about the selected color table
- Added /BuWhWhRd keyword for the
BLUE-WHITE-WHITE-RED colortable
- Added /BuYlYlRd keyword for the
BLUE-YELLOW-YELLOW-RED colortable
- Added /UserDef keyword to select
a user-defined color table.
cdh & bmy, 19 Nov 2007: GAMAP VERSION 2.11
- Now implement newer, less-saturated MYCT
drawing colors as defaults
- Added /BRIGHT_COLORS keyword to use
the older drawing colors for backwards
compatibility.
phs, 17 Apr 2008: GAMAP VERSION 2.12
- Now passes _extra to LOADCT, so a different
table file (*.tbl) can be used for example.
- bug fix: ncolors is correctly passed to
LOADCT if RANGE is not set.
- Added the XINTERACTIVE keyword to use
XCOLORS instead of LOADCT when no custom
table is loaded.
- Now use extra !MYCT tags: NAME, INDEX, FILE
- Added MIDCOLORPRESENT, USE_CURRENT keywords
phs, 22 Sep 2008: GAMAP VERSION 2.13
- Re-Added UserDef keyword. Users can define
(and then load) their own color table in the
Define_UserDef subroutine.
(See /n/home09/ryantosca/IDL/gamap2/color/myct.pro)
NAME:
MYCT_DEFAULTS (function)
PURPOSE:
Returns a structure associating the names of MYCT
drawing colors with their numeric values, plus
the default bottom and number of colors.
CATEGORY:
Color
CALLING SEQUENCE:
C = MYCT_DEFAULTS()
INPUTS:
None
KEYWORD PARAMETERS:
/GRAYSCALE -> If set, will define a grayscale colortable
such that the lowest color is white, and the highest
color is dark grey. Otherwise the standard "TRACE-P"
colortable (based on Mac Style #25) will be defined.
NCOLORS -> Specifies the number of colors for MYCT. The
default is 120, but if your terminal can support more,
you may specify a higher value.
OUTPUTS:
C -> Structure with the following tag names:
WHITE : Color index for "drawing color" WHITE
BLACK : Color index for "drawing color" BLACK
RED : Color index for "drawing color" RED
GREEN : Color index for "drawing color" GREEN
BLUE : Color index for "drawing color" BLUE
ORANGE : Color index for "drawing color" ORANGE
PURPLE : Color index for "drawing color" PURPLE
LIGHTRED : Color index for "drawing color" LIGHTRED
LIGHTGREEN : Color index for "drawing color" LIGHTGREEN
LIGHTBLUE : Color index for "drawing color" LIGHTBLUE
LIGHTORANGE : Color index for "drawing color" LIGHTORANGE
LIGHTPURPLE : Color index for "drawing color" LIGHTPURPLE
YELLOW : Color index for "drawing color" YELLOW
MAGENTA : Color index for "drawing color" MAGENTA
CYAN : Color index for "drawing color" CYAN
GRAY85 : Color index for "drawing color" 85% GRAY
GRAY67 : Color index for "drawing color" 67% GRAY
DARKGRAY : Color index for "drawing color" 67% GRAY
GRAY50 : Color index for "drawing color" 50% GRAY
MEDIUMGRAY : Color index for "drawing color" 50% GRAY
GRAY33 : Color index for "drawing color" 33% GRAY
GRAY : Color index for "drawing color" 33% GRAY
LIGHTGRAY : Color index for "drawing color" 33% GRAY
GRAY15 : Color index for "drawing color" 15% GRAY
FILE : Name of the color table (*.tbl) file
NAME : Color table name
INDEX : Color table index
BOTTOM : Color table starts at this index
NCOLORS : Number of colors
RANGE : Range of IDL color table to be used
SAT : Saturation value for MYCT
VALUE : Hue value for MYCT
REVERSE : REVERSE=1 means light --> dark
REVERSE=0 means dark --> light
SUBROUTINES:
None
REQUIREMENTS:
Designed to be used by the GAMAP routine "myct.pro".
NOTES:
(1) This routine is designed to be called by MYCT_DEFINE.
You should not normally have to call MYCT_DEFAULTS.
(2) MYCT defines a colortable such that the first 17
colors are "drawing" colors, or pure colors intended
for use with the PLOT, CONTOUR, MAP_SET, etc. commands.
MYCT then loads a standard IDL colortable (with NCOLORS
specifying the number of individual colors) into color
indices 18 and higher.
(3) New drawing colors (that are less saturated and
easier to read on the screen) are now the defaults.
See the documentation to the MYCT routine for more info.
EXAMPLE:
C = MYCT_DEFAULTS()
; Defines a grayscale colortable for use w/ MYCT.
MODIFICATION HISTORY:
bmy, 23 Jul 2001: TOOLS VERSION 1.48
- adapted from "default_colors.pro"
bmy, 04 Feb 2004: TOOLS VERSION 2.01
- Increased grayscale color range slightly
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- renamed DIAL to CUSTOM, to reflect that
we have other custom colortables in use
cdh & bmy, 19 Nov 2007: GAMAP VERSION 2.11
- Added names for the new MYCT drawing colors
bmy, 21 Apr 2008: GAMAP VERSION 2.12
- Removed obsolete settings and keywords
- Removed IS_CUSTOM tag name from !MYCT
- Added INDEX, FILE tag names to !MYCT
(See /n/home09/ryantosca/IDL/gamap2/color/myct_defaults.pro)
NAME:
MYCT_DEFINE
PURPOSE:
Defines the !MYCT system variable with default values.
!MYCT is used to make colortable parameters available to
plotting programs.
CATEGORY:
Color
CALLING SEQUENCE:
MYCT_DEFINE
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
MYCT_DEFAULTS (function)
REQUIREMENTS:
None
NOTES:
This routine should be called from your "idl_startup.pro"
batch file, so that !MYCT will be defined and ready for
use by all other routines that need it.
EXAMPLE:
MYCT_DEFINE
; Defines the !MYCT system variable
MODIFICATION HISTORY:
bmy, 30 Sep 2002: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/color/myct_define.pro)
NAME:
XCOLORS
PURPOSE:
The purpose of this routine is to interactively change color tables
in a manner similar to XLOADCT. No common blocks are used so
multiple copies of XCOLORS can be on the display at the same
time (if each has a different TITLE). XCOLORS has the ability
to notify a widget event handler, an object method, or an IDL
procedure if and when a new color table has been loaded. The
event handler, object method, or IDL procedure is then responsibe
for updating the program's display on 16- or 24-bit display systems.
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:
Color
CALLING SEQUENCE:
XCOLORS
INPUTS:
None.
KEYWORD PARAMETERS:
BLOCK: If this keyword is set, the program will try to block the
IDL command line. Note that this is only possible if no other
widget program is currently blocking the IDL command line. It
is much more reliable to make XCOLORS a modal widget (see the MODAL
keyword), although this can generally only be done when XCOLORS
is called from another widget program.
BOTTOM: The lowest color index of the colors to be changed.
COLORINFO: This output keyword will return either a pointer to
a color information structure (if the program is called in
a non-modal fashion) or a color information structure (if the program
is called in modal or blocking fashion). The color information
structure is an anonymous structure defined like this:
struct = { R: BytArr(!D.Table_Size), $ ; The current R color vector.
G: BytArr(!D.Table_Size), $ ; The current G color vector.
B: BytArr(!D.Table_Size), $ ; The current B color vector.
NAME: "", $ ; The name of the current color table.
INDEX: 0 } ; The index number of the current color table.
If a pointer to the structure is obtained, you will be responsible
for freeing it to prevent memory leakage:
XColors, ColorInfo=colorInfoPtr
Print, "Color Table Name: ", (*colorInfoPtr).Name
Ptr_Free, colorInfoPtr
Note that that Name field will be "Unknown" and the Index field will
be -1 until a color table is actually selected by the user. You are
responsible for checking this value before you use it.
When called in modal or blocking fashion, you don't have to worry about freeing
the pointer, since no pointer is involved:
XColors, /Block, ColorInfo=colorInfoData
Help, colorInfoData, /Structure
Print, "Color Table Name: ", colorInfoData.Name
DATA: This keyword can be set to any valid IDL variable. If
the variable is defined, the specified object method or notify
procedure will be passed this variable via a DATA keyword. This
keyword is defined primarily so that Notify Procedures are compatible
with the XLOADCT way of passing data. It is not strictly required,
since the _EXTRA keyword inheritance mechanism will allow passing
of *any* keyword parameter defined for the object or procedure that is
to be notified.
DRAG: Set this keyword if you want colors loaded as you drag
the sliders. Default is to update colors only when you release
the sliders.
_EXTRA: This keyword inheritance mechanism will pick up and
pass along to any method or procedure to be notified and keywords
that are defined for that procedure. Note that you should be sure
that keywords are spelled correctly. Any mis-spelled keyword will
be ignored.
FILE: A string variable pointing to a file that holds the
color tables to load. The normal colors1.tbl file is used by default.
GROUP_LEADER: The group leader for this program. When the group
leader is destroyed, this program will be destroyed.
INDEX: The index of the color table to start up. If provided, a color
table of this index number is loaded prior to display. Otherwise,
the current color table is used. Set this keyword if you wish
to have the index number of the event structure correct when
the user CANCELs out of the progam.
MODAL: Set this keyword (along with the GROUP_LEADER keyword) to
make the XCOLORS dialog a modal widget dialog. Note that NO
other events can occur until the XCOLORS program is destroyed
when in modal mode.
NCOLORS: This is the number of colors to load when a color table
is selected.
NOSLIDERS: If this keyword is set, the color stretch and color gamma
sliders are not displayed. This would be appropriate, for example,
for programs that just load pre-defined color tables.
NOTIFYID: A 2-column by n-row array that contains the IDs of widgets
that should be notified when XCOLORS loads a color table. The first
column of the array is the widgets that should be notified. The
second column contains IDs of widgets that are at the top of the
hierarchy in which the corresponding widgets in the first column
are located. (The purpose of the top widget IDs is to make it
possible for the widget in the first column to get the "info"
structure of the widget program.) An XCOLORS_LOAD event will be
sent to the widget identified in the first column. The event
structure is defined like this:
event = {XCOLORS_LOAD, ID:0L, TOP:0L, HANDLER:0L, $
R:BytArr(!D.TABLE_SIZE < 256), G:BytArr(!D.TABLE_SIZE < 256), $
B:BytArr(!D.TABLE_SIZE < 256), INDEX:0, NAME:""}
The ID field will be filled out with NOTIFYID[0, n] and the TOP
field will be filled out with NOTIFYID[1, n]. The R, G, and B
fields will have the current color table vectors, obtained by
exectuing the command TVLCT, r, g, b, /Get. The INDEX field will
have the index number of the just-loaded color table. The name
field will have the name of the currently loaded color table.
Note that XCOLORS can't initially tell *which* color table is
loaded, since it just uses whatever colors are available when it
is called. Thus, it stores a -1 in the INDEX field to indicate
this "default" value. Programs that rely on the INDEX field of
the event structure should normally do nothing if the value is
set to -1. This value is also set to -1 if the user hits the
CANCEL button. (Note the NAME field will initially be "Unknown").
Typically the XCOLORS button will be defined like this:
xcolorsID = Widget_Button(parentID, Value='Load New Color Table...', $
Event_Pro='Program_Change_Colors_Event')
The event handler will be written something like this:
PRO Program_Change_Colors_Event, event
; Handles color table loading events. Allows colors be to changed.
Widget_Control, event.top, Get_UValue=info, /No_Copy
thisEvent = Tag_Names(event, /Structure_Name)
CASE thisEvent OF
'WIDGET_BUTTON': BEGIN
; Color table tool.
XColors, NColors=info.ncolors, Bottom=info.bottom, $
Group_Leader=event.top, NotifyID=[event.id, event.top]
ENDCASE
'XCOLORS_LOAD': BEGIN
; Update the display for 24-bit displays.
Device, Get_Visual_Depth=thisDepth
IF thisDepth GT 8 THEN BEGIN
WSet, info.wid
...Whatever display commands are required go here. For example...
TV, info.image
ENDIF
ENDCASE
ENDCASE
Widget_Control, event.top, Set_UValue=info, /No_Copy
END
NOTIFYOBJ: A vector of structures (or a single structure), with
each element of the vector defined as follows:
struct = {XCOLORS_NOTIFYOBJ, object:Obj_New(), method:''}
where the Object field is an object reference, and the Method field
is the name of the object method that should be called when XCOLORS
loads its color tables.
ainfo = {XCOLORS_NOTIFYOBJ, a, 'Draw'}
binfo = {XCOLORS_NOTIFYOBJ, b, 'Display'}
XColors, NotifyObj=[ainfo, binfo]
Note that the XColors program must be compiled before these structures
are used. Alternatively, you can put this program, named
"xcolors_notifyobj__define.pro" (*three* underscore characters in this
name!) in your PATH:
PRO XCOLORS_NOTIFYOBJ__DEFINE
struct = {XCOLORS_NOTIFYOBJ, OBJECT:Obj_New(), METHOD:''}
END
Or, you can simply define this structure as it is shown here in your code.
"Extra" keywords added to the XCOLORS call are passed along to
the object method, which makes this an alternative way to get information
to your methods. If you expect such keywords, your methods should be defined
with an _Extra keyword.
NOTIFYPRO: The name of a procedure to notify or call when the color
tables are loaded. If the DATA keyword is also defined, it will
be passed to this program via an DATA keyword. But note that *any*
keyword appropriate for the procedure can be used in the call to
XCOLORS. For example, here is a procedure that re-displays and image
in the current graphics window:
PRO REFRESH_IMAGE, Image=image, _Extra=extra, WID=wid
IF N_Elements(wid) NE 0 THEN WSet, wid
TVIMAGE, image, _Extra=extra
END
This program can be invoked with this series of commands:
IDL> Window, /Free
IDL> TVImage, image, Position=[0.2, 0.2, 0.8, 0.8]
IDL> XColors, NotifyPro='Refresh_Image', Image=image, WID=!D.Window
Note that "extra" keywords added to the XCOLORS call are passed along to
your procedure, which makes this an alternative way to get information
to your procedure. If you expect such keywords, your procedure should
be defined with an _Extra keyword as illustrated above.
TITLE: This is the window title. It is "Load Color Tables" by
default. The program is registered with the name 'XCOLORS:' plus
the TITLE string. The "register name" is checked before the widgets
are defined. If a program with that name has already been registered
you cannot register another with that name. This means that you can
have several versions of XCOLORS open simultaneously as long as each
has a unique title or name. For example, like this:
IDL> XColors, NColors=100, Bottom=0, Title='First 100 Colors'
IDL> XColors, NColors=100, Bottom=100, Title='Second 100 Colors'
XOFFSET: This is the X offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
YOFFSET: This is the Y offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Colors are changed. Events are sent to widgets if the NOTIFYID
keyword is used. Object methods are called if the NOTIFYOBJ keyword
is used. This program is a non-blocking widget.
RESTRICTIONS:
None.
EXAMPLE:
To load a color table into 100 colors, starting at color index
50 and send an event to the widget identified at info.drawID
in the widget heirarchy of the top-level base event.top, type:
XCOLORS, NCOLORS=100, BOTTOM=50, NOTIFYID=[info.drawID, event.top]
MODIFICATION HISTORY:
Written by: David W. Fanning, 15 April 97. Extensive modification
of an older XCOLORS program with excellent suggestions for
improvement by Liam Gumley. Now works on 8-bit and 24-bit
systems. Subroutines renamed to avoid ambiguity. Cancel
button restores original color table.
23 April 1997, added color protection for the program. DWF
24 April 1997, fixed a window initialization bug. DWF
18 June 1997, fixed a bug with the color protection handler. DWF
18 June 1997, Turned tracking on for draw widget to fix a bug
in TLB Tracking Events for WindowsNT machines in IDL 5.0. DWF
20 Oct 1997, Changed GROUP keyword to GROUP_LEADER. DWF
19 Dec 1997, Fixed bug with TOP/BOTTOM reversals and CANCEL. DWF.
9 Jun 1998, Fixed bug when using BOTTOM keyword on 24-bit devices. DWF
9 Jun 1998, Added Device, Decomposed=0 for TrueColor visual classes. DWF
9 Jun 1998, Removed all IDL 4 compatibility.
21 Oct 1998, Fixed problem with gamma not being reset on CANCEL. DWF
5 Nov 1998. Added the NotifyObj keyword, so that XCOLORS would work
interactively with objects. DWF.
9 Nov 1998. Made slider reporting only at the end of the drag. If you
want continuous updating, set the DRAG keyword. DWF.
9 Nov 1998. Fixed problem with TOP and BOTTOM sliders not being reset
on CANCEL. DWF.
10 Nov 1998. Fixed fixes. Sigh... DWF.
5 Dec 1998. Added INDEX field to the XCOLORS_LOAD event structure. This
field holds the current color table index number. DWF.
5 Dec 1998. Modified the way the colorbar image was created. Results in
greatly improved display for low number of colors. DWF.
6 Dec 1998. Added the ability to notify an unlimited number of objects. DWF.
12 Dec 1998. Removed obsolete Just_Reg keyword and improved documetation. DWF.
30 Dec 1998. Fixed the way the color table index was working. DWF.
4 Jan 1999. Added slightly modified CONGRID program to fix floating divide
by zero problem. DWF
2 May 1999. Added code to work around a Macintosh bug in IDL through version
5.2 that tries to redraw the graphics window after a TVLCT command. DWF.
5 May 1999. Restore the current window index number after drawing graphics.
Not supported on Macs. DWF.
9 Jul 1999. Fixed a couple of bugs I introduced with the 5 May changes. Sigh... DWF.
13 Jul 1999. Scheesh! That May 5th change was a BAD idea! Fixed more bugs. DWF.
31 Jul 1999. Substituted !D.Table_Size for !D.N_Colors. DWF.
1 Sep 1999. Got rid of the May 5th fixes and replaced with something MUCH simpler. DWF.
14 Feb 2000. Removed the window index field from the object notify structure. DWF.
14 Feb 2000. Added NOTIFYPRO, DATA, and _EXTRA keywords. DWF.
20 Mar 2000. Added MODAL, BLOCK, and COLORINFO keywords. DWF
20 Mar 2000. Fixed a slight problem with color protection events triggering
notification events. DWF.
31 Mar 2000. Fixed a problem with pointer leakage on Cancel events, and improved
program documentation. DWF.
17 Aug 2000. Fixed a problem with CANCEL that occurred only if you first
changed the gamma settings before loading a color table. DWF.
10 Sep 2000. Removed the requirement that procedures and object methods must
be written with an _Extra keyword. DWF.
5 Oct 2000. Added the File keyword to LOADCT command, as I was suppose to. DWF.
5 Oct 2000. Now properly freeing program pointers upon early exit from program. DWF.
7 Mar 2001. Fixed a problem with the BLOCK keyword. DWF.
12 Nov 2001. Renamed Congrid to XColors_Congrid. DWF.
14 Aug 2002. Moved the calculation of NCOLORS to after the draw widget creation
to fix a problem with !D.TABLE_SIZE having a correct value when no windows had
been opened in the current IDL session. DWF.
14 Aug 2002. Fixed a documentation problem in the NOTIFYID keyword documentation
that still referred to !D.N_COLORS instead of the current !D.TABLE_SIZE. DWF.
27 Oct 2003. Added INDEX keyword. DWF.
29 July 2004. Fixed a problem with freeing colorInfoPtr if it didn't exist. DWF.
5 December 2005. Added NOSLIDERS keyword and performed some small cosmetic changes. DWF.
27 Sep 2006. Fixed a problem in which XCOLORS set device to indexed color mode. DWF.
bmy, 21 Apr 2008: GAMAP VERSION 2.12
- Added XCOLORS into GAMAP v2-12 unmodified,
except for minor comment header changes, e.g.:
* added ID tag for CVS repository
* also changed category to "Color" for
compatibility w/ GAMAP documentation
(See /n/home09/ryantosca/IDL/gamap2/color/xcolors.pro)