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.
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>
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, Manifest } 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 instanceof IIIFImage && parsedIiif.type === 'image') {
console.log('This is a IIIF Manifest!')
}
Parsing IIIF resources is also possible using the Allmaps CLI.
For example:
curl https://collections.leventhalmap.org/search/commonwealth:wd376720z/manifest | allmaps iiif parse
- MajorVersion
- LanguageString
- Metadata
- Metadata
- MetadataItem
- Size
- Region
- ImageRequest
- IIIF
- Collection
- EmbeddedManifest
- Manifest
- Canvas
- EmbeddedImage
- Image
IIIF API version
Type: (1
| 2
| 3
)
Type: Object<string, Array<string>>
Type: Array<MetadataItem>
Type: Array<MetadataItem>
Type: Object
-
label
LanguageString Metadata label -
value
LanguageString Metadata value
Image size, with width and height in pixels
Type: Object
Image region, with x, y, width, and height in pixels
Type: Object
-
x
number X coordinate, in pixels -
y
number Y coordinate, in pixels -
width
number Width, in pixels -
height
number Height, in pixels
Image request, with region and size
Type: Object
Base class that contains a static parse function for IIIF resources
Parses as IIIF resource and returns a class containing the parsed version
-
iiifResource
any Source data of a IIIF resource -
majorVersion
MajorVersion IIIF API version of resource. If not provided, it will be determined automatically (optional, defaultnull
)
Returns (Image | Manifest | Collection) Parsed IIIF resource
Parsed IIIF Collection
-
uri
string? URI of Collection -
label
LanguageString? Label of Collection -
items
(Array<Collection> | Array<Manifest> | Array<EmbeddedManifest>)? Items in Collection -
majorVersion
MajorVersion? IIIF API version of Collection -
type
string? Resource type, equals 'collection'
Parses a IIIF Collection and returns a Collection containing the parsed version
-
iiifCollection
any Source data of IIIF Collection -
majorVersion
MajorVersion IIIF API version of Collection. If not provided, it will be determined automatically (optional, defaultnull
)
Returns Collection Parsed IIIF Collection
Parsed IIIF Manifest, embedded in a Collection
-
embedded
boolean Whether the Manifest is embedded in a Collection -
uri
string? URI of Manifest -
label
LanguageString? Label of Manifest -
majorVersion
MajorVersion? IIIF API version of Manifest -
type
string? Resource type, equals 'manifest'
Extends EmbeddedManifest
Parsed IIIF Manifest
-
canvases
Array<Canvas> Array of parsed canvases -
description
LanguageString? Description of Manifest -
metadata
Metadata? Metadata of Manifest
Parses a IIIF resource and returns a Manifest containing the parsed version
-
iiifManifest
any Source data of IIIF Manifest -
majorVersion
MajorVersion IIIF API version of Manifest. If not provided, it will be determined automatically (optional, defaultnull
)
Returns Manifest Parsed IIIF Manifest
Parsed IIIF Canvas
-
uri
string? URI of Canvas -
label
LanguageString? Label of Manifest -
metadata
Metadata? Metadata of Manifest -
image
(EmbeddedImage | Image)? Image of painted on Canvas -
height
number? Height of Canvas -
width
number? Width of Canvas -
type
string? Resource type, equals 'canvas'
Parsed IIIF Image, embedded in a Canvas
-
embedded
boolean Whether the Image is embedded in a Canvas -
type
string? Resource type, equals 'image' -
uri
string URI of Image -
majorVersion
MajorVersion IIIF API version of Image -
supportsAnyRegionAndSize
boolean Whether the associated Image Service supports any region and size -
maxWidth
number? Maximum width of the associated Image Service -
maxHeight
number? Maximum height of the associated Image Service -
maxArea
number? Maximum area of the associated Image Service -
width
number Width of Image -
height
number Height of Image
Generates a IIIF Image API URL for the requested region and size
-
imageRequest
ImageRequest Image request object containing the desired region and size of the requested image
Returns string Image API URL that can be used to fetch the requested image
Extends EmbeddedImage
Parsed IIIF Image
-
tileZoomLevels
Array<TileZoomLevel> Array of parsed tile zoom levels -
sizes
Array<Size>? Array of parsed sizes
Returns a Image request object for a tile with the requested zoom level, column, and row
-
zoomLevel
TileZoomLevel Desired zoom level of the requested tile -
column
number Column of the requested tile -
row
number Row of the requested tile
Returns ImageRequest Image request object that can be used to fetch the requested tile
Returns a Image request object for the requested region and size
-
size
SizeObject Size of the requested thumbnail -
mode
("cover"
|"contain"
) Desired fit mode of the requested thumbnail (optional, default'cover'
)
Returns ImageRequest Image request object that can be used to fetch the requested thumbnail
Parses a IIIF image and returns a Image containing the parsed version
-
iiifImage
any Source data of IIIF Image -
majorVersion
MajorVersion IIIF API version of Image. If not provided, it will be determined automatically (optional, defaultnull
)
Returns Image Parsed IIIF Image