@maplat/transform/README.md

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

<!-- SECTION 1: Header (badges, title) -->
<h1 align="center">MaplatTransform</h1>

<p align="center">
  <a href="https://github.com/code4history/MaplatTransform/actions/workflows/test.yml"><img src="https://github.com/code4history/MaplatTransform/actions/workflows/test.yml/badge.svg" alt="CI" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@maplat/transform" alt="License" /></a>
</p>

<!-- SECTION 2: Elevator Pitch -->
## About MaplatTransform

MaplatTransform is a JavaScript library that performs coordinate transformation
between two plane coordinate systems using transformation definitions generated
by Maplat. It is the runtime transform engine of the Maplat ecosystem: the
companion [@maplat/tin](https://github.com/code4history/MaplatTin/) package
generates the TIN definitions, and MaplatTransform executes them at runtime.

MaplatTransform is open-source under the Apache License 2.0 (from version 0.5.3).

<!-- SECTION 3: Language switch link -->
**[Read this document in Japanese / 日本語で読む](README.ja.md)**

<!-- SECTION 4: Key Features -->
## Key Features

- Coordinate transformation between two plane coordinate systems using Maplat-generated TIN definitions (forward and backward, topology-preserving)
- V2/V3 compiled format support (V3 adds N-boundary vertices for higher accuracy)
- Multiple coordinate system support: standard orthogonal, Y-axis inverted, bird's-eye view distorted
- Sub-map selection, viewport transformation, and cross-map viewport sync (Processings 2–4)
- State save/restore for transformation states

<!-- SECTION 5: Quick Start -->
## Quick Start

<!-- release-pinned:start -->
> **Current release: `1.0.0`**. This block is the only place in
> this repository that carries a release version (ADR-0012); everything outside it is
> written against the 1.0 release.
> npm: [`@maplat/transform`](https://www.npmjs.com/package/@maplat/transform)
> [![npm](https://img.shields.io/npm/v/@maplat/transform)](https://www.npmjs.com/package/@maplat/transform)

### Install

```bash
# pnpm (recommended)
pnpm add @maplat/transform

# npm
npm install @maplat/transform
```

### Minimal usage

```typescript
import { Transform } from '@maplat/transform';

// Load a compiled transformation definition generated by Maplat
const transform = new Transform();
transform.setCompiled(compiledData);

// 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);
```

> The library may throw errors in strict mode, when a backward transformation
> is attempted while not allowed, or when the data structure is invalid. In
> those cases the transformation definition itself needs to be fixed — use
> [@maplat/tin](https://github.com/code4history/MaplatTin/) to edit the
> definition.

### CDN (jsDelivr)

```html
<script src="https://cdn.jsdelivr.net/npm/@maplat/transform@1.0.0/dist/maplat_transform.umd.js"></script>
```

### MapTransform usage (Processings 2–4)

For sub-map selection, viewport transformation, and cross-map viewport
synchronization, see the
[Wiki Tutorials](https://github.com/code4history/MaplatTransform/wiki/Tutorials).

### API reference

- **API signatures** (release-dependent): see [`docs/api/`](docs/api/)
- **Conceptual guide** (release-independent): see the
  [Wiki API-Reference](https://github.com/code4history/MaplatTransform/wiki/API-Reference)
- **Transform Internals** (runtime notes): see
  [docs/transform-internals.md](docs/transform-internals.md)

### Development

```bash
pnpm test
```
<!-- release-pinned:end -->

<!-- SECTION 6: Prerequisites -->
## Prerequisites

> Derived from the `engines` field in `package.json` (ADR-0012: release-dependent).

- Node.js: `>=20` or later
- pnpm: `>=9` or later (recommended; npm also works)

<!-- SECTION 7: Peer Dependencies -->
<!-- Omitted: MaplatTransform has no OpenLayers peer dependency. -->

<!-- SECTION 8: Ecosystem / Related Repositories -->
## Ecosystem

MaplatTransform is part of the Maplat ecosystem by [Code for History](https://github.com/code4history).
See the full ecosystem map (8 repositories + product/corporate sites):

📖 **Ecosystem Map** — *(the diagram is currently kept in a private planning
repository; the Sister repositories table below is the public substitute)*

### Sister repositories

| Repository | License | npm | Role |
|---|---|---|---|
| [Maplat](https://github.com/code4history/Maplat) | Apache 2.0 | `@maplat/ui` | Main viewer |
| [MaplatCore](https://github.com/code4history/MaplatCore) | Apache 2.0 | `@maplat/core` | Core library |
| [MaplatTin](https://github.com/code4history/MaplatTin) | Apache 2.0 | `@maplat/tin` | TIN conversion |
| [MaplatTransform](https://github.com/code4history/MaplatTransform) | Apache 2.0 | `@maplat/transform` | Coordinate transform |
| [MaplatEditor](https://github.com/code4history/MaplatEditor) | Apache 2.0 | — | Data authoring tool (desktop) |
| [Chuci](https://github.com/code4history/Chuci) | MIT | `@c4h/chuci` | Multimedia swiper & viewer Web Components |
| [Quyuan](https://github.com/code4history/Quyuan) | MIT | `@c4h/quyuan` | GeoJSON template engine + multimedia viewer Web Components |
| [Weiwudi](https://github.com/code4history/Weiwudi) | MIT | `@c4h/weiwudi` | Service Worker for tile cache |

> MaplatEditor is the data authoring tool used to create the maps and POIs
> that the viewers above render. The Maplat ecosystem is end-to-end:
> author with MaplatEditor, serve with any of the viewer libraries.

> **Note**: MaplatTransform executes coordinate transformations only. To create
> or edit transformation definitions, use
> [@maplat/tin](https://github.com/code4history/MaplatTin/).

<!-- SECTION 9: Nayuta links -->
## Links

| Audience | Link | Purpose |
|---|---|---|
| Project info / features / cases | <https://www.maplat.jp/en/> | Product site |
| Sponsor / business inquiry | <https://www.nayuta-inc.co.jp/en/> | Corporate site (Nayuta, Inc.) |

> ADR-0013: Apache-licensed repositories (this one) link to both sites.
> MIT-licensed sister repos (Weiwudi / Quyuan / Chuci) carry no Nayuta link.

<!-- SECTION 10: License -->
## License

Apache License 2.0 — see [LICENSE](LICENSE).

```
Copyright 2019-2026 Kohei Otsuka, Code for History / Nayuta, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

> **Patent notice**: The Maplat coordinate-transform technology is patented
> in Japan (Patent No. 6684776).

> **Past versions**: Versions before 0.5.3 were distributed under the
> Maplat Limited License 1.1. The license restoration to Apache 2.0 takes
> effect from version 1.0.0-rc1 onward. Earlier versions available on npmjs.com
> remain under their original limited-license terms.

<!-- SECTION 11: Contributors / Sponsors -->
## Contributors

- Kohei Otsuka
- Code for History

We welcome your contributions! Feel free to submit
[issues and pull requests](https://github.com/code4history/MaplatTransform/issues).