Maplat is the cool Historical Map/Illustrated Map Viewer API. 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.
npm install @maplat/core
html
`
$3
Install via pnpm (recommended):
`sh
pnpm add @maplat/core
`
Or via npm:
`sh
npm install @maplat/core
`
Peer Dependencies
MaplatCore strictly requires OpenLayers to function. Mapbox GL JS and MapLibre GL JS are optional extensions for vector tile support.
$3
OpenLayers is architecturally required for MaplatCore. You must install it and import its CSS.
pnpm:
`sh
pnpm add ol
`
CDN:
`html
`
$3
Only required if you use Mapbox vector tiles.
pnpm:
`sh
pnpm add mapbox-gl
`
CDN:
`html
`
Note: Mapbox GL JS requires an access token. Provide it via the mapboxToken option.
$3
Only required if you use MapLibre vector tiles.
pnpm:
`sh
pnpm add maplibre-gl
`
CDN:
`html
`
Usage
Lifecycle
- See docs/ui-core-lifecycle.md for lifecycle phases and uiHooks.$3
`html
`
$3
`typescript
import { MaplatApp } from '@maplat/core';
import 'ol/ol.css'; // REQUIRED: OpenLayers CSS
// Optional: Import MapLibre if needed
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
const option = {
maplibregl: maplibregl, // Optional
startFrom: 'gsi',
};
MaplatApp.createObject(option).then((app) => {
console.log('Maplat initialized', app);
});
`
$3
#### Map State & Control
- currentMapInfo(): object
- Get information about the currently active map.
- mapInfo(mapID: string): object
- Get information about a specific map by its ID.
- changeMap(mapID: string, restore?: object): Promise
- Switch to a different map. restore object can optionally set initial position (x, y, zoom, rotation).
- requestUpdateState(data: object): Promise
- Request an update to the map state (position, transparency, etc.).
#### Coordinate System
- clientPointToLngLat(clientX: number, clientY: number): [number, number]
- Convert screen coordinates (pixels relative to viewport) to Longitude/Latitude.
- lngLatToClientPoint(lng: number, lat: number): [number, number]
- Convert Longitude/Latitude to screen coordinates.
#### Markers (Point Data)
- addMarker(data: object, clusterId?: string): void
- Add a marker. data should contain lng, lat, name, desc (description), icon, etc.
- clusterId specifies which layer to add the marker to (e.g., 'main', or specific map layer).
- removeMarker(id: string): void
- Remove a specific marker by its ID (e.g. 'main_1').
- updateMarker(id: string, data: object, overwrite?: boolean): void
- Update an existing marker's data (e.g. move position).
- clearMarker(clusterId?: string): void
- Remove all markers from a specific cluster/layer.
- selectMarker(id: string): void
- Programmatically select (highlight) a marker.
- unselectMarker(): void
- Deselect the currently selected marker.
- getMarker(id: string): object
- Get data for a specific marker.
- setMarker(data: object): void
- Batch add/set markers. Useful for initialization or mass updates.
- showAllMarkers(): void
- Make all markers visible.
- hideAllMarkers(): void
- Hide all markers.
#### Lines & Vectors
- addLine(data: object): void
- Add a line feature. data: { lnglats: [[lng, lat], ...], stroke: { color: '#...', width: 2 } }
- addVector(data: object): void
- Add a polygon/vector feature (GeoJSON compatible).
- setLine(data: object): void / setVector(data: object): void
- Batch set lines/vectors.
- resetLine() / resetVector() / resetMarker()
- Clear and reset basic lines/vectors/markers (often used for default layers).
- clearLine() / clearVector()
- Clear all lines/vectors.
#### POI Layers
Maplat manages markers in "layers".
- addPoiLayer(id: string, data: object): void
- Create a new POI layer. data can define default icons.
- showPoiLayer(id: string): void
- Show a specific layer.
- hidePoiLayer(id: string): void
- Hide a specific layer.
- listPoiLayers(hideOnly?: boolean, nonzero?: boolean): string[]
- Get a list of available layer IDs.
#### GPS & User Position
- handleGPS(enable: boolean): void
- Turn GPS tracking on or off.
- getGPSEnabled(): boolean
- Check if GPS tracking is currently active.
- setGPSMarker(position: object): void
- Manually update the GPS marker position (usually handled automatically if GPS is on).
#### Event Handling
Use app.addEventListener(type, callback) to handle events.
- clickMarker: Fired when a marker is clicked. evt.detail contains marker data.
- clickMap: Fired when the map background is clicked.
- gps_result: Fired when a GPS position update happens.
- gps_error: Fired when GPS fails.
$3
`javascript
MaplatApp.createObject(option).then(function(app){
// Show current map info
console.log(app.currentMapInfo());
// Event Listener
app.addEventListener('clickMarker', function(evt) {
console.log('Marker clicked:', evt.detail);
app.selectMarker(evt.detail.namespaceID);
});
// Add a custom marker
app.addMarker({
lng: 141.1501111,
lat: 39.69994722,
name: "Morioka Castle",
desc: "Historical site in Morioka",
icon: "parts/blue_marker.png"
}, 'main'); // 'main' is the default layer
});
`
Development
$3
`sh
Run linting
pnpm run lint
Run type checking
pnpm run typecheck
Run unit tests
pnpm test
Run E2E tests
pnpm run test:e2e
`
$3
`sh
Build the library
pnpm run build
Build development demo
pnpm run build:demo
Run development server
pnpm run dev
``