top cgColorbar

Graphics

cgColorbar [, /ADDCMD] [, ANNOTATECOLOR=string] [, BOTTOM=integer] [, /BREWER] [, CHARPERCENT=float] [, CHARSIZE=float] [, CLAMP=float] [, COLOR=string] [, CTINDEX=integer] [, /DISCRETE] [, DIVISIONS=integer] [, /FIT] [, FONT=integer] [, FORMAT=string] [, /INVERTCOLORS] [, MAXRANGE=MAXRANGE] [, MINOR=integer] [, MINRANGE=float] [, NCOLORS=integer] [, NEUTRALINDEX=integer] [, NODISPLAY=NODISPLAY] [, OOB_FACTOR=float] [, OOB_HIGH=string] [, OOB_LOW=string] [, PALETTE=byte] [, POSITION=float] [, RANGE=float] [, /REVERSE] [, /RIGHT] [, TCHARSIZE=float] [, TEXTTHICK=float] [, TLOCATION=string] [, TICKINTERVAL=float] [, TICKLEN=float] [, TICKNAMES=string] [, TITLE=string] [, /TOP] [, /VERTICAL] [, /XLOG] [, XTICKINTERVAL=float] [, XTICKLAYOUT=integer] [, XTITLE=string] [, /YLOG] [, YTICKINTERVAL=float] [, YTICKLAYOUT=integer] [, YTITLE=string] [, /WINDOW] [, _REF_EXTRA=_REF_EXTRA]

Keywords

ADDCMD in optional type=boolean default=0

Set this keyword to add the command to the resizeable graphics window cgWindow.

ANNOTATECOLOR in optional type=string default=opposite

The name of the "annotation color" to use. The names are those for cgCOLOR. If this keyword is used, the annotation color is loaded after the color bar is displayed. This keyword is provided to maintain backward compatibility, but also to solve the potential problem of an extra line showing up in the color bar when the COLOR keyword is used in indexed color mode. In other words, use ANNOTATECOLOR in place of COLOR for complete color model independent results.

BOTTOM in optional type=integer default=0

The lowest color index of the colors to be loaded in the color bar.

BREWER in optional type=boolean default=0

This keyword is used only if the CTIndex keyword is used to select a color table number. Setting this keyword allows Brewer color tables to be used.

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.

CLAMP in optional type=float

A two-element array in data units. The color bar is clamped to these two values. This is mostly of interest if you are "window-leveling" an image. The clamp is set to the "window" of the color bar. Normally, when you are doing this, you would like the colors outside the "window" to be set to a neutral color. Use the NEUTRALINDEX keyword to set the netural color index in the color bar. (See the Examples section for more information.)

COLOR in optional type=string

The name of the color to use for color bar annotations. Ignored unless passed the name of a cgColor color. The default value is to use the ANNOTATECOLOR.

CTINDEX in optional type=integer

The index number of a color table. The Brewer and Reverse keywords will be checked to see how to load the color table into the Palette keyword. This keyword will take precidence over any colors that are loaded with the Palette keyword.

DISCRETE in optional type=boolean default=0

Set this keyword to configure certain properties of the color bar to make discrete color blocks for the color bar. This works best if you are using a handful of colors in the color bar (e.g, 8-16).

DIVISIONS in optional type=integer default=0

The number of divisions to divide the bar into. There will be (divisions + 1) annotations. When set to 0 (the default), the IDL Plot command detemines the number of divisions used.

FIT in optional type=boolean default=0

If this keyword is set, the colorbar "fits" 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. The fit many not always be accurate. 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.

FORMAT in optional type=string

The format of the color bar annotations. The dfault is to let the IDL Plot command determine how the color bar labels are formatted.

INVERTCOLORS in optional type=boolean default=0

Setting this keyword inverts the colors in the color bar.

MAXRANGE in optional

The maximum data value for the color bar annotation. Default is NCOLORS.

MINOR in optional type=integer default=2

The number of minor tick divisions.

MINRANGE in optional type=float default=0.0

The minimum data value for the bar annotation.

NCOLORS in optional type=integer default=256

This is the number of colors in the color bar.

NEUTRALINDEX in optional type=integer

This is the color index to use for color bar values outside the clamping range when clamping the color bar with the CLAMP keyword. If this keyword is absent, the highest color table value is used for low range values and the lowest color table value is used for high range values, in order to provide contrast with the clamped region. (See the Examples section for more information.)

NODISPLAY in optional

This keyword is obsolete and is no longer used.

OOB_FACTOR in optional type=float default=1.0

The default is to make the length of the out-of-bounds triangle the same distance as the height (or width, in the case of a vertical color bar) of the color bar. If you would prefer a shorted triangle length, set this keyword to a value less than zero (e.g., 0.5). If you prefer a longer length, set this keyword to a value greater than zero. The "standard" length will be multiplied by this value.

OOB_HIGH in optional type=string

The name of an out-of-bounds high color. This color will be represented by a triangle on the right or top of the color bar. If the color is a string byte value (e.g., "215"), then this color in the current color table is used. The color can also be a three-element color triple (e.g., [240, 200, 65]). Note, you can CANNOT use a long integer as a color table index number with this keyword. If you want to use a color table index number, be sure the number is a short integer, byte value, or a string (e.g, OOB_HIGH=200S, OOB_HIGH=200B, or OOB_HIGH='200').

OOB_LOW in optional type=string

The name of an out-of-bounds low color. This color will be represented by a triangle on the left or bottom of the color bar. If the color is a string byte value (e.g., "215"), then this color in the current color table is used. The color can also be a three-element color triple (e.g., [240, 200, 65]). Note, you can CANNOT use a long integer as a color table index number with this keyword. If you want to use a color table index number, be sure the number is a short integer, byte value, or a string (e.g, OOB_HIGH=200S, OOB_HIGH=200B, or OOB_HIGH='200').

PALETTE in optional type=byte

A color palette containing the RGB color vectors to use for the color bar. The program will sample NCOLORS from the color palette.

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.

RANGE in optional type=float

A two-element vector of the form [min, max]. Provides an alternative and faster way way of setting the MINRANGE and MAXRANGE keywords.

REVERSE in optional type=boolean default=0

An alternative keyword name (one I can actually remember!) for the INVERTCOLORS keyword. It reverses the colors in the color bar.

RIGHT in optional type=boolean default=0

This puts the labels on the right-hand side of a vertical color bar. It applies only to vertical color bars.

TCHARSIZE in optional type=float

The title size. By default, the same as Charsize. Note that this keyword is ignored for vertical color bars unless the title location (TLocation) is on the opposite side of the color bar from the color bar labels. This is a consequence of being upable to determine the length of color bar labels programmatically in this orientation.

TEXTTHICK in optional type=float default=1.0

Sets the thickness of the textual annotations on the color bar.

TLOCATION in optional type=string

The title location, which allows the user to set the title location independently of the colorbar labels. May be "TOP" or "BOTTOM" for horizontal color bars, and "LEFT" or "RIGHT" for vertical color bars.

TICKINTERVAL in optional type=float

Set this keyword to the interval spacing of major tick marks. Use this keyword in place of XTickInterval or YTickInterval keywords.

TICKLEN in optional type=float default=0.25

Set this keyword to the major tick length desired. Default is 0.25. Setting this keyword to a value greater than or equal to 0.5 will result in major tick marks extending the width of the color bar. Note that setting this keyword to 0.3 or greater will result in minor tick mark lengths being set to 0.01, which is almost too small to be seen. All direct graphics tick marks act in this (strange!) way.

TICKNAMES in optional type=string

A string array of names or values for the color bar tick marks. There should be divisions + 1 tick names in the array.

TITLE in optional type=string

This is title for the color bar. The default is to have no title.

TOP in optional type=boolean default=0

This puts the labels on top of the bar rather than under it. The keyword only applies if a horizontal color bar is rendered.

VERTICAL in optional type=boolean default=0

Setting this keyword give a vertical color bar. The default is a horizontal color bar.

XLOG in optional type=boolean default=0

Set this keyword to use logarithmic scaling for the colorbar data range.

XTICKINTERVAL in optional type=float

This keyword is trapped, but unused. Please use theTickInterval keyword instead.

XTICKLAYOUT in optional type=integer default=0

See the Plot graphics kewyords for an example. Used here only to track this keyword.

XTITLE in optional type=string

This keyword is ignored. Use the Title keyword to set a title for the color bar.

YLOG in optional type=boolean default=0

Set this keyword to use logarithmic scaling for the colorbar data range.

YTICKINTERVAL in optional type=float

This keyword is trapped, but unused. Please use theTickInterval keyword instead.

YTICKLAYOUT in optional type=integer default=0

See the Plot graphics kewyords for an example. Used here only to track this keyword.

YTITLE in optional type=string

This keyword is ignored. Use the Title keyword to set a title for the color bar.

WINDOW in optional type=boolean default=0

Set this keyword to display the plot in a resizeable graphics window (cgWindow).

_REF_EXTRA in optional

Any keyword appropriate for the PLOT and AXIS commands is also accepted by keyword inheritance.

Examples

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:

Copyright (c) 2008-2013, Fanning Software Consulting, Inc.

History:

Change History:

Written by: David W. Fanning, 4 February 2011, as a direct descendant of cgColorbar. Program developement stopped on cgColorbar as of this date, and this program has become a part of the Coyote Graphics System. Added FIT keyword. 28 Feb 2011. DWF Made default character size cgDefCharsize*0.85. 28 Feb 2011. DWF. Modified error handler to restore the entry decomposition state if there is an error. 17 March 2011. DWF Added CHARPERCENT keyword 18 March 2011. DWF. Added XTITLE and YTITLE keywords, which do nothing except prevent these keywords from being used inadvertently. 27 May 2011. DWF. Fixed a problem with assigning the color with the ANNOTATECOLOR keyword in the Z-graphics buffer. 30 Aug 2011. DWF. Changed the default DIVISIONS to 0 and the default FORMAT to "". 2 Sept 2011. DWF. Added code that will force MINRANGE and MAXRANGE values to be scalars. 5 Sept 2011. DWF. Problem with division by zero when FORMAT is not default value. Now, if format is the default value, then default is DIVISIONS=0, else DIVISIONS=6. Documented the TICKLEN keyword and set the default tick length to 0.25. 3 Oct 2011. DWF. Added the OOB_FACTOR, OOB_HIGH and OOB_LOW keywords. 5 Dec 2011. DWF. Added DISCRETE keyword. 7 Dec 2011. DWF. Changed the way the top axis was drawn, and had a problem with EXTRA keywords. Fixed. 20 Dec 2011. DWF. Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF. Fixed a problem with color palettes by defining NCOLORS according to the number of colors in the palette. 19 March 2012. DWF. Set the maximum number of divisions at 59 to recognize the IDL plot limit for tick marks. 19 March 2012. DWF. Modifications to the FIT algorithm to make sure the color bar is completely inside the graphics window. Also fixed mis-spelled variable name. 20 March 2012. DWF. Added TickInterval, XTickInterval and YTickInterval keywords to accommodate interval spacing of major tick marks. 21 July 2012. DWF. Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF. Added TLOCATION and TCHARSIZE keywords. 20 September 2012. DWF. Implemented a fix that will allow the user to specify a tick formatting function name with the FORMAT keyword. 21 September 2012. DWF. Fixed a problem in which setting the RANGE keyword gave different results, depending upon whether a FORMAT keyword was used or not. This change will affect the default color bar labeling *if* the user specifies a range. If you prefer the old labeling behavior, simiply set the `Divisions` keyword to 0. 16 Oct 2012. DWF. Added CTINDEX, and BREWER keywords to make loading a color table palette easier. 20 October 2012. DWF. Fixed a strange interaction between TickInterval and the Format keywords. 5 Nov 2012. DWF. Changes to support a tick formatting function when a log axis is used. 7 February 2013. DWF. Added XTICKLAYOUT and YTICKLAYOUT keywords. 8 February 2013. DWF. Somehow the default AnnotateColor had gotten changed from "opposite". Restored. 18 Feb 2013. DWF. Greatly simplified the code and turned over the responsibility of doing tick formatting and setting the number of divisions, etc. to the PLOT command. I do this with some trepidation, because it is a big change, but I think it will lead to better results in the long run and won't affect current IDL programs much, if at all. 27 Feb 2013. DWF. Added TEXTTHICK keyword to change the thickness of the textual annotations. 28 Feb 2013. DWF. Added more error handling for bad POSITION values. 26 July 2013. DWF. Modified the code so that the original input POSITION values are not changed by the program code. 8 August 2013. DWF. The check for a valid position is now done before the colorbar is drawn so that a colorbar sans axes is not left dangling on the display. 25 September 2013. Matthew Argall