ColorBar TCL UTILITIES USER MANUAL ColorBar
SYNOPSIS
Draw and annotate a colorbar
PACKAGE
TCLPLT
NAME
ColorBar
USAGE
set rV  [ColorBar  wID X1 Y1 Z1 X2 Y2 Z2 cInFo cMapP cMapS {Sep}]
INPUT DEFINITIONS
wID - The graphics window in which to output the colorbar.
X1 - The position of the lower X edge of the colorbar in wID. The position is given in terms of the absolute or relative window scaling depending on the setting of cInfo(POS) (see table in Description field below).
Y1 - The position of the lower Y edge of the colorbar in wID. The position is given in terms of the absolute or relative window scaling depending on the setting of cInfo(POS) (see table in Description field below).
Z1 - The position of the nearer Z edge of the colorbar in wID. The position is given in terms of the absolute or relative window scaling depending on the setting of cInfo(POS) (see table in Description field below). It is ignored in the Tk driver but possibly not in the VTK driver.
X2 - The position of the upper X edge of the colorbar in wID if the colarbar format specified in cInfo is not WHEEL, otherwise it is the diameter of the color wheel. The position or diameter is given in terms of the absolute or relative window scaling depending on the setting of cInfo(POS) (see table in Description field below).
Y2 - The position of the right Y edge of the colorbar in wID. The position is given in terms of the absolute or relative window scaling depending on the setting of cInfo(POS) (see table in Description field below). It is ignored if the colorbar format is set to WHEEL.
Z2 - The position of the outer Z edge of the colorbar in wID. The position is given in terms of the absolute or relative window scaling depending on the setting of cInfo(POS) (see table in Description field below). It is ignored if the colorbar format is set to WHEEL and is ignored in the Tk driver but possibly not in the VTK driver.
cInfo - An array of values which specifies all of the parameters to be used in generating the colorbar. Unspecified values are set to defaults. The complete list of parameters is given in the procedure description below.
cMapP - The color mapping array associated with the PRIMARY colorbar axis. This is used by many routines which convert value to a color table index.
cMapS - The color mapping array associated with the SECONDARY colorbar axis. This is used by many routines which convert value to a color table index. NOTE: Color wheels only have a PRIMARY axis associated with them
Sep - An optional input value used to specify the list separators used in list entries in cInfo. The value is defaulted to :. If set to a space (" ") the list entry must be specified as [list ...] otherwise it can just be specified as ValueSepValueSep...
RETURN DEFINITION
Returns the window number associated with the colorbar. This is also the plot colorbar plot number.
DESCRIPTION
ColorBar outputs and annotates a colorbar or color wheel in the window wID. Colorbars have their lower left-hand corner at (X1, Y1, Z1) and their upper right-hand corner at (X2, Y2, Z2). Color wheels are output in a square window which has its lower left-hand corner at (X1, Y1, Z1) and a diameter of X2. Positions are given in terms of the absolute or relative window scaling of wID depending on the setting of cInfo(POS). With the exception of the WHEEL format, all colorbars support both a primary and secondary axis. There are the axis which are ticked and annotated. The color wheel has only a primary axis.
All aspects of the colorbar are described in the cInfo array. This provides the colorbar output format, the scaling, and all of the annotation options. A complete listing of the array elements is given in the table below.
INDEX DEFAULT DESCRIPTION
pMIN Minimum value used in the mapping of the primary colorbar axis.
pMAX Maximum value used in the mapping of the primary colorbar axis.
pSCA NONE Scaling used in the mapping of the primary colorbar axis. This can be LINEAR, LOG or NONE where NONE indicates that the primary colorbar axis is not used.
sMIN Minimum value used in the mapping of the secondary colorbar axis.
sMAX Maximum value used in the mapping of the secondary colorbar axis.
sSCA NONE Scaling used in the mapping of the secondary colorbar axis. This can be LINEAR, LOG or NONE where NONE indicates that the secondary colorbar axis is not used.
WHITE NO Set to YES to include the color white in the colorbar otherwise set to NO.
POS RELATIVE Set to ABSOLUTE if the colorbar position in wID is given in absolute window coordinates, otherwise set to RELATIVE.
AXIS ON Set to ON to draw an axis (outline) the colorbar, otherwise set to OFF.
ANNOTATE YES Set to YES to outline, to output tick marks and to annotate the colorbar otherwise set to NO.
FMT VERTICAL The colorbar format. This can be either VERTICAL, RHORIZONTAL, LHORIZONTAL or WHEEL. In a VERTICAL colorbar the PRIMARY axis is the right Y axis and the SECONDARY axis in the left Y axis. In a HORIZONTAL colorbar the PRIMARY axis is the lower X axis and the SECONDARY axis is the upper X axis. The LHORIZONTAL outputs the colorbar with the minimum value to the left edge while RHORIZONTAL outputs the minimum value at the right edge. WHEEL has only a PRIMARY axis defined which is at the outer edge of the wheel.
NLEV 0.0:0.0 A two element list giving the distance in characters of any numerical annotation from the colorbar PRIMARY and SECONDARY axis respectively. Either or both of the list elements may be left undefined.
LEV 1.5:1.5 A two element list giving the distance in characters of any text annotation from the numerical output along the colorbar PRIMARY and SECONDARY axis respectively. Either or both of the list elements may be left undefined.
PRIMARY 1:1:1 A 3 element list with each element indicating if a particular axis feature should be drawn along the PRIMARY axis. The list elements are the major tick marks, minor tick marks, and numerical annotation respectively. Set the corresponding element to 1 to output otherwise set to 0 or OFF. Note: The default value for numerical annotation is set to 1 only when cInfo(pSCA) is not NONE. It is zero otherwise.
SECONDARY 1:1:1 A 3 element list with each element indicating if a particular axis feature should be drawn along the SECONDARY axis. The list elements are the major tick marks, minor tick marks, and numerical annotation respectively. Set the corresponding element to 1 to output otherwise set to 0 or OFF. Note: The default value for numerical annotation is set to 1 only when cInfo(sSCA) is not NONE. It is zero otherwise.
PSIZE 0.2:0.1:12 A 4 element list specifying tick mark and annotation sizes to use along the PRIMARY axis. The list elements are the major tick mark length, minor tick mark length, numerical annotation point size and axis text annotation point size respectively. Any value in the list set to HOLD will keep its default value.
SSIZE 0.2:0.1:12 A 4 element list specifying tick mark and annotation sizes to use along the SECONDARY axis. The list elements are the major tick mark length, minor tick mark length, numerical annotation point size and axis text annotation point size respectively. Any value in the list set to HOLD will keep its default value.
PFMTS INSIDE:INSIDE:%.1f A 3 element list specifying tick mark and numerical annotation formats to use along the PRIMARY axis. The list elements are the major tick mark format, minor tick mark format and numerical annotation format respectively. Any value in the list set to HOLD will keep its default value. Tick mark formats can be any of INSIDE, OUTSIDE, STRADDLE, or SPAN. The major tick mark format for WHEEL defaults to SPAN. The numerical annotation format can be any "C" format specification or expon which outputs just the value base 10 exponent.
SFMTS INSIDE:INSIDE:%.1f A 3 element list specifying tick mark and numerical annotation formats to use along the SECONDARY axis. The list elements are the major tick mark format, minor tick mark format and numerical annotation format respectively. Any value in the list set to HOLD will keep its default value. Tick mark formats can be any of INSIDE, OUTSIDE, STRADDLE, or SPAN. The major tick mark format for WHEEL defaults to SPAN. The numerical annotation format can be any "C" format specification or expon which outputs just the value base 10 exponent.
PNUMS 10:5 A 2 element list specifying number of major and minor tick mark along the PRIMARY axis. The list elements are the number of major tick marks and the number of minor tick marks respectively. Any value in the list set to HOLD will keep its default value.
SNUMS 10:5 A 2 element list specifying number of major and minor tick mark along the SECONDARY axis. The list elements are the number of major tick marks and the number of minor tick marks respectively. Any value in the list set to HOLD will keep its default value.
PCOLORS 255:255:255 A 3 element list specifying tick mark and annotation colors to use along the PRIMARY axis. The list elements are the major tick mark color, minor tick mark color and annotation color respectively. Any value in the list set to HOLD will keep its default value (white).
SCOLORS 255:255:255 A 3 element list specifying tick mark and annotation colors to use along the SECONDARY axis. The list elements are the major tick mark color, minor tick mark color and annotation color respectively. Any value in the list set to HOLD will keep its default value (white).
SCOLORS "":"" A 2 element list specifying the axis labels to use along the PRIMARY and SECONDARY axes respectively. Setting either value in the list set to HOLD will keep its default value.
ERRORS
None Generated
C BACKING
No
EXAMPLE(S)
EXAMPLE 1: Examples of different colorbars. 
# READ the GUI preference settings

GUIprefsRead

# SET a window size

set GphInfo(xsScrL) 600
set GphInfo(ysScrL) 500
set GphInfo(xScrL) 600
set GphInfo(yScrL) 500

# START graphics

GraphicsOn TK RainBow

# ESTABLISH graphics window 

GenWindow 1 0.0 0.0 0.0 1.0 1.0  0.0 -6.0 -6.0 0.0 6.0 6 0.0

# SET some common options to use in generating the colorbars 

set cInfo(pMIN) 500.0
set cInfo(pMAX) 1500.0
set cInfo(pSCA) LINEAR
set cInfo(sMIN) 3.0e4
set cInfo(sMAX) 7.0e12
set cInfo(sSCA) LOG
set cInfo(FMT)  VERTICAL
set cInfo(PFMTS) HOLD:HOLD:%.1f
set cInfo(SFMTS) HOLD:HOLD:expon
set cInfo(LABELS) PRIMARY:SECONDARY
set cInfo(PSIZE) HOLD:HOLD:10:10
set cInfo(SSIZE) HOLD:HOLD:10:10

# PUT up a vertical colorbar along the left-hand side of the window.

ColorBar 1 -4.8 -5.0 0.0 -4.2 5.0 0.0 cInfo cMa cMb

# SET up some options for a color wheel format colorbar.  This only
#   supports a primary axis  

set cInfo(FMT)  WHEEL
set cInfo(pMIN) 3.0e4
set cInfo(pMAX) 4.0e12
set cInfo(pSCA) LOG
set cInfo(PFMTS) HOLD:HOLD:expon
set cInfo(NLEV) 0.5
set cInfo(LEV) 1.0

# OUTPUT a color wheel at the top of the window.

ColorBar 1 1.0 3.0 0.0 2.0 2.0 0.0 cInfo cMa cMb

# SET up some options for a LHORIZONTAL colorbar. 

set cInfo(pMIN) 500.0
set cInfo(pMAX) 1500.0
set cInfo(pSCA) LINEAR
set cInfo(FMT)  LHORIZONTAL
set cInfo(PFMTS) HOLD:HOLD:%.1f
set cInfo(NLEV) 0.0

# OUTPUT the LHORIZONTAL colorbar in the middle of the window

ColorBar 1 -2.0 -1.0 0.0 5.0 0.0 0.0 cInfo cMa cMb

# SET up some options for a RHORIZONTAL colorbar. 

set cInfo(FMT)  RHORIZONTAL
set cInfo(SFMTS) HOLD:HOLD:%.0e

# OUTPUT the RHORIZONTAL colorbar long the bottom of the window

ColorBar 1 -2.0 -4.5 0.0 5.0 -3.5 0.0 cInfo cMa cMb
Apr 7, 2007