can't build newest pull

pdiiif is a JavaScript library to create PDFs from IIIF Manifests. For the most part, it runs both in browsers and as a Node.js server-side application. When generating a PDF in the browser, almost all communication happens directly between the user's browser and the IIIF APIs referenced from the Manifest. The only exception is for generating the cover page, which by default needs to be generated on the server. (see this section for more details)

It comes with a small sample web application that demonstrates how to use the library in the browser, you can check out a public instance of it at https://pdiiif.jbaiter.de, the source code is located in the pdiiif-web subdirectory.

A main goal of the library is to be as memory-efficient as possible, by never holding more than a few pages in memory and streaming directly to the user's disk (precise method depends on the environment).

It is also well-suited for embedding in other applications due to its relatively small footprint, for example, the example web application comes in at ~120KiB gzipped with all dependencies.

In addition to the images on the IIIF Canvases referenced in the manifest, the library can create a hidden text layer from OCR associated with each canvas (ALTO or hOCR referenced from a canvas' seeAlso property).

In order to not sever the connection between the PDF and the original IIIF resources on the Web, every PDF generated by pdiiif includes the IIIF Manifest as a PDF attachment, as well as every OCR file referenced in seeAlso. Additionally, pdiiif can generate the PDFs in a way that also makes them valid ZIP files that contain the manifest and all of the images and OCR files, with almost no storage overhead. (thanks to Ange Albertini and his work on Poc||GTFO for the inspiration!)

Features

PDF Page for every single-image Canvas in a Manifest
Rendering Canvases with multiple images
PDF Table of Contents from IIIF Ranges
Cover page with metadata, attribution and licensing information
Hidden text layer from ALTO or hOCR OCR
Render IIIF layers as PDF "optional content groups" that can be toggled
Rendering of IIIF Annotations as PDF annotations
Include IIIF Manifest and referenced OCR files as PDF attachments
Generate polyglot PDFs that are also ZIP files of all resources

Quickstart

Besides using the public instance at https://pdiiif.jbaiter.de, you can also run the app yourself. The easiest way to do this is with Docker:

$ docker build . -t pdiiif
# SYS_ADMIN capabilities are required (for Puppeteer's headless Chrome instance to generate cover page PDFs)
$ docker run -p 8080:8080 --cap-add=SYS_ADMIN --name pdiiif pdiiif

Cookbook Matrix

The IIIF Cookbook has a matrix of "recipes" with viewer support, here's an overview of the recipe support in pdiiif:

Basic Recipes (4 of 6 supported)

Simplest Manifest - Single Image File: Partial, only for JPEG images, Cookbook example doesn't work due to use of PNG
Simplest Manifest - Audio: NO, PDF has support for audio, but support in pdiiif unlikely, unless there is substantial demand for it
Simplest Manifest - Video: NO, PDF has support for video, but support in pdiiif unlikely, unless there is substantial demand for it
Support Deep Viewing with Basic Use of a IIIF Image Service: YES, Deep Viewing isn't useful in PDF, but IIIF Image Services are fully supported
Internationalization and Multi-language Values (label, summary, metadata, requiredStatement): YES
Simple Manifest - Book: YES

IIIF Properties (8 of 15 supported)

Structuring Resources (3 of 6 supported)

Table of Contents for Book Chapters (structures): YES
Table of Contents for A/V Content: NO
Multi-volume Work with Individually-bound Volumes: NO
Multiple Choice of Images in a Single View (Canvas): YES
Foldouts, Flaps, and Maps (behavior): NO, support unlikely due to global paging preference in PDF
Composition from Multiple Images: Partial, as long as all images have a JPEG representation

Image Recipes (6 of 6 supported)

Simplest Manifest - Single Image File: Partial, only for JPEG images, Cookbook example doesn't work due to use of PNG
Image and Canvas with Differing Dimensions: YES
Support Deep Viewing with Basic Use of a IIIF Image Service: YES, Deep Viewing isn't useful in PDF, but IIIF Image Services are fully supported
Simple Manifest - Book: YES
Viewing direction and Its Effect on Navigation (viewingDirection): Partially, right-to-left and left-to-right only, viewer support very spotty
Load Manifest Beginning with a Specific Canvas (start): YES

Annotation Recipes (4 of 5 supported)

Simple Annotation — Tagging: YES
Tagging with an External Resource: NO
Annotation with a Non-Rectangular Polygon: YES
Simplest Annotation: YES
Embedded or referenced Annotations: YES

Structure of the repository

./pdiiif-lib: Contains the library source code
./pdiiif-api: Small node.js server application that is responsible for generating the cover pages and that can be used as a fallback for browsers that don't support the Native Filesystem API or service workers.
./pdiiif-web: Sample web application (using Svelte) to demonstrate using pdiiif in the browser

Cover Page Endpoints

pdiiif tries to includes a cover page with a thumbnail, descriptive metadata and rights and attribution information. Since typesetting these pages is beyond the scope of what our bespoke PDF generator can provide (most notably, TTF/OTF font retrieval for arbitrary languages/scripts and font subsetting), this cover page currently needs to be generated elsewhere. By default, the library is using a public endpoint at https://pdiiif.jbaiter.de/api/coverpage, which generates a PDF with the default template. The endpoint can be changed with the coverPageEndpoint configuration parameter in the options passed to the convertManifest function.

If you want to customize the template that is being used, you can either host the API provided in this repository yourself (see Quickstart) and override the template by mounting your own custom Handlebars template into the image at /opt/pdiiif/pdiiif-api/dist/asses/coverpage.hbs. For a list of available helpers that you can use, refer to handlebars-helpers. Also available are these two custom helpers:

qrcode, takes a value and an optional { width, height, padding, color, background, ecl } options object and returns the value encoded as a SVG QR code image
sanitize-html, takes an arbitrary HTML string and sanitizes it according to the IIIF HTML rules

If you want to provide your own implementation, make sure that your HTTP endpoint generates a valid PDF and accepts a JSON POST body with the following shape (i.e. does not throw an error when encountering any of these fields):

{
  title: string;
  manifestUrl: string;
  thumbnail?: {
    url: string;
    iiifImageService?: string;
  };
  provider?: {
    label: string;
    homepage?: string;
    logo?: string;
  };
  requiredStatement?: {
    label: string;
    value: string;
  };
  rights?: {
    text: string;
    url?: string;
    logo?: string;
  };
  // [key, value] pairs, with value either single- or multi-valued
  metadata?: Array<[string, string | Array<string>]>;
  pdiiifVersion: string;
}