KML Support

This issue has been heavily edited since Andre’s original write-up and is now maintained by @mramato.

The initial KML implementation was started as part of the 2013 Google Summer of Code and resulted in many core features being implemented by @andre-nunes in his branch. Current work is taking place in the kml branch of the official Cesium repository. Since KML is a large specification, the plan is to implement what we see as the minimum viable product first and officially release that as part of Cesium. We will then continue to add additional functionality on a feature by feature basis with each Cesium release.

The below task list tries to capture everything at a fairly high level for each phase. There are many hidden features and requirements here and listing them all isn’t useful. For example, we are going to need polygon and polyline draping on terrain as a core Cesium feature (#2172). We will add new tasks when we encounter an issue as we implement each of the high-level types. If you have a strong need for a feature that we haven’t gotten to yet, or feel we’re missing something in the below list; please don’t hesitate to let us know.

Related Links

Mailing-list topic Google Documentation OGC Specification

• KmlDataSource
  • KMZ support
  • Proxy support
• Folder
• Placemark
  • Geometry
    • Point
    • LineString
    • LinearRing
    • Polygon
    • MultiGeometry
    • gx:MultiTrack
    • gx:Track
    • Model
• Overlay
  • GroundOverlay
  • ScreenOverlay
  • Super Overlays
  • PhotoOverlay
• NetworkLink
  • onExpire, onInterval, onStop
  • onRegion, onChange, onRequest
• [NetworkLinkControl] (https://developers.google.com/kml/documentation/kmlreference#networklinkcontrol)
  • Everything except updates
  • Updates
• Styles
  • LineStyle
  • PolyStyle
  • IconStyle
  • LabelStyle
  • BalloonStyle
  • styleUrl
  • StyleMap
    • normal
    • highlight
    • locally defined
  • ListStyle (requires DataSourceBrowser for full implementation)
• Additional <Link> features
  • <refreshMode>
  • <refreshInterval>
  • <viewRefreshMode>
  • <viewRefreshTime>
  • <viewBoundScale>
  • <viewFormat>
  • <httpQuery>
• Same <Link> features for <Icon>
• LookAt
• Camera
• ExtendedData
  • <Data>
  • <Schema> and <SchemaData>
  • Arbitrary XML data
• Resolve KMZ links inside of an entity description.
• Turn plain text urls in descriptions into links.
• gx:LatLonQuad
  • Trapezoidal Texture Projection
• Region
• root:// notation for older KML documents
• gx:Tour
• gx:drawOrder
• <gx:altitudeOffset> for LinearRing and LineString
• <gx:angles> for Track and MultiTrack (applies to both model and billboard).
• <Icon> gx extensions x, y, w, and h for GroundOverlay
• gx extensions for LineStyle
• xal:AddressDetails
• altitudeMode
  • absolute
  • clampToGround
  • relativeToGround (doesn’t work on terrain).
• gx:altitudeMode
• visibility
• ge:Track gets billboard heading from angles or direction of travel.
• Support for TIFF images. forum discussion
• Password protected kmz files.
• Password protected network links.
• Ability to specify default icon when load fails.

Random notes

• We need to match handling of missing x/y/w/h values when using Placemark gx sub-region
• All billboards KML produces are currently square, Google Earth instead scales the longer edge to 32 while maintaining aspect ratio. This can be seen in the KMZ Sandcastle demo, which has squate flags in Cesium and rectangular flags in GE.
• Cesium doesn’t have any way to support BalloonStyle:displayMode. I’m not sure we care.
• We currently replace BalloonStyle text $[geDirections] with nothing. If we ever provide out of the box routing, we can use that instead. (https://github.com/gregjacobs/Autolinker.js) can be used to do this.
• We may be able to use createObjectURL for loading data from a zip file (which is currently using data uris). The problem here is that you need to call revokeObjectURL in order to clean things up when you’re done.
• We need to support passing an ellipsoid to KmlDataSource to support other planets.
• We may want to expose some way to customize default values, either by exposing default entity graphics directly, or exposing a limited set of options (like GeoJSONDataSource does)
• Clicking on a link in a balloon description that returns KML has special behavior in GE. While we probably won’t mirror that directly in Cesium, we should provide a mechanism to be able to do so (maybe through events).
• zip.js has the ability to report progress which we currently don’t utilize. loadXmlFromZip and loadDataUriFromZip in KmlDataSource.js would be the place to start if we ever want to add it. We just need to pass a onprogress callback as the third parameter to entry.getData
• It would be nice to have a KML animation demo that uses TimeSpan, similar to the US states formation demo in Google’s own documentation.
• Google Earth silently ignores errors with invalid dates (such as having garbage in a when block). If we want to match Google Earth, we should too. Rather than try/catching JulianDate.fromIso8601, we should add a exceptionless version that returns undefined.

[ggetz]

Hi @icarter09,

1. I believe StyleMap -> Highlight is still yet to be implemented.
2. It would be great if you could contribute this! I’ll look into getting you some more information, but in the meantime this comment mentions the areas of the code to look.

[paullenhardt]

Well that would make plenty of sense. Apparently you can stare at an issue for hours and still never see the obvious.

GoogleEarth seems to ignore the <visibility> tag (I originally had set the <visibility> to ‘0’ within my kml generator to try to suppress the display upon KML loading and forgot about removing the <visibility> tag when it had no effect on GoogleEarth) so I am glad to see that Cesium honors that tag.

The nested folders was simply because I pulled the example from a much larger data-set where there was more data which the nesting provided organization to.

Thanks for the assist in debugging despite the obvious blunder on my part.