1.0.0-beta.83 • Published 3 months ago

@allmaps/render

Licence

MIT

Version

1.0.0-beta.83

Deps

Vulns

Weekly

Stars

140

Summary Dependency Versions

@allmaps/render

Allmaps render module. Renders georeferenced IIIF maps specified by a Georeference Annotation.

The following renderers are implemented:

CanvasRenderer: renders WarpedMaps to a HTML Canvas element with the Canvas 2D API
WebGL2Renderer: renders WarpedMaps to a WebGL 2 context
IntArrayRenderer: renders WarpedMaps to an IntArray

This module is mainly used in the Allmaps pipeline by the following packages:

It is also used in the Allmaps Preview worker and Allmaps Tile Server proxy server, both of which use the WasmRenderer, a WASM implementation of the CanvasRenderer.

How it works

The render module accomplishes this task with the following classes:

All renderers use the concept of a Viewport, describing coordinate reach that should be rendered. Create a viewport using it's constructor or the static methods in the Viewport class. The CanvasRenderer and WebGL2Renderer can deduce a viewport from the current WarpedMapList and the size of their (WebGL2-enabled) canvas.
All renderers extend the BaseRenderer class, which implements the general actions of the (automatically throttled) render() calls: checking which maps are inside the current viewport, initially loading their image informations, checking which zoomlevel corresponds to the viewport, getting the IIIF tiles of that zoomlevel that are within the viewport.
- For the WebGL2Renderer, a WebGL2RenderingContext contains the rendering context for the drawing surface of an HTML element, and a WebGLProgram stores the vertex and fragment shader used for rendering a map, its lines and points.
A WarpedMap is made from every Georeferenced Map (which in term are parsed Georeference Annotations) and is added to the renderer and hence to its warpedMapList. It contains useful properties like mask, center, size ... in resource, geospatial and projected geospatial coordinates. It contains a copy of the ground control points (GCPs) and resource masks, a projected version of the GCPs, a transformation built using the latter and usable to transform points from IIIF resource coordinates to projected geospatial coordinates.
- If WebGL2Renderer is used, a TriangulatedWarpedMap is created for every WarpedMap, finely triangulating the map, and a WebGL2WarpedMap is created, containing the WebGL2 information of the map (buffers etc.).
A WarpedMapList contains the list of WarpedMaps to draw and uses an RTree for geospatial map lookup.
A TileCache fetches and stores the image data of cached IIIF tiles.

From Georeference Annotation to a rendered map

During a CanvasRenderer or IntArrayRenderer render call, a map undergoes the following steps from Georeference Annotation to the canvas:

For each viewport pixel, from its viewport coordinates its projected geospatial coordinates are obtained and transformed to its corresponding resource coordinates, i.e. it's location in the IIIF image.
We find the tile on which this point is located, and express the resource coordinates in local tile coordinates.
We set the color of this pixel from the colors of the four tile pixels surrounding the tile point, through a bilinear interpolation.

During a WebGL2Renderer render call, a map undergoes the following steps from Georeference Annotation to the canvas:

The resource mask is triangulated: the area within is divided into small triangles.
The optimal tile zoom level for the current viewport is searched, 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 where to render each triangle 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 optionally build this package locally by running:

pnpm run build

The easiest way to test this package during local development is via @allmaps/test-plugins, since all of the plugins use the WebGL2Renderer to render a Georeference Annotation on screen.

Usage

Here's how each of the renderers can be used directly:

CanvasRenderer

import { CanvasRenderer } from '@allmaps/render/canvas'

// Create a canvas and set your desired width and height
const canvas = document.getElementById('canvas')
canvas.width = width // Your width
canvas.height = height // Your height

// Create a renderer from your canvas
const renderer = new CanvasRenderer(canvas)

// Fetch and parse an annotation
const annotationUrl = 'https://annotations.allmaps.org/images/4af0fa9c8207b36c'
const annotation = await fetch(annotationUrl).then((response) =>
  response.json()
)

// Add the annotation to the renderer
await renderer.addGeoreferenceAnnotation(annotation)

// Render
// Note: no viewport specified, so one will be deduced. See below.
await renderer.render()

Notes:

Maps with strong warping may appear to not exactly follow the specified viewport. This is due the backwards transform being explicitly used in the CanvasRenderer and IntArrayRenderer (and not in the WebGL2Renderer). For maps with strong warping, the backwards transform is currently not exact (even for polynomial transformations).

WebGL2Renderer

import { WebGL2Renderer } from '@allmaps/render/webgl2'

// Create a canvas and set your desired width and height
const canvas = document.getElementById('canvas')
canvas.width = width // Your width
canvas.height = height // Your height

// Get the webgl context of your canvas
const gl = canvas.getContext('webgl2', { premultipliedAlpha: true })

// Create a renderer from your canvas
const renderer = new WebGL2Renderer(gl)

// Fetch and parse an annotation
const annotationUrl = 'https://annotations.allmaps.org/images/4af0fa9c8207b36c'
const annotation = await fetch(annotationUrl).then((response) =>
  response.json()
)

// Add the annotation to the renderer
await renderer.addGeoreferenceAnnotation(annotation)

// Render
// Note: no viewport specified, so one will be deduced. See below.
renderer.render()

Notes: the WebGL2Renderer is not fully functional yet.

The WebGL2Renderer works with events which are meant to trigger re-renders. This logic can currently be implemented outside of this library (see the plugins), and will be implemented within this library soon. As this will affect the API, please refrain from using this renderer as described above for now.
The WebGL2Renderer loads images via web-workers. The bundling needs to be optimised to support using this renderer in all possible environments.

IntArrayRenderer

import { IntArrayRenderer } from '@allmaps/render/intarray'

// Create a renderer
// See the IntArrayRenderer constructor for more info
// And the Allmaps Preview application for a concrete example
const renderer =
  new IntArrayRenderer() <
  D > // A data type
  (getImageData, // A function to get the image date from an image
  getImageDataValue, // A function to get the image data value from an image
  getImageDataSize, // A function to get the image data size from an image
  options) // IntArrayRenderer options

const annotationUrl = 'https://annotations.allmaps.org/images/4af0fa9c8207b36c'
const annotation = await fetch(annotationUrl).then((response) =>
  response.json()
)

await renderer.addGeoreferenceAnnotation(annotation)

// Create your viewport (mandatory for this renderer)
const viewport = viewport // Your viewport, see below

const image = await renderer.render(viewport)

Notes:

Maps with strong warping may appear to not exactly follow the specified viewport. This is due the backwards transform being explicitly used in the CanvasRenderer and IntArrayRenderer (and not in the WebGL2Renderer). For maps with strong warping, the backwards transform is currently not exact (even for polynomial transformations).

The render() call of all renderers take a Viewport as input. For the IntArrayRenderer, this argument is required. For the others, it is optional: if unspecified a viewport will be deduced from the canvas size and the warpedMapList formed by the annotations.

A viewport can be created through one of the following options:

Directly using the Viewport constructor:

import { Viewport } from '@allmaps/render'

new Viewport(
  viewportSize, // Your viewport size, as [width, height]
  projectedGeoCenter, // Your center, in geo coordinates
  projectedGeoPerViewportScale, // Your geo-per-viewport scale
  {
    rotation, // Your rotation
    devicePixelRatio, // Your device pixel ratio, e.g. window.devicePixelRatio or just 1
    projection // Your projection (of the above projected geospatial coordinates), as compatible with Proj4js
  }
)

Using one of the following static methods:

Viewport.fromSizeAndMaps()
Viewport.fromSizeAndGeoPolygon()
Viewport.fromSizeAndProjectedGeoPolygon()
Viewport.fromScaleAndMaps()
Viewport.fromScaleAndGeoPolygon()
Viewport.fromScaleAndProjectedGeoPolygon()

For example, to derive a Viewport from a size and maps:

const viewport = Viewport.fromSizeAndMaps(
  viewportSize, // Your viewport size, as [width, height]
  warpedMapList, // Your WarpedMapList, e.g. `renderer.warpedMapList`
  partialExtendedViewportOptions // Your extended viewport options, including viewport options (rotation, devicePixelRatio and projection (used both to retrieve the extent of the maps and for the viewport itself)), a zoom; a fit; and WarpedMapList selection options like mapIds or `onlyVisible`
)

Or, to derive a Viewport from a scale and maps:

const viewport = Viewport.fromScaleAndMaps(
  projectedGeoPerViewportScale, // Your scale
  warpedMapList, // Your WarpedMapList, e.g. `renderer.warpedMapList`
  partialExtendedViewportOptions // Your extended viewport options, including viewport options (rotation, devicePixelRatio and projection (used both to retrieve the extent of the maps and for the viewport itself)), a zoom; and WarpedMapList selection options like mapIds or `onlyVisible`
)

// In this case, resize your canvas to the computed viewport
// before rendering, to encompass the entire image.
canvas.width = viewport.canvasSize[0]
canvas.height = viewport.canvasSize[1]
canvas.style.width = viewport.viewportSize[0] + 'px'
canvas.style.height = viewport.viewportSize[1] + 'px'
context.scale(viewport.devicePixelRatio, viewport.devicePixelRatio)

For usage examples in webmapping libraries, see the source code of the Allmaps plugins for Leaflet, MapLibre and OpenLayers.

Naming conventions

In this package the following naming conventions are used:

viewport... indicates properties described in viewport coordinates (i.e. with pixel size as perceived by the user)
canvas... indicates properties described in canvas coordinates, so viewport device pixel ratio (i.e. with effective pixel size in memory)
resource... indicates properties described in resource coordinates (i.e. IIIF tile coordinates of zoomlevel 1)
geo... indicates properties described in geospatial coordinates (always 'WGS84' projection { description: 'EPSG:4326' } i.e. [lon, lat])
projectedGeo... indicates properties described in projected geospatial coordinates (following a CRS, by default 'EPSG:3857' WebMercator)
tile... indicates properties described IIIF tile coordinates

License

MIT

API

`AnimationOptions`

Fields

animate (boolean)
animatedOptions? (Array< | keyof SpecificWebGL2WarpedMapOptions | keyof SpecificTriangulatedWarpedMapOptions | keyof WarpedMapOptions >)
duration (number)