Skip to content

Concepts

Jump to bottom
Kohei Otsuka edited this page Jul 24, 2026 · 1 revision

Concepts

Background and theory behind MaplatCore: coordinate transform, base-map pluggability, POI/layer model, and the relationship to the wider Maplat ecosystem.

Table of Contents

What MaplatCore provides

MaplatCore is the core library of the Maplat viewer stack. It exposes the MaplatApp class, which:

  • Loads map and app definition JSON
  • Computes (or loads pre-computed) the nonlinear homeomorphic TIN transform
  • Initializes the OpenLayers map
  • Exposes markers / lines / vectors / POI layers / GPS / event APIs

The end-user-facing viewer Maplat (@maplat/ui) is built on top of MaplatCore and adds the PWA shell, UI components, and the app-loader protocol. MaplatCore is the lower-level library for embedding map rendering with the same transform guarantees into a custom application.

Nonlinear homeomorphic coordinate transform

The defining property of Maplat is that historical maps are overlaid on accurate modern maps without distorting the original image. This is achieved by a TIN (Triangulated Irregular Network) transform that is:

  • Nonlinear — each triangle has its own affine map, so the overall transform can bend smoothly across the image.
  • Homeomorphic — the transform is continuous and has a continuous inverse, so the topology of the original image is preserved. No folding, no tearing.
  • Bidirectional / bijective (in strict mode) — each point on the historical image maps to exactly one point on the modern map and vice versa.

The transform library is maintained as a separate package: @maplat/tin (see MaplatTin Wiki for theory).

Strict and loose modes

State strict_status Behavior
Topology preserved STATUS_STRICT Bidirectional bijection guaranteed
Topology broken, strict mode STATUS_STRICT_ERROR Forward transform only; kinks property holds edge intersections
Topology broken, loose mode STATUS_LOOSE Bidirectional transform possible, but bijection is not guaranteed

This is the core theoretical guarantee that lets Maplat overlay historical maps on accurate modern maps without distorting the original image.

Base-map pluggability (OpenLayers / Mapbox GL JS / MapLibre GL JS)

MaplatCore uses OpenLayers as the rendering engine (required peer dependency). OpenLayers handles raster tile sources and the map viewport.

For vector tiles, MaplatCore supports two optional peer dependencies:

  • mapbox-gl (^1.0.0 || ^2.0.0 || ^3.0.0) — for Mapbox vector tiles. Requires a mapboxToken option.
  • maplibre-gl (^3.0.0 || ^4.0.0) — for MapLibre vector tiles. No token required.

Both are injected via the option object (mapboxgl / maplibregl keys), so the bundler can tree-shake the unused one.

POI and layer model

Maplat manages point data (markers) in layers. The default layer is 'main'. Each layer can have its own default icon and selected-icon. POI layers are independent of base-map sources — they are added on top of any map.

See Tutorials § POI layer management for the API and API-Reference for the conceptual model.

Event model

MaplatCore dispatches events via app.addEventListener(type, callback). The core events are:

  • clickMarker — evt.detail carries the clicked marker's data
  • clickMap — fired when the map background is clicked
  • gps_result — fired when a GPS position update happens
  • gps_error — fired when GPS fails

The event names are stable across releases. Payload schemas may evolve; see docs/api/ for the current shapes.

Relationship to Maplat (@maplat/ui)

Maplat is the end-user viewer application. It uses MaplatCore as its rendering core and adds:

  • PWA shell (manifest, service worker, share, URL state)
  • App-loader protocol (fetches app JSON, manages sources)
  • UI components (map selector, POI list, info balloon, etc.)
  • i18n

If you are building a web app for end users, use @maplat/ui directly. If you need lower-level control over the map lifecycle, use @maplat/core.

Relationship to MaplatTin (@maplat/tin)

MaplatTin is the standalone TIN transform library. MaplatCore uses it internally for coordinate transform. MaplatTin is independent of OpenLayers and can be used in a Node.js context for offline transform computation (e.g. preprocessing pipelines with MaplatTransform).

日本語版はこちら / Read this page in Japanese

See Also

MaplatCore

Language / 言語

Pages / ページ

English

日本語

External / 外部

Clone this wiki locally