@allmaps/annotation NPM

@allmaps/annotation

@allmaps/annotation is a JavaScript module that can generate and parse Georeference Annotations.

A Georeference Annotation is a Web Annotation that stores the metadata needed to georeference a IIIF image.

A Georeference Annotation contains the following data:

The URI of an IIIF Image, as well as its dimensions in pixels.
A list of ground control points (GCPs) that define the mapping between resource coordinates and geospatial coordinates.
A polygonal resource mask that defines the cartographic part of the image.

Georeference Annotations are a core part of Allmaps. For example, Allmaps Viewer can warp maps IIIF maps in the browser, just by loading a georeference annotation.

Installation & usage

This is an ESM-only module that works in browsers and Node.js.

Node.js:

First, run npm install @allmaps/annotation to add this module to your project.

import { parseAnnotation, generateAnnotation } from '@allmaps/annotation'

Browser:

<script type="module">
  import {
    parseAnnotation,
    generateAnnotation
  } from 'https://unpkg.com/@allmaps/annotation?module'
</script>

API

Generating & parsing Georeference Annotations

parseAnnotation

Parses a Georeference Annotation or an AnnotationPage containing multiple Georeference Annotations and returns an array of maps.

Parameters

annotation (Annotation | AnnotationPage) Georeference Annotation or AnnotationPage containing multiple Georeference Annotations

Examples

import fs from 'fs'
import { parseAnnotation } from '@allmaps/annotation'

const annotation = JSON.parse(fs.readFileSync('./examples/annotation.example.json'))
const maps = parseAnnotation(annotation)

Returns Array<Map> Array of maps

generateAnnotation

Generates a Georeference Annotation from a single map or an AnnotationPage containing multiple Georeference Annotations from an array of maps.

Parameters

mapOrMaps (Map | Array<Map>) Single map object, or array of maps

Examples

import fs from 'fs'
import { generateAnnotation } from '@allmaps/annotation'

const map = JSON.parse(fs.readFileSync('./examples/map.example.json'))
const annotation = generateAnnotation(map)

Returns (Annotation | AnnotationPage) Georeference Annotation