IIIF Image API入門

Image APIとは

IIIF Image APIは、デジタル画像の配信方法を標準化するAPIです。画像の特定領域を、指定したサイズ・回転・品質で取得するためのURLの構造を定義しています。Webブラウザやビューアは、このURLの規則に従ってリクエストを送るだけで、必要な画像を取得できます。

このAPIが解決する根本的な課題は、「大きな画像を効率的に配信すること」です。たとえば、文化財のデジタル画像は数千万画素に及ぶことも珍しくありません。このような画像をそのままダウンロードさせるのではなく、閲覧者が必要としている部分だけを、適切なサイズで動的に配信することで、快適な閲覧体験を実現します。

URIの構造

Image APIの最も重要な概念は、画像取得のためのURI構造です。以下の形式で画像を指定します。

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

各パラメータの意味は次のとおりです。

identifier（識別子）

画像を一意に識別するための文字列です。画像サーバの実装によって、ファイルパスやデータベースのIDなどが使われます。

https://example.org/iiif/book1-page1/full/max/0/default.jpg
                         ^^^^^^^^^^^^
                         identifier

region（領域）

画像のどの部分を切り出すかを指定します。

値	意味	例
`full`	画像全体	`full`
`square`	正方形（短辺に合わせた中央部分）	`square`
`x,y,w,h`	ピクセル座標で指定（左上が原点）	`100,200,300,400`
`pct:x,y,w,h`	パーセンテージで指定	`pct:10,10,80,80`

# 画像全体を取得
https://example.org/iiif/image1/full/max/0/default.jpg

# 左上から100x100の位置、幅300 高さ400の領域を取得
https://example.org/iiif/image1/100,100,300,400/max/0/default.jpg

# 画像中央の80%の領域を取得
https://example.org/iiif/image1/pct:10,10,80,80/max/0/default.jpg

size（サイズ）

出力画像のサイズを指定します。

値	意味	例
`max`	サーバが提供可能な最大サイズ	`max`
`^max`	元画像のサイズ（アップスケーリング許可）	`^max`
`w,`	幅を指定し、高さはアスペクト比を維持	`300,`
`,h`	高さを指定し、幅はアスペクト比を維持	`,400`
`w,h`	幅と高さを指定（アスペクト比が変わる可能性あり）	`300,400`
`!w,h`	指定した幅・高さに収まる最大サイズ（アスペクト比維持）	`!300,400`
`pct:n`	元画像に対するパーセンテージ	`pct:50`

# 幅300ピクセルで取得（高さは自動計算）
https://example.org/iiif/image1/full/300,/0/default.jpg

# 200x200に収まるサイズで取得
https://example.org/iiif/image1/full/!200,200/0/default.jpg

# 元画像の25%のサイズで取得
https://example.org/iiif/image1/full/pct:25/0/default.jpg

rotation（回転）

出力画像の回転角度を指定します。0から360の値を指定でき、時計回りに回転します。! を前置すると、回転前に左右反転します。

# 回転なし
https://example.org/iiif/image1/full/max/0/default.jpg

# 90度回転
https://example.org/iiif/image1/full/max/90/default.jpg

# 左右反転してから180度回転
https://example.org/iiif/image1/full/max/!180/default.jpg

quality（品質）

画像の品質を指定します。

値	意味
`default`	サーバのデフォルト品質
`color`	カラー画像
`gray`	グレースケール画像
`bitonal`	白黒2値画像

format（フォーマット）

出力する画像フォーマットを指定します。jpg、png、gif、webp、tif などが指定可能です（サーバの対応状況に依存します）。

URL組み立ての実例

以上のパラメータを組み合わせることで、目的に応じた画像を柔軟に取得できます。いくつかの実践的な例を示します。

# サムネイル用: 幅200pxのJPEG
https://example.org/iiif/image1/full/200,/0/default.jpg

# 一覧表示用: 正方形に切り出して150x150に縮小
https://example.org/iiif/image1/square/150,150/0/default.jpg

# 詳細表示用: 特定領域を拡大して確認
https://example.org/iiif/image1/1000,2000,500,500/800,/0/default.jpg

# 印刷用: 画像全体をグレースケールのPNGで取得
https://example.org/iiif/image1/full/max/0/gray.png

# SNS共有用: 画像全体を横幅1200pxで取得
https://example.org/iiif/image1/full/1200,/0/default.jpg

このように、URLのパラメータを変えるだけで、同一の元画像からさまざまなバリエーションの画像を取得できることがImage APIの大きな特徴です。

Compliance Level（準拠レベル）

Image APIには、サーバが対応すべき機能の範囲に応じて3つのレベルが定義されています。これにより、シンプルな静的配信から高機能な動的配信まで、段階的に対応できます。

Level 0 — 静的配信

Level 0は、事前に生成した静的なタイル画像を配信する最もシンプルなレベルです。サーバ側でリアルタイムの画像処理を行う必要がないため、GitHub PagesやAmazon S3のような静的ファイルホスティングサービスだけで画像を公開できます。

対応する機能:

事前に定義されたサイズの画像の取得
info.jsonの提供

制約:

任意の領域の切り出しはできない
任意のサイズへの変換はできない
回転や品質の変更はできない

Level 0は、画像配信サーバの運用コストを最小限に抑えたい場合や、小規模なコレクションを手軽にIIIF対応させたい場合に適しています。

Level 1 — 基本的な動的配信

Level 1は、基本的な画像処理機能を提供するレベルです。任意の領域の切り出しやサイズ変更が可能になります。

Level 0に加えて対応する機能:

任意の領域（region）の指定
任意のサイズ（size）への変換
0度以外の回転（90, 180, 270度）

Level 2 — 完全な動的配信

Level 2は、Image APIの全機能を提供する最も高機能なレベルです。

Level 1に加えて対応する機能:

任意の角度の回転
品質の変更（カラー、グレースケール、白黒2値）
複数の出力フォーマット

Cantaloupeのような本格的なイメージサーバはLevel 2に対応しています。

レベルの選び方

どのレベルを選ぶかは、プロジェクトの要件とリソースによって判断します。

観点	Level 0	Level 1	Level 2
サーバ要件	静的ホスティングのみ	画像処理サーバが必要	高機能な画像処理サーバが必要
運用コスト	低い	中程度	高い
機能の柔軟性	限定的	基本的な操作が可能	全機能利用可能
適したケース	小規模コレクション、予算が限られる場合	一般的なデジタルアーカイブ	高度な研究利用、大規模機関

まずはLevel 0で始めて、必要に応じてLevel 1やLevel 2にアップグレードするというアプローチも現実的です。

info.json — 画像の自己記述

Image APIにおいて、各画像は info.json という自己記述ファイルを持ちます。これは画像のメタデータを提供するもので、以下のURLで取得できます。

{scheme}://{server}/{prefix}/{identifier}/info.json

info.jsonの構造

info.jsonには、画像に関する技術的な情報が含まれます。以下はPresentation API 3.0に対応したinfo.jsonの基本的な構造です。

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/iiif/image1",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "maxWidth": 3000,
  "tiles": [
    {
      "width": 512,
      "scaleFactors": [1, 2, 4, 8, 16]
    }
  ],
  "preferredFormats": ["webp", "jpg"],
  "rights": "http://creativecommons.org/licenses/by/4.0/"
}

各フィールドの意味は次のとおりです。

id: この画像サービスのベースURI
type: サービスの種類（Image API 3.0の場合は ImageService3）
profile: 準拠レベル（level0、level1、level2）
width / height: 元画像のピクセル幅・高さ
maxWidth / maxHeight: サーバが返す画像の最大サイズ
tiles: タイル配信の設定。width はタイルの幅、scaleFactors は対応する縮小倍率
preferredFormats: サーバが推奨する画像フォーマット
rights: 画像の利用条件を示すURI

info.jsonの役割

ビューアはまずinfo.jsonを取得することで、以下の情報を得ます。

画像のサイズ: 表示領域の初期設定やUIの構築に必要
対応レベル: ビューアがどのような操作を要求できるかの判断
タイル情報: 効率的な深層ズーム（Deep Zoom）表示のためのタイルサイズと縮小倍率
制約情報: 最大サイズなどの制限事項

つまりinfo.jsonは、ビューアとイメージサーバの間の「契約書」のような役割を果たしています。ビューアはこの情報をもとに、サーバに対してどのようなリクエストを送れるかを判断します。

Level 0による静的配信の実装

ここでは、最も手軽なLevel 0での画像公開方法を解説します。Level 0では、事前にタイル画像を生成しておき、それを静的ファイルとして配信します。

タイル画像の生成

Pythonの iiif_static.py スクリプトなどを使って、元画像からタイル画像を生成します。Google Colabで実行できるノートブックも公開されており、環境構築なしで手軽に試すことができます。

タイル生成後のディレクトリ構造は以下のようになります。

tile/
├── image1/
│   ├── info.json
│   ├── full/
│   │   ├── 256,/
│   │   │   └── 0/
│   │   │       └── default.jpg
│   │   └── ...
│   ├── 0,0,1024,1024/
│   │   ├── 256,/
│   │   │   └── 0/
│   │   │       └── default.jpg
│   │   └── ...
│   └── ...

各ディレクトリパスがImage APIのURIパラメータに対応していることに注目してください。{region}/{size}/{rotation}/{quality}.{format} の構造がそのままファイルシステム上のパスになっています。サーバはURLに対応するファイルをそのまま返すだけでよいため、Webサーバの設定だけで画像配信が可能になります。

GitHub Pagesでの公開

生成したタイル画像をGitHubリポジトリにプッシュし、GitHub Pagesを有効にするだけで、IIIF Image API Level 0に準拠した画像配信が実現できます。

# タイル画像をリポジトリに追加
git add tile/
git commit -m "Add IIIF tile images"
git push origin main

公開後、https://{username}.github.io/{repo}/tile/image1/info.json のようなURLでinfo.jsonにアクセスでき、IIIFビューアから画像を表示できます。

Level 0の制約と対処法

Level 0では事前に生成したタイルしか提供できないため、以下のような制約があります。

ビューアで任意の領域を自由に拡大・切り出すことはできない（事前定義されたタイルの範囲内でのみ対応）
深層ズームの品質はタイルの解像度に依存する
元画像が多い場合、生成されるタイルファイルの総数が膨大になる

これらの制約が問題になる場合は、Level 1以上の動的配信に移行する必要があります。

動的配信（Level 1/2）が必要なケース

以下のような要件がある場合は、Cantaloupeなどの動的イメージサーバの導入を検討してください。

大規模コレクション: 数万点以上の画像を扱う場合、すべての画像について事前にタイルを生成・保存するのは現実的ではありません。動的サーバであれば、リクエストに応じてオンデマンドで画像を生成できます。

任意領域の切り出し: 研究用途では、画像の特定部分を正確に切り出して引用・参照することが求められます。Level 0ではこの要求に応えられません。

画像処理機能: グレースケール変換や任意角度の回転など、Image APIの高度な機能を活用したい場合はLevel 2対応のサーバが必要です。

API連携: 外部のアプリケーションやスクリプトからImage APIを呼び出して、動的にさまざまなサイズ・領域の画像を取得する場合に必要です。

動的配信のためのイメージサーバ構築については、次章「Cantaloupe入門」で詳しく解説します。

Image APIのURLを組み立てるツール

Image APIのURL構造は規則的ですが、パラメータの組み合わせを手作業で試すのは面倒な場合があります。そこで、URLの各パラメータをGUI上で操作できるツールが開発されています。

Nuxt 3とVuetify 3を用いたImage API操作ツールでは、URLを入力すると各パラメータ（region、size、rotation、quality、format）が自動的にパースされ、画面上で個別に値を変更しながら結果をプレビューできます。Image APIの学習や、URLのデバッグに役立ちます。

このようなツールを活用することで、Image APIのURL構造への理解が深まり、実践的な利用がスムーズになるでしょう。

まとめ

本章では、IIIF Image APIの基本を学びました。重要なポイントを振り返ります。

Image APIは {identifier}/{region}/{size}/{rotation}/{quality}.{format} というURI構造で画像を取得する
準拠レベルはLevel 0（静的配信）からLevel 2（完全な動的配信）まで3段階ある
info.jsonは画像の技術的メタデータを提供し、ビューアとサーバの間の契約書として機能する
Level 0は静的ファイルホスティングだけで実現できる最も手軽な方法
大規模コレクションや高度な画像操作が必要な場合はLevel 1/2の動的配信が適している

次章では、Level 2に対応した本格的なイメージサーバであるCantaloupeの導入と設定方法を学びます。

Image APIとは#

URIの構造#

identifier（識別子）#

region（領域）#

size（サイズ）#

rotation（回転）#

quality（品質）#

format（フォーマット）#

URL組み立ての実例#

Compliance Level（準拠レベル）#

Level 0 — 静的配信#

Level 1 — 基本的な動的配信#

Level 2 — 完全な動的配信#

レベルの選び方#

info.json — 画像の自己記述#

info.jsonの構造#

info.jsonの役割#

Level 0による静的配信の実装#

タイル画像の生成#

GitHub Pagesでの公開#

Level 0の制約と対処法#

動的配信（Level 1/2）が必要なケース#

Image APIのURLを組み立てるツール#

まとめ#