vdiff.js editor

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

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

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

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

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

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

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

動作デモ／活用例

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

局所強調比較モード
- vdiff.jsとvdiff.js editorを切り替えて利用するデモンストレーション
全体変化比較モード
- vdiff.jsとvdiff.js editorを切り替えて利用するデモンストレーション

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

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

使い方

本ツールは、「プレビュー」表示および「対応点を修正」表示からなる。

プレビュー

対象画像に対する射影変換の適用結果が半透明に重ね合わせて表示される。

射影変換に用いる対応点の情報は、呼び出し時に与えられた値が利用される。呼び出し時に指定がない場合には、画像比較ツールvdiff.jsと同様に射影変換行列の推定を試みる。

対応点を修正

対象画像がそれぞれ表示され、必要に応じて、ズームイン／ズームアウト、パン移動表示を行うことができる。

呼び出し時に与えられた対応点情報、または射影変換行列の推定結果に基づき、射影変換行列算出に必要な4組の対応点がそれぞれの対象画像表示上に示される。

それぞれの対象画像表示上に示された対応点（赤丸のマーカーで表示される）のドラッグ移動（またはマーカーを選択した状態で矢印キー押下）により、射影変換行列が更新され、プレビュー表示に即時反映される。

アイコンボタン

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

「対応点を四隅に設定」アイコンボタン押下によって、対応点をそれぞれの画像の四隅に配置した状態とすることができる。このとき、画像2全体が画像1全体に重ね合わされた状態となる。

「対応点を自動推定」アイコンボタン押下によって、射影変換行列の推定を試み、推定された射影変換行列に基づく対応点を配置した状態とすることができる。

「縦横レイアウト切り替え」アイコンボタン押下によって、プレビュー表示部と対応点修正部のレイアウトを変更できる。横レイアウト表示時（下図）は、両者の境界をドラッグすることにより、両者の幅の比率を調整できる。

埋め込み時の設定によっては、「対応点を保存」アイコンボタンが表示される。同ボタンの挙動は、埋め込み先サイトの実装依存であるが、修正後の対応点情報のデータベース等への保存、認証、画像比較ツールへの遷移等が行われることを想定している。

埋め込み時の設定によっては、「対応点を削除」アイコンボタンが表示される。同ボタンの挙動は、埋め込み先サイトの実装依存であるが、対応点情報のデータベース等からの削除、認証、画像比較ツールへの遷移等が行われることを想定している。

対応点情報出力機能

埋め込み時に画像比較ツールvdiff.jsのURLが与えられている場合、「画像比較ツールで確認」リンクにより、修正した対応点情報によるプレビューの状態を画像比較ツールで確認することができる。

また、本ツールが提供するAPI（後述）を利用して、本ツール外部から修正後の対応点情報を取得することも可能である。

埋め込み時の設定

注意点

`viewport`設定

モバイルブラウザでの動作を適切なものとするため、埋め込み先のページには、headセクション内に次のようなviewportの設定が必要である（参考）。

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />

埋め込みの順序

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

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

設定

VDiffEditor(config)

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

項目名	型	説明
`id`	String	（必須）本ツールの埋め込み先となる`<div>`のIDを指定する。
`data`	Object	対象画像に関する情報を指定する（後述）。埋め込み時に本項目が未設定である場合、埋め込み先ページURLに対するGETパラメータ指定により、本項目で指定可能な項目を設定できる。
`size`	Object	画像サイズの制限値を指定する（後述）。
`viewerUrl`	String	画像比較ツールvdiff.jsのURLを指定する。本項目が設定されている場合、射影変換パラメータを変更すると「画像比較ツールで確認」リンクが表示され、編集した射影変換パラメータを指定して画像比較ツールを呼び出すことができる。
`layout`	String	プレビュー表示部と対応点修正部のレイアウトについて、初期状態を指定する。縦レイアウト表示は`'vertical'`、横レイアウト表示は`'horizontal'`を指定する。
`showSaveParametersButton`	Boolean	対応点情報の保存ボタンを表示するか否かを指定する。 `true`の場合、本ツールの埋め込み先`id`に文字列`-save_param`を後置したIDを持つボタンが表示される。本機能はボタンの表示のみを行い、ボタン押下時の処理（対応点情報のデータベース等への保存、認証、画像比較ツールへの遷移等）は埋め込み先サイト側で実装することを想定している。
`showDeleteParametersButton`	Boolean	対応点情報の削除ボタンを表示するか否かを指定する。 `true`の場合、本ツールの埋め込み先`id`に文字列`-delete_param`を後置したIDを持つボタンが表示される。本機能はボタンの表示のみを行い、ボタン押下時の処理（対応点情報のデータベース等からの削除、認証、画像比較ツールへの遷移等）は埋め込み先サイト側で実装することを想定している。
`lang`	String	表示言語を指定する。日本語表示は'ja'、英語表示は'en'を指定する。
`doneCallback`	Function	正常完了時のコールバックを指定する。
`failCallback`	Function	異常終了時のコールバックを指定する。
`alwaysCallback`	Function	正常完了時・異常終了時のコールバックを指定する。

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

項目名	型	説明
`img1`	String	（必須）画像1のURLを指定する。
`img2`	String	（必須）画像2のURLを指定する。
`img1_label`	String	画像1のラベルを指定する。本ツール上の表示には影響しない^(*1)。
`img2_label`	String	画像2のラベルを指定する。本ツール上の表示には影響しない^(*1)。
`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仕様を参考とし、正の浮動小数点数または整数を受け付ける。
`show_img1_right`	Boolean	画像表示位置を指定する。未指定または`false`の場合は画像1が本ツールで左側、画像2が本ツールで右側に表示され、`true`の場合は画像1が右側、画像2が左側に表示される。
`mode`	Boolean	比較モードを指定する。本ツール上の表示には影響しない^(*1)。

*1：viewerUrl指定により、パラメータ編集結果を画像比較ツールvdiff.jsで開く際、画像比較ツールでの表示に反映される。

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

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

設定例

対象画像と対応点情報を指定した例

<link rel="stylesheet" href="vdiffjs/vdiff.bundle.css">
<script src="vdiffjs/vdiff.bundle.min.js"></script>
<div id="image01"></div>
<script>
  (function() {
    VDiffEditor({
      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',
        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>

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

目次