Skip to content

Home

Jump to bottom Edit New page
Roy Lechich edited this page Jul 26, 2017 · 22 revisions

Home

API Spec References:
http://iiif.io: the website for the IIIF project. It provides background (http://iiif.io/about/) and links to the API's.

The central API around which this server is built is the IIIF Presentation API (http://iiif.io/api/presentation/2.1/).
The Mirador viewer/annotation tool makes use of the IIIF Image API (http://iiif.io/api/image/2.1/)
http://projectmirador.org/ is the website for the IIF compliant Mirador viewer and annotation tool.

Purpose and Background: The Mirador Annotation-Server was designed to be a simple IIIF Annotations server which can be used stand-alone to store, retrieve, update and delete annotations. But it also functions more fully as the complementary annotation server to Yale's extension of the Mirador viewer/annotation tool.

The AnnoServer provides just a piece of a full IIIF context. A full IIIF environment will include manifests to hold organized information about images or pages, which are represented as canvases, which typically store references to images (these could be pages within a book, sections of a manuscript or murals, a painting etc.), as well as the annotations which are created to enrich/extend the meaning and value of the images. The purpose of this server is to provide storage and management of these annotations.

For the sake of fullness, a manifest will actually contain at least one sequence, which will in turn contain canvases . This allows for a manifest to be able to present its constituent canvases in different meaningful orders. Also, just as manifests represent some meaningful collection of canvases, the highest level in the IIIF hierarchy is a collection. A collection might be used to provide some meaningful way to contain manifests. Theoretically there is no minimum or maximum limit; a manifest might hold only one canvas to represent a painting for example, and this canvas might be annotated to include information or analysis relating to various sections of the painting.

Both the annotations and the images themselves are treated as "resources" within a canvas. While it is allowable to present a manifest with all its canvases and annotations inline, it would be impractical to store the data of the image files themselves inline. An image resource will contain metadata and other information about an image (or images) referred to in an image resource, including the actual pointers to an image server which can render and return the requested image. So another key piece of the IIIF environment is a IIIF-compliant image server.

Since the AnnoServer is strictly a IIIF Annotation server, it is agnostic about manifests, images and canvases, with the single exception of needing to know the id of the canvas(es) to which an annotation belongs. At one point, the storage of a manifest id with each annotation was considered, then rejected, since it was not strictly necessary and potentially problematic, since a canvas (or image file) might be included in several unrelated manifests.

Mirador, the AnnoServer and the Faculty Projects
The rest of the IIIF context for the AnnoServer is provided by an extended version of the Mirador application (http://projectmirador.org/), which is a community based open source project to provide a rich IIIF-compliant image viewer and annotation tool. This annotation server and the highly extended version of Mirador (also developed at Yale, but within the Mirador community and properly managed within the open source project) form the initial two components which comprise the project developed by Yale's CCT/Web Technology group to satisfy two faculty grant funded projects to allow annotation on Asian manuscripts and other source material.

The user requirements for these two faculty projects led to a number of functional requirements which in turn led to coordinated and complementary development efforts across both the AnnoServer and the Mirador development work. These will be discussed below.

Briefly, the default context flow in Mirador is:

  • it knows about the manifests, and therefore the canvases it is dealing with. Out of the box, an initial configuration for a stock deployment includes the population of a configuration file which tells Mirador, upon opening, which manifests to display, along with a list of thumbnails showing the canvasses within each manifest.
  • the user then selects one of the canvases, and the initial viewer window displays the primary image for that canvas.
  • the rendering of both the thumbnail list and the full selected image in the viewer window are accomplished using the IIIF Image API (http://iiif.io/api/image/2.1/)
  • the user then can list, edit, delete and add to the annotations which are associated with that canvas (depending on permissions of course)

The point here is that Mirador is designed to be manifest and canvas-aware upon opening, and any annotation activity is performed within this context.

Another configuration step in Mirador is the specification of an annotation endpoint, so that the user can interact with the annotations. In our case this is set to the AnnoServer.

Our locally extended version has been modified to get some of this initial context from external sources, which is now the the third leg of this overall project:

Drupal and the Project Management/Administrative Layer Drupal was used in this project to create an application to provide the ability for users to create, administer and manage projects. The project, which corresponds to, and actually generates a IIIF manifest, provides a container for project administrators to create a project with name and description, etc. along with an initial list of layers (discussed below). It also provides the project admin the ability to upload images (from which IIIF canvases are generated), handle user administration etc. It also populates and manages a SOLR index to provide SOLR searching for the annotations within a given project. It also provides other features, such as a user forum, etc.

This app is now the default entry point for users to select a project, potentially a canvas, and even a specific annotation via SOLR search results. Once one of these is selected, it will call Mirador and pass it this information.

From Mirador's perspective, this replaces the stock functionality of starting with a list of manifests in a configuration file, and a user selected canvas, and in fact adds to it the ability to initialize around one annotation.

From the AnnoServer's perspective, this is the source of layers, and also the target for the annotation feeds which are used to populate the SOLR index.

The core functionality: The IIIF API is central to these functions, ensuring that:

  • Create: when an annotation is received for storage, it ensures that the annotation is a a JSON-format which complies with the specifications.
  • Retrieve: when an annotation is requested from the server, it responds by fetching the annotation and rendering and returning a IIIF-compliant representation.
  • Update: again, the update method expects to receive a valid IIIF annotation, and will update and store it, as well as returning the updated IIIF-compliant representation.

The concept of using layers and lists to fulfill some of the requirements: This allows for annotations to be assigned to both a canvas and a project-specific layer, which can be used, for example to say that an annotation belongs to the "transcript" layer, or "translation" or "commentary" or any other qualities that provide for a useful grouping to generate an annotation window in Mirador.

See the other wiki pages for information on extra functionality and implementation.

Add a custom footer
Add a custom sidebar
Clone this wiki locally