@allmaps/render v1.0.0-beta.61

@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

• WarpedMapWithImageInfo
• WarpedMapList
  • getMaps
  • getWarpedMap
  • getMapZIndex
  • getBbox
  • getProjectedBbox
  • getMapsByGeoBbox
  • setImageInfoCache
  • setMapResourceMask
  • setMapsTransformationType
  • bringMapsToFront
  • sendMapsToBack
  • bringMapsForward
  • sendMapsBackward
  • showMaps
  • hideMaps
  • addGeoreferencedMap
  • removeGeoreferencedMap
  • addGeoreferenceAnnotation
  • removeGeoreferenceAnnotation
• Viewport
  • Properties
  • computeProjectedGeoRectangle
• TileCache
  • getCacheableTile
  • getCachedTile
  • getCacheableTiles
  • getCachedTiles
  • getTileUrls
  • requestFetcableMapTiles
• CacheableTile
  • fetch
  • isCachedTile
  • abort
• CachedTile
• FetchableMapTile
• WebGL2Renderer
  • getOpacity
  • setOpacity
  • resetOpacity
  • getMapOpacity
  • setMapOpacity
  • resetMapOpacity
  • getRemoveColorOptions
  • setRemoveColorOptions
  • resetRemoveColorOptions
  • getMapRemoveColorOptions
  • setMapRemoveColorOptions
  • resetMapRemoveColorOptions
  • getColorizeOptions
  • setColorizeOptions
  • resetColorizeOptions
  • getMapColorizeOptions
  • setMapColorizeOptions
  • resetMapColorizeOptions
  • getSaturation
  • setSaturation
  • resetSaturation
  • getMapSaturation
  • setMapSaturation
  • resetMapSaturation
  • render
• WebGL2WarpedMap
  • updateVertexBuffers
  • addCachedTileAndUpdateTextures
  • removeCachedTileAndUpdateTextures
• DEFAULT_TARGET_SCALE_FACTOR_CORRECTION
• getBestTileZoomLevelForScale
  • Parameters

WarpedMapWithImageInfo

Extends WarpedMap

Class for warped maps with image ID and parsed IIIF image.

Type: WarpedMapWithImageInfo

WarpedMapList

Extends EventTarget

Class for warped map lists, which describe an ordered array of maps to be drawn. They contain an imageInfoCash, and and RTree for quickly looking up maps using their Bbox.

Type: WarpedMapList

getMaps

Returns mapIds for the maps in this list.

Returns Iterable[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

getWarpedMap

Returns the WarpedMap object in this list of map specified by a mapId.

Parameters

• mapId string

Returns (WarpedMap | undefined)

getMapZIndex

Returns the zIndex of a map.

Parameters

• 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

• geoBbox Bbox

Returns Iterable[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

setImageInfoCache

Sets the image info cache

Parameters

• cache Cache the image info cache

setMapResourceMask

Sets the resource mask for a specified map

Parameters

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

setMapsTransformationType

Sets the transformation type of specified maps

Parameters

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

bringMapsToFront

Changes the zIndex of the specified maps to bring them to front

Parameters

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

sendMapsToBack

Changes the zIndex of the specified maps to send them to back

Parameters

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

bringMapsForward

Changes the zIndex of the specified maps to bring them forward

Parameters

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

sendMapsBackward

Changes the zIndex of the specified maps to send them backward

Parameters

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

showMaps

Changes the visibility of the specified maps to true

Parameters

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

hideMaps

Changes the visibility of the specified maps to false

Parameters

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

addGeoreferencedMap

Adds a georeferenced map to this list

Parameters

• georeferencedMap unknown

Returns Promise<(string | Error)>

removeGeoreferencedMap

Removes a georeferenced map from this list

Parameters

• georeferencedMap unknown

Returns Promise<(string | Error)>

addGeoreferenceAnnotation

Parses an annotation and adds its georeferenced map to this list

Parameters

• annotation unknown

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

removeGeoreferenceAnnotation

Parses an annotation and removes its georeferenced map from this list

Parameters

• annotation unknown

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

Viewport

Extends EventTarget

The viewport describes the view on the rendered map.

Type: Viewport

Properties

• geoCenter Point Center point of the viewport, in longitude/latitude coordinates.
• geoRectangle Rectangle Rotated rectangle (possibly quadrilateral) of the viewport point, in longitude/latitude coordinates.
• geoSize Size Size of the viewport in longitude/latitude coordinates, as [width, height]. (This is the size of the bounding box of the rectangle, since longitude/latitude only makes sense in in that case).
• geoRectangleBbox Bbox Bounding box of the rotated rectangle of the viewport, in longitude/latitude coordinates.
• projectedGeoCenter Point Center point of the viewport, in projected geo coordinates.
• projectedGeoRectangle Rectangle Rotated rectangle of the viewport point, in projected geo coordinates.
• projectedGeoSize Size Size of the viewport in projected geo coordinates, as [width, height]. (This is not the size of the bounding box of the rotated rectangle, but the width and hight of the rectangle).
• projectedGeoRectangleBbox Bbox Bounding box of the rotated rectangle of the viewport, in projected geo coordinates.
• rotation number Rotation of the viewport with respect to the projected coordinate system.
• projectedGeoPerViewportScale number Resolution of the viewport, in projected geo coordinates per viewport pixel.
• viewportCenter Point Center point of the viewport, in viewport pixels.
• viewportRectangle Rectangle Rectangle of the viewport point, in viewport pixels.
• viewportSize Size Size of the viewport in viewport pixels, as [width, height].
• viewportBbox Bbox Bounding box of the viewport, in viewport pixels.
• devicePixelRatio number The devicePixelRatio of the viewport.
• canvasCenter Point Center point of the HTMLCanvasElement of the viewport, in canvas pixels.
• canvasRectangle Rectangle Rectangle of the HTMLCanvasElement of the viewport, in canvas pixels.
• canvasSize Size Size of the HTMLCanvasElement of the viewport in canvas pixels (viewportSize*devicePixelRatio), as [width, height].
• canvasBbox Bbox Bounding box of the HTMLCanvasElement of the viewport, in canvas pixels.
• projectedGeoPerCanvasScale number Scale of the viewport, in projected geo coordinates per canvas pixel (resolution/devicePixelRatio).
• projectedGeoToViewportTransform Transform Transform from projected geo coordinates to viewport pixels. Equivalent to OpenLayers coordinateToPixelTransform.
• projectedGeoToClipTransform Transform Transform from projected geo coordinates to WebGL coordinates in the [-1, 1] range. Equivalent to OpenLayers projectionTransform.

computeProjectedGeoRectangle

Returns a rotated rectangle in projected geo coordinates

Parameters

• projectedGeoCenter
• projectedGeoPerViewportScale
• rotation
• viewportSize

TileCache

Extends EventTarget

A class for caches of tiles.

Type: TileCache

getCacheableTile

Get a specific cacheable tile in this cache I.e. independent of whether their fetching is completed and image bitmap is created

Parameters

• tileUrl string the url of the requested tile

Returns (CacheableTile | undefined)

getCachedTile

Get a specific cached tile in this cache I.e. with their fetching completed and image bitmap created

Parameters

• tileUrl string the url of the requested tile

Returns (CachedTile | undefined)

getCacheableTiles

Get the tiles in this cache (independent of whether their caching has completed)

Returns IterableIterator<CacheableTile>

getCachedTiles

Get the tiles in this cache whose caching has completed I.e. their fetching is completed and image bitmap is created

Returns Array<CacheableTile>

getTileUrls

Get the urls of all tiles in this cache

Returns IterableIterator[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

requestFetcableMapTiles

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

Parameters

• requestedTiles Array<FetchableMapTile>

CacheableTile

Extends EventTarget

Class for tiles that can be cached. These are used on the tile cache (and are not associated to a specific map)

Type: CacheableTile

fetch

Fetch the tile and create its image bitmap.

Returns and event when completed (or error).

Returns (Promise\ | void)

isCachedTile

Whether a tile has completed its caching I.e. their fetching is completed and image bitmap is created

abort

Abort the fetch

CachedTile

Extends CacheableTile

Class for cacheable tiles whose caching has been completed I.e. their fetching is completed and image bitmap is created

Type: CachedTile

FetchableMapTile

Class for tiles associated to a warped map. These are used to describe the tiles requested by the renderer.

Type: FetchableMapTile

WebGL2Renderer

Extends EventTarget

Class that render warped maps to a HTML canvas element using WebGL 2

Its main function is render

Type: WebGL2Renderer

getOpacity

Get the opacity of the renderer

Returns (number | undefined)

setOpacity

Set the opacity of the renderer

Parameters

• opacity number opacity to set

resetOpacity

Reset the opacity of the renderer

getMapOpacity

Get the opacity of a map

Parameters

• mapId string ID of the map

Returns (number | undefined)

setMapOpacity

Set the opacity of a map

Parameters

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

resetMapOpacity

Rreset the opacity of a map

Parameters

• mapId string ID of the map

getRemoveColorOptions

Get the remove color options of the renderer

Returns (Partial\ | undefined)

setRemoveColorOptions

Set the remove color options of the renderer

Parameters

• removeColorOptions RemoveColorOptions

resetRemoveColorOptions

Reset the remove color options of the renderer

getMapRemoveColorOptions

Get the remove color options of a map

Parameters

• mapId string ID of the map

Returns (Partial\ | undefined)

setMapRemoveColorOptions

Set the remove color options of a map

Parameters

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

resetMapRemoveColorOptions

Reset the remove color options of a map

Parameters

• mapId string ID of the map

getColorizeOptions

Get the colorize options of the renderer

Returns (Partial\ | undefined)

setColorizeOptions

Set the colorize options of the renderer

Parameters

• colorizeOptions ColorizeOptions the colorize options to set

resetColorizeOptions

Reset the colorize options of the renderer

getMapColorizeOptions

Get the colorize options of a map

Parameters

• mapId string ID of the map

Returns (Partial\ | undefined)

setMapColorizeOptions

Set the colorize options of a map

Parameters

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

resetMapColorizeOptions

Reset the colorize options of a map

Parameters

• 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

• saturation the satuation to set

resetSaturation

Reset the satuation of the renderer

getMapSaturation

Get the saturation of a map

Parameters

• mapId string ID of the map

Returns (number | undefined)

setMapSaturation

Set the saturation of a map

0 - grayscale, 1 - original colors

Parameters

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

resetMapSaturation

Reset the saturation of a map

Parameters

• mapId string ID of the map

render

Render the map for a given viewport

Parameters

• viewport Viewport the current viewport

WebGL2WarpedMap

Extends EventTarget

Class for storing the WebGL2 information necessary to draw WarpedMaps

Type: WebGL2WarpedMap

updateVertexBuffers

Update the vertex buffers of this warped map

Parameters

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

addCachedTileAndUpdateTextures

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

Parameters

• cachedTile CachedTile

removeCachedTileAndUpdateTextures

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

Parameters

• tileUrl string

DEFAULT_TARGET_SCALE_FACTOR_CORRECTION

Target scale factor correction Since this is done before comparing logarithmic evaluations of the target and available scale factors (to find the best fit), this has more effect on small scale factors. 0 = no correction, -1 = correct target scale factor with -1 to obain less sharp images (especially at low scale factors), 1 = idem with correction +1, ...

Type: number

getBestTileZoomLevelForScale

Returns the best TileZoomLevel for a given resource-to-canvas scale.

Parameters

• image Image A parsed IIIF Image
• resourceToCanvasScale number The resource to canvas scale, relating resource pixels to canvas pixels.
• targetScaleFactorCorrection (optional, default DEFAULT_TARGET_SCALE_FACTOR_CORRECTION)

Returns TileZoomLevel