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:
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.
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 build this package locally by running:
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 the bundled package, its classes are available under the Allmaps
global variable:
const warpedMapLayer = new Allmaps.WarpedMapLayer()
Built for MapLibre 4.0, but should work with earlier versions as well.
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,
// This is needed to improve rendering
// Future versions of the plugin might not need this
preserveDrawingBuffer: true
})
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, theid
has the valuewarped-map-layer
. When adding multiple WarpedMapLayers to your map, pass a uniqueid
to their constructor:
const warpedMapLayerWithUniqueId = new WarpedMapLayer('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)
The following events are emitted to inform you of the state of the WarpedMapLayer
.
Description | Type | Data |
---|---|---|
A warped map has been added to the warped map list | warpedmapadded |
mapId: string |
A warped map has been removed from the warped map list | warpedmapremoved |
mapId: string |
A warped map enters the viewport | warpedmapenter |
mapId: string |
A warped map leaves the viewport | warpedmapleave |
mapId: string |
The visibility of some warpedMaps has changed | visibilitychanged |
mapIds: string[] |
The cache loaded a first tile of a map | firstmaptileloaded |
{mapId: string, tileUrl: string} |
All tiles requested for the current viewport have been loaded | allrequestedtilesloaded |
You can listen to them in the typical MapLibre way. Here's an example:
warpedMapLayer.on('warpedmapadded', (event) => {
console.log(event.mapId, warpedMapLayer.getBounds())
})
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.
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 package, the
WebGL2WarpedMap
class is used to render the map.
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.
-
WarpedMapLayer
- onAdd
- onRemove
- addGeoreferenceAnnotation
- removeGeoreferenceAnnotation
- addGeoreferenceAnnotationByUrl
- removeGeoreferenceAnnotationByUrl
- addGeoreferencedMap
- removeGeoreferencedMap
- getWarpedMapList
- getWarpedMap
- showMap
- showMaps
- hideMap
- hideMaps
- isMapVisible
- setMapResourceMask
- setMapsTransformationType
- setMapsDistortionMeasure
- getBounds
- bringMapsToFront
- sendMapsToBack
- bringMapsForward
- sendMapsBackward
- getMapZIndex
- setImageInformations
- getOpacity
- setOpacity
- resetOpacity
- getMapOpacity
- setMapOpacity
- resetMapOpacity
- setSaturation
- resetSaturation
- setMapSaturation
- resetMapSaturation
- setRemoveColor
- resetRemoveColor
- setMapRemoveColor
- resetMapRemoveColor
- setColorize
- resetColorize
- setMapColorize
- resetMapColorize
- clear
- preparerender
- render
WarpedMapLayer class.
This class renders maps from a IIIF Georeference Annotation on a MapLibre map. WarpedMapLayer is implemented using MapLibre's CustomLayerInterface.
Method called when the layer has been added to the Map.
-
map
Map The Map this custom layer was just added to. -
gl
WebGL2RenderingContext The WebGL 2 context for the map.
Method called when the layer has been removed from the Map.
Adds a Georeference Annotation.
-
annotation
any Georeference Annotation
Returns Promise<Array<(string | Error)>> the map IDs of the maps that were added, or an error per map
Removes a Georeference Annotation.
-
annotation
any Georeference Annotation
Returns Promise<Array<(string | Error)>> the map IDs of the maps that were removed, or an error per map
Adds a Georeference Annotation by URL.
-
annotationUrl
string Georeference Annotation
Returns Promise<Array<(string | Error)>> the map IDs of the maps that were added, or an error per map
Removes a Georeference Annotation by URL.
-
annotationUrl
string Georeference Annotation
Returns Promise<Array<(string | Error)>> the map IDs of the maps that were removed, or an error per map
Adds a Georeferenced map.
-
georeferencedMap
unknown Georeferenced map
Returns Promise<(string | Error)> the map ID of the map that was added, or an error
Removes a Georeferenced map.
-
georeferencedMap
unknown Georeferenced map
Returns Promise<(string | Error)> the map ID of the map that was remvoed, or an error
Returns the WarpedMapList object that contains a list of the warped maps of all loaded maps
Returns WarpedMapList the warped map list
Returns a single map's warped map
-
mapId
string ID of the map
Returns (WebGL2WarpedMap | undefined) the warped map
Make a single map visible
-
mapId
string ID of the map
Make multiple maps visible
-
mapIds
Iterable<string> IDs of the maps
Make a single map invisible
-
mapId
string ID of the map
Make multiple maps invisible
-
mapIds
Iterable<string> IDs of the maps
Returns the visibility of a single map
-
mapId
Returns (boolean | undefined) whether the map is visible
Sets the resource mask of a single map
-
mapId
string ID of the map -
resourceMask
Ring new resource mask
Sets the transformation type of multiple maps
-
mapIds
Iterable<string> IDs of the maps -
transformation
TransformationType new transformation type
Sets the distortion measure of multiple maps
-
mapIds
Iterable<string> IDs of the maps -
distortionMeasure
DistortionMeasure new transformation type
Return the bounding box of all visible maps in the layer (inside or outside of the Viewport), in longitude/latitude coordinates.
Returns (Bbox | undefined) bounding box of all warped maps
Bring maps to front
-
mapIds
Iterable<string> IDs of the maps
Send maps to back
-
mapIds
Iterable<string> IDs of the maps
Bring maps forward
-
mapIds
Iterable<string> IDs of the maps
Send maps backward
-
mapIds
Iterable<string> IDs of the maps
Returns the z-index of a single map
-
mapId
string ID of the warped map
Returns (number | undefined) z-index of the warped map
Sets the object that caches image information
-
imageInformations
ImageInformations Object that caches image information
Gets the opacity of the layer
Returns (number | undefined) opacity of the map
Sets the opacity of the layer
-
opacity
number opacity between 0 and 1, where 0 is fully transparent and 1 is fully opaque
Resets the opacity of the layer to fully opaque
Gets the opacity of a single map
-
mapId
string ID of the map
Returns (number | undefined) opacity of the map
Sets the opacity of a single map
-
mapId
string ID of the map -
opacity
number opacity between 0 and 1, where 0 is fully transparent and 1 is fully opaque
Resets the opacity of a single map to fully opaque
-
mapId
string ID of the map
Sets the saturation of a single map
-
saturation
number saturation between 0 and 1, where 0 is grayscale and 1 are the original colors
Resets the saturation of a single map to the original colors
Sets the saturation of a single map
-
mapId
string ID of the map -
saturation
number saturation between 0 and 1, where 0 is grayscale and 1 are the original colors
Resets the saturation of a single map to the original colors
-
mapId
string ID of the map
Removes a color from all maps
-
options
Object remove color options
Resets the color removal for all maps
Removes a color from a single map
Resets the color for a single map
-
mapId
string ID of the map
Sets the colorization for all maps
-
hexColor
string desired hex color
Resets the colorization for all maps
Sets the colorization for a single mapID of the map
Resets the colorization of a single map
-
mapId
string ID of the map
Removes all warped maps from the layer
Prepare rendering the layer.
Render the layer.