This is an introduction to Sandcastle, a live-coding app for viewing Cesium examples and testing code quickly. The Cesium team uses Sandcastle constantly, and after this, we hope you will too!
Sandcastle provides a Cesium Viewer widget and a code editor. To modify examples, just edit the code and click ‘Run’ at the top of the window.
Browse the gallery of code examples to see the breath of Cesium capabilities. The examples are listed in the scrollable filmstrip at the bottom of the page. These examples can be filtered by labels, or with keywords using the search bar at the top. We’d start with Beginner examples.
Searching through the example code gallery.
Sandcastle provides easy-access for Cesium documentation. Simply double-click on a Cesium class, function or property in the code to open the relevant documentation page in a new tab on the right side of Sandcastle.
Code completion and quick documentation access.
Sandcastle makes it easy to share code examples.
To share a code example as is in Sandcastle, click the Share button at the top, which will save the current code as a GitHub Gist and generate a url to a Sandcastle example with the code loaded.
This is the best way to share code on the Cesium forum when asking for help, since this provides a live example of your work. The Cesium team also especially appreciates this when submitting bugs on GitHub.
Load saved Github Gists by clicking the Import Gist button and entering a generated gist url or ID.
Save, share and load examples quickly.
To save a Sandcastle example as an html for use in a local Cesium repository (and hopefully for contribution later!), just click the Save As button at the top, which will download the current code as an html file. Save the file as Apps/Sandcastle/gallery/*.html for use in a local build.
Sandcastle also provides some basic GUI widgets, helpful for interactive testing and debugging. Sandcastle widgets include buttons, dropdown menus and toggle buttons. See code examples here.
When a GUI element is triggered, Sandcastle will also highlight the executed code in green so it is easy to fine the related code.
Simple GUI examples.
Sandcastle is hosted on our website, but is also included in the Cesium repository, and can be built to use a local version of Cesium. See our build guide for more details. Using a local build is useful for testing code with different branches of Cesium.
Do you have a minimalist example that demonstrates a helpful Cesium feature? We’re always in need of more Sandcastle gallery additions! Feel free to open a pull request! See the Contributor’s Guide for how to get started.
Your Sandcastle example will require a few things:
That’s it! We hope you find Sandcastle as useful as we do!