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

Installation

npm

npm install @maplat/transform

JSR (JavaScript Registry)

# For Deno
deno add @maplat/transform

# For npm/Node.js
npx jsr add @maplat/transform

Deno

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

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

Basic Usage

Node.js/npm

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

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

Development

Running Tests

Node.js

npm test

Deno

deno task test

Running Examples

Deno

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

Deno Support

This library fully supports Deno. See the Deno Usage Guide for detailed instructions on using MaplatTransform with Deno.

License

Maplat Limited License 1.1

Developers

Kohei Otsuka
Code for History

We welcome your contributions! Feel free to submit issues and pull requests.