CesiumJS

[CesiumJS]Cesium Intermediate Tutorial 1 - Spatial Data Visualization (Part 1)

Cesium Chinese Website: http://cesiumcn.org/ | China fast access: http://cesium.coinidea.com/

This tutorial will teach readers how to use Cesium’s Entity API to draw spatial data such as points, markers, labels, lines, models, shapes, and volumes. No prior knowledge of Cesium is required, but if you have no experience at all, you may want to start with the “Getting Started Tutorial”.

What is the Entity API?

Cesium has a rich API for spatial data, which can be divided into two categories: a low-level API oriented toward graphics developers (commonly called the Primitive API) and a high-level API for data-driven visualization (called the Entity API).

The primary goal of the Primitive API is to expose the minimal amount of abstraction needed for the task at hand. It expects us to think like graphics programmers and use graphics terminology. Its structure is designed to provide the most performant and flexible implementation for a given type of visualization, rather than API consistency. Loading a model is different from creating a billboard, and both are completely different from creating a polygon. Each type of visualization has its own unique characteristics. Furthermore, they each have different performance characteristics and require following different best practices. While it is powerful and flexible, most applications provide higher-level service interfaces than the Primitive API’s level of abstraction.

The purpose of the Entity API is to expose a set of consistently designed high-level objects that aggregate related visualization and information into a unified data structure we call an Entity. It lets us focus on presenting our data rather than worrying about the underlying mechanisms of visualization. It also provides constructs that make it easy to build complex, time-dynamic visualizations that naturally fit with static data. While the Entity API actually uses the Primitive API behind the scenes, this is an implementation detail we (almost) never need to concern ourselves with. By applying various heuristics to the data we provide, the Entity API is able to deliver flexible, high-performance visualization while exposing a consistent, easy-to-learn, and easy-to-use interface.

Our First Entity

One of the basic ways to learn the Entity API is by looking at some code. To keep things simple, we’ll build on CesiumSandcastle’s Hello World example. If you’re developing Cesium locally, feel free to use your own application.

Suppose we want to add a polygon of the US state Wyoming from a list of longitudes and latitudes. (Wyoming was chosen because it’s a simple polygon.) We can copy and paste the following code into Sandcastle:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

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

var wyoming = viewer.entities.add({
  name : 'Wyoming',
  polygon : {
    hierarchy : Cesium.Cartesian3.fromDegreesArray([
                              -109.080842,45.002073,
                              -105.91517,45.002073,
                              -104.058488,44.996596,
                              -104.053011,43.002989,
                              -104.053011,41.003906,
                              -105.728954,40.998429,
                              -107.919731,41.003906,
                              -109.04798,40.998429,
                              -111.047063,40.998429,
                              -111.047063,42.000709,
                              -111.047063,44.476286,
                              -111.05254,45.002073]),
    height : 0,
    material : Cesium.Color.RED.withAlpha(0.5),
    outline : true,
    outlineColor : Cesium.Color.BLACK
  }
});

viewer.zoomTo(wyoming);

Click the Run button (or press F8) to see the following image:

Because one of our goals is to make Cesium code easy to understand, hopefully this is self-explanatory. We created the Viewer widget, which serves as the foundation for almost all Cesium applications, then added a new Entity via viewer.entities.add. The object we pass to add is just an options parameter providing initial values. The return value is the actual entity instance. Finally, we call viewer.zoomTo to make sure the entity is in view. There are many entity options available, but for now we specify a polygon with a semi-transparent red interior and a black outline. We also give the entity a display name of “Wyoming”.

Shapes and Volumes

With the basic knowledge of creating polygons, and thanks to the homogeneity of the Entity API, we can now create various graphics simply by using the Sandcastle examples as reference. Below is a complete list of supported shapes and volumes.

Materials and Outlines

Regardless of their geometric definition, all shapes and volumes have a common set of properties that control their appearance. The fill property is a boolean that specifies whether the interior surface is filled, while the outline property controls whether the shape’s edges are outlined. When fill is set to true, the material property determines what the fill looks like. In the following example, let’s create a semi-transparent blue ellipse. By default, fill is true and outline is false, so we only need to specify the material.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var entity = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(-103.0, 40.0),
  ellipse : {
    semiMinorAxis : 250000.0,
    semiMajorAxis : 400000.0,
    material : Cesium.Color.BLUE.withAlpha(0.5)
  }
});
viewer.zoomTo(viewer.entities);

var ellipse = entity.ellipse; // For upcoming examples

Image

We can also specify the material as an image URL:

1

ellipse.material = '//cesiumjs.org/tutorials/images/cats.jpg';

In both cases above, a ColorMaterialProperty or ImageMaterialProperty is automatically created for us during assignment. For more complex materials, we need to create a material property instance ourselves. Currently, entity shapes and volumes support color, image, checkerboard, stripe, and grid materials.

Checkerboard

1
2
3
4
5

ellipse.material = new Cesium.CheckerboardMaterialProperty({
  evenColor : Cesium.Color.WHITE,
  oddColor : Cesium.Color.BLACK,
  repeat : new Cesium.Cartesian2(4, 4)
});

Stripe

1
2
3
4
5

ellipse.material = new Cesium.StripeMaterialProperty({
  evenColor : Cesium.Color.WHITE,
  oddColor : Cesium.Color.BLACK,
  repeat : 32
});

Grid

1
2
3
4
5
6

ellipse.material = new Cesium.GridMaterialProperty({
  color : Cesium.Color.YELLOW,
  cellAlpha : 0.2,
  lineCount : new Cesium.Cartesian2(8, 8),
  lineThickness : new Cesium.Cartesian2(2.0, 2.0)
});

Outline

Unlike the fill property, outline does not have a corresponding material, but instead relies on two separate properties: outlineColor and outlineWidth. outlineWidth only works on non-Windows systems such as Android, iOS, Linux, and OS X. This is due to limitations in how WebGL is implemented in all three major browser engines on Windows.

1
2
3
4

ellipse.fill = false;
ellipse.outline = true;
ellipse.outlineColor = Cesium.Color.YELLOW;
ellipse.outlineWidth = 2.0;

Polyline

Polylines are a special case because they don’t have fill or outline properties. Instead, they rely on specialized materials to replace colors. Because of these special materials, polylines with different widths and outline widths will work on all systems.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

var entity = viewer.entities.add({
    polyline : {
        positions : Cesium.Cartesian3.fromDegreesArray([-77, 35,
                                                        -77.1, 35]),
    width : 5,
    material : Cesium.Color.RED
}});
viewer.zoomTo(viewer.entities);

var polyline = entity.polyline // For upcoming examples

Polyline Outline

1
2
3
4
5

polyline.material = new Cesium.PolylineOutlineMaterialProperty({
    color : Cesium.Color.ORANGE,
    outlineWidth : 3,
    outlineColor : Cesium.Color.BLACK
});

Polyline Glow

1
2
3
4

polyline.material = new Cesium.PolylineGlowMaterialProperty({
    glowPower : 0.2,
    color : Cesium.Color.BLUE
});

Height and Extrusion

All shapes that overlay the globe – currently circles, ellipses, polygons, and rectangles – can also be placed at an altitude or extruded into a volume. In both cases, the shape or volume still conforms to the curvature of the Earth beneath it.

For height, all we need to do is set the height property on the corresponding graphics object, which is the same for all shapes listed above. This might be a good time to mention that Cesium always uses meters, radians, and seconds as units, unless a function explicitly indicates otherwise, such as Cartesian3.fromDegrees. The following line of code elevates the polygon to 250,000 meters above the Earth.

1

wyoming.polygon.height = 250000;

Extruding a shape into a volume is equally easy – we just need to set the extrudedHeight property. The volume will be generated between height and extrudedHeight. If height is undefined, the volume starts from 0. To create a volume that starts at 200,000 meters and extends to 250,000 meters, we can use the following code. This of course means the volume itself is 50,000 meters tall.

1
2

wyoming.polygon.height = 200000;
wyoming.polygon.extrudedHeight = 250000;

Cesium Chinese Community QQ Group: 807482793

Cesium Chinese Website: http://cesiumcn.org/ | China fast access: http://cesium.coinidea.com/