Cesium 1.135.0におけるマーカー位置ズレ問題と解決方法

問題の概要

Cesium.js 1.135.0を使用したReactアプリケーションにおいて、CLAMP_TO_GROUND設定を使用したビルボードマーカーの位置が、カメラの移動やズーム操作後に不正確になる現象が確認された。

環境

Cesium.js : 1.135.0（問題発生）→ 1.134.0（問題解消）
フレームワーク : Next.js 16.0.1 + React 19.2.0
地形データ : Cesium World Terrain (Cesium.Terrain.fromWorldTerrain())
マーカー設定 :
- clampToGround: true
- heightReference: Cesium.HeightReference.CLAMP_TO_GROUND

症状

特定のマーカーをクリックしてズーム（拡大）
カメラの視点を変更（回転・パン）
遠くにあるマーカーを確認すると、地形から浮いているか、不正確な位置に表示される

この問題は、カメラが近距離に移動した際に読み込まれる高解像度の地形データ（LOD: Level of Detail）と、遠方のマーカーが参照する低解像度の地形データとの不整合によって発生すると考えられる。

調査プロセス

試行1: カメラ制御の明示化

マーカークリック時にsampleTerrainMostDetailedを使用して地形高度を取得し、明示的にカメラを移動させる実装を試みたが、問題は解消されなかった。

試行2: heightReferenceの変更

heightReferenceをCLAMP_TO_GROUNDからNONEに変更し、disableDepthTestDistanceを使用する実装を試みたが、この場合はマーカーが地形に正しく配置されず、別の問題が発生した。

試行3: バージョン比較

動作確認用のHTMLファイル（Cesium 1.110.0使用）では同様の問題が発生しないことを確認。Cesiumのバージョンが問題の原因である可能性を特定。

解決策

Cesium.jsを1.135.0から1.134.0にダウングレードすることで問題が解消された。

技術的背景

CLAMP_TO_GROUNDの動作

CesiumのCLAMP_TO_GROUND設定は、エンティティを地形の表面に固定する機能を提供する。この機能は地形タイルのLOD（Level of Detail）に依存しており、カメラの位置によって異なる解像度の地形データが使用される。

理論上、Cesiumは地形タイルの更新に応じてエンティティの位置を再計算する必要があるが、1.135.0ではこの再計算メカニズムに問題がある可能性が考えられる。

コード比較

問題発生時（1.135.0）

解決後（1.134.0）

同一のコードで正常に動作。バージョンのみを変更。

結論

Cesium 1.135.0にはCLAMP_TO_GROUND機能に関連するリグレッションが存在すると考えられる。現時点では1.134.0の使用を推奨する。

将来的に1.135.x系列でこの問題が修正される可能性があるため、Cesiumのリリースノートおよび関連issueを定期的に確認することが望ましい。

追加情報

回避策（バージョンを変更できない場合）

1.135.0を使用する必要がある場合、以下の回避策が考えられる（ただし、完全な解決にはならない可能性がある）：

この方法では、地形高度を一度サンプリングして固定値として使用するため、LOD変化の影響を受けない。ただし、動的な地形変更には対応できない制限がある。

最終更新 : 2025-11-13
検証環境 : macOS, Darwin 25.0.0

問題の概要#

環境#

症状#

調査プロセス#

試行1: カメラ制御の明示化#

試行2: heightReferenceの変更#

試行3: バージョン比較#

解決策#

技術的背景#

CLAMP_TO_GROUNDの動作#

関連Issue#

コード比較#

問題発生時（1.135.0）#

解決後（1.134.0）#

結論#

追加情報#

回避策（バージョンを変更できない場合）#