Example: Import KML with GroundOverlay Image

KML files can contain GroundOverlay references to images that are stored in other files and which are intended to be used as part of the KML.  Manifold will automatically import GroundOverlay images that are stored on the local machine or which are accessible through local network references as part of the KML import.  Manifold will not automatically import images from Internet URLs embedded within the KML, since such silent connections across the web pose a significant risk to user privacy and can be very costly, depending on the type of connection.

 

Google's developer documentation on Ground Overlays defines them as follows:  "Ground overlays enable you to "drape" an image onto the Earth's terrain. The <Icon> element contains the link to the .jpg file with the overlay image. "  Google's sample KML for Ground Overlays uses a .jpg image of Mount Etna erupting in 2001.   The KML code is:

 

<?xml version="1.0" encoding="UTF-8"?>

<kml xmlns="http://www.opengis.net/kml/2.2">

  <Folder>

    <name>Ground Overlays</name>

    <description>Examples of ground overlays</description>

    <GroundOverlay>

      <name>Large-scale overlay on terrain</name>

      <description>Overlay shows Mount Etna erupting

          on July 13th, 2001.</description>

      <Icon>

        <href>https://developers.google.com/kml/documentation/images/etna.jpg</href>

      </Icon>

      <LatLonBox>

        <north>37.91904192681665</north>

        <south>37.46543388598137</south>

        <east>15.35832653742206</east>

        <west>14.60128369746704</west>

        <rotation>-0.1556640799496235</rotation>

      </LatLonBox>

    </GroundOverlay>

  </Folder>

</kml>

 

 

We can place the above code in a file called EtnaGroundOverlay.kml    That .kml will fail to bring in the etna.jpg image because Manifold will not allow files during the import process to silently connect to the Internet.    One problem with KML as a format is that it allows embedding all sorts of tricky stuff that can actively contact other servers without the user's knowledge.   Manifold does not allow such security / privacy / financial risks, so instead if we want to use images that are referenced by a KML we download them manually as follows:

 

https://developers.google.com/kml/documentation/images/etna.jpg

 

We copy the above reference to the image and paste it into a browser, in the illustration below viewing it in Microsoft's Edge browser:  

 

eg_import_kml_groundoverlay01_01.png

 

We can then download the image to a local file called etna.jpg.   In Microsoft's Edge browser we right-click onto the image and choose Save picture as.

 

eg_import_kml_groundoverlay01_02.png

 

We save the etna.jpg image into the same folder as a KML file containing the following KML code:

 

<?xml version="1.0" encoding="UTF-8"?>

<kml xmlns="http://www.opengis.net/kml/2.2">

  <Folder>

    <name>Ground Overlays</name>

    <description>Examples of ground overlays</description>

    <GroundOverlay>

      <name>Large-scale overlay on terrain</name>

      <description>Overlay shows Mount Etna erupting

          on July 13th, 2001.</description>

      <Icon>

        <href>etna.jpg</href>

      </Icon>

      <LatLonBox>

        <north>37.91904192681665</north>

        <south>37.46543388598137</south>

        <east>15.35832653742206</east>

        <west>14.60128369746704</west>

        <rotation>-0.1556640799496235</rotation>

      </LatLonBox>

    </GroundOverlay>

  </Folder>

</kml>

 

The above code we place in a file called LocalEtnaGroundOverlay.kml.  It is the same code as before, except that we have replaced the https:// Internet reference to a local reference, using just the name of the file, etna.jpg.  

 

eg_import_kml_groundoverlay01_03.png

 

Launch Manifold and choose File - Import.

 

eg_import_kml_groundoverlay01_04.png

 

In the Import dialog we navigate to our LocalEtnaGroundOverlay.kml file and import it.   Note that the etna.jpg file is in the same folder, so the direct reference to it in the KML file will work.

 

eg_import_kml_groundoverlay01_05.png

 

The system immediately imports the KML.  This particular KML has no data in it other than a reference to the Ground Overlay image, which is imported using the LatLonBox information in the KML  to assign the correct coordinate system to it.

 

To view the image in context, we will create an image server layer using Bing streets, add that to a map we create and then we can drag and drop the etna image into the map.

 

eg_import_kml_groundoverlay01_06.png

 

In the illustration above we have created a new map and we have already added the Bing streets layer to the map.  We drag and drop the etna image into the map.

 

 

eg_import_kml_groundoverlay01_07.png

 

We ctrl-click on the etna layer tab to zoom to that image, and then we pan and zoom a bit to get the display above.   The image is correctly georeferenced and appears in the right location at the right size in the map because the KML file provided LatLonBox information that could be used to assign the initial coordinate system for the image.

 

See Also

Style

 

Web Servers

 

KML, KMZ Google