Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PNPM, Vitest, tsup #36

Merged
merged 7 commits into from
Apr 9, 2024
Merged

PNPM, Vitest, tsup #36

merged 7 commits into from
Apr 9, 2024

Conversation

stephenwf
Copy link
Member

@stephenwf stephenwf commented Apr 9, 2024

IIIF Parser

npm i @iiif/parser

This is a parser and set of low-level utilities for the following IIIF Specifications:

These include:

Note

A new version of the IIIF Presentation API is being developed (v4) which handles 3D content. This parser will
support this version soon. You can read about the additions here

Features

The features of this library are focussed on encoding the structure of all types of IIIF and providing utilities for extracting data from the IIIF or converting it into another format that is easier to develop with. The aim of the parser is to maximize the IIIF compatibility of other tools built on top of it.

IIIF Presentation 3

  • Empty types for each resource (e.g. Manifest, Canvas) which can be used as starting points for creating IIIF
  • Traverse utility for walking through IIIF documents and running code at different "types"
  • Normalize utility which will:
    • Add default empty defaults (null or empty array)
    • Organize by type into Records
    • Replace nested with references using ID/Type or SpecificResources
  • Serializers which take normalized data and output it again
    • Presentation v3 serializer- outputs well-formed Presentation 3 JSON
    • Presentation v2 serializer - outputs good-enough Presentation 2 JSON (missing features).
  • Strict Upgrader utility which can automatically fix Presentation 3 JSON that has issues.
import { Traverse } from '@iiif/parser';

// Or for presentation 2 resources
// import { Traverse } from '@iiif/parser/presentation-2'; 

const ids = [];
const extractCanvasLabels = new Traverse({
  Canvas: [(canvas) => {
    ids.push(canvas.id); // string
  }],
});

extractCanvasLabels.traverseUnknown(loadSomeManifest());

console.log(ids); // all canvas ids.

IIIF Presentation 2

  • Traverse utility for walking through IIIF v2 documents and running code at different "types"
  • Upgrader utility built on-top of the Traverse utility for upgrading IIIF v2 to IIIF v3.

The intention for IIIF Presentation 2 is to upgrade it to 3 and then work with that. The tooling will always offer and upgrade to the latest version and tools on top of that.

import { Traverse, convertPresentation2  } from '@iiif/parser/presentation-2';

convertPresentation2(p2); // to latest IIIF version

const logAnnotations = new Traverse({
  // Every type is a key on this record, with an array of functions to call
  Annotation: [
    anno => {
      console.log(anno['@id']);

      // Optionally return to replace the resource.
    }
  ]
});

logAnnotations.traverseManifest(someInputManifest); // Logs all annotation IDs.

// Also an "all" traversal.
const logAllIds = Traverse.all(resource => console.log(resource['@id']));

logAllIds.traverseUnknown(someInput);

Image 3

The Image 3 parser is adapted from an Image Server implementation, and supports:

  • Parsing of IIIF Image API request URLs (including info.json)
    • Extracting region
    • Extracting rotation
    • Extracting size
    • Extracting quality
    • Extracting format
  • Parsing of IIIF profiles, and feature detection
    • isLevel0(service)
    • supports(service, { extraQualities: ['grey'] }) helper which accepts a service and partial service to compare
    • imageServiceSupportsRequest() helper that can validate IIIF image requests before you make them
  • Serializing of IIIF Image requests
    • A custom structure for defining region, size, quality etc. and then creating a IIIF Image request URL.
    • Support for Image 2.1 servers
  • Handful of utilities for IIIF Image 3
    • extracting fixes sized images from an image service
    • extracting fixed sizes from scale factors (full tiles)
    • canonicalServiceUrl(), getId(), getType() and isImageService() for compatibility and validation
import { parseImageServiceRequest, imageServiceRequestInfo } from '@iiif/parser/image-3';
import {  ImageService } from '@iiif/presentation-3';

const parsed = parseImageServiceRequest(
  'https://munch.emuseum.com/apis/iiif/image/v2/17261/full/max/0/default.jpg',
  // Optionally provide a path, so the identifier can be extracted
  'apis/iiif/image/v2'
);

// {
//   "format": "jpg",
//   "identifier": "17261",
//   "originalPath": "/17261/full/max/0/default.jpg",
//   "prefix": "apis/iiif/image/v2",
//   "quality": "default",
//   "region": {
//     "full": true,
//   },
//   "rotation": {
//     "angle": 0,
//   },
//   "scheme": "https",
//   "server": "munch.emuseum.com",
//   "size": {
//     "confined": false,
//     "max": true,
//     "serialiseAsFull": false,
//     "upscaled": false,
//   },
//   "type": "image",
// }

// Can be changed.
parsed.rotation.angle = 90;

const imageUrl = imageServiceRequestToString(parsed);
// https://munch.emuseum.com/apis/iiif/image/v2/17261/full/max/90/default.jpg

const infoJson = imageServiceRequestInfo(parsed);
// https://munch.emuseum.com/apis/iiif/image/v2/17261/info.json


const imageService: ImageService = await fetch(infoJson).then(r => r.json());

// Likely true - as its supported by level0, level1 and level2
const supportsSizes = supports(imageService, {
  extraFeatures: ['sizeByWhListed']
});

Upgrader standalone

Upgrades IIIF JSON to the latest IIIF Presentation version (current: 3).

import { upgrade } from '@iiif/parser/upgrader';

upgrade(presentation2Manifest); // Presentation 3 Manifest or Collection

Copy link

codesandbox-ci bot commented Apr 9, 2024

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

@stephenwf stephenwf merged commit c3eae3e into main Apr 9, 2024
3 checks passed
@stephenwf stephenwf deleted the feature/v2.1 branch April 9, 2024 18:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant