Skip to content

IIIF

Jump to bottom
nilsw-ra edited this page Mar 17, 2022 · 20 revisions

Riksarkivet tillgängliggör publika digitiserade arkivhandlingar via IIIF (International Image Interoperability Framework). IIIF innehåller en serie protokoll för hantering och publicering av digitala bilder. Riksarkivet stöder IIIF Image 3.0 och IIIF Image 2.0 för bildhantering och IIIF Presentation 3.0 för presentation. Utöver dessa finns IIIF Authentication 1.0 för autenticering av bildresurser, IIIF Search 1.0 för sökning inom IIIF-resurser och IIIF Change Discovery 1.0 för publicering av ändringar i IIIF-resurser.

Dessa används i Riksarkivets tjänst Sök i arkiven, t.ex. uppslag ur Bergshammars vapenbok. I och med användningen av IIIF-APIerna kan bilderna visas i andra bildvisningstjänster, t.ex. Universal Viewer exempel. IIIF Image ger möjlighet att zooma och panorera bilderna, IIIF Presentation ger bläddring mellan relaterade bilder och presentation av metadata med hjälp av bildvisaren Universal Viewer.

IIIF Image

Image-APIet har metoder för att bearbeta källbilder. Riksarkivets IIIF-tjänst når compliance level 1, och stöder de metoder som inte är kursiverade nedan:

  • Utsnitt (fullständig, kvadratisk, x/y/bredd/höjd, procent x/y/bredd/höjd)
  • Skalning (max, bredd, höjd, bredd & höjd, bredd/höjd med uppskalning, bredd/höjd med begränsning)
  • Rotation (0, "rotationBy90s", godtycklig, spegelvändning)
  • Färgkvalitet (original, färg, gråskala, bitonal)
  • Bildformat (jpeg, png, tif, gif, pdf, jp2, webp)

Riksarkivets IIIF-tjänst stöder även IIIF Image 2.0, t.ex. för användning i bildvisare som inte stöder IIIF Image 3.0, som Universal Viewer.

Anrop (request)

Alla anrop använder HTTP GET.

Svar (response)

Svaret för alla IIIF Image-anrop har content-type: image/jpeg. Felaktiga anrop ger statuskod:

  • 400 BadRequest, delaktiga parametrar
  • 403 Forbidden, bilden saknar rättighstemärkning
  • 404 Not Found, bilden saknas
  • 429 Too many requests, klienten har överskridit rate limit, headers X-RateLimit-xxx anger gränsen och tid när det går att upprepa anropet
  • 501 Not Implemented, ej implementerad funktion

Proxy för IIIF Image

Externa tjänster som använder en IIIF bildvisare, som Universal Viewer eller Mirador, kan med fördel använda en reverse proxy så att bildvisaren inte anropar Riksarkivets IIIF Image API endpoint direkt.

Riksarkivet loggar användarens IP-adress för statistikändamål, se användningsvillkoren. I och med att anropen till IIIF Image API sker från webbläsaren kommer alltså loggen att lista slutanvändarens IP-adress om bildvisaren använder Riksarkivets API endpoint direkt. Med en reverse proxy kommer Riksarkivets logg att lista IP-adress för proxy-servern i stället. Det har flera fördelar:

  • Den externa tjänsten behöver inte upplysa om att slutanvändarens IP-adress loggas för statistik
  • Riksarkivets statistik blir bättre om all IIIF Image-trafik från en extern tjänst loggas samlat under proxy-serverns IP-adress
  • Utvecklaren av den externa tjänsten kan sätta upp egen statistikhantering med hjälp av loggning i proxy-servern

En reverse proxy kan sättas upp med t.ex. Apache HTTP Server eller NGINX.

Exempel: reverse proxy med Apache HTTP Server

Exempel: reverse proxy med Nginx

Version 3.0

https://lbiiif.riksarkivet.se/{bild-id}/{region}/{storlek}/{rotation}/{färgmodell}.jpg https://lbiiif.riksarkivet.se/v3/{bild-id}/{region}/{storlek}/{rotation}/{färgmodell}.jpg

För en fullständig beskrivning av URI-syntax se version 3.0

Parameter Beskrivning
region Önskat utsnitt av bilden: "full" eller "x-start,y-start,bredd,höjd"
storlek Önskad storlek i pixlar på bilden: "max", "bredd, höjd", "bredd," eller ",höjd"
rotation Önskad rotation av bilden: "0", "!0", "90", "!90", "180", "!180", "270" eller "!270", där talet anger vinkel (i jämna 90-gradersintervall) och ! anger spegelvändning
färgmodell Tjänsten stöder endast "default"

Version 2.0

https://lbiiif.riksarkivet.se/v2/{bild-id}/{region}/{storlek}/{rotation}/{färgmodell}.jpg

För en fullständig beskrivning av URI-syntax se version 2.0.

Parameter Beskrivning
region Önskat utsnitt av bilden: "full" eller "x-start,y-start,bredd,höjd"
storlek Önskad storlek i pixlar på bilden: "full", "bredd, höjd", "bredd," eller ",höjd"
rotation Önskad rotation av bilden: "0", "!0", "90", "!90", "180", "!180", "270" eller "!270", där talet anger vinkel (i jämna 90-gradersintervall) och ! anger spegelvändning
färgmodell Tjänsten stöder endast "default"

Exempel på IIIF Image-anrop

Bildformat (format)

Endast stöd för "jpg"

Färgmodell (quality)

Endast stöd för "default"

"Region" / Utsnitt

Exempel på "full" (fullständig): http://lbiiif.riksarkivet.se/arkis!C0002787_00008/full/max/0/default.jpg

Exempel på "square" (kvadratisk): http://lbiiif.riksarkivet.se/arkis!C0002787_00030/square/max/0/default.jpg

Exempel på utsnitt baserat på absoluta pixelvärden: http://lbiiif.riksarkivet.se/arkis!C0002787_00008/300,300,100,100/max/0/default.jpg

"Size" / Skalning

Skala på bredd: http://lbiiif.riksarkivet.se/arkis!C0002787_00030/full/300,/0/default.jpg

Skala på höjd: http://lbiiif.riksarkivet.se/arkis!C0002787_00030/full/,500/0/default.jpg

Skala på bredd samt höjd: http://lbiiif.riksarkivet.se/arkis!C0002787_00030/full/500,300/0/default.jpg

Rotation

Ingen rotation (0): http://lbiiif.riksarkivet.se/arkis!C0002787_00008/full/max/0/default.jpg

Rotation 90 grader medurs: https://lbiiif.riksarkivet.se/arkis!C0002787_00030/full/max/90/default.jpg

Rotation 90 grader medurs och speglad: https://lbiiif.riksarkivet.se/arkis!C0002787_00030/full/max/!90/default.jpg

IIIF Presentation

Presentation-APIet servar resurser som gör det möjligt att presentera bilder och audiovisuella media (ljud och film) med tillhörande metadata i en klienttillämpning (webbsida, app, etc.) Det finns två typer av resurser på den yttersta nivån:

  • Manifest, som innehåller referenser till bilder/audiovisuella filer och metadata
  • Collection, som innehåller referenser till underliggande Collections och Manifest för en hierarkisk gruppering

Svaren (response) är JSON-LD-dokument, dvs RDF-modeller, serialiserade i JSON-format, se ett exempel här: https://iiif.io/api/presentation/3.0/#b-example-manifest-response. Det finns flera visningstillämpningar för IIIF-manifest, t.ex.

Anrop (request)

Alla anrop använder HTTP GET.

Presentation-APIet har en enkel URL-syntax.

Manifest

https://lbiiif.riksarkivet.se/{identifierare}/manifest

Collection

Riksarkivet tillhandahåller en Collection-struktur för att externa klienter skall kunna bläddra sig fram till manifesten.

https://lbiiif.riksarkivet.se/collection/riksarkivet

Collection på toppnivån innehåller referenser till följande parallella sorteringar/hierarkier:

Ämnesområde - https://lbiiif.riksarkivet.se/collection/amnesomrade
Brott och straff
https://lbiiif.riksarkivet.se/collection/brott-och-straff
Emigration
https://lbiiif.riksarkivet.se/collection/emigration
Fastigheter och gårdar
https://lbiiif.riksarkivet.se/collection/fastigheter-och-gardar
Fotografier
https://lbiiif.riksarkivet.se/collection/fotografier
Gästgiveri och skjutsväsen
https://lbiiif.riksarkivet.se/collection/gastgiveri-och-skjutsvasen
Heraldik
https://lbiiif.riksarkivet.se/collection/heraldik
Idrott
https://lbiiif.riksarkivet.se/collection/idrott
Kartor och ritningar
https://lbiiif.riksarkivet.se/collection/kartor-och-ritningar
Tid - https://lbiiif.riksarkivet.se/collection/tid

Fler sorteringar tillkommer efter hand, t.ex. Ort.

Interna referenser

På nedersta nivå, som normalt motsvarar arkivenheter av typen serie, innehåller en Collection referenser till Manifest, som normalt motsvarar arkivenheter av typen volym. Interna referenser, till volymer i andra serier (Se: i Riksarkivets söktjänst), är inkluderade i items-listan om de hänvisar inom samma arkiv. Referenser till volymer i andra arkiv visas i söktjänsten men följer inte med i IIIF Collections på grund av tekniska begränsningar.

Presentationsresursernas innehåll och struktur finns beskrivna i specifikation för Presentation API.

CORS

IIIF-tjänsten skickar inte automatiskt response header

Access-Control-Allow-Origin: *

då detta inte fungerar med lösningar i Riksarkivets söktjänst. En API-klient som behöver CORS-stöd kan skicka med request header

Origin: https://domain.tld

och få tillbaka response header

Access-Control-Allow-Origin: https://domain.tld

Med en egen reverse proxy mot IIIF-tjänsten går det också att sätta response header

Access-Control-Allow-Origin: https://domain.tld

för alla anrop. Se reverse proxy med Apache HTTP Server och reverse proxy med Nginx för exempel på hur konfigurationen kan se ut.

Hitta bild-id från arkivenhet/pid

Arkivenheter på alla nivåer (arkiv, serie, volym, fotografi, karta/ritning etc.) har en persistent identifierar (pid) som kan användas för att länka till arkivenhetens presentation i söktjänsten, t.ex. 2Yz2ClKdn2VMeUXQcoZOO6 som via https://sok.riksarkivet.se/arkiv/2Yz2ClKdn2VMeUXQcoZOO6 länkar till volymen SE/RA/2113/2113.2/1, [Diplomatica Muscovitica Cosacica] 1654-1721, Filip Orliks ukrainska konstitution. Volymen har bilder, för att hitta bild-id

Riksarkivet

Clone this wiki locally