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.
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
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. 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 theGeoView
, 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 underlyingKmlDataset
, creating one if you didn't supply one through a constructor. The structure of a KML document can be examined throughKmlDataset.getRequestConfiguration()
after theKmlDataset
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 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.ArcGIS Runtime supports displaying KML content in both the
MapView
andSceneView
.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 underlyingKmlDataset
. Once the KmlDataset was successfully loaded, the structure of a KML document can be examined throughKmlDataset.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:
Layer
-
-
Constructor Summary
Constructors Constructor Description KmlLayer(KmlDataset kmlDataset)
Constructs a KmlLayer from the given KmlDataset.KmlLayer(PortalItem portalItem)
Creates a KmlLayer from the givenPortalItem
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
Adds a listener that will fire when there is a change to the full time extent.KmlDataset
getDataset()
Gets the KmlDataset that is associated with the KML layer.TimeExtent
getFullTimeExtent()
Returns the full time extent of the object.TimeValue
getTimeInterval()
Returns the suggested time slider step size for this time aware object.TimeValue
getTimeOffset()
Returns the time offset applied to this object.boolean
isTimeFilteringEnabled()
Returns whether or not the object must use the time extent defined on the owning GeoView to filter its data.boolean
isTimeFilteringSupported()
Returns whether or not the object supports filtering its contents by time values with the extent set on the owning GeoView.boolean
removeFullTimeExtentChangedListener(FullTimeExtentChangedListener listener)
Removes a full time extent changed listener.void
setIsTimeFilteringEnabled(boolean enabled)
Enables or disables whether the object must use the time extent defined on the owning GeoView to filter its data.void
setTimeOffset(TimeValue timeOffset)
Sets a time offset for this object.-
Methods inherited from class com.esri.arcgisruntime.layers.Layer
addDoneLoadingListener, addLoadStatusChangedListener, addVisibilityChangedListener, cancelLoad, canChangeVisibility, canShowInLegend, fetchLegendInfosAsync, getAttribution, getDescription, getFullExtent, getId, getItem, getLoadError, getLoadStatus, getMaxScale, getMinScale, getName, getOpacity, getSpatialReference, getSubLayerContents, isIdentifyEnabled, isVisible, isVisibleAtScale, loadAsync, removeDoneLoadingListener, removeLoadStatusChangedListener, removeVisibilityChangedListener, retryLoadAsync, setCanShowInLegend, setDescription, setId, setMaxScale, setMinScale, setName, setOpacity, setVisible
-
-
-
-
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 givenPortalItem
.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 interfaceTimeAware
- 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 interfaceTimeAware
- 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 owningGeoView
. This allows for data from different periods of time to be compared.- Specified by:
getTimeOffset
in interfaceTimeAware
- 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 interfaceTimeAware
- 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 interfaceTimeAware
- 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 interfaceTimeAware
- 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 owningGeoView
. 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 interfaceTimeAware
- 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 interfaceTimeAware
- 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 interfaceTimeAware
- Parameters:
listener
- the listener to remove- Returns:
- true if the listener was removed, otherwise false
-
-