Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.layers

Class KmlLayer

java.lang.Object
com.esri.arcgisruntime.layers.Layer
com.esri.arcgisruntime.layers.KmlLayer
All Implemented Interfaces:
TimeAware, LayerContent, Loadable
public final class KmlLayer extends Layer implements TimeAware
A layer that can visualize KML data.

Keyhole Markup Language (KML) is a specification for working with geographic content. KML files can contain 2D and 3D content, as well as links to content from the network. The Keyhole Markup Language (KML) is a XML text specification used to display geographic objects in two-dimensional (2D) and three-dimensional (3D) viewers. The original KML specification was created by Keyhole, Inc. and was acquired by Google in 2004. In 2008, KML was adopted by the OGC using the specification version 2.2. The full KML reference can be found at https://developers.google.com/kml/documentation/kmlreference. The formal KML specification version 2.2, as defined by the Open Geospatial Consortium (OGC), can be found at https://www.ogc.org/standards/kml.

You can read .kml and .kmz files from disk or the network and create, edit, and save a KML layer via the KmlDataset.

Functional characteristics

KML represents features as a tree of nodes, including network links, folders, and place marks. Like ArcGIS features, place marks are defined with point, line, or polygon geometry. KML geometry, however, is always based on the WGS84 coordinate system. KML can also have attributes, but unlike ArcGIS feature services, a KML document does not use a schema to define a standard set of fields. This API supports version 2.2 of the KML specification .

KML specifies a set of geographic objects placemarks and ground overlays. Placemarks specify locations on the Earth and can have vector geometry type of points, lines, or polygons. Ground overlays are images that are fixed to a map and oriented against the earth's surface rather than the screen.

Unique features of KML include network links and screen overlays.

Network links are useful for retrieving network content on a specified interval — perfect for keeping a live map up to date. Network links can also be used to split a large KML file into multiple per-region KML files, with each being loaded only when the region is in view. It is also possible to reference remote .kml or .kmz files.

Screen overlays can be used to show content, such as branding or compasses and legends, on top of the GeoView. Screen overlay content does not scroll with the map or react to user interaction.

All coordinates are expressed in latitude and longitude (using decimal degrees), and are based on the World Geodetic System 1984 (WGS84) geographic coordinate system returned by SpatialReferences.getWgs84(). Altitude is always expressed in meters. The geographic features can contain attribute information and various styles can be specified to render them. Ground overlays allow images to be displayed for specific geographic objects or draped onto the map itself. Screen overlays allow fixing images to the GeoView, and may be used for compasses, logos, legends, etc. Network links give the ability to reference remote .kml or .kmz files, and refresh them periodically.

Loading the KmlLayer also loads its underlying KmlDataset, creating one if you didn't supply one through a constructor. The structure of a KML document can be examined through KmlDataset.getRequestConfiguration() after the KmlDataset has successfully loaded. Missing or inaccessible .kml and .kmz files would cause loading to fail. Missing resources referenced by the KML document (such as images or files referenced via a network link will not prevent the layer from loading.

Performance characteristics

KML files can vary significantly in the features they use, including 3D models, network links, and refresh intervals. Not all features are supported in 2D and 3D. For example, 3D models only appear when the KML layer is shown in a scene. Many KML files consist solely of a pointer to another KML file and a refresh interval. For example, the National Weather Service distributes forecast maps in the United States this way.

Using this API to create KML layers

To create an instance of the KmLayer class you need to supply a KmlDataset(String url) object, where the url could be a local or internet kml/kmz file.

This API supports displaying KML content in both the MapView and SceneView.

The distribution of KML data types typically comes in the form of two file extension types: .kml and .kmz. Files with the .kml extension are XML-based and can be viewed in any text editor. Files with the .kmz extension are in a zipped format and must support the ZIP v2.0 specification. To manually view the contents of a .kmz file, you can use any ZIP v2.0 compatible software to extract the folder to disk. The contents of the unzipped folder contain at a minimum a single root KML document (traditionally called "doc.kml"). It can also contain other directories, image files, more .kml files, etc.

The KmlLayer is a loadable class inheriting from Layer. Loading the KmlLayer also loads its underlying KmlDataset. Once the KmlDataset was successfully loaded, the structure of a KML document can be examined through KmlDataset.getRootNodes().

Missing or inaccessible .kml and .kmz files will cause loading to fail. Missing resources referenced by the KML document (such as images or network link destinations) will not prevent the whole KmlLayer from loading.

KmlLayer provides a read-only view of a KML document, and does not allow authoring or editing.

Since:
100.4.0
See Also:

  • Constructor Details

    • KmlLayer

      public KmlLayer(KmlDataset kmlDataset)
      Constructs a KmlLayer from the given KmlDataset.
      Parameters:
      kmlDataset - a KmlDataset
      Throws:
      IllegalArgumentException - if kmlDataset is null
      Since:
      100.4.0

    • KmlLayer

      public KmlLayer(PortalItem portalItem)
      Creates a KmlLayer from the given PortalItem.

      If the portal item is not in LoadStatus.LOADED state it will be loaded automatically when this KmlLayer instance is loaded.

      If the loaded portalItem is not of type PortalItem.Type.KML the layer will fail to load.

      The portal item can contain a KML file directly or a URL to a KML resource.

      Parameters:
      portalItem - PortalItem from which this KmlLayer will be created
      Throws:
      IllegalArgumentException - if the portalItem is null
      Since:
      100.4.0

  • Method Details

    • getDataset

      public KmlDataset getDataset()
      Gets the KmlDataset that is associated with the KML layer.

      The dataset provides an entry point to traverse the tree of KML nodes that make up the KML document. If you created the layer from a portal item, the dataset will be created and loaded automatically.

      Returns:
      a KmlDataset
      Since:
      100.4.0

    • getFullTimeExtent

      public TimeExtent getFullTimeExtent()
      Description copied from interface: TimeAware
      Returns the full time extent of the object. Will be null if the object is not time aware.
      Specified by:
      getFullTimeExtent in interface TimeAware
      Returns:
      the time extent, or null if the object is not time aware

    • getTimeInterval

      public TimeValue getTimeInterval()
      Description copied from interface: TimeAware
      Returns the suggested time slider step size for this time aware object. Can be null if no time interval is suggested for this time aware object.
      Specified by:
      getTimeInterval in interface TimeAware
      Returns:
      the time interval, or null if there is no time interval

    • getTimeOffset

      public TimeValue getTimeOffset()
      Description copied from interface: TimeAware
      Returns the time offset applied to this object. The offset is subtracted from the time extent set on the owning GeoView. This allows for data from different periods of time to be compared.
      Specified by:
      getTimeOffset in interface TimeAware
      Returns:
      the time offset, or null if no offset has been set

    • isTimeFilteringEnabled

      public boolean isTimeFilteringEnabled()
      Description copied from interface: TimeAware
      Returns whether or not the object must use the time extent defined on the owning GeoView to filter its data.
      Specified by:
      isTimeFilteringEnabled in interface TimeAware
      Returns:
      true if time filtering is enabled; otherwise false

    • setIsTimeFilteringEnabled

      public void setIsTimeFilteringEnabled(boolean enabled)
      Description copied from interface: TimeAware
      Enables or disables whether the object must use the time extent defined on the owning GeoView to filter its data.
      Specified by:
      setIsTimeFilteringEnabled in interface TimeAware
      Parameters:
      enabled - true to enable time filtering; otherwise false

    • isTimeFilteringSupported

      public boolean isTimeFilteringSupported()
      Description copied from interface: TimeAware
      Returns whether or not the object supports filtering its contents by time values with the extent set on the owning GeoView.
      Specified by:
      isTimeFilteringSupported in interface TimeAware
      Returns:
      true if time filtering is supported; otherwise false

    • setTimeOffset

      public void setTimeOffset(TimeValue timeOffset)
      Description copied from interface: TimeAware
      Sets a time offset for this object. The time offset is subtracted from the time extent set on the owning GeoView. This allows for data from different periods of time to be compared. Can be null if there is no time offset.
      Specified by:
      setTimeOffset in interface TimeAware
      Parameters:
      timeOffset - the time offset, or null if there is no time offset

    • addFullTimeExtentChangedListener

      public void addFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
      Description copied from interface: TimeAware
      Adds a listener that will fire when there is a change to the full time extent.
      Specified by:
      addFullTimeExtentChangedListener in interface TimeAware
      Parameters:
      listener - the listener to add

    • removeFullTimeExtentChangedListener

      public boolean removeFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
      Description copied from interface: TimeAware
      Removes a full time extent changed listener.
      Specified by:
      removeFullTimeExtentChangedListener in interface TimeAware
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was removed, otherwise false