Maplat Logo

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 / 日本語で読む

Maplat

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/ui@0.11.5/dist/maplat_ui.css">
<script src="https://cdn.jsdelivr.net/npm/@maplat/ui@0.11.5/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.  <a href="https://github.com/code4history/Maplat/graphs/contributors"><img src="https://opencollective.com/maplat/contributors.svg?width=890&button=false" /></a>

Backers

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

Maplat

Install / Use

README

Maplat

Table of Contents

Prerequisites

Installation

Using npm/pnpm

Peer Dependencies

Using CDN in Browser

Usage

Lifecycle

ESM (EcmaScript Modules)

API Documentation

MaplatUi

Static Methods

Constructor

Methods

MaplatAppOption

Data Editor

Development

Setup

Development Server

Build

Test

Contributors

Backers

Sponsors