Cesium Language (CZML) Guide

Cesium Language (CZML) Guide

CZML is a language for describing a time-dynamic graphical scene for display in a web browser running Cesium. It describes lines, points, billboards (markers), models, and other graphical primitives, and specifies how they change with time. While Cesium has a rich client-side API, the CZML concept is to make it data-driven so that a generic Cesium viewer can display a rich scene without the need for any custom code. In many ways, the relationship between Cesium and CZML is similar to the relationship between Google Earth and KML. Both CZML and KML are data formats for describing scenes in their respective clients and are meant to be generated by a wide variety of applications and possibly even written by hand. And both are meant to be sufficiently client-agnostic that other, compatible clients can render the scene described therein. CZML has a number of important characteristics, some of which distinguish it from KML:

1. CZML is based on JSON.
2. CZML can accurately describe properties that change value over time. For example, a line can be red for one interval of time and blue for another. Clients are also expected to be able to interpolate over time-tagged samples. If the position of a vehicle is specified at two times, the client can accurately display the location of the vehicle in between those two times by using a CZML-specified interpolation algorithm.
3. CZML is structured for efficient, incremental streaming to a client. The entire document need not be present on the client before the scene can be displayed. In many cases, individual clients may even join and leave the stream while it is in progress.
4. CZML is optimized for client consumption; it aims to be compact and easy to parse. It is also reasonably readable and writable by humans.
5. CZML is extensible. While the primary goal of CZML is to communicate a scene to a virtual-globe-like client, the format can easily be extended to communicate additional static or time-dynamic data to a more sophisticated client. For example, time-dynamic data could be displayed on a 2D chart.

We describe CZML in three parts:

• CZML Structure - Describes the overall structure of a CZML document / stream.
• CZML Content - Describes the standard content, or graphical primitives, present in a CZML document / stream.
• CZML visualizers in Cesium - Describes the architecture for handling CZML within Cesium.

More information is available on the CZML landing page and on the Cesium main page.

There is also a czml-writer library on GitHub.