@allmaps/leaflet NPM

@allmaps/leaflet

Allmaps plugin for Leaflet. This plugin allows displaying georeferenced IIIF images on a Leaflet 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.

The development of the Allmaps plugin for Leaflet was funded by CLARIAH-VL.

Examples:

How it works

This plugin exports the class WarpedMapLayer that extends L.Layer. You can add one or multiple Georeference Annotations (or AnnotationPages that contain multiple Georeference Annotations) to a WarpedMapLayer, and add the WarpedMapLayer to your Leaflet map. This will render all georeferenced maps defined by the Georeference Annotations.

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:

npm install @allmaps/leaflet

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. They require Leaflet to be loaded as L, so place them after loading Leaflet.

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

When loading the bundled package, its classes are available under the Allmaps global variable:

const warpedMapLayer = new Allmaps.WarpedMapLayer(annotationUrl)

Usage

Built for Leaflet 1.9, 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/leaflet'

const map = L.map('map', {
  center: [51.0518, 3.7278],
  zoom: 14,
  // Zoom animations for more than one zoom level are
  // currently not supported by the Allmaps plugin for Leafet
  zoomAnimationThreshold: 1
})
L.tileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
  attribution:
    '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map)

const annotationUrl =
  'https://annotations.allmaps.org/manifests/8f9faeba73d67031'
const warpedMapLayer = new WarpedMapLayer(annotationUrl).addTo(map)

When adding this WarpedMapLayer to the Leaflet map, the georeferenced map specified in the Georeference Annotation will be rendered on the Leaflet map.

Specifying a the URL Georeference Annotation when creating a WarpedMapLayer (as is done above) is optional. A Georeference Annotation can also be added at a later stage using the addGeoreferenceAnnotation and addGeoreferenceAnnotationByUrl functions:

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

Or:

await warpedMapLayer.addGeoreferenceAnnotationByUrl(annotationUrl)

Events

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 warped maps 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 Leaflet way. Here's an example:

map.on(
  'warpedmapadded',
  (event) => {
    console.log(event.mapId, warpedMapSource.getBounds())
  },
  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?

A Leaflet map is an instance of the Leaflet Map class, the central class of the Leaflet 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 GeoreferencedMap class is created from it.
When this map is loaded into an application for rendering, an instance of the WarpedMap class is created from it.
Inside the WebGL2 rendering package, the WebGL2WarpedMap class is used to render the map.

All these map phases originate from the same Georeference Annotation have the same unique mapId property. This string value is used thoughout 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

WarpedMapLayer

WarpedMapLayer

WarpedMapLayer class.

Renders georeferenced maps of a Georeference Annotation on a Leaflet map. WarpedMapLayer extends Leaflet's L.Layer.

initialize

Creates a WarpedMapLayer

Parameters

annotationOrAnnotationUrl
options WarpedMapLayerOptions
annotation unknown? Georeference Annotation or URL of a Georeference Annotation

onAdd

Contains all code code that creates DOM elements for the layer and adds them to map panes where they belong.

Parameters

map

onRemove

Contains all cleanup code that removes the layer's elements from the DOM.

Parameters

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 any 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 any Georeferenced map

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

getContainer

Gets the HTML container element of the layer

Returns HTMLElement HTML Div Element

getCanvas

Gets the HTML canvas element of the layer

Returns (HTMLCanvasElement | null) HTML Canvas Element

getWarpedMapList

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

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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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 Array\ new resource mask

setMapsTransformationType

Sets the transformation type of multiple maps

Parameters

mapIds Iterable[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) IDs of the maps
transformation TransformationType new transformation type

getBounds

Returns the bounds of all visible maps (inside or outside of the Viewport), in latitude/longitude coordinates.

bringMapsToFront

Bring maps to front

Parameters

mapIds Iterable[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) IDs of the maps

sendMapsToBack

Send maps to back

Parameters

mapIds Iterable[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) IDs of the maps

bringMapsForward

Bring maps forward

Parameters

mapIds Iterable[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) IDs of the maps

sendMapsBackward

Send maps backward

Parameters

mapIds Iterable[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) IDs of the maps

bringToFront

Brings the layer in front of other overlays (in the same map pane).

bringToBack

Brings the layer to the back of other overlays (in the same map pane).

getMapZIndex

Returns the z-index of a single map

Parameters

mapId string ID of the map

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

getZIndex

Gets the zIndex of the layer.

setZIndex

Changes the zIndex of the layer.

Parameters

value number zIndex

setImageInfoCache

Sets the image info Cache of the warpedMapList

Parameters

cache Cache the image info cache

getPaneName

Gets the pane name the layer is attached to. Defaults to 'tilePane'

Returns string Pane name

getOpacity

Gets the opacity of the layer

Returns number Layer opacity

setOpacity

Sets the opacity of the layer

Parameters

opacity number Layer opacity

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 1

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