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

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

Browser:

`html

`

Usage

`js
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:

`json
{
"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:

`js
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:

`json
{
"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:

`ts
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:

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

License

MIT

API

$3

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

$3

###### Type

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

$3

###### Type

`ts
{[language: string]: Array}
`

$3

###### Type

`ts
number
`

$3

###### Type

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

$3

###### Type

`ts
Image | EmbeddedImage
`

$3

###### Type

`ts
{[language: string]: Array}
`

$3

###### Type

`ts
Array
`

$3

###### Type

`ts
Date
`

$3

###### Type

`ts
object
`

$3

###### Type

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

$3

###### Type

`ts
{label: LanguageString; value: LanguageString}
`

$3

###### Type

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

$3

###### Type

`ts
{[language: string]: Array}
`

$3

###### Type

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

$3

###### Type

`ts
CanvasTypeString
`

$3

###### Type

`ts
string
`

$3

###### Type

`ts
number
`

$3

###### Parameters

* parsedCollection (Collection2 | Collection3)
* options? (Partial | undefined)

###### Returns

Collection.

###### Extends

* EmbeddedCollection

$3

###### Type

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

$3

###### Type

`ts
Array
`

$3

###### Type

`ts
false
`

$3

###### Parameters

* options? (Partial | undefined)

###### Returns

Promise>>.

$3

###### Parameters

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

###### Returns

Promise.

$3

###### Parameters

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

###### Returns

Promise.

$3

###### Parameters

* options? (Partial | undefined)
* depth (number | undefined)

###### Returns

AsyncGenerator<
FetchNextItemResults,
void,
void >.

$3

###### Parameters

* path (Array)

###### Returns

Promise.

$3

###### Parameters

* path (Array)

###### Returns

EmbeddedManifest | EmbeddedCollection | Canvas | undefined.

$3

###### Type

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

$3

###### Type

`ts
Array
`

$3

###### Type

`ts
Array
`

$3

###### Type

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

$3

###### Type

`ts
{label: LanguageString; value: LanguageString}
`

$3

###### Type

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

$3

###### Type

`ts
unknown
`

$3

###### Type

`ts
{[language: string]: Array}
`

$3

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

###### Parameters

* iiifCollection (unknown)
* Source data of IIIF Collection
* options? (Partial | undefined)

###### Returns

Parsed IIIF Collection (Collection).

$3

###### Parameters

* parsedCollection (Collection2 | Collection3 | EmbeddedCollectionType)

###### Returns

EmbeddedCollection.

$3

###### Type

`ts
{[language: string]: Array}
`

$3

###### Type

`ts
true
`

$3

###### Type

`ts
{[language: string]: Array}
`

$3

###### Type

`ts
1 | 2 | 3
`

$3

###### Type

`ts
Array
`

$3

###### Type

`ts
Date
`

$3

###### Type

`ts
object
`

$3

###### Type

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

$3

###### Type

`ts
CollectionTypeString
`

$3

###### Type

`ts
string
`

$3

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

###### Parameters

* iiifCollection (unknown)
* Source data of IIIF Collection
* options? (Partial | undefined)

###### Returns

Parsed IIIF Collection (Collection).

$3

###### 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 | undefined; tile_width?: number | undefined; tile_height?: number | undefined; } | { ...; } | { ...; } | EmbeddedImageType)
* options? (Partial | undefined)

###### Returns

EmbeddedImage.

$3

###### Type

`ts
true
`

$3

###### Parameters

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

###### Returns

ImageRequest | Array>.

$3

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).

$3

###### Type

`ts
number
`

$3

###### Type

`ts
1 | 2 | 3
`

$3

###### Type

`ts
number | undefined
`

$3

###### Type

`ts
number | undefined
`

$3

###### Type

`ts
number | undefined
`

$3

###### Type

`ts
boolean
`

$3

###### Type

`ts
ImageTypeString
`

$3

###### Type

`ts
string
`

$3

###### Type

`ts
number
`

$3

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

$3

###### Type

`ts
{[language: string]: Array}
`

$3

###### Type

`ts
true
`

$3

###### Type

`ts
{[language: string]: Array}
`

$3

###### Type

`ts
1 | 2 | 3
`

$3

###### Type

`ts
Array
`

$3

###### Type

`ts
Date
`

$3

###### Type

`ts
object
`

$3

###### Type

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

$3

###### Type

`ts
ManifestTypeString
`

$3

###### Type

`ts
string
`

$3

Base class that contains a static parse function for IIIF resources

###### Parameters

There are no parameters.

###### Returns

IIIF.

$3

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

###### Parameters

* iiifResource (unknown)
* Source data of a IIIF resource
* options? (Partial | undefined)

###### Returns

Parsed IIIF resource (Image | Manifest | Collection).

$3

###### 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 | undefined; tile_width?: number | undefined; tile_height?: number | undefined; } | { ...; } | { ...; })
* options? (Partial | undefined)

###### Returns

Image.

###### Extends

* EmbeddedImage

$3

###### Type

`ts
false
`

$3

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>).

$3

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}).

$3

###### Type

`ts
Array
`

$3

###### Type

`ts
unknown
`

$3

###### Type

`ts
Array
`

$3

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

###### Parameters

* iiifImage (unknown)
* Source data of IIIF Image
* parseOptions? (Partial | undefined)

###### Returns

Parsed IIIF Image (Image).

$3

###### Fields

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

$3

###### Fields

* [language: string] (Array)

$3

###### Type

`ts
1 | 2 | 3
`

$3

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

###### Returns

Manifest.

###### Extends

* EmbeddedManifest

$3

###### Type

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

$3

###### Type

`ts
Array
`

$3

###### Type

`ts
false
`

$3

###### Parameters

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

###### Returns

Promise>>.

$3

###### Parameters

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

###### Returns

Promise.

$3

###### Parameters

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

###### Returns

AsyncGenerator, void, void>.

$3

###### Type

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

$3

###### Type

`ts
Array
`

$3

###### Type

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

$3

###### Type

`ts
{label: LanguageString; value: LanguageString}
`

$3

###### Type

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

$3

###### Type

`ts
unknown
`

$3

###### Type

`ts
{[language: string]: Array}
`

$3

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

###### Parameters

* iiifManifest (unknown)
* Source data of IIIF Manifest
* options? (Partial | undefined)

###### Returns

Parsed IIIF Manifest (Manifest).

$3

###### Type

`ts
Array
`

$3

###### Fields

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

$3

###### Fields

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

$3

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!)

$3

###### Fields

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

$3

###### Type

`ts
{
width: number
scaleFactors: Array
height?: number | undefined
}
``