Tutorials.ja

Tutorials（日本語）

MaplatTransform のステップバイステップのチュートリアルです。README を短く保つため README から退避した Transform クラスの基本使用法と MapTransform の利用パターン （処理2〜4）を扱います。

目次

• 基本的な使用方法
• 処理2 — サブマップ選択つき座標変換
• 処理3 — ビューポート変換
• 処理4 — 地図間ビューポート同期
• エラーハンドリング
• See Also

---

基本的な使用方法

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

// Maplat で生成されたコンパイル済み変換定義を適用
const transform = new Transform();
transform.setCompiled(compiledData);

// 順方向の変換（ソース座標系 → ターゲット座標系）
const transformed = transform.transform([100, 100], false);

// 逆方向の変換（ターゲット座標系 → ソース座標系）
const restored = transform.transform(transformed, true);

setCompiled は V2・V3・レガシーのコンパイル済みフォーマットを受け付け、どの フォーマットかを自動判別します。

処理2 — サブマップ選択つき座標変換

1枚の地図画像上に複数のTIN定義（sub_maps）が重なって存在する場合、MapTransform を使うと適切なTINを自動選択して座標変換できます。

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

const mt = new MapTransform();
mt.setMapData({
  compiled: mainCompiledData,   // メインTINのコンパイル済みデータ
  sub_maps: [
    { compiled: sub0Data, priority: 1, importance: 1 },
    { compiled: sub1Data, priority: 2, importance: 2 },
  ],
});

// 順方向: ピクセルXY → EPSG:3857（[レイヤーインデックス, Merc座標] または false を返す）
const result = mt.xy2MercWithLayer([320, 240]);
if (result) {
  const [layerIndex, merc] = result;
  console.log('レイヤー:', layerIndex, 'Merc座標:', merc);
}

// 逆方向: EPSG:3857 → ピクセルXY（重要度順に最大2レイヤー返す）
const results = mt.merc2XyWithLayer([15000000, 4000000]);
results.forEach((r, i) => {
  if (r) console.log(`結果${i}: レイヤー${r[0]}, XY座標`, r[1]);
});

処理3 — ビューポート変換

ピクセル地図の表示ビューポート（中心位置・ズームレベル・回転角）を、EPSG:3857空間上の 5点（中心＋東西南北）として相互変換します。

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

const mt = new MapTransform();
mt.setMapData({ compiled: compiledData });

const canvasSize = [800, 600];  // キャンバスサイズ [幅, 高さ]

// ピクセルビューポート → EPSG:3857 5点
const viewpoint = {
  center: [15000000, 4000000],  // ピクセル空間の中心に対応するEPSG:3857相当座標
  zoom: 14,
  rotation: 0,
};
const mercs = mt.viewpoint2Mercs(viewpoint, canvasSize);
// mercs: [[中心], [北], [東], [南], [西]]  (EPSG:3857)

// EPSG:3857 5点 → ピクセルビューポート
const vp = mt.mercs2Viewpoint(mercs, canvasSize);
console.log(vp.center, vp.zoom, vp.rotation);

処理4 — 地図間ビューポート同期

ある絵地図の表示ビューポートをEPSG:3857空間を中継して別の絵地図のビューポートへ 直接変換します。

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

const mtA = new MapTransform();
mtA.setMapData({ compiled: compiledDataA });

const mtB = new MapTransform();
mtB.setMapData({ compiled: compiledDataB });

const canvasSize = [800, 600];

// 地図Aのビューポート（ピクセル空間A）
const vpA = { center: [15000000, 4000000], zoom: 14, rotation: 0 };

// ピクセル空間A → EPSG:3857 5点（処理3の順変換）
const mercs = mtA.viewpoint2Mercs(vpA, canvasSize);

// EPSG:3857 5点 → 地図Bのビューポート（処理3の逆変換）
const vpB = mtB.mercs2Viewpoint(mercs, canvasSize);
console.log('地図Bのビューポート:', vpB);

エラーハンドリング

このライブラリは以下の場合にエラーをスローする可能性があります:

• 厳密モードでの変換エラー時
• 逆変換が許可されていない状態での逆変換実行時
• 不正なデータ構造での変換実行時

エラーが発生した場合は、変換定義データの修正が必要です。変換定義の修正は @maplat/tin を使ったエディタツールで 行ってください。strict / loose モードの挙動は Concepts を参照してください。

---

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

See Also

• Home.ja
• Concepts.ja — V2/V3・strict/loose・トポロジー・座標系
• API-Reference.ja — 概念解説・利用パターン
• README — インストール・クイックスタート