@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, 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!')
}

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

API

Table of Contents

• MajorVersion
• LanguageString
• Metadata
• Metadata
• MetadataItem
  • Properties
• Size
  • Properties
• Region
  • Properties
• ImageRequest
  • Properties
• IIIF
  • parse
• Collection
  • Properties
  • parse
• EmbeddedManifest
  • Properties
• Manifest
  • Properties
  • parse
• Canvas
  • Properties
• EmbeddedImage
  • Properties
  • getImageUrl
• Image
  • Properties
  • getIiifTile
  • getThumbnail
  • parse

MajorVersion

IIIF API version

Type: (1 | 2 | 3)

LanguageString

Type: Object<string, Array<string>>

Metadata

Type: Array<MetadataItem>

Metadata

Type: Array<MetadataItem>

MetadataItem

Type: Object

Properties

• label LanguageString Metadata label
• value LanguageString Metadata value

Size

Image size, with width and height in pixels

Type: Object

Properties

• width number Width, in pixels
• height number Height, in pixels

Region

Image region, with x, y, width, and height in pixels

Type: Object

Properties

• x number X coordinate, in pixels
• y number Y coordinate, in pixels
• width number Width, in pixels
• height number Height, in pixels

ImageRequest

Image request, with region and size

Type: Object

Properties

• region Region? Image region
• size Size? Image size

IIIF

Base class that contains a static parse function for IIIF resources

parse

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

Parameters

• iiifResource any Source data of a IIIF resource
• majorVersion MajorVersion IIIF API version of resource. If not provided, it will be determined automatically (optional, default null)

Returns (Image | Manifest | Collection) Parsed IIIF resource

Collection

Parsed IIIF Collection

Properties

• 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'

parse

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

Parameters

• iiifCollection any Source data of IIIF Collection
• majorVersion MajorVersion IIIF API version of Collection. If not provided, it will be determined automatically (optional, default null)

Returns Collection Parsed IIIF Collection

EmbeddedManifest

Parsed IIIF Manifest, embedded in a Collection

Properties

• 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'

Manifest

Extends EmbeddedManifest

Parsed IIIF Manifest

Properties

• canvases Array<Canvas> Array of parsed canvases
• description LanguageString? Description of Manifest
• metadata Metadata? Metadata of Manifest

parse

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

Parameters

• iiifManifest any Source data of IIIF Manifest
• majorVersion MajorVersion IIIF API version of Manifest. If not provided, it will be determined automatically (optional, default null)

Returns Manifest Parsed IIIF Manifest

Canvas

Parsed IIIF Canvas

Properties

• 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'

EmbeddedImage

Parsed IIIF Image, embedded in a Canvas

Properties

• 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

getImageUrl

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

Parameters

• 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

Image

Extends EmbeddedImage

Parsed IIIF Image

Properties

• tileZoomLevels Array<TileZoomLevel> Array of parsed tile zoom levels
• sizes Array<Size>? Array of parsed sizes

getIiifTile

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

Parameters

• 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

getThumbnail

Returns a Image request object for the requested region and size

Parameters

• 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

parse

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

Parameters

• iiifImage any Source data of IIIF Image
• majorVersion MajorVersion IIIF API version of Image. If not provided, it will be determined automatically (optional, default null)

Returns Image Parsed IIIF Image