The purpose of this routine is to add a discrete color bar to
a graphics plot. A "discrete" color bar is one with a handful
of colors. Labels are centered beneath or beside the color fields.
colors, in, required
A vector of "colors" to be represented in the color bar. The vector can be a
vector of color "names" that are known to cgColor. Or, it can be a vector of
24-bit color values that can be decomposed into color triples. Or, it can be a
vector of byte or integer values that can be used as indices into the current
color table. If both colors and NCOLORS (see below) are undefined, a 10-element
color table will be loaded and used.
addcmd: in, optional, type=boolean, default=0
Set this keyword to add the command to the resizeable graphics window cgWindow.
barcolor: in, optional, type=string
This is the name of a color known to cgCOLOR that can be used to draw the color
bar outlines. By default, the same as specified with the COLOR keyword.
bottom: in, optional, type=integer, default=0
The lowest color index of the colors to be loaded in the color bar.
charpercent: in, optional, type=float, default=0.85
A value from 0.0 go 1.0 that is multiplied by the CHARSIZE to produce
the character size for the color bar. This value is only used if CHARSIZE is
undefined. This keyword is primarily useful for using color bars in resizeable
graphics windows (cgWindow).
charsize: in, optional, type=float
The character size of the color bar annotations. Default is cgDefCharsize()*charPercent.
color: in, optional, type=string, default="opposite"
The name of the color to use for color bar annotations.
filename: in, optional, type=string
The name of a color table file that can be read by cgCOLOR. This allows you to
specify your own color names for your own colors.
fit: in, optional, type=boolean, default=0
If this keyword is set, the colorbar tries to "fit" itself to the normalized
coordinates of the last graphics command executed. In other words, for
a horizontal color bar, postition[[0,2]] = !X.Window, and for a vertical
color bar, position[[1,3]] = !Y.Window. Other positions are adjusted
to put the colorbar "reasonably" close to the plot. Because there are so many
ways this colorbar can be displayed, the "fit" may not always be a good one.
If you are fitting to an image, be sure to set the SAVE keyword on cgImage
to establish a data coordinate system.
font: in, optional, type=integer, default=!P.Font
Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
labels: in, optional, type=string
An array of string labels that should annotate each color. Must be the same length
as the colors vector. Colors are labelled consecutively by default.
ncolors: in, optional, type=integer, default=256
An alternative way to specify the colors in the color bar is by
using the NCOLORS and BOTTOM keywords to locate the colors in the
current color table. The NCOLORS and BOTTOM keywords have the same
meaning as in the LOADCT, XLOADCT, XCOLORS, or cgCOLORBAR programs.
position: in, optional, type=float
A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is [0.88, 0.10, 0.95, 0.90]
for a vertical bar and [0.10, 0.88, 0.90, 0.95] for a horizontal bar.
See the FIT keyword, also.
right: in, optional, type=boolean, default=0
This puts the title on the right-hand side of a vertical color bar. It applies
only to vertical color bars.
rotate: in, optional, type=float, default=0.0
Set this keyword to a value that will rotate the label text.
Positive values between 0 and 180 degrees rotate in a counter-clockwise
sense. Negative values between 0 and 180 degress rotate in a
spacing: in, optional, type=float, default=1.0
When labels are rotated, it is a little difficult to determine where,
exactly, they should be located. This keyword gives the user some control
over this location. The location "spacer" is multiplied by this amount.
So, for example, to move the labels a little further away from the color bar,
make this number greater than 1 (e.g, 1.25). To move the labels a little closer,
use a number less than 1 (e.g, 0.75).
tcharsize: in, optional, type=float
The character size of the title. By default, set to cgDefCharsize().
treverse: in, optional, type=boolean, default=0
Set this keyword to reverse the direction of the title on a vertical color bar.
title: in, optional, type=string, default=""
This is title for the color bar. The default is to have no title.
vertical: in, optional, type=boolean, default=0
Setting this keyword give a vertical color bar. The default is a horizontal color bar.
window: in, optional, type=boolean, default=0
Set this keyword to display the plot in a resizeable graphics window (cgWindow).
To display a 12 color horizontal color bar, labels with a three-letter
cgLoadCT, 5, NCOLORS=12, BOTTOM=1
cgDCBar, NCOLORS=12, BOTTOM=1, LABELS=theMonths(/Abbreviation)
To load a 5 color vertical color bar, with the labels rotated 45 degrees::
labels = StrArr(5)
FOR j=0,4 DO labels[j] = 'City ' + StrTrim(j+1,2)
colors = ['dodger blue', 'yellow', 'forest green', 'purple', 'tan']
cgDCBar, colors, LABELS=labels, ROTATE=45, /VERTICAL
FANNING SOFTWARE CONSULTING::
David W. Fanning
1645 Sheely Drive
Fort Collins, CO 80526 USA
Coyote's Guide to IDL Programming: http://www.idlcoyote.com
Written by: David W. Fanning, 15 March 2009.
Modification to code to avoid changing the colors vectors. 15 March 2009.
Added FONT keyword. 1 April 2009. DWF.
Code modified to support 24-bit PostScript printers. 23 September 2009. DWF.
Fixed a problem with determining visual depth in Z-buffer. 15 January 2010. DWF.
Added SPACING keyword and changed the default spacing on horizontal color bars slightly. 23 Apr 2010. DWF.
Modified the spacing of the labels on the color bar, specifically for the PostScript device. 3 November 2010. DWF.
Added Window and AddCmd keywords. 28 Jan 2011. DWF.
Added a Right keyword and changed the title spacing a little bit for aesthetic reasons. 2 July 2011. DWF.
Fixed a problem with assigning the color with the COLOR keyword in the Z-buffer. 30 Aug 2011. DWF.
The default BOTTOM keyword value was incorrect. Fixed in this version. 5 December 2011. DWF.
Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF.
Previous change incorrectly implemented for PS device. Fixed. 29 Dec 2011. DWF.
Added CHARPERCENT, FIT, and TREVERSE keywords. Cleaned up documentation. 20 March 2012. DWF.
Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF.
Copyright (c) 2009-2012, Fanning Software Consulting, Inc.