@allmaps/render

Allmaps render module. Renders georeferenced IIIF maps using Georeference Annotations. Currently, only rendering to a WebGL 2 context is implemented. This module is used by:

• Allmaps plugin for Leaflet
• Allmaps plugin for MapLibre
• Allmaps plugin for OpenLayers

How it works

The render module accomplishes this task with the following classes:

• A WebGL2RenderingContext containing the rendering context for the drawing surface of an HTML element.
• A WebGLProgram for storing the vertex and fragment shader
• A WarpedMapList containing the list of WarpedMaps to draw
• A list of WebGL2WarpedMap elements containing the GL information for each warped map
• A TileCache for storing the image bitmaps of cached tiles

This package also contains two other important classes:

• A Viewport describes which view of the map should be rendered (extent, zoom level, ...)
• A WarpedMap describes how a georeferenced map is warped using a specific transformation

The renderer draws in its WebGL2RenderingContext when its render function is called and passed a Viewport (e.g. by a JavaScript mapping library). Then, for each WarpedMap in the WarpedMapList, the following happens:

• The ground control points (GPCs) are read from the Georeference Annotation. These GCOs are used to compute a transformation from IIIF resource coordinates to projected geospatial coordinates.
• The resource mask is read from the Georeference Annotation, and the area within is divided into small triangles.
• The best tile zoom level is computed for the current viewport, telling us which IIIF tile scaleFactor to use.
• The Viewport is transformed backwards from projected geospatial coordinates to resource coordinates of the IIIF image. The IIIF tiles covering this viewport on the resource image are fetched and cached in the TileCache.
• The area inside the resource mask is rendered in the viewport, triangle by triangle, using the cached tiles. The location of the triangles is computed using the forward transformation built from the GPCs.

Installation

This package works in browsers and in Node.js as an ESM module.

Install with pnpm:

pnpm install @allmaps/render

You can build this package locally by running:

pnpm run build

Usage

Import the package and its classes:

import { Viewport, WebGL2Renderer } from '@allmaps/render'

For a complete example, see the source code of the Allmaps plugins for Leaflet, MapLibre and OpenLayers.

API

Table of Contents

• constructor
  • Parameters
• computeProjectedGeoRectangle
  • Parameters
• fromWarpedMapList
  • Parameters
• fromProjectedGeoBbox
  • Parameters
• constructor
  • Parameters
• getViewportMask
  • Parameters
• getViewportMaskBbox
  • Parameters
• getViewportMaskRectangle
  • Parameters
• getViewportFullMask
  • Parameters
• getViewportFullMaskBbox
  • Parameters
• getViewportFullMaskRectangle
  • Parameters
• getResourceToViewportScale
  • Parameters
• getResourceToCanvasScale
  • Parameters
• getReferenceScale
• setResourceViewportRing
  • Parameters
• setResourceMask
  • Parameters
• setTransformationType
  • Parameters
• setDistortionMeasure
  • Parameters
• setGcps
  • Parameters
• setBestScaleFactor
  • Parameters
• hasImageInfo
• loadImageInfo
• constructor
  • Parameters
• setResourceMask
  • Parameters
• setBestScaleFactor
  • Parameters
• updateTriangulation
  • Parameters
• updateProjectedGeoTrianglePoints
  • Parameters
• updateTrianglePointsDistortion
  • Parameters
• resetTrianglePoints
• mixTrianglePoints
  • Parameters
• constructor
  • Parameters
• updateVertexBuffers
  • Parameters
• addCachedTileAndUpdateTextures
  • Parameters
• removeCachedTileAndUpdateTextures
  • Parameters
• constructor
  • Parameters
• getMapIds
• getWarpedMap
  • Parameters
• getMapZIndex
  • Parameters
• getBbox
• getProjectedBbox
• getMapsByGeoBbox
  • Parameters
• setImageInformations
  • Parameters
• setMapResourceMask
  • Parameters
• setMapsTransformationType
  • Parameters
• setMapsDistortionMeasure
  • Parameters
• bringMapsToFront
  • Parameters
• sendMapsToBack
  • Parameters
• bringMapsForward
  • Parameters
• sendMapsBackward
  • Parameters
• showMaps
  • Parameters
• hideMaps
  • Parameters
• addGeoreferencedMap
  • Parameters
• removeGeoreferencedMap
  • Parameters
• addGeoreferenceAnnotation
  • Parameters
• removeGeoreferenceAnnotation
  • Parameters
• constructor
  • Parameters
• isCachedTile
• abort
• constructor
  • Parameters
• fetch
• fetch
• fetch
• getCacheableTile
  • Parameters
• getCachedTile
  • Parameters
• getCacheableTiles
• getCachedTiles
• getTileUrls
• requestFetchableTiles
  • Parameters
• allRequestedTilesLoaded
• constructor
  • Parameters
• getOpacity
• setOpacity
  • Parameters
• resetOpacity
• getMapOpacity
  • Parameters
• setMapOpacity
  • Parameters
• resetMapOpacity
  • Parameters
• getRemoveColorOptions
• setRemoveColorOptions
  • Parameters
• resetRemoveColorOptions
• getMapRemoveColorOptions
  • Parameters
• setMapRemoveColorOptions
  • Parameters
• resetMapRemoveColorOptions
  • Parameters
• getColorizeOptions
• setColorizeOptions
  • Parameters
• resetColorizeOptions
• getMapColorizeOptions
  • Parameters
• setMapColorizeOptions
  • Parameters
• resetMapColorizeOptions
  • Parameters
• getGridOptions
• setGridOptions
  • Parameters
• resetGridOptions
• getMapGridOptions
  • Parameters
• setMapGridOptions
  • Parameters
• resetMapGridOptions
  • Parameters
• getSaturation
• setSaturation
  • Parameters
• resetSaturation
• getMapSaturation
  • Parameters
• setMapSaturation
  • Parameters
• resetMapSaturation
  • Parameters
• render
  • Parameters
• addGeoreferenceAnnotation
  • Parameters
• addGeoreferencedMap
  • Parameters

constructor

Creates a new Viewport

Parameters

• e
• t
• o
• r
• s (optional, default 1)
• viewportSize Size Size of the viewport in viewport pixels, as [width, height].
• projectedGeoCenter Point Center point of the viewport, in projected coordinates.
• projectedGeoPerViewportScale number Resolution of the viewport, in projection coordinates per viewport pixel.
• rotation number Rotation of the viewport with respect to the project coordinate system.
• devicePixelRatio number The devicePixelRatio of the viewport. (optional, default 1)

computeProjectedGeoRectangle

Returns a rotated rectangle in projected geo coordinates

Parameters

• e
• t
• o
• r

fromWarpedMapList

Static method creates that creates a Viewport from a WarpedMapList

Parameters

• e
• t
• o
• r (optional, default "contain")
• s (optional, default 1)
• viewportSize Size Size of the viewport in viewport pixels, as [width, height].
• warpedMapList WarpedMapList<W> A WarpedMapList.
• devicePixelRatio number? The devicePixelRatio of the viewport.
• fit Fit Whether the viewport should contain or cover the bbox of the warpedMapList. (optional, default 'contain')

Returns Viewport A new Viewport object

fromProjectedGeoBbox

Static method creates that creates a Viewport from Bbox in projected geospatial coordinates.

Parameters

• e
• t
• o
• r (optional, default "contain")
• viewportSize Size Size of the viewport in viewport pixels, as [width, height].
• projectedGeoBbox WarpedMapList<W> A projectedGeoBbox.
• devicePixelRatio number? The devicePixelRatio of the viewport.
• fit Fit Whether the viewport should contain or cover the bbox of the warpedMapList. (optional, default 'contain')

Returns Viewport A new Viewport object

constructor

Creates an instance of WarpedMap.

Parameters

• e
• r
• s
• mapId string ID of the map
• georeferencedMap GeoreferencedMap Georeferenced map used to construct the WarpedMap
• options WarpedMapOptions? options

getViewportMask

Get resourceMask in viewport coordinates

Parameters

• e
• viewport Viewport the current viewport

Returns Ring

getViewportMaskBbox

Get Bbox of resourceMask in viewport coordinates

Parameters

• e
• viewport Viewport the current viewport

Returns Bbox

getViewportMaskRectangle

Get resourceMaskRectangle in viewport coordinates

Parameters

• e
• viewport Viewport the current viewport

Returns Rectangle

getViewportFullMask

Get resourceFullMask in viewport coordinates

Parameters

• e
• viewport Viewport the current viewport

Returns Ring

getViewportFullMaskBbox

Get bbox of rresourceFullMask in viewport coordinates

Parameters

• e
• viewport Viewport the current viewport

Returns Bbox

getViewportFullMaskRectangle

Get resourceFullMaskRectangle in viewport coordinates

Parameters

• e
• viewport Viewport the current viewport

Returns Rectangle

getResourceToViewportScale

Get scale of the warped map, in resource pixels per viewport pixels.

Parameters

• e
• viewport Viewport the current viewport

Returns number

getResourceToCanvasScale

Get scale of the warped map, in resource pixels per canvas pixels.

Parameters

• e
• viewport Viewport the current viewport

Returns number

getReferenceScale

Get the reference scaling from the forward transformation of the projected Helmert transformer

Returns number

setResourceViewportRing

Set resourceViewportRing at current viewport

Parameters

• e
• resourceViewportRing Ring

setResourceMask

Update the resourceMask loaded from a georeferenced map to a new mask.

Parameters

• e
• resourceMask Ring

setTransformationType

Update the transformationType loaded from a georeferenced map to a new transformation type.

Parameters

• e
• transformationType TransformationType

setDistortionMeasure

Set the distortionMeasure

Parameters

• e
• distortionMeasure DistortionMeasure? the disortion measure

setGcps

Update the Ground Controle Points loaded from a georeferenced map to new Ground Controle Points.

Parameters

• e
• gcps Array<GCP>

setBestScaleFactor

Set the bestScaleFactor for the current viewport

Parameters

• e
• scaleFactor number scale factor

Returns boolean

hasImageInfo

Check if warpedMap has image info

loadImageInfo

Fetch and parse the image info, and generate the image ID

Returns Promise<void>

constructor

Creates an instance of a TriangulatedWarpedMap.

Parameters

• e
• t
• i
• mapId string ID of the map
• georeferencedMap GeoreferencedMap Georeferenced map used to construct the WarpedMap
• options WarpedMapOptions? Options

setResourceMask

Update the resourceMask.

Parameters

• e
• resourceMask Ring

setBestScaleFactor

Set the bestScaleFactor for the current viewport

Parameters

• e
• scaleFactor number scale factor

Returns boolean

updateTriangulation

Update the triangulation of the resourceMask, at the current bestScaleFactor. Use cache if available.

Parameters

• e (optional, default !1)
• previousIsNew boolean? whether the previous and new triangulation are the same - true by default, false during a transformation transition

updateProjectedGeoTrianglePoints

Update the (previous and new) points of the triangulated resourceMask, at the current bestScaleFactor, in projectedGeo coordinates. Use cache if available.

Parameters

• e (optional, default !1)
• previousIsNew boolean (optional, default false)

updateTrianglePointsDistortion

Update the (previous and new) distortion at the points of the triangulated resourceMask. Use cache if available.

Parameters

• e (optional, default !1)
• previousIsNew boolean (optional, default false)

resetTrianglePoints

Reset the previous points of the triangulated resourceMask in projectedGeo coordinates.

mixTrianglePoints

Mix the previous and new points of the triangulated resourceMask in projectedGeo coordinates

Parameters

• e
• t number

constructor

Creates an instance of WebGL2WarpedMap.

Parameters

• e
• i
• r
• s
• n
• mapId string ID of the map
• georeferencedMap GeoreferencedMap Georeferenced map used to construct the WarpedMap
• gl WebGL2RenderingContext WebGL rendering context
• program WebGLProgram WebGL program
• options Partial<WarpedMapOptions> WarpedMapOptions

updateVertexBuffers

Update the vertex buffers of this warped map

Parameters

• e
• projectedGeoToClipTransform Transform Transform from projected geo coordinates to webgl2 coordinates in the [-1, 1] range. Equivalent to OpenLayers' projectionTransform.

addCachedTileAndUpdateTextures

Add cached tile to the textures of this map and update textures

Parameters

• e
• cachedTile CachedTile

removeCachedTileAndUpdateTextures

Remove cached tile from the textures of this map and update textures

Parameters

• e
• tileUrl string

constructor

Creates an instance of a WarpedMapList.

Parameters

• e
• t
• warpedMapFactory WarpedMapFactory<W>? Factory function for creating WarpedMap objects
• options WarpedMapListOptions? Options

getMapIds

Returns mapIds for the maps in this list.

Returns Iterable<string>

getWarpedMap

Returns the WarpedMap object in this list of map specified by its ID.

Parameters

• e
• mapId string

Returns (W | undefined)

getMapZIndex

Returns the z-index of a map.

Parameters

• e
• mapId string

Returns (number | undefined)

getBbox

Return the bounding box of all visible maps in this list, in longitude/latitude coordinates

Returns (Bbox | undefined)

getProjectedBbox

Return the bounding box of all visible maps in this list, in projected coordinates

Returns (Bbox | undefined)

getMapsByGeoBbox

Returns mapIds of the maps whose geoBbox overlaps with the specified geoBbox.

Parameters

• e
• geoBbox Bbox

Returns Iterable<string>

setImageInformations

Sets the object that caches image information

Parameters

• e
• imageInformations ImageInformations object that caches image information

setMapResourceMask

Sets the resource mask for a specified map

Parameters

• e
• t
• mapId string ID of the map
• resourceMask Ring the new resource mask

setMapsTransformationType

Sets the transformation type of specified maps

Parameters

• e
• t
• mapIds Iterable<string> the IDs of the maps
• transformationType TransformationType the new transformation type

setMapsDistortionMeasure

Sets the distortion measure of specified maps

Parameters

• e
• t
• mapIds Iterable<string> the IDs of the maps
• distortionMeasure DistortionMeasure? the distortion measure

bringMapsToFront

Changes the z-index of the specified maps to bring them to front

Parameters

• e
• mapIds Iterable<string>

sendMapsToBack

Changes the z-index of the specified maps to send them to back

Parameters

• e
• mapIds Iterable<string>

bringMapsForward

Changes the z-index of the specified maps to bring them forward

Parameters

• e
• mapIds Iterable<string>

sendMapsBackward

Changes the zIndex of the specified maps to send them backward

Parameters

• e
• mapIds Iterable<string>

showMaps

Changes the visibility of the specified maps to true

Parameters

• e
• mapIds Iterable<string>

hideMaps

Changes the visibility of the specified maps to false

Parameters

• e
• mapIds Iterable<string>

addGeoreferencedMap

Adds a georeferenced map to this list

Parameters

• e
• georeferencedMap unknown

Returns Promise<(string | Error)>

removeGeoreferencedMap

Removes a georeferenced map from this list

Parameters

• e
• georeferencedMap unknown

Returns Promise<(string | Error)>

addGeoreferenceAnnotation

Parses an annotation and adds its georeferenced map to this list

Parameters

• e
• annotation unknown

Returns Promise<Array<(string | Error)>>

removeGeoreferenceAnnotation

Parses an annotation and removes its georeferenced map from this list

Parameters

• e
• annotation unknown

Returns Promise<Array<(string | Error)>>

constructor

Creates an instance of CacheableTile.

Parameters

• t
• e
• fetchableTile FetchableTile
• fetchFn FetchFn? Optional fetch function to use

isCachedTile

Whether a tile has fetched its data

Returns boolean

abort

Abort the fetch

constructor

Creates an instance of FetchableTile.

Parameters

• e
• t
• tile Tile the tile
• warpedMap WarpedMapWithImageInfo A WarpedMap with fetched image information

fetch

Fetch the tile and create its ImageBitMap.

Returns Promise<void>

fetch

Fetch the tile and create its ImageData object.

Returns Promise<void>

fetch

Fetch the tile and create its IntArray data using the supplied getImageData function.

Returns Promise<void>

getCacheableTile

Get a specific tile in this cache

Parameters

• e
• tileUrl string the URL of the requested tile

Returns (CacheableTile | undefined)

getCachedTile

Get a specific cached tile in this cache that has been fetched

Parameters

• e
• tileUrl string the URL of the requested tile

Returns (CachedTile | undefined)

getCacheableTiles

Get the tiles in this cache

Returns IterableIterator<CacheableTile>

getCachedTiles

Get the tiles in this cache that have been fetched

Returns Array<CacheableTile>

getTileUrls

Get the URLs of all tiles in this cache

Returns IterableIterator<string>

requestFetchableTiles

Process the request for new tiles to be added to this cache

Parameters

• e
• tiles Array<FetchableTile>

allRequestedTilesLoaded

Returns a promise that resolves when all requested tiles are loaded. This could happen immidiately, in case there are no current requests and the tilesFetchingCount is zero, or in a while, when the count reaches zero and the ALLREQUESTEDTILESLOADED event is fired.

Returns Promise<void>

constructor

Creates an instance of WebGL2Renderer.

Parameters

• e
• t
• gl WebGL2RenderingContext WebGL 2 rendering context
• options WebGL2RendererOptions options

getOpacity

Get the opacity of the renderer

Returns (number | undefined)

setOpacity

Set the opacity of the renderer

Parameters

• e
• opacity number opacity to set

resetOpacity

Reset the opacity of the renderer

getMapOpacity

Get the opacity of a map

Parameters

• e
• mapId string ID of the map

Returns (number | undefined)

setMapOpacity

Set the opacity of a map

Parameters

• e
• t
• mapId string ID of the map
• opacity number opacity to set

resetMapOpacity

Rreset the opacity of a map

Parameters

• e
• mapId string ID of the map

getRemoveColorOptions

Get the remove color options of the renderer

Returns (Partial<RemoveColorOptions> | undefined)

setRemoveColorOptions

Set the remove color options of the renderer

Parameters

• e
• removeColorOptions RemoveColorOptions

resetRemoveColorOptions

Reset the remove color options of the renderer

getMapRemoveColorOptions

Get the remove color options of a map

Parameters

• e
• mapId string ID of the map

Returns (Partial<RemoveColorOptions> | undefined)

setMapRemoveColorOptions

Set the remove color options of a map

Parameters

• e
• t
• mapId string ID of the map
• removeColorOptions RemoveColorOptions the 'remove color options' to set

resetMapRemoveColorOptions

Reset the remove color options of a map

Parameters

• e
• mapId string ID of the map

getColorizeOptions

Get the colorize options of the renderer

Returns (Partial<ColorizeOptions> | undefined)

setColorizeOptions

Set the colorize options of the renderer

Parameters

• e
• colorizeOptions ColorizeOptions the colorize options to set

resetColorizeOptions

Reset the colorize options of the renderer

getMapColorizeOptions

Get the colorize options of a map

Parameters

• e
• mapId string ID of the map

Returns (Partial<ColorizeOptions> | undefined)

setMapColorizeOptions

Set the colorize options of a map

Parameters

• e
• t
• mapId string ID of the map
• colorizeOptions ColorizeOptions the colorize options to set

resetMapColorizeOptions

Reset the colorize options of a map

Parameters

• e
• mapId string ID of the map

getGridOptions

Get the grid options of the renderer

Returns (Partial<GridOptions> | undefined)

setGridOptions

Set the grid options of the renderer

Parameters

• e
• gridOptions GridOptions the grid options to set

resetGridOptions

Reset the grid options of the renderer

getMapGridOptions

Get the grid options of a map

Parameters

• e
• mapId string ID of the map

Returns (Partial<GridOptions> | undefined)

setMapGridOptions

Set the grid options of a map

Parameters

• e
• t
• mapId string ID of the map
• gridOptions GridOptions the grid options to set

resetMapGridOptions

Reset the grid options of a map

Parameters

• e
• mapId string ID of the map

getSaturation

Get the saturation of the renderer

Returns number

setSaturation

Set the saturation of the renderer

0 - grayscale, 1 - original colors

Parameters

• e
• saturation the satuation to set

resetSaturation

Reset the satuation of the renderer

getMapSaturation

Get the saturation of a map

Parameters

• e
• mapId string ID of the map

Returns (number | undefined)

setMapSaturation

Set the saturation of a map

0 - grayscale, 1 - original colors

Parameters

• e
• t
• mapId ID of the map
• saturation the saturation to set

resetMapSaturation

Reset the saturation of a map

Parameters

• e
• mapId string ID of the map

render

Render the map for a given viewport

Parameters

• e
• viewport Viewport the current viewport

addGeoreferenceAnnotation

Parses an annotation and adds its georeferenced map to this renderer's warped map list

Parameters

• e
• annotation unknown

Returns Promise<Array<(string | Error)>>

addGeoreferencedMap

Adds a georeferenced map to this renderer's warped map list

Parameters

• e
• georeferencedMap unknown

Returns Promise<(string | Error)>