.\

cgimage2kml.pro

top cgImage2KML

Graphics, FileIO, Maps

cgImage2KML [, image] [, mapCoord] [, ADDTOFILE=object] [, /BREWER] [, CTINDEX=integer] [, DESCRIPTION=string] [, DRAWORDER=integer] [, GEOTIFF=string] [, FILENAME=string] [, FLYTO=fltarr(3)] [, /KMZ] [, LATLONBOX=array] [, MAX_VALUE=MAX_VALUE] [, MIN_VALUE=MIN_VALUE] [, MISSING_VALUE=various] [, PALETTE=byte] [, PLACENAME=string] [, RESIZE_FACTOR=float] [, /REVERSE] [, TRANSPARENT=integer]

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.

Parameters

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

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

Copyright:

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.

File attributes

Modification date:	Fri Mar 27 11:07:38 2015
Lines:	414
Docformat:	rst rst

Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015