.\

cgdcbar.pro

top cgDCBar

Graphics

cgDCBar, colors [, /ADDCMD] [, BARCOLOR=string] [, BOTTOM=integer] [, CHARPERCENT=float] [, CHARSIZE=float] [, COLOR=string] [, FILENAME=string] [, /FIT] [, FONT=integer] [, LABELS=string] [, NCOLORS=integer] [, POSITION=float] [, /RIGHT] [, ROTATE=float] [, SPACING=float] [, TCHARSIZE=float] [, /TREVERSE] [, TITLE=string] [, /VERTICAL] [, /WINDOW]

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.

The program requires the Coyote Library to be installed on your machine.

Parameters

colors

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.

Keywords

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 clockwise sense.

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

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).

Examples

To display a 12 color horizontal color bar, labels with a three-letter month abbreviation:

  cgDisplay
  cgLoadCT, 5, NCOLORS=12, BOTTOM=1
  cgDCBar, NCOLORS=12, BOTTOM=1, LABELS=cgMonths(/Abbreviation)

To load a 5 color vertical color bar, with the labels rotated 45 degrees:

  cgDisplay
  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

Author information

Author:

FANNING SOFTWARE CONSULTING:

   David W. Fanning
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: david@idlcoyote.com
   Coyote's Guide to IDL Programming: http://www.idlcoyote.com

Copyright:

History:

Change History:

 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.
 Fixed a problem in which the colors variable was set to long integers if the BOTTOM keyword was used with
     NCOLORS. 2 Oct 2013. DWF.

File attributes

Modification date:	Fri Mar 27 11:07:38 2015
Lines:	452
Docformat:	rst rst

Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015