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, screen 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
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.
Create a KML screen overlay
A screen overlay is an image shown on top of the map, with a fixed position relative to the screen. Screen overlays are commonly used for compasses, logos, legends, and heads-up displays. Screen overlays are defined in screen coordinates and appear in the same location on the display when the geoview is panned or zoomed.
The following steps illustrate creating a simple screen overlay and adding it to a KML document's node collection:
A screen overlay is a KML element that displays an image on the screen. Like a ground overlay node, a screen overlay is created with geometry and a symbol. Unlike nodes that display on the map, the geometry for a screen overlay is defined relative to the screen, in display units such as pixels, or as a fraction of the width and height of the display. The overlay image is defined using a KML icon.
The following steps illustrate creating a north arrow screen overlay and adding it to a KML document's node collection:
- Create an icon to display with the screen overlay. The icon is defined using a URI to an online or local image.
- Create a KML image coordinate to define the location for the screen overlay. The screen overlay location is defined relative to the screen display. This can be defined in coordinates, such as pixels, or as a fraction of the width and height of the display.
The overlay location (screen coordinate) is mapped to a point on the icon. By default, this is the center of the image. This point can be explicitly defined by setting the OverlayCoordinate.
- Create a KML screen overlay and define the location and icon. Add the new overlay to the KML document's child node collection.