For several years, the documentation for CZML has been woefully incomplete. I’ve recently spent some time to work on revisions to the documentation text itself, and to re-generate the documentation output markdown.
Going forward, the documentation will be hosted on the czml-writer wiki:
The main change is the reference documentation, which should now reflect the current implementation. Each “type” is now a separate page with links between pages, to avoid previous problems with GitHub refusing to render one huge markdown file. I’ve started working on adding example CZML fragments to various pages, but there is much more left to do. Contributions welcome.
Sweet, thanks! I’m not actively using CZML myself at the moment, but I’d noted in the past that the CZML reference docs were both out of date and harder to read. Thank you for updating those.
The one additional request I’d make is a categorized page Table of Contents. The Github wiki has a list of all pages accessible on the right, and the “Packet” page has links to the intermediate types, but it’d be nice to able to see what all the pieces are in one place.
The one additional request I’d make is a categorized page Table of Contents.
I thought about this, but I’m not sure what that would look like. The individual low-level pieces of a document (e.g. BoxDimensions, DirectionList, UnitQuaternionValue, etc.) don’t really exist in isolation by themselves, they’re only meaningful in context. Conceptually, the Packet type is the table of contents.
I noticed that in CornerType.jsonschema, properties has CornerType, shouldn’t this be lower case cornerType to be consistent?
Yes, thanks. Fixed.
I noticed that CornerTypes are String in CZML, but they are integers in Cesium.
This is true of all enums in CZML and is intentional. The transport format (CZML) always deals with strings, the numeric representation in Cesium - or the numeric representation in czml-writer, for that matter - don’t matter.
I'm going to say up front that my comment may come across as sounding rude but that isn't the intention I promise. I'm just pointing out what I see.
I've asked before if CZML is something that AGI/Cesium team was committed to or if it may die out. I was told it was 100% the way to go and would be THE way to do stuff. It really doesn't seem like it though.
It would be really nice to have a better format of docs. I mean, any updates/fixes/etc are welcomed but leaving it in wiki for some other project (even though somewhat related) as opposed to having something that is better formatted, searchable, etc just seems like a half hearted "we dont really wanna mess with this" attempt.
If CZML is going to play such a big role in Cesium, why isn't it part of the Cesium docs?
We originally created CZML specifically for this purpose, and the Components Cesium library is built on top of the open-source czml-writer, which in turn is largely code-generated from the schema definition. As AGI builds new client-server products, Cesium is our primary visualization platform, and CZML is our primary transport format for loading data into that visualization, based on server-side calculations and analysis. So will it die out? No.
Is CZML THE way to do things in Cesium? Maybe, depending on one’s need. If an app doesn’t need to visualize a time-dynamic scene generated externally from Cesium, then maybe not. The various layers of the Cesium API provide different entry points with different amounts of flexibility (primitives - update everything yourself however you want, entities - tell Cesium declaratively how it should update things based on time, CZML - write a document describing how things change based on time).
All that said, however, I have also seen that CZML has become an afterthought for the team recently, unfortunately. Personally, I will be trying to take a stronger ownership role on CZML itself in the future. I am working on adding a number of features that were never properly put into the spec, and there are a few pull requests open with some great features that I want to give a careful and thorough review so we can bring them in (arbitrary reference frames and custom properties).
First off, thanks for the response and I primarily mean this: "All that said, however, I have also seen that CZML has become an afterthought for the team recently, unfortunately."
As mentioned, my post wasn't intended to seem rude or anything of that nature and I'm glad to see that you guys could acknowledge it isn't of blowing users off and making it seem like they are crazy for suggesting something like this. Not that you guys do that, but a lot of developers do.
In my current use case, I rely completely on czml and the entity api. I moved away from primitives completely a while back. I'm about to begin work on another little task that will rely exclusively on czml, hence my questions and interest in getting the docs updated and all.
As far as what the docs should look like, I'm not 100% sure. I guess I really more mentioned them being part of the Cesium docs because I kinda like the new format of the Cesium docs. I understand that because of the flexibility of the format that, that may be difficult to pull off. Using github pages to create something searchable, cleanly styled would be better in my opinion than something that is just the vanilla black/white with no styling and no visual separation between objects within the page.