@allmaps/render

Plugin that renders georeferenced maps in a warped fashion on an HTML canvas element.

Currently, only rendering using the WebGL2 API is implemented. In the future, rendering using the Canvas API might be implemented as well.

For practical implementations in webmapping libraries, see the @allmaps/openlayers, @allmaps/leaflet anc @allmaps/maplibre packages.

How it works

A renderer accomplishes this task using a set of properties it is assigned at it's creation:

• 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 it's WebGL2RenderingContext when it's render() function is called and passed a Viewport (e.g. by a JS mapping library). Then, for each WarpedMap is the WarpedMapList, the following happens:

• The Ground Control Points are read from the Georeference Annotation, and using those a warping transformation is computed from IIIF resource pixels to projected geo 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 level to use.
• The Viewport is transformed (warped) backwards from projected geo coordinates to the resource 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 Ground Control Points.

Installation

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

Install with npm:

npm install @allmaps/render

And load using:

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

You can build this package using

pnpm run build

Usage

API

Table of Contents

• WarpedMapWithImageInfo
• WarpedMapList
  • getMaps
  • getWarpedMap
  • getMapZIndex
  • getTotalBbox
  • getTotalProjectedGeoMaskBbox
  • 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_SCALE_FACTOR_SHARPENING
• 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>

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)

getTotalBbox

Return the total Bbox of all visible maps in this list, in geo coordinates

Returns (Bbox | undefined)

getTotalProjectedGeoMaskBbox

Return the total Bbox of all visible maps in this list, in projectedGeo coordinates

Returns (Bbox | undefined)

getMapsByGeoBbox

Returns mapId's of the maps whose geoBbox overlaps with the specified geoBbox.

Parameters

• geoBbox Bbox

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

sendMapsToBack

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

Parameters

• mapIds Iterable<string>

bringMapsForward

Changes the zIndex of the specified maps to bring them forward

Parameters

• mapIds Iterable<string>

sendMapsBackward

Changes the zIndex of the specified maps to send them backward

Parameters

• mapIds Iterable<string>

showMaps

Changes the visibility of the specified maps to true

Parameters

• mapIds Iterable<string>

hideMaps

Changes the visibility of the specified maps to false

Parameters

• mapIds Iterable<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 lon lat geo coordinates.
• geoRectangle Rectangle Rotated rectangle (possibly quadrilateral) of the viewport point, in lon lat geo coordinates.
• geoSize Size Size of the viewport in lon lat geo coordinates, as [width, height]. (This is the size of the bbox of the rectangle, since lon lat only makes sense in in that case).
• geoBbox Bbox Bbox of the rotated rectangle of the viewport, in lon lat geo 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 bbox of the rotated rectangle, but the width and hight of the rectangle).
• projectedGeoBbox Bbox Bbox 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 Bbox 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 Bbox 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 OpenLayer coordinateToPixelTransform.
• projectedGeoToClipTransform Transform Transform from projected geo coordinates to webgl2 coordinates in the [-1, 1] range. Equivalent to OpenLayer 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>

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 it's image bitmap.

Returns and event when completed (or error).

Returns (Promise<ImageBitmap> | void)

isCachedTile

Whether a tile has completed it's 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 for renderers that render warped maps to a HTML canvas element using WebGL2

It's 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<RemoveColorOptions> | 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<RemoveColorOptions> | 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<ColorizeOptions> | 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<ColorizeOptions> | 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_SCALE_FACTOR_SHARPENING

Scale factor sharpening: 1 = no sharpening, 2 = one level extra sharper, 4 = two levels extra sharper, 1/2 = one level less sharp ...

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.
• scaleFactorSharpening (optional, default DEFAULT_SCALE_FACTOR_SHARPENING)

Returns TileZoomLevel