Skip to main content

EclipseTracks - Interactive Solar Eclipses with Cesium

This is a guest post by Christopher Clark, creator of, who describes the app and its CZML toolchain. - Patrick

This Friday the only total solar eclipse of 2015 will cut between the U.K and Iceland on its way to the north pole. Solar eclipses occur about once every 18 months but their planet-wide nature means any one place can go decades between events. On August 21, 2017 the first total solar eclipse in the United States since 1994 takes place, and wanting to be able to explore the best areas to be along the ~100km wide coast-to-coast path of totality, I turned to Cesium and built

Data for the project was readily available from NASA's Eclipse website run by Fred Espenak. Scraping tables like this one for the August 2017 eclipse yielded values such as northern and southern umbral shadow limits along a central track on a two minute interval throughout each celestial event. Two open source python libraries were involved to transmute any NASA eclipse table into a valid CZML document. The application itself is also open source and all three are detailed further below.

The Python CZML Writer

In early 2013 Christian Lederman kicked off an open source library to read and write CZML in python. Development slowed down by mid-2014 (just shy of the Cesium 1.0 release). Also, since CZML is an extensive and descriptive language, there were many components that were under-supported or not yet supported at all.

After joining as a collaborator on the project, the python czml package is now available for python 2 and 3. It also now offers full support for all two-dimensional objects and their components, including materials. Position and coordinate system support has also been updated, and document object and clock support have been added.


Next came the middleware: a library to take an arbitrary NASA eclipse table as input and generate valid CZML as output, achieved through another open source python package called eclipsescraper.

Authoring CZML documents as the primary function of a test-driven development project can be daunting as good tests require hand-curated CZML content to compare against generated output. The library also generates JSON metadata objects for additional event information that would otherwise appear out of place baked into a CZML document itself. Here is where the work put into the python czml library paid off, as generating valid CZML from well-structured data objects is fast and straightforward.

EclipseTracks is itself open source and benefits from having a light server-side footprint. Indexing available events is done in a local flat file that is used by both the CZML generator script implementing eclipsescraper as well as the initializing JavaScript to build a navigation menu.

To bundle Cesium with the project efficiently, it is a subtree of the application repository. The subtree method offers the simplicity of adding Cesium to the project in a single squashed merge commit with easy ability to pull down new changes in subsequent squashed merge commits. And unlike with submodules, the subtree fades into the periphery of the application, never creating dependency errors.

Application deployment is on an inexpensive virtual private host, so bandwidth concerns are an issue. GitHub pages has served as an excellent pressure release for this situation, as further detailed here.

Challenges and Future Potential

The application's greatest current drawback is the inaccuracy of the animated umbral shadows for any given event. Detailed further here, in a nutshell, a proper comprehensive approach requires using Besselian elements to model the shadow cone and perpendicular fundamental plane for a given event. Positions for surface objects could then be generated finding conic intersections with the WGS-84 ellipsoid. It's unclear how difficult this will be given the current tool chain, but I hope to make progress on it before the North American eclipse of 2017 (shown below).

Once modeled, however, Cesium offers the ability to show much more interesting data for each event. In addition to accurate umbral shadows modeled with polygons the application could include polylines to model various levels of penumbral coverage, points to mark the location and moment of the greatest eclipse, or even the shadow cones and fundamental plane described by the Besselian elements. In concert with the app itself a search function to find eclipse events near a given location on the planet could also be featured. Of all the ways the application could go it has been rewarding to build and hopefully serves as a useful tool to solar eclipse enthusiasts around the world.

Christopher Clark