MapLibre classes for Allmaps
npm install @allmaps/maplibreAllmaps 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
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:
``sh`
pnpm install @allmaps/maplibre
You can optionally build this package locally by running:
`sh`
pnpm run build
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:
`js
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.id
* Just like other MapLibre layers, a WarpedMapLayer must have a unique . 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.id
* Just like other MapLibre layers, a WarpedMapLayer must have a unique . By default, the id has the value warped-map-layer. When adding multiple WarpedMapLayers to your map, pass a unique id to their constructor:
`js`
const warpedMapLayerWithUniqueId = new WarpedMapLayer({layerId: 'my-unique-id'})
A Georeference Annotation can be added to a WarpedMapLayer using the addGeoreferenceAnnotation and addGeoreferenceAnnotationByUrl functions:
`js`
fetch(annotationUrl)
.then((response) => response.json())
.then((annotation) => warpedMapLayer.addGeoreferenceAnnotation(annotation))
Or:
`js`
await warpedMapLayer.addGeoreferenceAnnotationByUrl(annotationUrl)
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):
`js`
warpedMapLayer.setLayerOptions({ visible: true })
warpedMapLayer.setMapOptions(mapId, { visible: true })
You can listen to events in the typical way:
`js`
map.on('warpedmapadded', (event) => {
console.log(event.mapIds)
})
MIT
###### Type
`ts`
SpecificMapLibreWarpedMapLayerOptions & Partial
###### Parameters
* type (WarpedMapEventType)data?
* (Partial)
###### Returns
WarpedMapEvent.
###### Extends
* Event
###### Type
`ts`
{
mapIds?: Array
tileUrl?: string | undefined
optionKeys?: Array
spritesInfo?: SpritesInfo | undefined
}
Creates a WarpedMapLayer instance
###### Parameters
* options? (Partial)
* options
###### Returns
WarpedMapLayer.
###### Extends
* BaseWarpedMapLayer
*
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).
###### Type
`ts`
string
###### Type
`ts`
MaplibreMap
Pass events
###### Parameters
* event (Event)
###### Returns
void.
Trigger the native update function of the map
###### Parameters
There are no parameters.
###### Returns
void.
Method called when the layer has been added to the Map.
###### Parameters
* map (MaplibreMap)gl
* The Map this custom layer was just added to.
* (WebGL2RenderingContext)
* The WebGL 2 context for the map.
###### Returns
void.
Method called when the layer has been removed from the Map.
###### Parameters
There are no parameters.
###### Returns
void.
Render the layer.
###### Parameters
There are no parameters.
###### Returns
void.
###### Type
`ts`
'2d'
###### Type
`ts``
'custom'