Maplat Tin

A JavaScript library that defines and executes homeomorphic conversion between two plane coordinate systems based on control points.
This is part of the Maplat project.

日本語のREADMEはこちら

Key Features

• Generate Transformation Definitions: Create coordinate transformation definitions based on control points and edge constraints
• Bidirectional Coordinate Transformation: Convert coordinates between two planes in both directions
• Topology Preservation: Maintains homeomorphic properties during transformation
• Flexible Configuration:
  • Vertex handling modes (normal/bird's-eye view)
  • Topology check modes (strict/auto/loose)
  • Y-axis direction control
• Edge Constraints: Ability to specify constrained edges for more accurate transformation
• State Management: Save and restore transformation definitions

Installation

npm

# Install the main package
npm install @maplat/tin

# Install required dependency
npm install delaunator

Browser

<!-- Required dependency -->
<script src="https://unpkg.com/delaunator/delaunator.min.js"></script>

<!-- Maplat Tin -->
<script src="https://unpkg.com/@maplat/tin/dist/maplat_tin.umd.js"></script>

Basic Usage

// Create a new instance with basic configuration
const tin = new Tin({
    wh: [500, 500],          // Width and height of the source plane
    yaxisMode: Tin.YAXIS_FOLLOW  // Y-axis direction handling
});

// Set control points: Array of [source, target] coordinates
tin.setPoints([
    [[100,100], [200, 200]], // Point 1
    [[200,200], [400, 400]], // Point 2
    [[150,150], [320, 350]], // Point 3
    [[200,100], [420, 220]]  // Point 4
]);

// Initialize the TIN network
tin.updateTin();

// Check topology status
if (tin.strict_status === Tin.STATUS_STRICT) {
    console.log('Topology OK: Roundtrip transform is guaranteed');
} else if (tin.strict_status === Tin.STATUS_LOOSE) {
    console.log('Topology warning: Roundtrip transform is not guaranteed');
}

// Forward transform: source to target
const transformed = tin.transform([160, 160], false);

// Backward transform: target to source
const restored = tin.transform(transformed, true);

Configuration

Constructor Options

Option	Type	Description	Default
bounds	Position[]	Boundary polygon vertices	-
wh	number[]	Width and height [w, h]	-
vertexMode	"plain"｜"birdeye"	Vertex handling mode	"plain"
strictMode	"strict"｜"auto"｜"loose"	Topology check mode	"auto"
yaxisMode	"follow"｜"invert"	Y-axis direction	"invert"
importance	number	Map importance	0
priority	number	Map priority	0

Either bounds or wh must be specified.

Methods

Method	Description
setPoints(points)	Set control points
setEdges(edges)	Set constrained edges
updateTin()	Initialize/update TIN network
transform(coords, inverse)	Execute coordinate transformation
getCompiled()	Get serializable state
setCompiled(state)	Restore from serialized state

Error Handling

The library may throw errors in the following cases:

• "TOO LINEAR1","TOO LINEAR2": Control points are too linear
• "SOME POINTS OUTSIDE": Points outside boundary
• Custom error when attempting backward transformation in a disallowed state

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.