This tutorial will get developers of all skill levels up and running with their first Cesium application.

Making sure that your browser is Cesium-ready

The easiest way to verify that Cesium works in your web browser is to run the Hello World example by clicking here (opens a new window). If you see something like the below image, congratulations, your system can run Cesium and you can safely skip to the next section; otherwise, continue reading.

Cesium is built on several new HTML5 technologies, the most important of which is WebGL. Even though these new standards are quickly becoming widely adopted, some browsers and systems need to be updated to support them. If the example application doesn’t work for you, here are a few things to try.

  1. Update your web browser. Most of the Cesium team uses Google Chrome, but Firefox, Internet Explorer 11, and Opera will also work. If you’re already using one of the above browsers, make sure it’s updated to the latest version.
  2. Update your video card driver to better support 3D. If you know what type of video card you have, you can check the vendor web site for updates. The three most popular are: Nvidia, AMD, and Intel.
  3. If you’re still having problems, try visiting http://get.webgl.org/, which offers additional trouble-shooting advice. You can also ask for help on the Cesium forum.

Selecting an editor or IDE

If you’re already a seasoned developer, you most likely have a favorite editor or development environment; for example, most of the Cesium team uses Eclipse. If you’re just starting out, a great free and open-source editor is Notepad++, which you can download from their website. Ultimately any text editor will do, so go with the one that you are most comfortable with.

Downloading a Cesium release

Assuming you haven’t already done so, click this button to grab the latest Cesium release: Cesium-1.29.zip

Once downloaded, extract the zip file into a new directory of your choice, I’ll refer to this throughout the tutorial as the Cesium root directory. The contents should look something like the below.

It may be tempting to double-click on index.html, but we’ll only be greeted with disappointment. In order for the application to actually work, it needs to run within a web server.

Setting up a web server

In order to run Cesium applications, we’ll need a local web server to host our files. We’ll be using Node.js for this and other tutorials. If you already have a web server that you want to use, that’s fine too, just be sure to host the root directory that we created in the previous section. Cesium has no server requirements; it is completely client side. This means any web server that can host static content can also host Cesium.

Setting up a web server with Node.js is easy and only takes 3 steps. 1. Install Node.js from their website, you can use the default install settings. 2. Open a command shell in the Cesium root directory and download/install the required modules by executing npm install. This will create a ‘node_modules’ directory in the root directory. 3. Finally, start your web server by executing node server.js in the root directory. 4. You should see something like the below

Hello (again) world!

Now that we have a web server up and running, we can launch a browser and navigate to http://localhost:8080/Apps/HelloWorld.html. This is the same Hello World application we used to test WebGL at the beginning of the tutorial, but now it’s running on your own system instead of the Cesium website. If we open up HelloWorld.html in an editor, we’ll find the following simple application.

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- Use correct character set. -->
  <meta charset="utf-8">
  <!-- Tell IE to use the latest, best version. -->
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <!-- Make the application on mobile take up the full browser screen and disable user scaling. -->
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no">
  <title>Hello World!</title>
  <script src="../Build/Cesium/Cesium.js"></script>
  <style>
      @import url(../Build/Cesium/Widgets/widgets.css);
      html, body, #cesiumContainer {
          width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden;
      }
  </style>
</head>
<body>
  <div id="cesiumContainer"></div>
  <script>
    var viewer = new Cesium.Viewer('cesiumContainer');
  </script>
</body>
</html>

These are the four lines needed to add Cesium to an application:

  1. The first step is to include Cesium.js in a script tag. This defines the Cesium object, which contains everything we need.

     <script src="../Build/Cesium/Cesium.js"></script>
    
  2. In order to use the Cesium Viewer widget, we need to include its CSS.

     @import url(../Build/Cesium/Widgets/widgets.css);
    
  3. In the HTML body, we create a div for the viewer to live.

     <div id="cesiumContainer"></div>
    
  4. Finally, we create an instance of viewer.

     var viewer = new Cesium.Viewer('cesiumContainer');
    

Where to go from here

Congratulations, you are up and running with Cesium and ready to start writing your own Cesium applications and web pages. Depending on the type of learner you are, you may be interested in checking out the other tutorials, which introduce the major Cesium features. If you’re a tinkerer, then Cesium Sandcastle is a live coding application that will allow you to not only view dozens of examples, but view and edit their source code, running with your updated changes from within the application. Finally, no matter how you learn, the reference documentation contains details on the API and is an invaluable resource for everyone.