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. Those other files may be located on our machine, or they might be located on different machines and referenced within the KML using a URL. We can fetch such images automatically by creating a data source on the KML file using File - Create - New Data Source.
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, shown below.
As discussed in the KML, KMZ Google topic, when using File - Import or File - Link, Manifold will not automatically follow links within a KML to fetch a ground overlay image, not even links within the same machine, since allowing a file to automatically trigger links to other files or across the web can pose a significant risk to user privacy.
When using the File - Create - New Data Source dialog, Manifold will automatically follow links one level deep within a KML to fetch a ground overlay image, and to further levels if the user allows. The presumption is that users who choose the New Data Source dialog are sufficiently informed to have KML files automatically connect across the web, if that is what they want.
We first consider a KML that wants to use a ground overlay image that is hosted on a different machine across the internet. Our example file is called EtnaGroundOverlay.kml. It contains 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>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>
If we use File - Import or File - Link to import or to link to the above .kml nothing will happen. That will fail to bring in the etna.jpg image because Manifold will not allow files during the import or link 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 instead use the New Data Source dialog.
We choose File - Create - New Data Source and then in the New Data Source dialog we provide a memorable name for the data source, Etna KML. We choose File: kml for the Type, and then we click the [...] browse button to navigate to the KML file we want to use.
In the Select File dialog, we navigate to the file we want, and we double-click it to choose it.
Back in the New Data Source dialog, we click Create Data Source.
A new data source named Etna KML appears in the project. When we expand it, the system takes a moment to follow the link inside the KML to the Google server and then fetches the image that was referenced by the URL. Depending on the speed of our Internet connection (usually fast in modern times) and the speed of the server (Google, so it is fast) that might go very quickly or it might less quickly.
Eventually, the image appears within the data source in the project. Manifold will cache the image for this session so performance can be faster once the image is fetched from the google server.
To view the image in context, we first create a map using a Bing streets image server as a base layer, and then we drag and drop the etna image into the map.
The image appears with correct georegistration, exactly where Mount Etna is located in Sicily. 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.
So far, the etna image is an image linked from a read-only data source, an image that is stored on the Google server to which Manifold connects using the URL in the KML file. If we would like a local copy of the image saved within the project, with no connection to the Google server, that is easy to do.
We ctrl-click on the etna drawing and the etna Tiles table, and then we can drag and drop them into the main part of the Project. That creates a local copy. If we like, we can then delete the Etna KML data source and work with the local etna image.
KML files can contain ground overlay images that are image files on the local computer. They do not have to use URLs that reference images on other computers.
Suppose we have a KML file called LocalEtnaGroundOverlay.kml. It is the same KML code as before, except that instead of an https:// URL to a file on a Google server it simply refers to a local file, etna.jpg:
<?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 KML assumes there is an image file called etna.jpg image in the same folder as the KML file.
To use the above KML we again choose File - Create - New Data Source, navigate to the LocalEtnaGroundOverlay.kml file, double-click it to choose it, and then we press Create Data Source, exactly as in the prior example. Once again, a data source will be created that contains the etna image. This time, however, the image will be linked from a local file on our computer, instead of being a link to a file stored on a remote Google server.
If we want a local copy of that image, we would once again drag and drop the image and table from within the data source into the local part of the project.
Why not just import when links are local? - When KML links refer to local files, why not just enable File - Import to import them? Is it not an extra step to use the New Data Source dialog? Yes, it is, but that is a small safety measure to ensure KML files do not silently trigger connections to other files or other computers. There is nothing about the name or the three letter extension of a KML file that tips off users it is not a purely local file. It might be entirely self contained, or it might contain links to other files, and those other files might be on the same computer or reached across Internet. If File - Import automatically followed a link to a local file, that local file could be another KML file, which in turn might launch a connection across Internet.
A work in progress - Following links in recursive KML files requires striking a balance between the convenience of fetching data from other machines versus users knowing that using a KML file in Manifold will launch a connection across Internet and agreeing that is OK. The current implementation gives up some convenience in order to get some more safety. If the user community prefers otherwise, the balance between convenience and safety can be moved as desired in future builds.