cesiumgs/cesiumjs-skills/cesiumjs-primitives

Claude Code and agent skill by cesiumgs/cesiumjs-skills

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

CesiumJS primitives and geometry - Primitive, GeometryInstance, Appearance, BufferPrimitive collections, GeoJsonPrimitive, Billboard/Label/PointPrimitive collections, built-in geometry shapes, ground primitives, classification. Use when rendering performance-critical static or vector geometry, loading GeoJSON without entities, creating custom shapes, batching draw calls, or using low-level collections.

Install

npx vskill@latest install cesiumgs/cesiumjs-skills/cesiumjs-primitives

SKILL.md

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

js
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
OptionDefaultPurpose
geometryInstances--Single instance or array
appearance--Shading (Appearance subclass)
showtrueToggle visibility
modelMatrixMatrix4.IDENTITYTransform all instances
asynchronoustrueBuild geometry on web worker
releaseGeometryInstancestrueFree geometry after GPU upload
allowPickingtruefalse saves GPU memory
shadowsShadowMode.DISABLEDCast/receive shadows

Batching Multiple Instances

All instances in one Primitive share a single draw call.

js
import {
Primitive, GeometryInstance, RectangleGeometry, EllipseGeometry,
PerInstanceColorAppearance, ColorGeometryInstanceAttribute,
Cartesian3, Rectangle, Color,
} from "cesium";
scene.primitives.add(new Primitive({
geometryInstances: [
new GeometryInstance({
geometry: new RectangleGeometry({
rectangle: Rectangle.fromDegrees(-140, 30, -100, 40),
vertexFormat: PerInstanceColorAppearance.VERTEX_FORMAT,
}),
id: "rect",
attributes: { color: ColorGeometryInstanceAttribute.fromColor(Color.RED.withAlpha(0.5)) },
}),
new GeometryInstance({
geometry: new EllipseGeometry({
center: Cartesian3.fromDegrees(-80, 35),
semiMinorAxis: 200000.0,
semiMajorAxis: 300000.0,
vertexFormat: PerInstanceColorAppearance.VERTEX_FORMAT,
}),
id: "ellipse",
attributes: { color: ColorGeometryInstanceAttribute.fromColor(Color.BLUE.withAlpha(0.5)) },
}),
],
appearance: new PerInstanceColorAppearance(),
}));
Batching Volume Geometry (CylinderGeometry Grid)

Volume geometry (Cylinder, Box, Ellipsoid) must be positioned via modelMatrix on each GeometryInstance. Use Matrix4.multiply to combine a world-space anchor with a local offset, then batch all instances into one Primitive.

js
import {
Primitive, GeometryInstance, CylinderGeometry,
PerInstanceColorAppearance, ColorGeometryInstanceAttribute,
Cartesian3, Matrix4, Transforms, Color, Math as CesiumMath,
} from "cesium";
const center = Cartesian3.fromDegrees(-73.9857, 40.7580);
const anchorFrame = Transforms.eastNorthUpToFixedFrame(center, undefined, new Matrix4());
const instances = [];
const GRID = 10;
const SPACING = 50; // metres
for (let row = 0; row < GRID; row++) {
for (let col = 0; col < GRID; col++) {
const xOffset = (col - GRID / 2) * SPACING;
const yOffset = (row - GRID / 2) * SPACING;
// Combine anchor ENU frame with a local XYZ offset
const modelMatrix = Matrix4.multiply(
anchorFrame,
Matrix4.fromTranslation(new Cartesian3(xOffset, yOffset, 100), new Matrix4()),
new Matrix4(),
);
instances.push(new GeometryInstance({
geometry: new CylinderGeometry({
length: 200,
topRadius: 8,
bottomRadius: 8,
vertexFormat: PerInstanceColorAppearance.VERTEX_FORMAT,
}),
modelMatrix,
attributes: { color: ColorGeometryInstanceAttribute.fromColor(Color.fromRandom({ alpha: 1.0 })) },
}));
}
}
scene.primitives.add(new Primitive({
geometryInstances: instances,
appearance: new PerInstanceColorAppearance({ flat: true }),
}));
// Frame the grid so the full batch is visible -- a shallow pitch hides cylinders
// behind the foreground; a near-nadir pitch flattens them. Aim for ~-45° (-PI/4)
// at a range that covers the grid footprint (GRID * SPACING) with margin.
const range = GRID * SPACING * 3; // ~1500 m for a 10x10x50m grid
viewer.camera.lookAt(
center,
new Cartesian3(0, -range * 0.7, range * 0.7), // offset south + up for -45° pitch
);

Key patterns:

  • Matrix4.multiply(anchorFrame, Matrix4.fromTranslation(offset, result), result) -- compose the ENU frame at a geographic anchor with a local East/North/Up translation.
  • Color.fromRandom({ alpha: 1.0 }) produces fully-opaque random colours suitable for rainbow-coloured batches.
  • Framing matters: for a grid of vertical volumes, prefer a ~-45° (-CesiumMath.PI_OVER_FOUR, ~-0.785 rad) pitch at a range of roughly 3 * gridFootprint. Pitches shallower than ~-0.6 rad can push the grid off-screen or hide it behind buildings; nadir views flatten cylinders into dots and lose the batched "field" appearance. A -0.61 rad pitch is still shallow enough to leave the grid completely out of frame.
  • Verify visibility: after primitive.ready, prefer viewer.camera.flyToBoundingSphere(primitive._boundingSpheres[0], { duration: 0 }) (or viewer.flyTo(primitive)) over hand-tuned offsets if the scenario only requires "the batch is visible".

Updating Per-Instance Attributes

js
import { ColorGeometryInstanceAttribute, ShowGeometryInstanceAttribute } from "cesium";
// Wait for async geometry compilation
const removeListener = scene.postRender.addEventListener(() => {
if (!primitive.ready) return;
const attrs = primitive.getGeometryInstanceAttributes("rect");
attrs.color = ColorGeometryInstanceAttribute.toValue(Color.YELLOW);
attrs.show = ShowGeometryInstanceAttribute.toValue(true);
removeListener();
});

PrimitiveCollection

Nestable container -- scene.primitives is itself a PrimitiveCollection.

js
import { PrimitiveCollection, BillboardCollection, LabelCollection } from "cesium";
const group = new PrimitiveCollection();
group.add(new BillboardCollection());
group.add(new LabelCollection());
scene.primitives.add(group);
group.show = false; // toggle all children

Choosing a Vector Data Path

NeedUse
Entity lifecycle, clustering, per-entity styling, time-dynamic valuesGeoJsonDataSource in cesiumjs-entities
One large GeoJSON object with low overhead and primitive-level performanceGeoJsonPrimitive in this skill
Tiled vector data, 3D Tiles LOD, metadata styling, feature pickingMVTDataProvider in cesiumjs-3d-tiles
Fully manual high-throughput point/polyline/polygon buffersBufferPointCollection, BufferPolylineCollection, BufferPolygonCollection

Buffer Primitive Collections (Experimental, 1.140+)

Use BufferPointCollection, BufferPolylineCollection, and BufferPolygonCollection for very large vector datasets where Entity/DataSource overhead is too high. These APIs were introduced in 1.140 (#13212) and refined through 1.142; they are experimental and use flyweight primitive objects: reuse one BufferPoint, BufferPolyline, or BufferPolygon when adding or iterating thousands of items.

js
import {
BlendOption,
BoundingSphere,
BufferPoint,
BufferPointCollection,
BufferPointMaterial,
Cartesian3,
Color,
} from "cesium";
const positions = [
Cartesian3.fromDegrees(-75.16, 39.95),
Cartesian3.fromDegrees(-73.98, 40.75),
];
const points = scene.primitives.add(new BufferPointCollection({
primitiveCountMax: positions.length,
allowPicking: true,
blendOption: BlendOption.TRANSLUCENT,
boundingVolume: BoundingSphere.fromPoints(positions), // world space in 1.142+
}));
const point = new BufferPoint();
const material = new BufferPointMaterial({
color: Color.CYAN.withAlpha(0.65),
outlineColor: Color.WHITE.withAlpha(0.9),
outlineWidth: 2,
size: 10,
});
positions.forEach((position, featureId) => {
points.add({
position,
featureId,
material,
}, point);
});
const picked = scene.pick(windowPosition);
if (picked?.collection === points) {
console.log(picked.index, picked.primitive.featureId);
}
Breaking change (1.141, #13448): BufferPrimitiveCollection.modelMatrix,
boundingVolume, and boundingVolumeWC are now readonly -- you may mutate
the object in place, but reassigning the property (collection.modelMatrix = ...)
throws. Update the existing matrix/volume instead of swapping in a new one.

1.142 notes:

  • boundingVolume is now world-space, not local/model-space. If you provide it manually, include the collection modelMatrix transform yourself.
  • Providing boundingVolume skips automatic recomputation; this helps large animated collections but makes you responsible for keeping the volume valid.
  • blendOption is supported on all three buffer collections and enables alpha from BufferPrimitiveMaterial#color; BufferPointCollection also honors outlineColor.alpha.
  • Use BlendOption.OPAQUE only when every material is fully opaque; use TRANSLUCENT or mixed blending when alpha varies.

In 1.143, BufferPointCollection no longer leaks outlineColor into the fill when outlineWidth is 0. Set the width to 0 to disable outlines; remove transparent-outline workarounds that would otherwise complicate batching.

GeoJsonPrimitive (Experimental, 1.142+)

GeoJsonPrimitive loads GeoJSON directly into buffer primitive collections, bypassing GeoJsonDataSource and the Entity layer. Prefer it for large static or bulk-updated vector datasets. Keep using GeoJsonDataSource when you need Entity conveniences, time-dynamic properties, clustering, or DataSource lifecycle integration.

js
import { GeoJsonPrimitive } from "cesium";
const counties = await GeoJsonPrimitive.fromUrl("/data/counties.geojson", {
allowPicking: true,
});
scene.primitives.add(counties);
console.log(counties.featureCount);
console.log(counties.points); // BufferPointCollection | undefined
console.log(counties.polylines); // BufferPolylineCollection | undefined
console.log(counties.polygons); // BufferPolygonCollection | undefined
// Picking returns the GeoJsonPrimitive pick object, including source properties.
const picked = scene.pick(windowPosition);
if (picked?.parentPrimitive === counties) {
const featureId = picked.primitive.featureId;
console.log(counties.getId(featureId));
console.log(counties.getProperties(featureId));
}

GeoJsonPrimitive.fromGeoJson(parsedObject) is available when the GeoJSON is already in memory. Source feature IDs are exposed through ids/getId(), and source properties through properties/getProperties().

Built-in Geometry Types (31)

All geometries take shape parameters and a vertexFormat matching the Appearance. Most have a paired *OutlineGeometry. Outlines require a separate Primitive.

Filled + Outline Pattern

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
44
Repository forks
7
7-day trend score
19

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/cesiumgs/cesiumjs-skills/cesiumjs-primitives/badge)](https://verified-skill.com/skills/cesiumgs/cesiumjs-skills/cesiumjs-primitives)

Something wrong with this skill or its page? Tell us.