Comprehensive Guide to Using Entity and Primitive Methods for 3D Earth Visualization with Cesium

This tutorial, part of the "Cesium 3D Earth Visualization from Beginner to Advanced" series, explains two primary ways to create graphics in Cesium: Entity and Primitive . It begins with an overview of the 17 supported entity types, presenting a table that lists each entity name, its graphics class, description, and an illustrative image.

Entity Overview

An Entity is a high‑level API for adding basic shapes such as points, lines, polygons, boxes, and models to the scene. The article details required and optional properties (id, name, position, and the specific graphics object) and explains how missing position prevents rendering.

Box Entity Example

A complete code snippet shows how to add a box entity with properties like dimensions , material , outline , outlineColor , outlineWidth , and show . Each property is described, and the effect of changing values (e.g., toggling fill or outline ) is illustrated with screenshots.

var boxEntity = viewer.entities.add({
  id: '1234abcdxxxx',
  name: 'Name of the entity',
  position: Cesium.Cartesian3.fromDegrees(-107.0, 40.0, 300000.0),
  box: {
    dimensions: new Cesium.Cartesian3(400000.0, 300000.0, 500000.0),
    material: Cesium.Color.RED.withAlpha(0.5),
    outline: true,
    outlineColor: Cesium.Color.BLACK
  }
});
viewer.zoomTo(boxEntity);

Point Entity Example

The article then demonstrates creating a point entity with attributes such as color , outlineColor , pixelSize , distanceDisplayCondition , heightReference , scaleByDistance , translucencyByDistance , and show . Explanations cover how each attribute influences appearance and visibility.

var pointEntity = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(-107.0, 40.0, 0.0),
  point: {
    color: Cesium.Color.RED,
    outlineColor: Cesium.Color.PINK,
    outlineWidth: 5,
    pixelSize: 20,
    distanceDisplayCondition: new Cesium.DistanceDisplayCondition(10, 10000),
    heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
    scaleByDistance: new Cesium.NearFarScalar(100, 2, 10000, 15),
    translucencyByDistance: new Cesium.NearFarScalar(100, 0.4, 200, 0.8),
    show: true
  }
});

Primitive Overview

Unlike entities, Primitive offers lower‑level, higher‑performance graphics by separating geometry and appearance. The article lists supported geometries (e.g., BoxGeometry, CircleGeometry, PolygonGeometry) and appearances (MaterialAppearance, EllipsoidSurfaceAppearance, PerInstanceColorAppearance, etc.), discussing their advantages, flexibility, and when to use them.

Simple Primitive Example

A rectangle primitive is added using Cesium.RectanglePrimitive with a dot material, followed by an equivalent approach using a GeometryInstance and Primitive with an EllipsoidSurfaceAppearance .

viewer.scene.primitives.add(new Cesium.RectanglePrimitive({
  rectangle: Cesium.Rectangle.fromDegrees(-100.0, 20.0, -90.0, 30.0),
  material: Cesium.Material.fromType('Dot')
}));

Batching Primitives

The tutorial shows how to batch many GeometryInstance objects into a single Primitive to improve performance, creating thousands of colored rectangles covering the globe.

let instances = [];
for (let lon = -180.0; lon < 180.0; lon += 5.0) {
  for (let lat = -90.0; lat < 90.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)
      }),
      attributes: {
        color: Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.fromRandom({alpha: 0.5}))
      }
    }));
  }
}
viewer.scene.primitives.add(new Cesium.Primitive({
  geometryInstances: instances,
  appearance: new Cesium.PerInstanceColorAppearance()
}));

Picking and Updating Primitives

Code examples illustrate how to assign IDs to geometry instances, use scene.pick to detect clicks, and dynamically update instance attributes such as color or visibility.

let instance = new Cesium.GeometryInstance({
  geometry: new Cesium.RectangleGeometry({
    rectangle: Cesium.Rectangle.fromDegrees(-100.0, 30.0, -90.0, 40.0)
  }),
  id: 'rectangle-1',
  attributes: { color: Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.RED) }
});
viewer.scene.primitives.add(new Cesium.Primitive({
  geometryInstances: instance,
  appearance: new Cesium.PerInstanceColorAppearance()
}));
let handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction(function(movement) {
  let pick = viewer.scene.pick(movement.position);
  if (Cesium.defined(pick) && pick.id === 'rectangle-1') {
    alert('Rectangle selected');
  }
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

Finally, the article reminds readers that this is the fifth part of the series, encourages following the author for more case studies, and provides a GitHub repository link for the sample code.