MyCoRe Logo
Deutsch English
2019.06 2020.06

IIIF API

Dieser Abschnitt beschreibt die Integration des International Image Interoperability Frameworks (IIIF).

Einführung

Mit dem MyCoRe Modul mycore-iiif ist es möglich, Metadaten und Bilder über URLs im IIIF API Format bereitzustellen. Dadurch können beispielsweise in MyCoRe-Anwendungen gespeicherten Bilddaten auch in externen IIIF Viewern angezeigt werden.

MyCoRe 2020.06 implementiert die IIIF Image API Version 2.1.1.

Die Konfigurationsmöglichkeiten wurden in 2020.06 überarbeitet.
Dabei wurde u.a. die Basis-URL von /rsc/iiif auf /api/iiif geändert.

Installation und Konfiguration

Das Modul mycore-iiif wird in die pom.xml der MyCoRe-Anwendung als Abhängigkeit eingetragen.

Da eine MyCoRe-Anwendung im Image-Identifier in der Regel URL-codierte Slashes (/ = %2F) verwendet, muss der Webserver dafür entsprechend konfiguriert werden:

Tomcat

Im Tomcat muss das System-Property org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true gesetzt werden.
Das kann durch Eintrag in die Konfigurationsdatei catalina.opts erfolgen oder indem der Tomcat mit dem Parameter -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true gestartet wird.

In aktuellen Tomcat-Versionen (>= 8.5.54, >= 9.0.34, >= 10) erfolgt die Konfiguration statt dessen über das Connector-Attribut encodedSolidusHandling="passthrough" in der Konfigurationsdatei server.xml.
(siehe: https://tomcat.apache.org/tomcat-8.5-doc/config/http.html#Common_Attributes). 

1
2

<Connector protocol="AJP/1.3" packetSize="65536" 
           encodedSolidusHandling="passthrough" port="8009" redirectPort="8443" />

Tomcat-Konfiguration: …/tomcat/conf/server.xml

Apache

1
2
3
4
5
6
7

AllowEncodedSlashes On

<Location /digibib/ >
  ProxyPass ajp://localhost:8080/digibib/ nocanon
  ProxyPassReverse ajp://localhost:8080/digibib/
  Require all granted
</Location>

Apache-Konfiguration: /etc/apache/sites-available/digibib.conf

Jetty

Keine spezifischen Anpassungen nötig. Jetty verarbeitet codierten Slashes (/) korrekt.

IIIF Image API

Aufbau der URL

Gemäß IIIF Image API Spezifikation haben URLs die folgende Struktur:
{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}.

{scheme}://{server}

entspricht der Basis-URL der MyCoRe-Anwendung

{prefix}

kann aus mehreren Pfad-Bestandteilen bestehen. Optional kann es an erster Stelle den Pfad zur Anwendung enthalten,
z.B.: http://localhost:8080/skeleton/api/v2/...

Die weiteren Pfad-Bestandteile bilden den Pfad zur IIIF API. Sie können ggf. eine ID für eine konkrete Implementierung enthalten,
z.B.: /api/iiif/image/v2 bzw. /api/iiif/image/v2/Iview bzw. /api/iiif/image/v2/thumbnail.

{identifier}

Der Image-Identifier hat in der MyCoRe-Standardimplementierung die Syntax: derivate_id:/pfad/zum/image.ext
Slashes sind in ihrer URL-codierten Form (%2F) zu verwenden,
z.B.: skeleton_derivate_00000024:%2Fsample1.png

/{region}/{size}/{rotation}/{quality}.{format}

Diese Parameter werden gemäß der IIIF API Spezifikation verwendet.

Beispiele

Verschiedene Implementierungen

Es lassen sich verschiedene Implementierungen der IIIF API in MyCoRe verwenden.
Die Standardimplementierung Iview arbeitet mit den gekachelten Bilddateien, die für MyCoRe-Viewer verwendet werden.

Folgende Properties können für die Konfiguration der Implementierung verwendet werden: 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# setzt die ID der Standardimplementierung, welche dadurch in der IIIF URL weggelassen werden kann
MCR.IIIFImage.Default=myimpl
    
# definiert die konkrete Klasse für die Implementierung
MCR.IIIFImage.myimpl=org.mycore.iview2.iiif.MCRIVIEWIIIFImageImpl

# definiert die maximale Größe eines ausgelieferten Images in Bytes.
# Bei größeren Bildern muss eine skalierte Größe (mit reduzierter Breite und Höhe)
# oder ein Ausschnitt definiert werden.
MCR.IIIFImage.myimpl.MaxImageBytes=1073741824

# gibt an, für welche Bildformate ein transparenter Hintergrund zurückgeliefert wird 
MCR.IIIFImage.myimpl.TransparentFormats=png

# bei der Verwendung von MCRIVIEWIIIFImageImpl:
# gibt eine Klasse mit einer alternativen Implementierung von org.mycore.iview2.backend.MCRTileFileProvider
# an, die zu einem gegebenen Identifier den Ablageort für die gekachelten Iview2-Bilddateien zurückliefert.
MCR.IIIFImage.myimpl.TileFileProvider=org.myinstiution.myimplementation.MyTileFileProvider

Konfiguration: mycore.properties

Beispiele

Implementierung für Thumbnails (von Bilder und PDF-Dateien)

MyCoRe liefert eine Spezialimplementierung für Vorschaubilder (Thumbnails) mit. In dieser Implementierung wird als Image-Identifier an Stelle einer Bilddatei die ID eines MyCoRe-Objektes angegeben.

Für PDFs werden die Vorschaubilder beim Speichern der MyCoRe-Objekte über einen Eventhandler extrahiert und im internen Bildformat abgelegt.

Es kann konfiguriert werden, welche Derivate-Typen der Eventhandler für die Thumbnail-Generierung berücksichtigen soll: 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# aktiviert die IIIF API Implementierung für Thumbnails
MCR.IIIFImage.thumbnail=org.mycore.iview2.iiif.MCRThumbnailImageImpl

# reduziert die zurückgelieferte Bildgröße (breite x höhe x farbtiefe = 1024 x 1024 x 3)
MCR.IIIFImage.thumbnail.MaxImageBytes=3145728

# Formate, für die ein transparenter Hintergrund gesetzt werden kann
MCR.IIIFImage.thumbnail.TransparentFormats=png

# Derivate Typen (Einträge aus der Klassifikation derivate_types), 
# die für die Thumbnail-Auslieferung in Frage kommen 
MCR.IIIFImage.thumbnail.Derivate.Types=derivate_types:thumbnail,derivate_types:content

# Eventhandler für die Generierung von Thumbnails aus PDF-Dateien
MCR.EventHandler.MCRDerivate.080.Class=org.mycore.iview2.events.MCRThumbnailForPdfEventHandler

# Derivate Typen (Einträge aus der Klassifikation derivate_types), 
#die für die Thumbnail-Erstellung in Frage kommen
MCR.IIIFImage.Iview.ThumbnailForPdfEventHandler.Derivate.Types=derivate_types:content

Konfiguration: mycore.properties

Beispiele

IIIF Presentation API

MyCoRe implementiert die IIIF Presentation API v.2.1.1. Diese kann verwendet werden, um Inhalte aus MyCoRe-Repositorien in anderen Webanwendungen mit standardisierten Viewern anzuzeigen. Beispielimplementierungen für IIIF-Viewer sind:

Konfiguration

In MyCoRe lassen sich verschiedenen Implementierungen der IIIF Presentation API verwenden. Die Standardimplementierung mets erstellt die Manifest-Datei aus einer bestehenden MyCoRe-Viewer-METS-Datei.

Folgende Properties können für die Konfiguration der Implementierung verwendet werden: 

1
2
3
4
5
6
7
8

# setzt die ID der Standardimplementierung, welche dadurch in der IIIF URL weggelassen werden kann
MCR.IIIFPresentation.Default=Mets

# definiert die konkrete Klasse für die Implementierung
MCR.IIIFPresentation.Mets=org.mycore.mets.iiif.MCRMetsIIIFPresentationImpl

# definiert den XSLT-Transformer für die Konvertierung der METS Datei in eine IIIF-Manifest-Datei
MCR.IIIFPresentation.Mets.Transformer=mets-dfg

Konfiguration: mycore.properties

Beispiele



Konfiguration und Verwendung 2019.06

Die Konfiguration ist recht einfach. Auf jeden Fall muss das Modul mycore-iiif in der pom.xml als Abhängigkeit eingetragen werden. Weiterhin sind folgende Properties in der mycore.properties zu setzen:

  • MCR.IIIFImage.IView=org.mycore.iview2.iiif.MCRIVIEWIIIFImageImpl
  • MCR.IIIFImage.IView.TransparentFormats=png,gif

Dabei gibt IView im Property-Namen den Typ der Implementierung an. MCRIVIEWIIIFImageImpl ist dann die Klasse der konkreten Implementierung. Die Lösung mit MCRIVIEWIIIFImageImpl benötigt das weitere Property TransparentFormats .

Die Daten können nun wie folgt abgerufen werden. Dabei ist darauf zu achen, das der Pfad zu den Bildern encoded ist (/ -> %2F).

  • http://my.mycore.repository.org/mycore_context/rsc/iiif/image/IView/... (Image API)
  • http://my.mycore.repository.org/mycore_context/rsc/iiif/presentation/IView/ (Presentation API)
Jens Kupferschmidt Sebastian Hofmann Robert Stephan - 12.06.2020