@allmaps/annotation

Parsing and Generating Georeference Annotations.

How it works

This 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. See this example.

A Georeference Annotation contains the following data:

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

Multiple maps can be defined in an Annotation Page (see spec).

Allmaps offers apps and packages for working with Georeference Annotations. Allmaps Viewer can for example warp IIIF maps in the browser, just by loading a Georeference Annotation.

A Georeferenced Map is the format Allmaps uses internally to describe a map and pass it between functions and packages. It contains the same information in a more practical form. See this example.

This module allows parsing Georeference Annotations to Georeferenced Maps and generating Georeference Annotations from Georeferenced Maps.

This module is written in TypeScript and is built using Zod.

Installation

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

Node.js:

Install with npm:

``sh
npm install @allmaps/annotation
`

Browser:

`html

`

Usage

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

// Fetch an annotation
const annotation = await fetch(annoationUrl).then((response) => response.json())

// Create a georeferencedMap from the annotation
const georeferencedMaps = parseAnnotation(annotation)
const georeferencedMap = georeferencedMaps[0]

// Use or modify the georeferencedMap(s)
// ...

// Generate Georeference Annotation
// Note: returns an annotation or annotation page based on input
const georeferenceAnnotation = generateAnnotation(georeferencedMap)
const georeferenceAnnotationPage = generateAnnotation(georeferencedMaps)
`

See the API below for more details.

License

MIT

API

$3

###### Type

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

$3

###### Type

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

$3

###### Type

`ts
AnnotationPage1Schema
`

$3

###### Type

`ts
Annotation1Schema
`

$3

###### Type

`ts
Annotation1FeaturePropertiesSchema
`

$3

###### Type

`ts
GeoreferencedMap2GCPSchema
`

$3

###### Type

`ts
{ type: "GeoreferencedMap"; resource: { type: "ImageService1" | "ImageService2" | "ImageService3" | "Canvas"; id: string; height?: number | undefined; width?: number | undefined; partOf?: Array | undefined; }; ... 7 more ...; resourceCrs?: { ...; } | undefined; }
`

$3

###### Type

`ts
GeoreferencedMap2Schema
`

$3

###### Type

`ts
GeoreferencedMaps2Schema
`

$3

###### Type

`ts
Array | undefined
`

$3

###### Type

`ts
{
type: string
id: string
label?: Record> | undefined
} & {partOf?: PartOfItem[]}
`

$3

###### Type

`ts
GeoreferencedMap2ResourceSchema
`

$3

###### Type

`ts
SvgSelector1Schema
`

$3

Generates a Georeference Annotation from a single Georeferenced Map or
an Annotation Page containing multiple Georeference Annotations from an array of Georeferenced Maps.

###### Parameters

* mapOrMaps (unknown)
* Single Georeferenced Map, or an array of Georeferenced Maps

###### Returns

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

###### Examples

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

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

$3

Parses a Georeference Annotation or an Annotation Page containing multiple Georeference Annotations
and returns an array of Georeferenced Maps.

###### Parameters

* annotation (unknown)
* Georeference Annotation or Annotation Page 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 | undefined; }; ... 7 more ...; resourceCrs?: { ...; } | undefined; }>).

###### Examples

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

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

$3

###### Parameters

* annotation (unknown)

###### Returns

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

$3

###### Parameters

* mapOrMaps (unknown)

###### Returns

{ type: "GeoreferencedMap"; resource: { type: "ImageService1" | "ImageService2" | "ImageService3" | "Canvas"; id: string; height?: number | undefined; width?: number | undefined; partOf?: Array | undefined; }; ... 7 more ...; resourceCrs?: { ...; } | undefined; } | Array<{ type: "GeoreferencedMap"; resou...`.