@maplat/transform 0.4.0 → 0.4.1

package/README.ja.md

@@ -1,5 +1,7 @@
 # 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/)プロジェクトの一部として開発されています。
 
@@ -13,8 +15,19 @@ English README is [here](./README.md).
 - **複数の座標系サポート:** 通常の直交座標系、Y軸反転座標系、鳥瞰図のような歪んだ座標系など、様々な座標系間の変換に対応
 - **状態管理:** 変換状態の保存と復元をサポート
 
+## 動作要件
+
+- **Node.js:** >= 20
+- **pnpm:** >= 9（開発時）
+
 ## インストール方法
 
+### pnpm（推奨）
+
+```sh
+pnpm add @maplat/transform
+```
+
 ### npm
 
 ```sh
@@ -30,6 +43,8 @@ npm install @maplat/transform
 ## 基本的な使用方法
 
 ```javascript
+import { Transform } from '@maplat/transform';
+
 // 変換定義データのインポート
 const transform = new Transform();
 transform.setCompiled(compiledData);  // Maplatで生成された変換定義を適用
@@ -51,6 +66,93 @@ 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で生成されたコンパイル済み変換定義をインポートして適用します。
+
+- **パラメータ:**
+  - `compiled`: コンパイル済み変換定義オブジェクト
+
+##### `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); // 現在のフォーマットバージョン
+```
+
+## ドキュメント
+
+変換処理の内部実装に関する技術的な詳細については、以下を参照してください:
+- [Transform Internals](./docs/transform-internals.ja.md) - Transformクラスの状態復元と座標検索処理に関する実行時メモ
+
+## 開発
+
+### テストの実行
+
+```sh
+pnpm test
+```
+
 ## 注意事項
 
 このライブラリは座標変換の実行に特化しており、変換定義自体の生成や編集機能は含まれていません。変換定義の作成や編集が必要な場合は、[@maplat/tin](https://github.com/code4history/MaplatTin/)パッケージをご利用ください。
@@ -59,7 +161,7 @@ const restored = transform.transform(transformed, true);
 
 Maplat Limited License 1.1
 
-Copyright (c) 2024 Code for History
+Copyright (c) 2025 Code for History
 
 ### 開発者
 

package/README.md

@@ -1,5 +1,7 @@
 # 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.
 
@@ -13,35 +15,23 @@ This is part of the [Maplat](https://github.com/code4history/Maplat/) project.
 - **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
+## Requirements
 
-### npm
+- **Node.js:** >= 20
+- **pnpm:** >= 9 (for development)
 
-```sh
-npm install @maplat/transform
-```
+## Installation
 
-### JSR (JavaScript Registry)
+### pnpm (Recommended)
 
 ```sh
-# For Deno
-deno add @maplat/transform
-
-# For npm/Node.js
-npx jsr add @maplat/transform
+pnpm add @maplat/transform
 ```
 
-### Deno
-
-```typescript
-// Using JSR (recommended)
-import { Transform } from "jsr:@maplat/transform";
-
-// Using deno.json import map
-import { Transform } from "@maplat/transform";
+### npm
 
-// Or directly from npm
-import { Transform } from "npm:@maplat/transform";
+```sh
+npm install @maplat/transform
 ```
 
 ### Browser
@@ -52,8 +42,6 @@ import { Transform } from "npm:@maplat/transform";
 
 ## Basic Usage
 
-### Node.js/npm
-
 ```javascript
 import { Transform } from '@maplat/transform';
 
@@ -68,24 +56,6 @@ const transformed = transform.transform([100, 100], false);
 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:
@@ -96,44 +66,102 @@ 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.
 
-## Development
+## API Reference
 
-### Running Tests
+### Transform Class
 
-#### Node.js
-```sh
-npm test
+The main class for coordinate transformation.
+
+#### Constructor
+
+```javascript
+const transform = new Transform();
 ```
 
-#### Deno
-```sh
-deno task test
+#### Methods
+
+##### `setCompiled(compiled: Compiled | CompiledLegacy): void`
+
+Import and apply a compiled transformation definition generated by Maplat.
+
+- **Parameters:**
+  - `compiled`: Compiled transformation definition object
+
+##### `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
 ```
 
-### Running Examples
+## Documentation
 
-#### Deno
-```sh
-# Run the example
-deno run --allow-read examples/deno-example.ts
+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
 
-# Or using deno task
-cd examples && deno run --allow-read deno-example.ts
+## 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.
 
-## 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
+Copyright (c) 2025 Code for History
 
 ### Developers
 

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "A JavaScript library that performs coordinate transformation between two plane coordinate systems using transformation definitions generated by Maplat.",
   "type": "module",
   "engines": {