feat: MapTransform 処理2〜4 実装 (0.5.1)

- MapTransform クラス: submap 選択付き座標変換（処理2）
- MapTransform クラス: ビューポート変換 viewpoint2Mercs / mercs2Viewpoint（処理3）
- 地図間ビューポート同期（処理4）: viewpoint2Mercs + mercs2Viewpoint の組み合わせ
- デモ: submaps.html（処理2）、mapsync.html（処理3・4）
- README（英語・日本語）に MapTransform 処理2〜4 の使用方法を追記

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kochizufan

18th_mapcontest_ea.json

@@ -15,6 +15,9 @@ English README is [here](./README.md).
 - **位相保存:** 変換時の同相性（トポロジー）を維持
 - **複数の座標系サポート:** 通常の直交座標系、Y軸反転座標系、鳥瞰図のような歪んだ座標系など、様々な座標系間の変換に対応
 - **状態管理:** 変換状態の保存と復元をサポート
+- **サブマップ選択（処理2）:** 同一画像上に複数のTIN領域（`sub_maps`）が存在する地図で、領域判定・優先度・重要度に基づいて適用するTINを自動選択し座標変換する
+- **ビューポート変換（処理3）:** ピクセル座標系上の表示ビューポート（中心位置・ズームレベル・回転角）を地図座標系（EPSG:3857）上のビューポートに相互変換する
+- **地図間ビューポート同期（処理4）:** ある絵地図の表示ビューポートを、共通の地図座標系（EPSG:3857）を中継して別の絵地図の表示ビューポートに直接変換する
 
 ## 動作要件
 
@@ -67,6 +70,90 @@ const restored = transform.transform(transformed, true);
 
 エラーが発生した場合は、変換定義データの修正が必要です。変換定義の修正は[@maplat/tin](https://github.com/code4history/MaplatTin/)を使用したエディタツールで行ってください。
 
+## MapTransform の使用方法
+
+### 処理2 — サブマップ選択つき座標変換
+
+1枚の地図画像上に複数のTIN定義（`sub_maps`）が重なって存在する場合、`MapTransform` を使うと適切なTINを自動選択して座標変換できます。
+
+```javascript
+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点（中心＋東西南北）として相互変換します。
+
+```javascript
+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空間を中継して別の絵地図のビューポートへ直接変換します。
+
+```javascript
+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);
+```
+
 ## API リファレンス
 
 ### Transform クラス
@@ -119,13 +206,88 @@ Maplatで生成されたコンパイル済み変換定義をインポートし
 - `Transform.YAXIS_FOLLOW`: Y軸方向に従う
 - `Transform.YAXIS_INVERT`: Y軸方向を反転
 
+### MapTransform クラス
+
+サブマップ選択、ビューポート変換、地図間ビューポート同期（処理2〜4）を担うクラスです。
+
+#### コンストラクタ
+
+```javascript
+const mt = new MapTransform();
+```
+
+#### メソッド
+
+##### `setMapData(mapData: MapData): void`
+
+メインTINとオプションのサブマップTINをロードします。
+
+- **パラメータ:**
+  - `mapData`: `{ compiled, maxZoom?, sub_maps? }` — メインのコンパイル済みTINデータ、オプションの明示的なmaxZoom、オプションのサブマップ定義配列
+
+##### `xy2Merc(xy: number[]): number[] | false`
+
+メインTINを使ってピクセル座標をEPSG:3857に変換します。
+
+- **パラメータ:** `xy` — ピクセル座標 `[x, y]`
+- **戻り値:** EPSG:3857座標、または範囲外の場合は `false`
+
+##### `merc2Xy(merc: number[]): number[] | false`
+
+メインTINを使ってEPSG:3857座標をピクセル座標に逆変換します。
+
+- **パラメータ:** `merc` — EPSG:3857座標 `[x, y]`
+- **戻り値:** ピクセル座標、または範囲外の場合は `false`
+
+##### `xy2MercWithLayer(xy: number[]): [number, number[]] | false`
+
+優先度と領域に基づいてサブマップから適切なTINを自動選択し、ピクセル座標をEPSG:3857に変換します（処理2）。
+
+- **パラメータ:** `xy` — ピクセル座標 `[x, y]`
+- **戻り値:** `[レイヤーインデックス, Merc座標]`、または範囲外の場合は `false`
+
+##### `merc2XyWithLayer(merc: number[]): ([number, number[]] | undefined)[]`
+
+該当する全TINレイヤーでEPSG:3857座標をピクセル座標に逆変換し、重要度順に最大2件を返します（処理2）。
+> 3件以上返したい場合は、実装内の `.slice(0, 2)` / `.filter(i < 2)` の上限値を変更してください。
+
+- **パラメータ:** `merc` — EPSG:3857座標 `[x, y]`
+- **戻り値:** 最大2要素の配列。各要素は `[レイヤーインデックス, XY座標]` または `undefined`
+
+##### `viewpoint2Mercs(viewpoint: Viewpoint, size: [number, number]): number[][]`
+
+ピクセル空間のビューポートをEPSG:3857の5点に変換します（処理3）。
+
+- **パラメータ:**
+  - `viewpoint`: `{ center, zoom, rotation }` — ピクセル空間のビューポート（centerは `xy2SysCoord` 変換後のEPSG:3857相当値）
+  - `size`: キャンバスサイズ `[幅, 高さ]`
+- **戻り値:** EPSG:3857の5点配列 `[中心, 北, 東, 南, 西]`
+- **例外:** 中心点がTIN範囲外の場合にエラー
+
+##### `mercs2Viewpoint(mercs: number[][], size: [number, number]): Viewpoint`
+
+EPSG:3857の5点からピクセル空間のビューポートに逆変換します（処理3の逆変換）。
+
+- **パラメータ:**
+  - `mercs`: EPSG:3857の5点配列（`viewpoint2Mercs` の戻り値と同形式）
+  - `size`: キャンバスサイズ `[幅, 高さ]`
+- **戻り値:** ピクセル空間の `Viewpoint` — `{ center, zoom, rotation }`
+- **例外:** 中心点が逆変換できない場合にエラー
+
+#### アクセサ
+
+- `maxxy: number` — `2^maxZoom × 256`。ピクセル座標とEPSG:3857座標の変換スケール係数
+
 ### エクスポートされる型
 
 - `PointSet`, `BiDirectionKey`, `WeightBufferBD`, `VertexMode`, `StrictMode`, `StrictStatus`, `YaxisMode`
 - `CentroidBD`, `TinsBD`, `KinksBD`, `VerticesParamsBD`, `IndexedTinsBD`
 - `Compiled`, `CompiledLegacy`
 - `Tins`, `Tri`, `PropertyTriKey`
 - `Edge`, `EdgeSet`, `EdgeSetLegacy`
+- `Viewpoint` — `{ center: number[], zoom: number, rotation: number }`
+- `MapData` — `{ compiled: Compiled, maxZoom?: number, sub_maps?: SubMapData[] }`
+- `SubMapData` — `{ compiled: Compiled, priority: number, importance: number, bounds?: number[][] }`
 
 ### エクスポートされるユーティリティ関数
 

18th_mapcontest_gp.json

@@ -15,6 +15,9 @@ This is part of the [Maplat](https://github.com/code4history/Maplat/) project.
 - **Topology Preservation:** Maintains homeomorphic properties during transformation
 - **Multiple Coordinate System Support:** Handles transformations between various coordinate systems including standard orthogonal coordinates, Y-axis inverted coordinates, and distorted coordinates like bird's-eye views
 - **State Management:** Save and restore transformation states
+- **Sub-map Selection (Processing 2):** For maps with multiple overlapping TIN regions (`sub_maps`), automatically determines which TIN to apply based on region boundaries, priority, and importance
+- **Viewport Transformation (Processing 3):** Converts a display viewport (center, zoom, rotation) in pixel coordinate space to a viewport in the map coordinate space (EPSG:3857)
+- **Cross-map Viewport Sync (Processing 4):** Converts a display viewport from one pixel map directly to the corresponding viewport of another pixel map, via the shared map coordinate space
 
 ## Requirements
 
@@ -67,6 +70,90 @@ The library may throw errors in the following cases:
 
 If errors occur, the transformation definition data needs to be modified. Please use editor tools that incorporate [@maplat/tin](https://github.com/code4history/MaplatTin/) to modify transformation definitions.
 
+## MapTransform Usage
+
+### Processing 2 — Sub-map selection and coordinate transformation
+
+When a single map image contains multiple overlapping TIN definitions (`sub_maps`), use `MapTransform` to automatically select the correct TIN and transform coordinates.
+
+```javascript
+import { MapTransform } from '@maplat/transform';
+
+const mt = new MapTransform();
+mt.setMapData({
+  compiled: mainCompiledData,   // Main TIN compiled data
+  sub_maps: [
+    { compiled: sub0Data, priority: 1, importance: 1 },
+    { compiled: sub1Data, priority: 2, importance: 2 },
+  ],
+});
+
+// Forward: pixel XY → EPSG:3857 (returns [layerIndex, mercCoord] or false)
+const result = mt.xy2MercWithLayer([320, 240]);
+if (result) {
+  const [layerIndex, merc] = result;
+  console.log('layer:', layerIndex, 'merc:', merc);
+}
+
+// Reverse: EPSG:3857 → pixel XY (returns up to 2 layers, each [layerIndex, xyCoord] or undefined)
+const results = mt.merc2XyWithLayer([15000000, 4000000]);
+results.forEach((r, i) => {
+  if (r) console.log(`result ${i}: layer ${r[0]}, xy`, r[1]);
+});
+```
+
+### Processing 3 — Viewport transformation
+
+Convert a pixel-map viewport (center position, zoom level, rotation angle) to and from a geographic viewport in EPSG:3857. The viewport is represented as five Mercator points (center + four cardinal offsets).
+
+```javascript
+import { MapTransform } from '@maplat/transform';
+
+const mt = new MapTransform();
+mt.setMapData({ compiled: compiledData });
+
+const canvasSize = [800, 600];   // [width, height] in pixels
+
+// Pixel viewport → EPSG:3857 five points
+const viewpoint = {
+  center: [15000000, 4000000],  // EPSG:3857 center of the pixel-space viewport
+  zoom: 14,
+  rotation: 0,
+};
+const mercs = mt.viewpoint2Mercs(viewpoint, canvasSize);
+// mercs: [[cx,cy], [north], [east], [south], [west]]  (EPSG:3857)
+
+// EPSG:3857 five points → pixel viewport
+const vp = mt.mercs2Viewpoint(mercs, canvasSize);
+console.log(vp.center, vp.zoom, vp.rotation);
+```
+
+### Processing 4 — Cross-map viewport synchronization
+
+Convert the display viewport of one pixel map to the corresponding viewport of another pixel map, using the shared EPSG:3857 space as an intermediary.
+
+```javascript
+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];
+
+// Map A viewport (pixel space A)
+const vpA = { center: [15000000, 4000000], zoom: 14, rotation: 0 };
+
+// Pixel space A → EPSG:3857 five points (Processing 3 forward)
+const mercs = mtA.viewpoint2Mercs(vpA, canvasSize);
+
+// EPSG:3857 five points → Map B viewport (Processing 3 reverse)
+const vpB = mtB.mercs2Viewpoint(mercs, canvasSize);
+console.log('Map B viewport:', vpB);
+```
+
 ## API Reference
 
 ### Transform Class
@@ -119,13 +206,88 @@ Perform coordinate transformation.
 - `Transform.YAXIS_FOLLOW`: Follow Y-axis direction
 - `Transform.YAXIS_INVERT`: Invert Y-axis direction
 
+### MapTransform Class
+
+The class for sub-map selection, viewport transformation, and cross-map viewport synchronization (Processings 2–4).
+
+#### Constructor
+
+```javascript
+const mt = new MapTransform();
+```
+
+#### Methods
+
+##### `setMapData(mapData: MapData): void`
+
+Load a main TIN and optional sub-map TINs.
+
+- **Parameters:**
+  - `mapData`: `{ compiled, maxZoom?, sub_maps? }` — main compiled TIN data, optional explicit maxZoom, and optional array of sub-map definitions
+
+##### `xy2Merc(xy: number[]): number[] | false`
+
+Transform a pixel coordinate to EPSG:3857 using the main TIN.
+
+- **Parameters:** `xy` — pixel coordinate `[x, y]`
+- **Returns:** EPSG:3857 coordinate, or `false` if out of bounds
+
+##### `merc2Xy(merc: number[]): number[] | false`
+
+Transform an EPSG:3857 coordinate to pixel coordinate using the main TIN (reverse).
+
+- **Parameters:** `merc` — EPSG:3857 coordinate `[x, y]`
+- **Returns:** Pixel coordinate, or `false` if out of bounds
+
+##### `xy2MercWithLayer(xy: number[]): [number, number[]] | false`
+
+Transform a pixel coordinate to EPSG:3857, automatically selecting the appropriate TIN from sub-maps based on priority and region (Processing 2).
+
+- **Parameters:** `xy` — pixel coordinate `[x, y]`
+- **Returns:** `[layerIndex, mercCoord]` or `false` if out of bounds
+
+##### `merc2XyWithLayer(merc: number[]): ([number, number[]] | undefined)[]`
+
+Transform an EPSG:3857 coordinate to pixel coordinate across all applicable TIN layers, returning up to 2 results ordered by importance (Processing 2).
+> To return more than 2 layers, increase the limit in the `.slice(0, 2)` / `.filter(i < 2)` lines inside the implementation.
+
+- **Parameters:** `merc` — EPSG:3857 coordinate `[x, y]`
+- **Returns:** Array of up to 2 elements; each is `[layerIndex, xyCoord]` or `undefined`
+
+##### `viewpoint2Mercs(viewpoint: Viewpoint, size: [number, number]): number[][]`
+
+Convert a pixel-space viewport to five EPSG:3857 points (Processing 3).
+
+- **Parameters:**
+  - `viewpoint`: `{ center, zoom, rotation }` — viewport in pixel space (center as EPSG:3857 equivalent via `xy2SysCoord`)
+  - `size`: Canvas size `[width, height]`
+- **Returns:** Array of 5 EPSG:3857 points `[center, north, east, south, west]`
+- **Throws:** Error if the center point is outside the TIN bounds
+
+##### `mercs2Viewpoint(mercs: number[][], size: [number, number]): Viewpoint`
+
+Convert five EPSG:3857 points back to a pixel-space viewport (Processing 3 reverse).
+
+- **Parameters:**
+  - `mercs`: Array of 5 EPSG:3857 points (as returned by `viewpoint2Mercs`)
+  - `size`: Canvas size `[width, height]`
+- **Returns:** `Viewpoint` — `{ center, zoom, rotation }` in pixel space
+- **Throws:** Error if the center point cannot be reverse-transformed
+
+#### Accessors
+
+- `maxxy: number` — `2^maxZoom × 256`; the pixel-to-EPSG:3857 scale factor
+
 ### Exported Types
 
 - `PointSet`, `BiDirectionKey`, `WeightBufferBD`, `VertexMode`, `StrictMode`, `StrictStatus`, `YaxisMode`
 - `CentroidBD`, `TinsBD`, `KinksBD`, `VerticesParamsBD`, `IndexedTinsBD`
 - `Compiled`, `CompiledLegacy`
 - `Tins`, `Tri`, `PropertyTriKey`
 - `Edge`, `EdgeSet`, `EdgeSetLegacy`
+- `Viewpoint` — `{ center: number[], zoom: number, rotation: number }`
+- `MapData` — `{ compiled: Compiled, maxZoom?: number, sub_maps?: SubMapData[] }`
+- `SubMapData` — `{ compiled: Compiled, priority: number, importance: number, bounds?: number[][] }`
 
 ### Exported Utility Functions