Cesium Syntax Entity

CesiumJS Entity API

Overview

The Entity API is the high-level, retained-mode way to put objects on the globe. An Entity is a container: it carries a position and one or more graphics objects (point, billboard, label, polyline, polygon, model, and others). CesiumJS visualizes entities automatically every frame.

Every value on an entity is a Property, which makes entities time-dynamic by construction. A raw value (a Color, a number, a Cartesian3) assigned to a graphics field is wrapped in a ConstantProperty internally.

Verified signatures and defaults are in references/methods.md. Runnable code is in references/examples.md. Failure modes are in references/anti-patterns.md.

Core Rules

• An entity renders nothing unless it has at least one graphics field set. ALWAYS set point, billboard, polygon, or another graphics object.
• Point, billboard, label, and model graphics ALWAYS need position. Polygon uses hierarchy; polyline uses positions. NEVER expect a point to show without a position.
• ALWAYS add entities through viewer.entities.add(...). NEVER push onto viewer.entities.values; that array must not be modified directly.
• A CallbackProperty whose value changes over time ALWAYS takes isConstant = false. With true, CesiumJS caches the first result and the value never updates.
• ALWAYS use the Entity API for interactive or time-dynamic data below roughly 10000 objects. NEVER use entities for tens of thousands of static objects; the visualizer loops every entity each frame. Use batched primitives or 3D Tiles instead.
• ALWAYS call entity.billboard.image with a loaded image URL or canvas. A missing or 404 image renders no billboard.
• ALWAYS set heightReference to CLAMP_TO_GROUND for ground-following graphics. Without it the entity sits at the height in its position (0 by default), which floats below or above terrain.

Quick Reference

viewer.entities.add accepts an Entity or an Entity.ConstructorOptions object and returns the Entity.

Anatomy Of An Entity

const site = viewer.entities.add({
  id: "site-42",                                   // omit for an auto GUID
  name: "Pumping Station",                          // shown in the InfoBox title
  position: Cesium.Cartesian3.fromDegrees(4.9, 52.37, 0.0),
  point: { pixelSize: 12, color: Cesium.Color.CYAN },
  label: { text: "Pumping Station", pixelOffset: new Cesium.Cartesian2(0, -24) },
  description: "<p>HTML shown in the InfoBox body.</p>",
});

An entity may carry several graphics objects at once (a point plus a label is the standard marker pattern). id is auto-generated if omitted. name and description feed the InfoBox.

Which Graphics Object

digraph graphics_choice {
    "What am I drawing?" [shape=diamond];
    "A single located marker?" [shape=diamond];
    "A filled area?" [shape=box];
    "A line between points?" [shape=box];
    "point, billboard, or label" [shape=box];
    "polygon (hierarchy)" [shape=box];
    "polyline (positions)" [shape=box];

    "What am I drawing?" -> "A single located marker?";
    "A single located marker?" -> "point, billboard, or label" [label="yes"];
    "A single located marker?" -> "A filled area?" [label="no"];
    "A filled area?" -> "polygon (hierarchy)";
    "A filled area?" -> "A line between points?" [label="otherwise"];
    "A line between points?" -> "polyline (positions)";
}

• point : a simple GPU dot, fastest single marker.
• billboard : an image marker. Requires a loaded image.
• label : screen-space text.
• polyline : a line through positions. Set clampToGround: true to drape.
• polygon : a filled area from hierarchy. Set perPositionHeight or an extrudedHeight for 3D shapes.
• model : a glTF model. See cesium-syntax-gltf-model.

Entity Versus Primitive

This is the most common architectural decision in CesiumJS code.

The EntityCollection visualizer loops every entity every frame. Past ~10000 entities this dominates the frame budget; past ~100000 entities the tab runs out of memory. For massive static data use batched GeometryInstance primitives (cesium-syntax-primitive) or stream 3D Tiles (cesium-syntax-3d-tiles).

The Property System

Every graphics field is a Property. Three concrete types cover most needs.

ConstantProperty (and auto-wrapping)

A raw value assigned to a graphics field is wrapped in a ConstantProperty automatically. These two are equivalent:

point: { color: Cesium.Color.RED }
point: { color: new Cesium.ConstantProperty(Cesium.Color.RED) }

Write the raw form. Use ConstantProperty explicitly only when calling setValue later.

SampledProperty (time-interpolated)

Holds time-indexed samples and interpolates between them. Use SampledPositionProperty for moving positions (see cesium-syntax-time).

const temperature = new Cesium.SampledProperty(Number);
temperature.addSample(Cesium.JulianDate.fromIso8601("2026-05-20T08:00:00Z"), 12);
temperature.addSample(Cesium.JulianDate.fromIso8601("2026-05-20T20:00:00Z"), 24);

CallbackProperty (per-frame)

Evaluates a callback every frame. The second argument, isConstant, is the single most error-prone parameter in the Entity API.

// isConstant MUST be false: the value changes every frame.
polyline: {
  positions: new Cesium.CallbackProperty(() => livePositions, false),
}

With isConstant = true, CesiumJS caches the first evaluation and the entity freezes. ALWAYS pass false for any animated callback. Use CallbackPositionProperty for a callback-driven position.

Materials

A graphics material field accepts a MaterialProperty or a raw Color (auto-wrapped into a ColorMaterialProperty).

polygon: { hierarchy, material: Cesium.Color.ORANGE.withAlpha(0.5) }
polyline: {
  positions,
  width: 8,
  material: new Cesium.PolylineGlowMaterialProperty({
    color: Cesium.Color.CYAN,
    glowPower: 0.25,   // verified default
    taperPower: 1.0,   // verified default
  }),
}

Polyline-specific materials: PolylineGlowMaterialProperty, PolylineDashMaterialProperty, PolylineArrowMaterialProperty, PolylineOutlineMaterialProperty. See references/methods.md.

Hierarchy And Availability

• parent builds a tree. entity.isShowing reflects the entity's own show and every ancestor's show.
• availability is a TimeIntervalCollection. An entity outside its availability is hidden by the clock. Use it for time-bounded features.

viewer.entities.add({
  parent: groupEntity,
  availability: new Cesium.TimeIntervalCollection([
    Cesium.TimeInterval.fromIso8601({ iso8601: "2026-05-20/2026-05-21" }),
  ]),
  position,
  point: { pixelSize: 8 },
});

Bulk Add Performance

Wrap large add or remove batches in suspendEvents / resumeEvents so the collection fires one change event instead of one per entity.

viewer.entities.suspendEvents();
for (const feature of features) {
  viewer.entities.add({ position: feature.position, point: { pixelSize: 6 } });
}
viewer.entities.resumeEvents();

Common Mistakes

Full diagnosis of each is in references/anti-patterns.md.

Reference Files

• references/methods.md : verified signatures for Entity, EntityCollection, the graphics objects, and the Property and material classes.
• references/examples.md : complete runnable entity, polygon, polyline, time-dynamic, and bulk-add examples.
• references/anti-patterns.md : every invisible-entity, frozen-callback, and performance failure mode with root cause and fix.

Related Skills

• cesium-core-coordinates : building Cartesian3 positions and hierarchies.
• cesium-syntax-primitive : the batched low-level alternative at scale.
• cesium-syntax-time : SampledPositionProperty and the Clock.
• cesium-syntax-gltf-model : the model graphics object in depth.
• cesium-impl-picking-measurement : picking entities and the InfoBox.