annotation

@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. The IIIF community is working on a turning georeference annotations into a specification and a IIIF extension.

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 pixels and geospatial coordinates.
• A polygonal pixel mask that defines the cartographic part of the image.

Georeference annotation 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 or in 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
    • Parameters
    • Examples
  • generateAnnotation
    • Parameters
    • Examples
• Types
  • Map
  • Annotation

Generating & parsing georeference annotations

parseAnnotation

Parses a georeference annotation and returns an array of maps.

Parameters

• annotation Annotation Georeference annotation

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 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 Georeference annotation

Types

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

Map

Object that contains the data needed to georeference a IIIF map. For details, see its JSON Schema or the example in the examples directory.

Type: Object

Annotation

Web Annotation that contains a single georeference annotation or an Annotation Page with georeference annotation. For details, see its JSON Schema or the example in the examples directory.

Type: Object