; docformat = 'rst' ; ; NAME: ; cgCBar2KML ; ; PURPOSE: ; This program creates a KML file that can be opened in Google Earth to display a ; color bar as a ScreenOverlay. Screen overlays are images that are displayed in ; a fixed location on the Google Earth display. A corresponding color bar image file is ; produced. The KML and color bar image file must be in the same directory to use them with ; Google Earth. ; ;******************************************************************************************; ; ; ; Copyright (c) 2012, by Fanning Software Consulting, Inc. All rights reserved. ; ; ; ; Redistribution and use in source and binary forms, with or without ; ; modification, are permitted provided that the following conditions are met: ; ; ; ; * Redistributions of source code must retain the above copyright ; ; notice, this list of conditions and the following disclaimer. ; ; * Redistributions in binary form must reproduce the above copyright ; ; notice, this list of conditions and the following disclaimer in the ; ; documentation and/or other materials provided with the distribution. ; ; * Neither the name of Fanning Software Consulting, Inc. nor the names of its ; ; contributors may be used to endorse or promote products derived from this ; ; software without specific prior written permission. ; ; ; ; THIS SOFTWARE IS PROVIDED BY FANNING SOFTWARE CONSULTING, INC. ''AS IS'' AND ANY ; ; EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES ; ; OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT ; ; SHALL FANNING SOFTWARE CONSULTING, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, ; ; INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED ; ; TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ; ; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ; ; ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ; ; (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS ; ; SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ; ;******************************************************************************************; ; ;+ ; This program creates a KML file that can be opened in Google Earth to display a ; color bar as a ScreenOverlay. Screen overlays are images that are displayed in ; a fixed location on the Google Earth display. A corresponding color bar image file is ; produced. The KML and color bar image file must be in the same directory to use them with ; Google Earth. In general, any keyword used for horizontal color bars in cgColorbar can ; be used with this program. The colorbar image is made from a PostScript intermediate file, which ; means ImageMagick must be installed on your computer and available to IDL to run this program ; successfully. Please see `IDL Output for Web Display ` ; for details. ; ; .. image:: cgcbar2kml.png ; ; :Categories: ; Graphics, FileIO, Maps ; ; :Keywords: ; addtofile: in, optional, type=object ; If this keyword contains a cgKML_File object, the image is added to the file ; as a 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, default="" ; 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. ; minrange: in, optional, type=float, default=0.0 ; The minimum data value for the bar annotation. ; minor: in, optional, type=integer, default=2 ; The number of minor tick divisions. ; 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 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. ; 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, default="" ; This is title for the color bar. The default is to have no title. ; 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. ; width: in, optional, type=integer, default=300 ; The width, in pixels, of the colorbar image that is created. ; 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 the`TickInterval` keyword instead. ; xtitle: in, optional, type=string ; This keyword is ignored. Use the `Title` keyword to set a title for the color bar. ; _ref_extra: in, optional ; Any keyword appropriate KML screen overlay objects is allowed. ; ; :Examples: ; Here is how you can put an AVHRR NDVI image of Africa on a Google Earth display ; with a color bar:: ; ; ;; Download the image file from the Coyote web page. ; netObject = Obj_New('IDLnetURL') ; url = 'http://www.idlcoyote.com/data/AF03sep15b.n16-VIg.tif' ; returnName = netObject -> Get(URL=url, FILENAME='AF03sep15b.n16-VIg.tif') ; Obj_Destroy, netObject ; ; ;; Create the image overlay KML file. ; kmlFile = Obj_New('cgKML_File', 'avhrr_ndvi_cb.kml') ; cgLoadCT, 11, /Brewer, /Reverse, RGB_Table=palette ; map = cgGeoMap('AF03sep15b.n16-VIg.tif', Image=image) ; scaledImage = BytScl(image > 0) ; cgImage2KML, scaledImage, map, $ ; Palette=palette, Missing_Value=0, $ ; Description='AVHRR NDVI Data from Africa', $ ; PlaceName='AVHRR Africa', $ ; AddToFile=kmlFile ; cgCBar2KML, Palette=palette, Range=[0,9400], $ ; Title='NDVI Index', $ ; Description='AVHRR NDVI Color Bar', $ ; PlaceName='NDVI Color Bar', $ ; AddToFile=kmlFile ; kmlFile -> Save ; kmlFile -> Destroy ; ; ;; Start Google Earth and open the KML file you just created. ; ; The output should look like the figure above. ; ; If you just wish to create a KML file with a color bar, you can do this:: ; ; cgCBar2KML, Filename='colorbar.kml', CTIndex=5, Title='Test Color Bar' ; ; :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 ; ; :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. ; ; :Copyright: ; Copyright (c) 2012-2013, Fanning Software Consulting, Inc. ;- PRO cgCBar2KML, $ ADDTOFILE=addtofile, $ BACKGROUND=background, $ BOTTOM=bottom, $ BREWER=brewer, $ CHARPERCENT=charpercent, $ CHARSIZE=charsize, $ CLAMP=clamp, $ COLOR=color, $ CTINDEX=ctindex, $ DESCRIPTION=description, $ DISCRETE=discrete, $ DIVISIONS=divisions, $ DRAWORDER=draworder, $ FILENAME=filename, $ FORMAT=format, $ KMZ=kmz, $ LOCATION=location, $ MAXRANGE=maxrange, $ MINOR=minor, $ MINRANGE=minrange, $ NCOLORS=ncolors, $ NEUTRALINDEX=neutralIndex, $ OOB_FACTOR=oob_factor, $ OOB_HIGH=oob_high, $ OOB_LOW=oob_low, $ PALETTE=palette, $ PLACENAME=placename, $ RANGE=range, $ REVERSE=reverse, $ TCHARSIZE=tcharsize, $ TICKINTERVAL=tickinterval, $ TICKLEN=ticklen, $ TICKNAMES=ticknames, $ TITLE=title, $ XLOG=xlog, $ XTICKINTERVAL=xtickinterval, $ ; Ignored. XTITLE=xtitle, $ ; Ignored. WIDTH=width, $ _REF_EXTRA=extra Compile_Opt idl2 Catch, theError IF theError NE 0 THEN BEGIN Catch, /CANCEL void = cgErrorMsg() RETURN ENDIF ; Default values. IF N_Elements(background) EQ 0 THEN background = 'gray' IF N_Elements(location) EQ 0 THEN location = [0.025, 0.975] IF N_Elements(placename) EQ 0 THEN placename = 'Color Bar' IF N_Elements(oob_factor) EQ 0 THEN oob_factor = 0.2 IF N_Elements(charsize) EQ 0 THEN charsize=1.75 IF N_Elements(tcharsize) EQ 0 THEN tcharsize = 2.0 IF N_Elements(title) EQ 0 THEN BEGIN position = [0.1, 0.425, 0.9, 0.775] ENDIF ELSE BEGIN position = [0.1, 0.525, 0.9, 0.875] ENDELSE ; If the KMZ keyword is set, make sure this version of IDL supports it. IF Keyword_Set(kmz) THEN BEGIN IF Float(!Version.Release) LT 8.0 THEN BEGIN Message, 'The KMZ keyword is not supported in this version of IDL.', /Informational kmz = 0 ENDIF ENDIF ; Need a filename? IF N_Elements(filename) EQ 0 THEN BEGIN CD, CURRENT=thisDir filename = Filepath(ROOT_DIR=thisDir, 'kml_cbimage.kml') ENDIF ; Construct the image filename rootName = cgRootName(filename, DIRECTORY=thisDir, EXTENSION=ext) IF StrUpCase(ext) NE 'KML' THEN Message, 'The output filename must have a KML file extension.' imageFilename = Filepath(ROOT_DIR=thisDir, rootname + '.png') IF cgObj_Isa(addtofile, 'cgKML_File') THEN BEGIN addToFile -> GetProperty, FILENAME=filename, COUNT=count rootname = cgRootName(filename, DIRECTORY=thisDir, EXTENSION=ext) imageFilename = FilePath(ROOT_DIR=thisDir, rootname + StrTrim(count+1,2) + '.png') ; Write the image file. rootname = cgRootName(imageFilename, DIRECTORY=thisDir) psFileName = Filepath(ROOT_DIR=thisDir, rootname + '.ps') cgPS_Open, psFilename, /Quiet cgDisplay, 1000, 200 cgColorFill, [0,1,1,0,0], [0,0,1,1,0], /Normal, Color=background cgColorbar, $ BOTTOM=bottom, $ BREWER=brewer, $ CHARPERCENT=charpercent, $ CHARSIZE=charsize, $ CLAMP=clamp, $ COLOR=color, $ CTINDEX=ctindex, $ DISCRETE=discrete, $ DIVISIONS=divisions, $ FORMAT=format, $ MAXRANGE=maxrange, $ MINOR=minor, $ MINRANGE=minrange, $ NCOLORS=ncolors, $ NEUTRALINDEX=neutralIndex, $ OOB_FACTOR=oob_factor, $ OOB_HIGH=oob_high, $ OOB_LOW=oob_low, $ PALETTE=palette, $ POSITION=position, $ RANGE=range, $ REVERSE=reverse, $ TCHARSIZE=tcharsize, $ TICKINTERVAL=tickinterval, $ TICKLEN=ticklen, $ TICKNAMES=ticknames, $ TITLE=title, $ XLOG=xlog cgPS_Close, /PNG, /DELETE_PS, WIDTH=width, /NoMessage ; Create the screen overlay object if a raster file was created. IF File_Test(imageFilename) THEN BEGIN overlay = Obj_New('cgKML_ScreenOverlay', $ HREF=File_Basename(imageFilename), $ DESCRIPTION=description, $ DRAWORDER=draworder, $ SCREEN_XY=location, $ PLACENAME=placename) addToFile -> Add, overlay ENDIF ENDIF ELSE BEGIN ; Write the image file. rootname = cgRootName(imageFilename, DIRECTORY=thisDir) psFileName = Filepath(ROOT_DIR=thisDir, rootname + '.ps') cgPS_Open, psFilename, /Quiet cgDisplay, 1000, 200 cgColorFill, [0,1,1,0,0], [0,0,1,1,0], /Normal, Color=background cgColorbar, $ BOTTOM=bottom, $ BREWER=brewer, $ CHARPERCENT=charpercent, $ CHARSIZE=charsize, $ CLAMP=clamp, $ COLOR=color, $ CTINDEX=ctindex, $ DISCRETE=discrete, $ DIVISIONS=divisions, $ FORMAT=format, $ MAXRANGE=maxrange, $ MINOR=minor, $ MINRANGE=minrange, $ NCOLORS=ncolors, $ NEUTRALINDEX=neutralIndex, $ OOB_FACTOR=oob_factor, $ OOB_HIGH=oob_high, $ OOB_LOW=oob_low, $ PALETTE=palette, $ POSITION=position, $ RANGE=range, $ REVERSE=reverse, $ TCHARSIZE=tcharsize, $ TICKINTERVAL=tickinterval, $ TICKLEN=ticklen, $ TICKNAMES=ticknames, $ TITLE=title, $ XLOG=xlog cgPS_Close, /PNG, /DELETE_PS, WIDTH=width, /NoMessage ; Write the KML file. kmlFile = Obj_New('cgKML_File', filename) ; Create the screen overlay object if a raster file was created. IF File_Test(imageFilename) THEN BEGIN overlay = Obj_New('cgKML_ScreenOverlay', $ HREF=File_Basename(imageFilename), $ DESCRIPTION=description, $ DRAWORDER=draworder, $ SCREEN_XY=location, $ PLACENAME=placename) kmlFile -> Add, overlay ENDIF kmlFile -> Save, KMZ=Keyword_Set(kmz) kmlFile -> Destroy ENDELSE END