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 project.

日本語のREADMEはこちら

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)

pnpm add @maplat/transform

npm

npm install @maplat/transform

Browser

<script src="https://unpkg.com/@maplat/transform/dist/maplat_transform.umd.js"></script>

Basic Usage

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 to modify transformation definitions.

API Reference

Transform Class

The main class for coordinate transformation.

Constructor

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

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 - Runtime notes on how Transform class reconstructs state and performs coordinate lookups

Development

Running Tests

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 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.