top cgCBar2KML

Graphics, FileIO, Maps

cgCBar2KML [, ADDTOFILE=object] [, BACKGROUND=string] [, BOTTOM=integer] [, /BREWER] [, CHARPERCENT=float] [, CHARSIZE=float] [, CLAMP=float] [, COLOR=string] [, CTINDEX=integer] [, DESCRIPTION=string] [, /DISCRETE] [, DIVISIONS=integer] [, DRAWORDER=integer] [, FILENAME=string] [, FORMAT=string] [, /KMZ] [, LOCATION=intarr] [, MAXRANGE=MAXRANGE] [, MINOR=integer] [, MINRANGE=float] [, NCOLORS=integer] [, NEUTRALINDEX=integer] [, OOB_FACTOR=float] [, OOB_HIGH=string] [, OOB_LOW=string] [, PALETTE=byte] [, PLACENAME=string] [, RANGE=float] [, /REVERSE] [, TCHARSIZE=float] [, TICKINTERVAL=float] [, TICKLEN=float] [, TICKNAMES=string] [, TITLE=string] [, /XLOG] [, XTICKINTERVAL=float] [, XTITLE=string] [, WIDTH=integer] [, _REF_EXTRA=_REF_EXTRA]

Keywords

ADDTOFILE in optional type=object

If this keyword contains a cgKML_File object, the image is added to the file as a <ScreenOverlay> element and a separate KML file is not created. In other words, the Filename keyword is ignored and the image file created takes its name from the cgKML_File object.

BACKGROUND in optional type=string default=gray

The background color for the color bar.

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.

DESCRIPTION in optional type=string

A string that is used to describe the image in the Google Earth interface.

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

The number of divisions to divide the bar into. There will be (divisions + 1) annotations. The default is 0 if using the default color bar formatting, which allows the plot command to determine how many divisions to make. Otherwise, if you are specifying some other format for the tick labels, the default number of divisions is six.

DRAWORDER in optional type=integer default=0

The drawing order of image overlay. The first order is 0. Images with a higher order are drawn on top of images with a lower order.

FILENAME in optional type=string default=kml_cbimage.kml

The name of the KML file that will be created. The image file will have the same name, but with a *.png file extension. The KML file and the image file will be created in the same directory.

FORMAT in optional type=string

The format of the color bar annotations. Default is "". Note that the formatting behaviour can change, depending up values for the keywords RANGE and DIVISIONS. If you prefer to let the IDL Plot command determine how the color bar labels are formatted, set the format to a null string and set the DIVISIONS keyword to 0. Note the difference in these two commands:

cgColorbar, Range=[18,125], Position=[0.1, 0.8, 0.9, 0.85] cgColorbar, Range=[18,125], Position=[0.1, 0.7, 0.9, 0.75], Divisions=0

KMZ in optional type=boolean default=0

Set this keyword to move the KML file and support files to a KMZ compressed file. Note that this capability is ONLY available in versions of IDL starting with version 8.0.

LOCATION in optional type=intarr

A two-element array giving the location of the top-left corner of the color bar in normalized coordinates from the upper-left of the Google Earth display screen. Default is [0.025, 0.975].

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

OOB_FACTOR in optional type=float default=0.2

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

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

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.

PLACENAME in optional type=string default=Color Bar

This is the <name> element in a Feature object. It is user-defined text that is used as the label for an object in Google Earth.

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.

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.

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.

TITLE in optional type=string

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

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.

XTITLE in optional type=string

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

WIDTH in optional type=integer default=300

The width, in pixels, of the colorbar image that is created.

_REF_EXTRA in optional

Any keyword appropriate KML screen overlay objects is allowed.

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) 2012-2013, Fanning Software Consulting, Inc.

History:

Change History:

Written, 30 October 2012 by David W. Fanning. Added DRAWORDER keyword and fixed a typo concerning MISSING_VALUE. 31 Oct 2012. DWF. Have been writing the absolute path to the image file into the KML file, when I should have been using a relative path. 22 Feb 2013. DWF.