Click or drag to resize

KML

Insight3D supports loading and rendering.kml and .kmz documents in a 3D scene. A simple tree of the document and its content is available using the KmlDocument, KmlFeature, KmlContainer, KmlFolder, and KmlNetworkLink types.

Basics

Insight3D provides a simple KML object model that can be used to access information about KML features and modify properties associated with KML rendering. KmlGraphics, accessed from the CentralBodyGraphics.Kml (get) property, contains methods for loading, unloading, and managing KML documents. The following code sample loads a KML document from a Uri asynchronously. Synchronous load methods are also provided and described below.

Note Note

KML can support SSL and relevant protocols like HTTPS for loading of documents or associated assets. See the NetworkContext class for details on configuring your network settings.

Java
getScene().getCentralBodies().getEarth().getKml().addDocumentLoaded(onDocumentLoaded);
getScene().getCentralBodies().getEarth().getKml().loadDocumentAsync(kmlPath);
Java
EventHandler<KmlDocumentLoadedEventArgs> onDocumentLoaded = EventHandler.of((sender, e) -> {
    KmlDocument document = e.getDocument();
    String documentName = document.getName();
});
Loading KML

The DocumentLoaded (add / remove) event is raised when the KML document has completed loading. The KmlDocumentLoadedEventArgs contain the KmlDocument that was loaded, as shown in the code sample above. Since KmlDocument derives from KmlFeature and KmlFeature, you can then access various properties of the document, including its Children (get). The following image illustrates the KML class hierarchy:

KML Class Hierarchy
Documents

As shown above, documents can be loaded from .kml and .kmz files. They can also be loaded directly from a string, if that string contains valid KML content. The following code sample loads a KML document synchronously from a string:

Java
String kmlContent = 
    "<?xml version=\"1.0\" encoding=\"utf-8\"?>" + 
    "<kml xmlns=\"http://www.opengis.net/kml/2.2\">" +
    "<Placemark>" + 
    "<name>Analytical Graphics, Inc</name>" +
    "<Point><coordinates>-75.59672941368964,40.03876371991856</coordinates></Point>" + 
    "</Placemark>" + 
    "</kml>";
KmlDocument kmlDocument = getScene().getCentralBodies().getEarth().getKml().load(kmlContent);

You can enumerate through the documents that were loaded by using the KmlGraphics.Documents (get) collection. To unload a document, call the unload method. Similarly, you can unload all documents from the scene by calling unloadAll.

Java
KmlDocument document = getScene().getCentralBodies().getEarth().getKml().loadDocument(kmlPath);
getScene().getCentralBodies().getEarth().getKml().unload(document);
getScene().getCentralBodies().getEarth().getKml().unloadAll();
Note Note

Every KmlFeature, including KmlDocument, has an IsLoaded (get) property that indicates whether the object is currently loaded or not. Once a KmlDocument has been unloaded, it is no longer valid, and accessing methods and properties on the document or associated features will throw an exception indicating such.

Features

KmlFeature is the primary type for KML in Insight3D. It provides basic properties such as Display (get / set), querying feature attributes, and allows you to fly to or show the balloon associated with the feature. You can also get the actual KML content of the KmlFeature. The following code sample queries various attributes of the feature, and then flies to the feature:

Java
KmlDocument kmlDocument = getScene().getCentralBodies().getEarth().getKml().loadDocument(kmlPath);
KmlFeature kmlFeature = kmlDocument.getChildren().get(0);
System.out.println(kmlFeature.getName());
System.out.println(kmlFeature.getDescription());
System.out.println(kmlFeature.getSnippet());
System.out.println(kmlFeature.getContent());

kmlFeature.flyTo();
getScene().render();
KML Feature
Network Links

A KmlNetworkLink will update automatically in the scene. Like KmlFeature, which it derives from, you can query and set various network link related properties. The following code changes the RefreshMode (get / set) and RefreshInterval (get / set) of the network link:

Java
KmlDocument kmlDocument = getScene().getCentralBodies().getEarth().getKml().loadDocument(kmlPath);
KmlNetworkLink networkLink = (KmlNetworkLink) kmlDocument.getChildren().get(0);

networkLink.setRefreshMode(KmlNetworkLinkRefreshMode.ON_INTERVAL);
networkLink.setRefreshInterval(Duration.fromSeconds(5D));
Folders and Containers

KmlContainer shares all the same attributes and behavior of KmlFeature, but also contains other KmlFeatures. Both KmlFolder and KmlDocument derive from KmlContainer. When the Display (get / set) property is set on a KmlContainer, all contained features will also show or hide. The following example enumerates through the children and then toggles off the display of a KmlFolder:

Java
KmlContainer folder = (KmlContainer) kmlDocument.getChildren().get(0);
for (KmlFeature feature : folder.getChildren()) {
    System.out.println(feature.getName());
}
folder.setDisplay(false);
Picking

Picking allows users to select and interact with KML features on the screen. The pick-int-int- method returns information about KmlFeatures, along with other Primitives. The below example demonstrates picking on a KmlFeature:

Java
List<PickResult> collection = getScene().pick(x, y);
if (collection.size() == 1) {
    KmlFeature feature = (KmlFeature) collection.get(0).getObjects().get(0);

    if (feature != null) {
        // Just a KmlFeature was picked, fly to it
        feature.flyTo();
    }
}
Picking KML
Compatibility

Insight3D supports almost the entire KML specification and many extensions, but still lacks support for certain features. The following KML-related features are not currently supported in Insight3D:

  • The tessellate option (Lines on Terrain) on LineString and LinearRing features

  • Globe overlays drawn at an altitude Fade extent for regions

  • Photo overlays

  • Highlighted style

  • Updating of models with link refresh properties

  • Anything in the Google extension namespace

  • Updating screen and globe overlays with link refresh properties