coyote: CGIMAGE2KML

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