@allmaps/maplibre

Allmaps plugin for MapLibre GL. This plugin allows displaying georeferenced IIIF images on a MapLibre map. The plugin works by loading Georeference Annotations and uses WebGL to transform images from a IIIF image server to overlay them on their correct geographical position. See allmaps.org for more information.

Examples:

• Observable notebook
• Observable notebook

How it works

This plugin creates a new class WarpedMapLayer which extends MapLibre's CustomLayerInterface. You can add one or multiple Georeference Annotations (or AnnotationPages with multiple Georeference Annotations) to a WarpedMapLayer, and add the WarpedMapLayer to your MapLibre map. This will render all georeferenced maps contained in the Georeference Annotation on your MapLibre map.

To understand what happens under the hood for each georeferenced map, see the @allmaps/render package.

Installation

This package works in browsers and in Node.js as an ESM or an UMD module.

Install with pnpm:

pnpm install @allmaps/maplibre

You can optionally build this package locally by running:

pnpm run build

Usage

Built for MapLibre 4.0, but should work with earlier versions as well.

Loading a Georeference Annotation

Creating a WarpedMapLayer and adding it to a map looks like this:

import { WarpedMapLayer } from '@allmaps/maplibre'

// MapLibre map with base layer
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
  center: [-73.9337, 40.8011],
  zoom: 11.5,
  // Pitch is currently not supported by the Allmaps plugin for MapLibre
  maxPitch: 0
})

const annotationUrl = 'https://annotations.allmaps.org/images/d180902cb93d5bf2'
const warpedMapLayer = new WarpedMapLayer()

map.on('load', () => {
  map.addLayer(warpedMapLayer)
  warpedMapLayer.addGeoreferenceAnnotationByUrl(annotationUrl)
})

WarpedMapLayer is implemented using MapLibre's CustomLayerInterface. It can be added to a map like any other MapLibre layer, but there are some things to take into account:

• WarpedMapLayer does not make use of a Source (although that could be implemented in the future, similar to @allmaps/openlayers).
• WarpedMapLayer currently does not support pitch, so disable it on your map.
• Just like other MapLibre layers, a WarpedMapLayer must have a unique id. By default, the id has the value warped-map-layer. When adding multiple WarpedMapLayers to your map, pass a unique id to their constructor:
• WarpedMapLayer does not make use of a Source (although that could be implemented in the future, similar to @allmaps/openlayers).
• WarpedMapLayer currently does not support pitch, so disable it on your map.
• Just like other MapLibre layers, a WarpedMapLayer must have a unique id. By default, the id has the value warped-map-layer. When adding multiple WarpedMapLayers to your map, pass a unique id to their constructor:

const warpedMapLayerWithUniqueId = new WarpedMapLayer({layerId: 'my-unique-id'})

A Georeference Annotation can be added to a WarpedMapLayer using the addGeoreferenceAnnotation and addGeoreferenceAnnotationByUrl functions:

fetch(annotationUrl)
  .then((response) => response.json())
  .then((annotation) => warpedMapLayer.addGeoreferenceAnnotation(annotation))

Or:

await warpedMapLayer.addGeoreferenceAnnotationByUrl(annotationUrl)

WarpedMapLayer API: Options and Events

See the @allmaps/warpedmaplayer package for the API documentation of the methods inherited from the WarpedMapLayer class (shared by all Allmaps plugins). It includes a list of all options that can be set on instances of the class and all events which are passed to the native map instance hosting the layer instance.

You can set options on the entire layer, or on a specific map on the layer (overwriting layer options):

warpedMapLayer.setLayerOptions({ visible: true })
warpedMapLayer.setMapOptions(mapId, { visible: true })

You can listen to events in the typical way:

map.on('warpedmapadded', (event) => {
  console.log(event.mapIds)
})

License

MIT

API

MapLibreWarpedMapLayerOptions

Type

SpecificMapLibreWarpedMapLayerOptions & Partial<WebGL2RenderOptions>

new WarpedMapEvent(type, data)

Parameters

• type (WarpedMapEventType)
• data? (Partial<WarpedMapEventData> | undefined)

Returns

WarpedMapEvent.

Extends

• Event

WarpedMapEvent#data?

Type

{
  mapIds?: Array<string> | undefined
  tileUrl?: string | undefined
  optionKeys?: Array<string> | undefined
  spritesInfo?: SpritesInfo | undefined
}

new WarpedMapLayer(options)

Creates a WarpedMapLayer instance

Parameters

• options? (Partial<MapLibreWarpedMapLayerOptions> | undefined)
  • options

Returns

WarpedMapLayer.

Extends

• BaseWarpedMapLayer
• CustomLayerInterface

WarpedMapLayer#getBounds()

Get the bounding box of all maps as a MapLibre LngLatBoundsLike object

This is the default MapLibre getBounds() function

Result is in longitude/latitude EPSG:4326 coordinates.

Parameters

There are no parameters.

Returns

bounding box of all warped maps (LngLatBoundsLike | undefined).

WarpedMapLayer#id

Type

string

WarpedMapLayer#map?

Type

MaplibreMap

WarpedMapLayer#nativePassWarpedMapEvent(event)

Pass events

Parameters

• event (Event)

Returns

void.

WarpedMapLayer#nativeUpdate()

Trigger the native update function of the map

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#onAdd(map, gl)

Method called when the layer has been added to the Map.

Parameters

• map (MaplibreMap)
  • The Map this custom layer was just added to.
• gl (WebGL2RenderingContext)
  • The WebGL 2 context for the map.

Returns

void.

WarpedMapLayer#onRemove()

Method called when the layer has been removed from the Map.

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#render()

Render the layer.

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#renderingMode

Type

'2d'

WarpedMapLayer#type

Type

'custom'