External links in czml


I’m currently writing up a wiki for external link support in czml. It’s another major feature we’re planning that will provide some powerful features. In a number of ways it can be compared to kml networklinks(but better). The wiki page is a work in progress, but please take a look at https://github.com/AnalyticalGraphicsInc/cesium/wiki/External-links and let me know of any features that you’d like to see or any ideas you might have.




I am the least knowledgeable in this area, but this looks like a good start. As discussed, Amato is interested in decoupling layers; you guys can sort that out.

I’m curious to hear Fili’s and Hank’s input. Given all the work Fili did with KML network links and that Hank is interested in using this.



I took a look at what you have so far and while I understand what you
are trying to do, I don't think the approach you're taking will work
in the current architecture. The ideas laid out on the wiki look
good, but the implementation needs to be different. My thoughts on
the czmlLayers branch code are below, followed by some high-level
thoughts on implementation. I can also put some information on the
wiki to flesh them out some more, but I didn't want to "step on your
toes" so to speak. I'll also mention that I'm treating layers as a
separate feature compared to external links. My plan would be to
implement external links completely and get it into master and then
add layers after that. Our concept for Czml layers (which still needs
to be fleshed out) is very different than the structural layout of KML
folders, so trying to simply treat external links as a layer won't
work for us. This concept will be needed in KML coversion anyway once
we go to impelement NetworkLinkUpdate in addition to just NetworkLink.

Branch review

Core/getJson - The documentation is no longer correct for this
function, since no dojo is involved.

Core/xhrGet - The headers should probably be passed in as parameters
rather than hardcoded, otherwise xhrGet will only work with json text.

DynamicScene/CompositeDynamicObjectCollection.js - The private
_getOrCreateObject method needs to remain private, it should never be
called externally as the only objects allowed to exist in a
CompositeDynamicObjectCollection are wrapper objects consisting of
properties from other DynamicObjectCollections. Objects are never
allowed to be added to a \CompositeDynamicObjectCollection.js manually
or otherwise.

DynamicScene/CzmlDefaults - You'll need a merger and cleaner for
processCzmlPacketExternal as well, or CompositeDynamicObjectCollection
won't work. Also, instead of having processCzmlPacketExternal on
DynamicObject, you should have an ExternalLink object (like we have a
DynamicBillboard) because external will ultimately consist of multiple
properties and not just be a single property; more on that below.

DynamicScene/DynamicExternalDocumentProperty - This object shouldn't
exist because the handling of external documents should not be done at
CZML processing time. CZML processing simply turns CZML JSON into
usable properties. It doesn't actually do anything with those
properties. Also, the external document shouldn't be processing in
the same DynamicObjectCollection as the parent CZML, this way the
external data is merged non-destructively.

DynamicScene/processCzml - Since we shouldn't actually process the
external document data as part of the processCzml step, none of these
changes are needed any longer.

My thoughts on implementation

Create an ExternalLink object, following the same strategy as other
objects such as DynamicBillboard. This object contains all properties
related to defining a single external link. An "external" property in
CZML gets turned into ExternalLink instances during the CZML
processing stage. All of these properties can vary with time just
like any other CZML property.

Create a new CzmlDocumentManager object, this object manages mutliple
CZML sources and processes and updates external links and produces a
single CompositeDynamicObjectCollection property (maybe
CzmlDocumentManager.dynamicObjects?) as output which can be used by
clients for visualization. This is similar to
CompositeObjectDynamicCollection, but it's one level of abstraction
hire and may eventually serve as the main interface for a
DocumentManager UI.

Most of the "heaving lifting" would be performed in
CzmlDocumentManager.update. This function iterates over all of the
DynamicObjects looking for "externalLink" properties. If it finds an
externalLink, it checks it against a map of existing links and sees
what processing (if any) is needed during this update. External links
are almost always processed in their own DynamicObjectCollection
instance, this way it can be non-destrucively merged with the rest of
the data. At the end of the process, it needs to remove all of the
dynamicObjectCollection instances associated with externaLinks that no
longer exist. (Of course depending on the nature of the link, it
might want to cache them rather than destroy them out right so that
they can be quickly brought back as animation changes.) To the
outside observer, the result of the CzmlDocumentManager.update is
simply changes to the flat collection of objects in the
CzmlDocumentManager.dynamicObjects. The rest of the system doesn't
require any knowledge of external links whatsoever.

Using these two objects, it's now easy to change the ViewerWidget to
simply have an instance of CzmlDocumentManager and pass the
CzmlDocumentManager.dynamicObjectCollection it produces to the
visualizer collection. During the render loop, you first call
update(time) on CzmlDocumentManager and then call update on
visualizers. I feel like I didn't do the best job explaining my
thoughts, but hopefully this helps get us on the same page. Lets get
together sometime soon to discuss this and flesh things out some more.



Matt, Thanks for your input. It’s greatly appreciated.

Some thoughts:

the branch name is a misnomer- My plan is only to address network links and network link updates(it currently can update existing objects).

Layers will be a powerful feature for CZML and we all know it’s on the horizon. As of yet, there has been no discussion of the concept of CZML layers. Because of this, there’s no way to know what the difference between the structural layout of KML folders and CZML layers really is. We should start discussions on layers as soon as possible to really understand what we want accomplished with them. Fortunately, I’m not working on the folders aspect, just network links.

A couple notes:

A lot of this is just code thrown together as proof of concept, so I’m not worried about documentation issues or other similar things. This will all be cleaned up once things are ironed out. At this point I’d like to understand how the dynamic scene structure works so I can make better decisions going forward.


This will change. I was trying the scoping aspect and for that to work, the CompositeDynamicObjectCollection could contain another CompositeDynamicObjectCollection. I’m rethinking scoping.


it’s actually creating a new DynamicObjectCollection and populating that with the network link’s generated CZML. Also if there’s a networklink update it handles that correctly too. It’s a non-destructive merge. It can handle SatelliteDatabase.kmz which is structured like networklink->networkLink->networkLinkUpdate. Three DynamicObjectCollections are used and each networklink populates the correct collection.

The document manager is something I worked on a long time ago and I completely agree its needed. We can also create a DocumentManager widget that displays all the documents and the children contained in each document. I can also see it being used to toggle layers on and off(useful if multiple layers are defined at the same interval and the user wants to see what’s going on ). Again, we need to start the discussion on layers though.

Thanks again,