KML, short for Keyhole Markup Language, is a standard that defines an XML-based format for representing geographic features and map visualizations. You can create and edit KML content in your ArcGIS Runtime app. ArcGIS Runtime saves KML version 2.2 to a compressed KML format known as KMZ.
A KML dataset is a container for a hierarchical collection of KML nodes. Some common types of KML nodes include the following:
- Document—A container for KML features (placemarks, overlays, folders, and so on).
- Folder—A container that defines a hierarchy for nodes in the tree.
- Ground overlay—Specifies a local or hosted image file to draw on the surface.
- Model—Represents an object in 3D coordinate space using a COLLADA file.
- Network link— Specifies the location of a KML or KMZ resource on a local or remote network.
- Placemark—Similar to an ArcGIS feature, it represents a geographic location with point, line, or polygon geometry.
- Screen overlay—Specifies a local or hosted image file to draw on the screen (such as a company logo).
- Tour—Defines a fly-through experience composed of an ordered list of elements to visit.
- Track/Multitrack—Describes the geographic position of an object over time.
ArcGIS Runtime SDK supports the creation and editing of documents, folders, placemarks, ground overlays, and network links. You can also edit the properties of KML nodes, including the name, description, snippet, geometries, and style. KML content you create or edit can be saved to a .kmz file.
Some advanced content types or behaviors are currently not supported for editing via ArcGIS Runtime, such as the following:
- Shared style elements
- Highlight style
- Screen overlays
KML geometry always uses the WGS84 coordinate system.
Create KML content and save it to a KMZ file
You can save any KML node to an output file by calling . Doing so writes the KML representation of the node and all of its child nodes to a compressed KML format (.kmz). Only files referenced by absolute URLs are supported for use as icons and links. It's common to save a KML document node since it serves as a top-level container for several related child nodes. The output KMZ archive is shared easily as a single file and can be read into any app that supports KML, such as ArcGIS Earth or an ArcGIS Runtime SDK app. See Display KML content for details.
The following steps describe how to create a KML dataset, add nodes, and save it locally to a new KMZ file.
- Create a KML document and use it to create a KML dataset.
The document is a top-level container for additional KML nodes.
- Create a style to represent a placemark. The style defines an icon style that is created with an icon (built with a URI to a local or online image).
- Create a placemark node with point geometry and set its style to use the icon. Provide a value for the ID, Name, and Description to give more information about the placemark.
- Save the KML document as a .kmz file. You can save any KML node to write its contents (its child nodes, in other words) to a file on disk.
- Optionally, display the new KML file as a KML layer in your map or scene.
Create a KML ground overlay
A ground overlay is a KML element that displays an area on the surface. Like a placemark node, a ground overlay is created with geometry and a symbol. It has name, description, and snippet properties that can be used to display additional information. Geometry for a ground overlay must be of type polygon or envelope. The data the overlay represents comes from an image reference in a KML icon.
The following steps illustrate creating a simple ground overlay and adding it to a KML document's node collection:
- Create an icon to display with the ground overlay. The icon is defined using a URI to an online or local image.
- Create geometry to use for the ground overlay. The ground overlay geometry must be a polygon or an envelope.
- Create a KML ground overlay with the geometry and icon to use. Add the new overlay to the KML document's child node collection.