@allmaps/iiif-parser

This is a JavaScript module that parser IIIF Collections, Manifests and Images. This is a core module of Allmaps and is used in all its apps and components.

Note: this module parses IIIF data to an intermediate format that is used by Allmaps internally. It does not parse all properties defined by the IIIF Image and Presentation APIs, only properties that are needed for Allmaps to function. See the files in the src/classes and src/schemas directories for details about these proeprties.

@allmaps/iiif-parser is written in TypeScript and is built using Zod.

Versions 1, 2 and 3 of the IIIF Image and Presentation APIs are supported.

This module has been tested on a wide variety of IIIF servers. Run npm test to run all tests.

Installation

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

Node.js:

First, run npm install @allmaps/iiif-parser to add this module to your project.

import { IIIF } from '@allmaps/iiif-parser'

Browser:

<script type="module">
  import { IIIF } from 'https://unpkg.com/@allmaps/iiif-parser?module'
</script>

Usage

import { IIIF } from '@allmaps/iiif-parser'

const manifestUrl =
  'https://collections.leventhalmap.org/search/commonwealth:wd376720z/manifest'
const manifest = await fetch(manifestUrl).then((response) => response.json())
const parsedManifest = IIIF.parse(manifest)
console.log(parsedManifest)

This will log parsedManifest to the console:

{
  "embedded": false,
  "type": "manifest",
  "uri": "https://ark.digitalcommonwealth.org/ark:/50959/wd376720z/manifest",
  "majorVersion": 2,
  "label": {
    "none": [
      "Map of Boston and vicinity showing tracks operated by the Boston Elevated Railway Co., surface lines"
    ]
  },
  "canvases": [
    {
      "type": "canvas",
      "width": 7486,
      "height": 9138,
      "uri": "https://ark.digitalcommonwealth.org/ark:/50959/wd376720z/canvas/wd3767217",
      "label": {
        "none": ["image 1"]
      },
      "image": {
        "embedded": true,
        "type": "image",
        "uri": "https://iiif.digitalcommonwealth.org/iiif/2/commonwealth:wd3767217",
        "majorVersion": 2,
        "supportsAnyRegionAndSize": true,
        "width": 7486,
        "height": 9138
      }
    }
  ],
  "metadata": [
    {
      "label": {
        "none": ["Title"]
      },
      "value": {
        "none": [
          "Map of Boston and vicinity showing tracks operated by the Boston Elevated Railway Co., surface lines"
        ]
      }
    },
    {
      "label": {
        "none": ["Date"]
      },
      "value": {
        "none": ["1898"]
      }
    },
    {
      "label": {
        "none": ["Publisher"]
      },
      "value": {
        "none": ["Boston, Mass : [Geo. H. Walker & Co.]"]
      }
    },
    {
      "label": {
        "none": ["Type of Resource"]
      },
      "value": {
        "none": ["Cartographic"]
      }
    },
    {
      "label": {
        "none": ["Format"]
      },
      "value": {
        "none": ["Maps"]
      }
    },
    {
      "label": {
        "none": ["Language"]
      },
      "value": {
        "none": ["English"]
      }
    },
    {
      "label": {
        "none": ["Subjects"]
      },
      "value": {
        "none": [
          "Boston Elevated Railway Company",
          "Street-railroads--Massachusetts--Boston--Maps",
          "Boston (Mass.)--Maps",
          "Massachusetts--Maps"
        ]
      }
    },
    {
      "label": {
        "none": ["Location"]
      },
      "value": {
        "none": ["Boston Public Library"]
      }
    },
    {
      "label": {
        "none": ["Collection (local)"]
      },
      "value": {
        "none": ["Norman B. Leventhal Map Center Collection"]
      }
    },
    {
      "label": {
        "none": ["Identifier"]
      },
      "value": {
        "none": [
          "https://ark.digitalcommonwealth.org/ark:/50959/wd376720z",
          "06_01_003041",
          "G3764.B6P33 1898 .M3",
          "39999058997337"
        ]
      }
    },
    {
      "label": {
        "none": ["Terms of Use"]
      },
      "value": {
        "none": [
          "No known copyright restrictions.",
          "No known restrictions on use."
        ]
      }
    }
  ]
}

You can also call the parse function on a specific IIIF class:

import { Image } from '@allmaps/iiif-parser'

const imageUrl =
  'https://iiif.digitalcommonwealth.org/iiif/2/commonwealth:wd3767217'
const image = await fetch(`${imageUrl}/info.json`).then((response) =>
  response.json()
)
const parsedImage = Image.parse(image)
console.log(parsedImage)

This will log parsedImage to the console:

{
  "embedded": false,
  "type": "image",
  "uri": "https://iiif.digitalcommonwealth.org/iiif/2/commonwealth:wd3767217",
  "majorVersion": 2,
  "supportsAnyRegionAndSize": true,
  "width": 7486,
  "height": 9138,
  "tileZoomLevels": [
    {
      "scaleFactor": 1,
      "width": 1024,
      "height": 1024,
      "originalWidth": 1024,
      "originalHeight": 1024,
      "columns": 8,
      "rows": 9
    },
    {
      "scaleFactor": 2,
      "width": 1024,
      "height": 1024,
      "originalWidth": 2048,
      "originalHeight": 2048,
      "columns": 4,
      "rows": 5
    },
    {
      "scaleFactor": 4,
      "width": 1024,
      "height": 1024,
      "originalWidth": 4096,
      "originalHeight": 4096,
      "columns": 2,
      "rows": 3
    },
    {
      "scaleFactor": 8,
      "width": 1024,
      "height": 1024,
      "originalWidth": 8192,
      "originalHeight": 8192,
      "columns": 1,
      "rows": 2
    },
    {
      "scaleFactor": 16,
      "width": 1024,
      "height": 1024,
      "originalWidth": 16384,
      "originalHeight": 16384,
      "columns": 1,
      "rows": 1
    },
    {
      "scaleFactor": 32,
      "width": 1024,
      "height": 1024,
      "originalWidth": 32768,
      "originalHeight": 32768,
      "columns": 1,
      "rows": 1
    },
    {
      "scaleFactor": 64,
      "width": 1024,
      "height": 1024,
      "originalWidth": 65536,
      "originalHeight": 65536,
      "columns": 1,
      "rows": 1
    }
  ],
  "sizes": [
    {
      "width": 117,
      "height": 143
    },
    {
      "width": 234,
      "height": 286
    },
    {
      "width": 468,
      "height": 571
    },
    {
      "width": 936,
      "height": 1142
    },
    {
      "width": 1872,
      "height": 2285
    },
    {
      "width": 3743,
      "height": 4569
    },
    {
      "width": 7486,
      "height": 9138
    }
  ]
}

You can check if a parsed IIIF resource object is of a specific class by using the instanceof operator or checking the type property:

import { IIIF } from '@allmaps/iiif-parser'

const url =
  'https://collections.leventhalmap.org/search/commonwealth:wd376720z/manifest'
const iiif = await fetch(url).then((response) => response.json())
const parsedIiif = IIIF.parse(manifest)

if (parsedIiif.type === 'manifest') {
  console.log('This is a IIIF Manifest!')
}

CLI

Parsing IIIF resources is also possible using the Allmaps CLI.

For example:

curl https://collections.leventhalmap.org/search/commonwealth:wd376720z/manifest | allmaps iiif parse

License

MIT

API

`new Canvas(parsedCanvas)`

Parameters

parsedCanvas ({ '@id': string; width: number; height: number; '@type': "sc:Canvas"; images: Array<{ resource: { service: { '@id': string; profile: string | ValidImage2ProfileArray; '@context'?: string | undefined; width?: number | undefined; height?: number | undefined; '@type'?: "ImageService2" | ... 2 more ... | undefined; } | ...)

Returns

Canvas.

`Canvas#annotations?`

Type

Array<{id: string; type: 'AnnotationPage'}>

`Canvas#description?`

Type

{[language: string]: Array<string | number | boolean>}

`Canvas#height`

Type

number

`Canvas#homepage?`

Type

Array<{
  id: string
  type?: string
  label?: LanguageString
  format?: string
  language?: string | string[]
}>

`Canvas#image`

Type

Image | EmbeddedImage

`Canvas#label?`

Type

{[language: string]: Array<string | number | boolean>}

`Canvas#metadata?`

Type

Array<MetadataItem>

`Canvas#navDate?`

Type

Date

`Canvas#navPlace?`

Type

object

`Canvas#rendering?`

Type

Array<{
  id: string
  type?: string
  label?: LanguageString
  format?: string
}>

`Canvas#requiredStatement?`

Type

{label: LanguageString; value: LanguageString}

`Canvas#seeAlso?`

Type

Array<{id: string; type?: string; format?: string; profile?: string}>

`Canvas#summary?`

Type

{[language: string]: Array<string | number | boolean>}

`Canvas#thumbnail?`

Type

Array<{
  id: string
  type?: string
  format?: string
  width?: number
  height?: number
}>

`Canvas#type`

Type

CanvasTypeString

`Canvas#uri`

Type

string

`Canvas#width`

Type

number

`new Collection(parsedCollection, options)`

Parameters

parsedCollection (Collection2 | Collection3)
options? (Partial<ConstructorOptions> | undefined)

Returns

Collection.

Extends

EmbeddedCollection

`Collection#annotations?`

Type

Array<{id: string; type: 'AnnotationPage'}>

`Collection#canvases`

Type

Array<Canvas>

`Collection#embedded`

Type

false

`Collection#fetchAllItems(options)`

Parameters

options? (Partial<FetchNextItemOptions> | undefined)

Returns

Promise<Array<FetchNextItemResults<Image | Manifest | Collection>>>.

`Collection#fetchItemWithId(id, fetchFn)`

Parameters

id (string)
fetchFn ( | ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined)

Returns

Promise<EmbeddedManifest | EmbeddedCollection | undefined>.

`Collection#fetchItemWithIndex(index, fetchFn)`

Parameters

index (number)
fetchFn ( | ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined)

Returns

Promise<Manifest | EmbeddedManifest | Collection | EmbeddedCollection>.

`Collection#fetchNextItem(options, depth)`

Parameters

options? (Partial<FetchNextItemOptions> | undefined)
depth (number | undefined)

Returns

AsyncGenerator< FetchNextItemResults<Image | Manifest | Collection>, void, void >.

`Collection#fetchUntilPath(path)`

Parameters

path (Array<number>)

Returns

Promise<void>.

`Collection#getItemAtPath(path)`

Parameters

path (Array<number>)

Returns

EmbeddedManifest | EmbeddedCollection | Canvas | undefined.

`Collection#homepage?`

Type

Array<{
  id: string
  type?: string
  label?: LanguageString
  format?: string
  language?: string | string[]
}>

`Collection#images`

Type

Array<Image | EmbeddedImage>

`Collection#items`

Type

Array<never>

`Collection#rendering?`

Type

Array<{
  id: string
  type?: string
  label?: LanguageString
  format?: string
}>

`Collection#requiredStatement?`

Type

{label: LanguageString; value: LanguageString}

`Collection#seeAlso?`

Type

Array<{id: string; type?: string; format?: string; profile?: string}>

`Collection#source?`

Type

unknown

`Collection#summary?`

Type

{[language: string]: Array<string | number | boolean>}

`Collection.parse(iiifCollection, options)`

Parses a IIIF Collection and returns a Collection containing the parsed version

Parameters

iiifCollection (unknown)
- Source data of IIIF Collection
options? (Partial<ParseOptions> | undefined)

Returns

Parsed IIIF Collection (Collection).

`new EmbeddedCollection(parsedCollection)`

Parameters

parsedCollection (Collection2 | Collection3 | EmbeddedCollectionType)

Returns

EmbeddedCollection.

`EmbeddedCollection#description?`

Type

{[language: string]: Array<string | number | boolean>}

`EmbeddedCollection#embedded`

Type

true

`EmbeddedCollection#label?`

Type

{[language: string]: Array<string | number | boolean>}

`EmbeddedCollection#majorVersion`

Type

1 | 2 | 3

`EmbeddedCollection#metadata?`

Type

Array<MetadataItem>

`EmbeddedCollection#navDate?`

Type

Date

`EmbeddedCollection#navPlace?`

Type

object

`EmbeddedCollection#thumbnail?`

Type

Array<{
  id: string
  type?: string
  format?: string
  width?: number
  height?: number
}>

`EmbeddedCollection#type`

Type

CollectionTypeString

`EmbeddedCollection#uri`

Type

string

`EmbeddedCollection.parse(iiifCollection, options)`

Parses a IIIF Collection and returns a Collection containing the parsed version

Parameters

iiifCollection (unknown)
- Source data of IIIF Collection
options? (Partial<ParseOptions> | undefined)

Returns

Parsed IIIF Collection (Collection).

`new EmbeddedImage(parsedImage, options)`

Parameters

parsedImage ({ '@context': "http://library.stanford.edu/iiif/image-api/1.1/context.json"; '@id': string; width: number; height: number; profile?: string | undefined; scale_factors?: Array<number> | undefined; tile_width?: number | undefined; tile_height?: number | undefined; } | { ...; } | { ...; } | EmbeddedImageType)
options? (Partial<ImageConstructorOptions> | undefined)

Returns

EmbeddedImage.

`EmbeddedImage#embedded`

Type

true

`EmbeddedImage#getImageRequest(size, mode)`

Parameters

size ({width: number; height: number})
mode (Fit | undefined)

Returns

ImageRequest | Array<Array<ImageRequest>>.

`EmbeddedImage#getImageUrl(imageRequest)`

Generates a IIIF Image API URL for the requested region and size

Parameters

imageRequest ({region?: Region; size?: SizeObject})
- Image request object containing the desired region and size of the requested image

Returns

Image API URL that can be used to fetch the requested image (string).

`EmbeddedImage#height`

Type

number

`EmbeddedImage#majorVersion`

Type

1 | 2 | 3

`EmbeddedImage#maxArea`

Type

number | undefined

`EmbeddedImage#maxHeight`

Type

number | undefined

`EmbeddedImage#maxWidth`

Type

number | undefined

`EmbeddedImage#supportsAnyRegionAndSize`

Type

boolean

`EmbeddedImage#type`

Type

ImageTypeString

`EmbeddedImage#uri`

Type

string

`EmbeddedImage#width`

Type

number

`new EmbeddedManifest(parsedManifest)`

Parameters

parsedManifest ({ '@id': string; '@type': "sc:Manifest"; sequences: Array<{ canvases: [{ '@id': string; width: number; height: number; '@type': "sc:Canvas"; images: Array<{ resource: { service: { '@id': string; profile: string | ValidImage2ProfileArray; '@context'?: string | undefined; width?: number | undefined; height?: number | ...)

Returns

EmbeddedManifest.

`EmbeddedManifest#description?`

Type

{[language: string]: Array<string | number | boolean>}

`EmbeddedManifest#embedded`

Type

true

`EmbeddedManifest#label?`

Type

{[language: string]: Array<string | number | boolean>}

`EmbeddedManifest#majorVersion`

Type

1 | 2 | 3

`EmbeddedManifest#metadata?`

Type

Array<MetadataItem>

`EmbeddedManifest#navDate?`

Type

Date

`EmbeddedManifest#navPlace?`

Type

object

`EmbeddedManifest#thumbnail?`

Type

Array<{
  id: string
  type?: string
  format?: string
  width?: number
  height?: number
}>

`EmbeddedManifest#type`

Type

ManifestTypeString

`EmbeddedManifest#uri`

Type

string

`new IIIF()`

Base class that contains a static parse function for IIIF resources

Parameters

There are no parameters.

Returns

IIIF.

`IIIF.parse(iiifResource, options)`

Parses as IIIF resource and returns a class containing the parsed version

Parameters

iiifResource (unknown)
- Source data of a IIIF resource
options? (Partial<ParseOptions> | undefined)

Returns

Parsed IIIF resource (Image | Manifest | Collection).

`new Image(parsedImage, options)`

Parameters

parsedImage ({ '@context': "http://library.stanford.edu/iiif/image-api/1.1/context.json"; '@id': string; width: number; height: number; profile?: string | undefined; scale_factors?: Array<number> | undefined; tile_width?: number | undefined; tile_height?: number | undefined; } | { ...; } | { ...; })
options? (Partial<ConstructorOptions> | undefined)

Returns

Image.

Extends

EmbeddedImage

`Image#embedded`

Type

false

`Image#getImageRequest(size, mode)`

Returns a Image request object for the requested region and size

Parameters

size ({width: number; height: number})
- Size of the requested thumbnail
mode (Fit | undefined)
- Desired fit mode of the requested thumbnail

Returns

Image request object that can be used to fetch the requested thumbnail (ImageRequest | Array<Array<ImageRequest>>).

`Image#getTileImageRequest(zoomLevel, column, row)`

Returns a Image request object for a tile with the requested zoom level, column, and row

Parameters

zoomLevel ({ scaleFactor: number width: number height: number originalWidth: number originalHeight: number columns: number rows: number })
- Desired zoom level of the requested tile
column (number)
- Column of the requested tile
row (number)
- Row of the requested tile

Returns

Image request object that can be used to fetch the requested tile ({region?: Region; size?: SizeObject}).

`Image#sizes?`

Type

Array<SizeObject>

`Image#source?`

Type

unknown

`Image#tileZoomLevels`

Type

Array<TileZoomLevel>

`Image.parse(iiifImage, parseOptions)`

Parses a IIIF image and returns a Image containing the parsed version

Parameters

iiifImage (unknown)
- Source data of IIIF Image
parseOptions? (Partial<ParseOptions> | undefined)

Returns

Parsed IIIF Image (Image).

`ImageRequest`

Fields

region? ({x: number; y: number; width: number; height: number})
size? ({width: number; height: number})

`LanguageString`

Fields

[language: string] (Array<string | number | boolean>)

`MajorVersion`

Type

1 | 2 | 3

`new Manifest(parsedManifest, options)`

Parameters

parsedManifest ({ '@id': string; '@type': "sc:Manifest"; sequences: Array<{ canvases: [{ '@id': string; width: number; height: number; '@type': "sc:Canvas"; images: Array<{ resource: { service: { '@id': string; profile: string | ValidImage2ProfileArray; '@context'?: string | undefined; width?: number | undefined; height?: number | ...)
options? (Partial<ConstructorOptions> | undefined)

Returns

Manifest.

Extends

EmbeddedManifest

`Manifest#annotations?`

Type

Array<{id: string; type: 'AnnotationPage'}>

`Manifest#canvases`

Type

Array<never>

`Manifest#embedded`

Type

false

`Manifest#fetchAllItems(fetchFn)`

Parameters

fetchFn ( | ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined)

Returns

Promise<Array<FetchNextItemResults<Image>>>.

`Manifest#fetchImageByUri(imageUri, fetchFn)`

Parameters

imageUri (string)
fetchFn ( | ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined)

Returns

Promise<Image | undefined>.

`Manifest#fetchNextItem(fetchFn, depth)`

Parameters

fetchFn ( | ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) | undefined)
depth (number | undefined)

Returns

AsyncGenerator<FetchNextItemResults<Image>, void, void>.

`Manifest#homepage?`

Type

Array<{
  id: string
  type?: string
  label?: LanguageString
  format?: string
  language?: string | string[]
}>

`Manifest#images`

Type

Array<Image | EmbeddedImage>

`Manifest#rendering?`

Type

Array<{
  id: string
  type?: string
  label?: LanguageString
  format?: string
}>

`Manifest#requiredStatement?`

Type

{label: LanguageString; value: LanguageString}

`Manifest#seeAlso?`

Type

Array<{id: string; type?: string; format?: string; profile?: string}>

`Manifest#source?`

Type

unknown

`Manifest#summary?`

Type

{[language: string]: Array<string | number | boolean>}

`Manifest.parse(iiifManifest, options)`

Parses a IIIF resource and returns a Manifest containing the parsed version

Parameters

iiifManifest (unknown)
- Source data of IIIF Manifest
options? (Partial<ParseOptions> | undefined)

Returns

Parsed IIIF Manifest (Manifest).

`Metadata`

Type

Array<MetadataItem>

`ProfileProperties`

Fields

maxArea? (number)
maxHeight? (number)
maxWidth? (number)
supportsAnyRegionAndSize (boolean)

`Region`

Fields

height (number)
width (number)
x (number)
y (number)

`Size`

Two numbers indicating the size of a Bbox as [width, height] or [xSize, ySize] ([number, number]). Alternatively, two numbers indicating the minimum and maximum of, for example, an array of numbers Alternatively, two numbers indicating the dimensions of a matrix: rows, cols (which is a different handedness!)

`TileZoomLevel`

Fields

columns (number)
height (number)
originalHeight (number)
originalWidth (number)
rows (number)
scaleFactor (number)
width (number)

`Tileset`

Type

{
  width: number
  scaleFactors: Array<number>
  height?: number | undefined
}