KML

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.

getScene().getCentralBodies().getEarth().getKml().addDocumentLoaded(onDocumentLoaded);
getScene().getCentralBodies().getEarth().getKml().loadDocumentAsync(kmlPath);

EventHandler<KmlDocumentLoadedEventArgs> onDocumentLoaded = EventHandler.of((sender, e) -> {
    KmlDocument document = e.getDocument();
    String documentName = document.getName();
});

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:

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:

String kmlContent = 
    "<?xml version=\"1.0\" encoding=\"utf-8\"?>" + 
    "<kml xmlns=\"http://www.opengis.net/kml/2.2\">" +
    "<Placemark>" + 
    "<name>AGI</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.

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

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.

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:

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();

Note
KML documents may specify the height of a feature using absolute altitude mode, which is measured relative to mean sea level (MSL). In order to compute this height, Insight3D requires that the EarthCentralBody.MeanSeaLevel (get / set) property be configured, or it will throw an exception. See the Terrain topic for more information on obtaining and loading MSL data into DME Component Libraries.

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:

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

networkLink.setRefreshMode(KmlNetworkLinkRefreshMode.ON_INTERVAL);
networkLink.setRefreshInterval(Duration.fromSeconds(5.0));

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:

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

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:

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();
    }
}

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