geo_webview — 仕様書

geo_webview ドキュメント

この仕様書は README.md と CHANGELOG.md の内容に基づき、機能別に整理した正式な仕様を提供します。 対象リポジトリ: geo_webview(ルートに配置)。

目的と範囲

1. 機能概要


2. API / エンドポイント仕様(高水準)

共通的な振る舞い:


3. パーマリンク形式とパラメータ

基本(推奨)

例:

http://localhost:8089/qgis-map?x=139.01234&y=35.12345&scale=1000.0&rotation=0.00

短縮形式(プレゼン資料向け)

変換ルール:


4. Web 配信(KASUGAI Canvas エクスポート)

プラグイン内蔵の生成HTMLビューア(旧 /qgis-map・/maplibre・/map3d)は v3.24.0 で廃止され、閲覧は KASUGAI Canvas に一本化された。 現在の Web 配信は .kasc+canvas_data/ エクスポートが中核であり、詳細は §15 を参照。


5–9. OGC サービス(v3.29.0 で廃止)

WMS / WMTS・XYZ / WFS・/maplibre-style の各エンドポイントと関連内部実装 (wms_service.py・wmts_service.py・wfs_service.py・sld_renderer.py・ maplibre/、ANGLE パイプライン、WFS/WMTS キャッシュ)は v3.29.0 で撤去。 プラグインはサーバレス配信(.kasc+canvas_data/ 出力+/export-data/ 配信)に専念する。 旧実装の詳細は git 履歴を参照。

10. Google Maps / Google Earth 連携(v3.30.0 で廃止)

Google Maps / Google Earth の URL 生成・パース機能 (_build_google_maps_url・_build_google_earth_url・ _parse_google_maps_at_url・_parse_google_earth_url・パネルの外部 起動ボタン・bridge の googleMapsUrl/googleEarthUrl/openExternal の Google 対応)は v3.30.0 で撤去。Google Earth へのリンクは KASUGAI Canvas 側のベースマップコントロールが担う。 旧実装の詳細は git 履歴を参照。


11. External Control(外部制御)のパース優先度と挙動


12. テーマ (Theme) サポート


13. レンダリング(/screenshot)とパフォーマンス

契約(contract):

視聴者ズーム(クライアント単位・ステートレス):

実装:

性能上の注意:


14. 投影 (CRS) ポリシー


15. KASUGAI Canvas 連携(送出)

QGIS プロジェクトのレイヤツリーを、KASUGAI Canvas のプロジェクト (.kasc + canvas_data/)として書き出す機能。実体は kasugai_export.py。

起動経路

経路 呼び出し 用途
パネルボタン ▶ Canvas / ▶ WebView ボタン (plugin.py: on_kasugai_launch_clicked) 人手操作。パネルの Engine: コンボで起動エンジンを選択(QSettings kasugai_engine に保存)。▶ Canvas(route=kasugai)は再エクスポートしてから登録・ブラウザ起動するため、押すたびに最新のレイヤ状態が Canvas に反映される。Canvas 未検出時はボタンが「Install KASUGAI Canvas」表示となり、クリックでセットアップ(NSIS・.kasc 関連付けあり)/ポータブルZIP(展開のみ)を選んでバックグラウンドインストール後に起動へ合流。▶ WebView(route=hosted)は bridge kasugaiExport(open_app=True) と同じく出力→フォールバック→ブラウザ起動まで行う。CDN 行の CDN: コンボ(編集可、ZIP ボタンと同じ行)でホスト版チャンネルを選択(stable/unstable/カスタムURL、QSettings kasugai_hosted_channel に保存・設定ダイアログと共通)
パネルボタン Export ボタン (plugin.py: on_kasugai_export_clicked) 人手操作(ファイル出力のみ。Canvas 起動・登録はしない。ZIP は生成しない)
パネルボタン ZIP ボタン (plugin.py: on_kasugai_zip_clicked) エクスポート物一式を kasugai_canvas_<チャンネル>.zip としてブラウザダウンロード。/export-data/ がオンデマンドで ZIP を生成して返す(要 HTTP サーバー稼働)。CDN コンボのチャンネルがファイル名に反映される
HTTP GET http://localhost:8089/kasugai (server_manager._handle_kasugai) 外部アプリ・AI からの一発起動。?engine= で起動エンジン指定可。応答は {ok,url,via,dir,layers,tiles,engine} JSON
Bridge bridge_call の kasugaiExport(output_dir, open_app, native_formats, hidden_as_off, emit_themes, emit_bookmarks, emit_launchers, engine, install, route, use_existing, emit_atlas, link_files, vector_format, visible_data_only, progress_cb, site_control) Live Driver 経由の AI 制御(MCP qgis_bridge_call / REST /api/cmd / JSONL)。use_existing=True で再エクスポートせず既存の .kasc のみ使用(未出力なら code=not_exported)

出力フォルダ構成

<out_dir>/                    # 既定: <ドキュメント>/kasugai_canvas_qgis
├─ kasugai_canvas.kasc        # インスペクタ設定(外部プロジェクト登録対象)
├─ project.json               # {"title": ...}
└─ canvas_data/
   ├─ *.geojson               # 変換失敗時の最終フォールバック出力(EPSG:4326)
   ├─ *.fgb                   # ベクター変換の第1候補出力 / ネイティブ参照の FGB(複製)
   ├─ *.gpkg                  # ネイティブ参照の GPKG(複製)
   ├─ *.parquet               # ネイティブ参照の Parquet(複製)
   ├─ *.csv / *.tsv           # duckdb: 参照の区切りテキスト(複製)
   ├─ <dir>/                  # ローカル 3D Tiles / ローカル XYZ タイルの複製(1GiB 上限)
   ├─ *.qml                   # 各ベクターレイヤの QGIS スタイル
   └─ *.svg / *.png 等        # .qml が参照するシンボル画像(QGIS 内蔵SVG・ローカル画像の複製)

.kasc 行の生成規則

| QGIS 側 | .kasc 行 | 備考 | |---|---|---| | GPKG ソース(地理座標系) | gpkg: グループ/名 | canvas_data/x.gpkg | on | table=<表> | style=canvas_data/x.qml | ファイルを canvas_data/ へ複製。複数テーブルは1ファイルを共有 | | GeoJSON/Parquet/FGB ソース | geojson: / geoparquet: / flatgeobuf: 参照行 | ローカルは複製、http(s) は URL をそのまま記述 | | CSV/TSV(delimitedtext・ogr) | duckdb: 名 | canvas_data/x.csv | on | format=csv | lon=<列> | lat=<列> | ジオメトリ列は geom=。delimitedtext は URI の xField/yField/wktField を引き継ぎ、ogr CSV はヘッダから推定。delimitedtext で非地理座標系の場合は FlatGeobuf 変換(フォールバック時 GeoJSON) | | フィルタ(subsetString)付き GPKG | gpkg: … | where=<フィルタ> | ネイティブ参照のままフィルタ維持(SQL 評価) | | フィルタ付き GeoJSON/FGB・URL Parquet | geojson:/flatgeobuf:/geoparquet: … | where=<フィルタ> | Canvas 側 where-eval.js のクライアント評価(OGR SQL WHERE句準拠・|| 連結対応)。評価器が扱えない式(単独 |・% 等)は FlatGeobuf 変換でフィルタを地物へ焼き込む(フォールバック時 GeoJSON) | | フィルタ付き Parquet(ローカル) | duckdb: 名 | canvas_data/x.parquet | on | format=parquet | where=<フィルタ> | duckdb: へ切替えて SQL 評価 | | 3D Tiles レイヤ(QgsTiledSceneLayer) | 3dtiles: グループ/名 | <tileset.json URL or canvas_data/x/tileset.json> | on | http(s) は URL 参照、ローカルはディレクトリごと canvas_data/ へ複製(1GiB 上限・超過は skipped) | | XYZ タイルラスタ | xyz: 行。表示中の最下段のみ base: 行(既定ベースマップとして既定群の先頭に置く)。「背景図」「ベースマップ」「basemap」名のグループ内にある XYZ は位置・表示状態に関わらず全て base: 行(ベースマップ候補)として登録し、グループ名はタイトルから外す(配下のサブグループは残し、Canvas のベースマップ選択でグループ化表示される)。非表示の候補は | off 付きで出力。グループ名は設定ダイアログの Basemap Groups(QSettings kasugai_basemap_groups・カンマ区切り)で追加可能 | zmin/zmax → minZoom=/maxZoom=。不透明度は opacity=、限定範囲は bbox=西経,南緯,東経,北緯。縮尺表示は minScale=/maxScale= | | XYZ ローカルテンプレート | xyz: 行(canvas_data/

/{z}/{x}/{y}.png) | file:///…/{z}/{x}/{y}.png はタイルツリーごと canvas_data/ へ複製(1GiB 上限・超過は skipped) | | WMS ラスタ(type=xyz 以外) | wms: グループ/名 | <エンドポイントURL> | on | layers=, styles=, format= | QGIS の WMS 接続 URI から url=/layers=/styles=/format= を抽出。Canvas 側が GetMap を 256px タイルへ分解して要求 | | その他ベクター(SHP/PostGIS/WFS/メモリ等)・非地理座標系 | FlatGeobuf(EPSG:4326・空間インデックス付き)へ変換して canvas_data/ へ flatgeobuf: 行 | ドライバ非搭載時は Parquet、変換失敗時は GeoJSON へフォールバック。再投影は warnings に記録 | | 属性テーブルのみ(NoGeometry)・ローカルラスタ・ベクタータイル・メッシュ・点群・アノテーション等 | 出力せず skipped に種別/理由付きで記録 | | | 非表示レイヤ | hidden_as_off=True またはマップテーマ存在時に | off 付きで出力。visible_data_only=True(QSettings kasugai_visible_data_only・既定 ON)ではレイヤ行を一切出力せず skipped(背景図グループの base: 候補のみ従来通り出力・高速化)。visible_data_only=False で | off 行として全データを変換・複製する従来動作 | 既定(visible_only=True)では除外 | | キャンバス | cam: 行(中心座標+概算高度+回転) | | || 保存済み3Dビュー(ローカル/グローブ) | cam:QGIS3D <名>|lat|lon|h=|p=|d= 行(注視点+dist/pitch/yaw→ENUオフセットでカメラ位置逆算: 高さ=dist·cos(pitch)・水平=dist·sin(pitch)・視線方位=360-yaw・p=pitch-90) + terrain: 行(垂直誇張/オフセット/陰影/ジェネレータ) + scene3d: 行(背景色/スカイボックス/影/SSAO/EDL・グローブは globe=on) + light: 行(平行光源の方位・仰角・強度・色) | 3Dビューが存在する場合のみ出力。シーンCRSはビューごとの <qgis3d><crs> を解決し、地心系(QGIS4グローブ・EPSG:4978等)はECEF→測地変換で対応。既定値相当の項目は省略 | || 3Dビューのアニメーション(<animation3d>キーフレーム) | fly_geojson: QGIS3D <名> | canvas_data/anim3d_<slug>.geojson | speed=<m/s> | view=camera | step=<m> 行 + カメラ軌道の LineString GeoJSON | 各キーフレーム(注視点+dist/pitch/yaw+時刻)のカメラ位置を計算してカメラ軌道にする。speed=軌道3D総延長÷アニメ時間。キーフレーム2個未満は出力しない | | ベクターの3Dレンダラ(立ち上げ) | ベクター行へ | extrude=<m>(立ち上げ高さ)・| z=<m>(基準高さオフセット) を付与 | QgsVectorLayer3DRenderer のポリゴン/ラインシンボル。Canvas(Cesium)側で polygon の height/extrudedHeight へ反映 | | ブックマーク | bookmarks.xml(qgis_bookmarks形式・EPSG:4326正規化) + bookmark: 行(プロジェクト+アプリケーション両方) | emit_bookmarks=False で抑制。Canvas 側が XML を読み込みカメラプリセットへ展開する | | アトラス有効な印刷レイアウト | fly_geojson: Atlas: <レイアウト名> | canvas_data/atlas_<slug>.geojson | speed= | pitch=-85 | height=0 | view=camera | step= 行 | emit_atlas=False で抑制(v4.8.0〜)。各アトラスページの表示範囲(参照地図 extent)を巡回するプレゼン用フライパス。座標Z値にページを収めるカメラ高(楕円体高)を焼き込み、properties.heightReference="MSL" で地形加算を抑止、ページ名一覧は properties.pages へ。地図回転付きは warnings に記録のみ |

その他: attr= に QGIS レイヤの出典(attribution)を引き継ぐ。 where= は行の最終オプションで、値は改行までが式 (|| 連結・'a|b' リテラル等の | を含んでよい)。 where-eval.js は || 連結に対応済み(単独 |・% は非対応)。 off や他の key=value は where= より前に置く。 view: の ;where= は行内トークンのため対象外(値に | は書けない)。 全レイヤ行で minScale=/maxScale= に QGIS の「縮尺による表示」 (minimumScale=引き側限界・maximumScale=寄り側限界)を出力する。 Canvas 側は同じ範囲で表示/非表示を切り替える。 .qml 書き出し後、シンボルレイヤが参照する画像(SvgMarker/RasterMarker/ SVGFill/RasterFill 等の name/imageFile/svgFile/file)を実ファイルへ 解決して canvas_data/ へ複製し、.qml 内の参照を canvas_data/ 内のファイル名へ書き換える (QGIS 内蔵SVGの transport/… 等の相対名は QgsApplication.svgPaths() で 解決。http(s)/data/base64: 参照はそのまま維持。解決不能は warnings 記録)。 sql: 行は QGIS 側に対応する任意クエリソースが無いため出力しない (クエリ系は duckdb: の宣言的オプションで網羅する)。

ベクターレイヤの出力方針を切り替える「推奨形式スイッチ」 (QSettings kasugai_vector_format、既定 native)。 切替は4経路あり、パネル/設定ダイアログは永続設定を読み書きし、 URL/bridge は当該エクスポートだけの一時上書き(いずれも相互に同期):

  • パネルの Format: コンボ (native (reference as-is) / recommended (FlatGeobuf → canvas_data/) / geojson (WEB interop → GeoJSON))— 永続
  • 設定ダイアログの Vector Export Format コンボ — 永続
  • GET /kasugai?fmt=recommended|native|geojson — そのリクエストのみ上書き (応答 JSON に vector_format を含む)
  • bridge kasugaiExport(vector_format='recommended'|'native'|'geojson') — 呼出しのみ上書き
モードベクターの扱い
native(既定) 読めるソースはそのまま参照(gpkg:/geojson:/shp:/wfs:/duckdb:/flatgeobuf:/geoparquet: 行)。非ネイティブ形式のみ変換(下表のフォールバック)
recommended FlatGeobuf/GeoParquet 以外の全ソースを FlatGeobuf(EPSG:4326・空間インデックス付き)へ変換し canvas_data/ へ flatgeobuf: 行で配置。既に FlatGeobuf/GeoParquet のソースは参照を維持(flatgeobuf:/geoparquet:/duckdb:+format=parquet 行)。subsetString・fields/where/limit は変換データへ焼き込み。Canvas 側では bbox=auto の範囲読みが効く(flatgeobuf: は空間インデックス+Range、geoparquet: は covering.bbox 列または行グループ geospatial statistics による部分読み。いずれも無いファイルは全件へフォールバック)
geojson(WEB連携) 全ベクター(FlatGeobuf/GeoParquet ソース含む・WFS/メモリ等も)を GeoJSON(EPSG:4326)へ変換し canvas_data/ へ geojson: 行で配置。canvas_data/ がオープン標準の GeoJSON のみになるため、KASUGAI Canvas 以外の WebGIS・GIS ツールでもそのまま読み込める相互運用向けモード

変換ドライバは FlatGeobuf が第1候補(非搭載環境は Parquet)で、 変換失敗時は GeoJSON(EPSG:4326) へフォールバックする(native モードの非ネイティブ変換と同じ経路)。 geojson モードは GeoJSON 固定(ドライバ切替なし)。

非表示レイヤの出力省略(表示中のみ変換)

非表示レイヤ(hidden_as_off=True またはマップテーマ存在時に | off で出力されるレイヤ)を .kasc のレイヤ行へ一切出力しない 高速化スイッチ(QSettings kasugai_visible_data_only、既定 ON)。 Canvas のレイヤ一覧に非表示レイヤが並ばず、データ変換・ canvas_data/ へのコピー・スタイル書き出しのコストも掛からない。 背景図グループ内の XYZ タイルなど base: 候補のみ従来通り | off 付きで出力する(ベースマップ選択の候補)。スキップされた レイヤは Canvas で表示に切り替えられない(skipped に理由付きで 記録)。theme: 行は実際に出力されたレイヤのみを対象とする。 OFF で従来通り非表示レイヤも | off 行として全データを変換・ 複製する(プロジェクトの丸ごと引越し用途)。

切替経路(パネル/設定ダイアログは永続設定を読み書き、 bridge/API 引数は当該エクスポートだけの一時上書き):

  • パネルの Visible data only (faster) チェック — 永続
  • 設定ダイアログの Vector Export Format 内にある同名チェック — 永続
  • bridge kasugaiExport(visible_data_only=True|False) — 呼出しのみ上書き
  • export_kasugai_project(visible_data_only=…) — 呼出しのみ上書き

カスタムレイヤタブ(custom-layer)とレイヤ別オプション

パネルの Layers タブでレイヤごとの .kasc オプションを 設定できる。値はレイヤ customProperty へ保存され、エクスポート時に レイヤ行の | key=value として出力される (グレー表示=自動値、空欄に戻すと自動値へ復帰)。

列customProperty.kasc 出力
sitekasugai_sitesite=<箇所名>(-/空=強制未割当。空欄+チェックONでグループ名を自動付与)
orderkasugai_orderorder=<数値>(同一 site 内の順序。小さいほど最前面。VIEW モードの ▲▼ ボタンで設定(EDIT の列は無し))
listkasugai_listlist=off(レイヤ一覧から非表示・標準/カスタムとも。地図は描画)
optskasugai_opts任意の key=value を空白/パイプ区切りで追加(例 opacity=0.5 heat=on)。legend_order=asc|desc|reverse|ラベル列挙 でカスタムタブの凡例順を変更可

Custom layers tab チェック(QSettings kasugai_site_control、既定 OFF)を ON にすると、 レイヤツリーのグループ名を site=<グループ階層> (例 site=A工区、入れ子は 工事/A工区)として グループ内全レイヤへ自動付与する。site= 付きレイヤが 1件でも出力されれば assets/custom-layer.js を canvas_data/ へ複製して plugin: custom-layer | name=レイヤ | url=canvas_data/custom-layer.js | before=layers-panel 行を書く(チェックOFFでも customProperty 指定の site= だけは 有効かつプラグイン行が出る)。

  • Canvas 側では site= は custom-layer タブ (表示名「レイヤ」)専用の集約キーで、標準レイヤタブには 全レイヤが従来通り表示される(標準一覧から隠すには list=off。タブ名が重複するため組み込み側は 「システムレイヤ」に改称される)。custom-layer タブでは グループごとの一括 on/off と、メンバーの凡例(QML 分類) の表示・シンボル別 on/off ができる。point/line/polygon 等の 種別違いをまとめて制御できる
  • グループ無しレイヤは site= なしで出力され、 custom-layer タブの「その他」に集約されて一括 on/off (標準レイヤタブには残る)。ベースマップグループは対象外
  • url= はプロジェクト相対のため CDN/静的ホスティング・全エンジンでそのまま動作する。 プラグインJSの正本は Canvas web/cesium/PLUGIN/custom-layer/plugin.js

切替経路:

  • パネル Layers タブの Custom layers tab チェック — 永続
  • 設定ダイアログの同名チェック — 永続
  • bridge kasugaiExport(site_control=True|False) — 呼出しのみ上書き
  • export_kasugai_project(site_control=…) — 呼出しのみ上書き

エクスポート進捗(progress_cb)

export_kasugai_project / bridge kasugaiExport に progress_cb(done, total, name) を渡すと、レイヤツリー走査の 各レイヤ処理開始時に「何件目/全何件・対象名」を通知する (全件完了時は (total, total, ''))。パネルのエクスポート/ 起動ボタンは QProgressDialog に「レイヤーを変換中 N/M: 名前」 とバーを表示し、Cancel 押下で ExportCancelled を送出して 中断できる(bridge は code: 'cancelled' で返す)。 GET /kasugai 経路は GUI を持たないため同形式の進捗を QgsMessageLog へ記録する。

.qml スタイル出力

スタイル(.qml)はベクターデータ形式とは独立で、 native/recommended/geojson のどのモードでも同じ扱い:

  • 出力される全ベクターレイヤについて layer.saveNamedStyle() で canvas_data/<slug>.qml を書き出し、.kasc 行へ | style=canvas_data/<slug>.qml を付与する。 ネイティブ参照行(gpkg:/flatgeobuf: 等)でも 変換行(flatgeobuf:/geojson:)でも付き方は同じ
  • .qml の中身は <renderer-v2>(シンボル)・ <labeling>/<text-style>(ラベル)・ 時間設定等の QGIS レンダラ定義。Canvas 側は qml-style.js+<engine>/qml-render.js が これをエンジン描画へコンパイルする(データ形式ではなくスタイル再現の責務)
  • ユーザー定義関数(geo_userfunc の @qgsfunction)を含む式属性は 書き出し時に宣言式へ展開する(配布物を組込み関数のみにする)
  • シンボル画像(SvgMarker/RasterMarker/SVGFill/RasterFill 等)の参照は canvas_data/ へ複製し .qml 内パスを書き換える(前述「その他」の通り)
  • 差分エクスポート(changed)では style 変更のあったレイヤのみ .qml を再書き出しし、未変更レイヤは既存 .qml を再利用する

スタイルの配布経路は .qml+style= の1系統に統一 (v4.21.0 で GPKG layer_styles への書き込み経路 embed_gpkg_style は廃止)。

KASUGAI 側への反映

起動中の KASUGAI ローカルサーバー(KASUGAI_CANVAS_PORT、既定 8510)が あれば POST /api/projects/register で外部プロジェクト登録し、 POST /api/command の switchProject で表示を切り替える。

Canvas が使えない場合は次の順でフォールバックする (/kasugai・kasugaiExport とも応答の via で供給元を返す):

via 条件 URL
kasugai Canvas 稼働(or exe/関連付けで起動成功) http://127.0.0.1:8510/<engine>/?project=<id>
qgis-http Canvas 未起動だが インストール済み web/ あり http://localhost:<port>/<engine>/?kasc=<export-data URL>
hosted Canvas 未インストール(要インターネット) https://yamamoto-ryuzo.github.io/kasugai-canvas-web/<channel>/<engine>/?kasc=<export-data URL>
null いずれも不可 出力のみ成功
  • qgis-http: geo_webview の HTTP サーバーが エンドポイントに一致しなかった パスをインストール済み Canvas の web/ 配下へ静的解決する (find_kasugai_web_dir())。同一オリジンのため混在コンテンツ問題なし
  • hosted: エンジン本体は kasugai-canvas-web(GitHub Pages)から取得し、 .kasc+canvas_data/ は本サーバーの /export-data/ から読む。https→localhost の fetch は Chrome Private Network Access 対象のため、サーバーは OPTIONS プリフライトに Access-Control-Allow-Private-Network: true で 応答する。チャンネルは設定 kasugai_hosted_channel (stable/unstable/カスタムURL、既定 stable)で、 パネルの CDN: コンボまたは設定ダイアログから変更する
  • エンジン起動HTML は HEAD メソッドで <engine>/index.html を自動探索する ため、サーバーは HEAD(静的配信のみ)にも応答する

AI からの操作

  • Live Driver の qgis_bridge_call(MCP/REST/JSONL)で kasugaiExport を呼ぶ — 推奨(引数制御可能・JSON 応答)
  • または GET /kasugai を直接 HTTP で呼ぶ
  • KASUGAI 側の WebView プラグイン qgis-import (kasugai_canvas web/PLUGIN/)の「QGISから取り込み」ボタンも 同じ /kasugai を呼ぶ薄い実装

16. セキュリティ・運用上の注意

  • デフォルトで外部アクセスを許す設計だが、公開環境ではファイアウォールやプロキシでアクセス制御を厳格に行うこと。
  • External Control を有効にしていると任意の外部URLで QGIS の表示が書き換わるため、信頼できるネットワーク内または追加の承認フローを用いることを強く推奨。
  • ログを適切に出力し、受信元IP・タイムスタンプ・実行アクションを残す運用を推奨。

17. テスト・QA 手順

自動テスト候補:

  • server_manager.py のユニットテスト: ポート選定・バインド挙動のモックテスト。
  • URL パーサ(内部形式)の単体テスト(複数フォーマットのケース)。
  • wmts タイル座標→BBOX 変換のユニットテスト。

手動テスト手順(QGIS 実環境):

  1. QGIS を起動しプラグインをインストール。
  2. Export で .kasc+canvas_data/ を出力し、パネルの Engine: でエンジンを選び ▶ Canvas を押してブラウザでそのエンジンが開くことを確認(未出力時はエクスポートを促すメッセージが出る)。▶ WebView は出力→ブラウザ起動まで一発で行う(/kasugai と同じフォールバックが働く)。
  3. External Control を ON にして、別ホスト(または同一ホスト)から /qgis-map?x=...&y=...&scale=... にアクセスして QGIS がジャンプすることを確認。
  4. /screenshot でキャンバス PNG が返ることを確認。
  5. /present ページがブラウザで開くことを確認。

テスト注意:

  • CI 環境では qgis.core や PyQt6 が無いため、これらをモックするかローカルでの手動確認が必要。

18. 実装ファイルと責務マッピング

  • plugin.py — メインプラグインロジック、パーマリンク/ナビゲート、パネルイベント配線。
  • panel.py — パネル UI 実装(Web配信グループ、ナビゲート、生成、外部制御トグル等)。
  • panel_base.ui — Qt Designer の UI 定義。
  • server_manager.py — 組み込み HTTP サーバーの起動/停止・ルーティング(/kasugai /export-data/ /present /present/state /screenshot /received /layouts /layout-pdf /<engine>/ 等)。
  • http_server.py — HTTP 応答の低水準送信ユーティリティ。
  • kasugai_export.py — KASUGAI Canvas 連携(.kasc+canvas_data/ 生成、起動HTML生成、プロジェクト登録、コマンド送信、フォールバックURL構築)。
  • scale_zoom.py — スケール/ズーム換算。
  • settings_dialog.py — 設定ダイアログ(KASUGAI インストール先・ホスト版チャンネル・Basemap Groups)。
  • bridge.py — AI/外部制御用ブリッジ(kasugaiExport 等)。

19. 変更履歴の要約(V2/V3 ハイライト)

  • V2.0.0: WMS サポートと外部アクセス(0.0.0.0 バインド)を追加。

  • V2.6.0: 投影定義と軸順情報を生成 HTML に埋め込み、座標表示の精度向上。

  • V2.8.0: External Control の自動ナビゲート追加。

  • V2.10.0: Google Earth y トークン対応とスケール推定の改善。

  • V2.12.0: テーマ対応 WMS 出力(仮想マップビュー)。

  • V2.13.0: WMTS タイルエンドポイント、MapLibre 改善(pitch トグル、zoom clamp 解除)。

  • V3.0.0: MapLibre WFS + QGIS スタイル注入の安定化、ベーススタイルの相対URL化、ブラシ無しポリゴンの正しい境界線表示、単位正規化(mm/pt→px)を確立。

  • V3.1.0: WMTS キャッシュ導入

    • サーバ側で WMTS タイルのキャッシュを有効化しました。キャッシュは各 "identity" ごとに分離され、identity は表示中のレイヤ識別子(layer ID)と各レイヤに適用されるスタイル識別子(style ID)を決定的に組み合わせた JSON を sha1 ハッシュ化し、その先頭 12 文字(short hash)を採用して生成されます。
    • GetCapabilities の ResourceURL / ServiceMetadataURL に ?v=<identity_short> を付与することで、クライアントが現在サーバ側で有効な identity を検出できるようにしました。
    • クライアント(MapLibre)は画面移動(moveend)時に GetCapabilities を再取得し、identity が変化していれば WMTS タイルソースのみを差し替えて新しいタイルを取得する挙動を推奨します(WFS やスタイル全体の再読み込みは不要)。
    • この仕組みにより、サーバ側で表示用レイヤやスタイルが変更された際に WMTS のみを効率的に更新・無効化でき、WFS の重複登録や全スタイル再適用に起因する副作用を避けられます。