cesiumjs-primitives

CesiumJS Primitives & Geometry

Applies to: CesiumJS v1.144+ (ES module imports, ?? instead of defaultValue)

Architecture

The Primitive API is the low-level rendering layer beneath the Entity API, trading convenience for performance.

Core formula: Primitive = GeometryInstance[] + Appearance

• GeometryInstance -- positions a Geometry in world space with per-instance attributes (color, show).
• Geometry -- vertex data describing a shape (polygon, box, ellipsoid, etc.).
• Appearance -- GLSL shaders + render state + optional Material that shade the geometry.

Primitives are immutable after first render -- geometry cannot change, but per-instance attributes update via primitive.getGeometryInstanceAttributes(id).

Primitive

import {
  Viewer, Primitive, GeometryInstance, EllipseGeometry,
  EllipsoidSurfaceAppearance, Material, Cartesian3, Math as CesiumMath,
} from "cesium";

const viewer = new Viewer("cesiumContainer");
const scene = viewer.scene;

const primitive = scene.primitives.add(new Primitive({
  geometryInstances: new GeometryInstance({
    geometry: new EllipseGeometry({
      center: Cartesian3.fromDegrees(-100.0, 40.0),
      semiMinorAxis: 250000.0,
      semiMajorAxis: 400000.0,
      rotation: CesiumMath.PI_OVER_FOUR,
      vertexFormat: EllipsoidSurfaceAppearance.VERTEX_FORMAT, // must match appearance
    }),
    id: "myEllipse", // returned by Scene.pick()
  }),
  appearance: new EllipsoidSurfaceAppearance({ material: Material.fromType("Stripe") }),
}));

Key Options

Option	Default	Purpose
geometryInstances	--	Single instance or array
appearance	--	Shading (Appearance subclass)
show	true	Toggle visibility
modelMatrix	Matrix4.IDENTITY	Transform all instances
asynchronous	true	Build geometry on web worker
releaseGeometryInstances	true	Free geometry after GPU upload
allowPicking	true	false saves GPU memory
shadows	ShadowMode.DISABLED	Cast/receive shadows