MaplatTin is a JavaScript library that defines and executes homeomorphic conversion between two plane coordinate systems based on control points. It guarantees a nonlinear but topology-preserving (homeomorphic) bidirectional mapping, which is the core property that lets the Maplat viewer overlay historical maps on accurate modern maps without distorting the original images.
MaplatTin is open-source under the Apache License 2.0 (from version 0.14.2).
Read this document in Japanese / 日本語で読む
- 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 — specify constrained edges for more accurate transform
- State Management — save and restore transformation definitions
- Open-source (Apache 2.0 from version 0.14.2) — part of the Maplat ecosystem
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/tin
# pnpm (recommended)
pnpm add @maplat/tin
# npm
npm install @maplat/tinimport Tin from '@maplat/tin';
// 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,
});
// Set control points: Array of [source, target] coordinates
tin.setPoints([
[[100, 100], [200, 200]],
[[200, 200], [400, 400]],
[[150, 150], [320, 350]],
[[200, 100], [420, 220]],
]);
// Initialize the TIN network
tin.updateTin();
// Forward transform: source to target
const transformed = tin.transform([160, 160], false);
// Backward transform: target to source
const restored = tin.transform(transformed, true);<!-- MaplatTin (UMD) -->
<script src="https://cdn.jsdelivr.net/npm/@maplat/tin@1.0.0/dist/maplat_tin.umd.js"></script>
<script>
const tin = new maplatTin.default({ wh: [500, 500] });
</script>Or using ES modules:
<script type="module">
import Tin from 'https://cdn.jsdelivr.net/npm/@maplat/tin@1.0.0/dist/maplat_tin.js';
const tin = new Tin({ wh: [500, 500] });
</script>Note: Make sure to use the latest compatible versions.
- API signatures (release-dependent): see
docs/api/ - Conceptual guide (release-independent): see the Wiki API-Reference
Clone the repository and install dependencies.
git clone https://github.com/code4history/MaplatTin.git
cd MaplatTin
pnpm installStart the development server with hot reload.
pnpm devpnpm build # Build library (dist/)
pnpm build:demo # Build demo site (dist-demo/)pnpm test # Run unit tests (Vitest)
pnpm typecheck # Run type checks (TypeScript)
pnpm lint # Run linter and formatter (ESLint/Prettier)Test coverage:
tests/edgebound/— internal EdgeBound constraint engine tests (455 tests)tests/tin.test.ts— TIN transformation tests with real map datatests/transform.test.ts— coordinate transformation tests
Derived from the
enginesfield inpackage.json(ADR-0012: release-dependent).
- Node.js:
>=20.0.0(LTS tested via GitHub Actions) - pnpm:
>=9.0.0(required;package.jsonenforces pnpm)
MaplatTin is part of the Maplat ecosystem by Code for History. 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)
| Repository | License | npm | Role |
|---|---|---|---|
| Maplat | Apache 2.0 | @maplat/ui |
Main viewer |
| MaplatCore | Apache 2.0 | @maplat/core |
Core library |
| MaplatTin | Apache 2.0 | @maplat/tin |
TIN conversion |
| MaplatTransform | Apache 2.0 | @maplat/transform |
Coordinate transform |
| MaplatEditor | Apache 2.0 | — | Data authoring tool (desktop) |
| Chuci | MIT | @c4h/chuci |
Multimedia swiper & viewer Web Components |
| Quyuan | MIT | @c4h/quyuan |
GeoJSON template engine + multimedia viewer Web Components |
| 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.
| 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.
Apache License 2.0 — see 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.14.2 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.
- Kohei Otsuka
- Code for History
We welcome your contributions! Feel free to submit issues and pull requests.