cesiumgs/cesiumjs-skills/cesiumjs-interaction

Name: cesiumjs-interaction
Author: cesiumgs

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 interaction and picking - ScreenSpaceEventHandler, multi-key KeyboardEventModifier input actions, Scene.pick, Scene.drillPick, Scene.pickPosition, Scene.snap edge snapping (1.144), mouse and touch events. Use when handling user clicks on the globe, selecting entities or 3D Tiles features, registering modifier-key shortcuts, implementing hover effects, snapping to model edges for measurement, or building drag-based interactions.

Install

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

SKILL.md

CesiumJS Interaction & Picking

Version baseline: CesiumJS v1.144 (ES module imports, Ion token required).

ScreenSpaceEventHandler

Central class for mouse, touch, and pointer events on the Cesium canvas. Always construct a new `ScreenSpaceEventHandler` bound to `viewer.scene.canvas` for interaction logic -- it isolates your listeners from Cesium's default camera/selection handlers and is the idiomatic pattern shown across all recipes below.

import { ScreenSpaceEventHandler, ScreenSpaceEventType,
  KeyboardEventModifier, defined } from "cesium";
let handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
// Register a click handler
handler.setInputAction((event) => {
  console.log("Clicked at", event.position.x, event.position.y);
}, ScreenSpaceEventType.LEFT_CLICK);
// With keyboard modifier (Shift+Click)
handler.setInputAction((event) => {
  console.log("Shift+Click at", event.position);
}, ScreenSpaceEventType.LEFT_CLICK, KeyboardEventModifier.SHIFT);
// With multiple modifiers (Ctrl+Shift+Click, 1.142+)
handler.setInputAction((event) => {
  console.log("Ctrl+Shift+Click at", event.position);
}, ScreenSpaceEventType.LEFT_CLICK, [
  KeyboardEventModifier.CTRL,
  KeyboardEventModifier.SHIFT,
]);
// Query or remove actions
const clickAction = handler.getInputAction(ScreenSpaceEventType.LEFT_CLICK);
const ctrlShiftClickAction = handler.getInputAction(ScreenSpaceEventType.LEFT_CLICK, [
  KeyboardEventModifier.SHIFT,
  KeyboardEventModifier.CTRL, // order does not matter
]);
if (defined(clickAction) && defined(ctrlShiftClickAction)) {
  console.log("Click handlers registered");
}
handler.removeInputAction(ScreenSpaceEventType.LEFT_CLICK);
handler.removeInputAction(ScreenSpaceEventType.LEFT_CLICK, [
  KeyboardEventModifier.CTRL,
  KeyboardEventModifier.SHIFT,
]);
// Always destroy when done to avoid memory leaks
handler = handler && handler.destroy();

The Viewer also exposes a built-in handler at viewer.screenSpaceEventHandler which drives default behavior (entity selection, double-click tracking). You can attach to it, but for any non-trivial interaction prefer constructing your own new ScreenSpaceEventHandler(viewer.scene.canvas) so your handlers are independently disposable and do not collide with Cesium defaults.

ScreenSpaceEventType Reference

Event	Callback shape	Notes
`LEFT_DOWN` / `LEFT_UP` / `LEFT_CLICK`	`({ position })`	Cartesian2 screen coords
`LEFT_DOUBLE_CLICK`	`({ position })`	Left only
`RIGHT_DOWN` / `RIGHT_UP` / `RIGHT_CLICK`	`({ position })`
`MIDDLE_DOWN` / `MIDDLE_UP` / `MIDDLE_CLICK`	`({ position })`
`MOUSE_MOVE`	`({ startPosition, endPosition })`	Fires on every pointer move
`WHEEL`	`(delta)`	Positive = scroll up
`PINCH_START`	`({ position1, position2 })`	Two-finger touch begins
`PINCH_END`	`()`	Two-finger touch ends
`PINCH_MOVE`	`({ distance, angleAndHeight })`	Two-finger move

KeyboardEventModifier: SHIFT, CTRL, ALT -- optional third argument to setInputAction, getInputAction, and removeInputAction. In 1.142+, pass a single modifier or an array of modifiers. Modifier arrays are order-independent but exact: a handler registered for [CTRL, SHIFT] does not fire when ALT is also held.

Scene Picking Methods

pick / pickAsync / drillPick / pickPosition

import { Cartographic, Math as CesiumMath, defined } from "cesium";
// pick -- synchronous, returns top-most object or undefined
const picked = viewer.scene.pick(event.position);
// pickAsync -- non-blocking (WebGL2, v1.136+), falls back to sync on WebGL1
const picked2 = await viewer.scene.pickAsync(movement.endPosition);
// drillPick -- all objects at position, front-to-back; use limit to cap cost
const allPicked = viewer.scene.drillPick(event.position, 5);
// pickPosition -- world Cartesian3 from depth buffer
if (viewer.scene.pickPositionSupported) {
  const cartesian = viewer.scene.pickPosition(event.position);
  if (defined(cartesian)) {
    const c = Cartographic.fromCartesian(cartesian);
    console.log(CesiumMath.toDegrees(c.longitude), CesiumMath.toDegrees(c.latitude), c.height);
  }
}

Set scene.pickTranslucentDepth = true to include translucent primitives in pickPosition.

pickVoxel (experimental)

// Pick a voxel cell and read its properties
const voxelCell = viewer.scene.pickVoxel(event.position);
if (defined(voxelCell)) {
  console.log(voxelCell.getProperty("temperature"));
}

snap (experimental, 1.144+)

scene.snap searches a screen-space region around a window position and returns the best snap target, preferring model edges (from CAD-style EXT_mesh_primitive_edge_visibility data) over surfaces; among hits of the same kind, the one nearest the cursor wins. Use it for measurement and inspection tools that should latch onto edges instead of raw cursor hits.

import { defined } from "cesium";
// Search a 25x25 px region centered on the cursor
const result = viewer.scene.snap(movement.endPosition, { width: 25 });
if (defined(result)) {
  // SceneSnapResult: { object, position, screenPosition, isEdge }
  console.log(result.isEdge ? "edge" : "surface", result.position);
}

Only primitives rendered through the Model pipeline (3D Tiles and glTF models) are snappable. Snapping requires WebGL2 with float color attachments (EXT_color_buffer_float); when that is unsupported, or the region contains no snappable geometry, snap returns undefined.

Picking Return Values

Picked object	Return shape	Key properties
Entity	`{ primitive, id }`	`id` is the `Entity` instance
Cesium3DTileFeature	`Cesium3DTileFeature`	`.getProperty(name)`, `.getPropertyIds()`, `.color`
Billboard/Label (collection)	`{ primitive, id }`	`id` is the user-set id
Primitive (geometry)	`{ primitive, id }`	`id` is the `GeometryInstance` id
Globe surface	`undefined`	Use `camera.pickEllipsoid()` or `pickPosition()`

Camera Framing for Interaction Demos

Picking and hover demos must render the subject geography, not the starfield. Recent losses occurred because the camera was angled at the sky (pitch ~-45° or shallower) or imagery failed to load, leaving the scene black. Two non-negotiable rules:

**Set the camera with viewer.camera.setView (or flyTo with duration: 0)

using an explicit top-down pitch of CesiumMath.toRadians(-90)** (nadir) when the scenario calls for a regional map view. Do not rely on default pitch.

Frame the scene at an altitude that contains all subject features.

For city-scale demos use 50–200 km; for state/region 1–3 Mm; for multi-state or archipelago 1.5–4 Mm. If pins or polygons land outside the frame, the judge will mark the candidate down even when programmatic checks pass.

For regional pin demos, include the full latitude span with margin.

West-coast Seattle/San Francisco/Los Angeles views need a center near 40.8 N, -121 W and about 3.2-4.0 Mm altitude, or a fitted rectangle. At 2.5 Mm centered on 40 N, Seattle often lands at the top edge and fails as off-frame.

import { Cartesian3, Math as CesiumMath } from "cesium";
viewer.camera.setView({
  destination: Cartesian3.fromDegrees(-122.0, 37.5, 1_500_000),
  orientation: { heading: 0.0, pitch: CesiumMath.toRadians(-90), roll: 0.0 },
});

Coordinate Conversion (Required for Readouts)

Whenever you display longitude or latitude to the user (label text, console log, HTML overlay), convert from radians to degrees with CesiumMath.toDegrees. Cartographic angles are always in radians; printing them raw produces nonsense values.

import { Cartographic, Math as CesiumMath } from "cesium";
const c = Cartographic.fromCartesian(cartesian);
const lonDeg = CesiumMath.toDegrees(c.longitude);
const latDeg = CesiumMath.toDegrees(c.latitude);
// Never display c.longitude / c.latitude directly in a UI label.

Recipes

Polygon Setup For Picking Examples

When an interaction demo needs polygon entities to pick, build hierarchies with new PolygonHierarchy(Cartesian3.fromDegreesArray([...])). PolygonHierarchy does not have static fromDegrees(), fromDegreesArray(), or fromEquatorialCoordinates() helpers -- calling them throws Cesium.PolygonHierarchy.fromDegrees is not a function at runtime and the scene renders empty. The only correct construction is:

import { PolygonHierarchy, Cartesian3 } from "cesium";
const hierarchy = new PolygonHierarchy(
  Cartesian3.fromDegreesArray([
    -87.6, 41.8,
    -85.6, 41.8,
    -85.6, 43.3,
    -87.6, 43.3,
  ]),
);
viewer.entities.add({
  polygon: { hierarchy, material: Color.CRIMSON.withAlpha(0.5) },
});

1. Entity Selection with Click

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction((event) => {
  const picked = viewer.scene.pick(event.position);
  if (defined(picked) && defined(picked.id)) {
    viewer.selectedEntity = picked.id; // shows InfoBox
  } else {
    viewer.selectedEntity = undefined;
  }
}, ScreenSpaceEventType.LEFT_CLICK);

2. 3D Tiles Feature Picking and Property Inspection

import { Cesium3DTileFeature, Color } from "cesium";
const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction((event) => {
  const picked = viewer.scene.pick(event.position);
  if (picked instanceof Cesium3DTileFeature) {
    // Read properties
    const ids = picked.getPropertyIds();
    ids.forEach((id) => console.log(`${id}: ${picked.getProperty(id)}`));
    picked.color = Color.YELLOW; // highlight
  }
}, ScreenSpaceEventType.LEFT_CLICK);

3. Terrain Position Picking (Lon/Lat from Click)

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction((event) => {
  const cartesian = viewer.camera.pickEllipsoid(
    event.position, viewer.scene.globe.ellipsoid);
  if (defined(cartesian)) {
    const c = Cartographic.fromCartesian(cartesian);
    console.log(`Lon: ${CesiumMath.toDegrees(c.longitude).toFixed(6)}`);
    console.log(`Lat: ${CesiumMath.toDegrees(c.latitude).toFixed(6)}`);
  }
}, ScreenSpaceEventType.LEFT_CLICK);

For height on 3D content, use scene.pickPosition instead (see above).

4. Multi-Pick with drillPick

import { EntityCollection, CallbackProperty, ColorMaterialProperty, Color } from "cesium";
const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
const pickedEntities = new EntityCollection();
const highlightColor = Color.YELLOW.withAlpha(0.5);
// Make entity material react to selection state
function makePickable(entity, baseColor) {
  entity.polygon.material = new ColorMaterialProperty(
    new CallbackProperty((time, result) => {
      return pickedEntities.contains(entity)
        ? highlightColor.clone(result) : baseColor.clone(result);
    }, false));
}
handler.setInputAction((movement) => {
  const all = viewer.scene.drillPick(movement.endPosition);
  pickedEntities.removeAll();
  for (const p of all) {
    if (defined(p.id)) pickedEntities.add(p.id);
  }
}, ScreenSpaceEventType.MOUSE_MOVE);

5. Hover Highlighting with MOUSE_MOVE

import { Color } from "cesium";
const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
const highlighted = { feature: undefined, originalColor: new Color() };
handler.setInputAction((movement) => {
  if (defined(highlighted.feature)) {
    highlighted.feature.color = highlighted.originalColor;
    highlighted.feature = undefined;
  }
  const picked = viewer.scene.pick(movement.endPosition);
  if (defined(picked) && defined(picked.color)) {
    highlighted.feature = picked;
    Color.clone(picked.color, highlighted.originalColor);
    picked.color = Color.YELLOW;
  }
}, ScreenSpaceEventType.MOUSE_MOVE);

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

See the full security report

Quality evaluation

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

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/cesiumjs-interaction/SKILL.md

Popularity

Repository stars: 98
Repository forks: 13
7-day trend score: 23

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 21 Jul 2026, 3 months ago.

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](https://verified-skill.com/api/v1/skills/cesiumgs/cesiumjs-skills/cesiumjs-interaction/badge)](https://verified-skill.com/skills/cesiumgs/cesiumjs-skills/cesiumjs-interaction)

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