# @allmaps/annotation

> Functions for generating and parsing IIIF georeference annotations

Latest version **1.0.0-beta.38** (published 2026-09-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @allmaps/annotation
pnpm add @allmaps/annotation
yarn add @allmaps/annotation
bun add @allmaps/annotation
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.0.0-beta.38 |
| Published | 2026-09-22 |
| First published | 2021-01-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 1 |
| Unpacked size | 475.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 143 |
| Author | Bert Spaan |
| Maintainers | bertspaan |
| Keywords | iiif, georeference, map |

## Links

- npm: https://www.npmjs.com/package/@allmaps/annotation
- Repository: https://github.com/allmaps/allmaps
- Homepage: https://allmaps.org
- Issues: https://github.com/allmaps/allmaps/issues
- npm.io page: https://npm.io/package/@allmaps/annotation

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^4.3.6

## Recent versions

- 1.0.0-beta.38 (latest) — 2026-09-22
- 1.0.0-beta.33 (beta) — 2025-05-22
- 1.0.0-beta.37 — 2026-05-28
- 1.0.0-beta.36 — 2025-11-10
- 1.0.0-beta.35 — 2025-07-09
- 1.0.0-beta.34 — 2025-07-07
- 1.0.0-beta.32 — 2025-03-12
- 1.0.0-beta.30 — 2024-10-31
- 1.0.0-beta.29 — 2024-08-20
- 1.0.0-beta.28 — 2024-08-16
- 1.0.0-beta.27 — 2024-05-29
- 1.0.0-beta.26 — 2024-03-09
- 1.0.0-beta.25 — 2024-03-09
- 1.0.0-beta.22 — 2024-02-09
- 1.0.0-beta.21 — 2024-02-09
- … 38 more at https://npm.io/package/@allmaps/annotation/versions

## README

# @allmaps/annotation

Parsing and Generating Georeference Annotations.

## How it works

This module that can generate and parse [Georeference Annotations](https://iiif.io/api/extension/georef/).

A **Georeference Annotation** is a [Web Annotation](https://www.w3.org/TR/annotation-model/) that stores the metadata needed to [georeference](https://en.wikipedia.org/wiki/Georeferencing) a [IIIF image](https://iiif.io/api/image/3.0/). See this [example](./examples/annotation.example.json).

A Georeference Annotation contains the following data:

* The [URI of an IIIF Image](https://iiif.io/api/image/3.0/#3-identifier), 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](https://iiif.io/api/presentation/3.0/#2-resource-type-overview)).

Allmaps offers apps and packages for working with Georeference Annotations. [Allmaps Viewer](../../apps/viewer/) can [for example](https://viewer.allmaps.org/#data=data%3Atext%2Fx-url%2Chttps%3A%2F%2Fraw.githubusercontent.com%2Fallmaps%2Fannotation%2Fdevelop%2Fexamples%2Fannotation.example.json) 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](./examples/map.example.json).

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.

<!-- TODO: create Observable notebook that allows you to try out this module! -->

## Installation

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

Node.js:

Install with pnpm:

```sh
pnpm install @allmaps/annotation
```

Browser:

```html
<script type="module">
  import { Annotation } from 'https://unpkg.com/@allmaps/annotation?module'
</script>
```

## 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

### `Annotation`

###### Type

```ts
{ id?: string | undefined; type: "Annotation"; '@context'?: string | Array<string> | undefined; motivation?: string | undefined; created?: string | undefined; modified?: string | undefined; target: { ...; }; body: { ...; }; }
```

### `AnnotationPage`

###### Type

```ts
{ id?: string | undefined; type: "AnnotationPage"; '@context'?: string | Array<string> | undefined; items: Array<{ id?: string | undefined; type: "Annotation"; '@context'?: string | Array<string> | undefined; motivation?: string | undefined; created?: string | undefined; modified?: string | undefined; target: { ...;...
```

### `AnnotationPageSchema`

###### Type

```ts
AnnotationPage1Schema
```

### `AnnotationSchema`

###### Type

```ts
Annotation1Schema
```

### `FeaturePropertiesSchema`

###### Type

```ts
Annotation1FeaturePropertiesSchema
```

### `GCPSchema`

###### Type

```ts
GeoreferencedMap2GCPSchema
```

### `GeoreferencedMap`

###### Type

```ts
{ '@context'?: "https://schemas.allmaps.org/map/2/context.json" | undefined; type: "GeoreferencedMap"; id?: string | undefined; created?: string | undefined; modified?: string | undefined; ... 5 more ...; _allmaps?: unknown; }
```

### `GeoreferencedMapSchema`

###### Type

```ts
GeoreferencedMap2Schema
```

### `GeoreferencedMapsSchema`

###### Type

```ts
GeoreferencedMaps2Schema
```

### `PartOf`

###### Type

```ts
Array<PartOfItemType>
```

### `PartOfItem`

###### Type

```ts
{
  id: string
  type: string
  label?: z.infer<typeof LanguageValueSchema>
  partOf?: PartOfItemType[]
}
```

### `ResourceSchema`

###### Type

```ts
GeoreferencedMap2ResourceSchema
```

### `SvgSelectorSchema`

###### Type

```ts
SvgSelector1Schema
```

### `generateAnnotation(mapOrMaps)`

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 (`{ id?: string | undefined; type: "Annotation"; '@context'?: string | Array<string> | undefined; motivation?: string | undefined; created?: string | undefined; modified?: string | undefined; target: { ...; }; body: { ...; }; } | { ...; }`).

###### 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)
```

### `parseAnnotation(annotation)`

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<{ '@context'?: "https://schemas.allmaps.org/map/2/context.json" | undefined; type: "GeoreferencedMap"; id?: string | undefined; created?: string | undefined; modified?: string | undefined; ... 5 more ...; _allmaps?: unknown; }>`).

###### 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)
```

### `validateAnnotation(annotation)`

###### Parameters

* `annotation` (`unknown`)

###### Returns

`{ id?: string | undefined; type: "Annotation"; '@context'?: string | Array<string> | undefined; motivation?: string | undefined; created?: string | undefined; modified?: string | undefined; target: { ...; }; body: { ...; }; } | { ...; }`.

### `validateGeoreferencedMap(mapOrMaps)`

###### Parameters

* `mapOrMaps` (`unknown`)

###### Returns

`Array<{ '@context'?: "https://schemas.allmaps.org/map/2/context.json" | undefined; type: "GeoreferencedMap"; id?: string | undefined; created?: string | undefined; modified?: string | undefined; ... 5 more ...; _allmaps?: unknown; }> | { '@context'?: "https://schemas.allmaps.org/map/2/context.json" | undefined; type...`.

---
_Source: https://npm.io/package/@allmaps/annotation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._