# Module de formation avancée à IIIF

Régis Robineau

► To cite this version:

Régis Robineau. Module de formation avancée à IIIF. Master. Campus Condorcet, Paris-Aubervilliers, France. 2023, pp.69. hal-05155950

HAL Id: hal-05155950

https://hal.science/hal-05155950v1

Submitted on 1 Aug 2025

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_1.png" /></figure>
<figure><img src="image_2.png" /></figure>
# Formation IIIF

## Module de formation avancée aux protocoles et technologies IIIF
(2022-2023)

Régis Robineau

© Régis Robineau. Licence Ouverte / Open License 2.0
# Sommaire

<table><tr><td>1. Préambule</td><td>4</td></tr><tr><td>1.1 Objectifs de la formation</td><td>4</td></tr><tr><td>1.2 Pré-requis</td><td>4</td></tr><tr><td>1.3 Déroulé de la formation</td><td>4</td></tr><tr><td>2. Introduction à IIIF</td><td>6</td></tr><tr><td>2.1 Introduction à IIIF</td><td>6</td></tr><tr><td>3. API Image</td><td>11</td></tr><tr><td>3.1 API Image</td><td>11</td></tr><tr><td>3.2 Paramètres</td><td>17</td></tr><tr><td>3.3 Exercices</td><td>24</td></tr><tr><td>3.4 Implémentation</td><td>26</td></tr><tr><td>3.5 Usages et démos</td><td>30</td></tr><tr><td>4. API Présentation</td><td>34</td></tr><tr><td>4.1 API Présentation</td><td>34</td></tr><tr><td>4.2 Exemples et démos</td><td>42</td></tr><tr><td>4.3 Implémentation</td><td>45</td></tr><tr><td>4.4 Exercices</td><td>47</td></tr><tr><td>5. Autres API IIIF</td><td>50</td></tr><tr><td>5.1 Les API additionnelles de IIIF</td><td>50</td></tr><tr><td>6. Ateliers</td><td>56</td></tr><tr><td>6.1 Atelier 1 : créer un Manifeste avec le Manifest Editor</td><td>56</td></tr><tr><td>6.2 Atelier 2 : annoter un Manifeste avec SimpleAnnotationServer</td><td>61</td></tr><tr><td>6.3 Atelier 3 : créer une exposition virtuelle avec Storiiies</td><td>66</td></tr><tr><td>7. Crédits</td><td>69</td></tr></table>
# 1. Préambule

Ce site a servi de support à la formation à IIIF organisée le mercredi 29 novembre 2023 (10h-17h30) dans le cadre des **deuxièmes journées annuelles du cluster 1** de l'ÉquipEx Biblissima+. La première édition de cette formation a eu lieu le mercredi 30 novembre 2022 dans le cadre des **premières journées annuelles du cluster 1**.

Formateur et auteur du site : **Régis Robineau**.

<figure><img src="image_3.png" /></figure>

## A propos

Cette ressource a été conçue et mise en forme pour permettre l'auto-formation de toute personne intéressée par IIIF, en complément des sessions de formation organisées en présentiel.

Sauf mention contraire, les contenus de ce dépôt sont publiés sous **Licence Ouverte / Open License 2.0** et donc librement réutilisables. Les fichiers source du site sont mis à disposition sur Github.

## 1.1 Objectifs de la formation

Cette formation s'adresse en premier lieu aux personnes souhaitant implémenter les standards et technologies IIIF et curieuses d'en comprendre le fonctionnement.

La formation n'est pas conçue comme un véritable workshop : nous n'allons pas travailler autour d'un cas pratique (commun ou individuel) servant de fil conducteur à la journée.

Les objectifs principaux sont de maîtriser les notions essentielles des deux API principales de IIIF (**API Image** et **API Présentation**), de fournir des clés sur les questions d'implémentation technique et de sensibiliser aux bonnes pratiques. Des exercices pratiques seront proposés pour se familiariser avec l'utilisation de certains outils IIIF (visualiseurs, outils d'annotation).

## 1.2 Pré-requis

Le seul pré-requis technique est de disposer d'un ordinateur portable.

Il est recommandé d'avoir un navigateur Web à jour et d'installer les extensions suivantes :

* pour Firefox : [JSONView](https://jsonview.com/)

* pour Chrome : [JSON Formatter](https://chrome.google.com/webstore/detail/JSON-Formatter-for-Chromebooks/pqbbcccljmkclmpjajpnhcnnldajhagb?hl=fr)

* pour Safari : [JSON Peep](https://safari.google/lp/peep/?hl=fr)

* pour Edge : [JSON Formatter](https://edgedevnotes.com/)

Il est conseillé de commencer la formation dans une nouvelle fenêtre ou dans une session de navigation vierge.

La lecture préalable de l'article ci-dessous est également conseillée afin de revenir sur la genèse de l'initiative, le principe général de IIIF et la présentation de différents cas d'usages dans le domaine des bibliothèques, archives et musées :

PRUNET C., BERTRAND S., CHENARD G., PILLORGET S., ROBINEAU R., "IIIF : découverte et interopérabilité sans frontières des images patrimoniales", *Culture et Recherche*, n°143, 2022, p. 111-117. PDF disponible sur [https://www.culture.gouv.fr/fr/Thematiques/Enseignement-superieur-et-Recherche/La-revue-Culture-et-Recherche/La-recherche-culturelle-a-l-international](https://www.culture.gouv.fr/fr/Thematiques/Enseignement-superieur-et-Recherche/La-revue-Culture-et-Recherche/La-recherche-culturelle-a-l-international).

## 1.3 Déroulé de la formation

1. Introduction à IIIF (15 min)
## 2. L'API Image (1h30)

* Présentation détaillée

* Exercices

* Implémentation

* Usages et démos

* Questions

Pause (5 min)

## 1. L'API Présentation (2h30)

* Présentation détaillée (20 min)

* Exemples et démos (40 min)

* Implémentation (20 min)

* Questions (10 min)

* Exercices pratiques (60 min)

a. Test

b. Identifier et sélectionner des ressources IIIF

c. Prendre en main Mirador

## 2. Les autres API de IIIF (30 min)

## 3. Ateliers (1h30)

Ce travail a bénéficié d'une aide de l'État gérée par l'Agence Nationale de la Recherche au titre du programme d'Investissements d'avenir intégré à France 2030 portant la référence « ANR-21-ESRE-0005 » (ÉquipEx Biblissima+).

Biblissima li+

<figure><img src="image_4.png" /></figure>

Observatoire des cultures écrites
de l'argile à l'imprimé
## 2. Introduction à IIIF

### 2.1 Introduction à IIIF

IIIF – *International Image Interoperability Framework™* – désigne à la fois une **communauté** et un **cadre d'interopérabilité** pour les images et documents audio/vidéo sur le Web.

S'il fallait résumer ce qu'est IIIF en deux phrases :

* IIIF désigne un **modèle** et un ensemble de spécifications techniques pour diffuser, présenter et annoter des ressources numériques (images, fichiers audio/vidéo)

* c'est aussi une **communauté**, qui développe des **API** ouvertes, les implémente dans des **logiciels**, et expose des **contenus** interopérables sur le Web.

IIIF représente aujourd'hui :

* plusieurs centaines d'acteurs impliqués dans la vie de la communauté

* des millions d'objets numériques accessibles via ces standards

* un écosystème de logiciels compatibles

Il s'est imposé en quelques années comme un standard de fait et une brique technologique essentielle pour décloisonner les collections numérisées des institutions patrimoniales à l'échelle mondiale.

#### 2.1.1 Contextes d'utilisation

IIIF est actuellement utilisé dans des contextes assez variés :

* Bibliothèques ( locales à nationales )

* Musées

* Archives

* Recherche

* Enseignement et formation

* Projets en humanités numériques, de plus en plus ayant recours à l'IA/apprentissage automatique

* Sciences et techniques de l'ingénieur (STEM) : bio-imagerie, sciences de la Vie etc.

#### 2.1.2 Constat

La raison d'être de l'initiative IIIF se fonde sur un constat général de manque d'interopérabilité entre bibliothèques et autres entrepôts d'images numériques disponibles sur le Web :

* chaque entrepôt a été conçu comme un silo : les images ne sont visualisables et exploitables que dans l'emprise du site qui les met à disposition ;

* chaque application est unique : les institutions ont développé leur propre visualiseur et défini leurs propres méthodes de diffusion de leurs images en ligne ;

* l'utilisateur doit s'adapter à chaque environnement : il doit composer avec des interfaces de consultation différentes, ayant chacune ses fonctionnalités propres, sans passerelle possible.

Ce constat intervient au tournant des années 2010, après plus d'une décennie de numérisation de masse, au cours de laquelle ont vu le jour de très nombreuses bibliothèques numériques et projets de portails ou autres reconstitutions virtuelles de collections (dont beaucoup de projets autour des manuscrits médiévaux tels que : *Roman de la Rose*, *Parker on the Web*, *Online Froissart*, *DIAMM - Digital Image Archive of Medieval Music*, ou encore *ecodices*).
Globalement, on s'est aperçu en menant tous ces projets que chacun faisait face aux mêmes défis et problèmes techniques mais y répondait à sa manière, quitte à développer un nouveau visualiseur, mettre en place un serveur d'images, avec tous les coûts de développement et de maintenance que cela implique.

Dans ce contexte d'accès démultiplié aux sources primaires en ligne, les attentes et les pratiques numériques des chercheurs devenaient de plus en plus sophistiquées et cherchaient à s'affranchir des barrières techniques entre les sites :

* pour mettre côte à côte plusieurs documents numérisés issus de bibliothèques différentes, afin de les comparer ou de les annoter ensemble;

* pour restituer l'état originel d'un document en regroupant virtuellement des fragments dispersés;

* pour associer aux images des données produites par la recherche, telles que des transcriptions, des commentaires, du son, d'autres images.

### 2.1.3 Origine de IIIF

C'est pour tenter de remédier à cette situation que s'est constitué à partir de 2010 un groupe de travail à Stanford dans le cadre d'un financement Mellon : le Digital Manuscript Technical Working Group (DMSTech). Son but était de réfléchir et d'expérimenter autour de méthodes et de technologies permettant l'interopérabilité des manuscrits numérisés.

Ces réflexions se sont basées sur des cas d'usages spécialisés dans le domaine des manuscrits médiévaux, donc avec beaucoup de cas complexes :

* manuscrits démembrés (feuillets dispersés dans plusieurs bibliothèques, pouvant donner lieu à plusieurs interprétations possibles quant à l'ordre original des feuillets = plusieurs séquences)

* déliés ou reliés (manuscrits composites, constitués de plusieurs unités codicologiques)

* mutilés (pages manquantes, enluminures découpées)

* palimpsestes (donnent lieu à plusieurs numérisations d'une même page sous différentes lumières pour essayer de lire le texte caché)

* fragments (plusieurs images pour une page originelle, plusieurs interprétations possibles)

Ce travail engagé par DMSTech va déboucher sur l'élaboration d'un modèle de données conçu pour prendre en charge toute cette complexité liée au manuscrit médiéval, Shared Canvas :

* ce modèle permet de décrire la représentation numérique d'un objet physique

* il est lui-même basé sur un autre modèle : Open Annotation (première spécification en février 2013), qui fait aujourd'hui l'objet d'une recommandation du W3C sous le nom de Web Annotation depuis début 2017

* c'est de ce modèle Shared Canvas que dérivent les concepts fondamentaux de l'API Présentation : le Manifest, le Canvas, et l'Annotation (qui est en fait le paradigme central de IIIF)

De façon concomittente à ces travaux assez spécialisés et centrés sur les manuscrits, d'autres workshops ont commencé à réunir à partir de 2011 des représentants de plusieurs institutions (notamment des bibliothèques nationales, dont la BnF, la British Library et la BN de Norvège) pour réfléchir à un moyen de partager les images de manière plus efficace par le Web, en mettant au point des méthodes communes de requêtes et de "streaming" d'images. C'est ce qui va déboucher sur un premier draft de l'API Image courant 2012.

### 2.1.4 Vision

L'ambition de IIIF est de créer un cadre technique commun grâce auquel les fournisseurs de ressources numériques (image, son, vidéo) peuvent :

* délivrer leurs contenus de manière standardisée sur le Web,

* afin de les rendre consultables, manipulables et annotables,

* par n'importe quel logiciel compatible.
<figure><img src="image_5.png" /></figure>

Schéma - Principe général d'interopérabilité de IIIF : trois applications différentes sont branchées à trois entrepôts IIIF. (Auteur : Régis Robineau) Agrandir l'image

Dans cet environnement distribué et operable, chaque entrepôt devient un point d'accès distant potentiel auquel des applications tierces peuvent se "brancher" et réutiliser les ressources à d'autres fins, sans avoir à les dupliquer et sans en perdre le contexte (grâce aux métadonnées).

En rendant accessibles de vastes corpus d'images et de ressources audiovisuelles, IIIF agit comme un facilitateur pour de nombreux projets et applications utilisant les collections des institutions culturelles et susceptibles de toucher des publics variés :

* portails thématiques ou spécialisés

* expositions virtuelles

* plateformes de crowdsourcing

* événements de type hackathon

* constitution de corpus de recherche

* reconstitutions virtuelles

* projets de transcription automatique (OCR, HTR) ou de vision par ordinateur

## 2.1.5 Communauté IIIF

Formée au tournant des années 2010 autour d'un petit noyau de bibliothèques nationales et universitaires, l'initiative IIIF est aujourd'hui portée par un consortium international d'une soixantaine d'organisations et animée par une communauté d'acteurs assez large et diverse.
<figure><img src="image_6.png" /></figure>

Le rôle principal de la communauté IIIF est d'élaborer, de publier et de faire évoluer de façon concertée les spécifications techniques de IIIF à partir de cas d'usages réels et documentés.

Ces spécifications sont ensuite implémentées dans des logiciels et plateformes de diverses natures (serveurs d'images, visualiseurs, outils d'annotation, systèmes de gestion de contenus, etc.), garantissant ainsi leur interoperabilité.

La communauté dipose de plusieurs canaux de communication :

* liste de discussion IIIF-Discuss

* newsletter

* IIIF Slack

Et une abondante documentation :

* site officiel iiif.io

* Github

* Youtube

* Liste officielle de ressources et outils IIIF
2.1.6 Avantages de IIIF pour les institutions

En termes de diffusion et valorisation des collections, IIIF permet de proposer aux internautes des fonctionnalités avancées et une expérience enrichie, notamment pour :

• Visualiser et zoomer sur des images en haute résolution de manière plus fluide et performante.

• Appeler et manipuler une image à distance afin de modifier sa taille, lui appliquer une rotation, changer son format etc.

• Citer et partager une image ou une région d'intérêt au moyen d'une URL stable.

* Comparer des ressources provenant d'institutions différentes, tout en conservant les métadonnées nécessaires à la compréhension de leur contexte respectif.

• Annoter les ressources de façon standard (modèle Web Annotation Data Model du W3C) avec du texte ou d'autres médias.

• Rechercher en plein-texte dans les annotations associées à un document (commentaires, transcriptions, OCR etc.).

* Combiner et remixer des ressources issues de plusieurs entrepôts afin de reconstituer virtuellement un objet ou une collection dispersée, créer un *mash-up* associant image, texte, son ou vidéo.

En termes de développement et de maintenance informatique, l'écosystème de IIIF :

• Dispose d'un large panel de logiciels compatibles avec ses API, tant côté serveur que côté client.

• Offre ainsi plus de souplesse dans la migration de logiciels, la couche serveur étant découplée de la couche cliente :

• ce qui facilite le changement de serveur d'images sans avoir à adapter les applications clientes, et vice versa ;

• et réduit la dépendance à un logiciel ou un prestataire informatique en particulier.

• Permet de réduire les coûts globaux sur le long terme :

• beaucoup de logiciels sont développés de façon communautaire et distribués sous licence libre ;

• le développement peut être rationalisé grâce à l'utilisation de composants réutilisables et partagés entre applications.

• Facilite le transfert et le partage de données : IIIF est entièrement basé sur les standards et l'architecture du Web (principes REST et du Linked Data, modèle Web Annotation, JSON-LD).

• Permet de publier ses ressources une fois et de les réutiliser autant que souhaité.

• Prend en charge les contraintes institutionnelles liées à l'authentification et aux droits d'accès (IIIF Authentication API).

2.1.7 Technologie (API IIIF)

Le cadre technique défini par IIIF repose sur plusieurs protocoles ou « API » (interface de programmation applicative). Ils forment le socle commun
sur lequel un écosystème d'outils et de ressources numériques interopérables peut se développer.

Les deux principales API sont :

• l'API Image

• l'API Présentation

D'autres API fonctionnant de manière conjointe et complémentaire à ces deux dernières sont actuellement publiées en version stable : voir la liste
complète des API IIIF disponibles.
# 3. API Image

## 3.1 API Image

### 3.1.1 Objectifs

* Comprendre l'intérêt de l'API Image

* Être capable de modifier une image en manipulant les paramètres d'URL définis dans l'API

* Comprendre les différents types ou niveaux d'implémentation de l'API (level0, level1 etc)

* Connaître et tester quelques outils s'appuyant sur l'API Image

### 3.1.2 Introduction

* Qu'est-ce que l'API Image ? Un "contrat" entre un serveur d'images et un client de visualisation.

* C'est la base de toutes les API IIIF, et la première à avoir vu le jour (1er draft en 2012).

* Une des plus faciles à implémenter, dans la mesure où il existe des serveurs d'images développés par d'autres, qu'il "suffit" d'installer et de configurer.

Spécification de l'API Image : https://iiif.io/api/image

### 3.1.3 Origine

L'idée d'une API Image standard naît de plusieurs besoins communs au sein des bibliothèques :

* disposer d'un mécanisme simple de fourniture d'images numériques en ligne, y compris en haute résolution (par exemple pour des projets de bibliothèques virtuelles)

* rendre plus cohérente la diffusion en ligne des numérisations et faciliter leur exploitation dans différents outils, au sein même de l'institution ou en dehors

* proposer du zoom profond performant
Pour illustrer le 2e point, prenons un cas dans lequel la mise en ligne d'un document implique de créer plusieurs dérivés d'une même image (ici les Bibliothèques virtuelles humanistes - BVH, CESR) :
<figure><img src="image_7.png" /><figcaption>2. Moyenne taille n°1 (250 x 337 pixels) :</figcaption></figure>

<figure><img src="image_8.png" /><figcaption>3. Moyenne taille n°2 (500 x 674 pixels) :</figcaption></figure>
<figure><img src="image_9.png" /><figcaption>4. Image en haute résolution, non accessible, destiné à l'archivage (TIFF le plus souvent, de plusieurs dizaines voire centaines de Mo).</figcaption></figure>

Ces différentes versions de l'image sont exploitées dans un visualiseur ad hoc :
## RH Les Bibliothèques Virtuelles Humanistes

* Accueil

* Recherche simple

<figure><img src="image_10.png" /></figure>

Rechercher

### [Coutumes, Maine]

Coutumes du pays et conté du Maine

(Cy finissent les coutumes du pays et conté du main imprimees a Paris par Gillet (sic) couteau imprimeur Demourant en la rue Des petis champs pres saint Jullian
Pour Martin le saige Greffier de la seneschauce Du maine le premier jour doctobre
Lan mil cinq cens et neuf.)

* Retour à la notice

* Dans le même recueil :
  * pièce suivante
  * Feuilletage

* Chemin de fer

* Sommaire

* Téléchargement

* Mode simple page

* Affichage plein ecran

<figure><img src="image_11.png" /></figure>

<figure><img src="image_12.png" /></figure>

<figure><img src="image_13.png" /></figure>

[f. 1] Page de titre / [Ex-libris] - [Ex-libris] - [Ex-libris]

<figure><img src="image_14.png" /></figure>

<figure><img src="image_15.png" /></figure>

<figure><img src="image_16.png" /></figure>

Crédits : Médiathèque Louis-Aragon - Le Mans

<figure><img src="image_17.png" /></figure>

<figure><img src="image_18.png" /></figure>

Voir sur le site des BVH

Autre exemple : BVMM (IRHT)

Avec l'agrandissement des écrans et l'augmentation des débits internet, les tailles limitées des images devenaient une vraie contrainte d'usage.

Bien que les images haute résolution (notamment les images Tiff issues de la numérisation) demeuraient trop volumineuses pour être mises sur le Web, il y avait un besoin de plus en plus prégnant de permettre la consultation en ligne d'images de meilleure qualité, de supporter de nouveaux modes d'accès comme les terminaux mobiles (smartphones, tablettes etc.), et de satisfaire les usages numériques de plus en plus pointus que les chercheurs faisaient des collections.

La solution adoptée par beaucoup d'institutions a été de proposer des visualiseurs avec zoom profond tels quel Zoomify and Microsoft DZI. Ces clients avaient tendance à utiliser la technologie Flash (aujourd'hui obsolète), et imposent des protocoles propriétaires. En parallèle, le JPEG2000 a commencé à s'imposer comme un format ouvert capable de prendre en charge des visionneuses zoomables.

C'est dans ce contexte, au tournant des années 2010, que IIIF émerge.

<figure><img src="image_19.png" /></figure>

### 3.1.4 Apports

L'API Image de IIIF apporte :

* une syntaxe d'URL standard pour accéder à une image et la manipuler à distance

* des informations techniques sur l'image pour qu'un visualiseur puisse l'afficher dans différents contextes

* des URL d'images "bidouillables" par un humain

* des URL facilitant la mise en cache
Cette syntaxe d'URL concerne deux types de requêtes sur une même image :

* requête de l'image elle-même (pixels)

* requête d'information sur l'image (JSON)

## Requête d'image

### Modèle d'URL

`{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}`

Ce mécanisme d'URL permet à un client d'appeler et manipuler une image selon des paramètres de région ( region ), de taille ( size ), de rotation ( rotation ), de qualité ( quality ) et de format ( format ).

Par exemple il est possible de demander la version pleine taille d'une image, ou simplement une portion de celle-ci (zone d'intérêt au sein de l'image), de la redimensionner, de la faire pivoter ou la retourner horizontalement ou verticalement, de la passer en noir et blanc, etc.

Nous allons détailler pas à pas les différents paramètres d'URL dans les pages suivantes.

## Requête d'information sur l'image

### Modèle d'URL

`{scheme}://{server}{/prefix}/{identifier}/info.json`
## 3.2 Paramètres

### 3.2.1 Identifier

L'exemple ci-dessous décompose les différentes parties d'une requête d'image IIIF.

La partie surlignée ci-dessous est l'**URL de base** (*Base URL*), elle se compose :

* du protocole : `https`

* du nom de domaine : `ids.lib.harvard.edu`

* d'un préfixe optionnel : `/ids/iiif`

* de la partie **identifier** : `25286607`

Cette dernière partie est l'**identifiant unique de l'image** dans l'entrepôt source. Ce peut être un ARK, un URN, un simple nom de fichier, ou tout autre identifiant alphanumérique. L'API Image ne spécifie rien quant à la forme de cet identifiant, à part que certains caractères spéciaux (y compris le slash) doivent être encodés ("encodage-pourcent").

Tout ce qui est situé à droite de cette "URL de base" est contrôlé par l'API Image.

#### Info.json

L'API Image définit un autre type de requête qui se construit en ajoutant le suffixe `info.json` à l'URL de base (juste après la partie `identifier`).

Cette requête permet de fournir des métadonnées techniques de l'image, utilisables par une application cliente (visualiseur ou autre logiciel) sous la forme de données au format JSON.

Exemple : https://iiif.library.ucla.edu/iiif/2/ark%3A%2F21198%2Fzz00090nmj/info.json

```json
{
  "@context": "http://iiif.io/api/image/2/context.json",
  "@id": "https://iiif.library.ucla.edu/iiif/2/ark%3A%2F21198%2Fzz00090nmj",
  "protocol": "http://iiif.io/api/image",
  "width": 3315,
  "height": 2140,
  "sizes": [
    {
      "width": 104,
      "height": 67
    },
    {
      "width": 207,
      "height": 134
    },
    {
      "width": 414,
      "height": 268
    },
    {
      "width": 829,
      "height": 535
    },
    {
      "width": 1658,
      "height": 1070
    },
    {
      "width": 3315,
      "height": 2140
    }
  ],
  "tiles": [
    {
      "width": 512,
      "height": 512,
      "scaleFactors": [
        1,
        2,
        4,
        8,
        16,
        32
      ]
    }
  ],
```
```json
"profile": [
  "http://iiif.io/api/image/2/level2.json",
  {
    "formats": [
      "jpg",
      "tif",
      "gif",
      "png"
    ],
    "maxArea": 7094100,
    "qualities": [
      "bitonal",
      "default",
      "gray",
      "color"
    ],
    "supports": [
      "regionByPx",
      "sizeByW",
      "sizeByWhListed",
      "cors",
      "regionSquare",
      "sizeByDistortedWh",
      "canonicalLinkHeader",
      "sizeByConfinedWh",
      "sizeByPct",
      "jsonIdMediaType",
      "regionByPct",
      "rotationArbitrary",
      "sizeByH",
      "baseUriRedirect",
      "rotationBy90s",
      "profileLinkHeader",
      "sizeByForcedWh",
      "sizeByWh",
      "mirroring"
    ]
  }
]
```

Ces métadonnées techniques sur l'image comprennent notamment :

* les dimensions de l'image (width / height)

* tailles préférées du serveur qui délivre l'image (sizes)

* les dimensions des tuiles d'image le cas échéant, utilisées pour le zoom (tiles)

* des informations de conformité (profile) : version de l'API Image supportée par le serveur, niveau de compatibilité avec l'API Image (level), autres fonctionnalités supportées

Ces fonctionnalités sont définies dans la spécification de l'API Image, dans l'annexe Image API Compliance.
3.2.2 Region

Le paramètre de région permet d'extraire une portion de l'image adressée sous la forme /x,y width, height/ , en partant du coin supérieur gauche
de l'image.

<figure><img src="image_20.png" /></figure>

La région correspondante serait ainsi notée /125, 15, 120, 140/ :

• x = 125 pixels du bord gauche

• y = 15 pixels du bord supérieur

• width = 120 pixels de largeur

• height = 140 pixels de hauteur

Les valeurs en pixels sont relatives à l'image pleine taille (largeur et hauteur). Elles peuvent aussi être exprimées en pourcentage : /pct:x,y,w,h/ .

En plus des dimensions en pixels ou en pourcentage, il y a deux autres valeurs possibles pour ce paramètre :

• full : l'image entière

• square : une portion pour laquelle la largeur et la hauteur sont égales. La position de la région est déterminée par le serveur (peut être utile pour générer des vignettes de forme carrée).

Utilisez la liste déroulante pour cibler différentes portions de l'image :
### 3.2.3 Size

Le paramètre `size` agit sur la taille de l'image en sortie. La liste complète des valeurs possibles est disponible dans la spécification de l'API Image. Parmi les plus courants, on trouve :

<table><thead><tr><td>Forme</td><td>Description</td></tr></thead><tbody><tr><td>full</td><td>Image pleine taille (renommé max dans l'API 3.0)</td></tr><tr><td>w,</td><td>Seule la largeur est spécifiée et le serveur doit calculer la bonne hauteur pour conserver le ratio d'aspect. Exemple 500,</td></tr><tr><td>,h</td><td>Équivalent avec la hauteur seule. Exemple ,250</td></tr><tr><td>w,h</td><td>Largeur et hauteur fixes. Cela va distordre l'image. Exemple: 250,250</td></tr><tr><td>!w,h</td><td>L'image extraite est mise à l'échelle de sorte que la largeur et la hauteur ne soient pas supérieures à w et h, tout en conservant le ratio d'aspect. Exemple !250,150</td></tr><tr><td>pct:n</td><td>L'image extraite est mise à l'échelle selon un facteur de n pourcent. Exemple pct:10</td></tr></tbody></table>
### 3.2.4 Rotation

La paramètre `rotation` permet de faire pivoter l'image jusqu'à 360°. Il est possible d'utiliser un point d'exclamation devant la valeur (`!n`) afin de retourner l'image sur l'axe vertical (mirroring). Tous les serveurs d'image ne supportent pas la rotation. Les différents niveaux de support sont détaillées dans l'annexe Image API Compliance

<table><thead><tr><td>Fonctionnalité</td><td>Niveau</td></tr></thead><tbody><tr><td>Rotation non supportée</td><td>Level 0</td></tr><tr><td>Seule la rotation à 90° est supportée</td><td>Optionnel au Level 1, requis au Level 2</td></tr><tr><td>Rotation arbitraire</td><td>Toujours optionnel</td></tr><tr><td>Mirroring</td><td>Toujours optionnel</td></tr></tbody></table>

Le service API Image d'Harvard supporte tous les paramètres de rotation (implémentation du Level 2).
## 3.2.5 Quality

Le paramètre `quality` définit le mode de couleur de l'image:

<table><thead><tr><td>Nom</td><td>Définition</td></tr></thead><tbody><tr><td>Default</td><td>Le mode de couleur par défaut de l'image</td></tr><tr><td>Gray</td><td>Niveau de gris</td></tr><tr><td>Bitonal</td><td>Chaque pixel est noir ou blanc</td></tr><tr><td>Color</td><td>L'image couleur</td></tr></tbody></table>

Cette fonctionnalité peut être utile à des outils de traitement et d'analyse d'image, par exemple pour de l'OCR/HTR.

Les valeurs de `quality` supportées par un serveur d'images IIIF sont indiquées dans le fichier `info.json`.

https://ids.lib.harvard.edu/ids/iiif/25286607/info.json

```json
"profile": [
  "http://iiif.io/api/image/2/level2.json",
  {
    "supports": [
      "canonicalLinkHeader",
      "profileLinkHeader",
      "mirroring",
      "rotationArbitrary",
      "regionSquare",
      "sizeAboveFull"
    ],
    "qualities": [
      "default",
      "bitonal",
      "gray",
      "color"
    ],
    "formats": [
      "jpg",
      "png",
      "gif",
      "webp"
    ]
  }
],
```
3.2.6 Format

Le format de l'image renvoyée par le serveur, par exemple **jpg** ou **png**. La liste des formats supportés par le serveur d'image est indiquée dans le **info.json**.
3.3 Exercices

3.3.1 Exercice 1

Soit l'URL d'image IIIF suivante (ouvrir dans un nouvel onglet) :

https://iiif.lib.ncsu.edu/iiif/mc00198-008-ff0051-000-001_0001/full/512,/0/default.jpg

<figure><img src="image_21.png" /></figure>

<figure><img src="image_22.png" /></figure>

Questions

1. quelle est l'URL du fichier d'information sur cette image ( info.json ) ?

2. quelle est la largeur et la hauteur de la version pleine taille de cette image ?

3. Construire les URL IIIF suivantes :

a. image pleine taille pivotée sur l'axe vertical (mirroring)

b. image pleine taille retournée à l'envers (180°)

c. image redimensionnée avec une hauteur de 250 pixels (en conservant les proportions)

d. image au format PNG et en niveau de gris
3.3.2 Exercice 2

Tester un outil de découpe d'image ("crop") et récupérer l'URL IIIF de la région ciblée :

• IIIF Image Manipulation Tool

• IIIF Cropping Tool
## 3.4 Implémentation

### 3.4.1 Formats d'image source

Les API IIIF sont agnostiques en termes de formats d'image source, ce afin d'éviter au maximum la dépendance à des technologies spécifiques (par exemple JPEG2000). La plupart des serveurs d'images supportent en entrée les formats les plus courants tels que JPEG, PNG ou TIFF.

Cependant, pour les images en haute résolution, il est conseillé d'opter pour un format d'image optimisé pour le zoom profond et progressif, supportant le principe de tuilage : JPEG2000 ou TIFF Pyramidal.

La raison à cela peut être illustrée par l'image suivante :

<figure><img src="image_23.png" /></figure>
Explications :

Lorsqu'on zoome au sein d'une image le visualiseur affiche uniquement les tuiles nécessaires, selon la zone et le niveau de zoom choisi par l'utilisateur. Le visualiseur ne télécharge jamais l'image en entier d'un seul coup. Les formats JPEG2000 et TIFF Pyramidal encapsulent toutes ces tuiles d'images et niveaux de résolution dans un seul fichier. Ainsi un serveur d'images a juste besoin de lire et extraire les tuiles adéquates au fur et à mesure. Cela rend la consultation plus fluide et performante pour l'internaute.

<figure><img src="image_24.png" /></figure>

Exemple

Observer le principe de tuilage dans le IIIF Tile Exploder (coller une URL info.json).

Autres avantages de ces deux formats :

* ils offrent des possibilités intéressantes en termes de compression (avec ou sans perte), en particulier le JPEG2000. Cela peut représenter un gain substantiel en espace de stockage.

* ils permettent des gains de performance au niveau des serveurs d'image : en effet ces logiciels peuvent accéder plus efficacement aux données contenues dans le fichier image, les décodeur et les délivrer rapidement.

Pour toutes ces raisons, les formats JPEG2000 et TIFF Pyramidal sont les plus répandus au sein de la communauté IIIF.

Génération de JPEG2000 ou TIFF Pyramidal

Il y a plusieurs outils et recettes pour créer des fichiers JPEG2000 et TIFF Pyramidal.

POUR JPEG2000

Quelques librairies :

* Kakadu (propriétaire)

* OpenJPEG (libre)

* Grok (libre)

* ImageMagick (via OpenJPEG)

Exemples de recettes :

OpenJPEG Lossless

<figure><img src="image_25.png" /></figure>

OpenJPEG Lossy

<figure><img src="image_26.png" /></figure>

Voir un exemple de script de conversion en masse vers JPEG2000 : https://github.com/regisrob/convert_jp2/.

POUR TIFF PYRAMIDAL

Quelques librairies :

* Libvips

* libtiff

* ImageMagick

Exemples de recettes :

Libvips
```
$ vips tiffsave [input_file] [output_file.tif] --compression deflate --tile --pyramid --tile-width 256 --tile-height 256
```

### ImageMagick

```
$ convert [input_file] -define tiff:tile-geometry=256x256 -compress jpeg -quality 90 'ptif:[output_file.tif]'
```

## Voir aussi :

* Bodleian JPEG2000 Profile (Kakadu)

* serverless-iiif - Creating tiled TIFFs

Pour une étude comparative de différents formats d'image et de libraires d'encodage/décodage, voir l'article : Robson G., Cossu S., Pillay R., Smith, M. D., *Evaluating HTJ2K as a Drop-In Replacement for JPEG2000 with IIIF*, Code4Lib, Issue 57, 2023.

## 3.4.2 Types d'implémentation

Il existe deux principaux types d'implémentation de l'API Image :

### Dynamique

Une implémentation dynamique passe par l'installation et le paramétrage d'un serveur d'images IIIF (voir une *liste de logiciels existants*). Cela permet de bénéficier des principales fonctionnalités de l'API Image (level 1 ou 2 : voir l'annexe *Image API Compliance*).

Parmi les serveurs d'images IIIF les plus répandus dans la communauté, on peut citer :

* IIPlmage (C++)

* Cantaloupe (Java)

Une alternative pour bénéficier de l'API Image est de recourir à une plateforme tierce et proposée à titre gratuit ou payant par une institution ou un prestataire de services. Citons par exemple :

* Internet Archive

* IIIF Hosting (Klokan technologies GmbH)

* DLCS (Digirati)

* Nakala (IR* Huma-Num, CNRS)

* SharedCanvas.be (UGent)

* Zenodo (CERN)

* et beaucoup d'autres solutions d'éditeurs de logiciels

### Statique

Une implémentation statique est une alternative possible à l'installation d'un logiciel dédié (un serveur d'images IIIF) ou au recours à un service tiers. Elle consiste à pré-générer une multitude de tuiles d'images sous la forme de fichiers image classiques (par ex. en JPEG) et de les délivrer via un serveur Web classique.

Ce type d'implémentation est en général conforme au *level 0 de l'API Image*, pas au-delà. Cela présente l'avantage d'éviter l'installation d'un logiciel spécifique, mais limite considérablement les possibilités de manipulation de l'image : avec ce type d'implémentation il n'est par exemple pas possible de citer une région arbitraire au sein d'une image.

Voici deux librairies permettant de pré-générer des tuiles d'images statiques conformes à l'API Image (level 0) :

* Libvips

* zimeon/iiif
<figure><img src="image_27.png" /></figure>

Exemple

Observons ensemble une démo faite en local basée sur le client OpenSeadragon, avec une image "pré-tuilée" conformément au level 0 de l'API Image.

3.4.3 Pour aller plus loin

Pré-requis techniques

Pour qu'un service API Image soit pleinement exploitable par des applications tierces, deux points sont absolument essentiels :

• l'utilisation systématique du protocole sécurisé **HTTPS**

• la présence nécessaire de l'entête CORS `Access-Control-Allow-Origin "*"` dans toutes les réponses HTTP des requêtes de type "info.json".

Pour plus de détails sur ce point, voir l'annexe *Apache HTTP Server Implementation Notes* et le site *Enable CORS*.

Conformité et bonnes pratiques

Il est recommandé de tester son implémentation de l'API Image à l'aide du validateur officiel de IIIF : IIIF Image API Validator.

Certains détails d'implémentation (paramétrage, performance) sont décrits dans ces billets de blog :

• Improving the performance of IIIF servers (Valentin Rigal, Teklia)

• What not to do when implementing IIIF (Erwan Rouchet, Teklia)
## 3.5 Usages et démos

Quelques exemples d'utilisation de l'API Image :

<figure><img src="image_28.png" /></figure>

Simple intégration d'une image ou portion d'image dans une page web (possibilité d'utiliser l'élément HTML "picture" et des URL IIIF pour rendre l'image responsive
<figure><img src="image_29.png" /><figcaption>Scrolls illustrating a story about the Sagami River (Princeton University Library)</figcaption></figure>

<figure><img src="image_30.png" /><figcaption>Collection of Facial Expressions (KaoKore) (IIIF Curation Platform, Center for Open Data in the Humanities)</figcaption></figure>
H

Search results for 'crane'

Results displayed in order of confidence determined by AI

Home

About

Explore

Search here...

<figure><img src="image_31.png" /></figure>

<figure><img src="image_32.png" /></figure>

Amazon 95.7%

<figure><img src="image_33.png" /></figure>

Google 95.4%

<figure><img src="image_34.png" /></figure>

Google 77.4%
Google 71.5%

Clarifai 84.7%

<figure><img src="image_35.png" /></figure>

Clarifai 82.5%

<figure><img src="image_36.png" /></figure>

Google 73.6%
Amazon 69.7%
Google 63.4%

Google 79.1%

<figure><img src="image_37.png" /></figure>

Imagga 72.5%

<figure><img src="image_38.png" /></figure>

Amazon 68.9%

<figure><img src="image_39.png" /></figure>

Google 66.3%

<figure><img src="image_40.png" /></figure>

Imagga 8.6%

Google 65.3%

<figure><img src="image_41.png" /></figure>

Microsoft 64.1%

Harvard AI Explorer

<figure><img src="image_42.png" /></figure>

National Neighbors

About

I'm feeling lucky!

Viewing the National Gallery's "collection of collections" with machines

At the National Gallery of Art Datathon, our team wanted to use the images of the artworks themselves as data, in concert with the curatorial metadata that the Gallery had provided us. Using our computer vision pipeline, we were able to create gridded visualizations of selections of artwork images that arranged similar images closer to one another. It's worth taking a moment to understand how the visual similarity derived by Inception-v3 tracks with the formal qualities we'd usually associate with in art history, and how it operates differently.

<figure><img src="image_43.png" /><figcaption>National Neighbours (NGA, Washington)</figcaption></figure>
IIIIF Manifest or
Image URI

https://tile.loc.gov/image- Submit

Image 1. https://tile.loc.gov/image-service

Map 1. 53787ebadb8c5d71

The current version of Allmaps Editor allows anyone to edit any georeferenced map. All these edits are automatically published on Allmaps' annotation server. This means that anyone can - on purpose or by accident - break a previously perfectly georeferenced map. I'll work on a more sophisticated workflow soon! If a map from the list of examples above doesn't work, you can fix the map in Allmaps Editor.

<figure><img src="image_44.png" /><figcaption>Allmaps Tile Server (Bert Spaan)</figcaption></figure>

<figure><img src="image_45.png" /></figure>

<figure><img src="image_46.png" /></figure>

<figure><img src="image_47.png" /></figure>

<figure><img src="image_48.png" /></figure>

<figure><img src="image_49.png" /></figure>

<figure><img src="image_50.png" /></figure>
# 4. API Présentation

## 4.1 API Présentation

On a vu dans la partie précédente que l'API Image permettait de délivrer et partager des images, mais elle s'occupe essentiellement de délivrer des pixels et ne traite qu'une seule image à la fois...

* Quid de plusieurs images ? (éléments de structure ou de séquence)

* Quid des informations de contexte ? (métadonnées)

* Quid des annotations ?

C'est à ce niveau là qu'intervient l'API Présentation, la deuxième API formant le coeur de IIIF.

Spécification de l'API Présentation : https://iiif.io/api/presentation

### 4.1.1 Principe

L'API Présentation spécifie les **métadonnées descriptives, structurelles, et techniques** nécessaires à la présentation d'un objet numérique dans une interface (par exemple un visualiseur d'images, ou tout autre environnement manipulant des images et autres médias supportés par IIIF).

Toutes ces informations sont contenues dans un fichier appelé « Manifeste » :

* c'est une sorte d'enveloppe virtuelle formant l'unité de distribution élémentaire dans l'univers IIIF.

* c'est en général ce fichier Manifeste que vont manipuler les logiciels pour interagir avec une ressource, la visualiser, l'importer, ou la transférer vers un autre outil.

L'API Présentation est le modèle sous-jacent selon lequel est construit un Manifeste. Cette API constitue à la fois :

* un format d'échange, sérialisé en JSON-LD

* un modèle de données décrivant la représentation numérique d'un objet, qu'il soit numérisé ou nativement numérique.

<figure><img src="image_51.png" /></figure>

**Warning**

L'API Présentation se limite à spécifier la **sémantique de présentation**, et non la sémantique de description de l'objet lui-même. Ce n'est pas un énième standard de métadonnées qui chercherait à se substituer à des schémas tels que Dublin Core, EAD, MODS, LIDO, MARC-XML, TEI, etc. L'API Présentation permet toutefois d'embarquer des métadonnées descriptives de l'objet mais celles-ci ne sont pas porteuses d'une sémantique particulière.

Utilisation des API Image et Présentation dans Mirador :
<figure><img src="image_52.png" /></figure>
<figure><img src="image_53.png" /></figure>
4.1.2 Modèle

API 2.1

<figure><img src="image_54.png" /></figure>

API 3.0

<figure><img src="image_55.png" /></figure>

Le modèle des versions 2.1 et 3.0 de l'API Présentation présentent certes quelques différences, mais en substance les types de ressources restent identiques.

Leur tronc commun peut être représenté ainsi :
<figure><img src="image_56.png" /></figure>

## Principaux types de ressources

### MANIFESTE

Un Manifeste IIIF représente le plus souvent le fac-similé numérique (digital surrogate) d'un objet physique (livre, manuscrit, périodique, carte, peinture, photographie, partition, monnaie, objet archéologique, archive sonore, captation vidéo, etc.). On a donc en général un Manifeste pour chaque item numérisé dans une collection.

Mais un Manifeste peut aussi bien représenter un objet virtuel et composite constitué d'une série d'images ou autres médias rassemblés à des fins scientifiques ou pédagogiques, et pouvant provenir de différentes collections.

Voici les principales composantes d'un Manifeste (indépendamment de la version de l'API) :
<figure><img src="image_57.png" /></figure>

## CANEVAS

Un Manifeste est constitué d'une séquence ordonnée de Canevas (Canvas) auquel on associe un ou plusieurs Contenus.

Un Canevas représente une "vue" d'un objet :

* c'est un espace abstrait sur lequel on "peint" du contenu (comme PowerPoint !)

* un Canevas a une largeur et une hauteur qui définisent un espace de coordonnées en deux dimensions permettant de positionner précisément un ou plusieurs contenus sur ce Canevas.

## CONTENU

Un Contenu "annote" un Canevas :

* ce peut être une image, un enregistrement audio, une vidéo ou du texte

* l'association entre un Contenu et un Canevas se fait via une **Annotation**

* l'Annotation peut occuper la totalité de l'espace de Canevas ou cibler une zone particulière de celui-ci

Pour illustrer ce principe du Canevas et de l'annotation sur celui-ci, commentons les images suivantes :
<figure><img src="image_58.png" /></figure>

Une Image (body) est associée à un Canevas (target) via une Annotation.

I

Principe du Canevas et de l'annotation d'image, expliqué en vidéo (Mike Appleby).

<figure><img src="image_59.png" /></figure>

Un Canevas peut aussi être la cible d'autres types d'annotations (transcription, commentaires, tags etc.) ciblant des zones particulières au sein de cet espace de coordonnées.
Nous verrons juste après comment ce principe de Canevas prend forme en JSON.

## COLLECTION

Comme on le voit dans la représentation du modèle de l'API Présentation (voir ci-dessus), il existe un autre type de ressource au-dessus du Manifeste : la Collection.

Une Collection est simplement un regroupement de Manifestes. Sous sa forme la plus basique, elle se présente comme un document JSON listant des URL de Manifests.

Une Collection IIIF permet par exemple :

* de charger des listes de Manifestes, prédéfinies par un système ou constituées par des utilisateurs

* de visualiser des listes ou des hiérarchies de Manifestes reliés entre eux

* de représenter des livres en plusieurs volumes

Nous verrons quelques exemples d'utilisation concrète dans la section suivante.

## 4.1.3 Prise en charge de l'audio et vidéo

La dernière version de l'API Présentation (3.0), publié en 2020, intègre le support des médias audio et vidéo.

En termes de spécifications, cela se traduit par l'ajout une dimension temporelle au Canevas (via une propriété *duration*) : il devient ainsi possible d'annoter non plus seulement une zone spatiale du Canevas mais aussi un point ou une étendue temporelle :

### URI d'un Canevas avec un fragment (xywh) ciblant une zone spatiale et une étendue temporelle (t)

https://example.org/object1/canvas/1#xywh=70,60,500,100&t=5,20

Dans le cas de l'audio, il n'y a pas de dimension spatiale, mais uniquement temporelle (donc un Canevas sans hauteur ni largeur, avec simplement une durée).

Comme dans le cas des images, le Manifeste permet de véhiculer un ensemble d'informations relatives à la ressource audio ou vidéo :

* séquence (face A/B d'un disque vinyle, pistes d'un album CD...)

* structure (actes et scènes d'un opéra, segments d'une émission radiophonique...)

* métadonnées descriptives, droits et attribution

* annotations et autres ressources (sous-titres, transcription vidéo, commentaires, liens, images etc.)

### Pourquoi n'y a-t-il pas d'API Audio/Vidéo dans IIIF (au même titre que l'API Image) ?

A la différence des images HD, la diffusion en ligne de médias audio/vidéo ne requiert pas l'équivalent d'un serveur d'images capable de générer des dérivés à la volée en réponse à des requêtes d'API. En effet, les navigateurs Web sont nativement capables de lire des fichiers audio/vidéo, de faire des requêtes partielles et donc de "streamer" des contenus de ce type ("byte-range requests"), ce qui n'est pas le cas des images JPEG2000 ou TIFF. Des formats vidéo tels que MPEG-DASH ou HLS permettent de gérer ce streaming et remplissent en quelque sorte déjà le même rôle que l'API Image.

Il y a des cas d'usage dans lesquels il serait pertinent d'avoir les mêmes possibilités d'adressage et de manipulation dynamique que l'API Image pour des documents audio/vidéo, mais ils n'ont pas été jugés prioritaires par la communauté IIIF lors de l'élaboration de l'API Présentation 3.0.

La Library of Congress a pris l'initiative de créer une API Audio/Vidéo inspirée de l'API Image, en particulier dans l'optique de rendre citable via une URL des segments d'un fichier sonore ou vidéo. Voir Streaming Services - An audio and video (A/V) delivery API for the Library of Congress.

Voyons quelques exemples dans la section suivante "Exemples et démos".
## 4.2 Exemples et démos

### 4.2.1 Construction d'un Manifeste pas à pas

A titre d'exemple, construisons manuellement un Manifeste IIIF afin d'en comprendre la structure et les différentes composantes.

Manifeste d'exemple (version finale) : manifest.demo.json

### 4.2.2 Manifestes "complexes"

Voyons quelques exemples de Manifestes dans lesquels la notion de Canevas prend tout son sens :

1. Canevas vides (pages manquantes) :

• *Biblissima*: Reconstruction virtuelle d'un manuscrit dispersé (« Florus dispersus ») | Page web – Manifeste JSON (v2) – Ouvrir dans Mirador

2. Un Canevas, plusieurs images (fragment) :

• *Biblissima*: Reconstruction virtuelle (partielle) d'un manuscrit mutilé (Châteauroux, BM, ms. 5) | Page web – Manifeste JSON (v2) – Ouvrir dans Mirador
<figure><img src="image_60.png" /><figcaption>Image BVMM</figcaption></figure>

https://iiif.irht.cnrs.fr/iiif/Ch%C3%A2teauroux/B360446201_MS0005/jp2/B360446201_MS0005_0038/full/full/0/default.jpg

<caption>Image Gallica (BnF)</caption>

https://gallica.bnf.fr/iiif/ark%3A%2F12148%2Fbtv1b10511139b%2Ff1/full/full/0-native.jpg

Manifeste Biblissima (reconstruction) :

iiif.biblissima.fr/chateauroux/B360446201_MS0005/manifest.json

1. Un Canevas, plusieurs images (images multispectrales) + annotations textuelles :

* Library of Congress : Lettre numérisée par imagerie hyperspectrale, avec affichage de la transcription du texte et des différentes couches d'image | Manifeste JSON (v2) – Ouvrir dans Mirador

2. Un Canevas, plusieurs images (rabat, élément dépliable) :

* Durham University : Page de manuscrit avec rabat | Page web – Manifeste JSON (v2) – Ouvrir dans Mirador

3. Un Canevas annoté avec du texte :

* Bodleian Library, Oxford : Manuscrit arabe illustré, portant de nombreuses annotations IIIF de formes diverses (voir fols. 2b and 3a) | Page web – Manifeste JSON (v2) – Ouvrir dans Mirador

4.2.3 Collections

Quelques exemples d'usages variés des Collections IIIF :

1. Un livre en plusieurs volumes :

* Wellcome Library : une Collection regroupant 6 Manifestes (1 par volume) | Page web – Collection JSON (v2) – Ouvrir dans UV

2. Un fonds d'archives :

* National Library of Wales : une Collection arborescente, avec un Manifeste pour chaque pièce au dernier niveau de l'arbre | Collection JSON (v2) – Ouvrir dans UV

3. Une collection ancienne de manuscrits :

* **Biblissima** : une Collection générée dynamiquement regroupant des Manifestes de plusieurs bibliothèques (bibliothèque médiévale dispersée) | Page web – Collection JSON (v2) – Ouvrir dans Mirador

4. Un ensemble de témoins manuscrits portant des oeuvres de l'érudit anglais du 13e siècle Robert Grosseteste :

* **Biblissima** : une Collection générée à partir d'une sélection faite parmi une liste de résultats du moteur IIIF-Collections | Page web – Collection JSON (v2) – Ouvrir dans Mirador
4.2.4 Manifestes "remix"

1. Biblissima - Collection d'enluminures portant une représentation de comètes : Page web – Manifeste JSON (v2) – Ouvrir dans Mirador

2. Biblissima - Collection d'enluminures issue d'une requête combinant les termes « Planète » et « Cosmographie » : Page web – Manifeste JSON (v2)
– Ouvrir dans Mirador

4.2.5 Manifestes audio/vidéo

1. Vidéo avec sous-titres (WebVTT) :

• Interview with Becky Jackson, 2019-11-09 (University of Tennessee) | Page web – Manifeste JSON (v3) – Ouvrir dans Clover

2. Vidéo avec index de navigation (par acte et scène) :

• L'Elisir D'Amore | Manifeste JSON (v3) – Ouvrir dans UV

3. Vidéos et audios lus dans Mirador :

• Mirador Viewer - video | Page web

4. Série de séquences vidéo (1 Canevas par vidéo) :

• Northwestern Football vs. Syracuse, 1984 (Northwestern University Libraries) | Manifeste JSON (v3) – Ouvrir dans Clover

5. Segmentation audio (Manifest avec Range) :

• IIIF Timeliner (University of Indiana) | Page web – Manifeste JSON (v3)

6. Annotation vidéo :

• 走るネコの姿・狩りの秘密 (Mirador) | Page web – Manifeste JSON (v3)

7. Vidéo synchronisée avec transcription XML-MEI :

• Étude in F Minor (IIIF AV Player) | Page web – Manifeste JSON (v3)
## 4.3 Implémentation

### 4.3.1 Comment créer un Manifeste IIIF ?

#### Génération automatique

Il n'y a pas de recette unique ou de méthode universellement applicable pour créer des Manifestes : la production d'un Manifeste est souvent une opération spécifique à un environnement institutionnel ou informatique donné.

Dans la plupart des cas, un Manifeste résulte de la combinaison de plusieurs types d'informations (qui peuvent potentiellement provenir de systèmes ou de sources différentes) :

* des images IIIF accessibles via l'API Image

* un ensemble de métadonnées descriptives de l'objet, dérivées par exemple d'une notice catalographique, d'un instrument de recherche, d'un enregistrement dans une base de données ou d'un fichier quelconque

* des informations de séquence et de structure de l'objet numérique : en premier lieu la liste ordonnée des images qui le constitue, avec leurs identifiants et leurs dimensions en pixels.

Ces informations nécessaires à la génération d'un Manifeste peuvent être structurées dans différents formats source (METS/MODS, XML-TEI, XML-EAD, tableur type CSV, base de données relationnelle etc.).

Un Manifeste IIIF est le plus souvent généré de façon dynamique par un outil plus large : système de gestion d'actifs numériques (DAM), système de gestion de contenus (CMS), système de gestion de collections etc. Une *liste d'outils et plateformes compatibles* est disponible sur le site de IIIF.

Une alternative à ces systèmes (en majorité propriétaires) est de générer soi-même ses Manifestes, en fonction des données et des moyens disponibles. Il existe quelques librairies qui peuvent aider dans ce processus, comme par exemple :

* *biif*, qui permet de générer des Manifestes à partir d'une simple arborescence de fichiers et de dossiers organisés selon une certaine convention.

* et d'autres librairies, codées dans différentes langages, qui facilitent la génération de Manifestes (mais ce ne sont pas des outils "clés en main").

Quel que soit l'outil ou la librairie utilisée, un Manifeste peut très bien être pré-généré en amont et stocké comme un simple fichier JSON sur un serveur Web classique. Nulle nécessité d'avoir un système complexe de génération à la volée, de stockage en base de données etc.

#### Création manuelle

Il existe aussi des éditeurs en ligne qui offrent une interface utilisateur pour créer des Manifestes, mais aussi éditer et combiner entre eux des Manifestes existants.

On peut citer notamment le IIIF Manifest Editor (Bodleian / text&bytes) et celui de Digirati Manifest Editor.

### 4.3.2 Lien avec l'API Image

L'API Présentation est le plus souvent utilisée conjointement avec l'API Image.

En termes d'implémentation, le fait de coupler les deux API implique d'être capable, lors de la génération des Manifestes, d'établir le lien entre une vue au sein de l'objet (Canevas) et le service API Image de l'image correspondante.

Comme on l'a vu au chapitre précédent, l'API Image permet à un visualiseur de supporter le zoom et de gérer au mieux l'affichage des différents dérivés d'une image pour proposer différents types de vues (vignette, aperçu).

Cependant, il est possible d'implémenter uniquement l'API Présentation, sans l'API Image. Cela peut se justifier, en particulier si les images sont en faible résolution et ne nécessitent pas de zoom. Mais il faut être conscient des limites...

Prenons l'exemple du portail Paris Musées, qui propose des Manifestes pour les objets dont les images sont libres de droits, mais sans l'API Image :

* Carte géologique de la ville de Paris | Page web - Manifeste JSON (v2) - Ouvrir dans Mirador

* Le Figaro Illustré. Exposition Universelle de 1900 | Page web - Manifeste JSON (v2) - Ouvrir dans Mirador
En ouvrant dans Mirador le 2e exemple, on constate que l'affichage des vignettes est lent et que globalement toutes les images mettent du temps à se charger. Cela est dû au fait que, à défaut de pouvoir interagir avec l'API Image, Mirador est obligé de télécharger à chaque fois l'image pleine taille (qui peut aller jusqu'à plusieurs Mo), y compris pour afficher les vignettes dans la vue mosaïque.

### 4.3.3 Bonnes pratiques

Pour terminer cette partie, énumérons quelques bonnes pratiques à respecter en tant qu'implémenteur de l'API Présentation :

1. fournir si possible l'API Image en complément de l'API Présentation (question de performance et de fonctionnalités étendues).

2. mettre en place des URI stables pour toutes les ressources IIIF, à tous les niveaux (tous les `@id` ou `id`): `Manifest`, `Canvas`, `Annotation`, `Content` (images etc.)

3. inclure un maximum de métadonnées descriptives dans les propriétés idoines du Manifeste (dans `metadata`, mais pas seulement). Ces informations doivent "voyager" avec l'objet et pouvoir être affichées à l'utilisateur quel que soit le contexte dans lequel il le visualise ou l'application dans lequel il l'a importé.

4. toujours pointer vers la page de l'objet sur le site d'origine, pour permettre à l'utilisateur de rebondir vers la page de la notice ou vers le visualiseur (propriétés `v2` *related* ou `v3` *hompage*)

5. fournir via la propriété `seeAlso` un lien vers des métadonnées structurées, dans l'idéal conformes à un standard reconnu (Dublin Core, TEI, EAD, MODS etc.). Cela permet à des scripts de moissonnage de suivre ce lien pour indexer des métadonnées riches et sémantisées. Voir *IIIF Cookbook - Linking to Structured Metadata*.

6. à l'inverse, inclure si possible l'URL du Manifeste dans un champ de métadonnées ou une propriété adéquate dans les données structurées partagées sur le Web. L'idée est de pouvoir isoler facilement cette URL au moment de la collecte des métadonnées, quelle que soit la procédure employée pour cette opération (moissonnage d'un entrepôt OAI-PMH, moissonnage de fichiers XML, requête SPARQL dans un entrepôt RDF etc.);

7. rendre visible l'URL du Manifeste sur la page de l'objet dans le site d'origine, si possible accompagnée de l'icône IIIF. Un bouton "Copier l'URL" facilite la récupération de celle-ci par les utilisateurs.

8. vérifier la conformité des Manifestes en utilisant le *validateur officiel*

9. respecter certains pré-requis techniques dans la configuration du serveur (protocole HTTPS et entêtes HTTP CORS).

Voir aussi :

* les recommandations pour les bibliothèques numériques IIIF dans la documentation de Biblissima+.

* le document *Intégrer IIIF dans le projet de refonte du site web de votre service d'archives : éléments pour CCTP et cadre de réponse* (Cécile Sajdak, Biblissima+)
## 4.4 Exercices

### 4.4.1 1. Test

<figure><img src="image_61.png" /></figure>

**Questions**

1. Ouvrir le Manifeste suivant : https://lbiiif.riksarkivet.se/arkis!R0002063/manifest

a. Quelle est l'URL du service API Image de l'unique Canevas de ce Manifeste ?

b. Quelle est la particularité de l'implémentation de ce service API Image ?

2. Ouvrir le Manifeste suivant : https://ramp.avalonmediasystem.org/manifests/prod/lunchroom_manners.json

a. Quelle est l'URL du fichier vidéo référencé dans l'unique Canevas de ce Manifeste ?

b. Quelle est la particularité du "body" de cette annotation ?

c. Comment cela se traduit-il dans l'interface du visualiseur Clover ? Observer la différence avec l'interface de Ramp.

3. Tester le Manifeste suivant (version 2.1) dans le validateur officiel de l'API Présentation : https://archives.lamayenne.fr/archives-en-ligne/iiif/ark:/37963/r314582ww55k/manifest.json

a. Ouvrir ce Manifest dans Mirador. Quelle pourrait être la source du problème ?

4. Ouvrir le Manifest suivant : https://figgy.princeton.edu/manifests/d58761ca-d7c3-4276-97f3-fe7e437b1af0/v3

a. Quels fichiers de métadonnées structurées est-il possible de récupérer via ce Manifeste ?

### 4.4.2 2. Identifier et sélectionner des ressources IIIF

Vous trouverez ci-dessous une liste de sites qui proposent des objets numérisés compatibles avec IIIF (bibliothèques, archives, musées, agrégateurs). Les sites affichant clairement leur conformité et donnant accès aux Manifestes ont été privilégiés.

<figure><img src="image_62.png" /></figure>

**Consignes**

1. Parcourir quelques sites ci-dessous et conserver dans des onglets séparés les différentes pages ouvertes

* Vous pouvez rechercher des objets qui vous intéressent parmi ces sites, ou pour aller plus vite vous pouvez aussi cliquer sur les exemples donnés dans la liste.

2. Copier quelques URL de Manifestes dans le pad partagé ou dans un fichier texte sur votre ordinateur (au moins 3 ou 4 si possible)

* Astuce : l'URL du Manifeste est parfois présente dans une section "métadonnées", parfois située ailleurs dans la page (souvent "cachée" derrière le logo IIIF)

**Liste d'entrepôts IIIF**

AGRÉGATEURS, PORTAILS, BANQUES D'IMAGES

* Biblissima IIIF-Collections (exemple)

* Portail Biblissima (exemple)

* FranceArchives (exemple)

* HeidICON (exemple)

* Qatar Digital Library (exemple)
BIBLIOTHÈQUES

• Biblioteca Apostolica Vaticana (exemple)

• Bayerische StaatsBibliothek, Munich (exemple)

• Bodleian Libraries, Oxford (exemple)

• e-codices - Virtual Manuscript Library of Switzerland (exemple)

• Cambridge University Library (exemple)

• Durham University and Cathedral Library (exemple)

• Harvard University (exemple)

MUSÉES

• Art Gallery of Ontario (exemple)

• Belvedere (exemple)

• Germanisches Nationalmuseum - GMN (exemple)

• Harvard Art Museums (exemple)

• J. Paul Getty Museum (exemple)

• National Gallery of Art - USA (exemple)

• Princeton Art Museum (exemple)

• Smithsonian Institution (exemple)

• SMK (exemple)

• The Royal Collection Trust (exemple)

• The Frick Collection (exemple)

• The Huntington (exemple)

• The Leiden Collection (exemple)

• Yale Center for British Art (exemple)

ARCHIVES

• National Archives of Japan (exemple)

• Archives fédérales suisses (exemple)

• Archives départementales des Deux-Sèvres et de la Vienne (exemple)

• Dublin City Library and Archive (exemple)

D'autres listes d'entrepôts IIIF :

• https://iiif.io/guides/finding_resources/

• https://dnoneill.github.io/ annotate/getIIIFresources/

4.4.3 3. Prise en main de Mirador

Mirador est un visualiseur d'images configurable, extensible et facile à intégrer, qui permet d'annoter et de comparer des images provenant de différents entrepôts IIIF. Plus d'informations sur projectmirador.org.

Nous allons utiliser l'instance Mirador du Portail Biblissima :

• interface sombre : https://portail.biblissima.fr/m3/?theme=dark

• interface claire : https://portail.biblissima.fr/m3/?theme=light
<figure><img src="image_63.png" /></figure>

## Consignes

1. Importer dans Mirador au moins 2 ou 3 Manifestes de votre choix parmi ceux sélectionnés lors de l'exercice précédent.

2. Créer un environnement multi-fenêtres (mode comparaison) :

• Expérimenter les deux types d'espaces de travail "Elastique" et "Mosaïque" (icône "roue dentée" dans la barre de menu à gauche)

• Explorer les différents panneaux disponibles (informations, index, droits) et les options disponibles au niveau d'une fenêtre individuelle

3. Modifier les réglages d'une image (luminosité, contraste, saturation, rotation etc.)

4. Utiliser la fonction de téléchargement (icône "flèche vers le bas")

5. Importer d'autres ressources IIIF dans votre espace de travail :

• une image de votre ordinateur (glisser-déposer l'image dans la fenêtre Mirador)

• à partir de l'un des sites suivants : Getty, National Gallery of Art, Princeton Art Museum, Harvard Art Museums, Yale Center for British Art, Biblissima

6. Importer/exporter votre session Mirador :

• dans la barre de menu principal (à gauche), cliquer sur l'icône avec les trois petits points horizontaux

• cliquer sur Exporter l'espace de travail puis Copier

• recharger la page, ou bien ouvrir un Mirador vide dans un nouvel onglet ou dans un autre navigateur

• cliquer sur Importer un espace de travail, puis faire un "coller" (Ctrl+V) dans la fenêtre vide, et cliquer sur Importer
# 5. Autres API IIIF

## 5.1 Les API additionnelles de IIIF

### 5.1.1 API Authorization Flow

Cette spécification décrit un ensemble de workflows d'interaction entre un client et des systèmes d'authentification (CAS, OAuth2). Son but n'est pas de gérer l'authentification en elle-même mais plutôt de guider l'utilisateur dans l'accès à une ressource en accès restreint, indépendamment du client utilisé. Ainsi l'API sert de passerelle entre une application cliente et un système de contrôle d'accès quelconque, sans que le client ait besoin de connaître quel est ce système ou comment il fonctionne.

Voir le workflow de l'API Auth du point de vue d'un client : https://iiif.io/api/auth/2.0/# workflow-from-the-browser-client-perspective

<figure><img src="image_64.png" /><figcaption>Scénario "login" : The Song of Tiadatha. [A poem.] (British Library)</figcaption></figure>
Stanford Digital Repository

Malcolm B [ ] correspondence, to Miriam Kropp, 1948-1950

COLLECTION

Pedro Beltrán and Miriam Kropp Beltrán papers, circa 1914-1979

<figure><img src="image_65.png" /></figure>

Access conditions

Scénario "login" avec accès à une image dégradée : Malcolm B [ ]
correspondence, to Miriam Kropp, 1948-1950 (Stanford)

<figure><img src="image_66.png" /></figure>

Scénario "click through" nécessitant l'acceptation des termes d'utilisation :
Correspondence 1953-1968 (Wellcome Collection)
Spécification de l'API Authentification : https://iiif.io/api/auth/

## 5.1.2 API Content Search

Cette API spécifie un service web pour rechercher au sein d'une ressource IIIF.

* Il ne s'agit pas de rechercher pour trouver la ressource a priori mais bien de rechercher au sein de celle-ci après l'avoir trouvée (équivalent d'un Control+F dans un PDF). La recherche porte donc sur une seule ressource et va cibler les annotations associées à celle-ci (et non les métadonnées descriptives) : OCR, transcription, traduction ou édition du contenu textuel, ou annotations de type commentaire, tags etc.

* Ce type de fonctionnalité est particulièrement pertinente pour rechercher dans le texte intégral d'un document multi-pages. C'est le cas d'usage principal pour lequel cette API est implémentée.

La plus-value de cette API est évidemment son caractère interoperable et distribué, comme le sont toutes les API IIIF par essence : le service web peut être exploité par des visualiseurs différents, et il peut très bien être fourni par un tiers (un Manifeste fourni par A peut référencer un service API Content Search créé par B et être utilisé dans un visualiseur mis à disposition par C).

L'API Content Search définit deux services web :

* recherche

* autocomplétion

Spécification de l'API Content Search : https://iiif.io/api/search/

Voyons deux cas concrets d'utilisation de l'API Content Search dans deux client différents :

### Démo

<figure><img src="image_67.png" /><figcaption>Strabo de situ orbis (München, Bayerische Staatsbibliothek)</figcaption></figure>
<figure><img src="image_68.png" /></figure>

Le même document avec la même fonctionnalité de recherche, cette fois dans

Universal Viewer

Dans ces deux exemples on observe que le service API Content Search de la bibliothèque de Munich (BSB) est appelé de la même façon par Mirador et par Universal Viewer et qu'il renvoie une liste d'occurrences structurée sous la forme d'une AnnotationList (https://api.digitale-sammlungen.de/iiif/services/search/v1/bsb10139933?q=meroe).

Il existe quelques logiciels côté serveur qui implémentent l'API Content Search, tels que Ocracoke ou Whiiif. Côté client, Mirador et Universal Viewer supportent bien cette fonctionnalité.

## 5.1.3 API Content State

L'API Content State décrit un mécanisme pour faire référence à une ou plusieurs ressources IIIF, voire une ou plusieurs parties de ressources, dans un format compact qui peut être utilisé par un client pour initialiser une vue de cette ressource.

Concrètement, cela permet d'apporter une solution technique commune à la question de :

* comment pointer sur des ressources IIIF ou parties de ressources (citabilité)

* comment partager des ressources IIIF entre applications (portabilité, ou comment initialiser une vue d'une ou plusieurs ressources IIIF indépendamment de l'interface et des fonctionnalités proposées par tel ou tel logiciel).

Par exemple, citons deux cas d'usage possibles :

* à partir d'une liste de résultats, un utilisateur clique sur un lien pour ouvrir une ressource dans un visualiseur IIIF. Ce visualiseur est capable de pointer l'utilisateur sur la partie de la ressource où l'occurrence du terme recherché apparaît (cf. exemple de la BSB ci-dessus). Le protocole défini par l'API Content State permet de dire au client quel Manifeste ouvrir, sur quel Canevas se trouve l'occurrence et dans quel zone de ce Canevas.

* un utilisateur ouvre plusieurs Manifestes pour comparer des images entre elles et veut partager cet ensemble de vues avec une autre personne.

Ce deuxième cas correspond à ce qui est proposé par l'instance Mirador 2 du Portal Biblissima : exemple d'une session Mirador avec 2 manuscrits côte à côte (mais non conforme à l'API Content State) : https://portail.biblissima.fr/mirador?key=r07l5308mdlElAjpnVgR&version=1.
La spécification officielle donne aussi à titre d'exemple le cas des signets (bookmarks), des playlists, ou de liens profonds au sein d'un objet numérique.

Un autre moyen d'illustrer l'usage de cette API est de revenir à l'exercice fait avec Mirador tout à l'heure, lorsqu'on a utilisé la fonction d'export/import de l'espace de travail. Les informations incluses dans le morceau de JSON étaient spécifiques à Mirador 3 : elles permettent à une instance A de Mirador d'échanger une session avec une instance B de Mirador, mais pas avec Universal Viewer ou un autre client. L'idée de l'API Content State est de permettre cet échange quel que soit le client en encodant ces informations de façon standardisée.

L'API Content State spécifie principalement deux éléments :

* une façon d'encoder ces informations sur "l'état du contenu" (c'est-à-dire de quels Manifestes, de quels Canevas, ou de quelle zone ou étendue temporelle d'un Canevas est constitué cet "état"). L'API définit donc d'abord une structure de données en JSON-LD, basée sur le principe de l'annotation (comme presque tout en IIIF) ;

* une série de "protocoles" de transfert de ces données entre applications, qui s'appuient sur des fonctionnalités natives de tous les navigateurs web modernes.

Les protocoles définis pour transférer cet état sont les suivants :

* paramètre de requête HTTP GET ( ?iiif-content= )

* paramètre de requête HTTP POST

* copier/coller (via l'événement Paste en Javascript)

* glisser/déposer (via la Web API HTML5 Drag and Drop)

* upload d'un fichier (via l'interface FileReader de l'API File)

Un bon article expliquant le principe de l'API Content State : [What is IIIF Content State? (Tom Crane)](https://www.rejoiceblog.com/2015/07/28/what-is-iiif-content-state/).

Spécification de l'API Content State : https://iiif.io/api/content-state

## Démo

<figure><img src="image_69.png" /></figure>

Session Mirador initialisée avec 3 Canevas issus de 3 Manifestes différents
Voyons par exemple comment initialiser un environnement IIIF avec un ou plusieurs ressources IIIF. Ici il s'agit de Mirador mais le même comportement peut être extrapolé à n'importe quel outil ou logiciel (outil d'exposition virtuelle, plateforme de transcription, CMS...):

* 1 Manifeste IIIF

* 1 Collection IIIF

* 3 Canevas issus de 3 Manifestes différents

NB : l'instance Mirador de Biblissima a été modifiée pour supporter le 3e exemple ("base64url encoding").

Observons le contenu encodé du 3e exemple ci-dessus en utilisant l'outil Base64Decode.

Testons ensemble la page Content State POC proposée par Glen Robson qui montre les différentes méthodes de transfert de contenu définies par l'API Content State.

## 5.1.4 API Change Discovery

Commençons par enfoncer une porte ouverte : les ressources IIIF, bien que nativement interopérables, n'ont d'utilité que si elles peuvent être trouvées ! En effet, l'interopérabilité introduite par IIIF ne résout pas à elle seule la question de la "trouvabilité" (findability) des ressources sur le Web...

* du point de vue d'un utilisateur : comment trouver des ressources disponibles en IIIF ?

* du point de vue d'une institution : comment rendre mes ressources IIIF "découvrables" et indexables par des tiers ?

* du point de vue d'un agrégateur : comment découvrir, moissonner et indexer ces ressources ? comment se maintenir à jour ?

Tout cela est à l'origine d'un des axes de travail de la communauté IIIF ces dernières années, qui a débouché sur la mise au point d'une nouvelle API : l'API Change Discovery.

Cette API spécifie un mécanisme standard de découverte et de moissonnage en masse de ressources IIIF par des machines (scripts, crawlers etc.). Une des principales mises en application est la construction de moteurs de recherche et portails généralistes ou thématiques, comme cela a été initié par Cultural Japan ou Biblissima IIIF-Collections.

Ainsi l'API Change Discovery fournit un mécanisme pour découvrir/rendre découvrables des ressources IIIF :

* elle apporte une méthode cohérente pour publier des listes de ressources IIIF (par ex. des Manifestes et des Collections) afin d'en permettre le moissonnage.

* elle permet aussi d'optimiser ce processus en permettant aux "moissonneurs" de récupérer uniquement les ressources qui ont été ajoutées ou modifiées depuis leur dernier passage.

Spécification de l'API Change Discovery : https://iiif.io/api/discovery
# 6. Ateliers

## 6.1 Atelier 1 : créer un Manifeste avec le Manifest Editor

Le IIIF Manifest Editor est une application Web pour éditer des Manifestes développée par Bodleian Libraries (Oxford) et text & bytes LLC.

Accéder au Manifest Editor : https://digital.bodleian.ox.ac.uk/manifest-editor
<figure><img src="image_70.png" /></figure>

Consignes
Dans cet exercice nous allons créer un nouveau Manifest à partir de plusieurs Manifestes. Vous pouvez utiliser ceux sélectionnés à l'exercice précédent.
1. Créer un nouveau Manifeste et importer des images :

• cliquer sur New Manifest

• dans le panneau à droite, aller sur Manifest Actions > Import Canvases

• cliquer ensuite sur le bouton Open Sequence, puis copier-coller une URL de Manifeste dans le champ "Enter a remote Manifest URL", puis cliquer sur Open. Une vue zoomable de l'objet devrait s'ouvrir dans la fenêtre à gauche.

• répéter ces actions pour chaque Manifeste choisi.

2. Composer/éditer la séquence de votre Manifeste :

• Une fois vos Manifestes chargés dans l'éditeur, vous pouvez glisser-déposer une à une les images de votre choix dans la partie inférieure de la page (dans l'espace horizontal blanc avec l'indication + Add Canvas ) :

• pour cela, survoler la partie inférieure d'une image, un bandeau avec des vignettes devrait apparaître.

• glisser-déposer la vignette de votre choix dans le bandeau inférieure (au niveau de Add Canvas )

• répéter l'opération pour chaque image que vous souhaitez incorporer dans votre Manifeste.

• vous pouvez réordonner la séquence d'images en faisant glisser chaque Canevas, vous pouvez aussi dupliquer ou supprimer un Canevas

• en cliquant sur un Canvevas, on active le panneau Canvas Metadata à droite qui permet de modifier les métadonnées du Canevas ou d'en renseigner de nouvelles

3. Éditer les métadonnées de votre Manifeste :

• Une fois votre séquence faite, cliquer sur Return to Edit Manifest dans le panneau à droite

• Dans ce même panneau latéral, vous pouvez éditer les métadonnées de votre Manifeste dans la section Manifest Metadata :

• éditer les champs pré-existants du Manifeste d'origine, ou ajouter un nouveau champ en cliquant sur Add metadata field : renseigner au moins le label et la description.

4. Sauvegarder votre Manifeste :

• Dans le panneau latéral, cliquer sur Save Manifest puis Download Manifest.

• Un document manifest.json devrait avoir été téléchargé sur votre ordinateur
## 5. Publier le Manifest sur le Web :

* Pour pouvoir utiliser un Manifeste dans une application, il faut pouvoir le rendre accessible à travers une URL, et donc le déposer quelque part sur un serveur Web. Pour cela, deux options s'offrent à nous :

a. **Option A** : Si vous disposez d'un compte Github (sinon, n'hésitez pas à en créer un !), vous pouvez utiliser le **IIIF Workbench** :

* une fois connecté, vous pouvez charger votre fichier "manifest.json" via l'onglet Manifests : celui-ci sera alors déposé automatiquement sur Github et se verra ainsi attribué une URL

* une fois le chargement effectué, les informations de votre Manifeste devraient apparaître sur la page

* ensuite cliquer sur le logo IIIF pour ouvrir le Manifeste. On constate qu'il est désormais accessible à une URL *.github.io.

* copier cette URL et coller là dans le pad ou dans un fichier texte

* si besoin vous pouvez continuer à éditer le Manifeste à la main directement via Github : pour cela, cliquer sur le 2e bouton Edit manifest in Github

* copier aussi l'URL pour éditer le Manifest sur Github et coller là dans le pad, nous en aurons besoin plus loin

b. **Option B** : Si vous ne souhaitez pas créer de compte Github, vous pouvez utiliser un service de stockage en ligne de documents JSON : **n:point** La pérennité du service n'est en aucun cas garantie mais cela suffit amplement pour l'exercice.

* tout d'abord, retourner dans vos fichiers sur votre ordinateur, ouvrir votre manifest.json et copier-coller tout le contenu JSON (Ctrl+A puis Ctrl+C)

* revenir sur le site n:point et cliquer sur Create JSON Bin

* supprimer le JSON présent par défaut dans la fenêtre et collez le contenu de votre Manifeste (Ctrl+V)

* cliquer ensuite sur Save pour sauvegarder les données

* puis cliquer sur Share, une fenêtre modale devrait s'ouvrir au milieu de l'écran.

* copier la première URL (celle juste en dessous de Access this bin via the API at: ). Vous pouvez la coller dans le pad ou dans un fichier texte. Cette URL sera désormais celle de votre Manifeste sur le Web, elle est utilisable dans n'importe quelle application compatible.

* copier aussi l'URL npoint de la page de votre Manifeste et coller là dans le pad, nous en aurons besoin plus loin pour éditer le Manifeste
6.2 Atelier 2 : annoter un Manifeste avec SimpleAnnotationServer

<figure><img src="image_71.png" /></figure>

SimpleAnnotationServer

SimpleAnnotationServer (SAS) est un serveur d'annotations IIIF écrit en Java et développé par Glen Robson (coordonateur technique de IIIF) :

• il est couplé à la version 2 de Mirador pour la partie cliente dédiée à la visualisation des images et à la création des annotations.

• la partie serveur sert à stocker les annotations de façon persistente. Différents backend sont possibles : Jena, ElasticSearch, Solr

• il supporte l'API Content Search et fournit un point d'accès (endpoint) permettant de rechercher dans les annotations créées.

Pour cet exercice, nous allons utiliser l'instance de test de Biblissima, activée pour les besoins de la formation : https://demos-dev.biblissima.fr/
simpleAnnotationStore/

Avant de commencer l'exercice, voyons un exemple d'exploitation des annotations IIIF créées via Mirador et stockées dans SAS :

• Ovide moralisé ou La Bible des poètes en images. Comparaison de deux cycles iconographiques avec IIIF et Mirador. Démos Biblissima. https://demos.biblissima.fr/ovide-moralise/
<figure><img src="image_72.png" /></figure>

Consignes
## 1. Importer un Manifeste dans SAS :

* cliquer sur Index Manifest puis entrer l'URL de votre Manifeste créé à l'étape précédente

* une page dédiée à votre Manifeste devrait s'afficher, avec son label en tant que titre principal de la page

* votre Manifeste devrait aussi s'afficher dans l'onglet View annotations, parmi la liste des Indexed Manifests

## 2. Annoter votre Manifeste dans Mirador :

* revenir sur la page de votre Manifeste dans SAS

* cliquer sur le lien Annotate : votre Manifeste devrait alors s'ouvrir dans Mirador

* cliquer sur l'icône en forme de bulles en haut à gauche de la vue image

* sélectionner une forme de tracé (rectangle, ovale, tracé libre, polygone, marqueur) et changer si vous le souhaitez l'épaisseur et la couleur du trait, ainsi que la couleur de remplissage de la forme

* délimiter la zone (ou le point) de l'image à annoter ; une fenêtre devrait apparaître au-dessus de l'image

* saisir votre annotation dans l'éditeur (un formatage html de base est possible) ; un champ "Tags" est aussi disponible

* cliquer sur Enregistrer pour sauvegarder l'annotation : celle-ci est désormais stockée de manière persistente dans SAS (dans l'entrepôt RDF de Jena, plus précisément)

* répéter l'opération pour créer 2 ou 3 annotations sur une ou plusieurs images

## 3. Voir dans SAS le détail des annotations créées :

* cliquer sur View annotations dans le menu supérieur, puis cliquer sur votre Manifeste

* cliquer ensuite sur Download annotations, puis sur un lien situé en dessous de l'encadré gris : un document JSON s'ouvre, il contient la liste des annotations qui ont été créées (ce document JSON est une AnnotationList conforme à l'API Presentation 2.1)

## 4. Activer et tester la recherche dans ces annotations (API Content Search) :

* revenir sur la page de votre Manifeste dans View annotations

* dans la section IIIF Search Service, copier le morceau de JSON du 1er encadré gris (celui qui commence par "service") : ceci est la référence au service API Content Search actif pour votre Manifeste

* mais pour qu'un visualiseur tiers puisse utiliser ce service, il va falloir éditer votre Manifeste et inclure cette référence dans le fichier JSON source

* pour ce faire, ouvrir dans un nouvel onglet la page npoint ou Github de votre Manifeste (selon le choix fait lors de l'atelier 1) de façon à pouvoir l'éditer

* coller le morceau de JSON juste après le label par exemple, puis enregistrer la modification

* ouvrir votre Manifeste dans un autre onglet et vérifier que la modification a bien été appliquée (avec Github il peut y avoir un petit délai avant que le changement ne soit effectif)

* une fois le Manifeste mis à jour, l'importer dans l'instance Mirador 3 utilisée tout à l'heure : https://portail.biblissima.fr/m3/?theme=light&context=collection

* il ne vous reste plus qu'à tester la recherche ! Dans la barre d'outils à gauche, cliquer sur l'icône en forme de loupe, puis rechercher un terme parmi ceux que vous avez saisis dans vos annotations créées plus haut (attention la recherche est sensible à la casse). Vous pouvez rechercher un terme dans le texte de l'annotation ou dans les tags (si vous en avez saisis). Des résultats devraient s'afficher dans le panneau de gauche.
## 5. Activer et tester l'affichage des annotations (annotationList) :

* revenir sur la page de votre Manifeste dans `View annotations`

* cliquer sur `Download annotations`: cette page liste les Canevas qui ont été annotés dans votre Manifeste (les liens vers les `AnnotationLists` de chaque Canevas apparaissent sous l'encadré gris)

* l'encadré gris avec le morceau de JSON présente un exemple de comment ces `AnnotationLists` doivent être inclus dans votre Manifeste au niveau de chaque Canevas. C'est ce que nous allons essayer de faire dans la suite de l'exercice. L'idée est de référencer ces `AnnotationLists` dans votre Manifeste pour que n'importe quel client soit en mesure de les afficher.

* au préalable, essayer de retenir sur quel(s) Canevas(s) vous avez fait des annotations. En principe le libellé de chaque Canevas est indiqué dans la liste de liens en dessous de l'encadré gris (par exemple `Page 1`)

* copier uniquement la partie `otherContent` du morceau de JSON :

```json
"otherContent": [ {
  "@id": "http://example.com/sas/annotation/list/4f0d84d2b3a3788a1d4a4faf7cc22b56.json",
  "@type": "sc:AnnotationList",
  "label": "Example annotations"
} ],
```

* dans un nouvel onglet, revenir à la page d'édition de votre Manifeste sur `npoint` ou `Github` (selon le choix fait lors de l'atelier 1)

* coller le morceau `otherContent` dans le Canevas correspondant (de préférence vers le début pour que ce soit plus facile de se repérer) : vous pouvez par exemple le copier juste après le `@id` du Canevas en question

* si vous avez fait des annotations sur plusieurs Canevas, et donc si vous avez plusieurs `AnnotationLists`, répéter l'opération pour chaque Canevas concerné

* maintenant il va falloir remplacer la fausse URL `http://example.com/sas/annotation/list` par la vraie, là encore pour tous les Canevas concernés

* pour ce faire, retourner dans SAS et copier l'URL de chaque `AnnotationLists`

* revenir ensuite dans `npoint` ou `Github` puis remplacer l'URL présente dans le `@id` du `otherContent` (`http://example.org/sas/...`) par celle de votre propre `AnnotationLists` :

```json
"otherContent": [ {
  "@id": "https://demos-dev.biblissima.fr/simpleAnnotationStore/annotation/list/7c6c5b88519132f268f89b96674ece81.json",
  "@type": "sc:AnnotationList",
  "label": "Mes annotations test"
} ],
```

* une fois cela fait pour un ou plusieurs Canevas, enregistrer la modification de votre Manifeste

* ouvrir votre Manifeste dans un autre onglet et vérifier que la modification a bien été appliquée (avec Github il peut y avoir un petit délai avant que le changement ne soit effectif)

* une fois le Manifeste mis à jour, l'importer dans l'instance Mirador 3 utilisée tout à l'heure : https://portail.biblissima.fr/m3/?theme=light&context=collection

* vous devriez remarquer qu'une icône `Annotations` avec une pastille orange est désormais présente dans la barre d'outils à gauche

* cliquer sur cette icône pour déplier le panneau : vos annotations devraient y être listées et apparaître sur l'image

Mais pour quelle raison étrange avons-nous dû faire toutes ces manipulations fastidieuses ?
Pour mieux comprendre, revenons dans l'instance Mirador de SAS :

* On peut constater que les annotations s'affichent bien pour tous les Manifestes qui ont été importés et annotés dans la plateforme, sans qu'on ait eu besoin de faire toute cette tambouille. **Pourquoi ?**

* Cela est dû au fait que cette instance de Mirador est en quelque sorte "branchée" au serveur d'annotations SAS : le visualiseur "sait" où et comment il doit envoyer des requêtes pour récupérer les annotations associées à chaque Canevas. Il est d'une certaine manière "connecté" à la base de stockage de ces annotations.

* En revanche, une autre instance de Mirador ou de n'importe quel autre visualiseur n'a pas cette connaissance et ne pourra donc pas accéder aux annotations créées dans SAS. Le seul moyen pour qu'il puisse les afficher est de les inclure, ou plutôt de les référencer, dans le Manifeste. C'est par ce biais que les annotations vont pouvoir "voyager" avec le Manifeste...

## Dans ce cas, pourquoi SAS n'inclut-il pas lui-même ces annotations dans le Manifeste ?

Lorsque SAS importe et indexe un Manifeste, il ne crée pas une copie de ce dernier : il importe le contenu du Manifeste tel quel, en conservant tous les `@id` d'origine (URI du Manifest, URI des Canevas, URI des images). Ce qui veut dire que toutes les annotations créées seront rattachées à ces URI : ainsi chaque annotation va cibler un Canevas en particulier, identifié par telle URI, provenant de tel Manifest, identifié par telle URI, etc. C'est là qu'on entre dans la dimension proprement "web sémantique" de IIIF. Toutes ces données sont en réalité des triplets RDF dans lesquels chaque ressource (Manifest, Canvas, Annotation etc.) est identifiée de manière unique par une URI sur le Web.

Pour revenir à la question de départ, si SAS ne crée pas une copie d'un Manifeste importé, c'est justement pour conserver la relation entre les annotations créées et les ressources IIIF d'origine (à la fois le Manifest et le Canevas cible, grâce à leurs URI). Moralité : ces annotations restent de fait séparées du Manifest d'origine. Les annotations sont stockées dans SAS, mais les Manifestes auxquels elles sont associées restent inchangés et sont toujours appelés à distance (depuis n'importe quel entrepôt IIIF). Évidemment SAS n'a pas la main pour modifier les Manifestes à la source...

Dans cet exercice nous avons créé au préalable notre propre Manifeste, auquel nous avons accès en écriture (via npoint ou Github). C'est ce qui nous a permis d'ajouter à la main à la fois la référence au service API Content Search puis aux *AnnotationLists*. Ainsi un visualiseur externe tel que l'instance Mirador de Biblissima a pu avoir accès à ces données et à cette fonctionnalité via notre Manifeste, comme nous avons pu l'expérimenter. Mais si nous étions parti par exemple d'un Manifeste de Gallica, nous n'aurions pas pu faire la même chose, en tout cas pas sans dupliquer ce Manifeste pour le restocker quelque part où on puisse le modifier...

Il serait certes envisageable que SAS crée un dérivé du Manifest d'origine au moment de l'import, tout en conservant les URI des Canevas, mais ce n'est pas le choix qui a été fait par le développeur. En faisant cela, on se retrouverait dans une situation dans laquelle chaque annotateur ou projet d'annotation devrait travailler sur un clone du Manifest d'origine. Ce n'est pas optimal, mais c'est la seule solution possible à l'heure actuelle. Et c'est ainsi que procèdent beaucoup de projets qui utilisent des Manifestes fournis par des institutions patrimoniales et qui y apportent des enrichissements (annotations, transcriptions etc.). On peut citer notamment les plateformes de transcription *FromThePage* aux États-Unis, et *Arkindex* en France (Teklia), qui chacune recrée dans son propre système un Manifeste dérivé pour pouvoir avoir la main dessus et ainsi l'enrichir avec ses propres données.

Le plus important dans ce cas de figure est que le Manifeste dérivé et les annotations créées conservent quelque part dans les données les références aux ressources IIIF d'origine, de façon à ce que ces annotations puissent à un moment donné être reversées dans le Manifest source (maintenu par telle ou telle bibliothèque, service d'archives, musée etc.).

Voyons quelques exemples pour illustrer ce propos :

* Page d'un manuscrit de Parker Library (Corpus Christi College, Cambridge) dans le Portail Biblissima, avec affichage des annotations (Manifeste IIIF délivré par Stanford) : https://portail.biblissima.fr/fr/ark:/43093/mdata52c0e7fe45e95a834dfdcfb9704c8c3774988b6

* Page du site *Thematic Pathways on the Web - IIIF annotations of manuscripts from the Vatican collections* : 28r: Urb.lat.365 – Miniatura tabellare assegnata a, où l'on peut voir des annotations IIIF, mais celles-ci ne sont pas répercutées dans le Manifest d'origine publié par la Bibliothèque Vaticane (voir ce manuscrit sur DigiVatLib et sur le Mirador Biblissima)

* Page d'un manuscrit de la BnF dans *FromThePage*, importé via IIIF et transcrit dans le cadre d'un projet collaboratif : BnF. Bibliothèque de l'Arsenal. Ms-8536. La plateforme a recréé un Manifeste (https://fromthepage.com/iiif/34889/manifest) et propose de façon assez astucieuse une API qui permettrait par exemple à la BnF de récupérer facilement les données produites (transcription + traduction) : https://fromthepage.com/iiif/for/https://gallica.bnf.fr/iiif/ark:/12148/btv1b55013450m/manifest.json (https://fromthepage.com/iiif/{URL_MANIFESTE_SOURCE})
## 6.3 Atelier 3 : créer une exposition virtuelle avec Storiies

Storiies est un outil d'exposition virtuelle permettant de créer des parcours guidés au sein d'une image. Il s'appuie à la fois sur des images et des annotations IIIF pour proposer ces parcours. Il est développé par la société britannique Cogapp.

Il est constitué de deux applications :

* le Storiies Editor : éditeur pour créer et modifier une exposition virtuelle, utilisable uniquement via le site de Cogapp

* le Storiies Viewer : visualiseur d'exposition virtuelle, disponible en open source (Github)

Pour cet atelier nous allons utiliser une version du Storiies Viewer hébergée par Biblissima : https://demos.biblissima.fr/storiies-viewer/. Cette instance supporte le paramètre *iiif-content* de l'API Content State, ce qui signifie qu'il est possible de charger un Manifeste en passant son adresse dans ce paramètre d'URL.

### Modèle d'URL pour ouvrir un Manifeste dans le Storiies Viewer

https://demos.biblissima.fr/storiies-viewer/?iiif-content={url MANIFESTE_story}
<figure><img src="image_73.png" /></figure>

## Consignes

Dans cet exercice nous allons tous partir du même Manifest : https://www.loc.gov/item/2003626426/manifest.json (Library of Congress : Waldseemüller's 1507 Map).

1. Ouvrir le Storiies Editor pour créer votre "story"

* coller l'URL du Manifeste dans le champ `IIIF manifest` or `info.json` URL

* renseigner les autres champs proposés

2. Créer un parcours en zoomant sur différents détails dans l'image :

* zommer sur un détail et créer une annotation en cliquant sur le bouton "Add new +" en haut à gauche. Chaque annotation correspondra à une étape du parcours au sein de l'image

* répéter l'opération de façon à créer 3 ou 4 annotations

3. Prévisualiser votre story et récupérer l'URL du Manifeste correspondant :

* cliquer sur le bouton "Preview" (ouvre un nouvel onglet) et tester votre story

* reconstruire l'URL du Manifeste de votre story en suivant les indications ci-dessous :

L'URL de la page du Preview est sous la forme suivante :

https://storiies.cogapp.com/viewer/{id}/{story_name}

Pour récupérer l'URL du Manifeste de votre story, il faut d'abord prendre son identifiant (valeur de `{id}`) et construire l'URL suivante :

https://manifest.storiies-editor.cogapp.com/v3/{id}

4. Ouvrir le Manifeste et repérer dans le JSON les annotations créées dans le Storiies Editor :

* repérer la propriété `annotations` au niveau de l'unique Canevas présent dans votre Manifest

5. Importer le Manifeste dans le Storiies Viewer :

* utiliser pour cela le paramètre `iiif-content` de l'API Content State vu précédemment :

Modèle :

https://demos.biblissima.fr/storiies-viewer/?iiif-content={url: manifest.story}

6. Importer le Manifeste dans l'outil Annona :

* utiliser pour cela le même paramètre `iiif-content` :

Modèle :

https://demos.biblissima.fr/annona/?iiif-content={url Mani}: feste.story}

Il existe d'autres outils dans la galaxie IIIF qui permettent de créer des expériences similaires, parmi lesquels :

* Exhibit.so est plus perfectionné que Storiies (prend en charge plusieurs images issues de plusieurs Manifests, propose différents templates), mais le code source est fermé et il n'est possible de récupérer ni le Manifest généré par l'application, ni les annotations créées.

Exemple : The Voyage of Life, par Thomas Cole

* Adno a l'avantage d'être entièrement open source mais, comme Storiies, il ne prend en charge qu'une seule image par parcours. De plus il ne supporte IIIF qu'en entrée, pas en sortie (l'outil permet néanmoins d'exporter un projet au format Web Annotation, puis de réimporter le projet par la suite). Il est basé sur les librairies Annona, Annotorious et OpenSeaDragon.

Pour une liste plus complète, voir la section Exhibition and Guided Viewing Tools de awesome-iiif.
<figure><img src="image_74.png" /></figure>

Questions
# 7. Crédits

## Auteur : Régis Robineau

Ce travail a bénéficié d'une aide de l'État gérée par l'Agence Nationale de la Recherche au titre du programme d'Investissements d'avenir portant la référence « ANR-21-ESRE-0005 » (ÉquipEx Biblissima+).

Biblissima li+

<figure><img src="image_75.png" /></figure>

Observatoire des cultures écrites
de l'argile à l'imprimé

Certains contenus de cette formation ont été inspirés du IIIF Online workshop (licence CC-BY-4.0) proposé par le consortium IIIF et assuré par Glen Robson. Cela concerne principalement la partie API Image (exemples et code Javascript du formulaire de manipulation des paramètres). L'essentiel des contenus du site est le fruit d'un travail original.

Sauf mention contraire les contenus de ce site sont publiés sous la Licence Ouverte / Open License 2.0.

## Source des images :

* API Image / Region : region.png (Copyright © 2012-2022 Editors and contributors. Published by the IIIF Consortium under the CC-BY license)

* API Image / Implémentation : Pyramid Image (Source : IIPlImage. Copyright © 2022 Ruven Pillay)

* API Présentation / Introduction : objects-all.webp & data-model.png & objects.webp (Copyright © 2012-2022 Editors and contributors. Published by the IIIF Consortium under the CC-BY license)