@maplat/transform/README.md

A JavaScript library that performs coordinate transformation between two plane coordinate systems using transformation definitions generated by Maplat.

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