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:
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.
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
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.
- WarpedMapWithImageInfo
- WarpedMapList
- getMaps
- getWarpedMap
- getMapZIndex
- getBbox
- getProjectedBbox
- getMapsByGeoBbox
- setImageInfoCache
- setMapResourceMask
- setMapsTransformationType
- bringMapsToFront
- sendMapsToBack
- bringMapsForward
- sendMapsBackward
- showMaps
- hideMaps
- addGeoreferencedMap
- removeGeoreferencedMap
- addGeoreferenceAnnotation
- removeGeoreferenceAnnotation
- Viewport
- TileCache
- CacheableTile
- 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
- DEFAULT_TARGET_SCALE_FACTOR_CORRECTION
- getBestTileZoomLevelForScale
Extends WarpedMap
Class for warped maps with image ID and parsed IIIF image.
Type: WarpedMapWithImageInfo
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
Returns mapIds for the maps in this list.
Returns Iterable<string>
Returns the WarpedMap object in this list of map specified by a mapId.
mapId
string
Returns (WarpedMap | undefined)
Returns the zIndex of a map.
mapId
string
Return the bounding box of all visible maps in this list, in longitude/latitude coordinates
Returns (Bbox | undefined)
Return the bounding box of all visible maps in this list, in projected coordinates
Returns (Bbox | undefined)
Returns mapIds of the maps whose geoBbox overlaps with the specified geoBbox.
geoBbox
Bbox
Returns Iterable<string>
Sets the image info cache
cache
Cache the image info cache
Sets the resource mask for a specified map
mapId
string ID of the mapresourceMask
Ring the new resource mask
Sets the transformation type of specified maps
mapIds
Iterable<string> the IDs of the mapstransformationType
TransformationType the new transformation type
Changes the zIndex of the specified maps to bring them to front
mapIds
Iterable<string>
Changes the zIndex of the specified maps to send them to back
mapIds
Iterable<string>
Changes the zIndex of the specified maps to bring them forward
mapIds
Iterable<string>
Changes the zIndex of the specified maps to send them backward
mapIds
Iterable<string>
Changes the visibility of the specified maps to true
mapIds
Iterable<string>
Changes the visibility of the specified maps to false
mapIds
Iterable<string>
Adds a georeferenced map to this list
georeferencedMap
unknown
Returns Promise<(string | Error)>
Removes a georeferenced map from this list
georeferencedMap
unknown
Returns Promise<(string | Error)>
Parses an annotation and adds its georeferenced map to this list
annotation
unknown
Returns Promise<Array<(string | Error)>>
Parses an annotation and removes its georeferenced map from this list
annotation
unknown
Returns Promise<Array<(string | Error)>>
Extends EventTarget
The viewport describes the view on the rendered map.
Type: Viewport
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.
Returns a rotated rectangle in projected geo coordinates
projectedGeoCenter
projectedGeoPerViewportScale
rotation
viewportSize
Extends EventTarget
A class for caches of tiles.
Type: TileCache
Get a specific cacheable tile in this cache I.e. independent of whether their fetching is completed and image bitmap is created
tileUrl
string the url of the requested tile
Returns (CacheableTile | undefined)
Get a specific cached tile in this cache I.e. with their fetching completed and image bitmap created
tileUrl
string the url of the requested tile
Returns (CachedTile | undefined)
Get the tiles in this cache (independent of whether their caching has completed)
Returns IterableIterator<CacheableTile>
Get the tiles in this cache whose caching has completed I.e. their fetching is completed and image bitmap is created
Returns Array<CacheableTile>
Get the urls of all tiles in this cache
Returns IterableIterator<string>
Process the request for new tiles to be added to this cache
requestedTiles
Array<FetchableMapTile>
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 the tile and create its image bitmap.
Returns and event when completed (or error).
Returns (Promise<ImageBitmap> | void)
Whether a tile has completed its caching I.e. their fetching is completed and image bitmap is created
Abort the fetch
Extends CacheableTile
Class for cacheable tiles whose caching has been completed I.e. their fetching is completed and image bitmap is created
Type: CachedTile
Class for tiles associated to a warped map. These are used to describe the tiles requested by the renderer.
Type: FetchableMapTile
Extends EventTarget
Class that render warped maps to a HTML canvas element using WebGL 2
Its main function is render
Type: WebGL2Renderer
Get the opacity of the renderer
Set the opacity of the renderer
opacity
number opacity to set
Reset the opacity of the renderer
Get the opacity of a map
mapId
string ID of the map
Set the opacity of a map
Rreset the opacity of a map
mapId
string ID of the map
Get the remove color options of the renderer
Returns (Partial<RemoveColorOptions> | undefined)
Set the remove color options of the renderer
removeColorOptions
RemoveColorOptions
Reset the remove color options of the renderer
Get the remove color options of a map
mapId
string ID of the map
Returns (Partial<RemoveColorOptions> | undefined)
Set the remove color options of a map
mapId
string ID of the mapremoveColorOptions
RemoveColorOptions the 'remove color options' to set
Reset the remove color options of a map
mapId
string ID of the map
Get the colorize options of the renderer
Returns (Partial<ColorizeOptions> | undefined)
Set the colorize options of the renderer
colorizeOptions
ColorizeOptions the colorize options to set
Reset the colorize options of the renderer
Get the colorize options of a map
mapId
string ID of the map
Returns (Partial<ColorizeOptions> | undefined)
Set the colorize options of a map
mapId
string ID of the mapcolorizeOptions
ColorizeOptions the colorize options to set
Reset the colorize options of a map
mapId
string ID of the map
Get the saturation of the renderer
Returns number
Set the saturation of the renderer
0 - grayscale, 1 - original colors
saturation
the satuation to set
Reset the satuation of the renderer
Get the saturation of a map
mapId
string ID of the map
Set the saturation of a map
0 - grayscale, 1 - original colors
mapId
ID of the mapsaturation
the saturation to set
Reset the saturation of a map
mapId
string ID of the map
Render the map for a given viewport
viewport
Viewport the current viewport
Extends EventTarget
Class for storing the WebGL2 information necessary to draw WarpedMaps
Type: WebGL2WarpedMap
Update the vertex buffers of this warped map
projectedGeoToClipTransform
Transform Transform from projected geo coordinates to webgl2 coordinates in the [-1, 1] range. Equivalent to OpenLayer projectionTransform.
Add cached tile to the textures of this map and update textures
cachedTile
CachedTile
Remove cached tile from the textures of this map and update textes
tileUrl
string
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
Returns the best TileZoomLevel for a given resource-to-canvas scale.
image
Image A parsed IIIF ImageresourceToCanvasScale
number The resource to canvas scale, relating resource pixels to canvas pixels.targetScaleFactorCorrection
(optional, defaultDEFAULT_TARGET_SCALE_FACTOR_CORRECTION
)
Returns TileZoomLevel