@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
}