IIIF v osobním obsahu 2021

Osobní obsah a virtuální výstavy dostupné přes IIIF: zpráva o implementaci IIIF Presentation API.

Tento dokument je zprávou o implementaci IIIF Presentation API pro potřeby disseminace osobního obsahu a virtuálních výstav do Manuscriptoria.

Úvodem

Cílem prací bylo umožnit poskytování uživatelského obsahu Manuscriptoria prostřednictvím protokolu IIIF Presentation API a tím zásadně navýšit užitek z jeho tvorby, protože obsah tvořený v Manuscriptoriu bude ve formě IIIF dostupný i mimo systém Manuscriptoria prostřednictvím libovolné služby či SW s podporou IIIF protokolů.

Uživatelský obsah tvořený uživateli Manuscriptoria tvoří ontologie entit (graf) reálného světa. Jako takový je snadno propojitelný s ostatními ontologiemi spravovanými v Manuscriptoriu.

„Struktura“ takového grafu je velmi pestrá a předpokládáme, že se bude v budoucnu plynule vyvíjet tak, jak se budou vyvíjet potřeby a činnosti uživatelů Manuscriptoria (ať už máme na mysli uživatele koncové, nebo tvůrce a poskytovatele dat, nebo spolupracující systémy třetích stran, jako je Europeana). Naším cílem přitom není přizpůsobit strukturu informací strukturám výměnných formátů – ani těm triviálním, jako je například Dublin Core, nebo těm sofistikovaným, za jaký považujeme protokol IIIF Presentation.

Smyslem existence IIIF je usnadnit sdílení a využívání obsahu bez ohledu na to, z jakého obsahového repositáře tento obsah pochází. Naším cílem tedy je překládat vlastní bohatě strukturovaný obsah do univerzální formy podle IIIF.

To má smysl nejen pro „oficiální“ agregovaný obsah Manuscriptoria, ale také pro obsah tvořený koncovými uživateli.

Struktura uživatelského obsahu v Manuscriptoriu

Tento obsah může být poskládán z dílčích informací různých typů. Těmto informacím říkáme pracovně „nibbles“ (kousíčky) a jedná se nově o položky typu:

• Záznam
• Dokument
• Stránka dokumentu
• IIIF Manifest
• Obraz
• IIIF Obraz
• Text
• Odkaz
• Video stream
• Audio stream (ve vývoji)

Takové nibbles patří uživateli a jsou otiskem oficiálního obsahu, který nazýváme pracovně „cuts“ a který je unikátní v rámci konkrétní více či méně specifické služby (katalogy, digitální knihovny, obrazové repositáře, streamovací služby, webové encyklopedie …). Zatímco nibbles uživatel opatřuje vlastním obsahem (jako je například poznámka, popiska, jiný text apod.), obsah cuts.

Forma uživatelského obsahu v Manuscriptoriu

Byť je struktura informací na pozadí univerzální, může být forma výsledného uživatelského obsahu velice různorodá - podle způsobu, jakým uživatel jednotlivé nibbles uspořádá. Může jít o:

• virtuální kolekce (výběr záznamů či digitálních dokumentů opatřený poznámkami),
• virtuální dokumenty (výběr stránek/obrazů z různých fyzických exemplářů uspořádaný do nového virtuálního dokumentu),
• články (autorské texty s odkazy na záznamy či obrazy),
• virtuální výstavy (různorodě zaměřený, bohatě strukturovaný mix textů, poznámek, záznamů, obrazů a odkazů),
• jakýkoliv jiný obsah dle potřeb konkrétního uživatele.

Konkrétní cíl, hlavní výzvy

Naším cílem tedy bylo primárně splnit zdánlivě prostý úkol:

1. Najít způsob, jak převádět uživatelský obsah do formy IIIF, bez ohledu na to, jakou má formu.
2. Zvolit takový způsob, aby byl co možná nejlépe použitelný bezprostředně po implementaci řešení.

Největší výzvou se dle očekávání ukázalo naplnit druhý bod: a to zejména proto, že IIIF Presentation API dovoluje velké množství variant zápisu stejného typu informace a zároveň je dosti benevolentní ve svých požadavcích na klientské aplikace, který mají obsah interpretovat. Domníváme se, že jedno implikuje druhé a že to je v současnosti největší slabina jinak velmi perspektivního výměnného formátu: variant zápisu formát připouští tolik, že kombinací je příliš mnoho na to, aby bylo možné mít striktní požadavky na autory klientských aplikací (čteček).

Ve zkratce jde o to, že předpis IIIF Presentation API stanovuje pravidla typu MUST, SHOULD, MAY pro každou vlastnost, a to jak pro repository, tak pro klientskou aplikaci (více infromací k danému problému je také v naší zprávě o implementaci první verze nativní čtečky pro Windows: Charlene). I obyčejnou poznámku k jedné položce lze zapsat mnoha různými způsoby a je na vůli autorů čteček, zda a jak daný způsob uvedení poznámky implementuje (typicky „client SHOULD or MAY implement what repository SHOULD or MAY provide“).

Způsob řešení

Naše práce tedy spočívala v opakování těchto kroků:

1. Zvolit způsob mapování konkrétního fragmentu obsahu tak, aby byl výsledek validní dle předpisů,
2. naprogramovat převody,
3. testovat výsledek s využitím obsahu různých forem, což zahrnovalo
   • nejprve validaci s využitím IIIF validátoru,
   • testování a vyhodnocení zobrazení ve vybrané referenční čtečce,
4. vybrat nové mapování,
5. vrátit se ke kroku 1 nebo pokračovat dalším typem obsahu.

Jako referenční čtečku jsme vybrali výsledek projektu Mirador - v současnosti jednoznačně nejlepší a dosti univerzální on-line čtečku IIIF kompatibilního obsahu. Mirador jednak implementujeme do Manuscriptoria verze 4, ale lze ho najít i v řadě jiných projektů, kde pak lze načítat obsah tvořený v Manuscriptoriu.

Ani Mirador nezobrazoval vše, co by klient měl (SHOULD) zobrazovat a dokonce ani Mirador aktuálně nezobrazí celý obsah příkladů ze vzorového manifestu uváděného v závěru manuálu IIIF Presentation API.

Uvedeným způsobem jsme postupovali tak dlouho, dokud jsme nenalezli takový způsob mapování uživatelského obsahu, který je podle našeho názoru aktuálně optimálním kompromisem mezi:

1. (primárně a nepřekročitelně) správností zápisu do IIIF,
2. aktuálním způsobem zobrazení v Miradoru.

Kde to tedy bylo možné, hledali jsme variantu zápisu, kterou Mirador aktuálně dokáže zobrazit. Kde se nám toto nepodařilo, tak je obsah v IIIF kolekcích a manifestech poskytovaných Manuscritptoriem sice korektně uveden, ale Mirador jej ještě zobrazit nedokáže.

Domníváme se, že takto jsme zároveň nalezli optimální způsob zápisu, a proto hodláme působit v rámci volně navazujícího evropského projektu ARMA - The Art of Reading in the Middle Ages na to, aby na základě této naší práce vznikla určitá unifikovaná forma komunikace podobného typu obsahu poskytovaného všemi projekty oblasti historických knižních fondů. Věříme, že pak i autoři čteček doplní do svého SW podporu naší good practice.

Verze IIIF Presentation API

V létě 2020 zveřejnilo konsorcium IIIF Presentation API verze 3.0.0 jako stable version. Po zvážení odlišností proti původně implementované verzi 2.1 jsme se rozhodli dokončit implementační práce včetně přechodu na verzi 3.0.

Terminologické poznámka

Termíny převzaté z terminologie dokumentace IIIF Presentation API nepřekládáme a používáme je v anglickém jazyce. Definice termínů je pak dostupná v dokumentaci IIIF.

Uživatelský obsah v Manuscriptoriu je organizován do obecných kontejnerů, které nazýváme Kolekce (jednotlivé nibbles mohou být organizovány do kolekcí). Termín Collection používá také IIIF. Abychom oba termíny rozlišili, budeme používat český termín Kolekce pro kontejnery Manuscriptoria a anglický výraz Collection pro označení kolekcí v IIIF.

Uvažovaná řešení

S ohledem na vlastnosti a omezení IIIF Presentation API ve vztahu k osobnímu obsahu Manuscriptoria uvažujeme dvě řešení podle toho, zda obsahu Kolekcí uživatele budeme generovat jako Collections nebo jako Manifest.

Kolekce je Collection

Kolekce v Manuscriptoriu neslouží jen k organizaci dokumentů do stromečkové struktury a mají svou povahou do značné míry charakter dokumentu. Obsahem Kolekce mohou být nibbles libovolného typu, včetně nibble typu Kolekce. Neboli z pohledu typu obsahu se naše Kolekce blíží víc Manifestu, než Collection, i když může obsahovat vnořené Kolekce. Problém je, že podle pravidel IIIF obsahem Manifestů nemohou být Collections.

Struktura obsahu v manifestu je zachycena pomocí items. Definice o strukturálních vlastnostech říká:

💭 A Collection must have the items property. Each item must be either a Collection or a Manifest. Clients must process items on a Collection.

Z toho pro Manuscriptorium plyne, že v rámci Collection lze uvést items pro nibbles typu:

• záznam katalogu (zahrnout jako Manifest),
• dokument (zahrnout jako Manifest),
• kolekce (zahrnout jako Collections),
• stránka dokumentu (zahrnout jako Manifest s využitím property start).

Jakýkoliv jiný druh obsahu, který se může v Kolekci vyskytovat, se nedá zařadit přímo, ale musel by být zařazen v rámci vnořených manifestů.

Doporučení pro implementaci

Navrhujeme jednoduché řešení, kdy se jiný, než přímo podporovaný obsah do IIIF nepřevádí. Převedeny jsou tedy katalogové záznamy, celé dokumenty, stránky z dokumentů a Kolekce. Ostatní typy nibbles jsou ignorovány.

Veškerá relevantní popisná metadata vztahující se k jednotlivým položkám převáděnému obsahu, včetně uživatelských poznámek, se převádí v rámci properties label, description a metadata.

Takto vzniknou z osobního obsahu ekvivalenty virtuálních dokumentů a virtuálních kolekcí, což jistě má svou hodnotu, avšak dochází k vypuštění podstatné části informací – uživatel by na toto měl být upozorněn (bude-li vědět, že jako IIIF má smysl využít obsah typu virtuální dokument nebo virtuální kolekce, má řešení smysl).

Ověření funkčnosti v Miradoru

Mirador takto připravená data zobrazí. Nedokáže však zobrazovat obsah Annotation Page a Annotation k jednotlivým položkám dříve, než uživatel zobrazí aktuální Collection nebo Manifest.

Je-li tedy obsahem Kolekce externí dokument v IIIF a uživatel si k němu vytvořil vlastní obsah, jako například poznámku, musí implementace takového řešení zahrnout načtení koncových manifestů (například z partnerské repository) a dogenerování uživatelského obsahu do jeho sekce metadata. To je řešitelné, ale na systémové prostředky na straně serveru vcelku náročné řešení. A konečně, v případě Kolekcí záleží na pořadí jednotlivých položek obsahu, kdežto Mirador při prezentaci rozdělí obsah Collection na Collection a Manifesty.

Závěr

Je patrné, že aparát Collection je skutečně navrhnut jako jednoduché rozhraní a jeho využívání k interpretaci složitějšího obsahu uvedeným způsobem nemá smysl.

Kolekce je Manifest

Podstatou řešení je využití Manifestu jako kontejneru pro Kolekce.

Dokumentace IIIF říká:

💭 A Manifest must have the items property with at least one item. Each item must be a Canvas. Clients must process items on a Manifest.

Canvas je z podstaty (definice viz https://iiif.io/api/presentation/3.0/#21-defined-types) virtuální kontejner, který může obsahovat obrazy, video a text (atd.) a tudíž nemusí být nutně pouze kontejnerem pro zachycení obrazu fyzické stránky. Může to být jakékoliv view na daný blok obsahu obecně. Hodí se tedy velmi dobře pro zachycení uživatelského obsahu s nibbles různých typů.

Pokud jde o zanořování kolekcí, pak patrně jediný způsob, jak postupovat, je načítat položky obsahu jednotlivých vnořených Kolekcí přímo do jediného Manifestu nejhornější mateřské Kolekce a využít property structures pro modelování stromečkové struktury jednotlivých items.

Mapování jednotlivých položek Kolekce do Manifestu

Obsahem Manifestu kromě jiných properties jsou items výhradně typu Canvas. Ovšem v Canvasu můžeme uvádět jak další pole items (kam umístíme obrazy), tak pole annotations, kam vložíme jiný typ obrazu, jak uvádí definice na https://iiif.io/api/presentation/3.0/#53-canvas.

Obrazová data a textová data

Připravili jsme tedy příklad (priklad-B-01.json, priklad-B-01-invalid.json, priklad-B-02-2.json), abychom ověřili validitu a funkčnost v Miradoru. Samotný manifest je validní, pokud u Canvasu není uvedena property height a width - což postrádá logiku, pokud je předmětem canvasu něco jiného, než takto popsatelný objekt a především to neopovídá textu specifikace, která říká (https://iiif.io/api/presentation/3.0/#31-descriptive-properties), že

💭 A Canvas may have the height property. If it has a height, it must also have a width. Clients must process height on a Canvas.

Uvážit při implementaci: Jako work-around lze zatím pouze implementovat generování fiktivních hodnot pro tyto properties, protože i Mirador s oběma vlastnostmi počítá.

Po této úpravě je interpretace v Miradoru podle našeho názoru dostatečná (ačkoliv anotace na úrovni Canvasu nemá v defaultním rozvržení pracovního prostoru ideální umístění).

Následně jsme se pokusili přidat anotaci s motivací commenting s textem do Canvasu, který neobsahuje items a v textu obsahuje základní HTML markup (příklad priklad-B-03.json).

Manifest je validní a korektně se zobrazí v Miradoru, dochází však k podstatnému zjednodušení při interpretaci HTML obsahu (ačkoliv se při mapování pohybujeme v hranicích doporučeného specifikací v https://iiif.io/api/presentation/3.0/#45-html-markup-in-property-values) – například je ignorován atribut style v elementu span apod.

Uvážit při implementaci: Zjednodušit HTML v textech Kolekcí rovnou na sadu elementů, které Mirador právě podporuje (lepší je řízené zjednodušení při mapování do Manifestu, než chybná interpretace Miradorem).

Zároveň Mirador předpokládá, že těžištěm při zobrazování bude obrazová informace, takže uživateli nabízí plochu pro obraz, která zůstává prázdná. Z pohledu uživatele je to jistě matoucí, avšak při správném rozvržení dává i tak prohlížení v Miradoru smysl.

Pokoušeli jsme se použít varianty hodnoty motivation, počínaje v textu specifikace používaným supplementing:

💭 Content that is derived from the Canvas, such as a manual or automatic (OCR) transcription of text in an image or the words spoken in an audio representation, must be associated by an Annotation that has the motivation value supplementing.

Testovali jsme i hodnotu describing (dle W3C https://www.w3.org/TR/annotation-vocab/#motivation). Anotace s takovou motivací Mirador ignoroval.

Uvážit při implementaci: využít v manifestu jak možnost commenting annotation, tak i alternativní zobrazování obsahu pomocí rendering jako PDF (aplikace vygeneruje dílčí PDF pro daný textový nibble) nebo seeAlso jako XML.

Bohužel, rendering PDF zdá se Mirador aktuálně nepodporuje, i když dokumentace říká:

💭 Any resource type may have the rendering property with at least one item. Clients should render rendering on a Collection, Manifest or Canvas, and may render rendering on other types of resource.

Aktuálně Mirador vygeneroval externí odkaz (do nového tabu) na PDF jen pokud byla property rendering přítomná přímo v Manifestu. Stejně se Mirador chová k property seeAlso.

Uvážit při implementaci: využít defaultní obrázek v painted annotation Canvasu tak, aby indikoval, že se jedná o textovou položku a uživatel nebyl překvapen prázdným prostorem.

Uvážit při implementaci: generovat textový obsah jako obrázek a ten pak využít v painted items Canvasu.

Až dosud se nám využití Manifestu jako kontejneru pro Kolekce zdálo smysluplnější, než se o totéž snažit s Collection. Implementovat zvolené správné mapování do commenting annotation a zároveň generovat work-around dle doporučení a/nebo jen vyčkat na novější verze Miradoru.

Video a Audio

Pro Canvasy s video a audio obsahem lze využít annotace, jejichž obsahem je body typu Video nebo Sound jak ukazuje tento případ: https://iiif.io/api/cookbook/recipe/0003-mvm-video/.

Problém je, že takto lze použít přímé odkazy na video soubory, což není stejné, jako když se v Kolekcích odkazujeme ne stream služby typu YouTube a podobně. V případě Audio a Video obsahu je tedy potřeba pracovat s odkazy na Externí web resource.

Externí web resource

Pomocí annotations na externí web resource se lze obecně odkazovat na související externě dostupný obsah (viz https://www.w3.org/TR/annotation-model/#purpose-for-external-web-resources). Takto připravený obsah (příklad priklad-B-03-text-dlouhyText-a-PDF.json) však podle IIIF není validní. Lze použít property rendering, avšak tu na úrovni Canvasů Mirador neinterpretuje.

Jedinou možností tedy zůstává interpretovat commenting annotation a využít odkazování z textu anotace.

Toto je zřejmě jediné řešení, které lze aktuálně použít pro video, audio, externí odkazy, ale i vnořené manifesty, což je krajně nešikovné.

Závěr

Manifest se jako kontejner pro Kolekce nehodí, protože i když je vhodná struktura v IIIF Presentation API 3.0 definována, jsou značné mezery na straně klienta/čtečky, kde potřebná funkčnost nemá aktuálně dostatečnou podporu.

Zvolené řešení

Ani jedno z dosud uvažovaných řešení není samo o sobě optimální. Kolekce jako Manifest lze v principu disseminovat pomocí IIIF Presentation API, ale podpora zobrazení takového obsahu ve čtečkách je nedostatečná a zobrazení je kompromisní.

Kolekce jako Kolekce zase neumožňuje poskytnout nekrácený obsah a v Miradoru je obsah navíc přetříděn na skupinu Manifestů a skupinu Collections (viz výše).

Přesto se domníváme, že má smysl oba přístupy zkombinovat a to takto:

• Pokud Kolekce obsahuje pouze vnořené Kolekce, pak ji budeme interpretovat jako Collection.
• Pokud Kolekce nebude obsahovat žádnou vnořenou Kolekci, pak ji budeme interpretovat jako Manifest.
• Pokud kolekce obsahuje jak vnořené Kolekce, tak jiné položky (záznamy, texty, obrazy) pak její obsah při generování IIIF přeorganizujeme pro potřeby zobrazení tak, aby blok položek, které nejsou Kolekcí, byly sdruženy do vygenerované Kolekce s generickým názvem (Část číslo X apod.) a sekvence samostatných položek (které nejsou reprezentovatelné manifestem) pak seskupíme do nových Manifestů.

Tak zajistíme, že:

• bude dodrženo pořadí informací při prezentaci (Mirador nepřeskupí manifesty a kolekce),
• ve stromečku kolekcí nakonec vždy bude existovat kolekce, která obsahuje pouze Manifesty a obsah jednotlivých manifestů bude uživateli zobrazen pohodlně.

Zobrazení pak bude přirozené, bude respektovat strukturu Kolekcí a vyhoví jak požadavkům IIIF, tak schopnostem aktuálních čteček (ačkoliv zde zatím poněkud kompromisně).

Při generování manifestů se budeme snažit využít jak annotation s motivation commenting a infromacemi strukturovanými v HTML, aby informaci zobrazil Mirador, ale budeme také korektně využívat aparát se zatím nepodporovanými druhy annotation a odkazování se na external web resources.

Budeme tak poskytovat čisté strojově zpracovatelné informace v souladu s IIIF navzdory tomu, že je čtečka aktuálně nezobrazí a redundantně budeme zobrazovat jejich zjednodušenou formu, aby tyto informace pokud možno zobrazily i aktuální čtečky (byť v kompromisní podobě). Taková redundance není na škodu – nejde o primární metadata, ale o výměnný formát.

Implementace

Zvolené řešení je implementováno v Manuscriptoriu verze 4, good practices při používání implementovaných jsou odkázány v sekci dokumentace o IIIF v Manuscriptoriu a jsou k dispozici i návody pro vytvoření osobního obsahu obecně.