WissKI Mirador¶

wisski_mirador shows the images of WissKI entities in the Mirador IIIF viewer. It adds a WissKI Mirador style to Views: every result row opens as one Mirador window, loading the IIIF manifest that wisski_iip_image builds for the entity. Optionally, users draw and comment regions on the images; the annotations are stored as WissKI individuals of the annotation model WissKI ships, or in a bundle you choose.

Installation¶

Enable the module. It needs wisski_iip_image.
```
drush en wisski_mirador
```
Install the WissKI Mirador Integration library, a prebuilt Mirador 4 bundle with the Mirador Annotation Editor, image tools and download plugins:
```
drush wisski-mirador:wisski-mirador-integration
```
Or open Reports → Status report and follow the link in the WissKI Mirador Integration library entry.

The module pins one release of rnsrk/wisski-mirador-integration. The download is checked against the release's SHA-256 checksum and extracted to libraries/wisski-mirador-integration; a download with any other content is not installed.

Update the library¶

When a WissKI update pins a newer release, the status report shows a warning. Run the same command again; it replaces the library only after the new release has been downloaded and verified:

drush wisski-mirador:wisski-mirador-integration

Use --force to reinstall the pinned release, for example after files in the library directory were changed by hand.

Until the library is updated, the viewer keeps running on the installed release. Version 2.0 replaces the Mirador 3 bundle of 1.x with Mirador 4 and the Mirador Annotation Editor.

Upgrade from 8.x-4.9 or scs_base¶

These steps also apply to sites on scs_base, which matches WissKI 8.x-3.16. Nothing stops working when you update; the viewer shows images throughout. Do these steps once after the update:

Run the database updates. They enable wisski_iip_image, add the annotation settings, move the first complete view mapping into those settings, remove the mapping options from all views, and list the view displays whose annotation tools stay hidden:
```
drush updb
```
Update the library to 2.0 from Reports → Status report or with drush wisski-mirador:wisski-mirador-integration. Until then, the viewer keeps running on 1.1.
If the status report shows WissKI Mirador annotation mapping, the listed displays have annotations enabled while the annotation settings are missing or not fully mapped, so Mirador shows the images without annotation tools. Open Configuration → WissKI → WissKI Mirador, tab Annotations, and complete the mapping. It needs the UUID, the JSON document and the image; text, keywords, SVG, canvas, creator and creation time can stay empty. The xywh box stays in the annotation document. A view mapping that differs from settings that are already enabled is dropped; those annotations stay stored but are no longer shown. If the status report says the annotation mapping is broken, a mapped field no longer exists. Fix it on the same settings page; annotation requests fail until then.
Grant API Access to WissKI Mirador to the roles that may annotate (People → Permissions). On scs_base the annotation API was open to everybody and this permission did not exist, so after the update no role has it and only administrators see the annotation tools. The update does not grant it, because that would give write access to everybody who could read before, anonymous visitors included. Until a role other than an administrator role has it, the status report shows WissKI Mirador annotation permission.

Stored annotations are not changed by the update.

Custom annotation clients

The annotation endpoints moved to /wisski/mirador-annotations/{view}/{display}/… (see Annotation API). Writes need Content-Type: application/json and an X-CSRF-Token header from /session/token. The old endpoints answer 410 Gone with the new address. The WissKI Mirador views style needs no change; it sets the endpoint itself.

Show images in a view¶

Create a view of WissKI entities and set its format to WissKI Mirador.
Add the entity ID as a field. Its manifest is loaded automatically. Alternatively, show a field that holds an IIIF manifest URL as the first field.
Adjust the window settings, a JSON object of Mirador window settings. The view only saves valid JSON.

Several Mirador views or blocks can be shown on one page.

Show the images of one entity¶

On the bundle's Manage display page, enable Mirador. The field is hidden until then. It opens one Mirador window with the IIIF manifest wisski_iip_image builds for that entity. Annotation tools stay off: drawing annotations needs a view, because annotations are enabled per view display.

The manifest stays the image document. Annotations are not written into it. Mirador loads them from the annotation page of the view.

Show an external IIIF manifest in a block¶

The Mirador Block Viewer block shows the IIIF manifest URL that a field of the current page displays. It was the blockmirador module before (see wisski_mirador_block).

At Structure → Block layout, place Mirador Block Viewer.
IIIF Field Number is the system name of the field that shows the manifest URL, for example f1234567890abcdef. It is listed on the bundle's Manage fields tab. The block stays hidden on pages where that field is empty or shows no address containing manifest.
Viewer Height is the height in pixels, 600 by default.

The block runs on the WissKI Mirador Integration library. If the integration library is missing but the Mirador build that blockmirador required is still in /libraries/mirador/dist/mirador.min.js, the block uses that one, and the status report only warns that the views style and the display field need the integration library. Once the integration library is installed, the block uses it too, so a page with the block and a view loads one Mirador only.

What Mirador loads¶

A view does not hand Mirador a file URL. It hands Mirador the IIIF manifest of the entity, /wisski/navigate/{id}/iiif_manifest. One entity can have several image files. Each file becomes one canvas, a page in that manifest. The canvas address is not the file address:

http://localhost:3600/wisski/42/sequence/normal/0/seite1.png/normal.json

42 is the entity, normal is the name of the sequence, 0 is the position of this file in the manifest, and normal.json is the canvas document. Drupal picks the file by the position alone. Opening that address returns the canvas:

height and width are the pixel size of the page. Annotation coordinates are pixels of this page.
images[0].resource.service is the IIIF image service Mirador reads the pixels from.
images[0].resource.filepath is the public file URL, for example http://localhost:3600/sites/default/files/seite1.png.
images[0].resource.fileuri is the same file as WissKI stores it, for example public://seite1.png.
The entry under images is the IIIF instruction “paint this file on the page”. It is not a WissKI annotation.

The same file on another entity has another canvas address, because the entity id is part of it. seite1.png itself still holds one image. Several canvases mean several files on one entity, not several pictures inside one file.

How an annotation is stored and found¶

Mirador sends the canvas address. The adapter loads GET /wisski/mirador-annotations/{view}/{display}/pages?uri={canvas} and, on create, posts the canvas address with the annotation document.

Drupal stores one WissKI individual per annotation. The document Mirador sends, including the SVG shape and the xywh box, is written into the annotation document field. There is no separate fragment field: xywh=100,200,50,80 is the rectangle around the mark, and the SVG is the outline. A rectangle's box and outline coincide; a polygon's box is only the rectangle around it.

The area's image field receives the file URI (public://seite1.png in the shipped model, the public URL in a mapping without an area). That is how the annotation reaches the same image individual as the rest of the site. The shipped model maps a canvas field. It stores the canvas address as a string, not the canvas JSON. With that field mapped, annotations of the open page are found by the canvas address. A bundle you model yourself can leave the field empty and is then found by the file.

Finding the annotations of the open page:

Mirador sends the canvas address.
If a canvas field is mapped, Drupal searches annotations whose canvas field equals that address, and does not look at the file.
Otherwise Drupal loads the canvas and reads filepath and fileuri. With an area, it finds areas whose image field holds either address, then the annotations that point at those areas. Without an area, it searches the annotation's image field directly.

An annotation found by the file shows up wherever that file is shown. An annotation found by the canvas shows up only on that page of that entity's manifest.

The image bundle is not chosen on the annotation settings page. It is a pathbuilder group. Its URL field is the address the views already give Mirador, and its annotations field is the reverse path (L49i, then the area, then L43i) that lists the annotations of that image. Views read those fields from the pathbuilder. Adding an annotation writes the file address on the area, so the same image individual shows the annotation through that reverse path.

Canvas in the WissKI ontology is a subclass of Digital_Media: one page of a manifest, not the image file. Ontology 1.2.0 had a different class, http://wiss-ki.eu/ontology/1.2.0/Canvas, a subclass of its Image. The path the annotation model adds is:

Annotation ── P67 refers to ──▶ Canvas ── P1 is identified by ──▶ URL ── P3 has note

The stored value is the canvas address. The canvas individual is reused (disamb on Canvas) when that address is written again. Reload the WissKI ontology in the store of the pathbuilder before adding the model, so the class is there.

Configuration¶

Annotations are stored and mapped at Configuration → WissKI → WissKI Mirador (/admin/config/wisski/mirador-annotations). The sections below are that page: the shipped model, your own bundle, and enabling annotations on a view. Showing images in a view or on one entity does not require annotations.

Store annotations¶

Annotations are off until you enable them at Configuration → WissKI → WissKI Mirador (/admin/config/wisski/mirador-annotations). Annotations are WissKI individuals; once enabled, the page shows the bundle and fields they are stored in, for all WissKI Mirador views.

Use the WissKI annotation model¶

WissKI ships a semantic annotation model built from CIDOC CRM, CRMdig and the WissKI ontology. The store of the pathbuilder must contain WissKI ontology 2.7.0 or later, CIDOC CRM 7.1.3 or later and CRMdig 4.0 or later. The forms read the versions the WissKI ontology page lists and refuse to continue when one is missing or older.

On the settings page, open More actions in the top bar and select Add the WissKI annotation model. Without the navigation top bar, the same action is the button on the page.
Choose the pathbuilder and what to add:
- Annotation group (see Annotation model on the WissKI Mirador help page);
- Image file (see Image file model on the WissKI Mirador help page).
Without the image file group, choose the image group of your data and its URL field: the image path of the area continues with that field's path.
Select Continue, review the groups and fields that will be added, and confirm. A progress bar shows the bundles and fields being generated.

Annotation (crmdig:D29) ── P1 is identified by ──▶ UUID ── P3 has note              UUID
                        ├─ P190 has symbolic content                               annotation document (JSON)
                        ├─ P106 is composed of ──▶ Annotation_Text ── P3 has note   text (formatted)
                        ├─ P2 has type ──▶ Keyword ── P1 ──▶ Preferred_Name ── P3   keywords (reused)
                        ├─ P67 refers to ──▶ Canvas ── P1 ──▶ URL ── P3 has note   canvas (reused)
                        ├─ L43 annotates ──▶ Annotated_Area (subgroup)
                        │     ├─ P190 has symbolic content                         SVG
                        │     └─ L49 is primary area of ──▶ {URL path of the image group}   image
                        └─ L48i was annotation created by ──▶ D30 Annotation Event (subgroup)
                              ├─ P14 carried out by ──▶ E21 Person ── P1 ──▶ E41 Appellation ── P3   creator
                              └─ P4 has time-span ──▶ E52 ── P82 at some time within               created

Image_File (group) ── P1 is identified by ──▶ URL ── P3 has note                    URL
                   └─ L49i has primary area ──▶ Annotated_Area ── L43i is annotated by ──▶ Annotation   annotations

The area and the event are subgroups because WissKI creates the intermediate individuals of every path anew: SVG and image on two paths of the annotation group would describe two different areas, creator and creation time two different events. The image path of the area ends like the URL path of the image group and reuses (disamb) its image individuals, so the image file group lists the images of your data with their annotations. The groups stay editable in the pathbuilder like any other.

The settings page¶

Annotation mapping is what Mirador writes an annotation to: the annotation bundle and its fields, then the Area with its subgroup, SVG and image, then the Annotation event with its subgroup, creator and creation time. Only the subgroups of the chosen bundle are offered. The image field stores which image the annotation belongs to. Canvas stores the address of the IIIF page and is how the shipped model finds the annotations of that page. Keywords holds the tags: each tag is the name of a keyword, and a keyword that already has that name is reused. The keyword field is part of the annotation group Add the WissKI annotation model writes. Both groups are explained on the WissKI Mirador help page (Administration → Help).
Creator name chooses what is written into the creator field: the username, a field of the user (for example Name), or a fixed value. The same name is shown as the author in the editor. An empty field or fixed value falls back to the username.

Use your own bundle¶

If you model annotations yourself, enable annotations on the settings page and map your WissKI bundle: the annotation bundle, fields for the UUID and the annotation document (JSON), and the image field are required. The image field stores the address of the canvas image, so the annotation belongs to that image. It is not the image field of the view. Text, keywords, SVG, canvas, creator and creation time are optional copies of parts of the document, for searching and editing; a formatted text field keeps the formatting. The xywh box stays in the annotation document. Keywords are the tags. The field stores the name, and the keyword that already has that name is reused, as on an object's keyword path. If your annotation group has subgroups for the area and the event, choose them; their reference fields follow from the pathbuilder, and the image, SVG, creator and creation time fields belong to them, as in the WissKI model.

When a mapped field is filled, it wins over the JSON document, so an edit in the entity form is what Mirador shows. Annotations are found by the image the canvas shows; if a canvas field is mapped, by canvas, as before.

Enable annotations in a view¶

In the view's WissKI Mirador format settings, check Enable annotations.
Grant API Access to WissKI Mirador to the roles that may annotate.

Users without that permission see the viewer without the annotation tools. Creating, editing and deleting an annotation additionally needs create, update or delete access to the annotation entity, as on the entity's own forms.

The viewer shows its images whether or not annotations are enabled.

Annotation mappings of views

Views used to map annotations in their format settings. drush updb moves the first complete mapping to the settings page if annotations are not enabled there yet, and removes the mapping options from all views. A view mapping that differs from enabled settings is dropped; its annotations stay stored but are no longer shown.

Where annotations are stored

The annotation API reads the mapping from the settings. The browser only sends the annotation itself, so it cannot choose where annotations are written.

Annotations from Mirador 3

Annotations stored by the Mirador 3 plugin mirador-annotations are converted to the shape the Mirador Annotation Editor reads when they are shown. The stored data is not rewritten.

Annotation API¶

Mirador talks to these endpoints, which follow the Annotot protocol; the module's own adapter in js/wisski_mirador.js talks to them:

Method	Path	Purpose
`GET`	`/wisski/mirador-annotations/{view}/{display}/pages?uri={canvas}`	Annotation page of a canvas
`POST`	`/wisski/mirador-annotations/{view}/{display}`	Create an annotation
`PATCH`	`/wisski/mirador-annotations/{view}/{display}?uuid={id}`	Update an annotation
`DELETE`	`/wisski/mirador-annotations/{view}/{display}?uuid={id}`	Delete an annotation

POST and PATCH require Content-Type: application/json. POST, PATCH and DELETE with a session cookie require the X-CSRF-Token header with the token from /session/token; the WissKI Mirador viewer sends it itself. A new annotation must target a canvas of this site (/wisski/{id}/sequence/…/normal.json); the canvas is resolved inside Drupal, not fetched over HTTP.

Permissions¶

Permission	Allows
API Access to WissKI Mirador	Using the annotation API and seeing the annotation tools
Administer WissKI Mirador	Installing and updating the library from the status report, and the annotation settings

Link to repository