>  Docs Center  >  Libraries  >  Coyote  >  CGIMAGE2KML


  This program creates a KML file that can be opened in Google Earth to display the
  image drapped over the Google Earth terrain. A corresponding image file is also
  produced. The KML and image file must be in the same directory to use them with
  Google Earth.


    Graphics, FileIO, Maps


    image: in, optional
      A 2D image or a 24-bit image with or without an alpha channel. If an alpha
      channel is present, it will be modified by the program if the `Transparent`
      keyword is used. An image is required unless the `GeoTiff` keyword is used
      to obtain an image.
    mapcoord: in, optional, type=object
      A map coordinate object (cgMap) from which map projection information and map
      boundaries for the image overlay can be obtained. This parameter is required
      unless the `GeoTiff` keyword is used to obtain a map coordinate object.


    addtofile: in, optional, type=object
      If this keyword contains a cgKML_File object, the image is added to the file
      as a <GroundOverlay) 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.
    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.
    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. This keyword
      applies only to 2D images.
    description: in, optional, type=string
      A string that is used to describe the image in the Google Earth interface.
    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.
    geotiff: in, optional, type=string
      The name of a GeoTiff file from which the `image`, `mapcoord`, `palette` (possibly),
      and `latlonbox` values can be obtained.
    filename: in, optional, type=string, default='kml_image.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.
    flyto: in, optional, type=fltarr(3)
        A three-element array that gives the coordinates [longitude, latitude, elevation] where
        the "eye" should be located with respect to the Earth. This implements a LookAt element
        in KML file, so that when the KML file is open, it "flies to" the location represented
        here. Longitude must be in the range -180 to 180. Latitude must be in the range -90 to 90.
        And elevation is a number in kilometers. If a two-element array [longitude, latitude] is
        passed in, the default value for elevation is 11000 km above the surface of the Earth.
    kmz: in, optional, type=boolean, default=0
        If this keyword is set, the KML file is zipped into a KMZ file. This
        functionality is only available if you have installed the Open Source
        `7-Zip compression program <http://www.7-zip.org/>' and set up the path
        to 7z.exe correctly in cgKML2KMZ. If you don't understand, please don't
        set this keyword!
    latlonbox: out, optional, type=array
        A four-element array giving the boundaries of the map projection in the
        Google Map form of [north, south, east, west]. Normally, this information
        is obtained from the mapCoord object and need not be passed in. The values
        are in latitude and longitude coordinates that go from -90 to 90 and -180 to
        180 degrees, respectively.
    max_value: in, optional
        The value to use for the MAX value when the image is scaled with BYTSCL.
    min_value: in, optional
        The value to use for the MIN value when the image is scaled with BYTSCL.
    missing_value: in, optional, type=various
        The "color" of a pixel that will be treated as a "missing" color or value.
        Any pixels in the image with this color value will be set completely
        transparent. If `Color` is a string, use cgColor to obtain a color triple.
        If `Color` is a non-strint scalar, this value is taken to be the missing color index
        in a 2D image. Otherwise, this is assumed to be a color triple that indicates
        the "missing" color or value in the output image. The alpha channel in the output image
        is set to 0 for the "missing" color, which makes this value completely transparent.
        If the `Transparent` keyword is not used, it is set to 0 by using the `Missing_Value`
    palette: in, optional, type=byte
        Set this keyword to a 3x256 or 256x3 byte array containing the RGB color
        vectors to be loaded before the transparent image is created. Such vectors can be
        obtained, for example, from cgLoadCT with the RGB_TABLE keyword::
                IDL> cgLoadCT, 4, /BREWER, /REVERSE, RGB_TABLE=palette
                IDL> tImage = cgTransparentImage( cgDemoData(7), PALETTE=palette)
        The default is to use whatever colors are loaded in the current hardware color table.
        A palette applies only to 2D input images.
    placename: in, optional, type=string
        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.
    resize_factor: in, optional, type=float
        Setting this keyword to a value allows the user to resize the image prior to making the
        PNG image file that will be output with the KML file. This is especially helpful with
        very large images. Setting the factor to 0.5 will reduce the image to half it's normal
        size before processing. Setting the factor to 2.0 will increase the size by a factor
        of 2 before processing. The image is resized with nearest neighbor sampling.
    reverse: in, optional, type=boolean, default=0
        Set this keyword to reverse the color table vectors selected with the `CTIndex` keyword.
    transparent: in, optional, type=integer, default=50
        The percentage of transparency desired in the output image. A number
        between 0 and 100.


    Here is how you can put an AVHRR NDVI image of Africa on a Google Earth display::
      ;; 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.
      cgImage2KML, GeoTiff='AF03sep15b.n16-VIg.tif', Min_Value=0, CTIndex=11, $
          /Brewer, /Reverse, Transparent=50, Filename='avhrr_ndvi.kml', $
          Description='AVHRR NDVI Data from Africa'
      ;; Start Google Earth and open the KML file you just created.
    The output should look like the figure above.


      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


    Change History::
        Written, 30 October 2012 by David W. Fanning.
        Added DRAWORDER keyword and fixed a typo concerning MISSING_VALUE. 31 Oct 2012. DWF.
        Fixed a problem that was causing floating underflow warnings to be thrown. 5 Nov 2012. DWF.
        Images with values between 0 and 255 were not getting scaled properly. Fixed. 30 Nov 2012. DWF.
        Added a FlyTo keyword to allow the user to fly to a particular location on the Earth. 31 Dec 2012. DWF.
        Was not handling 24- or 32-bit images correctly, nor was the MISSING_COLOR keyword being
            interpreted correctly when expressed as a color string. 20 Feb 2013. 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.
        Problem with the MISSING keyword. Fixed. 14 Mar 2013. DWF.


    Copyright (c) 2012, Fanning Software Consulting, Inc.

© 2020 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us