Keyhole Markup Language (KML) is an XML notation popularized by Google Earth and used to display geographic data for maps and scenes. KML is an extension of XML and uses a tag-based structure with nested elements and attributes. The KML file specifies a set of features (place marks, images, polygons, 3D models, textual descriptions, etc.) that can be displayed on maps in geospatial software implementing the KML encoding, include ArcGIS.
Along with geographic positioning information, KML files provide supporting content (including images and 3D models) and are often distributed in a zipped KMZ archive file. The contents of a KMZ file are a single root KML document (notionally "doc.kml") and optionally any overlays, images, icons, and COLLADA 3D models referenced in the KML, including network-linked KML files.
KML specification version 2.2 as defined by the Open GIS Consortium (OGC) is supported. Use the free Esri product ArcGIS Earth to read and write KML and KMZ files. See this Google KML Tutorial to learn more about the KML file structure, commonly used tags, and so on.
Display a KML/KMZ file
KML content is loaded using a KmlDataset. The KmlDataset constructor takes a URL, which can point to a local file or a network location. Loading the layer will cause the associated dataset to load. KML layers can also be loaded from portal items, which can specify a link to a file or the KML/KMZ file itself.
// Create a new KML dataset using the specified QUrl to a KML/KMZ file.
KmlDataset* kmlDataset = new KmlDataset(qUrlKmlDataset, this);
// Create a new KML layer using the specified KML dataset.
KmlLayer* kmlLayer = new KmlLayer(kmlDataset, this);
Many KML files are wrappers that point to resources over the network. For example, a weather map might consist of a single network link that points to the latest forecast, to be retrieved every five minutes. As a result, loading the layer does not necessarily guarantee that the content has loaded linked content can fail to load without affecting the load status of the layer.
Explore the KML content tree
KML layers contain content in a hierarchy. You may need to programmatically explore this hierarchy to interact with KML content. For example, to turn off a screen overlay, you would need to first find it in the tree, then change its visibility. This code will follow a recursive pattern, using a function that calls itself for each node in the tree. The KML tree should be explored starting with KmlDataset, which exposes the KML feature tree with the root function. This provides a a list of KmlNode objects.
void Layers::exploreKml(const QList<KmlNode*>& qListKmlNodes)
{
// Loop through each KML node in the QList of KML nodes.
for (KmlNode* kmlNode : qListKmlNodes)
{
// Do work here...
}
}
The non-recursive part of turning off a screen overlay is toggling its visibility after it is found. Because you are working with a generic KmlNode, you first need to determine whether each iterated node is a KmlScreenOverlay. After the screen overlay is found, toggle its visibility.
void Layers::exploreKml(const QList<KmlNode*>& qListKmlNodes)
{
// Loop through each KML node in the QList of KML nodes.
for (KmlNode* kmlNode : qListKmlNodes)
{
// Test if we have a KML node type of a Kml screen overlay.
if (kmlNode->kmlNodeType() == KmlNodeType::KmlScreenOverlay)
{
// Toggle the visibility of the KML screen overlay node.
kmlNode->setVisible(!kmlNode->isVisible());
}
}
}
You should then look for screen overlay nodes that may exist deeper in the hierarchy, however. Recursively call the explore function (shown next) on any nodes that have children.
void Layers::exploreKml(const QList<KmlNode*>& qListKmlNodes)
{
// Loop through each KML node in the QList of KML nodes.
for (KmlNode* kmlNode : qListKmlNodes)
{
// Test if we have a KML node type of a Kml screen overlay.
if (kmlNode->kmlNodeType() == KmlNodeType::KmlScreenOverlay)
{
// Toggle the visibility of the KML screen overlay node.
kmlNode->setVisible(!kmlNode->isVisible());
}
QList<KmlNode*> qListKmlNodeChildren;
// Test if the KML node is a KML container.
if (KmlContainer* kmlContainer = dynamic_cast<KmlContainer*>(kmlNode); kmlContainer)
{
// Get the KML node list model from the KML container.
const KmlNodeListModel& kmlNodeListModel = *kmlContainer->childNodesListModel();
// Use the C++ std library copy function to put the KML container nodes into the
// QList of KML nodes children.
std::copy(kmlNodeListModel.begin(), kmlNodeListModel.end(), std::back_inserter(qListKmlNodeChildren));
}
// Test if the KML node is a KML network link.
else if (KmlNetworkLink* kmlNetworkLink = dynamic_cast<KmlNetworkLink*>(kmlNode); kmlNetworkLink)
{
// Get the QList of KML nodes from the KML network link and assign them to the
// QList of KML nodes children.
qListKmlNodeChildren = kmlNetworkLink->childNodes();
}
// Recursively call the function to iterate over all of the nodes (no matter how nested they are
// within KML containters and KML network links) until the all the KML screen overlay nodes have
// their visibility toggled.
exploreKml(qListKmlNodeChildren);
}
}
KmlDataset root method, either after loading the map or in reaction to user action (such as a button press).The tree-exploration pattern is useful for other tasks involving KML. For example, ArcGIS Earth uses a recursive pattern to build a table of contents:
Identify and popups in KML
In the ArcGIS information model, a popup is defined with a set of fields that describe an object, including how that information is formatted. Unlike ArcGIS feature services, KML files don't define a standard schema for object attributes. Instead, KML files may provide a rich HTML annotation for each object, which can be presented in place of a popup. You can access the HTML annotation via KmlNode.Balloon and then display that using a web view.
Viewpoints in KML
The OGC KML specification has two primary ways for defining viewpoints:
-
LookAt - defines a camera relative to the position of a KML feature
-
Camera - defines the position of the camera explicitly
The KmlViewpoint class can represent both types of viewpoints. Custom code is required to convert from a KML viewpoint to an ArcGIS viewpoint, which can be used for navigating a scene. See Google's reference documentation for details, including diagrams. Earth browsing apps should respect LookAt viewpoints specified in KML content.
// Get the KML viewpoint from the KML node.
const KmlViewpoint kmlViewpoint = kmlNode->viewpoint();
// Test if the KML viewpoint is empty, proceed if not empty.
if (!kmlViewpoint.isEmpty())
{
const Point pointLocation = kmlViewpoint.location();
const double doubleRange = kmlViewpoint.range();
const double doubleHeading = kmlViewpoint.heading();
const double doublePitch = kmlViewpoint.pitch();
const double doubleRoll = kmlViewpoint.roll();
// Switch to the various KML viewpoint types.
switch (kmlViewpoint.type())
{
case KmlViewpointType::LookAt:
{
// Create a camera with a range.
const Camera camera1 = Camera(pointLocation, doubleRange, doubleHeading, doublePitch, doubleRoll);
// Set the view point to one with a range.
m_viewpoint = Viewpoint(pointLocation, camera1);
// Exit the Case/Switch.
return;
}
case KmlViewpointType::Camera:
{
// Create a camera without a range.
const Camera camera2 = Camera(pointLocation, doubleHeading, doublePitch, doubleRoll);
// Set the view point to one without a range.
m_viewpoint = Viewpoint(pointLocation, camera2);
// Exit the Case/Switch.
return;
}
default:
{
// Log a warning of an unexpected KML view point type.
qWarning("Unexpected KmlViewpointType");
// Exit the Case/Switch.
return;
}
}
}
Play KML tours
Playing tours contained in KML files is supported. A KML tour defines a map exploration experience that can contain: narration and music, animated movement between viewpoints, and dynamic animation of KML feature properties.
To play a KML tour, create a KmlTourController and set its tour property to the tour you want to play. Then use the Play, Pause, and Restart methods on KmlTourController to work with the tour. If the tour contains audio, that audio will play automatically with the tour. To monitor the status of the tour, you can check to the tour property on KmlTour.
The following example shows a function that can search KML nodes for a tour and assign the first one it finds to a KmlTourController.
See Touring in KML on the Google developers site to learn more about KML Tours.
// Loop through each KML node in the QList of KML nodes.
for (KmlNode* kmlNode : qListKmlNodes)
{
// Continue if we have a KML node type of a Kml screen overlay.
if (kmlNode->kmlNodeType() == KmlNodeType::KmlTour)
{
// Get a KML tour from the KML node.
KmlTour* kmlTour = dynamic_cast<KmlTour*>(kmlNode);
// Create a new KML tour controller using the default constructor.
KmlTourController* kmlTourController = new KmlTourController(this);
// Set the KML tour on the KML tour controller.
kmlTourController->setTour(kmlTour);
}
}
