@maplat/transform 0.5.0 → 0.5.1

package/README.ja.md

@@ -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,6 +206,78 @@ 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`
@@ -126,6 +285,9 @@ Maplatで生成されたコンパイル済み変換定義をインポートし
 - `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[][] }`
 
 ### エクスポートされるユーティリティ関数
 

package/README.md

@@ -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,6 +206,78 @@ 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`
@@ -126,6 +285,9 @@ Perform coordinate transformation.
 - `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
 

package/dist/index.d.ts

@@ -102,6 +102,161 @@ export declare type KinksBD = {
     [key in BiDirectionKey]?: Kinks;
 };
 
+/**
+ * Input data for MapTransform.setMapData().
+ */
+export declare interface MapData {
+    /** Compiled TIN data for the main layer */
+    compiled: Compiled;
+    /** maxZoom value used to compute _maxxy = 2^maxZoom * 256 */
+    maxZoom?: number;
+    /** Sub-map layers */
+    sub_maps?: SubMapData[];
+}
+
+/**
+ * MapTransform — 処理2・3・4を担う座標変換クラス
+ *
+ * - 処理2: submaps 属性を持つ地図で、複数 TIN のうちどれを適用するか判定・選択し座標変換
+ * - 処理3: ビューポート ↔ メルカトル5点 変換
+ * - 処理4: ビューポート ↔ TIN 適用後メルカトル5点 変換
+ *
+ * OpenLayers への依存ゼロ。ブラウザ・Node.js 両対応。
+ */
+export declare class MapTransform {
+    private mainTin;
+    private subTins;
+    private _maxxy;
+    /**
+     * 地図データ（コンパイル済み TIN + sub_maps）をロードする
+     *
+     * @param mapData - メイン TIN と sub_maps の情報
+     */
+    setMapData(mapData: MapData): void;
+    /**
+     * ピクセル座標 → メルカトル座標（最適レイヤー選択）
+     *
+     * @param xy - ピクセル座標 [x, y]
+     * @returns メルカトル座標、または範囲外の場合は false
+     */
+    xy2Merc(xy: number[]): number[] | false;
+    /**
+     * メルカトル座標 → ピクセル座標（最適レイヤー選択）
+     *
+     * @param merc - メルカトル座標 [x, y]
+     * @returns ピクセル座標、または範囲外の場合は false
+     */
+    merc2Xy(merc: number[]): number[] | false;
+    /**
+     * ピクセル座標 → メルカトル座標（レイヤーID付き）
+     * histmap_tin.ts xy2MercAsync_returnLayer() の同期版
+     *
+     * @param xy - ピクセル座標 [x, y]
+     * @returns [レイヤーインデックス, メルカトル座標] または false
+     */
+    xy2MercWithLayer(xy: number[]): [number, number[]] | false;
+    /**
+     * メルカトル座標 → ピクセル座標（複数レイヤー結果）
+     * histmap_tin.ts merc2XyAsync_returnLayer() の同期版
+     *
+     * 現在は MaplatCore の仕様に合わせ、最大2レイヤーまで返す。
+     * 3レイヤー以上返したい場合は、下記の .slice(0, 2) および .filter(i < 2) の
+     * 上限値を増やすか、引数で上限を指定できるようにすること。
+     *
+     * @param merc - メルカトル座標 [x, y]
+     * @returns 最大2要素の配列。各要素は [レイヤーインデックス, ピクセル座標] または undefined
+     */
+    merc2XyWithLayer(merc: number[]): ([number, number[]] | undefined)[];
+    /**
+     * メルカトル5点 → システム座標（複数レイヤー）
+     * histmap_tin.ts mercs2SysCoordsAsync_multiLayer() の同期版
+     *
+     * @param mercs - 5点のメルカトル座標配列（中心＋上下左右）
+     * @returns 各レイヤーのシステム座標配列（または undefined）
+     */
+    mercs2SysCoords(mercs: number[][]): (number[][] | undefined)[];
+    /**
+     * ビューポート → TIN 適用後メルカトル5点
+     * histmap_tin.ts viewpoint2MercsAsync() の同期版
+     *
+     * @param viewpoint - ビューポート（center, zoom, rotation）
+     * @param size - 画面サイズ [width, height]
+     * @returns TIN 変換後のメルカトル5点
+     */
+    viewpoint2Mercs(viewpoint: Viewpoint, size: [number, number]): number[][];
+    /**
+     * TIN 適用後メルカトル5点 → ビューポート
+     * histmap_tin.ts mercs2ViewpointAsync() の同期版
+     *
+     * @param mercs - TIN 変換後のメルカトル5点
+     * @param size - 画面サイズ [width, height]
+     * @returns ビューポート（center, zoom, rotation）
+     */
+    mercs2Viewpoint(mercs: number[][], size: [number, number]): Viewpoint;
+    /** zoom2Radius の静的ラッパー */
+    static zoom2Radius(size: [number, number], zoom: number): number;
+    /** mercViewpoint2Mercs の静的ラッパー */
+    static mercViewpoint2Mercs(center: number[], zoom: number, rotation: number, size: [number, number]): number[][];
+    /** mercs2MercViewpoint の静的ラッパー */
+    static mercs2MercViewpoint(mercs: number[][], size: [number, number]): Viewpoint;
+    /** xy2SysCoord の静的ラッパー */
+    static xy2SysCoord(xy: number[], maxxy: number): number[];
+    /** sysCoord2Xy の静的ラッパー */
+    static sysCoord2Xy(sysCoord: number[], maxxy: number): number[];
+    private _assertMapData;
+    private _assertMaxxy;
+    /**
+     * レイヤーインデックスに対応する Transform インスタンスを返す（三角網描画などの用途）
+     *
+     * @param idx - 0 = メイン TIN、1以上 = sub_maps[idx-1]
+     * @returns 対応する Transform、または範囲外の場合は null
+     */
+    getLayerTransform(idx: number): Transform | null;
+    /** レイヤー数を返す（メイン + sub 数） */
+    get layerCount(): number;
+    /**
+     * viewpoint 変換に使用する最大ピクセル幅（2^maxZoom × 256）
+     * stateToViewpoint / viewpointToState で zoom ↔ scale 変換に使用する
+     * zoom = log2(scale × maxxy / 256) の関係
+     */
+    get maxxy(): number;
+    /** priority 降順でソートした [index, tin, isMain] の配列を返す */
+    private _getTinsSortedByPriority;
+    /** メイン TIN + 全 sub TIN を index 付きで返す */
+    private _getAllTinsWithIndex;
+    /**
+     * 指定レイヤーインデックスで TIN 変換を実行する
+     * index 0 → mainTin, index 1..n → subTins[index-1]
+     */
+    private _transformByIndex;
+    /** 内部用 xy2SysCoord（_maxxy を使用） */
+    private xy2SysCoordInternal;
+}
+
+export declare const MERC_CROSSMATRIX: number[][];
+
+export declare const MERC_MAX = 20037508.342789244;
+
+/**
+ * メルカトル5地点情報からメルカトル地図でのサイズ情報（中心座標、ズーム、回転）を得る
+ *
+ * @param mercs - 中心＋上下左右の5点のメルカトル座標配列
+ * @param size - 画面サイズ [width, height]
+ * @returns Viewpoint オブジェクト（center, zoom, rotation）
+ */
+export declare function mercs2MercViewpoint(mercs: number[][], size: [number, number]): Viewpoint;
+
+/**
+ * 画面サイズと地図ズームから、メルカトル座標上での5座標を取得する
+ *
+ * @param center - 中心のメルカトル座標 [x, y]
+ * @param zoom - メルカトルズームレベル
+ * @param rotation - 回転角（ラジアン）
+ * @param size - 画面サイズ [width, height]
+ * @returns 中心＋上下左右の5点のメルカトル座標配列
+ */
+export declare function mercViewpoint2Mercs(center: number[], zoom: number, rotation: number, size: [number, number]): number[][];
+
 /**
  * エッジセットを正規化する
  * 古いバージョンのフォーマットを新しいフォーマットに変換する
@@ -128,6 +283,15 @@ declare type PropertyTri = {
 
 export declare type PropertyTriKey = "a" | "b" | "c";
 
+/**
+ * 与えられた差分行列を回転する
+ *
+ * @param xys - 回転する座標の配列
+ * @param theta - 回転角（ラジアン）
+ * @returns 回転後の座標の配列
+ */
+export declare function rotateMatrix(xys: number[][], theta: number): number[][];
+
 /**
  * 三角形の頂点の順序を修正する
  * 地図外郭の頂点を含む三角形について、頂点の順序を統一する
@@ -146,6 +310,29 @@ export declare type StrictMode = "strict" | "auto" | "loose";
  */
 export declare type StrictStatus = "strict" | "strict_error" | "loose";
 
+/**
+ * Sub-map TIN data for MapTransform.setMapData().
+ */
+export declare interface SubMapData {
+    /** Compiled TIN data */
+    compiled: Compiled;
+    /** Layer priority (higher = checked first) */
+    priority: number;
+    /** Layer importance (used when multiple layers overlap) */
+    importance: number;
+    /** Bounds vertices in pixel (XY) space. Falls back to compiled.bounds if omitted. */
+    bounds?: number[][];
+}
+
+/**
+ * システム座標（EPSG:3857相当）をピクセル座標に変換する
+ *
+ * @param sysCoord - システム座標 [x, y]
+ * @param maxxy - 最大座標値（2^maxZoom * 256）
+ * @returns ピクセル座標 [x, y]
+ */
+export declare function sysCoord2Xy(sysCoord: number[], maxxy: number): number[];
+
 export declare type Tins = FeatureCollection<Polygon, PropertiesTri>;
 
 export declare type TinsBD = {
@@ -273,6 +460,18 @@ export declare type VerticesParamsBD = {
     [key in BiDirectionKey]?: VerticesParams;
 };
 
+/**
+ * Viewport representation: center in mercator, zoom level, rotation in radians.
+ */
+export declare interface Viewpoint {
+    /** Mercator coordinate [x, y] */
+    center: number[];
+    /** Mercator zoom level */
+    zoom: number;
+    /** Rotation angle in radians */
+    rotation: number;
+}
+
 declare type WeightBuffer = {
     [index: string]: number;
 };
@@ -284,9 +483,27 @@ export declare type WeightBufferBD = {
     [key in BiDirectionKey]?: WeightBuffer;
 };
 
+/**
+ * ピクセル座標をシステム座標（EPSG:3857相当）に変換する
+ *
+ * @param xy - ピクセル座標 [x, y]
+ * @param maxxy - 最大座標値（2^maxZoom * 256）
+ * @returns システム座標 [x, y]
+ */
+export declare function xy2SysCoord(xy: number[], maxxy: number): number[];
+
 /**
  * Y-axis handling directive.
  */
 export declare type YaxisMode = "follow" | "invert";
 
+/**
+ * size（画面サイズ）とズームから、地図面座標上での半径を得る
+ *
+ * @param size - 画面サイズ [width, height]
+ * @param zoom - メルカトルズームレベル
+ * @returns メルカトル座標上での半径
+ */
+export declare function zoom2Radius(size: [number, number], zoom: number): number;
+
 export { }