Migrating from Google Earth Part II

This tutorial looks at major concepts in Cesium from the perspective of a Google Earth plugin developer. We’ll draw from the 30 Google Earth examples and demos that were ported to Cesium.

This is Part II in a series of tutorials. If you haven’t already, check out Part I.

Positions and Rectangles

When specifying positions, there are a few basic differences between GE and Cesium:

  • GE uses latitude and longitude, in that order, and defines them in degrees. Natively, Cesium uses Cartesian positions (x, y, z) in WGS84 coordinates (and other reference frames like north-east-up).
  • Cesium provides helper functions to construct a Cartesian position from longitude, latitude, and an optional height (in that order) like Cartesian3.fromDegrees and Cartesian3.fromDegreesArray.
  • With the exception of fromDegrees helpers, angles in Cesium are measured in radians, not degrees like GE. Like GE, distances are always in meters.
  • In GE, rectangle parameters are ordered north, south, east, west. In Cesium, they are west, south, east, north (think lower-left then upper-right).

Putting these concepts together, here’s an example of creating a ground overlay in Cesium:

var latitude = 40.0;
var longitude = -100.0;
var north = latitude + .35;
var south = latitude - .35;
var east = longitude + 1.55;
var west = longitude - 1.55;
var rectangle = Cesium.Rectangle.fromDegrees(west, south, east, north);

var entity = viewer.entities.add({
  rectangle : {
    coordinates : rectangle,
    material : './static/Cesium_Logo_Color.jpg'
  }
});

See this example side-by-side with the GE example code.

Example

In general, the GE plugin API follows the layout of KML. The Cesium API is more general; it abstracts geospatial and graphics concepts, and provides more fine-grained control over the scene.

In the code above, we added an Entity which can contain different types of graphics…

Placemarks and Beyond

In Cesium, an entity can represent a placemark by including a label to represent the text and a billboard to represent the icon. For example:

var pinBuilder = new Cesium.PinBuilder();
var entity = viewer.entities.add({
    position : Cesium.Cartesian3.fromDegrees(-75.10, 39.57),
    label : {
        text : 'pin' + counter,
        verticalOrigin : Cesium.VerticalOrigin.TOP
    },
    billboard : {
        image : pinBuilder.fromColor(Cesium.Color.SALMON, 48).toDataURL(),
        verticalOrigin : Cesium.VerticalOrigin.BOTTOM,
    }
});

See the side-by-side placemark examples with GE: creating and styling.

Placemarks

By default, the label and billboard are both centered at the entity’s position so the verticalOrigin property is used to draw the label below the center point and the billboard above it.

In addition to assigning an image url to a billboard’s image, PinBuilder can be used to create custom pins.

Cesium offers many more shapes and volumes, such as cylinders, corridors, and ellipsoids. See the Visualizing Spatial Data tutorial for a full list. Also check out the side-by-side examples for line strings, polygons, and circle.

Camera Control

Cesium has camera control similar to GE’s. Here’s a GE example:

var camera = ge.getView().copyAsCamera(ge.ALTITUDE_RELATIVE_TO_GROUND);
camera.set(latitude, longitude, altitude, ge.ALTITUDE_ABSOLUTE, heading, tilt, roll);
ge.getView().setAbstractView(camera);

In Cesium, this would be:

viewer.camera.setView({
    destination : Cesium.Cartesian3.fromDegrees(longitude, latitude, altitude),
    orientation: {
        heading : Cesium.Math.toRadians(heading),
        pitch : Cesium.Math.toRadians(tilt - 90.0),
        roll : Cesium.Math.toRadians(roll)
    }
});

The position, in degrees, is converted to Cartesian. The heading, pitch, and roll are converted from degrees to radians. In GE, tilt ranges from 0 (straight down) to 180 (straight up) compared to -90 (straight down) to 90 (straight up) so 90 degrees is subtracted.

setView sets the view immediately. Instead, we can fly to a view using flyTo.

viewer.camera.flyTo({
  destination : Cesium.Cartesian3.fromDegrees(-75.1641667, 39.9522222, 6000.0),
  orientation : {
    heading : Cesium.Math.toRadians(35.0),
    pitch : Cesium.Math.toRadians(-35.0),
    roll : 0.0
  },
  duration : 4.0, // in seconds
  complete : function() {
    // called when the flight finishes
  }
});

Since we often want to use the camera to view an entity, camera-entity integration allows us to easily zoom or fly to an entity or collection of entities:

var heading = Cesium.Math.toRadians(90);
var pitch = Cesium.Math.toRadians(-30);
viewer.zoomTo(entity, new Cesium.HeadingPitchRange(heading, pitch));

Check out the side-by-side examples for moving the camera and tilting the camera.

3D Models

GE supports 3D models using COLLADA. Cesium supports 3D models, including key-frame animation, skinning, and individual node picking, using glTF, an emerging industry-standard format for 3D models on the web by the Khronos Group, the consortium behind WebGL and COLLADA. Cesium also provides a web-based tool to convert COLLADA models to glTF for optimized use with Cesium.

glTF models have a .gltfextension and are loaded using the modelproperty of an entity.

var entity = viewer.entities.add({
  position : Cesium.Cartesian3.fromDegrees(-100, 40),
  model : {
    uri : './static/Cesium_Man.gltf',
    scale : 10
  }
});

3D Model Example

Here is a side-by-side code example.

Using Terrain

Cesium supports streaming high-resolution global terrain using open-formats including the optimized quantized-mesh format. A global high-resolution terrain data, STK World Terrain, is hosted on cesiumjs.org. Use it in Cesium like this:

viewer.terrainProvider = new Cesium.CesiumTerrainProvider({
    url : '//assets.agi.com/stk-terrain/world'
});

Terrain Example

For side-by-side code examples, see show/hide terrain and retrieving altitude.

Screen Overlays

Since Cesium is not a plugin, other HTML elements can be composited over top of it. This is useful for overlaying web UIs and screen overlays. Check out the side-by-side code examples for frame and screen overlays.

KML

Initial KML support, including KMZ, was released with Cesium 1.7 on March 2nd, 2015. Check out the live demo in Sandcastle. A good portion of KML 2.2 is supported and future versions of Cesium will continue to add additional capabilities until we reach full parity with Google Earth.

Many users also convert their KML to the Cesium Language, CZML, a JSON schema for describing Cesium scenes. This has many benefits including being web-friendly JSON, first-class support for time-dynamic visualization, and incremental streaming.

Next Steps

Cesium has a lot more to offer. Check out all the Cesium features and the standard tutorials.