Class KmlLayer

  • All Implemented Interfaces:
    TimeAware, LayerContent, Loadable

    public final class KmlLayer
    extends Layer
    implements TimeAware
    A layer that can visualize Keyhole Markup Language (KML) data.

    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.

    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 specification can be found at http://www.opengeospatial.org/standards/kml.

    ArcGIS Runtime 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.

    KML specifies a set of geographic objects (Placemarks and Ground Overlays) as well as other data types (Screen Overlays, Network Links, and more). Placemarks specify locations on the Earth and can have vector geometry type of points, lines, or polygons. All coordinates are expressed in latitude and longitude (using decimal degrees), and are based on the World Geodetic System 1984 (WGS84) geographic coordinate system. 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 things such as: compasses, logos, legends, etc. Network Links give the ability to reference remote .kml or .kmz files, and refresh them periodically.

    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
    • Constructor Detail

      • 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 Detail

      • 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