	Viewport
	Canvas
	Selected Canvas
	Frame

Fork me on GitHub

Layout Functions for IIIF Canvas Sequences

The IIIF Presentation API provides the necessary information to display a structured image collection, such as one representing a book or archive. The specification requires support for several reading directions and viewing hints, such as top-to-bottom scrolls, paged books, or sequences of single images. To lay these out in space is not a trivial task when we must also take into account zooming, styling, and annotation requirements. Iteratively building a DOM/CSS-based, canvas, or svg rendering of the collection would make it prohibitively resource intensive to query the resulting layout for multi-modal presentation, as is often required.

Instead, we must calculate an intermediate representation of the positions of rectangles in space in a normalised coordinate system which the programmer can scale to the given rendering environment. The layout can be rendered using different technologies for distinct purposes: DOM for styling, canvas for a minimap, OpenSeadragon for interaction. Changes in this intermediate representation can then be tracked by the multiple consuming objects and re-rendered appropriately, without relying on DOM querying. This library provides a set of functions that makes these layout calculations for the programmer's convenience.

The examples below render the output of the provided layout algorithms. They conclude with an example of a simple navigator composed out of these layouts.

Inputs and Outputs

These functions take in an array of IIIF Canvases, a viewport object, and a set of optional layout parameters, described below.

IIIF Sequence/Canvases

All these functions act on an array of IIIF 2.1 canvases (described at iiif.io). This array is usually derived from a IIIF manifest sequence.

Viewport

The viewport input is an object giving the dimensions of the container into which the layout will be rendered. The aspect ratio of the viewport is a major determining constraint on the resultant layout.

Layout Primitives

Canvas

The canvas is the fundamental layout building block. Its dimensions are taken automatically from the IIIF sequence input to the function; the programmer can not alter its dimensions.

Frame

A canvas sits inside a frame. In overview layouts, the frame "frames" the canvas. The purpose of this object is to allow space between canvases and, optionally, a label or other overlays in a target rendering.

FramePadding

The frame padding puts space around the canvas in overview mode to make room for a label and provide visual space between elements.

Vantage

A "vantage" gives the dimensions of the viewport from which to optimally view a selected canvas. Every selected canvas will have a target "vantage" generated for it. This can either be used in a renderer to move the viewport or explicitly drawn in a minimap, as in some of the examples below.

Viewport Padding

The viewport padding applies to every vantage, and allows the programmer to leave space in key states of the layout for controls that may sit on top of the rendering container, such as titles, thumbnail strips, or information panels. This allows a zooming interface to pan or zoom underneath these elements, but still allow state in which overlaid controls to not overlap the image rendering.

Left-to-Right Layouts

Individuals

Overview Perspective

Show Viewport Viewport Aspect Ratio Show Frames Show Canvas Numbers

Intermediate Perspective

Detail Perspective

Paged

Overview Perspective

Intermediate Perspective

Detail Perspective

Continuous

Overview Perspective

Intermediate Perspective

Detail Perspective

Right-to-Left Layouts

Individuals

Overview Perspective

Intermediate Perspective

Detail Perspective

Paged

Overview Perspective

Intermediate Perspective

Detail Perspective

Continuous

Overview Perspective

Intermediate Perspective