@maplat/transform 0.4.0 → 0.5.0

package/README.ja.md

@@ -1,69 +1,179 @@
-# Maplat Transform
-
-Maplatで生成された座標変換定義を使用して、2つの平面座標系間で座標変換を実現するJavaScriptライブラリです。
-[Maplat](https://github.com/code4history/Maplat/)プロジェクトの一部として開発されています。
-
-English README is [here](./README.md).
-
-## 主な機能
-
-- **座標変換定義のインポート:** Maplatで生成された座標変換定義をインポートし、変換のための内部構造を構築
-- **双方向座標変換:** 2つの平面間で双方向の座標変換が可能
-- **位相保存:** 変換時の同相性（トポロジー）を維持
-- **複数の座標系サポート:** 通常の直交座標系、Y軸反転座標系、鳥瞰図のような歪んだ座標系など、様々な座標系間の変換に対応
-- **状態管理:** 変換状態の保存と復元をサポート
-
-## インストール方法
-
-### npm
-
-```sh
-npm install @maplat/transform
-```
-
-### ブラウザ
-
-```html
-<script src="https://unpkg.com/@maplat/transform/dist/maplat_transform.umd.js"></script>
-```
-
-## 基本的な使用方法
-
-```javascript
-// 変換定義データのインポート
-const transform = new Transform();
-transform.setCompiled(compiledData);  // Maplatで生成された変換定義を適用
-
-// 順方向の変換（ソース座標系 → ターゲット座標系）
-const transformed = transform.transform([100, 100], false);
-
-// 逆方向の変換（ターゲット座標系 → ソース座標系）
-const restored = transform.transform(transformed, true);
-```
-
-### エラーハンドリング
-
-このライブラリは以下の場合にエラーをスローする可能性があります：
-
-- 厳密モードでの変換エラー時
-- 逆変換が許可されていない状態での逆変換実行時
-- 不正なデータ構造での変換実行時
-
-エラーが発生した場合は、変換定義データの修正が必要です。変換定義の修正は[@maplat/tin](https://github.com/code4history/MaplatTin/)を使用したエディタツールで行ってください。
-
-## 注意事項
-
-このライブラリは座標変換の実行に特化しており、変換定義自体の生成や編集機能は含まれていません。変換定義の作成や編集が必要な場合は、[@maplat/tin](https://github.com/code4history/MaplatTin/)パッケージをご利用ください。
-
-## ライセンス
-
-Maplat Limited License 1.1
-
-Copyright (c) 2024 Code for History
-
-### 開発者
-
-- Kohei Otsuka
-- Code for History
-
+# Maplat Transform
+
+[![CI](https://github.com/code4history/MaplatTransform/actions/workflows/test.yml/badge.svg)](https://github.com/code4history/MaplatTransform/actions/workflows/test.yml)
+
+Maplatで生成された座標変換定義を使用して、2つの平面座標系間で座標変換を実現するJavaScriptライブラリです。
+[Maplat](https://github.com/code4history/Maplat/)プロジェクトの一部として開発されています。
+
+English README is [here](./README.md).
+
+## 主な機能
+
+- **座標変換定義のインポート:** Maplatで生成された座標変換定義をインポートし、変換のための内部構造を構築
+- **V2/V3フォーマット対応:** レガシーV2フォーマット（固定4境界頂点）と新しいV3フォーマット（N境界頂点、より高精度）の両方に対応
+- **双方向座標変換:** 2つの平面間で双方向の座標変換が可能
+- **位相保存:** 変換時の同相性（トポロジー）を維持
+- **複数の座標系サポート:** 通常の直交座標系、Y軸反転座標系、鳥瞰図のような歪んだ座標系など、様々な座標系間の変換に対応
+- **状態管理:** 変換状態の保存と復元をサポート
+
+## 動作要件
+
+- **Node.js:** >= 20
+- **pnpm:** >= 9（開発時）
+
+## インストール方法
+
+### pnpm（推奨）
+
+```sh
+pnpm add @maplat/transform
+```
+
+### npm
+
+```sh
+npm install @maplat/transform
+```
+
+### ブラウザ
+
+```html
+<script src="https://unpkg.com/@maplat/transform/dist/maplat_transform.umd.js"></script>
+```
+
+## 基本的な使用方法
+
+```javascript
+import { Transform } from '@maplat/transform';
+
+// 変換定義データのインポート
+const transform = new Transform();
+transform.setCompiled(compiledData);  // Maplatで生成された変換定義を適用
+
+// 順方向の変換（ソース座標系 → ターゲット座標系）
+const transformed = transform.transform([100, 100], false);
+
+// 逆方向の変換（ターゲット座標系 → ソース座標系）
+const restored = transform.transform(transformed, true);
+```
+
+### エラーハンドリング
+
+このライブラリは以下の場合にエラーをスローする可能性があります：
+
+- 厳密モードでの変換エラー時
+- 逆変換が許可されていない状態での逆変換実行時
+- 不正なデータ構造での変換実行時
+
+エラーが発生した場合は、変換定義データの修正が必要です。変換定義の修正は[@maplat/tin](https://github.com/code4history/MaplatTin/)を使用したエディタツールで行ってください。
+
+## API リファレンス
+
+### Transform クラス
+
+座標変換を行うメインクラスです。
+
+#### コンストラクタ
+
+```javascript
+const transform = new Transform();
+```
+
+#### メソッド
+
+##### `setCompiled(compiled: Compiled | CompiledLegacy): void`
+
+Maplatで生成されたコンパイル済み変換定義をインポートして適用します。レガシー形式、V2（4境界頂点）、V3（N境界頂点）を自動的に判別して処理します。
+
+- **パラメータ:**
+  - `compiled`: コンパイル済み変換定義オブジェクト（V2、V3、またはレガシー形式）
+
+##### `transform(apoint: number[], backward?: boolean, ignoreBounds?: boolean): number[] | false`
+
+座標変換を実行します。
+
+- **パラメータ:**
+  - `apoint`: 変換する座標 `[x, y]`
+  - `backward`: 逆方向の変換を行うか（デフォルト: `false`）
+  - `ignoreBounds`: 境界チェックを無視するか（デフォルト: `false`）
+- **戻り値:** 変換後の座標、または境界外の場合は `false`
+- **例外:** `strict_status == "strict_error"` の状態で逆変換を試みた場合にエラーをスロー
+
+#### 静的定数
+
+**頂点モード:**
+- `Transform.VERTEX_PLAIN`: 標準平面座標系
+- `Transform.VERTEX_BIRDEYE`: 鳥瞰図座標系
+
+**厳密モード:**
+- `Transform.MODE_STRICT`: 厳密な変換モード
+- `Transform.MODE_AUTO`: 自動モード選択
+- `Transform.MODE_LOOSE`: 緩い変換モード
+
+**厳密ステータス:**
+- `Transform.STATUS_STRICT`: 厳密ステータス
+- `Transform.STATUS_ERROR`: エラーステータス（逆変換不可）
+- `Transform.STATUS_LOOSE`: 緩いステータス
+
+**Y軸モード:**
+- `Transform.YAXIS_FOLLOW`: Y軸方向に従う
+- `Transform.YAXIS_INVERT`: Y軸方向を反転
+
+### エクスポートされる型
+
+- `PointSet`, `BiDirectionKey`, `WeightBufferBD`, `VertexMode`, `StrictMode`, `StrictStatus`, `YaxisMode`
+- `CentroidBD`, `TinsBD`, `KinksBD`, `VerticesParamsBD`, `IndexedTinsBD`
+- `Compiled`, `CompiledLegacy`
+- `Tins`, `Tri`, `PropertyTriKey`
+- `Edge`, `EdgeSet`, `EdgeSetLegacy`
+
+### エクスポートされるユーティリティ関数
+
+- `transformArr`: 低レベルの座標変換関数
+- `rotateVerticesTriangle`: 三角形の頂点を回転
+- `counterTri`: カウンター三角形ユーティリティ
+- `normalizeEdges`: エッジ定義の正規化
+
+### フォーマットバージョン
+
+```javascript
+import { format_version } from '@maplat/transform';
+console.log(format_version); // 現在のフォーマットバージョン
+```
+
+コンパイル済みデータのフォーマットには2つのモダンバージョンがあります:
+
+- **V2:** マップのバウンディングボックスから算出した固定4点の境界頂点を使用
+- **V3:** N個（4以上）の境界頂点を使用し、特にマップ端付近の変換精度を向上
+
+どちらのフォーマットも `setCompiled()` が自動的に判別して処理します。V3フォーマットのコンパイル済みデータはバージョン3以降の[@maplat/tin](https://github.com/code4history/MaplatTin/)で生成されます。
+
+## ドキュメント
+
+変換処理の内部実装に関する技術的な詳細については、以下を参照してください:
+- [Transform Internals](./docs/transform-internals.ja.md) - Transformクラスの状態復元と座標検索処理に関する実行時メモ
+
+## 開発
+
+### テストの実行
+
+```sh
+pnpm test
+```
+
+## 注意事項
+
+このライブラリは座標変換の実行に特化しており、変換定義自体の生成や編集機能は含まれていません。変換定義の作成や編集が必要な場合は、[@maplat/tin](https://github.com/code4history/MaplatTin/)パッケージをご利用ください。
+
+## ライセンス
+
+Maplat Limited License 1.1
+
+Copyright (c) 2025 Code for History
+
+### 開発者
+
+- Kohei Otsuka
+- Code for History
+
 あなたの貢献をお待ちしています！[イシューやプルリクエスト](https://github.com/code4history/MaplatTransform/issues)は大歓迎です。

package/README.md

@@ -1,143 +1,179 @@
-# Maplat Transform
-
-A JavaScript library that performs coordinate transformation between two plane coordinate systems using transformation definitions generated by Maplat.
-This is part of the [Maplat](https://github.com/code4history/Maplat/) project.
-
-日本語のREADMEは[こちら](./README.ja.md)
-
-## Key Features
-
-- **Import Transformation Definitions:** Import and build internal structures from transformation definitions generated by Maplat
-- **Bidirectional Coordinate Transformation:** Convert coordinates between two planes in both directions
-- **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
-
-## Installation
-
-### npm
-
-```sh
-npm install @maplat/transform
-```
-
-### JSR (JavaScript Registry)
-
-```sh
-# For Deno
-deno add @maplat/transform
-
-# For npm/Node.js
-npx jsr add @maplat/transform
-```
-
-### Deno
-
-```typescript
-// Using JSR (recommended)
-import { Transform } from "jsr:@maplat/transform";
-
-// Using deno.json import map
-import { Transform } from "@maplat/transform";
-
-// Or directly from npm
-import { Transform } from "npm:@maplat/transform";
-```
-
-### Browser
-
-```html
-<script src="https://unpkg.com/@maplat/transform/dist/maplat_transform.umd.js"></script>
-```
-
-## Basic Usage
-
-### Node.js/npm
-
-```javascript
-import { Transform } from '@maplat/transform';
-
-// Import transformation definition
-const transform = new Transform();
-transform.setCompiled(compiledData);  // Apply transformation definition generated by Maplat
-
-// Forward transformation (source → target coordinate system)
-const transformed = transform.transform([100, 100], false);
-
-// Backward transformation (target → source coordinate system)
-const restored = transform.transform(transformed, true);
-```
-
-### Deno
-
-```typescript
-import { Transform } from "../src/index.ts";
-
-// Load compiled data from file
-const compiledJson = await Deno.readTextFile('./compiled.json');
-const compiledData = JSON.parse(compiledJson);
-
-// Create and configure transform
-const transform = new Transform();
-transform.setCompiled(compiledData);
-
-// Use the same API as Node.js
-const transformed = transform.transform([100, 100], false);
-const restored = transform.transform(transformed, true);
-```
-
-### Error Handling
-
-The library may throw errors in the following cases:
-
-- Transformation errors in strict mode
-- Attempting backward transformation when not allowed
-- Invalid data structure during transformation
-
-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.
-
-## Development
-
-### Running Tests
-
-#### Node.js
-```sh
-npm test
-```
-
-#### Deno
-```sh
-deno task test
-```
-
-### Running Examples
-
-#### Deno
-```sh
-# Run the example
-deno run --allow-read examples/deno-example.ts
-
-# Or using deno task
-cd examples && deno run --allow-read deno-example.ts
-```
-
-## Important Note
-
-This library specializes in executing coordinate transformations and does not include functionality for generating or editing transformation definitions. If you need to create or edit transformation definitions, please use the [@maplat/tin](https://github.com/code4history/MaplatTin/) package.
-
-## Deno Support
-
-This library fully supports Deno. See the [Deno Usage Guide](./docs/DENO_USAGE.md) for detailed instructions on using MaplatTransform with Deno.
-
-## License
-
-Maplat Limited License 1.1
-
-Copyright (c) 2024 Code for History
-
-### Developers
-
-- Kohei Otsuka
-- Code for History
-
-We welcome your contributions! Feel free to submit [issues and pull requests](https://github.com/code4history/MaplatTransform/issues).
+# Maplat Transform
+
+[![CI](https://github.com/code4history/MaplatTransform/actions/workflows/test.yml/badge.svg)](https://github.com/code4history/MaplatTransform/actions/workflows/test.yml)
+
+A JavaScript library that performs coordinate transformation between two plane coordinate systems using transformation definitions generated by Maplat.
+This is part of the [Maplat](https://github.com/code4history/Maplat/) project.
+
+日本語のREADMEは[こちら](./README.ja.md)
+
+## Key Features
+
+- **Import Transformation Definitions:** Import and build internal structures from transformation definitions generated by Maplat
+- **V2/V3 Format Support:** Compatible with both legacy V2 compiled format (4 fixed boundary vertices) and the new V3 format (N boundary vertices for higher accuracy)
+- **Bidirectional Coordinate Transformation:** Convert coordinates between two planes in both directions
+- **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
+
+## Requirements
+
+- **Node.js:** >= 20
+- **pnpm:** >= 9 (for development)
+
+## Installation
+
+### pnpm (Recommended)
+
+```sh
+pnpm add @maplat/transform
+```
+
+### npm
+
+```sh
+npm install @maplat/transform
+```
+
+### Browser
+
+```html
+<script src="https://unpkg.com/@maplat/transform/dist/maplat_transform.umd.js"></script>
+```
+
+## Basic Usage
+
+```javascript
+import { Transform } from '@maplat/transform';
+
+// Import transformation definition
+const transform = new Transform();
+transform.setCompiled(compiledData);  // Apply transformation definition generated by Maplat
+
+// Forward transformation (source → target coordinate system)
+const transformed = transform.transform([100, 100], false);
+
+// Backward transformation (target → source coordinate system)
+const restored = transform.transform(transformed, true);
+```
+
+### Error Handling
+
+The library may throw errors in the following cases:
+
+- Transformation errors in strict mode
+- Attempting backward transformation when not allowed
+- Invalid data structure during transformation
+
+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.
+
+## API Reference
+
+### Transform Class
+
+The main class for coordinate transformation.
+
+#### Constructor
+
+```javascript
+const transform = new Transform();
+```
+
+#### Methods
+
+##### `setCompiled(compiled: Compiled | CompiledLegacy): void`
+
+Import and apply a compiled transformation definition generated by Maplat. Supports legacy format, V2 (4 boundary vertices), and V3 (N boundary vertices) automatically.
+
+- **Parameters:**
+  - `compiled`: Compiled transformation definition object (V2, V3, or legacy format)
+
+##### `transform(apoint: number[], backward?: boolean, ignoreBounds?: boolean): number[] | false`
+
+Perform coordinate transformation.
+
+- **Parameters:**
+  - `apoint`: Coordinate to transform `[x, y]`
+  - `backward`: Whether to perform backward transformation (default: `false`)
+  - `ignoreBounds`: Whether to ignore boundary checks (default: `false`)
+- **Returns:** Transformed coordinate or `false` if out of bounds
+- **Throws:** Error if backward transformation is attempted when `strict_status == "strict_error"`
+
+#### Static Constants
+
+**Vertex Modes:**
+- `Transform.VERTEX_PLAIN`: Standard plane coordinate system
+- `Transform.VERTEX_BIRDEYE`: Bird's-eye view coordinate system
+
+**Strict Modes:**
+- `Transform.MODE_STRICT`: Strict transformation mode
+- `Transform.MODE_AUTO`: Automatic mode selection
+- `Transform.MODE_LOOSE`: Loose transformation mode
+
+**Strict Status:**
+- `Transform.STATUS_STRICT`: Strict status
+- `Transform.STATUS_ERROR`: Error status (backward transformation not allowed)
+- `Transform.STATUS_LOOSE`: Loose status
+
+**Y-axis Modes:**
+- `Transform.YAXIS_FOLLOW`: Follow Y-axis direction
+- `Transform.YAXIS_INVERT`: Invert Y-axis direction
+
+### Exported Types
+
+- `PointSet`, `BiDirectionKey`, `WeightBufferBD`, `VertexMode`, `StrictMode`, `StrictStatus`, `YaxisMode`
+- `CentroidBD`, `TinsBD`, `KinksBD`, `VerticesParamsBD`, `IndexedTinsBD`
+- `Compiled`, `CompiledLegacy`
+- `Tins`, `Tri`, `PropertyTriKey`
+- `Edge`, `EdgeSet`, `EdgeSetLegacy`
+
+### Exported Utility Functions
+
+- `transformArr`: Low-level coordinate transformation function
+- `rotateVerticesTriangle`: Rotate vertices of a triangle
+- `counterTri`: Counter triangle utility
+- `normalizeEdges`: Normalize edge definitions
+
+### Format Version
+
+```javascript
+import { format_version } from '@maplat/transform';
+console.log(format_version); // Current format version
+```
+
+The compiled data format has two modern versions:
+
+- **V2:** Uses 4 fixed boundary vertices derived from the map bounding box
+- **V3:** Uses N boundary vertices (≥4) for more precise boundary definition, improving transformation accuracy especially near map edges
+
+Both formats are handled transparently by `setCompiled()`. V3 compiled data is generated by [@maplat/tin](https://github.com/code4history/MaplatTin/) version 3 or later.
+
+## Documentation
+
+For detailed technical information about the transformation internals, see:
+- [Transform Internals](./docs/transform-internals.md) - Runtime notes on how Transform class reconstructs state and performs coordinate lookups
+
+## Development
+
+### Running Tests
+
+```sh
+pnpm test
+```
+
+## Important Note
+
+This library specializes in executing coordinate transformations and does not include functionality for generating or editing transformation definitions. If you need to create or edit transformation definitions, please use the [@maplat/tin](https://github.com/code4history/MaplatTin/) package.
+
+## License
+
+Maplat Limited License 1.1
+
+Copyright (c) 2025 Code for History
+
+### Developers
+
+- Kohei Otsuka
+- Code for History
+
+We welcome your contributions! Feel free to submit [issues and pull requests](https://github.com/code4history/MaplatTransform/issues).

package/dist/index.d.ts

@@ -32,7 +32,7 @@ export declare interface Compiled {
     strictMode?: StrictMode;
     vertices_params: number[][];
     vertices_points: PointSet[];
-    edges: EdgeSet[];
+    edges?: EdgeSet[];
     bounds?: number[][];
     boundsPolygon?: Feature<Polygon>;
     wh?: number[];