Skip to content
Allmaps
Getting started

@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

Annotation

Type
{ type: "Annotation"; target: { type: "SpecificResource"; source: { type: "ImageService1" | "ImageService2" | "ImageService3"; height: number; width: number; '@id': string; partOf?: Array<PartOfItem> | undefined; } | { ...; } | { ...; }; selector: { ...; }; }; ... 5 more ...; motivation?: string | undefined; }

AnnotationPage

Type
{ type: "AnnotationPage"; items: Array<{ type: "Annotation"; target: { type: "SpecificResource"; source: { type: "ImageService1" | "ImageService2" | "ImageService3"; height: number; width: number; '@id': string; partOf?: Array<PartOfItem> | undefined; } | { ...; } | { ...; }; selector: { ...; }; }; ... 5 more ...; m...

AnnotationPageSchema

Type
AnnotationPage1Schema

AnnotationSchema

Type
Annotation1Schema

FeaturePropertiesSchema

Type
Annotation1FeaturePropertiesSchema

GCPSchema

Type
GeoreferencedMap2GCPSchema

GeoreferencedMap

Type
{ type: "GeoreferencedMap"; resource: { type: "ImageService1" | "ImageService2" | "ImageService3" | "Canvas"; id: string; height?: number | undefined; width?: number | undefined; partOf?: Array<PartOfItem> | undefined; }; ... 6 more ...; transformation?: { ...; } | undefined; }

GeoreferencedMapSchema

Type
GeoreferencedMap2Schema

GeoreferencedMapsSchema

Type
GeoreferencedMaps2Schema

ResourceSchema

Type
GeoreferencedMap2ResourceSchema

SvgSelectorSchema

Type
SvgSelector1Schema

generateAnnotation(mapOrMaps)

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

Parameters
  • mapOrMaps (unknown)
    • Single Georeferenced Map, or an array of Georeferenced Maps
Returns

Georeference Annotation ({ type: "Annotation"; target: { type: "SpecificResource"; source: { type: "ImageService1" | "ImageService2" | "ImageService3"; height: number; width: number; '@id': string; partOf?: Array<PartOfItem> | undefined; } | { ...; } | { ...; }; selector: { ...; }; }; ... 5 more ...; motivation?: string | undefined; } | { ....).

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


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

parseAnnotation(annotation)

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

Parameters
  • annotation (unknown)
    • Georeference Annotation or AnnotationPage containing multiple Georeference Annotations
Returns

Array of maps (Array<{ type: "GeoreferencedMap"; resource: { type: "ImageService1" | "ImageService2" | "ImageService3" | "Canvas"; id: string; height?: number | undefined; width?: number | undefined; partOf?: Array<PartOfItem> | undefined; }; ... 6 more ...; transformation?: { ...; } | undefined; }>).

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


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

validateAnnotation(annotation)

Parameters
  • annotation (unknown)
Returns

{ type: "Annotation"; target: { type: "SpecificResource"; source: { type: "ImageService1" | "ImageService2" | "ImageService3"; height: number; width: number; '@id': string; partOf?: Array<PartOfItem> | undefined; } | { ...; } | { ...; }; selector: { ...; }; }; ... 5 more ...; motivation?: string | undefined; } | { .....

validateGeoreferencedMap(mapOrMaps)

Parameters
  • mapOrMaps (unknown)
Returns

{ type: "GeoreferencedMap"; resource: { type: "ImageService1" | "ImageService2" | "ImageService3" | "Canvas"; id: string; height?: number | undefined; width?: number | undefined; partOf?: Array<PartOfItem> | undefined; }; ... 6 more ...; transformation?: { ...; } | undefined; } | Array<{ type: "GeoreferencedMap"; re....