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