@allmaps/maplibre

Allmaps plugin for MapLibre. 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.

How it works

This plugin creates a new class WarpedMapLayer which extends and behaves like a MapLibre Layer. You can add one or multiple Georeference Annotations (or Georeference Annotation Pages) to a WarpedMapLayer, and add the WarpedMapLayer to your MapLibre map. This will render all Georeferenced Maps contained in the annotation (pages) 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 module.

Install with npm:

npm install @allmaps/maplibre

And load using:

import { WarpedMapLayer } from '@allmaps/maplibre'

You can build this package using

pnpm run build

As an alternative to loading using import, ESM and UMD bundled versions of the code are also provided under /dist/bundled (once the code is built). These are also published online, so can load them directly in a HTML script tag using a CDN.

<script src="https://cdn.jsdelivr.net/npm/@allmaps/maplibre/dist/bundled/allmaps-maplibre-4.0.umd.js"></script>

When loading as bundled code, the package's functions are available under the Allmaps global variable:

// ... (see 'Usage' below)
const warpedMapLayer = new Allmaps.WarpedMapLayer()
// ...

Usage

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

Loading an annotation

Creating a layer adding it to map looks like this:

import { WarpedMapLayer } from '@allmaps/maplibre'

// MapLibre map with base layer
const map = new maplibregl.Map({
  container: 'map',
  style:
    'https://api.maptiler.com/maps/streets/style.json?key=get_your_own_OpIi9ZULNHzrESv6T2vL',
  center: [-71.0599, 42.3589],
  zoom: 13,
  pitchWithRotate: false, // Disable pitch on your map
  preserveDrawingBuffer: true
})

const warpedMapLayer = new WarpedMapLayer()

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

WarpedMapLayer is implemented using MapLibre's CustomLayerInterface, which allows it to draw directly into the map's WebGL context using the map's camera. Although it can be added to a map (possibly in between other layers) like usual using map.addLayer(), there are some differences to a normal layer 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 can't be styles using the MapLibre Style Spec.
• 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 value to their constructor: const warpedMapLayerWithUniqueId = new WarpedMapLayer('my-unique-id')
• WarpedMapLayer does not support pitching, so disable it on your map. Enabling antialiasing on your map will create the WebGL context with MSAA antialiasing, so custom layers like the WarpedMapLayer are antialiased, which may improve the visual result.

A Georeference Annotation can be added to a WarpedMapLayer using the functions addGeoreferenceAnnotation() or addGeoreferenceAnnotationByUrl(), which will render it as part of the WarpedMapLayer on the OpenLayers map. Here's an example of the first using fetch() and then().

const annotationUrl =
  'https://annotations.allmaps.org/images/813b0579711371e2@2c1d7e89d8c309e8'

map.on('load', async () => {
  map.addLayer(warpedMapLayer)

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

And here's an example of the later inside the nameless call-back function of the 'load' event.

map.on('load', async () => {
  map.addLayer(warpedMapLayer)

  await warpedMapLayer.addGeoreferenceAnnotationByUrl(annotationUrl)
})

Example

Once this package is published, a CodePen example will be added here.

Events

The following events are emitted to inform you of the state of the WarpedMapLayer.

You can listen to them in the typical MapLibre way. Here's an example:

map.on(
  'warpedmapadded',
  (event) => {
    console.log(event.mapId, warpedMapLayer.getTotalBounds())
  },
  map
)

Some of the functions specified in the API only make sense once a warped map is loaded into the WarpedMapLayer. You can use such listeners to make sure function are run e.g. only after a warped map has been added.

What is a 'map'?

Both MapLibre and Allmaps have a concept named a 'map'.

A MapLibre map is an instance of the MapLibre Map Class, the central class of the MapLibre API, used to create a map on a page and manipulate it.

In Allmaps there are multiple classes describing maps, one for each phase a map takes through the Allmaps rendering pipeline:

• When a Georeference Annotation is parsed, an instance of the Georeferenced Map class is created from it.
• When this map is loaded into an application for rendering, an instance of the Warped Map class is created from it.
• (Inside the WebGL2 rendering code, there's also a WebGL2WarpedMap)

All these map phases originating from the same Georeference Annotation have the same unique mapId property. This string value is used though-out Allmaps (and in the API below) to identify a map. It is returned after adding a georeference annotation to a warpedMapLayer, so you can use it later to call functions on a specific map.

API

Table of Contents

• WarpedMapLayer
  • onAdd
  • onRemove
  • addGeoreferenceAnnotation
  • removeGeoreferenceAnnotation
  • addGeoreferenceAnnotationByUrl
  • removeGeoreferenceAnnotationByUrl
  • addGeoreferencedMap
  • removeGeoreferencedMap
  • getWarpedMapList
  • getWarpedMap
  • showMap
  • showMaps
  • hideMap
  • hideMaps
  • isMapVisible
  • setMapResourceMask
  • setMapsTransformationType
  • getTotalBbox
  • getTotalProjectedBbox
  • bringMapsToFront
  • sendMapsToBack
  • bringMapsForward
  • sendMapsBackward
  • getMapZIndex
  • setImageInfoCache
  • getOpacity
  • setOpacity
  • resetOpacity
  • getMapOpacity
  • setMapOpacity
  • resetMapOpacity
  • setSaturation
  • resetSaturation
  • setMapSaturation
  • resetMapSaturation
  • setRemoveColor
  • resetRemoveColor
  • setMapRemoveColor
  • resetMapRemoveColor
  • setColorize
  • resetColorize
  • setMapColorize
  • resetMapColorize
  • preparerender
  • render

WarpedMapLayer

WarpedMapLayer class.

This class renders georeferenced maps of a IIIF Georeference Annotation on a MapLibre map. WarpedMapLayer is implemented using MapLibre's CustomLayerInterface.

onAdd

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

Parameters

• map Map The Map this custom layer was just added to.
• gl WebGL2RenderingContext The gl context for the map.

onRemove

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

addGeoreferenceAnnotation

Adds a Georeference Annotation.

Parameters

• annotation any Georeference Annotation

Returns Promise<Array<(string | Error)>> the map IDs of the maps that were added, or an error per map

removeGeoreferenceAnnotation

Removes a Georeference Annotation.

Parameters

• annotation any Georeference Annotation

Returns Promise<Array<(string | Error)>> the map IDs of the maps that were removed, or an error per map

addGeoreferenceAnnotationByUrl

Adds a Georeference Annotation by URL.

Parameters

• annotationUrl string Georeference Annotation

Returns Promise<Array<(string | Error)>> the map IDs of the maps that were added, or an error per map

removeGeoreferenceAnnotationByUrl

Removes a Georeference Annotation by URL.

Parameters

• annotationUrl string Georeference Annotation

Returns Promise<Array<(string | Error)>> the map IDs of the maps that were removed, or an error per map

addGeoreferencedMap

Adds a Georeferenced map.

Parameters

• georeferencedMap unknown Georeferenced map

Returns Promise<(string | Error)> the map ID of the map that was added, or an error

removeGeoreferencedMap

Removes a Georeferenced map.

Parameters

• georeferencedMap unknown Georeferenced map

Returns Promise<(string | Error)> the map ID of the map that was remvoed, or an error

getWarpedMapList

Returns the WarpedMapList object that contains a list of the warped maps of all loaded maps

Returns WarpedMapList the warped map list

getWarpedMap

Returns a single map's warped map

Parameters

• mapId string ID of the map

Returns (WarpedMap | undefined) the warped map

showMap

Make a single map visible

Parameters

• mapId string ID of the map

showMaps

Make multiple maps visible

Parameters

• mapIds Iterable<string> IDs of the maps

hideMap

Make a single map invisible

Parameters

• mapId string ID of the map

hideMaps

Make multiple maps invisible

Parameters

• mapIds Iterable<string> IDs of the maps

isMapVisible

Returns the visibility of a single map

Parameters

• mapId

Returns (boolean | undefined) whether the map is visible

setMapResourceMask

Sets the resource mask of a single map

Parameters

• mapId string ID of the map
• resourceMask Ring new resource mask

setMapsTransformationType

Sets the transformation type of multiple maps

Parameters

• mapIds Iterable<string> IDs of the maps
• transformation TransformationType new transformation type

getTotalBbox

Return the Bbox of all visible maps in the layer (inside or outside of the Viewport), in lon lat coordinates.

Returns (Bbox | undefined) bbox of all warped maps

getTotalProjectedBbox

Return the Bbox of all visible maps in the layer (inside or outside of the Viewport), in projected coordinates.

Returns (Bbox | undefined) bbox of all warped maps

bringMapsToFront

Bring maps to front

Parameters

• mapIds Iterable<string> IDs of the maps

sendMapsToBack

Send maps to back

Parameters

• mapIds Iterable<string> IDs of the maps

bringMapsForward

Bring maps forward

Parameters

• mapIds Iterable<string> IDs of the maps

sendMapsBackward

Send maps backward

Parameters

• mapIds Iterable<string> IDs of the maps

getMapZIndex

Returns the z-index of a single map

Parameters

• mapId string ID of the warped map

Returns (number | undefined) z-index of the warped map

setImageInfoCache

Sets the image info Cache of the warpedMapList, informing it's warped maps about possibly cached imageInfo.

Parameters

• cache Cache the image info cache

getOpacity

Gets the opacity of the layer

Returns (number | undefined) opacity of the map

setOpacity

Sets the opacity of the layer

Parameters

• opacity number opacity between 0 and 1, where 0 is fully transparent and 1 is fully opaque

resetOpacity

Resets the opacity of the layer to fully opaque

getMapOpacity

Gets the opacity of a single map

Parameters

• mapId string ID of the map

Returns (number | undefined) opacity of the map

setMapOpacity

Sets the opacity of a single map

Parameters

• mapId string ID of the map
• opacity number opacity between 0 and 1, where 0 is fully transparent and 1 is fully opaque

resetMapOpacity

Resets the opacity of a single map to fully opaque

Parameters

• mapId string ID of the map

setSaturation

Sets the saturation of a single map

Parameters

• saturation number saturation between 0 and 1, where 0 is grayscale and 1 are the original colors

resetSaturation

Resets the saturation of a single map to the original colors

setMapSaturation

Sets the saturation of a single map

Parameters

• mapId string ID of the map
• saturation number saturation between 0 and 1, where 0 is grayscale and 1 are the original colors

resetMapSaturation

Resets the saturation of a single map to the original colors

Parameters

• mapId string ID of the map

setRemoveColor

Removes a color from all maps

Parameters

• options Object remove color options

  • options.hexColor string? hex color to remove
  • options.threshold number? threshold between 0 and 1
  • options.hardness number? hardness between 0 and 1

resetRemoveColor

Resets the color removal for all maps

setMapRemoveColor

Removes a color from a single map

Parameters

• mapId string ID of the map

• options Object remove color options

  • options.hexColor string? hex color to remove
  • options.threshold number? threshold between 0 and 1
  • options.hardness number? hardness between 0 and 1

resetMapRemoveColor

Resets the color for a single map

Parameters

• mapId string ID of the map

setColorize

Sets the colorization for all maps

Parameters

• hexColor string desired hex color

resetColorize

Resets the colorization for all maps

setMapColorize

Sets the colorization for a single mapID of the map

Parameters

• mapId string ID of the map
• hexColor string desired hex color

resetMapColorize

Resets the colorization of a single map

Parameters

• mapId string ID of the map

preparerender

Prepare rendering the layer.

render

Render the layer.