Maplat

Maplat is the cool Historical Map/Illustrated Map Viewer.
It can transform each map coordinates with nonlinear but homeomorphic projection and makes possible that the maps can collaborate with GPS/accurate maps, without distorting original maps.
Data editor of this solution is provided as another project, MaplatEditor.
This project won Grand Prize / Educational Effectiveness Prize / Visitors Selection Prize on Geo-Activity Contest 2018 held by Ministry of Land, Infrastructure, Transport and Tourism.

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

Table of Contents

• Maplat
  • Table of Contents
  • Prerequisites
  • Installation
    • Using npm/pnpm
      • Peer Dependencies
    • Using CDN in Browser
  • Usage
    • ESM (EcmaScript Modules)
  • Lifecycle
  • API Documentation
    • MaplatUi
      • Static Methods
      • Constructor
      • Methods
    • MaplatAppOption
  • Data Editor
  • Development
    • Setup
    • Development Server
    • Build
    • Test
  • Contributors
  • Backers
  • Sponsors

Prerequisites

Based on the engines field in package.json:

• Node.js: v20 or v22 (Recommended)
• pnpm: v9.0.0 or higher

Installation

Using npm/pnpm

This project recommends pnpm.

pnpm add @maplat/ui

Or if you use npm:

npm install @maplat/ui

Peer Dependencies

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

• ol (OpenLayers): v9.0.0 or v10.0.0+

pnpm add ol

If 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
• maplibre-gl: ^3.0.0 || ^4.0.0

Using CDN in Browser

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.

Usage

Lifecycle

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

ESM (EcmaScript Modules)

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
});

API Documentation

MaplatUi

The main class.

Static Methods

• createObject(option: MaplatAppOption): Promise<MaplatUi> Creates a MaplatUi instance and returns a Promise that resolves when initialization is complete. This is the recommended way to create an instance.

Constructor

• new MaplatUi(option: MaplatAppOption) Creates an instance but does not wait for initialization. You should wait for the waitReady property.

Methods

• remove(): Destroys the application and releases resources.
• updateUrl(): Updates the URL to reflect current state (if stateUrl is enabled).

MaplatAppOption

Key properties of the option object passed during initialization.

| Property | Type | Description | | ------------------ | ------------------- | ----------------------------------- | | appid | string | Application ID (Required) | | pwaManifest | boolean \| string | Enable PWA manifest or specify path | | pwaWorker | string | Service Worker path | | overlay | boolean | Enable overlay mode | | enableHideMarker | boolean | Enable marker hiding | | enableMarkerList | boolean | Enable marker list | | enableBorder | boolean | Enable border display | | stateUrl | boolean | Enable URL state management | | enableShare | boolean | Enable share feature | | mapboxToken | string | Access token for Mapbox |

Data Editor

Please use MaplatEditor for data creation.

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)

Contributors

This project exists thanks to all the people who contribute.

Backers

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

Sponsors

Maplat is supported by

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

Copyright (c) 2024-2026 Code for History