openlayers

@allmaps/openlayers

Allmaps plugin for OpenLayers. Plugin that uses WebGL to show warped IIIF images on an OpenLayers map. The plugin works by loading Georeference Annotations.

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.

Examples:

• Observable notebook
• HTML example using ESM and Skypack
• HTML example using UMD and jsDelivr

How it works

This plugin exports the class WarpedMapLayer. You can add one or multiple Georeference Annotations (or AnnotationPages that contain multiple Georeference Annotations) to a WarpedMapLayer and add the WarpedMapLayer to your OpenLayers 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:

pnpm install @allmaps/openlayers

You can optionally 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/openlayers/dist/bundled/allmaps-openlayers-8.umd.js"></script>

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

const warpedMapLayer = new Allmaps.WarpedMapLayer()

Usage

Built for OpenLayers 8, but should work with OpenLayers 6 and OpenLayers 7 as well.

Loading a Georeference Annotation

Creating a WarpedMapLayer and adding a Georeference Annotation to an OpenLayers map looks like this:

import { WarpedMapLayer } from '@allmaps/openlayers'

const map = new ol.Map({
  target: 'map',
  layers: [
    new ol.layer.Tile({
      source: new ol.source.OSM()
    })
  ],
  view: new ol.View({
    center: ol.proj.fromLonLat([-71.00661, 42.37124]),
    zoom: 14
  })
})

// Create WarpedMapLayer
const warpedMapLayer = new WarpedMapLayer()

// Add the WarpedMapLayer to the map and load a Georeference Annotation
const annotationUrl = 'https://annotations.allmaps.org/maps/a9458d2f895dcdfb'
map.addLayer(warpedMapLayer)
warpedMapLayer.addGeoreferenceAnnotationByUrl(annotationUrl)

A Georeference Annotation can be added 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 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 OpenLayers way. Here's an example:

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

What is a map?

An OpenLayers map is an instance of the OpenLayers Map class, the central class of the OpenLayers 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 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

new OLWarpedMapEvent(type, data)

Parameters

• type (string)
• data (unknown)

Returns

OLWarpedMapEvent.

Extends

• Event

OLWarpedMapEvent#data

Type

unknown

new WarpedMapEvent(type, data)

Parameters

• type (WarpedMapEventType)
• data? (unknown)

Returns

WarpedMapEvent.

Extends

• Event

WarpedMapEvent#data?

Type

unknown

new WarpedMapLayer(options)

Creates a WarpedMapLayer instance

Parameters

• options? (Partial<RendererOptions> | undefined)
  • the WebGL2 renderer options

Returns

WarpedMapLayer.

Extends

• Layer

WarpedMapLayer#addEventListeners()

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#addGeoreferenceAnnotation(annotation)

Adds a Georeference Annotation.

Parameters

• annotation (unknown)
  • Georeference Annotation

Returns

Promise<Array<string | Error>>.

• the map IDs of the maps that were added, or an error per map

WarpedMapLayer#addGeoreferenceAnnotationByUrl(annotationUrl)

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

WarpedMapLayer#addGeoreferencedMap(georeferencedMap)

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

WarpedMapLayer#bringMapsForward(mapIds)

Bring maps forward

Parameters

• mapIds (Iterable<string>)
  • IDs of the maps

Returns

void.

WarpedMapLayer#bringMapsToFront(mapIds)

Bring maps to front

Parameters

• mapIds (Iterable<string>)
  • IDs of the maps

Returns

void.

WarpedMapLayer#canvas

Type

HTMLCanvasElement

WarpedMapLayer#canvasSize

Type

[number, number]

WarpedMapLayer#clear()

Clears: removes all maps

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#container

Type

HTMLElement

WarpedMapLayer#contextLost(event)

Parameters

• event (Event)

Returns

void.

WarpedMapLayer#contextRestored(event)

Parameters

• event (Event)

Returns

void.

WarpedMapLayer#dispose()

Disposes all WebGL resources and cached tiles

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#getCanvas()

Gets the HTML canvas element of the layer

Parameters

There are no parameters.

Returns

HTML Canvas element (HTMLCanvasElement | null).

WarpedMapLayer#getContainer()

Gets the HTML container element of the layer

Parameters

There are no parameters.

Returns

HTML element (HTMLElement).

WarpedMapLayer#getExtent()

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

Parameters

There are no parameters.

Returns

Extent | undefined.

• bounding box of all warped maps

WarpedMapLayer#getLonLatExtent()

Return the bounding box of all visible maps in the layer (inside or outside of the Viewport), in longitude/latitude coordinates.

Parameters

There are no parameters.

Returns

Extent | undefined.

• Bounding box of all warped maps

WarpedMapLayer#getMapOpacity(mapId)

Gets the opacity of a single map

Parameters

• mapId (string)
  • ID of the map

Returns

Opacity of the map (number | undefined).

WarpedMapLayer#getMapZIndex(mapId)

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

WarpedMapLayer#getWarpedMap(mapId)

Returns a single map's warped map

Parameters

• mapId (string)
  • ID of the map

Returns

the warped map (WebGL2WarpedMap | undefined).

WarpedMapLayer#getWarpedMapList()

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

Parameters

There are no parameters.

Returns

the warped map list (WarpedMapList<WebGL2WarpedMap>).

WarpedMapLayer#gl

Type

WebGL2RenderingContext

WarpedMapLayer#hideMap(mapId)

Make a single map invisible

Parameters

• mapId (string)
  • ID of the map

Returns

void.

WarpedMapLayer#hideMaps(mapIds)

Make multiple maps invisible

Parameters

• mapIds (Iterable<string>)
  • IDs of the maps

Returns

void.

WarpedMapLayer#isMapVisible(mapId)

Returns the visibility of a single map

Parameters

• mapId (string)

Returns

boolean | undefined.

• whether the map is visible

WarpedMapLayer#passWarpedMapEvent(event)

Parameters

• event (Event)

Returns

void.

WarpedMapLayer#removeEventListeners()

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#removeGeoreferenceAnnotation(annotation)

Removes a Georeference Annotation.

Parameters

• annotation (unknown)
  • Georeference Annotation

Returns

Promise<Array<string | Error>>.

• the map IDs of the maps that were removed, or an error per map

WarpedMapLayer#removeGeoreferenceAnnotationByUrl(annotationUrl)

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

WarpedMapLayer#removeGeoreferencedMap(georeferencedMap)

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

WarpedMapLayer#removeGeoreferencedMapById(mapId)

Parameters

• mapId (string)

Returns

void.

WarpedMapLayer#render(frameState)

Render the layer.

Parameters

• frameState ({ pixelRatio: number; time: number; viewState: State; animate: boolean; coordinateToPixelTransform: Transform; ... 14 more ...; renderTargets: { [x: string]: boolean; }; })
  • OpenLayers frame state

Returns

The rendered element (HTMLElement).

WarpedMapLayer#renderer

Type

WebGL2Renderer

WarpedMapLayer#resetColorize()

Resets the colorization for all maps

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#resetGrid()

Resets the grid for all maps

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#resetMapColorize(mapId)

Resets the colorization of a single map

Parameters

• mapId (string)
  • ID of the map

Returns

void.

WarpedMapLayer#resetMapGrid(mapId)

Resets the grid of a single map

Parameters

• mapId (string)
  • ID of the map

Returns

void.

WarpedMapLayer#resetMapOpacity(mapId)

Resets the opacity of a single map to fully opaque

Parameters

• mapId (string)
  • ID of the map

Returns

void.

WarpedMapLayer#resetMapRemoveColor(mapId)

Resets the color for a single map

Parameters

• mapId (string)
  • ID of the map

Returns

void.

WarpedMapLayer#resetMapSaturation(mapId)

Resets the saturation of a single map to the original colors

Parameters

• mapId (string)
  • ID of the map

Returns

void.

WarpedMapLayer#resetRemoveColor()

Resets the color removal for all maps

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#resetSaturation()

Resets the saturation of a single map to the original colors

Parameters

There are no parameters.

Returns

void.

WarpedMapLayer#resizeCanvas(canvas, __1)

Parameters

• canvas (HTMLCanvasElement)
• undefined ([number, number])

Returns

boolean.

WarpedMapLayer#resizeObserver

Type

ResizeObserver

WarpedMapLayer#resized(entries)

Parameters

• entries (Array<ResizeObserverEntry>)

Returns

void.

WarpedMapLayer#sendMapsBackward(mapIds)

Send maps backward

Parameters

• mapIds (Iterable<string>)
  • IDs of the maps

Returns

void.

WarpedMapLayer#sendMapsToBack(mapIds)

Send maps to back

Parameters

• mapIds (Array<string>)
  • IDs of the maps

Returns

void.

WarpedMapLayer#setColorize(hexColor)

Sets the colorization for all maps

Parameters

• hexColor (string)
  • desired hex color

Returns

void.

WarpedMapLayer#setGrid(enabled)

Sets the grid for all maps

Parameters

• enabled (boolean)
  • whether to show the grid

Returns

void.

WarpedMapLayer#setImageInformations(imageInformations)

Sets the object that caches image information

Parameters

• imageInformations (Map<string, unknown>)
  • Object that caches image information

Returns

void.

WarpedMapLayer#setMapColorize(mapId, hexColor)

Sets the colorization for a single mapID of the map

Parameters

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

Returns

void.

WarpedMapLayer#setMapGcps(mapId, gcps)

Sets the GCOs of a single map

Parameters

• mapId (string)
  • ID of the map
• gcps (Array<Gcp>)

Returns

void.

WarpedMapLayer#setMapGrid(mapId, enabled)

Sets the grid for a single mapID of the map

Parameters

• mapId (string)
  • ID of the map
• enabled (boolean)
  • whether to show the grid

Returns

void.

WarpedMapLayer#setMapOpacity(mapId, opacity)

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

Returns

void.

WarpedMapLayer#setMapRemoveColor(mapId, options)

Removes a color from a single map

Parameters

• mapId (string)
  • ID of the map
• options ({ hexColor?: string | undefined threshold?: number | undefined hardness?: number | undefined })

Returns

void.

WarpedMapLayer#setMapResourceMask(mapId, resourceMask)

Sets the resource mask of a single map

Parameters

• mapId (string)
  • ID of the map
• resourceMask (Array<Point>)
  • new resource mask

Returns

void.

WarpedMapLayer#setMapSaturation(mapId, saturation)

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

Returns

void.

WarpedMapLayer#setMapTransformationType(mapId, transformation)

Sets the transformation type of a single map

Parameters

• mapId (string)
  • ID of the map
• transformation ( | 'straight' | 'helmert' | 'polynomial' | 'polynomial1' | 'polynomial2' | 'polynomial3' | 'projective' | 'thinPlateSpline')
  • new transformation type

Returns

void.

WarpedMapLayer#setMapsDistortionMeasure(mapIds, distortionMeasure)

Sets the distortion measure of multiple maps

Parameters

• mapIds (Iterable<string>)
  • IDs of the maps
• distortionMeasure? (DistortionMeasure | undefined)
  • new distortion measure

Returns

void.

WarpedMapLayer#setMapsTransformationType(mapIds, transformation)

Sets the transformation type of multiple maps

Parameters

• mapIds (Iterable<string>)
  • IDs of the maps
• transformation ( | 'straight' | 'helmert' | 'polynomial' | 'polynomial1' | 'polynomial2' | 'polynomial3' | 'projective' | 'thinPlateSpline')
  • new transformation type

Returns

void.

WarpedMapLayer#setRemoveColor(options)

Removes a color from all maps

Parameters

• options ({ hexColor?: string | undefined threshold?: number | undefined hardness?: number | undefined })

Returns

void.

WarpedMapLayer#setSaturation(saturation)

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

Returns

void.

WarpedMapLayer#showMap(mapId)

Make a single map visible

Parameters

• mapId (string)
  • ID of the map

Returns

void.

WarpedMapLayer#showMaps(mapIds)

Make multiple maps visible

Parameters

• mapIds (Iterable<string>)
  • IDs of the maps

Returns

void.