Plugin that uses WebGL to show warped IIIF images on an OpenLayers map. The plugin works by loading Georeference Annotations.
This plugin creates a new class WarpedMapLayer which extends and behaves like a OpenLayers Layer. You can add one or multiple Georeference Annotations (or Georeference Annotation Pages) to a WarpedMapLayer, and add the WarpedMapLayer to your OpenLayers map. This will render all Georeferenced Maps contained in the annotation (pages) on your OpenLayers 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 module.
Install with npm:
npm install @allmaps/openlayersAnd load using:
import { WarpedMapLayer } from '@allmaps/openlayers'You can build this package using
pnpm run buildAs 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.cjs"></script>When loading as bundled code, the package's functions are available under the Allmaps global variable:
// ... (see 'Usage' below)
const warpedMapSource = new Allmaps.WarpedMapSource()
// ...Built for OpenLayers 8, but should work with OpenLayers 6 and OpenLayers 7 as well. See the vite config for more information about globals, and the OpenLayers version for which it has been compiled.
As is custom in OpenLayers, this package differentiates 'source' and 'layer'. In the Allmaps Leaflet package, this distinction is not made.
Create a source and layer and adding them to map looks like this:
import { WarpedMapLayer, WarpedMapSource } from '@allmaps/openlayers'
// Create warpedMapSource and warpedMapLayer
const warpedMapSource = new WarpedMapSource()
const warpedMapLayer = new WarpedMapLayer({
source: warpedMapSource
})
// OpenLayers map with OSM base layer and the warpedMapLayer
const map = new ol.Map({
target: 'map',
layers: [
new ol.layer.Tile({
source: new ol.source.OSM()
}),
warpedMapLayer
],
view: new ol.View({
center: ol.proj.fromLonLat([-71.0599, 42.3589]),
zoom: 13
})
})A Georeference Annotation can be added to a WarpedMapSource using the functions addGeoreferenceAnnotation() or addGeoreferenceAnnotationByUrl(), which will render it as part of the WarpedMapLayer on the OpenLayers map. Here's an example of the first using fetch() and then().
const annotationUrl = 'https://annotations.allmaps.org/images/813b0579711371e2@2c1d7e89d8c309e8'
fetch(annotationUrl)
.then((response) => response.json())
.then((annotation) => {
warpedMapSource.addGeoreferenceAnnotation(annotation)
})And here's an example of the later using a custom async function
async function asyncAddGeoreferenceAnnotationByUrl() {
// ...
return await warpedMapSource.addGeoreferenceAnnotationByUrl(annotationUrl)
}
asyncAddGeoreferenceAnnotationByUrl()
Click the image above to see a live CodePen example of a minimal html file that loads an OpenLayers map, creates a Source and Layer and adds a Georeference Annotation to the Source to display it's Georeferenced Map on the OpenLayers map.
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.getTotalBounds())}, 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.
Both OpenLayers and Allmaps have a concept named a 'map'.
A 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 code, there's also a WebGL2WarpedMap)
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.
- Point
- Bbox
- TransformationType
- WarpedMapLayer
- WarpedMapSource
- addGeoreferenceAnnotation
- removeGeoreferenceAnnotation
- addGeoreferenceAnnotationByUrl
- removeGeoreferenceAnnotationByUrl
- addGeoreferencedMap
- removeGeoreferencedMap
- getWarpedMapList
- getWarpedMap
- showMap
- showMaps
- hideMap
- hideMaps
- isMapVisible
- setMapResourceMask
- setMapsTransformationType
- getTotalBbox
- getTotalProjectedBbox
- bringMapsToFront
- sendMapsToBack
- bringMapsForward
- sendMapsBackward
- getMapZIndex
- setImageInfoCache
- clear
Point
Bounding box
Type: [number, number, number, number]
Transformation type
Type: ("helmert" | "polynomial" | "polynomial1" | "polynomial2" | "polynomial3" | "projective" | "thinPlateSpline")
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.
Gets the HTML container element of the layer
Returns HTMLElement HTML Div Element
Gets the HTML canvas element of the layer
Returns (HTMLCanvasElement | null) HTML Canvas Element
Gets the opacity of a single map
mapIdstring ID of the map
Returns (number | undefined) opacity of the map
Sets the opacity of a single map
mapIdstring ID of the mapopacitynumber 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
mapIdstring ID of the map
Sets the saturation of a single map
saturationnumber 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
mapIdstring ID of the mapsaturationnumber 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
mapIdstring ID of the map
Removes a color from all maps
-
optionsObject remove color options
Resets the color removal for all maps
Removes a color from a single map
Resets the color for a single map
mapIdstring ID of the map
Sets the colorization for all maps
hexColorstring 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
mapIdstring ID of the map
Disposes all WebGL resources and cached tiles
Render the layer.
frameState
Returns HTMLElement The rendered element
WarpedMapSource class. Together with a WarpedMapLayer, this class renders a warped map on an OpenLayers map.
Adds a Georeference Annotation.
annotationany 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.
annotationany 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.
annotationUrlstring 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.
annotationUrlstring 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.
georeferencedMapunknown Georeferenced map
Returns Promise<(string | Error)> the map ID of the map that was added, or an error
Removes a Georeferenced map.
georeferencedMapunknown 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
mapIdstring ID of the map
Returns (WarpedMap | undefined) the warped map
Make a single map visible
mapIdstring ID of the map
Make multiple maps visible
mapIdsIterable<string> IDs of the maps
Make a single map invisible
mapIdstring ID of the map
Make multiple maps invisible
mapIdsIterable<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
mapIdstring ID of the mapresourceMaskRing new resource mask
Sets the transformation type of multiple maps
mapIdsIterable<string> IDs of the mapstransformationTransformationType new transformation type
Return the Bbox of all visible maps in the layer (inside or outside of the Viewport), in lon lat coordinates.
Returns (Bbox | undefined) bbox of all warped maps
Return the Bbox of all visible maps in the layer (inside or outside of the Viewport), in projected coordinates.
Returns (Bbox | undefined) bbox of all warped maps
Bring maps to front
mapIdsIterable<string> IDs of the maps
Send maps to back
mapIdsIterable<string> IDs of the maps
Bring maps forward
mapIdsIterable<string> IDs of the maps
Send maps backward
mapIdsIterable<string> IDs of the maps
Returns the z-index of a single map
mapIdstring ID of the warped map
Returns (number | undefined) z-index of the warped map
Sets the image info Cache of the warpedMapList, informing it's warped maps about possibly cached imageInfo.
cacheCache the image info cache
Clears the source, removes all maps