@maplat/transform 0.2.3 → 0.4.0

package/README.md

@@ -1,143 +1,143 @@
-# 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
+
+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).

package/dist/index.d.ts

@@ -5,21 +5,18 @@ import { Polygon } from 'geojson';
 import { Position } from 'geojson';
 
 /**
- * 変換の方向を示す型定義
- * - forw: 順方向（ソース → ターゲット）
- * - bakw: 逆方向（ターゲット → ソース）
+ * Directional selector shared across the codebase.
  */
 export declare type BiDirectionKey = "forw" | "bakw";
 
-export declare type Centroid = Feature<Point>;
+declare type Centroid = Feature<Point>;
 
 export declare type CentroidBD = {
     [key in BiDirectionKey]?: Centroid;
 };
 
 /**
- * コンパイルされた設定の型定義
- * 変換に必要な全ての情報を含む
+ * Serialized structure generated by MaplatTin and consumed by Transform.
  */
 export declare interface Compiled {
     version?: number;
@@ -42,6 +39,9 @@ export declare interface Compiled {
     xy?: number[];
 }
 
+/**
+ * Historical serialization format prior to 2.00703.
+ */
 export declare interface CompiledLegacy extends Compiled {
     tins?: TinsBD;
     centroid?: CentroidBD;
@@ -96,7 +96,7 @@ export declare type IndexedTinsBD = {
     [key in BiDirectionKey]?: IndexedTins;
 };
 
-export declare type Kinks = FeatureCollection<Point>;
+declare type Kinks = FeatureCollection<Point>;
 
 export declare type KinksBD = {
     [key in BiDirectionKey]?: Kinks;
@@ -113,7 +113,7 @@ export declare type KinksBD = {
 export declare function normalizeEdges(edges: EdgeSet[] | EdgeSetLegacy[], version?: number): EdgeSet[];
 
 /**
- * 座標ペアの型定義。[ソース座標, ターゲット座標] の形式
+ * Two-way coordinate pair: [source, target].
  */
 export declare type PointSet = [Position, Position];
 
@@ -137,18 +137,12 @@ export declare type PropertyTriKey = "a" | "b" | "c";
 export declare function rotateVerticesTriangle(tins: Tins): Tins;
 
 /**
- * 厳密性モードの型定義
- * - strict: 厳密モード（交差なしを保証）
- * - auto: 自動モード（可能な限り厳密に）
- * - loose: 緩和モード（交差を許容）
+ * Strictness flags supported during transformation.
  */
 export declare type StrictMode = "strict" | "auto" | "loose";
 
 /**
- * 厳密性モードの生成結果
- * - strict: 厳密モード生成成功
- * - auto: 厳密モードでエラー
- * - loose: 緩和モード
+ * Result of strictness evaluation.
  */
 export declare type StrictStatus = "strict" | "strict_error" | "loose";
 
@@ -200,6 +194,19 @@ export declare class Transform {
     stateFull: boolean;
     stateTriangle?: Tri;
     stateBackward?: boolean;
+    /**
+     * Optional properties for MaplatCore extension
+     * These properties allow consuming applications to extend Transform instances
+     * with additional metadata without requiring Module Augmentation
+     */
+    /** Layer priority for rendering order */
+    priority?: number;
+    /** Layer importance for display decisions */
+    importance?: number;
+    /** Bounds in XY (source) coordinate system */
+    xyBounds?: Feature<Polygon>;
+    /** Bounds in Mercator (Web Mercator) coordinate system */
+    mercBounds?: Feature<Polygon>;
     constructor();
     /**
      * コンパイルされた設定を適用します
@@ -214,6 +221,8 @@ export declare class Transform {
      * 4. インデックスの作成
      */
     setCompiled(compiled: Compiled | CompiledLegacy): void;
+    private applyModernState;
+    private applyLegacyState;
     /**
      * TINネットワークのインデックスを作成します
      *
@@ -254,9 +263,7 @@ export declare function transformArr(point: Feature<Point>, tins: Tins, indexedT
 export declare type Tri = Feature<Polygon, PropertiesTri>;
 
 /**
- * 頂点モードの型定義
- * - plain: 通常モード
- * - birdeye: 鳥瞰図モード
+ * Vertex interpolation modes.
  */
 export declare type VertexMode = "plain" | "birdeye";
 
@@ -271,16 +278,14 @@ declare type WeightBuffer = {
 };
 
 /**
- * 両方向の重み付けバッファの型定義
+ * Weight buffers indexed by node id for both directions.
  */
 export declare type WeightBufferBD = {
     [key in BiDirectionKey]?: WeightBuffer;
 };
 
 /**
- * Y軸の向きの型定義
- * - follow: Y軸の向きを維持
- * - invert: Y軸の向きを反転
+ * Y-axis handling directive.
  */
 export declare type YaxisMode = "follow" | "invert";