KML Support

[andr3nun3s]

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

• [x] KmlDataSource
  • [x] KMZ support
  • [x] Proxy support
• [x] Folder
• [ ] Placemark
  • [x] Geometry
    • [x] Point
    • [x] LineString
    • [x] LinearRing
    • [x] Polygon
    • [x] MultiGeometry
    • [x] gx:MultiTrack
    • [x] gx:Track
    • [ ] Model
• [ ] Overlay
  • [x] GroundOverlay
  • [x] ScreenOverlay
  • [ ] Super Overlays
  • [ ] PhotoOverlay
• [x] NetworkLink
  • [x] onExpire, onInterval, onStop
  • [ ] onRegion, onChange, onRequest
• [ ] [NetworkLinkControl] (https://developers.google.com/kml/documentation/kmlreference#networklinkcontrol)
  • [x] Everything except updates
  • [ ] Updates
• [ ] Styles
  • [x] LineStyle
  • [x] PolyStyle
  • [x] IconStyle
  • [x] LabelStyle
  • [x] BalloonStyle
  • [x] styleUrl
  • [ ] StyleMap
    • [x] normal
    • [ ] highlight
    • [x] locally defined
  • [ ] ListStyle (requires DataSourceBrowser for full implementation)
• [x] Additional <Link> features
  • [x] <refreshMode>
  • [x] <refreshInterval>
  • [x] <viewRefreshMode>
  • [x] <viewRefreshTime>
  • [x] <viewBoundScale>
  • [x] <viewFormat>
  • [x] <httpQuery>
• [ ] Same <Link> features for <Icon>
• [ ] LookAt
• [ ] Camera
• [ ] ExtendedData
  • [x] <Data>
  • [ ] <Schema> and <SchemaData>
  • [ ] Arbitrary XML data
• [x] Resolve KMZ links inside of an entity description.
• [x] Turn plain text urls in descriptions into links.
• [x] gx:LatLonQuad
  • [ ] Trapezoidal Texture Projection
• [ ] Region
• [x] 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
• [x] altitudeMode
  • [x] absolute
  • [x] clampToGround
  • [ ] relativeToGround (doesn't work on terrain).
• [ ] gx:altitudeMode
• [x] 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.

[mramato]

This is a good start. Let's concentrate on Placemark and geometry first. We can just render point geometry as default billbboards and everything else as white lines and polygons. This will help us get basic architecture in place and also show some early visual progress. We'll probably have to further break up some of these roadmap items into smaller tasks as we go.

[andr3nun3s]

I believe that Point and LineString is done.

I've also marked style processing and styleUrl.

[andr3nun3s]

Hey @mramato, how's this going? Is there anything I can do to help out?

[mramato]

Hey @andre-nunes. I haven't worked directly on KML in a little while but #1444 adds some major features that we needed in order to move forward (such as extruded polygons), so once that's in master and I merge it down, there should be some exciting stuff.

One thing you could start looking into is supporting the various Balloon options and styles. There's some basic code in their now that hooked up the description property to load balloon data in our new InfoBox widget, sync up and give it a try. We would want to also handle BallonStyle and ExtendedData. I have at least one KMZ I can send you that uses these, let me know and I'll email you.

Other than that, feel free to just review what's there (and the list above) and see if there's anything you want to do. No matter how small, feel free to open a pull request into this branch any time.

[andr3nun3s]

Yes, please send me the KMZ and I'll start looking into Ballon options and styles during the week!

[mramato]

I did another pass on the main task list and unchecked most of the boxes for now. My plan is to go through what we have and validate/complete each item and then I'll start checking things back on one at a time.

[andr3nun3s]

Hey, I'd like to help out if possible, I was really busy last time and would like to make up for it. Just let me get up to speed on current developments.

Is there anything specific I could look into?

[mramato]

That would be awesome. I'm in the process of figuring out where we left off (since I haven't looked at this code in months) but once I have a plan of attack put together I'll let you know and we can split up the work. I'll also probably create a new mailing list post to let people know what we're up to and where we are going. Are you still in school, or have you graduated?

[andr3nun3s]

That sounds good!

I'm still in school but as I'm just attending some leftover courses I'll have more free time during this year.

Let me know when you've got the plan worked out.

[mramato]

Hey @andre-nunes I know we haven't talked much but I just wanted to let you know that we just opened a PR for KML to go into master (link above this post). There's still a lot of work to do with KML overall, but it's looking really good for a bunch of use cases. That's again for getting the ball started on this!

[andr3nun3s]

Hi @mramato, I'm really glad to see some of my work being finally merged into cesium, let me know if there's something I can help out with in my free time. Oh and I just noticed that you've updated GSoC's ideas for 2015, is Cesium applying this year? I might shoot you an email regarding that ;)

[mramato]

Yes, we're applying. I assumed you graduated already. Definitely let me know if you're interested and what you want to work on.

[GatorScott]

Some, because I didn't try them all, of the KML files available from http://activefiremaps.fs.fed.us/googleearth.php result in error.

An error occurred while loading the file: conus_latest_modis.kml An error occurred while loading the file, which may indicate that it is invalid. A detailed error report is below:

Request has failed.

[GatorScott]

The file https://www.google.com/maps/d/kml?mid=zp8nK_5H0MFQ.kzTmU5XK-qJQ results in the following:

An error occurred while loading the file: 2015 California Fire Map.kmz An error occurred while loading the file, which may indicate that it is invalid. A detailed error report is below:

TypeError: Cannot read property 'length' of undefined TypeError: Cannot read property 'length' of undefined at Autolinker.HtmlParser.Autolinker.Util.extend.parse (http://localhost:8080/Source/ThirdParty/Autolinker.js:947:24) at Autolinker.link (http://localhost:8080/Source/ThirdParty/Autolinker.js:359:15) at processDescription (http://localhost:8080/Source/DataSources/KmlDataSource.js:1225:27) at processFeature (http://localhost:8080/Source/DataSources/KmlDataSource.js:1288:9) at processPlacemark (http://localhost:8080/Source/DataSources/KmlDataSource.js:1331:17) at processDocument (http://localhost:8080/Source/DataSources/KmlDataSource.js:1319:21) at processFolder (http://localhost:8080/Source/DataSources/KmlDataSource.js:1327:9) at processDocument (http://localhost:8080/Source/DataSources/KmlDataSource.js:1319:21) at processFeatureNode (http://localhost:8080/Source/DataSources/KmlDataSource.js:1477:13) at http://localhost:8080/Source/DataSources/KmlDataSource.js:1502:13

[mramato]

Thanks @GatorScott. The Request has failed. is a CORS issue. Just like imagery, any KML files loaded via url to another website or that contain a NetworkLink to another website either needs CORS to be enabled on that server or it has to go through a proxy. I'm writing up a tutorial on using KML in Cesium and I plan on having a section covering this.

That being said, once I used a proxy, I got a lot of errors about invalid styles; so I'll definitely look into and fix the issue for all KML on that page.

The length issue appears to be a clear cut bug caused by KML objects with no description but an empty ExtendedData node. It's an easy fix that I'll have a PR open for in a few minutes.

Thanks again for the link.

[mramato]

#2538 fixes the length problem.

[mramato]

#2539 fixes the rest of the issues. All of the files @GatorScott linked to should now load and work in Cesium (though loading directly from the URL, or ones that use NetworkLink still require use of a proxy).

[GatorScott]

The "2015 California Fire Map KML" works now but is displaying the placemark names using a serif font that is pretty illegible.

[mramato]

The "2015 California Fire Map KML" works now but is displaying the placemark names using a serif font that is pretty illegible.

It's using the browser's default san-serif font, but I agree it could be done better. I also want to allow people to select the font to use for labels as well. Cesium's label rendering as a whole needs improvements, this problem is not specific to KML. I'll write up an issue, since I don't think we have one right now.

[GatorScott]

You wrote "san-serif" when it should be "sans-serif" which is French for without serif.

[mramato]

Looks like that typo is also in the KML code, so it's not even using sans-serif but instead whatever the default browser font is. Unfortunately, fixing it doesn't fix the overall problem so we still have a bug somewhere in LabelCollection or writeTextToCanvas. Thanks for the heads up.

[GatorScott]

Could you make that a bold sans-serif by default? It looks way better.

I tried to get a non-bold picture but the California fire file doesn't work from cesiumjs.org.

[mramato]

I opened #2549 which majorly improves font issues (but is going to probably be partially held up by #2130). We could go with a bold in the meantime, I also recommended a monospace font in a comment in that PR which looks good without bolding.

[carsonpowers]

Is there a way to control z-level for polygons loads through KMLs?

I have placemarks loaded into my viewer:

But when I load a polygon over the are the placemarks are buried behind it, barely visable:

Is there a way to make it so the placemark undeaneath can come to the top? A way to control the z-level? I believe a problem might be that the polygon kml acting at the large blue overlay has the attribute: gx:altitudeModeclampToSeaFloor/gx:altitudeMode

And I noticed that "gx:altitudeMode" has yet to incorporated into the API, perhaps that is the problem?

[mramato]

I swear I answered this yesterday, but I guess I never submitted the comment. I just posted an answer to the same question on the mailing list. I assume that was you too?

[maburiza]

Hi, How can I get the coordinates from Kml file using JavaScript

[Hoverbear]

Hi folks, is there anyone working on lookAt right now? If not, could someone point me at where I might want to look to add this or at least access the data in the KML? Thanks.

[mramato]

@maburiza and @Hoverbear in the future, please use the forum for general questions and discussions. More people will see it and you're likely to get a faster answer.

@maburiza We don't have a way to directly get the extent of an entire file (since it changes over time), but you can iterate the loaded entities and discover any information you need.

@Hoverbear No one is working on lookAt, but if you are interested in adding the capability, we would be willing to look at a pull request. My first approach would be to modify processFeature in KmlDataSource to load the lookAt element and convert it and assign it to the viewFrom property on the Entity being created. There might be some roadblocks to this approach but if you take it as far as you can and open a PR, we can help you finish it.

Please create a forum topic to continue any further discussion.

[maikuru]

There are some sample KML files for regions in this forum thread https://groups.google.com/forum/#!topic/cesium-dev/7BTA9RCCdIc

[tonpo]

Other resources for regions. I find them more clear for me than the KML reference:

1. the standard
2. this tutorial: http://www.google.com/earth/outreach/tutorials/region.html