# @allmaps/iiif-parser
This is a JavaScript module that parser IIIF [Collections](https://iiif.io/api/presentation/3.0/#51-collection), [Manifests](https://iiif.io/api/presentation/3.0/#52-manifest) and [Images](https://iiif.io/api/image/3.0/#5-image-information). This is a core module of [Allmaps](https://allmaps.org/) 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`](src/classes) and [`src/schemas`](src/schemas) directories for details about these proeprties.*
@allmaps/iiif-parser is written in TypeScript and is built using [Zod](https://zod.dev/).
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 `pnpm 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](https://github.com/allmaps/allmaps/tree/main/apps/cli).
For example:
```sh
curl https://collections.leventhalmap.org/search/commonwealth:wd376720z/manifest | allmaps iiif parse
```
## License
MIT
## API
### `new Canvas(parsedCanvas)`
###### Parameters
* `parsedCanvas` (`{ '@id': string; '@type': "sc:Canvas"; width: number; height: number; images: Array<{ resource: { service: { '@id': string; profile: string | ValidImage2ProfileArray; '@type'?: "ImageService2" | ... 2 more ... | undefined; width?: number | undefined; height?: number | undefined; '@context'?: string | undefined; } | ...`)
###### Returns
`Canvas`.
### `Canvas#annotations?`
###### Type
```ts
Array<{id: string; type: 'AnnotationPage'}>
```
### `Canvas#description?`
###### Type
```ts
{[language: string]: Array}
```
### `Canvas#height`
###### Type
```ts
number
```
### `Canvas#homepage?`
###### Type
```ts
Array<{
id: string
type?: string
label?: LanguageString
format?: string
language?: string | string[]
}>
```
### `Canvas#image`
###### Type
```ts
Image | EmbeddedImage
```
### `Canvas#label?`
###### Type
```ts
{[language: string]: Array}
```
### `Canvas#metadata?`
###### Type
```ts
Array
```
### `Canvas#navDate?`
###### Type
```ts
Date
```
### `Canvas#navPlace?`
###### Type
```ts
object
```
### `Canvas#rendering?`
###### Type
```ts
Array<{
id: string
type?: string
label?: LanguageString
format?: string
}>
```
### `Canvas#requiredStatement?`
###### Type
```ts
{label: LanguageString; value: LanguageString}
```
### `Canvas#seeAlso?`
###### Type
```ts
Array<{id: string; type?: string; format?: string; profile?: string}>
```
### `Canvas#summary?`
###### Type
```ts
{[language: string]: Array}
```
### `Canvas#thumbnail?`
###### Type
```ts
Array<{
id: string
type?: string
format?: string
width?: number
height?: number
}>
```
### `Canvas#type`
###### Type
```ts
CanvasTypeString
```
### `Canvas#uri`
###### Type
```ts
string
```
### `Canvas#width`
###### Type
```ts
number
```
### `new Collection(parsedCollection, options)`
###### Parameters
* `parsedCollection` (`{ '@id': string; '@type': "sc:Collection"; manifests?: Array<{ '@id': string; '@type': "sc:Collection"; manifests?: Array<... | { '@id': string; '@type': "sc:Manifest"; label?: string | Array | { '@value': string | Array; '@language'?: string | undefined; } | Array<{ '@value': string | Array;...`)
* `options?` (`Partial | undefined`)
###### Returns
`Collection`.
###### Extends
* `EmbeddedCollection`
### `Collection#annotations?`
###### Type
```ts
Array<{id: string; type: 'AnnotationPage'}>
```
### `Collection#canvases`
###### Type
```ts
Array