ライブラリ
KASUGAI Canvas を構成する主要ライブラリについてまとめる章。基本は CesiumJS + Three.js。3D Tiles・DEM 上への XYZ 重ね合わせなど、地球規模の 3D 表示が必要な箇所は CesiumJS を主軸とする。
推奨構成：KASUGAI Canvas
| 役割 | ライブラリ | 備考 |
|---|---|---|
| 3D 地球・3D Tiles・DEM ドレープ・XYZ 重ね合わせ | CesiumJS | KASUGAI Canvas の 3D 描画の核。地球規模 LOD・地形・イメージリレイヤー・3D Tiles をネイティブに扱う |
| 点群・3DGS・高度な 3D 表現 | Three.js | GLB / 点群 / 3DGS エコシステム。Cesium 内のエンティティ / プリミティブと連携 |
| ベクターデコード / SQL 絞り込み | hyparquet / flatgeobuf / DuckDB-WASM | GeoParquet・FlatGeobuf・Parquet/CSV/GPKG 等をブラウザ内で
デコードし GeoJSON へ正規化（vectorDecoders
レジストリ経由） |
- KASUGAI Canvas = CesiumJS + Three.js。地理院標高 PNG / PLATEAU 3D Tiles 等をそのまま読み込む。
- 正式な描画方式：CesiumJS の Viewer / Scene 内でレイヤー・深度・カメラを一括管理する。3D Tiles・DEM・XYZ・GeoJSON は CesiumJS のレイヤー / プリミティブとして配置する。
地図エンジン（フロントエンジン）の選定と追加候補
web/ はエンジン別フロントを並べるマルチエンジン構成
（?engine= で切替）ですが、開発の基本としてメインエンジンは
CesiumJS です。新機能・UI・AI 制御対応はまず Cesium フロント
（web/cesium/）を対象とし、他エンジンは .kasc
プロジェクトの再生プレイヤーとしての互換実装です。プロジェクトデータは
エンジン非依存の projects/ に置き、web/shared/
の .kasc ローダー・ベクターデコーダー・QML コンパイラを全エンジンで
共有するため、新しい 2D エンジンの追加コストは比較的小さくなっています。
現在のエンジン構成
| エンジン | 位置づけ | 特性 | .kasc 対応 |
|---|---|---|---|
| CesiumJS | メイン（既定） | 3D グローブ・3D Tiles・DEM ドレープ・TerrainProvider をネイティブ 対応する唯一のフル機能エンジン。SCENE2D で真上視点の 2D も可。 フットプリントは大きいが KASUGAI の全機能（FLY・AI ツール・プラグイン）はここに集約 | 全行タイプ対応（3dtiles: 含む） |
| MapLibre GL | 2D プレイヤー | WebGL ベースの 2D ベクタータイルエンジン（Mapbox GL v1 フォーク・
OSS）。MVT ベクタータイルをネイティブ描画でき、回転・傾斜表示も可能。
スタイル仕様がデファクト標準（QGIS・geo_webview の /maplibre
配信とも整合） |
2D 行・QML・duckdb/sql・属性 UI・3dtiles:
（deck.gl Tile3DLayer を必要時のみ遅延ロード）実装済み。
3D Tiles ドレープ（deck.gl TerrainExtension）にも対応 |
| OpenLayers | 2D プレイヤー | OGC 準拠最良の 2D エンジン。WMS/WMTS/WFS・多様な投影系・ラスタ 演算に強く、Canvas レンダリングで WebGL 要件が緩い。QGIS 系ツール （QGIS2Web・Lizmap）との親和性が高い | MapLibre 相当（QML・duckdb/sql・属性 UI） |
| Leaflet | 2D プレイヤー | 約 40KB の超軽量 2D エンジン。WebGL 不要の DOM/SVG 描画で 古いブラウザでも動作。専用 pane にレイヤーを割り当てて .kasc の積み順を再現（ラスタ・ベクター混在も順序保持）。地図回転は 非対応のため回転系設定は設けていない | MapLibre 相当（QML・duckdb/sql・属性 UI・インスペクター・3dtiles:
（deck.gl Tile3DLayer をオーバーレイキャンバスで必要時のみ遅延ロード）） |
| GSI Maps | 中間エンジン（調整中） | vendored 地理院地図（gsi-cyberjapan/gsimaps）を同一オリジン iframe で 組み込み、上流コード無改変のまま中間層が GSI/Leaflet API 経由で .kasc を再生。地理院地図の標準 UI（情報リスト・Globe 等）をそのまま利用でき、 Globe 表示時は .kasc レイヤを Cesium 注入で 3D 表示する | ベクター行→作図リスト注入、base:/xyz:/wms:/wmts:→外部タイル。
cam:/theme:・属性 UI 対応。地理院地図の表示レイヤを
xyz: 行として .kasc へ取り込み可。3dtiles: 等は未対応 |
| Navara | 試験的（写実 3D） | @navaramap/three（Rust/WASM GIS コア + Three.js）による
写実 3D プレゼンエンジン。大気散乱・太陽・影のフォトリアルシーンと
quantized-mesh 地形（Re:Earth Terrain）を持つ。ライブラリは npm dist
スナップショットを vendor/navara/ にピン留めし importmap
で読む（Worker が import.meta.url 相対のため同一オリジン必須） |
ベクター行・base:/xyz:・3dtiles:・
cam:/theme: 対応。wms:/wmts:・
3D Tiles ドレープ・地物単位の凡例フィルタは未対応 |
追加候補エンジンの優先順位
評価軸: ①ライセンス（OSS か）、
②メンテナンス状況、③web/shared/
の .kasc 基盤を再利用できるか（移植コスト）、
④既存 3 エンジンでは埋まらない用途があるか。
| 優先度 | エンジン | 特性・採用理由 | 用途・条件 |
|---|---|---|---|
| 中 | deck.gl（オーバーレイ） | 単独エンジンではなく MapLibre/Cesium 上に重ねる大規模データ 可視化レイヤ（ArcLayer・GridLayer・HexagonLayer・TripsLayer 等）。 MapboxOverlay で maplibre フロントに統合可能 | 数十万点規模の密度・集約・軌跡表現が要件化した場合 |
| 中 | ol-cesium（olcs）（連携方式） | 新エンジンではなく OpenLayers 2D ↔ Cesium 3D のカメラ同期ライブラリ。 openlayers フロントで編集しながら cesium の 3D 確認を同時に行う 2D/3D 連動ビューを実現できる | 2D/3D 連動表示が欲しくなった場合（同期モードとして実装） |
| 中 | Potree（点群特化） | EPT/COPC 形式の大規模点群に特化した three.js 系ビューア。 Cesium の 3D Tiles（pnts）でも代替可能だが、LAS/LAZ の大量点群を そのまま軽快に見せる用途では専用ビューアに分がある | kasuga_converter（PDAL 経路）の点群成果物の納品が要件化した場合 |
| 中 | Maptalks | 2D + 2.5D + 3D を1ライブラリで扱うハイブリッド（three.js 統合・ 地形対応）。OpenLayers 的 API で 3D 建物まで描ける。活発に開発中だが 日本語情報・採用実績は少ない | OL の手軽さで軽い 3D まで欲しい場合（代替検討枠） |
| 低 | iTowns | IGN（フランス国土地理院）の three.js ベース 3D エンジン。 グローブ・3D Tiles・点群に対応し Cesium より軽量だが、 エコシステムが小さく役割が Cesium と重複 | Cesium が重すぎる環境での軽量 3D が必要になった場合 |
| 低 | Mapbox GL JS | MapLibre の本家。v2 以降はプロプライエタリで、スタイル仕様は MapLibre と互換のため既存 maplibre フロントで事実上代替済み | Mapbox 独自サービス（Mapbox タイル・Search 等）を使う場合のみ |
| 低 | Google Maps JS API ／ ArcGIS Maps SDK | 商用・API キー・課金必須。ベンダーロックインが .kasc の中立性（エンジン非依存のプロジェクト形式）と衝突する | 顧客要件で明示指定された場合のみ |
| 低 | globe.gl / three-globe | 最小構成の three.js 地球儀。デモ・可視化特化で、地図レイヤ体系 （XYZ・ベクター・属性）は自前実装が必要 | 簡易 3D グローブのデモが必要な場合 |
| 低 | Mapillary JS / Panoramax ビューア（特殊用途） | 街路画像の専用ビューア。地図エンジンではなく連携ウィジェットとして 既存フロントに組み込む性質のもの | kasugai_box の画像連携など、地点写真ビューアの構想が具体化した場合 |
参考（不採用）: Tangram（Mapzen の WebGL ベクタータイルレンダラ）と harp.gl（HERE）は いずれも開発が停止しており、新規採用の対象外です。
KASUGAI Canvas で可能な表示モード
| 表示モード | 可否 | 説明 |
|---|---|---|
| 平面（2D 地図・図面） | ◎ | CesiumJS SceneMode.SCENE2D（真上視点の 2D
地図表示） |
| 3D パース（3D モデル・点群・3DGS） | ◎ | Cesium Cesium3DTileset / Model +
Three.js 点群・3DGS レンダラー |
| 地形（DEM ドレープ） | ◎ | Cesium TerrainProvider /
CesiumWorldTerrain + ImageryLayer |
| グローブ（球形地球儀） | ◎ | CesiumJS はデフォルトで地球儀表示を扱う。グローブ / ローカル 3D 空間の切り替えが可能 |
- KASUGAI Canvas は グローブ（球形地球） も ローカル 3D 空間 も扱える。
- WGS84 / 平面直角座標等の座標系
を使い、CesiumJS の座標変換（
Cartographic,Cartesian3,Transforms）で統一して描画する。
データ種別別のライブラリ選択
| データ | CesiumJS | Three.js | 備考 |
|---|---|---|---|
| 3D Tiles / GLB | ◎ | ◯ | Cesium Cesium3DTileset / Model
でネイティブ表示。PLATEAU も直接読み込み |
| DEM / 標高PNG | ◎ | △ | Cesium TerrainProvider で高精細地形。
地理院標高PNG は GsiDemTerrainProvider
でデコード済み。XYZ を ImageryLayer としてドレープ |
| XYZ / TMS / WMS | ◎ | △ | Cesium ImageryLayer /
UrlTemplateImageryProvider
で曲面・地形にドレープ |
| GeoJSON | ◎ | △ | Cesium GeoJsonDataSource（entity 描画）/
GeoJsonPrimitive（バッチ描画・
render=primitive） |
| バイナリベクター (GeoParquet / FlatGeobuf) | ◎ | △ | geoparquet: / flatgeobuf: /
duckdb: / sql:
でブラウザ内デコード → GeoJSON 正規化経路へ |
| 2D タイル (MVT) | △ | △ | 現行未実装。XYZ ラスタタイルは
ImageryLayer で対応。MVT はタイル/大規模経路として将来候補 |
| 点群 (PLY/LAS/EPT) | ◯ | ◯ | Cesium Cesium3DTileset（pnts / 3DTiles_next）or
Three.js Points / Potree |
| 3DGS (PLY/SPZ/Splat) | △ | ◎ | Three.js 系専用レンダラー |
CesiumJS の強力機能
| 機能 | 用途例 |
|---|---|
| ImageryLayer / ImageryProvider | XYZ / TMS / WMS を地球/地形へ重ね合わせ。前後関係は
ImageryLayerCollection で管理 |
| TerrainProvider | DEM / 標高PNG・CesiumWorldTerrain 等で 3D 地形を構築 |
| Cesium3DTileset | PLATEAU 等の大規模 3D Tiles をネイティブ LOD・カリングで描画 |
| ClippingPlaneCollection / ClippingPlane | 3D Tiles・点群の断面カット |
| ClassificationPrimitive / Vector3DTilePrimitive | 3D 地形・建物へのドレープ・クラシフィケーション |
| GeoJsonPrimitive / GroundPrimitive | ベクターの地形・3D Tiles への高速ドレープ（ベクター高速ドレープ /
render=primitive） |
- CesiumJS は 3D Tiles、DEM、XYZ いずれも 同じグローブ / 深度バッファ 内で描画するため、重ね合わせの前後関係が自然に扱える。
点群・3DGS 用ライブラリ
| ライブラリ | 点群 (LAS/PLY/EPT) | 3DGS (PLY/SPZ/Splat) | 特徴 |
|---|---|---|---|
| CesiumJS | ◯ (3D Tiles pnts / 3DTiles_next) | △ (要カスタムレンダラー) | 大規模点群を地球規模で描画。3DGS は現状最適化されていない |
| Three.js | ◯ (BufferGeometry) |
◎ (gaussian-splats-3d / Splat Viewer) |
3DGS エコシステムが最も充実 |
| Potree | ◎ (専用点群レンダラー) | ❌ | 大規模点群 Web 可視化特化 |
| PlayCanvas SuperSplat | ❌ | ◎ | 3DGS 専用ビューアー。変換・最適化にも強い |
- 点群：大量 PLY / LAS は Potree 形式 / EPT / 3D Tiles（pnts） へ変換して KASUGAI Canvas（CesiumJS / Three.js）で描画
- 3DGS：そのまま描画には Three.js 系の専用レンダラー が現状最適。配信には SPZ 等の圧縮を検討
CesiumJS + Three.js の連携パターン
現行実装：オーバーレイ canvas + カメラ同期
#cesium-container内に Three.js 用の<canvas>（three-canvas、pointer-events:none）を重ねるscene.postRenderでviewer.camera.viewMatrix/frustum.projectionMatrixを Three.js カメラへコピーして同期。ECEF（Cartesian3）座標を Three.js のワールド座標としてそのまま共有できる- 実装が容易で、各エンジンの描画サイクルを独立に保てる
- 深度バッファを共有しないため、地球・3D Tiles との遮蔽関係やピッキングの統合はできない（Three.js 側は常に全面に描画される）
将来候補：同一 WebGL コンテキストでの統合
- CesiumJS の GL コンテキスト上で Three.js を描画し、深度バッファを共有する方式（遮蔽関係を正しく合成可能）
- CesiumJS の内部 GL 状態管理に依存しバージョンアップで壊れやすいため、現行はオーバーレイ方式を採用している
- 単独オブジェクトなら Three.js を介さず CesiumJS の
Model/Primitive+CustomShaderで済ませる方が安定
補完ライブラリ
| 用途 | ライブラリ | 説明 |
|---|---|---|
| 座標変換 | proj4.js / coordsys | 平面直角座標 ↔︎ WGS84 等の変換 |
| GPKG 読込 | sql.js（SQLite WASM・Web Worker） | gpkg: / duckdb:（.gpkg）でブラウザ内読込
→ GeoJSON 正規化（実装済み） |
| Shapefile 読込 | DuckDB-WASM（spatial 拡張 ST_Read） |
duckdb: の format=read。非 COI
環境・リモート URL では動作しないため実質未対応 |
| GeoParquet デコード | hyparquet | CDN から遅延ロード。WKB / ネイティブ GEOMETRY → GeoJSON |
| FlatGeobuf デコード | flatgeobuf 公式 JS リーダー | CDN から遅延ロード。ストリームで逐次 GeoJSON Feature 化 |
| FGDB 変換 | ogr2ogr（サーバー or 事前変換） | プロプライエタリ形式をブラウザ内では読みにくいため、サーバー or 事前変換で対応 |
| 点群変換 | Potree Converter / entwine | PLY/LAS → EPT / 3D Tiles |