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.
ArcGIS Runtime provides the ability to read .kml and .kmz files from disk or the network. You can also create, edit, and save a KML layer via the
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. ArcGIS Runtime 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.
KmlLayeralso 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
KmlDatasethas 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.
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 the Runtime 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.
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
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.
- See Also:
All Methods Instance Methods Concrete Methods Modifier and Type Method Description
addFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)Adds a listener that will fire when there is a change to the full time extent.
getDataset()Gets the KmlDataset that is associated with the KML layer.
getFullTimeExtent()Returns the full time extent of the object.
getTimeInterval()Returns the suggested time slider step size for this time aware object.
getTimeOffset()Returns the time offset applied to this object.
isTimeFilteringEnabled()Returns whether or not the object must use the time extent defined on the owning GeoView to filter its data.
isTimeFilteringSupported()Returns whether or not the object supports filtering its contents by time values with the extent set on the owning GeoView.
removeFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)Removes a full time extent changed listener.
setIsTimeFilteringEnabled(boolean enabled)Enables or disables whether the object must use the time extent defined on the owning GeoView to filter its data.
setTimeOffset(TimeValue timeOffset)Sets a time offset for this object.
Methods inherited from class com.esri.arcgisruntime.layers.Layer
public KmlLayer(KmlDataset kmlDataset)Constructs a KmlLayer from the given KmlDataset.
kmlDataset- a KmlDataset
IllegalArgumentException- if kmlDataset is null
public KmlLayer(PortalItem portalItem)Creates a KmlLayer from the given
If the portal item is not in
LoadStatus.LOADEDstate it will be loaded automatically when this KmlLayer instance is loaded.
If the loaded portalItem is not of type
PortalItem.Type.KMLthe layer will fail to load.
The portal item can contain a KML file directly or a URL to a KML resource.
portalItem- PortalItem from which this KmlLayer will be created
IllegalArgumentException- if the portalItem is null
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.
- a KmlDataset
public TimeExtent getFullTimeExtent()Returns the full time extent of the object. Will be null if the object is not time aware.
public TimeValue getTimeInterval()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.
public TimeValue getTimeOffset()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.
public boolean isTimeFilteringEnabled()
public void setIsTimeFilteringEnabled(boolean enabled)
public boolean isTimeFilteringSupported()
public void setTimeOffset(TimeValue timeOffset)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.
public void addFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)Adds a listener that will fire when there is a change to the full time extent.
public boolean removeFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)Removes a full time extent changed listener.