[CesiumJS] Cesium Intermediate Tutorial 7

Cesium Chinese website: http://cesiumcn.org/ | Fast access in China: http://cesium.coinidea.com/

This tutorial will introduce you to the geometry and appearance system using the Primitive API. This is an advanced topic for extending CesiumJS with custom meshes, shapes, volumes, and appearances, rather than for general Cesium users. If you are interested in learning how to draw various shapes and volumes on the globe, please check out the Creating Entities tutorial. CesiumJS can create different geometry types using entities (such as polygons and ellipsoids). For example, copy and paste the following code into the Hello World Sandcastle example to create a rectangle with a stripe pattern on the globe:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var viewer = new Cesium.Viewer('cesiumContainer');

viewer.entities.add({
    rectangle : {
        coordinates : Cesium.Rectangle.fromDegrees(-100.0, 20.0, -90.0, 30.0),
        material : new Cesium.StripeMaterialProperty({
            evenColor: Cesium.Color.WHITE,
            oddColor: Cesium.Color.BLUE,
            repeat: 5
        })
    }
});

In this tutorial, we will go under the hood and look at the geometry and appearance types that make them up. Geometry defines the structure of a Primitive, i.e., the triangles, lines, or points that make up the primitive. Appearance defines the shading of the Primitive, including its full GLSL vertex and fragment shaders, as well as the render state.

The benefits of using geometry and appearances are:

Performance: When drawing a large number of Primitives (such as polygons for every zip code in the United States), using geometry directly allows us to combine them into a single geometry to reduce CPU overhead and better utilize the GPU. Combining Primitives is done on a web worker to keep the UI responsive.
Flexibility: Primitives combine geometry and appearance. By separating them, we can modify each independently. We can add new geometries that are compatible with many different appearances, and vice versa.
Low-level access: Appearances provide close-to-the-metal rendering access without worrying about all the details of using the Renderer directly. Appearances make it easy to:
- Write full GLSL vertex and fragment shaders
- Use custom render states

Of course, there are also some drawbacks:

Using geometry and appearances directly requires more code and a deeper understanding of graphics. Entities are at an abstraction level suitable for mapping applications; geometry and appearances are at an abstraction level closer to a traditional 3D engine.
Combining geometries is effective for static data, but not necessarily for dynamic data.

Let’s rewrite the initial code example using geometry and appearances:

 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
27
28
var viewer = new Cesium.Viewer('cesiumContainer');
var scene = viewer.scene;

// original code
//viewer.entities.add({
//    rectangle : {
//        coordinates : Cesium.Rectangle.fromDegrees(-100.0, 20.0, -90.0, 30.0),
//        material : new Cesium.StripeMaterialProperty({
//            evenColor: Cesium.Color.WHITE,
//            oddColor: Cesium.Color.BLUE,
//            repeat: 5
//        })
//    }
//});

var instance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-100.0, 20.0, -90.0, 30.0),
    vertexFormat : Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT
  })
});

scene.primitives.add(new Cesium.Primitive({
  geometryInstances : instance,
  appearance : new Cesium.EllipsoidSurfaceAppearance({
    material : Cesium.Material.fromType('Stripe')
  })
}));

We used a Primitive (Primitive) instead of a rectangle entity, which combines geometry and appearance. For now, we will not distinguish between Geometry and GeometryInstance. An instance is not just an instance of a geometry, but also a container for it.

To create the geometry for a rectangle – the triangles covering the rectangular area and conforming to the curvature of the globe – we created a RectangleGeometry.

Since it is on the surface, we can use EllipsoidSurfaceAppearance. This saves memory by assuming the geometry is on the surface or at a constant height above the ellipsoid.

Geometry Types

CesiumJS provides the following geometries:

Combining Geometry

When we use a single Primitive to draw multiple static geometries, we see performance benefits. For example, drawing two rectangles in one Primitive.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 var viewer = new Cesium.Viewer('cesiumContainer');
var scene = viewer.scene;

var instance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-100.0, 20.0, -90.0, 30.0),
    vertexFormat : Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT
  })
});

var anotherInstance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-85.0, 20.0, -75.0, 30.0),
    vertexFormat : Cesium.EllipsoidSurfaceAppearance.VERTEX_FORMAT
  })
});

scene.primitives.add(new Cesium.Primitive({
  geometryInstances : [instance, anotherInstance],
  appearance : new Cesium.EllipsoidSurfaceAppearance({
    material : Cesium.Material.fromType('Stripe')
  })
}));

We created another instance with a different rectangle, then provided both instances to the Primitive. This draws both instances with the same appearance.

Some appearances allow each instance to provide unique attributes. For example, we can use PerInstanceColorAppearance to shade each instance with a different color.

 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
27
var viewer = new Cesium.Viewer('cesiumContainer');
var scene = viewer.scene;

var instance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-100.0, 20.0, -90.0, 30.0),
    vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
  }),
  attributes : {
    color : new Cesium.ColorGeometryInstanceAttribute(0.0, 0.0, 1.0, 0.8)
  }
});

var anotherInstance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-85.0, 20.0, -75.0, 30.0),
    vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
  }),
  attributes : {
    color : new Cesium.ColorGeometryInstanceAttribute(1.0, 0.0, 0.0, 0.8)
  }
});

scene.primitives.add(new Cesium.Primitive({
  geometryInstances : [instance, anotherInstance],
  appearance : new Cesium.PerInstanceColorAppearance()
}));

Each instance has a color attribute. The Primitive is constructed with PerInstanceColorAppearance, which uses each instance’s color attribute to determine the shading.

Combining geometries allows CesiumJS to efficiently draw many geometries. The following example draws 2,592 uniquely colored rectangles.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var viewer = new Cesium.Viewer('cesiumContainer');
var scene = viewer.scene;

var instances = [];

for (var lon = -180.0; lon < 180.0; lon += 5.0) {
  for (var lat = -85.0; lat < 85.0; lat += 5.0) {
    instances.push(new Cesium.GeometryInstance({
      geometry : new Cesium.RectangleGeometry({
        rectangle : Cesium.Rectangle.fromDegrees(lon, lat, lon + 5.0, lat + 5.0),
        vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
      }),
      attributes : {
        color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.fromRandom({alpha : 0.5}))
      }
    }));
  }
}

scene.primitives.add(new Cesium.Primitive({
  geometryInstances : instances,
  appearance : new Cesium.PerInstanceColorAppearance()
}));

Picking

Instances can be accessed independently after being combined. Assign an ID to an instance and use it to determine whether that instance is picked using Scene.Pick.

The following example creates an instance with an id and writes a message to the console when the instance is clicked.

 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 scene = viewer.scene;

var instance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-100.0, 30.0, -90.0, 40.0),
    vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
  }),
  id : 'my rectangle',
  attributes : {
    color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.RED)
  }
});

scene.primitives.add(new Cesium.Primitive({
  geometryInstances : instance,
  appearance : new Cesium.PerInstanceColorAppearance()
}));

var handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);
handler.setInputAction(function (movement) {
    var pick = scene.pick(movement.position);
    if (Cesium.defined(pick) && (pick.id === 'my rectangle')) {
      console.log('Mouse clicked rectangle.');
    }
  }, Cesium.ScreenSpaceEventType.LEFT_CLICK);

Using id avoids keeping a reference to the entire instance in memory after the Primitive is constructed, including the geometry.

Geometry Instances

Instances can be used to position, scale, and rotate the same geometry in different parts of the scene. This is possible because multiple instances can reference the same Geometry, and each instance can have a different modelMatrix. This allows us to compute the geometry only once and reuse it multiple times.

The following example creates an EllipsoidGeometry and two instances. Each instance references the same ellipsoid geometry but uses a different modelMatrix to place it, resulting in one ellipsoid positioned above the other.

 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
27
28
29
30
31
32
33
34
35
36
37
38
39
var viewer = new Cesium.Viewer('cesiumContainer');
var scene = viewer.scene;

var ellipsoidGeometry = new Cesium.EllipsoidGeometry({
    vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT,
    radii : new Cesium.Cartesian3(300000.0, 200000.0, 150000.0)
});

var cyanEllipsoidInstance = new Cesium.GeometryInstance({
    geometry : ellipsoidGeometry,
    modelMatrix : Cesium.Matrix4.multiplyByTranslation(
        Cesium.Transforms.eastNorthUpToFixedFrame(Cesium.Cartesian3.fromDegrees(-100.0, 40.0)),
        new Cesium.Cartesian3(0.0, 0.0, 150000.0),
        new Cesium.Matrix4()
    ),
    attributes : {
        color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.CYAN)
    }
});

var orangeEllipsoidInstance = new Cesium.GeometryInstance({
    geometry : ellipsoidGeometry,
    modelMatrix : Cesium.Matrix4.multiplyByTranslation(
        Cesium.Transforms.eastNorthUpToFixedFrame(Cesium.Cartesian3.fromDegrees(-100.0, 40.0)),
        new Cesium.Cartesian3(0.0, 0.0, 450000.0),
        new Cesium.Matrix4()
    ),
    attributes : {
        color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.ORANGE)
    }
});

scene.primitives.add(new Cesium.Primitive({
    geometryInstances : [cyanEllipsoidInstance, orangeEllipsoidInstance],
    appearance : new Cesium.PerInstanceColorAppearance({
        translucent : false,
        closed : true
    })
}));

Updating Per-Instance Attributes

After geometry is added to a Primitive, update per-instance attributes of the geometry to change the visualization. Per-instance attributes include:

Color: ColorGeometryInstanceAttribute determines the color of the instance. The Primitive must have a PerInstanceColorAppearance.
Show: A boolean type that determines whether the instance is visible. All instances have this attribute.

The following demonstrates how to change the color of a geometry instance:

 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
27
var viewer = new Cesium.Viewer('cesiumContainer');
var scene = viewer.scene;

var circleInstance = new Cesium.GeometryInstance({
    geometry : new Cesium.CircleGeometry({
        center : Cesium.Cartesian3.fromDegrees(-95.0, 43.0),
        radius : 250000.0,
        vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
    }),
    attributes : {
        color : Cesium.ColorGeometryInstanceAttribute.fromColor(new Cesium.Color(1.0, 0.0, 0.0, 0.5))
    },
    id: 'circle'
});
var primitive = new Cesium.Primitive({
    geometryInstances : circleInstance,
    appearance : new Cesium.PerInstanceColorAppearance({
        translucent : false,
        closed : true
    })
});
scene.primitives.add(primitive);

setInterval(function() {
    var attributes = primitive.getGeometryInstanceAttributes('circle');
    attributes.color = Cesium.ColorGeometryInstanceAttribute.toValue(Cesium.Color.fromRandom({alpha : 1.0}));
},2000);

The attributes of a geometry instance can be retrieved from the primitive using primitive.getGeometryInstanceAttributes. The properties of attributes can be changed directly.

Appearances

Geometry defines the structure. The other key property of a primitive, appearance, defines the shading of the primitive, i.e., the color of individual pixels. A primitive can have multiple geometry instances but only one appearance. Depending on the type of appearance, the appearance will have a material that defines the body of the shading.

CesiumJS has the following appearances:

Appearances define the full GLSL vertex and fragment shaders that are executed on the GPU when drawing a Primitive. Appearances also define the full render state, which controls the state of the GPU when drawing a primitive. We can define the render state directly, or use higher-level properties like “closed” and “translucent”, which the appearance will convert into render state. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// Perhaps for an opaque box that the viewer will not enter.
//  - Backface culled and depth tested.  No blending.

var appearance  = new Cesium.PerInstanceColorAppearance({
  translucent : false,
  closed : true
});

// This appearance is the same as above
var anotherAppearance  = new Cesium.PerInstanceColorAppearance({
  renderState : {
    depthTest : {
      enabled : true
    },
    cull : {
      enabled : true,
      face : Cesium.CullFace.BACK
    }
  }
});

Once an appearance is created, its renderState property cannot be changed, but its material can. We can also change the appearance property of a primitive.

Most appearances also have flat and faceForward properties, which indirectly control the GLSL shaders.

flat: Flat shading. Do not consider lighting.
faceForward: When lighting, flip the normal so that it always faces the viewer. Avoids dark areas on the back side, such as the inside of a wall.

Geometry and Appearance Compatibility

Not all appearances work with all geometries. For example, the EllipsoidSurfaceAppearance does not work with WallGeometry because a wall is not on the surface of the globe.

For an appearance to be compatible with a geometry, they must have matching vertex formats, meaning the geometry must have the input data expected by the appearance. A vertexFormat can be provided when creating a geometry.

The vertexFormat of a geometry determines whether it can be combined with other geometries. Two geometries do not need to be the same type, but they need matching vertex formats.

For convenience, appearances either have a vertexFormat property or a VERTEX_FORMAT static constant that can be passed as a geometry option.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
var geometry = new Ceisum.RectangleGeometry({
  vertexFormat : Ceisum.EllipsoidSurfaceAppearance.VERTEX_FORMAT
  // ...
});

var geometry2 = new Ceisum.RectangleGeometry({
  vertexFormat : Ceisum.PerInstanceColorAppearance.VERTEX_FORMAT
  // ...
});

var appearance = new Ceisum.MaterialAppearance(/* ... */);
var geometry3 = new Ceisum.RectangleGeometry({
  vertexFormat : appearance.vertexFormat
  // ...
});

Resources

Reference documentation:

For more materials, visit: Fabric For future plans, visit: Geometry and Appearances Roadmap

Cesium Chinese website QQ group: 807482793

Cesium Chinese website: http://cesiumcn.org/ | Fast access in China: http://cesium.coinidea.com/