1.0.0-beta.44 • Published 3 weeks ago

@allmaps/warpedmaplayer

Licence

MIT

Version

1.0.0-beta.44

Deps

Size

98 kB

Vulns

Weekly

Stars

143

Summary Dependency Versions

@allmaps/warpedmaplayer

Base class for Allmaps plugins. This class contains the main logic for the WarpedMapLayer class exported by the Leaflet, OpenLayers and MapLibre plugins for Allmaps, which allow displaying georeferenced IIIF images on a webmap. These plugins work by loading Georeference Annotations and use WebGL to transform images from a IIIF image server to overlay them on their correct geographical position.

How it works

This plugin creates a new class WarpedMapLayer which extends or is implemented by the Layer classes of the webmap libraries Leaflet, OpenLayers and MapLibre. Where it extends (MapLibre), the methods defined in this package are inherited automatically. Where it is implemented (Leaflet and OpenLayers) any changes to these methods should be copy-pasted to the implementing classes (see comments in the code).

To understand what happens under the hood for each georeferenced map, see the @allmaps/render package.

Installation

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

Install with pnpm:

pnpm install @allmaps/warpedmaplayer

You can optionally build this package locally by running:

pnpm run build

Usage

This package contains the main logic for the WarpedMapLayer class exported by the Allmaps plugins for Leaflet, OpenLayers and MapLibre. It should not be used directly. See the readme of the plugins for more usage information.

Use this readme to understand the API of the WarpedMapLayer methods shared between the plugins, including event types emitted by a WarpedMapLayer instance and a list of available options.

Events

The following events are emitted by the native map object to inform you of the state of the WarpedMapLayer.

Type	Description
`imageinfosadded`	Image infos have been directly added into the warped map list
`georeferenceannotationadded`	A georeference annotation has been added to the warped map list
`georeferenceannotationremoved`	A georeference annotation has been removed from the warped map list
`warpedmapadded`	A warped map has been added to the warped map list
`warpedmapremoved`	A warped map has been removed from the warped map list
`warpedmapentered`	A warped map has entered the viewport
`warpedmapleft`	A warped map has left the viewport
`imageloaded`	An image was loaded for a map from cache or by fetching image info
`maptilesloadedfromsprites`	Tiles have been loaded to the tile cache from a fetched sprites image map
`maptileloaded`	A tile has been loaded to the tile cache for a map
`maptiledeleted`	A tile has been deleted from the tile cache for a map
`firstmaptileloaded`	The cache loaded a first tile of a map
`requestedtilesloading`	New tiles requested for the current viewport started loading
`allrequestedtilesloaded`	All tiles requested for the current viewport have been loaded
`cleared`	The warped map list has been cleared
`preparechange`	An upcoming options change has been prepared for a specific map (by mixing previous and new properties if the animation was ongoing)
`immediatechange`	An options change has been processed immediately
`animatedchange`	An options change has been processed with an animation

Event data follows the Partial<WarpedMapEventData> type:

export type WarpedMapEventData = {
  mapIds: string[]
  tileUrl: string
  optionKeys: string[]
  spritesInfo: SpritesInfo
}

Options

Options can be set on a WarpedMapLayer both as layer options, which apply to all maps, or as individual map options. For each map, the final options that are applied to it result from merging the default options, options specified in the georeference annotation (like resourceMask, transformationType, internalProjection and gcps), layer options and map options. When merging options, undefined options are neglected, so setting a layer or map option to undefined effectively resets it.

The following options are available:

Key	Description	Default
`applyMask`	Apply the resource mask (if false, the full mask is used)	`true`
`colorize`	Colorize the map	`false`
`colorizeColor`	Color to colorize the map	`"#ff56ba"`
`debugTiles`	Debug: show the tile boundaries	`false`
`debugTriangles`	Debug: show the triangulation triangles	`false`
`distortionColor00`	First color in the `'log2sigma'` distortion	`"#fe5e60"`
`distortionColor01`	Second color in the `'log2sigma'` distortion	`"#3b44ad"`
`distortionColor1`	Color in the `'twoOmega'` distortion	`"#64c18f"`
`distortionColor2`	Color in the `'airyKavr'` distortion	`"#ffc742"`
`distortionColor3`	Color in the `'signDetJ'` distortion	`"#fe5e60"`
`distortionMeasures`	Distortion measures to be computed	`['log2sigma', 'twoOmega']`
`gcps`	Ground control points	`[]` (overwritten by the GCPs in the georeference annotation)
`internalProjection`	Internal projection (see @allmaps/project)	`WebMercatorProjection` (possibly overwritten by the internal projection in the georeference annotation)
`opacity`	Opacity	`1`
`projection`	Projection (see @allmaps/project)	`WebMercatorProjection`
`removeColor`	Remove color	`false`
`removeColorColor`	Color to remove	`"#222222"`
`removeColorHardness`	Hardness when removing color	`0.7`
`removeColorThreshold`	Threshold when removing color	`0`
`renderAppliableMask`	Render the appliable mask, which is the resource mask as specified in the georeferenced annotation (or options), even when the mask is not applied (see the `applyMask` option) and the full mask is used	`false`
`renderAppliableMaskColor`	Color when rendering the appliable mask	`"#ff56ba"`
`renderAppliableMaskSize`	Size in viewport pixels when rendering the appliable mask	`8`
`renderFullMask`	Render the full mask	`false`
`renderFullMaskColor`	Color when rendering the full mask	`"#64c18f"`
`renderFullMaskSize`	Size in viewport pixels when rendering the full mask	`8`
`renderGcps`	Render the GCPs	`false`
`renderGcpsColor`	Color when rendering the GCPs	`"#63d8e6"`
`renderGcpsSize`	Size in viewport pixels when rendering the GCPs	`16`
`renderGrid`	Render the grid	`false`
`renderGridColor`	Color when rendering the grid	`"#222222"`
`renderMask`	Render the mask	`false`
`renderMaskColor`	Color when rendering the mask	`"#ff56ba"`
`renderMaskSize`	Size in viewport pixels when rendering the mask	`8`
`renderTransformedGcps`	Render the transformed GCPs	`false`
`renderTransformedGcpsColor`	Color when rendering the transformed GCPs	`"#ff56ba"`
`renderTransformedGcpsSize`	Size in viewport pixels when rendering the transformed GCPs	`16`
`renderVectors`	Render the vectors connecting each GCP with its respective transformed GCP	`false`
`renderVectorsColor`	Color when rendering the vectors	`"#222222"`
`renderVectorsSize`	Size in viewport pixels when rendering the vectors	`6`
`resourceMask`	Resource mask	`[]` (overwritten by the resource mask in the georeference annotation)
`saturation`	Saturation	`1`
`transformationType`	Transformation type	`"polynomial"` (possibly overwritten by the transformation type in the georeference annotation)
`visible`	Visible	`true`

What is a map?

Leaflet, OpenLayer and MapLibre each have their concept of a 'map' as the central class their API (see Leaflet Map, OpenLayers Map and MapLibre Map). It generally refers to a <div> an a page where tiles or WebGL logic is used to render a projection of the world.

In Allmaps the concept 'map' is rather related to a Georeference Annotation. There are different classes named 'map', one for each phase a map takes through the Allmaps rendering pipeline:

When a Georeference Annotation is parsed, an instance of the GeoreferencedMap class is created from it.
When this map is loaded into an application for rendering, an instance of the WarpedMap class is created from it.
Inside the WebGL2 Renderer, the WebGL2WarpedMap class is used to render the map.

All these map phases originating from the same Georeference Annotation have the same unique mapId property. This string value is used though-out Allmaps (and in the API below) to identify a map. It is returned after adding a georeference annotation to a warpedMapLayer, so you can use it later to call functions on a specific map.

Note that since a WarpedMapLayer can load multiple Georeference Annotations, we could have multiple Allmaps 'maps' on e.g. one Leaflet 'map'.

License

MIT

API

`new BaseWarpedMapLayer(defaultSpecificWarpedMapLayerOptions, options)`

Creates a WarpedMapLayer instance