IIIFマニフェストの作成と管理

マニフェスト作成の全体像

前章でPresentation APIの仕様を学びましたが、本章では実際にマニフェストファイルを作成・管理するための具体的な手法を紹介します。マニフェストの作成方法は大きく分けて以下の3つのアプローチがあります。

手動作成: JSON-LDファイルをテキストエディタで直接記述する
プログラムによる生成: PythonやJavaScriptなどのライブラリを使って自動生成する
CMSによる管理: Headless CMSやデジタルアーカイブシステムを通じて管理する

少数の資料を扱う場合や仕様の学習目的であれば手動作成が適していますが、数百件以上の資料を扱うプロジェクトではプログラムによる自動生成が現実的です。また、継続的に資料を追加・更新するようなケースでは、CMSベースの管理が運用負荷を下げてくれます。

iiif-prezi3（Python）を使ったマニフェスト生成

Pythonでマニフェストを生成する場合、iiif-prezi3ライブラリが有力な選択肢です。このライブラリはIIIF Presentation API v3に対応しており、Pythonオブジェクトとしてマニフェストを構築し、仕様に準拠したJSONを出力できます。

インストールと基本設定

pip install iiif-prezi3

日本語の資料を扱う場合、言語設定をあらかじめ行っておくと便利です。

import iiif_prezi3

iiif_prezi3.config.configs['helpers.auto_fields.AutoLang'].auto_lang = "ja"

この設定により、labelやmetadataの言語フィールドが自動的にjaとして出力されます。

Collectionの作成

collection = iiif_prezi3.Collection(
    id="https://example.org/iiif/collection.json",
    label="東寺百合文書",
    viewingDirection="right-to-left",
    provider=iiif_prezi3.ProviderItem(
        id="https://example.org/",
        label="提供機関名",
    ),
    homepage=iiif_prezi3.HomepageItem(
        id="https://example.org/",
        type="Text",
        label="提供機関名",
        format="text/html",
        language="ja"
    ),
    metadata=[
        iiif_prezi3.KeyValueString(label="Attribution", value="帰属情報"),
        iiif_prezi3.KeyValueString(label="Rights", value="ライセンスURL"),
    ],
    rights="https://creativecommons.org/licenses/by/4.0/",
)

iiif_prezi3.ProviderItemを使うと、type: "Agent"が自動的に設定されます。iiif_prezi3.KeyValueString関数を使うことで、labelとvalueが仕様に準拠した言語マップ配列として出力される点も、手動でJSONを書く場合に比べて大きな利点です。

JSON出力

with open("collection.json", "w") as f:
    f.write(collection.json(ensure_ascii=False, indent=2))

ensure_ascii=Falseを指定することで、日本語がエスケープされずにそのまま出力されます。本番環境向けにはindent=Noneとすることでファイルサイズを削減できます。

ManifestとCanvasの作成

Manifestやキャンバスについても同様のパターンで作成できます。特にキャンバスのサイズ指定については、iiif-prezi3の公式レシピ（https://iiif-prezi.github.io/iiif-prezi3/recipes/0004-canvas-size/）が参考になります。画像のURLとサイズ情報を元に、適切なCanvasとAnnotationを自動生成するコードを組めば、大量のページ画像を持つ資料でも効率的にマニフェストを作成できます。

Headless CMSを使ったマニフェスト管理

マニフェストの管理にHeadless CMSを活用するアプローチも有効です。CMSのGUI上でメタデータや画像情報を登録し、APIを通じてIIIFマニフェスト形式に変換して配信するという仕組みです。

Contentfulを使った実装例

Contentful（https://www.contentful.com/）では、以下のようなContent modelを設計します。

iiifモデル: ラベル、メタデータなどの基本情報
imageモデル: 画像URL、幅、高さの情報（Referenceフィールドでiiifモデルと紐付け）

Nuxt3のサーバサイドAPIルートを作成し、ContentfulのAPIから取得したデータをIIIFマニフェストのJSON構造に変換して返却します。contentful npmパッケージを使用することで、ContentfulのAPIとの接続が容易に行えます。

microCMSを使った実装例

microCMS（https://microcms.io/）でも同様のアプローチが可能です。「カスタムフィールド」機能を使って、画像URL・幅・高さの3つのフィールドを持つカスタムフィールドを定義し、繰り返しフィールドとしてマニフェストのスキーマに追加します。これにより、複数の画像を持つ資料をGUI上で直感的に管理できます。

CMSアプローチの利点

Headless CMSを使ったマニフェスト管理には以下のメリットがあります。

非エンジニアでも運用可能: GUI上でコンテンツを登録・編集できるため、技術的知識がなくてもマニフェストを管理できる
APIファースト: ContentfulやmicroCMSはREST APIを提供しているため、マニフェスト変換処理の実装が容易
スケーラビリティ: CMSのスケーリング機能を活用して大量のコンテンツを管理できる
バージョン管理: CMSの履歴機能を使ってコンテンツの変更履歴を追跡できる

OmekaのようなデジタルアーカイブシステムをHeadless CMSとフロントエンドフレームワークの組み合わせで再構築するという発想も、現代的なアーキテクチャとして検討に値します。

既存データからのマニフェスト変換

すでに何らかの形式で公開されているデータをIIIFマニフェストに変換するケースも多くあります。

東寺百合文書の変換事例

京都府立京都学・歴彩館が所蔵する国宝・東寺百合文書のデータをIIIF形式に変換した事例では、公開されているデータセットからiiif-prezi3を使ってマニフェストを生成しています。このプロジェクトでは以下の点がポイントでした。

画像サイズの取得: 元のデータセットに画像のwidth/height情報が含まれていなかったため、画像サーバのinfo.jsonから取得してCanvasのサイズ情報として設定
IIIFコレクションの構築: 生成した個々のマニフェストをまとめるCollectionファイルを作成し、機械的なアクセスを可能に
静的ホスティング: GitHub Pagesで静的にホスティングすることで、サーバ側の動的処理を不要に

既存データからの変換では、元データのスキーマとIIIFマニフェストの構造のマッピングを最初に設計することが重要です。特に画像のサイズ情報が元データに含まれていない場合、IIIF Image APIのinfo.jsonエンドポイントから取得するか、画像ファイルを直接読み込んでサイズを計測する必要があります。

マニフェストのユーティリティ

既存のマニフェストファイルを加工・変換するための各種ユーティリティも実務では頻繁に使用します。

画像URL一覧のCSV出力

マニフェストファイルから画像URLの一覧をCSV形式で出力するツールが便利な場面は多くあります。例えば、OmekaやDrupalといったCMSにCSVで一括登録する際や、画像の一覧管理を行いたい場合です。

出力されるCSVには以下のような情報が含まれます。

url,width,height,canvas
https://example.org/iiif/image1/info.json,6890,4706,https://example.org/iiif/canvas/1
https://example.org/iiif/image2/info.json,6890,4706,https://example.org/iiif/canvas/2

@iiif/parserのconvertPresentation2関数を組み合わせることで、入力マニフェストがv2であってもv3であっても統一的に処理できます。

マニフェストからPDFへの変換

IIIFマニフェストからPDFファイルを生成する需要もあります。Pythonのimg2pdfライブラリを活用し、マニフェストから画像URLを抽出してダウンロードし、PDFとして結合する方法が実用的です。Google Colabのノートブックとして提供すれば、環境構築なしで利用できます。

Canvas URIの一括置換

マニフェストファイル内のURIを一括で置換する必要が生じることがあります。例えば、画像サーバのドメインが変更になった場合などです。

find . -type f -name "*.json" \
  -exec sed -i '' 's/www\.example\.org/example\.org/g' {} +

この種の一括置換を行う際は、必ず事前にバックアップを取り、バイナリファイルに対して実行しないよう注意してください。また、JSON内の値だけでなくキーにも同じ文字列が含まれる可能性があるため、置換結果を慎重に確認することが重要です。

各巻の冒頭ページ抽出

複数巻で構成される資料のマニフェストから、各巻の冒頭ページへのリンクを抽出するニーズもあります。マニフェストのstructuresプロパティに定義されたRange情報を解析し、各Rangeのlabelと最初のCanvas URLを取得します。

if (manifest.structures) {
  for (const structure of manifest.structures) {
    if (structure.ranges && structure.ranges.length > 0) continue;
    if (structure.canvases && structure.canvases.length > 0) {
      const label = structure.label;
      const firstCanvas = structure.canvases[0];
      // 抽出データに追加
    }
  }
}

structuresが存在しない場合は、sequences[0].canvasesの最初の要素を取得するフォールバック処理を入れておくとよいでしょう。

IIIFアイコンによるドラッグ&ドロップ共有

IIIFのマニフェストURLを他のビューアに簡単に読み込ませる仕組みとして、IIIFアイコンのドラッグ&ドロップがあります。Webページ上のIIIFアイコンをMiradorやUniversal Viewerのウィンドウにドラッグすると、そのマニフェストがビューアに読み込まれます。

この機能を正しく動作させるには、aタグのhref属性に?manifest=パラメータを含める必要があります。

<!-- 正しい記述 -->
<a href="https://example.org/manifest?manifest=https://example.org/manifest">
  <img src="iiif-dragndrop-100px.png" alt="IIIF Drag-n-drop"/>
</a>

URLに?manifest=パラメータが含まれていることをビューア側が検出し、その値をマニフェストURLとして読み込みます。そのため、?manifest=の前の部分（default_target）は実際にはマニフェストのURLでなくても動作します。Universal ViewerやIIIF Curation Viewerなどのビューアリンクにも?manifest=パラメータが含まれているため、これらのリンクやアイコンも同様にドラッグ&ドロップで他のビューアに読み込ませることができます。

hrefにマニフェストURLを2回記述する形は冗長に見えますが、これがIIIFコミュニティにおける標準的な実装パターンです。サイトにIIIFアイコンを設置する際は、この記述方式に従うことで、幅広いビューアとの互換性を確保できます。

マニフェスト管理のベストプラクティス

実運用におけるマニフェスト管理のベストプラクティスをまとめます。

バリデーションの自動化: マニフェストを生成・更新するたびにPresentation API Validatorで検証するワークフローを組み込みましょう。ローカルバリデータをCI/CDパイプラインに統合すれば、仕様違反を自動で検出できます。

バージョンの統一: プロジェクト内ではPresentation APIのバージョンを統一することを推奨します。新規プロジェクトではv3を採用するのが望ましいですが、既存システムとの互換性が求められる場合はv2を使い続けることも選択肢です。@iiif/parserを活用すれば、異なるバージョン間の変換が可能です。

URIの永続性: マニフェストやCanvasのURIは一度公開すると外部から参照される可能性があるため、できるだけ安定したURIスキームを設計してください。ドメイン変更が必要になった場合はリダイレクトを設定し、一括置換ツールで関連ファイルを更新します。

権利情報の明示: rightsプロパティにCreative CommonsまたはRightsStatements.orgのURLを設定し、requiredStatementやmetadataにも利用条件を明記しましょう。これにより、利用者が権利情報を容易に確認できるようになります。

静的ホスティングの活用: マニフェストファイルは静的なJSONファイルであるため、GitHub PagesやAWS S3などの静的ホスティングで配信できます。動的生成が不要な場合は、静的ホスティングによりインフラの運用コストを大幅に削減できます。

まとめ

マニフェストの作成は、手動記述からプログラムによる自動生成、CMSによる管理まで、プロジェクトの規模や要件に応じて適切な手法を選択することが重要です。iiif-prezi3のようなライブラリを活用すれば仕様準拠のマニフェストを効率的に生成でき、Headless CMSと組み合わせれば非エンジニアでも運用できるワークフローを構築できます。画像URL抽出やPDF変換、URI一括置換といったユーティリティも活用しながら、持続可能なマニフェスト管理体制を構築していきましょう。

マニフェスト作成の全体像#

iiif-prezi3（Python）を使ったマニフェスト生成#

インストールと基本設定#

Collectionの作成#

JSON出力#

ManifestとCanvasの作成#

Headless CMSを使ったマニフェスト管理#

Contentfulを使った実装例#

microCMSを使った実装例#

CMSアプローチの利点#

既存データからのマニフェスト変換#

東寺百合文書の変換事例#

マニフェストのユーティリティ#

画像URL一覧のCSV出力#

マニフェストからPDFへの変換#

Canvas URIの一括置換#

各巻の冒頭ページ抽出#

IIIFアイコンによるドラッグ&ドロップ共有#

マニフェスト管理のベストプラクティス#

まとめ#