Skip to content

Concepts.ja

Jump to bottom
Kohei Otsuka edited this page Jul 24, 2026 · 1 revision

概念解説（日本語）

MaplatCore の背景と理論: 座標変換・ベースマップ切替・POI/レイヤーモデル・ Maplat エコシステム全体との関係。

目次

MaplatCore が提供するもの

MaplatCore は Maplat ビューアスタックのコアライブラリです。MaplatApp クラスを公開し、以下を行います:

  • 地図・アプリ定義 JSON の読み込み
  • 非線形同相 TIN 変換の計算（または事前計算済みデータの読み込み）
  • OpenLayers 地図の初期化
  • マーカー / ライン / ベクター / POI レイヤー / GPS / イベント API の提供

エンドユーザー向けビューアである Maplat （@maplat/ui）は MaplatCore 上に構築され、PWA シェル・UI コンポーネント・ アプリローダープロトコルを追加します。MaplatCore は、同じ変換保証を持つ 地図描画をカスタムアプリへ組込みたい場合の低レベルライブラリです。

非線形同相座標変換

Maplat の定義的特性は、古地図を正確な現代地図へ重ね合わせる際に 元の画像を歪めない ことです。これは TIN（Triangulated Irregular Network）変換により実現されます:

  • 非線形 — 各三角形が独自のアフィン写像を持ち、全体として滑らかに 曲げられる変換となります。
  • 同相 — 変換は連続かつ連続な逆写像を持ち、元の画像の位相が保存 されます。折り返しや引き裂きは発生しません。
  • 双方向・全単射（strict モード時）— 古地図上の各点は現代地図上の 唯一の点へ、その逆も同様に写像されます。

変換ライブラリは独立パッケージとして管理されています: @maplat/tin（理論は MaplatTin Wiki 参照）。

strict と loose モード

状態 strict_status 挙動
位相保存 STATUS_STRICT 双方向の全単射が保証されます
位相崩壊・strict モード STATUS_STRICT_ERROR 順方向変換のみ。kinks プロパティにエッジ交差一覧
位相崩壊・loose モード STATUS_LOOSE 双方向変換は可能だが、全単射は保証されません

これが Maplat が古地図を歪めずに正確な現代地図へ重ね合わせる 中核理論保証です。

ベースマップ切替（OpenLayers / Mapbox GL JS / MapLibre GL JS）

MaplatCore は描画エンジンとして OpenLayers を使用します（必須の peer dependency）。OpenLayers がラスタタイルソースとビューポートを処理します。

ベクタータイル については2つのオプション peer dependency をサポートします:

  • mapbox-gl（^1.0.0 || ^2.0.0 || ^3.0.0）— Mapbox ベクタータイル用。 mapboxToken オプションが必要です。
  • maplibre-gl（^3.0.0 || ^4.0.0）— MapLibre ベクタータイル用。トークン不要。

どちらも option オブジェクト（mapboxgl / maplibregl キー）経由で注入 されるため、バンドラーは未使用側をツリーシェイクできます。

POI とレイヤーモデル

Maplat はポイントデータ（マーカー）をレイヤーで管理します。デフォルトレイヤーは 'main' です。各レイヤーは独自のデフォルトアイコン・選択アイコンを持ちます。 POI レイヤーはベースマップソースから独立しており、どの地図にも重ねられます。

API は Tutorials § POI レイヤー管理 を、 概念モデルは API-Reference を参照してください。

イベントモデル

MaplatCore は app.addEventListener(type, callback) でイベントを配信します。 コアイベント:

  • clickMarker — evt.detail にクリックされたマーカーのデータを格納
  • clickMap — 地図の背景がクリックされたときに発火
  • gps_result — GPS 位置更新があったときに発火
  • gps_error — GPS が失敗したときに発火

イベント名はリリース間で安定です。ペイロードスキーマは進化する可能性が あります。現状は docs/api/ を参照してください。

Maplat（@maplat/ui）との関係

Maplat はエンドユーザー向け ビューアアプリです。MaplatCore を描画コアとして使用し、以下を追加します:

  • PWA シェル（マニフェスト・Service Worker・シェア・URL 状態）
  • アプリローダープロトコル（アプリ JSON を取得・ソースを管理）
  • UI コンポーネント（地図セレクタ・POI リスト・情報バルーン等）
  • i18n

エンドユーザー向けのウェブアプリを構築する場合は @maplat/ui を直接 使用してください。地図ライフサイクルを低レベルで制御したい場合は @maplat/core を使用します。

MaplatTin（@maplat/tin）との関係

MaplatTin はスタンドアロンの TIN 変換ライブラリです。MaplatCore は内部で座標変換に使用します。 MaplatTin は OpenLayers に依存せず、Node.js 環境でオフライン変換計算 （例: MaplatTransform による前処理パイプライン）にも使用できます。

英語版はこちら / Read this page in English

関連項目

MaplatCore

Language / 言語

Pages / ページ

English

日本語

External / 外部

Clone this wiki locally