Skip to content

Concepts.ja

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

Concepts（日本語）

Maplat の背景概念と理論: データ形式・座標変換・TIN ライブラリ。

目次

データ形式

アプリケーションデータ形式

アプリケーションデータは、複数の地図データや POI を集めて地図切り替え可能な アプリケーションとして定義する JSON ファイルです。Maplat のルートフォルダ下に apps フォルダを作成し、{アプリID}.json として配置します。

サンプルは apps/sample.json にあります。

スキーマ（0.2.6 時代 — draft-04）

以下のスキーマは 0.2.6 時代（2018年8月）のものです。snake_case のフィールド名を 使用します。現行版は camelCase（appName, fakeGps, homePosition, defaultZoom, fakeCenter, fakeRadius, startFrom）を使用します。詳細は後述の注記を参照してください。

$schema: "http://json-schema.org/draft-04/schema#"
title: "Maplat Application"
type: "object"
required:
  - "app_name"
  - "home_position"
  - "default_zoom"
  - "sources"
properties:
  app_name:
    oneOf:
      - type: "string"
      - type: "locales"
  fake_gps:
    type: "boolean"
  fake_center:
    oneOf:
      - type: "string"
      - type: "locales"
  fake_radius:
    type: "number"
  home_position:
    type: "array"
    items:
      type: "number"
      minItems: 2
      maxItems: 2
  default_zoom:
    type: "number"
  sources:
    type: "array"
    items:
      anyOf:
        - type: "string"
          enum: ["osm", "gsi"]
        - type: "object"
          required: ["mapID"]
          properties:
            mapID: { type: "string" }
            label: { oneOf: [{ type: "string" }, { type: "locales" }] }
            maptype:
              type: "string"
              enum: ["base", "overlay", "maplat"]
            url: { type: "string" }
  pois:
    type: "array"
    items:
      type: "object"
      required: ["name", "lat", "lng", "desc"]
      properties:
        name: { oneOf: [{ type: "string" }, { type: "locales" }] }
        address: { oneOf: [{ type: "string" }, { type: "locales" }] }
        lat: { type: "number" }
        lng: { type: "number" }
        desc: { oneOf: [{ type: "string" }, { type: "locales" }] }
        image: { type: "string" }

現行版との差異（2026-07 �照合）

現行の apps/sample.json（foss4g-stories ブランチ）は 0.2.6 スキーマと以下の点で異なります:

フィールド 0.2.6 (snake_case) 現行 (camelCase) 備考
app_name → appName app_name appName camelCase 化
fake_gps → fakeGps fake_gps fakeGps camelCase 化
fake_center → fakeCenter fake_center fakeCenter 現行は plain string の場合も
home_position → homePosition home_position homePosition camelCase 化
default_zoom → defaultZoom default_zoom defaultZoom camelCase 化
pois inline POI オブジェクト配列 POI ソース filename 配列（例: ["tatebayashi.json", "stones_poi.geojson"]） POI は外部 GeoJSON ソースへ分離
sources ショートカット "osm", "gsi" "osm", "gsi", "gsi_ortho" gsi_ortho（オルソ画像）追加
sources item フィールド mapID, label, maptype, url + maxZoom, envelopeLngLats, mercatorXShift, mercatorYShift, title, attr, contributor, author, createdAt より豊富なソースメタデータ
startFrom — startFrom (string) 初期表示地図指定
splash — splash (string) スプラッシュ画面画像
description — description (string) アプリ説明文

JSON Schema の構造（locales 型・必須フィールド）は概念的には依然有効ですが、 フィールド命名規則と POI の扱いが変更されています。正本は現行の apps/sample.json およびソースコード内の TypeScript 型定義です。

マップデータ形式

Maplat には2種類の相互運用可能なデータフォーマットが存在します。 maps フォルダ下に {マップID}.json として配置します。

標準データフォーマット

標準フォーマットは人間による手動編集が可能です。標準地図座標系 （Web メルカトル図法, SRID:3857）と古地図/絵地図座標系の対応点対（GCP）で定義されます。

$schema: "http://json-schema.org/draft-04/schema#"
title: "Maplat Standard"
type: "object"
required: ["title", "attr", "width", "height", "gcps"]
properties:
  title: { type: "string" }
  attr: { type: "string" }
  width: { type: "number" }
  height: { type: "number" }
  year: { type: ["string", "number"] }
  url: { type: "string" }
  gcps:
    type: "array"
    items:
      type: "array"
      minItems: 2
      maxItems: 2
      items:
        type: "number"
        minItems: 2
        maxItems: 2
  • gcps — 座標対応点対の配列: [[画像X, 画像Y], [メルカトルX, メルカトルY]]
  • width, height — オリジナル地図画像のピクセル幅/高さ
  • その他属性（title, attr, year）はメタデータ

コンパイル済データフォーマット

コンパイル済フォーマットは標準フォーマットから変換計算を事前完了したものです。 gcps 属性がなくなり、代わりに compiled 属性の下にコンパイル済データ構造が入ります。 人間系での編集を想定していません（一貫性が失われます）。MaplatEditor で相互変換可能です。

フォーマットの選択: コンパイル済フォーマットはデータサイズが大きくなる （100倍以上になる場合も）ですが、読み込み後に変換計算が不要のため体感速度が速いです。 対応点の多い地図ではコンパイル済を推奨します。

座標変換

Tin 変換クラス

Maplat の座標変換は TIN（Triangulated Irregular Network）に基づき、 2つの座標系間の 非線形かつ同相（トポロジーを維持する）双方向写像を保証します。

変換クラスは MaplatTin リポジトリ （@maplat/tin として公開）にあります。歴史的には Maplat リポジトリの js/tin.js に含まれていましたが、別パッケージに分離されました。

依存モジュール:

オブジェクト生成

var tin = new Tin({
    wh: [width, height],
    points: points
});
  • wh — 古地図/絵地図画像のピクセル幅/高さ
  • points — GCP 対の配列（標準マップデータの gcps 属性と同形式）

wh・points とも省略可能で setWh / setPoints で後から設定可能。 いずれかを差し替えると事前計算結果がリセットされ、オブジェクトを再利用できます。 points 配列の一部追加/削除には非対応（常に全件差し替え）。

事前計算: updateTinAsync 

tin.setPoints(points);
tin.updateTinAsync(true).then(function() {
    var illstXy = tin.transform(mapXy, true);
});

updateTinAsync(strict) は Promise を返します。strict 引数は トポロジー維持 TIN が構築できない場合の挙動を制御します。

変換: transform(xy, inverse)

  • 第1引数: 変換対象の XY 座標
  • 第2引数: true なら逆方向（標準地図→絵地図）・省略 or false なら正方向（絵地図→標準地図）

コンパイル済データ: getCompiled / setCompiled

  • getCompiled() — 事前計算結果を取得（シリアライズ用）
  • setCompiled(data) — コンパイル済データを直接セット（updateTinAsync 不要）
  • setCompiled 使用時も wh は先に設定しておく必要あり

strict モードと loose モード

Maplat は生成された TIN が双方向でトポロジーを維持する場合、 双方向全単射（一対一・上への）変換を保証します。

状態 strict_status 挙動
トポロジー維持 STATUS_STRICT 双方向全単射保証
トポロジー破綴・strict モード STATUS_STRICT_ERROR 正方向変換のみ。kinks プロパティに辺の交点リスト
トポロジー破綴・loose モード STATUS_LOOSE 双方向変換可能だが全単射は 非保証

これが Maplat が古地図を正確な地図に重ね合わせる際に 元の画像を歪めない という 核心的保証の理論的基盤です。

TIN 変換ライブラリ

TIN 変換ライブラリ（@maplat/tin）の詳細な API リファレンスは MaplatTin リポジトリ で管理されています。 別 npm パッケージとして公開されており、専用の Wiki / ドキュメントを持ちます。

Maplat レベルの API（MaplatUi）については API-Reference を参照してください。

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

関連ページ

Maplat

Language / 言語

Pages / ページ

English

日本語

External / 外部

Clone this wiki locally