Maplat

About Maplat

Maplat is the cool Historical Map / Illustrated Map Viewer. It can transform each map's coordinates with a nonlinear but homeomorphic projection, which lets the maps collaborate with GPS and accurate maps without distorting the original map image. The companion data editor is provided as another project, MaplatEditor. This project won the Grand Prize / Educational Effectiveness Prize / Visitors Selection Prize on the Geo-Activity Contest 2018 held by the Ministry of Land, Infrastructure, Transport and Tourism.

Maplat is open-source under the Apache License 2.0 (from version 0.12.2).

Read this document in Japanese / 日本語で読む

Key Features

• Historical map / illustrated map viewer with nonlinear but homeomorphic coordinate transformation
• GPS / accurate map collaboration without distorting the original map image
• Pluggable base maps (OpenLayers-based; optional Mapbox GL JS / MapLibre GL JS for vector tiles)
• PWA-ready application shell (manifest, Service Worker, share, URL state)
• Viewer UI available in 11 languages: English, Japanese, German, Spanish, French, Indonesian, Korean, Thai, Vietnamese, Chinese (Simplified), and Chinese (Traditional)
• Open-source (Apache 2.0 from version 0.12.2) with a companion desktop editor (MaplatEditor)

Quick Start

Current release: 1.2.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/ui

Install

# pnpm (recommended)
pnpm add @maplat/ui

# npm
npm install @maplat/ui

Minimal usage

import { MaplatUi } from '@maplat/ui';
import '@maplat/ui/dist/maplat_ui.css'; // Import styles

const option = {
  appid: 'myMark',
  // ...
};

MaplatUi.createObject(option).then(app => {
  // Application initialized
});

CDN (jsDelivr)

For usage directly in the browser without a bundler, you must load OpenLayers before loading Maplat UI. Maplat Core is bundled, so you do not need to load it separately.

<!-- OpenLayers -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10/ol.min.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10/dist/ol.min.js"></script>

<!-- Maplat UI -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@maplat/[email protected]/dist/maplat_ui.css">
<script src="https://cdn.jsdelivr.net/npm/@maplat/[email protected]/dist/maplat_ui.umd.js"></script>

<div id="map_div"></div>
<script>
  var appOption = {
    appid: "tm",
    // ... options
  };
  MaplatUi.createObject(appOption).then(function(app) {
    console.log("Maplat initialized");
  });
</script>

Note: Make sure to use the latest compatible versions.

POI specification (setting.pois)

Maplat UI passes the pois field of an app/map setting straight through to MaplatApp.createObject, so every form accepted by MaplatCore is accepted here unchanged. The common ways to point at POI data are:

• URL string — "pois/landmarks.geojson", fetched at initialization
• Map-embedded POI — an inline FeatureCollection written directly in the setting
• Layer ref (wrapper) — { layer: <URL|FeatureCollection>, hide?, title?, icon?, selectedIcon? }, which references a layer and overrides only its presentation for this app without editing the referenced file

The full list of accepted forms, the override precedence, and the rule for unknown keys are documented once in MaplatCore; see POI specification (setting.pois) in the MaplatCore README.

Lifecycle

• See docs/ui-core-lifecycle.md for lifecycle phases and uiHooks.

API reference

• API signatures (release-dependent): see docs/api/
• Conceptual guide (release-independent): see the Wiki API-Reference

Development

Setup

Clone the repository and install dependencies.

git clone https://github.com/code4history/Maplat.git
cd Maplat
pnpm install

Development Server

Start the development server with hot reload.

pnpm dev

Access http://localhost:5173/ in your browser.

Build

pnpm build        # Build npm package (dist/)
pnpm build:demo   # Build demo application (dist-demo/)

Test

pnpm test         # Run tests (Vitest)
pnpm typecheck    # Run type checks (TypeScript)
pnpm lint         # Run linter and formatter (ESLint/Prettier)

Prerequisites

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

• Node.js: v20 or v22 (LTS tested via GitHub Actions)
• pnpm: >=9.0.0 (required; package.json enforces pnpm)

Peer Dependencies

Maplat UI depends on the following libraries as peer dependencies. You must install them manually.

• OpenLayers (ol) — ^9.0.0 || ^10.0.0 (peer dependency of Maplat @maplat/ui and MaplatCore @maplat/core)

pnpm add ol

If you use Vector Tiles, you may also need Mapbox GL JS or MapLibre GL JS:

• mapbox-gl: ^2.0.0 || ^3.0.0
• maplibre-gl: ^5.0.0 || ^6.0.0

Ecosystem

Maplat 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)

Sister repositories

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.

Links

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

License

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.12.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.

Contributors

This project exists thanks to all the people who contribute.

Sponsors

Maplat is supported by

Thank you to all our backers! 🙏 [Become a backer]

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]