# coyote: CGIMAGE2KML

- coyote/Graphics
- coyote/FileIO
- coyote/Map Utilities
- [Source code]

Description

      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.
      .. image:: cgimage2kml.png

Categories

      Graphics, FileIO, Maps

Params

      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.

Keywords

      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`
          keyword.
      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.

Examples

      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.

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

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