API Reference.ja

API Reference（日本語）

Transform / MapTransform API の概念解説・利用パターンです。本ページは リリース非依存 の読み物（ADR-0012）に絞ります。最新の API シグネチャ一覧は リポジトリ内の docs/api/ を参照してください。

目次

• クラスライフサイクル
• 処理1〜4 の概念レベル解説
• 利用パターン
• API シグネチャ参照
• See Also

---

クラスライフサイクル

MaplatTransform は2つのクラスを公開しています:

Transform（処理1）

1. 生成 — new Transform() がステートレスなインスタンスを返します。
2. 読み込み — setCompiled(compiled) がコンパイル済み定義（V2・V3・レガシー）を 読み込み、内部の検索構造を構築します。再度 setCompiled を呼ぶと前の定義を置き換えます。
3. 変換 — transform(apoint, backward?, ignoreBounds?) が順方向または逆方向の 座標変換を実行します。
4. 状態保存・復元 — コンパイル済み状態は setCompiled で再読み込みすることで 保存済みスナップショットへ復元できます。

MapTransform（処理2〜4）

1. 生成 — new MapTransform() がステートレスなインスタンスを返します。
2. 読み込み — setMapData(mapData) がメインTINとオプションのサブマップTIN （sub_maps）を読み込みます。maxxy は maxZoom から計算されます。
3. 利用 — xy2Merc / merc2Xy（メインTINによる処理1レベルの変換）、 xy2MercWithLayer / merc2XyWithLayer（処理2）、 viewpoint2Mercs / mercs2Viewpoint（処理3）を呼び出します。 処理4 は2つの MapTransform インスタンスの組み合わせです（Tutorials 参照）。

どちらのクラスも setCompiled / setMapData を呼ぶまではステートレスです。 再利用可能で、新しい定義を読み込むと前の定義を置き換えます。

処理1〜4 の概念レベル解説

• 処理1 — Transform: 1つのTIN定義を用いて、ソースXY とターゲットXY の間の 単一平面座標変換を行います。
• 処理2 — MapTransform: 1枚の地図画像内に複数の重なり合うTIN領域 （sub_maps）が存在する場合、領域判定・優先度・重要度に基づいて適用するTINを 自動選択します。順方向は1件、逆方向は重要度順に最大2件を返します。
• 処理3 — MapTransform: ピスプレイビューポート（中心・ズーム・回転）をピクセル 座標系と EPSG:3857 の5点（中心＋東西南北）の間で相互変換します。ピクセル空間の表示と 地理空間の表示を同期させるための構成要素です。
• 処理4 — MapTransform: 地図間ビューポート同期。2つの MapTransform インスタンスが 共通の EPSG:3857 空間を共有し、地図Aで処理3の順変換、地図Bで処理3の逆変換を行うと、 地図Bでの同等のビューポートが得られます。

トポロジー維持・strict / loose モードの理論は Concepts を参照してください。

利用パターン

パターン1: CDN 最小利用例

バンドルせずにブラウザで直接利用する場合は UMD バンドルを CDN から読み込みます。 バージョンはインストール済み・意図したリリースと一致させてください。

<script src="https://cdn.jsdelivr.net/npm/@maplat/transform@0.5.3/dist/maplat_transform.umd.js"></script>
<script>
  var t = new MaplatTransform.Transform();
  t.setCompiled(compiledData);
  var out = t.transform([100, 100], false);
</script>

アップグレード時は 0.5.3 をインストール済みのバージョンに置き換えてください。 OpenLayers の依存はなく、個別に読み込む必要はありません。

パターン2: npm ESM import

import { Transform, MapTransform } from '@maplat/transform';

const t = new Transform();
t.setCompiled(compiledData);
const out = t.transform([100, 100], false);

パターン3: フレームワーク組み込み

React・Vue 等に組み込む場合は、コンポーネントのマウント時に Transform / MapTransform インスタンスを生成し、地図描画前に setCompiled / setMapData を 呼び出します。インスタンスはコンポーネントのライフサイクル中維持し、アンマウント時に 解放してください。どちらのクラスも内部の検索テーブル以外に外部リソースを持ちません。

1つの MapTransform インスタンスを2つの独立した地図で使い回さないでください。 処理4 は2つのインスタンス（それぞれに独自の mapData）を必要とします。

API シグネチャ参照

完全な API シグネチャ一覧（コンストラクタ・メソッド・静的定数・アクセサ・エクスポート型・ ユーティリティ関数・フォーマットバージョン export）はリポジトリ内の docs/api/ で管理しています。本 Wiki ページでは正本との 分岐を避けるためシグネチャを重複保持しません。

参照先:

• docs/api/ — 正本の API シグネチャ
• README §API リファレンス — 概要と導線

---

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

See Also

• Home.ja
• Concepts.ja — V2/V3・strict/loose・トポロジー・座標系
• Tutorials.ja — 具体的な利用パターン（処理2〜4）
• README — インストール・クイックスタート