@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

Table of Contents

• Generating & parsing Georeference Annotations
  • parseAnnotation
  • generateAnnotation
• Types
  • Map
  • Annotation
  • AnnotationPage

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

Types

The two types this module converts between, Annotation, AnnotationPage and Map, are described below.

Map

Object that contains the data needed to georeference a IIIF resource in the format that is used by Allmaps internally.

Type: Object

Annotation

Web Annotation that contains a single Georeference Annotation.

Type: Object

AnnotationPage

An Annotation Page that contains multiple Georeference Annotations.

Type: Object