Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


Harris Geospatial / Docs Center / Libraries / Coyote / CGCBAR2KML

CGCBAR2KML

CGCBAR2KML
  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 <http://www.idlcoyote.com/graphics_tips/weboutput.php>`
  for details.
 
 

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



© 2017 Exelis Visual Information Solutions, Inc. |  Legal
My Account    |    Buy    |    Contact Us