MaplatCore is the core library of the Maplat Historical Map / Illustrated Map Viewer. It transforms each map's coordinates with a nonlinear but homeomorphic projection, so maps can collaborate with GPS and accurate maps without distorting the original map image. The end-user viewer built on top of it is Maplat; the data authoring tool is MaplatEditor.
MaplatCore is open-source under the Apache License 2.0 (from version 0.13.2).
Read this document in Japanese / 日本語で読む
- Historical map / illustrated map viewer API 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)
- Event-driven POI / line / layer management
- Open-source (Apache 2.0 from version 0.13.2) — part of the Maplat ecosystem
Release-dependent information (ADR-0012). The version
0.13.2below is the current release; update it on each new release.
# pnpm (recommended)
pnpm add @maplat/core
# npm
npm install @maplat/coreimport { MaplatApp } from '@maplat/core';
import 'ol/ol.css'; // REQUIRED: OpenLayers CSS
const option = {
startFrom: 'gsi',
};
MaplatApp.createObject(option).then((app) => {
console.log('Maplat initialized', app);
});For usage directly in the browser without a bundler, you must load OpenLayers before loading MaplatCore.
<!-- OpenLayers -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10/ol.css">
<script src="https://cdn.jsdelivr.net/npm/ol@10/dist/ol.js"></script>
<!-- MaplatCore -->
<script src="https://cdn.jsdelivr.net/npm/@maplat/core@0.13.2/dist/maplat_core.umd.js"></script>
<div id="map_div"></div>
<script>
var option = {
startFrom: 'gsi',
div: 'map_div',
};
MaplatApp.createObject(option).then(function (app) {
console.log('Maplat initialized', app);
});
</script>Note: Make sure to use the latest compatible versions.
- See docs/ui-core-lifecycle.md for lifecycle
phases and uiHooks (this document lives in the Maplat viewer repository; the
lifecycle is shared with
@maplat/ui).
- 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/MaplatCore.git
cd MaplatCore
pnpm installStart the development server with hot reload.
pnpm devpnpm build # Build npm package (dist/)
pnpm build:demo # Build demo application (dist-demo/)pnpm test # Run unit tests (Vitest)
pnpm typecheck # Run type checks (TypeScript)
pnpm lint # Run linter and formatter (ESLint/Prettier)
pnpm run test:e2e # Run E2E tests (Playwright)Derived from the
enginesfield inpackage.json(ADR-0012: release-dependent).
- Node.js: v20 or v22 (LTS tested via GitHub Actions)
- pnpm:
>=9.0.0(required;package.jsonenforces pnpm)
MaplatCore depends on the following libraries as peer dependencies. You must install them manually.
- OpenLayers (
ol) —^9.0.0 || ^10.0.0(required; peer dependency of MaplatCore and Maplat@maplat/ui)
pnpm add olIf you use Vector Tiles, you may also need Mapbox GL JS or MapLibre GL JS:
mapbox-gl:^1.0.0 || ^2.0.0 || ^3.0.0(optional)maplibre-gl:^3.0.0 || ^4.0.0(optional)
MaplatCore 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) |
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.13.2 were distributed under the Maplat Limited License 1.1. The license restoration to Apache 2.0 takes effect from version 0.13.2 onward. Earlier versions available on npmjs.com remain under their original limited-license terms.