vdiff.js

“vdiff.js”は、ウェブページ埋め込み型の画像比較ツールである。

本ツールは、射影変換機能を備え、画像内で比較したい対象の配置の違いを軽減して比較できる点に独自性があり、2枚の類似した画像の比較から変化を調べる目的に適している。

類似画像の違い探し、古写真と現代写真の今昔比較、災害写真のビフォー／アフター比較など、画像を用いたストーリーテリングのツールとしても幅広く活用できる。例えば、武鑑全集では同一出版物の異なる版の画像比較、メモリーグラフでは同一地点を同一構図で撮影した写真比較に、本ツールを活用している。

また、“vdiff.js editor”は、画像比較に用いる対応点の修正ツールである。

vdiff.jsにおける重ね合わせ結果が満足できない場合、対応点を修正する機能を提供する。

この文書は、vdiff.jsについて記述する。その他の情報については、以下の別資料を参照のこと。

vdiff.js editor：画像比較修正ツールに関する情報

動作デモ／活用例

動作デモ（シンプル版・開発者向け）

動作デモ（解説あり・一般向け）

局所強調比較モード
- 差読のための画像照合サービス
全体変化比較モード
- ビフォーアフター比較（今昔写真）のための画像照合サービス

活用例

局所強調比較モード
- 武鑑全集差読（Differential Reading）プラットフォーム
- 源氏百人一首（パタパタ顔比較）(東京大学総合図書館)
全体変化比較モード

使い方

本ツールは、「局所強調比較モード」または「全体変化比較モード」のいずれかの状態で表示される。

局所強調比較モードは、局所的な差異を強調する機能によって、差異に気付きやすくする効果を備えており、武鑑全集のように版間変化を比較するアプリケーションに適している。

全体変化比較モードは、全体的な変化の雰囲気に注目する効果を備えており、メモリーグラフのように時間変化を比較するアプリケーションに適している。

各モードでは、それぞれ数種類の画像比較手法が提供され、アイコンボタンまたは画像上を右クリックして表示されるアイコンメニューにより、適宜選択できる。

また、埋め込み時の設定に応じて、各種機能を提供するアイコンボタンが表示される。

これらアイコンボタンは、設定に応じて、画像の上部または下部に表示される。

また、画像に関するラベル（画像のタイトル／キャプション）が、設定に応じて、画像の上部または下部に表示される。ラベルには、比較モードおよび画像に応じたカラーチップ（後述）が付加される。

局所強調比較モード

差異が存在する箇所の把握に適した、4種類の比較手法が選択できる。

左右表示

画像上に表示される分割線を左右にドラッグすることにより、出版物における「あおり校正」のように、能動的に差異を探索する比較手法である。

強調チェックボックスがチェックされているとき、強調表示（後述）に基づくハイライト表示が重畳され、注目箇所が示唆される。このとき、ハイライト箇所にマウスカーソルを重ねると、マウスカーソルの周囲ではハイライト表示が解除され、資料の元の状態を確認できる。

強調表示

画像間の差分を取捨した結果をハイライト表示することで、静的に差異の概要を把握する比較手法である。

画像間の差分から、撮影条件の違い等に起因するもの（ノイズ）を除去し、撮影対象の本来の差異を強調することを目的としている。

ただし、ノイズ除去に伴い本来の差異も除去されてしまうケースや、ノイズ除去が不十分となるケースもあるため、他の比較手法（赤青表示など）と併せて利用されたい。

ハイライト表示は、以下の配色となる。

設定により、画像1が左側、画像2が右側に表示されている場合（後述）
- どちらの画像も白地に黒文字であるとき
  - 左画像（画像1）にはあって右画像（画像2）にはない文字部分：青色のハイライト
  - 右画像（画像2）にはあって左画像（画像1）にはない文字部分：赤色のハイライト
- どちらの画像も黒地に白文字であるとき
  - 左画像（画像1）にはあって右画像（画像2）にはない文字部分：赤色のハイライト
  - 右画像（画像2）にはあって左画像（画像1）にはない文字部分：青色のハイライト
設定により、画像1が右側、画像2が左側に表示されている場合（後述）
- どちらの画像も白地に黒文字であるとき
  - 右画像（画像1）にはあって左画像（画像2）にはない文字部分：青色のハイライト
  - 左画像（画像2）にはあって右画像（画像1）にはない文字部分：赤色のハイライト
- どちらの画像も黒地に白文字であるとき
  - 右画像（画像1）にはあって左画像（画像2）にはない文字部分：赤色のハイライト
  - 左画像（画像2）にはあって右画像（画像1）にはない文字部分：青色のハイライト

これらのとき、画像に関するラベルのカラーチップにこれらの配色が反映される。

赤青表示

差異箇所を赤色・青色で表示することで、静的に差異の詳細を検討する比較手法である。

画像間の差分について、可能な限り差異情報を失わずに提示することを目的としている。

前述の強調表示とは異なりノイズ除去を行わないため、本来の差異が除去されてしまうおそれは少ないが、差異の概要を把握する目的には最適ではないため、他の比較手法（強調表示など）と併せて利用されたい。

赤色・青色の配色は、強調表示におけるハイライト表示と同様である。

並列表示

射影変換後の画像を左右に並べて表示することで、左右に視線を往復させながら画像の差異を検討する比較手法である。

全体変化比較モード

変化の雰囲気の把握に適した、3種類の比較手法が選択できる。

左右表示

画像上に表示される分割線を左右にドラッグすることにより、画像の鮮明さを保ちつつ能動的に画像の変化を把握する比較手法である。

透明表示

重ね合わせ透明度スライダを変更することにより、2枚の画像を半透明で重ね合わせ表示しつつ画像の変化を把握する比較手法である。

並列表示

射影変換後の画像を左右に並べて表示することで、左右に視線を往復させながら画像の変化を把握する比較手法である。

アノテーション

vdiff.js v1.5からは、アノテーションの表示と付与に対応している。

埋め込み時にアノテーション付与機能を無効にしている場合（未設定の場合も含む）、アノテーションの表示機能のみが提供される。

埋め込み時にアノテーション付与機能を有効にしている場合、アノテーション付与機能が提供され、アノテーション領域の作成・移動・リサイズ・削除や、アノテーションに記述された情報の追加・編集・削除を行うことができる。

アノテーション表示

アノテーション表示機能のみが提供されている場合、表示中の画像比較にアノテーションが含まれていれば、「アノテーション表示／非表示を切り替え」アイコンボタン（トグルボタン）が表示される。同ボタンは、左右表示時および並列表示時は無効となり、アノテーション表示は行われない。

「アノテーション表示／非表示を切り替え」アイコンボタンが有効かつオンになっているとき、アノテーション領域へのマウスオーバーにより、アノテーションに記述された情報がツールチップ表示される。また、アノテーション領域のクリックにより、アノテーションに記述された情報がポップアップ表示される。アノテーション記述中にハイパーリンクが含まれる場合、ポップアップからアクセスすることができる。

アノテーション付与

アノテーション付与機能が提供されている場合、「アノテーション表示／非表示を切り替え」アイコンボタン（トグルボタン）および「アノテーションを保存」アイコンボタンが表示される。前者のボタンは、左右表示時および並列表示時は無効となり、アノテーション表示や付与は行われない。また、後者のボタンの挙動は、埋め込み先サイトの実装依存であるが、付与・編集したアノテーション情報のデータベース等への保存等が行われることを想定している。

「アノテーション表示／非表示を切り替え」アイコンボタンが有効かつオンになっているとき、画像上のマウスドラッグにより、アノテーション領域の作成・移動・リサイズや、アノテーションに記述する情報の追加を行うことができる。また、表示中の画像比較にアノテーションが含まれていれば、アノテーション領域のクリックにより、アノテーション領域の移動・リサイズ・削除や、アノテーションに記述された情報の追加・編集・削除を行うことができる。

埋め込み時の設定

注意点

埋め込みの順序

JavaScriptファイルの読み込みと本ツールのインスタンス化は、以下の順序で行うこと。

本ツールのJavaScriptファイル読み込み
本ツールのインスタンス化
OpenCV.jsのJavaScriptファイル読み込み

設定

VDiff(config)

configは次に挙げるプロパティを持ったオブジェクト

項目名	型	説明
`id`	String	（必須）本ツールの埋め込み先となる`<div>`のIDを指定する。
`data`	Object	対象画像に関する情報を指定する（後述）。埋め込み時に本項目が未設定である場合、埋め込み先ページURLに対するGETパラメータ指定により、本項目で指定可能な項目を設定できる。
`size`	Object	画像サイズ・画像表示サイズの制限値を指定する（後述）。
`editorUrl`	String	画像比較修正ツールvdiff.js editorのURLを指定する。本項目が設定されている場合、「画像比較を修正」アイコンボタン（画像比較修正ツールへのリンク）が表示される。ただし、画像比較中にアノテーションが含まれる可能性がある場合、リンク遷移により情報の欠落が生じるおそれがあるため、本項目の設定によりリンク遷移を行うことは推奨しない。
`layout`	Number	アイコンボタンやラベル表示のレイアウトパターン番号を指定する。 `1`：上部にアイコンボタン、下部にラベル `2`：上部にラベル、下部にアイコンボタン `3`：上部にアイコンボタンとラベル `4`：下部にラベルとアイコンボタン画像比較結果を他者に見せることが主たる目的である場合や、比較検討作業を自ら行うことが主たる目的である場合など、本ツール利用の目的に応じて、望ましいレイアウトを選択できる。
`method`	Number	初期選択される画像比較手法を指定する。局所強調比較モード `1`：左右表示 `2`：強調表示 `3`：赤青表示 `4`：並列表示全体変化比較モード `1`：左右表示 `2`：透明表示 `3`：並列表示未設定または範囲外の場合は、局所強調比較モードでは強調表示、全体変化比較モードでは左右表示が初期選択となる。
`enableAnnotator`	Boolean	アノテーション機能を指定する。未指定または`false`の場合はアノテーション表示機能のみが提供され、`true`の場合はアノテーション付与機能が提供される。
`lang`	String	表示言語を指定する。日本語表示は'ja'、英語表示は'en'を指定する。
`doneCallback`	Function	正常完了時のコールバックを指定する。
`failCallback`	Function	異常終了時のコールバックを指定する。
`alwaysCallback`	Function	正常完了時・異常終了時のコールバックを指定する。

dataは次に挙げるプロパティを持ったオブジェクト

項目名	型	説明
`img1`	String	（必須）画像1のURLを指定する。
`img2`	String	（必須）画像2のURLを指定する。
`img1_label`	String	画像1のラベルを指定する。
`img2_label`	String	画像2のラベルを指定する。
`corr_pts`	Object\|String	対応点情報（画像1と画像2の対応点、画像サイズの情報を含むオブジェクト）、または、対応点指示文字列を指定する。対応点情報に含める対応点は、4組必要。詳細は設定例（後述）参照。 `corr_pts`に対応点情報が適切に与えられている場合、その対応点情報に基づいて射影変換行列を求め、射影変換が行われる。 `corr_pts`に対応点指示文字列`'corners'`が指定されている場合、画像1および画像2の四隅を対応点として扱い、射影変換が行われる。上記以外の場合（`corr_pts`が未指定の場合を含む）、`img1_roi_xywh`（`img1_roi_xywh`も未指定の場合は画像全体）を対象として、ブラウザ上で特徴量抽出と対応点決定を行い、射影変換が行われる。
`img1_roi_xywh`	String	関心領域（画像1のうち、画像2と比較したい矩形領域）を指定する。記載例： `'160,120,320,240'` `'pixel:160,120,320,240'` `'percent:25,25,50,50'` `'pct:25.2,25.2,50.5,50.7'` パーセント指定時は、画像1のサイズに対する指定となる。「pixel:」「percent:」による指定は、W3C Media Fragments URI仕様に従い、整数値を受け付ける。「pct:」による指定は、IIIF Image API仕様を参考とし、正の浮動小数点数または整数を受け付ける。
`annotations`	Array	アノテーションの配列を指定する。アノテーションは、W3C Web Annotationモデルに準拠した、「Annotorious」が対応する範囲のものとする（詳細）。ただし、セレクタについては、Fragment Selectorのみ対応する。
`show_img1_right`	Boolean	画像表示位置を指定する。未指定または`false`の場合は画像1が本ツールで左側、画像2が本ツールで右側に表示され、`true`の場合は画像1が右側、画像2が左側に表示される。
`mode`	Boolean	比較モードを指定する。未指定または`false`の場合は局所強調比較モード、`true`の場合は全体変化比較モードとなる。

sizeは次に挙げるプロパティを持ったオブジェクト

画像サイズの制限値

項目名	型	説明
`max-size`	Number	画像処理上の最大サイズ（一辺の長さ）をピクセル値で指定する。対象画像の一辺の長さが指定値を超える大きさであった場合、指定の制限を満たすように縮小の上、画像処理（特徴量抽出と対応点決定）が行われる。ブラウザに表示される際の画像の大きさはCSS設定や画像表示サイズの制限値による。

画像表示サイズの制限値（次に挙げるプロパティのいずれか）

項目名	型	説明
`max-width`	Number	画像表示の最大幅をピクセル値で指定する。対象画像の幅が指定値を超える大きさであった場合、指定の制限を満たすように縮小して表示される。並列表示においては、当指定値の2倍が最大幅となる。
`max-height`	Number	画像表示の最大高さをピクセル値で指定する。対象画像の高さが指定値を超える大きさであった場合、指定の制限を満たすように縮小して表示される。

設定例

対象画像とラベル、対応点情報を指定した例

<link rel="stylesheet" href="vdiffjs/vdiff.bundle.css">
<script src="vdiffjs/vdiff.bundle.min.js"></script>
<div id="image01"></div>
<script>
  (function() {
    VDiff({
      id: 'image01',
      data: {
        img1: 'http://codh.rois.ac.jp/pmjt/iiif/200019661/200019661_00005.tif/full/pct:15/0/default.jpg',
        img2: 'http://codh.rois.ac.jp/pmjt/iiif/200019662/200019662_00004.tif/full/pct:15/0/default.jpg',
        img1_label: '昇栄武鑑（嘉永６）',
        img2_label: '昇栄武鑑（安政３）',
        corr_pts: {
          img1: {
            size: {w:5616, h:3744},
            pts: [{x:2817, y:1257}, {x:4800, y:1216}, {x:4812, y:2608}, {x:2828, y:2601}]
          },
          img2: {
            size: {w:5616, h:3744}, 
            pts: [{x:2840, y:1250}, {x:4815, y:1273}, {x:4785, y:2661}, {x:2811, y:2592}]
          }
        }
      }
    });
  })();
</script>
<script src="https://docs.opencv.org/4.5.1/opencv.js" async></script>

以下、JavaScript/CSSファイルの読み込み部分は例示を省略する。

対象画像と関心領域を指定した例

<div id="image02"></div>
<script>
  (function() {
    VDiff({
      id: 'image02',
      data: {
        img1: 'http://codh.rois.ac.jp/pmjt/iiif/200019661/200019661_00005.tif/full/pct:15/0/default.jpg',
        img2: 'http://codh.rois.ac.jp/pmjt/iiif/200019662/200019662_00004.tif/full/pct:15/0/default.jpg',
        img1_roi_xywh: 'percent:50,25,50,50'
      }
    });
  })();
</script>

対象画像は指定せず、GETパラメータによって指定されることを想定した例（この例では、画像表示幅を最大600ピクセルに制限している）

<div id="image03"></div>
<script>
  (function() {
    VDiff({
      id: 'image03',
      size: { 'max-width': 600 }
    });
  })();
</script>

API

メソッド	返り値	説明
`getParameters()`	Object	本ツールの内部状態を、`data`オブジェクト形式で返す。

制限仕様

本ツールでは、WebAssemblyを使用しており、WebAssemblyに未対応のブラウザ（Internet Explorerなど）では動作しない。

また、オリジン間リソース共有などセキュリティ上の制約により画像が取得できない場合は、動作対象外である。

ライセンス

vdiff.js - JavaScript-based visual differencing tool
http://codh.rois.ac.jp/software/vdiffjs/

Copyright 2021 Center for Open Data in the Humanities, Research Organization of Information and Systems
Released under the MIT license

Core contributor: Jun HOMMA (@2SC1815J)

Licenses of open source libraries, see acknowledgements.md

開発履歴

バージョン1.5 (2022-12-25)

Viewerの改良
- アノテーション表示機能を追加
- アノテーション付与機能を追加
Editorの改良
- 「対応点を削除」ボタンとその関連機能追加
Viewer/Editor共通の改良
- 埋め込み時オプションに表示言語指定を追加

バージョン1.4 (2022-03-24)

ラベルの表示方法を改良
ボタンとラベルの表示位置を制御するレイアウトパターン選択を追加

バージョン1.3 (2021-12-10)

Viewerの比較手法に「並列表示」を追加

バージョン1.2 (2021-11-11)

Viewerの改良
- 強調表示アルゴリズムの改善

バージョン1.1 (2021-11-08)

Viewer/Editor共通の改良
- 巨大な画像に対する処理の改善
Viewerの改良
- 比較結果の画像のダウンロード機能を追加
Editorの改良
- プレビュー部と対応点修正部の縦横レイアウト切り替え機能の追加
- 横レイアウト表示時、プレビュー部と対応点修正部の幅の比率をマウスドラッグにより調整できる機能を追加

バージョン1.0 (2021-06-25)

vdiff.jsを公開

目次

動作デモ／活用例

動作デモ（シンプル版・開発者向け）

動作デモ（解説あり・一般向け）

活用例

使い方

局所強調比較モード

左右表示

強調表示

赤青表示

並列表示

全体変化比較モード

左右表示

透明表示

並列表示

アノテーション

アノテーション表示

アノテーション付与

埋め込み時の設定

注意点

埋め込みの順序

設定

設定例

API

制限仕様

ライセンス

開発履歴

バージョン1.5 (2022-12-25)

バージョン1.4 (2022-03-24)

バージョン1.3 (2021-12-10)

バージョン1.2 (2021-11-11)

バージョン1.1 (2021-11-08)

バージョン1.0 (2021-06-25)