cesiumjs-interaction

CesiumJS の操作とピッキング

バージョンの基準：CesiumJS v1.144（ES モジュールのインポート、Ion トークンが必要）。

ScreenSpaceEventHandler

Cesium キャンバス上のマウス、タッチ、ポインターイベントを扱う中心的なクラスです。 操作ロジックでは、必ず viewer.scene.canvas にバインドした新しい ScreenSpaceEventHandler を作成してください。これにより、リスナーを Cesium のデフォルトのカメラ／選択ハンドラーから分離できます。以下のすべてのレシピで示している標準的なパターンです。

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();

Viewer は、デフォルトの動作（エンティティの選択、ダブルクリックによるトラッキング）を処理する組み込みハンドラー viewer.screenSpaceEventHandler も公開しています。このハンドラーにイベントを登録することもできますが、単純でない操作では、独自に new ScreenSpaceEventHandler(viewer.scene.canvas) を作成することをおすすめします。ハンドラーを個別に破棄でき、Cesium のデフォルト動作と競合しません。

ScreenSpaceEventType リファレンス

イベント	コールバックの形式	備考
LEFT_DOWN / LEFT_UP / LEFT_CLICK	({ position })	Cartesian2 の画面座標
LEFT_DOUBLE_CLICK	({ position })	左ボタンのみ
RIGHT_DOWN / RIGHT_UP / RIGHT_CLICK	({ position })
MIDDLE_DOWN / MIDDLE_UP / MIDDLE_CLICK	({ position })
MOUSE_MOVE	({ startPosition, endPosition })	ポインターが移動するたびに発生
WHEEL	(delta)	正の値は上方向へのスクロール
PINCH_START	({ position1, position2 })	2 本指のタッチ開始
PINCH_END	()	2 本指のタッチ終了
PINCH_MOVE	({ distance, angleAndHeight })	2 本指での移動

KeyboardEventModifier：SHIFT、CTRL、ALT。setInputAction、getInputAction、removeInputAction の第 3 引数として任意で指定します。1.142 以降では、修飾キーを 1 つまたは配列で渡せます。修飾キーの配列の順序は問いませんが、完全一致が必要です。[CTRL, SHIFT] に登録したハンドラーは、ALT も押されている場合には発生しません。

シーンのピッキングメソッド

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);
  }
}

pickPosition に半透明のプリミティブを含めるには、scene.pickTranslucentDepth = true を設定します。

pickVoxel（試験的機能）

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

snap（試験的機能、1.144 以降）

scene.snap は、ウィンドウ座標の周囲にある画面空間の領域を検索し、最適なスナップ対象を返します。CAD 形式の EXT_mesh_primitive_edge_visibility データに基づくモデルのエッジをサーフェスより優先し、同じ種類の候補が複数ある場合は、カーソルに最も近いものを選択します。カーソル位置の対象ではなくエッジにスナップさせたい、計測や検査のツールで使用してください。

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);
}

スナップ可能なのは、Model パイプラインを通じてレンダリングされるプリミティブ（3D Tiles および glTF モデル）のみです。スナップには、浮動小数点カラーアタッチメントに対応した WebGL2（EXT_color_buffer_float）が必要です。この機能がサポートされていない場合、または領域内にスナップ可能なジオメトリがない場合、snap は undefined を返します。

ピッキングの戻り値

ピッキング対象	戻り値の形式	主なプロパティ
Entity	{ primitive, id }	id は Entity インスタンスです
Cesium3DTileFeature	Cesium3DTileFeature	.getProperty(name)、.getPropertyIds()、.color
Billboard/Label（コレクション）	{ primitive, id }	id はユーザーが設定した ID です
Primitive（ジオメトリ）	{ primitive, id }	id は GeometryInstance の ID です
Globe サーフェス	undefined	camera.pickEllipsoid() または pickPosition() を使用します

操作デモ用のカメラフレーミング

ピッキングとホバーのデモでは、星空ではなく対象の地理的な特徴を描画する必要があります。最近の不具合は、カメラが空を向いていた（ピッチが約 -45°またはそれより浅かった）、あるいは画像の読み込みに失敗し、シーンが真っ黒になったことが原因で発生しています。譲れないルールは次の 3 つです。

1. シナリオで地域地図を表示する場合は、明示的にトップダウンのピッチ CesiumMath.toRadians(-90)（天底）を指定して、viewer.camera.setView（または duration: 0 を指定した flyTo）でカメラを設定してください。デフォルトのピッチに頼らないでください。
2. すべての対象の特徴が収まる高度でシーンをフレーミングしてください。都市規模のデモでは 50～200 km、州・地域では 1～3 Mm、複数の州または諸島では 1.5～4 Mm を使用してください。ピンやポリゴンがフレーム外にあると、プログラムによるチェックに合格していても、評価者は候補を低く評価します。
3. 地域規模のピンのデモでは、余白を含めて緯度の範囲全体を表示してください。西海岸のシアトル／サンフランシスコ／ロサンゼルスを表示する場合は、中心を緯度 40.8、経度 -121 付近にして高度を約 3.2～4.0 Mm にするか、矩形に合わせてください。緯度 40 を中心とする高度 2.5 Mm では、シアトルが上端に位置し、フレーム外と判定されることがよくあります。

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 },
});

座標変換（読み取り表示で必須）

ユーザーに経度または緯度を表示する場合（ラベルテキスト、コンソールログ、HTML オーバーレイ）、ラジアンから度に CesiumMath.toDegrees で変換してください。カートグラフィック角度は常にラジアンです。そのまま出力すると意味のない値になります。

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.

レシピ

ピッキング例のポリゴン設定

操作デモでピッキング用のポリゴンエンティティが必要な場合は、new PolygonHierarchy(Cartesian3.fromDegreesArray([...])) で階層を構築してください。PolygonHierarchy には静的な fromDegrees()、fromDegreesArray()、fromEquatorialCoordinates() ヘルパーはありません。これらを呼び出すと、実行時に Cesium.PolygonHierarchy.fromDegrees is not a function がスローされ、シーンが何も描画されません。正しい構築方法は次のとおりです。

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. クリックによるエンティティ選択

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 タイルのフィーチャーピッキングとプロパティの確認

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. 地形上の位置のピッキング（クリックから経度・緯度を取得）

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);

3D コンテンツ上の高さには、代わりに scene.pickPosition を使用してください（上記を参照）。

4. 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. 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);

エンティティの場合、ピッキングされたオブジェクトは picked.id です。picked.color ではなく、グラフィックスのマテリアルを置き換えてください（たとえば、picked.id.polygon.material を保存して Color.YELLOW に設定し、先に前のエンティティのマテリアルを復元します）。プロンプトで指定されたグラフィックの種類を構築してください。「地域上のポリゴン」は rectangle グラフィックではなく、PolygonHierarchy の位置を持つ polygon グラフィックを意味します。対象地域が長方形の場合も同様です。

6. ドラッグによる描画と計測

import { Cartographic, EllipsoidGeodesic, Ellipsoid, Color } from "cesium";

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
const positions = [];

handler.setInputAction((event) => {
  const cartesian = viewer.camera.pickEllipsoid(
    event.position, viewer.scene.globe.ellipsoid);
  if (!defined(cartesian)) return;
  positions.push(cartesian);

  if (positions.length === 2) {
    viewer.entities.add({
      polyline: { positions: positions.slice(), width: 3,
        material: Color.RED, clampToGround: true },
    });
    const start = Cartographic.fromCartesian(positions[0]);
    const end = Cartographic.fromCartesian(positions[1]);
    const geodesic = new EllipsoidGeodesic(start, end, Ellipsoid.WGS84);
    console.log(`Distance: ${(geodesic.surfaceDistance / 1000).toFixed(2)} km`);
    positions.length = 0;
  }
}, ScreenSpaceEventType.LEFT_CLICK);

7. マウス移動時の座標読み取り表示

ポインターを動かす前から表示されるよう、妥当な初期値でラベルを初期化してください。シナリオでは、ユーザーが操作していなくてもデフォルトの読み取り値を検証することがよくあります。必ず CesiumMath.toDegrees で変換してください。

import { HorizontalOrigin, VerticalOrigin, Cartesian2, Cartesian3,
  Cartographic, Math as CesiumMath } from "cesium";

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);

// Seed position/text so the label renders immediately on load.
const initialLon = 25.0;
const initialLat = 37.5;
const coordLabel = viewer.entities.add({
  position: Cartesian3.fromDegrees(initialLon, initialLat),
  label: {
    text: `Lon: ${initialLon.toFixed(2)} Lat: ${initialLat.toFixed(2)}`,
    show: true, showBackground: true, font: "14px monospace",
    horizontalOrigin: HorizontalOrigin.LEFT,
    verticalOrigin: VerticalOrigin.TOP,
    pixelOffset: new Cartesian2(15, 0),
  },
});

handler.setInputAction((movement) => {
  const cartesian = viewer.camera.pickEllipsoid(
    movement.endPosition, viewer.scene.globe.ellipsoid);
  if (defined(cartesian)) {
    const c = Cartographic.fromCartesian(cartesian);
    coordLabel.position = cartesian;
    coordLabel.label.show = true;
    coordLabel.label.text =
      `Lon: ${CesiumMath.toDegrees(c.longitude).toFixed(4)}\n` +
      `Lat: ${CesiumMath.toDegrees(c.latitude).toFixed(4)}`;
  }
}, ScreenSpaceEventType.MOUSE_MOVE);

8. ピッキングされたオブジェクトの種類に応じた条件分岐

import { Cesium3DTileFeature } from "cesium";

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);

handler.setInputAction((event) => {
  const picked = viewer.scene.pick(event.position);
  if (!defined(picked)) {
    console.log("No object picked");
  } else if (picked instanceof Cesium3DTileFeature) {
    console.log("3D Tile feature:", picked.getProperty("name"));
  } else if (defined(picked.id) && defined(picked.id.position)) {
    viewer.selectedEntity = picked.id; // Entity
  } else if (defined(picked.primitive)) {
    console.log("Primitive:", picked.primitive.constructor.name);
  }
}, ScreenSpaceEventType.LEFT_CLICK);

9. ノンブロッキングなホバーに使用する pickAsync（v1.136+）

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
const highlighted = { feature: undefined, originalColor: new Color() };

handler.setInputAction(async (movement) => {
  if (defined(highlighted.feature)) {
    highlighted.feature.color = highlighted.originalColor;
    highlighted.feature = undefined;
  }
  const picked = await viewer.scene.pickAsync(movement.endPosition);
  if (defined(picked) && defined(picked.color)) {
    highlighted.feature = picked;
    Color.clone(picked.color, highlighted.originalColor);
    picked.color = Color.YELLOW;
  }
}, ScreenSpaceEventType.MOUSE_MOVE);

10. シルエットを使ったホバーと選択（完全なパターン）

シルエットは、選択したプリミティブに適用されるポストプロセスのエッジ検出エフェクトです。スクリーンショットにはっきりと輪郭を表示するには、選択対象が奥行きを持つ不透明なプリミティブ（ボックス、モデル、3D Tiles フィーチャー）である必要があります。地面に固定された平面ポリゴンや点は、広域表示のカメラ高度では、判別できる輪郭が表示されることはほとんどありません。これまでの評価では、エッジが細すぎて見えない場合に失敗し、同じシナリオでボックスのシルエットエッジを太くすると改善しました。このような後退を避けるには、次の点に従ってください。

• point や地面ポリゴンよりも、dimensions がゼロでない box グラフィックス（広域表示のカメラ高度では、通常は各辺が 10～50 km）または 3D Tiles フィーチャーを優先してください。
• シルエットの length は少なくとも 0.25にし、都市規模以上の範囲を表示する場合は 0.5 に上げてください。0.1 未満の値は、評価に使用されるスクリーンショットの解像度では実質的に見えません。
• 衛星画像に対してコントラストの高い色（Color.ORANGE、Color.YELLOW、Color.LIME）を選んでください。海のタイルに溶け込む青は避けてください。

import { PostProcessStageLibrary, Color } from "cesium";

const scene = viewer.scene;
const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);

const silhouetteHover = PostProcessStageLibrary.createEdgeDetectionStage();
silhouetteHover.uniforms.color = Color.YELLOW;
silhouetteHover.uniforms.length = 0.25;
silhouetteHover.selected = [];

const silhouetteSelect = PostProcessStageLibrary.createEdgeDetectionStage();
silhouetteSelect.uniforms.color = Color.ORANGE;
silhouetteSelect.uniforms.length = 0.5;
silhouetteSelect.selected = [];

scene.postProcessStages.add(
  PostProcessStageLibrary.createSilhouetteStage([silhouetteHover, silhouetteSelect]));

let selectedFeature;

handler.setInputAction((movement) => {
  silhouetteHover.selected = [];
  const picked = scene.pick(movement.endPosition);
  if (defined(picked) && picked !== selectedFeature) {
    silhouetteHover.selected = [picked];
  }
}, ScreenSpaceEventType.MOUSE_MOVE);

handler.setInputAction((event) => {
  silhouetteSelect.selected = [];
  const picked = scene.pick(event.position);
  if (defined(picked)) {
    selectedFeature = picked;
    silhouetteSelect.selected = [picked];
    silhouetteHover.selected = [];
  } else {
    selectedFeature = undefined;
  }
}, ScreenSpaceEventType.LEFT_CLICK);

ユーザーの操作を想定せず、読み込み時にあらかじめエンティティを選択するシナリオでは、エンティティを追加した直後に silhouetteSelect.selected = [entity] を直接割り当てると、初期スクリーンショットに輪郭が表示されます。

11. カスタムロジックを使ったホイールズーム

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);

handler.setInputAction((delta) => {
  // delta > 0 = scroll up (zoom in), delta < 0 = scroll out
  const zoomAmount = delta > 0 ? 0.9 : 1.1;
  viewer.camera.zoomIn(viewer.camera.positionCartographic.height * (1 - zoomAmount));
}, ScreenSpaceEventType.WHEEL);

12. 右クリックのコンテキストメニュー

viewer.scene.canvas.addEventListener("contextmenu", (e) => e.preventDefault());

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);

handler.setInputAction((event) => {
  const picked = viewer.scene.pick(event.position);
  if (defined(picked) && defined(picked.id)) {
    showContextMenu(event.position, picked.id); // your app logic
  }
}, ScreenSpaceEventType.RIGHT_CLICK);

13. ドラッグ操作（エンティティの移動）

const handler = new ScreenSpaceEventHandler(viewer.scene.canvas);
let draggedEntity = null;
const sscc = viewer.scene.screenSpaceCameraController;

handler.setInputAction((event) => {
  const picked = viewer.scene.pick(event.position);
  if (defined(picked) && defined(picked.id)) {
    draggedEntity = picked.id;
    sscc.enableRotate = false;
    sscc.enableTranslate = false;
  }
}, ScreenSpaceEventType.LEFT_DOWN);

handler.setInputAction((movement) => {
  if (!defined(draggedEntity)) return;
  const cartesian = viewer.camera.pickEllipsoid(
    movement.endPosition, viewer.scene.globe.ellipsoid);
  if (defined(cartesian)) draggedEntity.position = cartesian;
}, ScreenSpaceEventType.MOUSE_MOVE);

handler.setInputAction(() => {
  draggedEntity = null;
  sscc.enableRotate = true;
  sscc.enableTranslate = true;
}, ScreenSpaceEventType.LEFT_UP);

パフォーマンスのヒント

1. MOUSE_MOVE では pick より pickAsync を優先する -- 同期的な pick は GPU パイプラインを停止させます。pickAsync は GPU に処理を譲り、次のフレームで結果を返します（WebGL2、v1.136 以降）。
2. drillPick には limit を指定する -- 指定しないと、重なっているオブジェクトごとにシーンが再レンダリングされます。
3. クリックによる pick だけが必要な場合は、MOUSE_MOVE で pick を使わない -- MOUSE_MOVE はポインターが動くたびに発生し、その都度 pick のレンダーパスを実行します。
4. 地形上で正確な pickPosition の結果を得るには、depthTestAgainstTerrain を有効にしてください。
5. 使用しないハンドラーは破棄する -- ハンドラーごとに DOM リスナーが登録されるため、クリーンアップしないとメモリリークが発生します。
6. 負荷の高いホバーロジックはスロットルする -- 単純なハイライト以外の処理には、50～100 ミリ秒のデバウンスを設定してください。
7. pickPosition を使う前に scene.pickPositionSupported を確認してください -- GPU がサポートしていない場合は、camera.pickEllipsoid にフォールバックします。
8. 必要な場合にのみ scene.pickTranslucentDepth = true を設定する -- 追加のレンダーパスが発生します。
9. 結果オブジェクトを再利用する -- pickPosition にスクラッチ用の Cartesian3 を渡すと、MOUSE_MOVE での GC 負荷を軽減できます。
10. pick と併せて scene.requestRenderMode = true を使うと、不要なレンダリングを避けられます。状態が変化したときのみ scene.requestRender() を呼び出してください。

関連項目

• cesiumjs-entities -- Entity API、グラフィックの種類、DataSources
• cesiumjs-3d-tiles -- Cesium3DTileset、Cesium3DTileFeature、スタイリング、メタデータ
• cesiumjs-camera -- Camera.pickEllipsoid、ScreenSpaceCameraController、flyTo