@allmaps/openlayers NPM

@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:

How it works

This plugin exports the classes WarpedMapLayer and WarpedMapSource. You can add one or multiple Georeference Annotations (or AnnotationPages that contain multiple Georeference Annotations) to a WarpedMapSource, add this WarpedMapSource to a WarpedMapLayer and this 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 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 warpedMapSource = new Allmaps.WarpedMapSource()

Usage

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

Loading a Georeference Annotation

Creating a WarpedMapLayer and WarpedMapSource and adding them to a map looks like this:

import { WarpedMapLayer, WarpedMapSource } 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 WarpedMapSource and WarpedMapLayer
const warpedMapSource = new allmapsOpenLayers.WarpedMapSource()
const warpedMapLayer = new allmapsOpenLayers.WarpedMapLayer({
  source: warpedMapSource
})

// Add layer to map and Georeference Annotation to source
const annotationUrl = 'https://annotations.allmaps.org/maps/a9458d2f895dcdfb'
map.addLayer(warpedMapLayer)
warpedMapSource.addGeoreferenceAnnotationByUrl(annotationUrl)

A Georeference Annotation can be added to a WarpedMapSource using the addGeoreferenceAnnotation and addGeoreferenceAnnotationByUrl functions:

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

Or:

await warpedMapSource.addGeoreferenceAnnotationByUrl(annotationUrl)

Events

The following events are emitted to inform you of the state of the WarpedMapLayer, WarpedMapSource and rendering.

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:

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

Some of the functions specified in the API only make sense once a warped map is loaded into the WarpedMapSource. 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?

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 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

Point

Type: [number, number]

Bbox

Bounding box

Type: [number, number, number, number]

TransformationType

Transformation type

WarpedMapLayer

WarpedMapLayer class.

Together with a WarpedMapSource, this class renders georeferenced maps of a IIIF Georeference Annotation on an OpenLayers map. WarpedMapLayer is a subclass of Layer.

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

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