Entities and primitives

Quick answer

This tutorial contrasts the Entity API with the Primitive API and explains when each is appropriate. It walks through viewer.entities.add configuration objects with point, billboard, label, polyline, polygon, wall and model graphics, plus custom properties for business data. It demonstrates SampledPositionProperty, CallbackProperty with isConstant false, suspendEvents for bulk insertion and scene.pick based hover highlighting. Readers can choose the right abstraction and build responsive, memory-safe entity layers.

Last verified 2026-11-03 · CesiumJS 1.121 · Cite this page

Key points

Give each entity an explicit id so viewer.entities.getById can retrieve it later.
Pass isConstant false to CallbackProperty, otherwise the animated value is cached.
Wrap bulk additions in suspendEvents and resumeEvents to avoid one redraw per entity.

Example

viewer.entities.add({
  id: 'station-01',
  name: '气象站 01',
  position: Cesium.Cartesian3.fromDegrees(116.391263, 39.907359, 60),
  point: {
    pixelSize: 10,
    color: Cesium.Color.fromCssColorString('#4d9bff'),
    outlineColor: Cesium.Color.WHITE,
    outlineWidth: 2
  },
  label: {
    text: '气象站 01',
    font: '500 12px sans-serif',
    fillColor: Cesium.Color.WHITE,
    pixelOffset: new Cesium.Cartesian2(0, -20),
    disableDepthTestDistance: Number.POSITIVE_INFINITY
  },
  properties: {                 // 业务字段，拾取后可以读
    temperature: 21.4,
    updatedAt: '2026-10-27T08:00:00Z'
  }
});

var position = new Cesium.SampledPositionProperty();
position.addSample(Cesium.JulianDate.fromIso8601('2026-10-27T00:00:00Z'),
  Cesium.Cartesian3.fromDegrees(116.39, 39.90, 100));
position.addSample(Cesium.JulianDate.fromIso8601('2026-10-27T00:05:00Z'),
  Cesium.Cartesian3.fromDegrees(116.45, 39.95, 100));
var pulse = new Cesium.CallbackProperty(function (time, result) {
  var phase = Date.now() % 2000 / 2000;
  return Cesium.Color.fromCssColorString('#4d9bff')
    .withAlpha(0.35 + 0.65 * Math.abs(Math.sin(phase * Math.PI)));
}, false);

Notes

entity.show = false keeps geometry in memory; call viewer.entities.remove for rolling data.
WebGL usually caps line width at one pixel, so thick polylines need a material or wall geometry.

Runnable examples Chinese original All Tutorials

English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.

Cite this page

Atlaslog (2026). Entities and primitives. https://www.jingweizhi.com/en/cesium/tutorials/entity.html (accessed 2026-11-03).