Skip to content

CZML Guide

Jump to bottom
Scott Hunter edited this page Jun 14, 2016 · 2 revisions

Cesium Language (CZML) Guide

CZML is a JSON format for describing a time-dynamic graphical scene, primarily for display in a web browser running Cesium. It describes lines, points, billboards, models, and other graphical primitives, and specifies how they change with time. While Cesium has a rich client-side API, CZML allows it to be 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. Every property is time-dynamic.
  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.
  6. CZML is an open format. We would like as many projects to take advantage of it as possible and hope to one day formalize with a standard body, such as OGC.
  7. An open-source library, czml-writer, for writing CZML is maintained on Github.
  • CZML Structure - the overall structure of a CZML document / stream.
  • Packet - the schema of the standard content present in a CZML document / stream.

Live demos are available on the Cesium Home page.

Clone this wiki locally