Skip to content

IIIF

Jump to bottom
David Haskiya edited this page Jul 28, 2023 · 20 revisions

English version

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 media, primärt bilder men också video och ljud. Riksarkivet stöder

Utöver dessa ingår följande i IIIF-standarden

Det finns för närvarande ingen tidplan för att implementera de senare i Riksarkivets IIIF-tjänst.

Riksarkivets tjänst Sök i arkiven använder IIIF Image och IIIF Presentation, t.ex. uppslag ur Bergshammars vapenbok. 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. I och med användningen av IIIF-APIerna kan bilderna visas i andra bildvisningstjänster, t.ex. Universal Viewer exempel.

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, felaktiga 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!R0001216_00005/full/max/0/default.jpg

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

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

"Size" / Skalning

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

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

Skala på fast bredd och höjd (ändrar bildens proportioner): http://lbiiif.riksarkivet.se/arkis!R0001216_00005/full/500,300/0/default.jpg

Rotation

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

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

Rotation 90 grader medurs och speglad: https://lbiiif.riksarkivet.se/arkis!R0001216_00005/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 (ljud, video) filer och metadata till dessa
  • Collection, som innehåller referenser till underliggande Collections och Manifest för en hierarkisk gruppering

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 fram till manifesten.

Toppnivå-collection: https://lbiiif.riksarkivet.se/collection/riksarkivet

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

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

Svar (response)

Svaret för alla IIIF Presentation-anrop har content-type: application/json. Felaktiga anrop ger statuskod:

  • 400 BadRequest, felaktig parameter (identifierare)
  • 403 Forbidden, resursen saknar rättighstemärkning eller är inte tillgänglig via API av andra skäl
  • 404 Not Found, resursen 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

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 med öppen källkod, t.ex.

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 eller karta/ritning. 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.

Rättigheter

IIIF Presentation- och IIIF Image-APIerna ger tillgång till data som berör öppet (ej sekretessbelagt) arkivmaterial som är äldre än 110 år.

IIIF Presentation manifest och IIIF Image är tillgängliga för bildmaterial som har explicit rättighetsmärkning. Tilldelning av rättighetsmärkning är ett pågående arbete.

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. Till exempel: **2Yz2ClKdn2VMeUXQcoZOO6 **kan användas till en URL https://sok.riksarkivet.se/arkiv/2Yz2ClKdn2VMeUXQcoZOO6 som länkar till presentation i söktjänsten av volymen SE/RA/2113/2113.2/1, [Diplomatica Muscovitica Cosacica] 1654-1721, Filip Orliks ukrainska konstitution. Volymen är digitiserad, för att hitta IIIF-manifestets URI kan man hämta data om volymen som en IIIF Collection med https://lbiiif.riksarkivet.se/collection/arkiv/2Yz2ClKdn2VMeUXQcoZOO6

{
  "id": "https://lbiiif.riksarkivet.se/collection/arkiv/2Yz2ClKdn2VMeUXQcoZOO6",
  "type": "Collection",
  "label": {
    "sv": [
      "1 (1654-1721) - Handlingar rörande förhandlingar mellan Sverige oc..."
    ]
  },
  "summary": {
    "sv": [
      "Referenskod: SE/RA/2113/2113.2/1",
      "Arkivinstitution: ",
      "Datering: 1654-1721"
    ]
  },
  "items": [
    {
      "id": "https://lbiiif.riksarkivet.se/arkis!R0000480/manifest",
      "type": "Manifest",
      "label": {
        "sv": [
          "1 (1654-1721) - R0000480 - Handlingar rörande förhandlingar mellan Sverige oc..."
        ]
      }
    }
  ]
}

URI till bildernas IIIF-manifest finns under "items".

Kodexempel (Python)

Riksarkivet

Clone this wiki locally