Miradorビューアの導入と基本操作

Miradorの概要

Miradorは、IIIF対応の高機能画像ビューアです。Stanford大学を中心としたコミュニティによってオープンソースで開発されており、デジタルヒューマニティーズの研究や文化遺産機関のデジタルアーカイブで幅広く使用されています。

Miradorの最大の特徴はマルチウィンドウ表示です。複数のIIIFマニフェストを同時に開き、異なる機関が公開する画像を並べて比較閲覧できます。例えば、同じ作品の異本を複数機関から読み込んで同一画面上で対照することが可能です。

バージョンの歴史

Mirador 2: 初期の安定版。Scroll View（連続表示）などが標準で利用できた
Mirador 3: Reactベースに書き直された大規模リファクタリング版。プラグインアーキテクチャの導入、Reduxによるステート管理が特徴。現在広く使われているバージョン
Mirador 4: 2025年現在開発中のalpha版。内部APIの改善やinitialViewerConfigによる初期表示設定の強化など、新機能が追加されつつある

各バージョンは後方互換性が完全ではないため、プラグインやカスタマイズコードの移行には注意が必要です。

インストールと基本セットアップ

Miradorの導入方法は主に3つあります。

CDN経由での利用

もっとも手軽な方法です。HTMLファイルに以下のコードを記述するだけでMiradorが動作します。

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
  <title>Mirador</title>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" />
</head>
<body>
  <div id="mirador" style="position: absolute; top: 0; bottom: 0; left: 0; right: 0;"></div>
  <script src="https://unpkg.com/mirador@latest/dist/mirador.min.js"></script>
  <script>
    Mirador.viewer({
      id: "mirador",
      windows: [{
        manifestId: "https://dl.ndl.go.jp/api/iiif/3437686/manifest.json",
      }],
      language: "ja",
    });
  </script>
</body>
</html>

npm経由でのインストール

プロジェクトに組み込む場合はnpmを使います。

npm install mirador

JavaScriptやTypeScriptのプロジェクトからインポートして使用できます。Mirador 4のローカル開発環境を立ち上げる場合は以下のようにします。

git clone https://github.com/projectmirador/mirador
cd mirador
pnpm i
pnpm start

ポート4444でローカル開発サーバが起動します。

iframe埋め込み

既存のWebサイトにMiradorを埋め込む場合、iframeを使う方法が実用的です。Stanford大学のStanford Digital Repositoryなどでも採用されているアプローチで、書誌情報の上部にビューアを配置し、メタデータと画像を同一ページで閲覧できるようにしています。

<iframe
  src="/mirador/index.html?manifest=https://example.org/manifest.json&embed=true&theme=dark&lang=ja"
  width="100%"
  height="600px"
  allow="fullscreen"
  allowFullScreen
  style="border: none;"
></iframe>

URLパラメータで各種設定を制御できます。

パラメータ	説明	例
`manifest`	IIIFマニフェストURL（必須）。セミコロン区切りで複数指定可能	`https://example.org/manifest.json`
`embed`	埋め込みモード（`true`で閉じるボタンと左側メニューを非表示）	`true`
`theme`	テーマ（`dark`または`light`）	`dark`
`lang`	言語コード	`ja`
`canvas`	初期表示するキャンバスID	-
`annotationState`	アノテーション表示モード	`true`

埋め込みモード（embed=true）では、ウィンドウの閉じるボタンや最大化ボタン、左側のワークスペースコントロールパネルを非表示にすることで、サイトのデザインに馴染むシンプルな表示になります。

主要機能

マルチウィンドウと画像比較

Miradorの代表的な機能として、複数のマニフェストを並べて表示する画像比較があります。入力フォームで比較したい画像のマニフェストURLとCanvas URIを指定し、それぞれをMiradorのウィンドウとして同時に開くことで、異なる資料の視覚的な比較が可能です。

ウィンドウの設定で複数のマニフェストを同時に読み込む場合は、manifestパラメータにセミコロン区切りで複数のURLを指定します。

var manifests = vars["manifest"];
var array = manifests.split(";");
for (var i = 0; i < array.length; i++) {
  windows.push({
    manifestId: decodeURIComponent(array[i]),
    thumbnailNavigationPosition: "far-right",
  });
}

スクロールビュー（Scroll View）

スクロールビューは、複数のキャンバス（ページ画像）を縦や横に連結して表示するモードです。絵巻物や錦絵のように、複数の画像を繋げて鑑賞する用途に適しています。

Mirador 2ではデフォルトでScroll Viewが使用可能でしたが、Mirador 3ではデフォルトで無効化されています。有効にするには、初期設定のviewsにscrollを追加します。

const config = {
  id: "mirador",
  windows: [{
    manifestId: "./manifest.json",
  }],
  language: "ja",
  window: {
    defaultView: "scroll",
    views: [
      { key: "single" },
      { key: "gallery" },
      { key: "scroll" }
    ],
  },
};
Mirador.viewer(config);

views配列にscrollを追加すると、ビューア上部のビュー切り替えボタンにスクロール表示のオプションが現れます。defaultView: "scroll"を設定しておくと、初期表示時からスクロールビューで開きます。

なお、デフォルト表示を未指定のままスクロールビューに切り替えると表示が崩れるバグが報告されており、defaultViewの明示的な設定で回避できます。

ズーム操作

Miradorのズーム操作は内部的にOpenSeadragonを使用しています。特定の領域にズームするには、Mirador.actions.updateViewport（Mirador 3）またはinitialViewerConfig（Mirador 4）を使います。

// Mirador 3でのプログラム的なズーム
const boxToZoom = { x: 1420, y: 1831, width: 800, height: 1195 };
const zoomCenter = {
  x: boxToZoom.x + boxToZoom.width / 2,
  y: boxToZoom.y + boxToZoom.height / 2,
};
var action = Mirador.actions.updateViewport(windowId, {
  x: zoomCenter.x,
  y: zoomCenter.y,
  zoom: 1 / boxToZoom.width,
});
miradorInstance.store.dispatch(action);

ズーム時にOpenSeadragonの制約（constraints）を超えて拡大してしまう問題がある場合、viewport.applyConstraints()を追加することで回避できます。

Mirador 3からMirador 4への移行ポイント

Mirador 4はまだalpha版ですが、いくつかの重要な変更点があります。

initialViewerConfigの導入

Mirador 4では、ウィンドウの初期表示状態をより直接的に制御できるinitialViewerConfigが導入されました。キャンバスの指定、ズームレベル、回転角度などを初期化時に設定できます。

const config = {
  id: 'mirador',
  windows: [{
    canvasId: 'https://example.org/canvas/p2',
    initialViewerConfig: {
      rotation: 180,
      x: zoomCenter.x,
      y: zoomCenter.y,
      zoom: 1 / Math.max(boxToZoom.width, boxToZoom.height),
    },
    manifestId: 'https://example.org/manifest',
  }],
};

Mirador 3では初期ロード時に回転を指定する公式な方法が限られていましたが、Mirador 4のこの機能によりContent State APIへの対応も容易になります。

アクション関数へのアクセス方法の変更

Mirador 3ではMirador.actions.updateViewportのようにactionsオブジェクト経由でアクション関数にアクセスしていましたが、Mirador 4のUMDビルドではMirador.actionsがundefinedになる場合があります。代わりにMirador.receiveSearchやMirador.addCompanionWindowのように、関数に直接アクセスします。

// Mirador 4でのアクション関数アクセス
const receiveSearch = Mirador.receiveSearch;
const addCompanionWindow = Mirador.addCompanionWindow;

回転アニメーションの制御

Mirador 4でinitialViewerConfigにrotationを指定すると、初期ロード時にアニメーションが発生する場合があります。これはviewport.setRotationの内部実装にimmediatelyフラグが渡されていないことが原因です。即座に回転を適用したい場合は、OpenSeadragonViewerのソースコードでimmediately: trueを追加する必要があります。

外部からのマニフェスト読み込みと制御

外部マニフェストのウィンドウタイトル制御

他機関が公開するマニフェストを読み込んで表示する際、ウィンドウのタイトルにはマニフェストのlabelがそのまま表示されます。自プロジェクト独自の名称で表示したい場合、マニフェストのデータ自体を改変せずに、Miradorが描画したDOMのウィンドウタイトル部分だけを差し替えるアプローチが推奨されます。

具体的には、Mirador 4のウィンドウ上部バーにあるh2要素だけを対象にMutationObserverで監視・差し替えを行います。

container
  .querySelectorAll(".mirador-window-top-bar h2")
  .forEach(function (h2) {
    if (h2.textContent.trim() === originalLabel) {
      h2.textContent = customTitle;
    }
  });

store.subscribeでReduxストアの変更を監視し、MutationObserverでReactの再描画に追従することで、ウィンドウタイトルの差し替えを維持します。この方法であればマニフェストJSONは一切変更されず、情報パネルのメタデータ表示も元のlabelのままです。

キャンバス指定と検索語ハイライト

Mirador 4ではdefaultSearchQueryオプションにより初期化時に自動検索を実行できますが、指定キャンバスを表示しながらハイライトも表示したい場合は、receiveSearchアクションを直接使用するアプローチが効果的です。

Search APIを直接呼び出して指定キャンバスのヒットを取得
IIIF Search API形式のレスポンスを構築
addCompanionWindowで検索パネルを追加
receiveSearchで検索結果をMiradorに登録

この方法により、キャンバスの初期表示を維持しながらMiradorの標準的な検索ハイライト機能を活用できます。

任意領域のハイライト表示

IIIF Search APIに非対応のマニフェストでも、receiveSearchアクションを活用すれば任意の領域をハイライト表示できます。OCRで抽出したテキスト領域や、機械学習で検出したオブジェクトの領域などを可視化する際に有用です。

必要な情報はキャンバスURI、座標（xywh形式）、関連テキストの3つだけです。これらをIIIF Search API形式のJSONに構築し、store.dispatchで登録します。store.subscribeでマニフェストの読み込み完了を検知してからハイライトを追加することで、タイミングの問題を回避できます。

表示方向の制御

日本語の縦書き書籍のように右から左へページをめくる資料を表示する場合、viewingDirectionの設定が重要になります。

const miradorConfig = {
  id: "viewer",
  windows: [{
    loadedManifest: manifestUrl,
    viewingDirection: viewingDirection,
  }],
};

URLパラメータから動的に表示方向を指定することも可能です。

const urlParams = new URLSearchParams(window.location.search);
const viewingDirection = urlParams.get('viewingDirection') || 'right-to-left';

指定可能な値は以下の4つです。

left-to-right: 左から右へ（欧文書籍など）
right-to-left: 右から左へ（和書、アラビア語書籍など）
top-to-bottom: 上から下へ（巻物など）
bottom-to-top: 下から上へ

注意点として、マニフェストファイル内でviewingDirectionが指定されている場合はマニフェストの設定が優先されます。この外部制御は主にマニフェスト内で表示方向が未指定の場合に有効です。

よくあるトラブルと対処法

Presentation API v2のマニフェストが表示できない

Mirador 3でv2マニフェストを読み込んだ際、「A IIIF v3 localized property value must have an array as the value for a given language.」というエラーが出ることがあります。

これは、Canvasのlabelがオブジェクト形式で記述されている場合に発生します。

// エラーが出る記述
"label": {
  "type": "literal",
  "property_id": 1,
  "@value": "0001-01"
}

// 正しい記述
"label": "0001-01"

Mirador内部のパーサーがv2のつもりでv3として解釈してしまうことが原因です。labelを単純な文字列にすることで解消できます。Omeka SのIIIF Serverモジュールの特定バージョンでこの形式が出力されることが報告されており、モジュールの更新で解決する場合もあります。

テーマとカスタマイズ

Miradorはlightとdarkの2つのテーマを標準で提供しています。selectedThemeで指定するほか、カスタムテーマを定義することも可能です。

Mirador.viewer({
  selectedTheme: 'custom',
  themes: {
    custom: {
      palette: {
        type: 'dark',
        primary: {
          main: '#80104E',
        },
      },
    },
  },
});

Scroll Viewの表示崩れ

Mirador 3でScroll Viewに切り替えた際に表示がうまく切り替わらない場合、defaultView: "scroll"を初期設定で指定しておくことで回避できます。

まとめ

Miradorは高機能なIIIFビューアであり、CDNからの簡単な導入から、Reduxストアを活用した高度なカスタマイズまで幅広い利用形態に対応しています。マルチウィンドウ表示、スクロールビュー、ズーム・回転制御、検索ハイライトなど、デジタルアーカイブの閲覧に必要な機能が揃っています。Mirador 4ではinitialViewerConfigの導入により初期表示制御が容易になるなど、着実に進化を続けています。次章ではMiradorのプラグインによる機能拡張について学んでいきます。

Miradorの概要#

バージョンの歴史#

インストールと基本セットアップ#

CDN経由での利用#

npm経由でのインストール#

iframe埋め込み#

主要機能#

マルチウィンドウと画像比較#

スクロールビュー（Scroll View）#

ズーム操作#

Mirador 3からMirador 4への移行ポイント#

initialViewerConfigの導入#

アクション関数へのアクセス方法の変更#

回転アニメーションの制御#

外部からのマニフェスト読み込みと制御#

外部マニフェストのウィンドウタイトル制御#

キャンバス指定と検索語ハイライト#

任意領域のハイライト表示#

表示方向の制御#

よくあるトラブルと対処法#

Presentation API v2のマニフェストが表示できない#

テーマとカスタマイズ#

Scroll Viewの表示崩れ#

まとめ#