@maplat/transform 0.4.1 → 0.5.0

package/README.md

@@ -1,171 +1,179 @@
-# 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
-- **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.
-
-- **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
-```
-
-## 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).
+# 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[];