Skip To Content ArcGIS for Developers Sign In Dashboard

Edit KML content

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

Note:

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 SaveAsAsync. 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.

  1. 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 new KML document and set its name property.
    KmlDocument kmlDocument = new KmlDocument
    {
        Name = "UFO sightings"
    };
    
    // Create a new KML dataset using the KML document.
    KmlDataset kmlDataset = new KmlDataset(kmlDocument);

  2. 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 new icon using a URL to an online image.
    KmlIcon placemarkIcon = new KmlIcon(new System.Uri("http://static.arcgis.com/images/Symbols/SafetyHealth/esriCrimeMarker_56_Gradient.png"));
    
    // Create an icon style using the icon, adjust the size using the scale argument.
    KmlIconStyle iconStyle = new KmlIconStyle(placemarkIcon, 3);
    
    // Create a KML style that uses the icon style.
    KmlStyle placemarkStyle = new KmlStyle
    {
        IconStyle = iconStyle
    };

  3. 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.

    // Create a KML placemark, give it a name and description.
    MapPoint mapPoint = new MapPoint(-105.243, 33.968, 0.0, SpatialReferences.Wgs84);
    KmlGeometry kmlGeometry = new KmlGeometry(mapPoint, KmlAltitudeMode.ClampToGround);
    KmlPlacemark kmlPlacemark = new KmlPlacemark(kmlGeometry)
    {
        Id = "43a",
        Name = "Roswell crash site",
        Description = "Debris discovered at a ranch in Roswell, New Mexico, in 1947 is widely " +
                        " believed to be from an alien spacecraft."
    };
    
    // Apply the icon style to the placemark.
    kmlPlacemark.Style = placemarkStyle;
    
    // Add the placemark to the KML node collection.
    kmlDocument.ChildNodes.Add(kmlPlacemark);

  4. 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.

    // Save the KML document as a local .kmz file.
    await kmlDocument.SaveAsAsync(outFolder + "TruthIsOutThere.kmz");

  5. Optionally, display the new KML file as a KML layer in your map or scene.

    // Create a new KML layer from the output KMZ file.
    KmlLayer kmlLayer = new KmlLayer(new System.Uri(outFolder + "TruthIsOutThere.kmz"));
    
    // Add the KML layer to the scene (or map).
    MySceneView.Scene.OperationalLayers.Add(kmlLayer);
    
    // Zoom to the extent of the new layer.
    Envelope layerExtent = kmlLayer.FullExtent;
    await MySceneView.SetViewpointAsync(new Viewpoint(layerExtent));

A scene view showing a KML placemark that displays a name and description.

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:

  1. Create an icon to display with the ground overlay. The icon is defined using a URI to an online or local image.

    // Create an icon from a image URL to display the ground overlay.
    KmlIcon icon = new KmlIcon(new System.Uri("http://static.arcgis.com/images/Symbols/Basic/CrossHair.png"));

  2. Create geometry to use for the ground overlay. The ground overlay geometry must be a polygon or an envelope.

    // Use a polygon builder to create a rectangle polygon (in WGS 84 coordinates).
    PolygonBuilder overlayPolyBldr = new PolygonBuilder(SpatialReferences.Wgs84);
    overlayPolyBldr.AddPoint(-115.858, 37.204);
    overlayPolyBldr.AddPoint(-115.858, 37.326);
    overlayPolyBldr.AddPoint(-115.757, 37.326);
    overlayPolyBldr.AddPoint(-115.757, 37.204);
    Polygon overlayPoly = overlayPolyBldr.ToGeometry();

  3. 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 new groundOverlay with the polygon and icon.
    KmlGroundOverlay groundOverlay = new KmlGroundOverlay(overlayPoly, icon);
    
    // Provide a name and description.
    groundOverlay.Name = "Area 51";
    groundOverlay.Description = "A highly classified US Air Force facility in the Nevada Test and Training Range.";
    
    // Add the ground overlay to the document's child nodes.
    kmlDocument.ChildNodes.Add(groundOverlay);

A scene view showing a KML ground overlay.