MatchTemplate 仕様｜eDocArrangement2

MatchTemplateはコンソールアプリケーションです。コンソールアプリケーションは、eDocArrangementのコマンド実行から呼び出すことが可能です。

テンプレート画像が被探索画像に含まれるかマッチングを行い、最も類似度の高い結果を1つ出力します。

テンプレート画像を複数指定すると、指定されたテンプレート画像の中で最も類似度の高い結果を1つ出力します。 (帳票判別などに利用できます)

被探索画像とテンプレート画像は、以下のようなイメージで用意します。

被探索画像

テンプレート画像

使用方法

書式

matchTemplate.exe -t テンプレート画像ファイル名 -tl テンプレート画像リストファイル名 -s 被探索画像ファイル名 [-u 長さの単位] [-d 区切り文字] [-p ページNo] [-ds マッチしたとみなす類似度] [-tcm 最大スレッド数] [-rtf] [-z 結果ファイル名] [-zmf] [-ec]

「name 1.txt」のように値にスペースが含まれる場合は、"name 1.txt" のようにダブルクォートで括ってください。

[]は省略可能な引数です。引数の仕様は以下の通りです。

-t テンプレート画像ファイル名	テンプレート画像ファイルを指定します。指定可能なファイル形式はJPEG,PNG,BMP,TIFF,GIFです。テンプレート画像ファイルを複数指定する時は、以下のように -t テンプレート画像ファイル名の組み合わせで複数指定します。 -t テンプレート画像ファイル名1 -t テンプレート画像ファイル名2 -t テンプレート画像ファイル名3 ...
-tl テンプレート画像リストファイル名	テンプレート画像ファイル名を1行1ファイル名で記述したファイルを指定します。 -tlを指定した場合は、-tで指定したテンプレート画像ファイル名は無視されます。テンプレート画像リストファイルの例 C:\template\請求書.tif C:\template\納品書.tif
-s 被探索画像ファイル名	被探索画像ファイルを指定します。指定可能なファイル形式はJPEG,PNG,BMP,TIFF,GIFです。
-u 長さの単位	マッチング結果の座標の長さの単位を指定します。指定できる長さの単位はpixel,mm,inchです。 -uを指定しない時のデフォルト値はpixelです。
-d 区切り文字	マッチング結果の値の区切り文字を指定します。指定できる区切り文字はcomma,tab,spaceです。 -dを指定しない時のデフォルト値はcommaです。
-p ページNo	マッチングを行う被探索画像のページNoを指定します。カンマ区切りで複数指定できます。被探索画像がマルチページ対応フォーマットの時に有効です。 -pを指定しない時は全てのページに対してマッチングを行います。
-ds マッチしたとみなす類似度	類似度が指定された値以上の時にマッチング処理を終了します。 -dsを指定しない時は、全てのテンプレート画像ファイルのマッチングを行い、最も類似度が高いマッチング結果を出力します。
-tcm 最大スレッド数	マッチングを並列処理するスレッド数の上限を指定します。1以上の数値を指定します。テンプレート画像を複数指定した時に有効です。 -tcmを指定しない時のデフォルト値: 8
-rtf	マッチング結果のテンプレート画像ファイル名のインデックスをテンプレート画像ファイル名に置き換えます。テンプレート画像ファイル名はフォルダーを取り除いたファイル名となります。テンプレート画像を複数指定した時に有効です。 -rtfを指定しない時は、結果のテンプレート画像ファイルを表す値はインデックスとなります。
-z 結果ファイル名	処理結果をファイルに出力します。結果ファイルが存在していた時は上書きします。
-zmf	処理結果を出力するフォルダーが存在しない時に、フォルダーを作成します。
-ec	結果ファイルに出力される終了コードと、エラーメッセージの一覧を出力します。

マッチング結果

指定したテンプレート画像ファイル名の数で出力結果が異なります。

テンプレート画像ファイル名を1つ指定した時

類似度, X座標, Y座標, 幅, 高さの5つの値を出力します。値の区切り文字は、カンマ(comma)もしくは、指定された区切り文字となります。

テンプレート画像ファイル名を2つ以上指定した時

テンプレート画像ファイル名のインデックス, 類似度, X座標, Y座標, 幅, 高さの6つの値を出力します。値の区切り文字は、カンマ(comma)もしくは、指定された区切り文字となります。

指定された複数のテンプレート画像のマッチング結果の中で最も高い類似度のマッチング結果を出力します。
テンプレート画像ファイル名のインデックスは、引数に指定した複数のテンプレート画像ファイル名の順番(1から始まる数値)です。
-rtfを指定した時は、テンプレート画像ファイル名のインデックスはテンプレート画像ファイル名に置き換わります。

被探索画像がマルチページ対応フォーマットの時は、1ページにつき1つの結果を出力します。

ページNoを指定した時は、指定したページのみマッチングを行います。

マッチしたとみなせる類似度は、おおよそ0.7～0.8以上です。

判定の際の類似度の閾値は、扱う画像の状態で異なります。運用に際しては、実際に使用するテンプレート画像にて複数回テストを行い、閾値の確認・調整を行ってください。

使用例

例1

テンプレート画像ファイルtemplate.jpgが、被探索画像search.jpgに含まれるかマッチングを行い、長さの単位をmmで結果ファイルresult.txtに出力。

matchTemplate.exe -t template.jpg -s search.jpg -u mm -z result.txt

result.txtの内容の例

0
0.8271,138.25,52.4,40,30

※ 1行目の数値は終了コード。0 は正常終了。

例2

テンプレート画像ファイルtemplate1.jpgとtemplate2.jpgが被探索画像search.jpgに含まれるかマッチングを行い、長さの単位をmmで最も類似度の高いマッチング結果を結果ファイルresult.txtに出力。

matchTemplate.exe -t template1.jpg -t template2.jpg -s search.jpg -u mm -z result.txt

result.txtの内容の例

0
2,0.8926,143.68,50.19,40,30

※ 1行目の数値は終了コード。0 は正常終了。

例3

テンプレート画像ファイルtemplate.tifがマルチページの被探索画像search.tifの1ページ目と2ページ目に含まれるかマッチングを行い、長さの単位をmmで結果ファイルresult.txtに出力。

matchTemplate.exe -t template.tif -s search.tif -u mm -p 1,2 -z result.txt

result.txtの内容の例

0
0.8271,138.25,52.04,40,30
0.8926,143.68,50.19,40,30

※ 1行目の数値は終了コード。0 は正常終了。

例4

テンプレート画像リストファイルtemplateList.txtに記述されたテンプレート画像ファイルが被探索画像search.tifに含まれるかマッチングを行い、長さの単位をmmで、マッチング結果のテンプレート画像ファイル名のインデックスをテンプレート画像ファイル名にして、結果ファイルresult.txtに出力。

matchTemplate.exe -tl templateList.txt -s search.tif -u mm -rtf -z result.txt

templateList.txtの内容の例

C:\template\請求書.tif
C:\template\納品書.tif

result.txtの内容の例

0
請求書.tif,0.8926,143.68,50.19,40,30

※ 1行目の数値は終了コード。0 は正常終了。

終了コード

終了コードは以下の通りです。

0	正常終了
1	対象外のスイッチが指定されています。 'スイッチ'
2	テンプレート画像ファイル名を指定してください。
3	テンプレート画像ファイルが存在しません。 'テンプレート画像ファイル名'
4	テンプレート画像リストファイル名を指定してください。
5	テンプレート画像リストファイルが存在しません。 'テンプレート画像リストファイル名'
6	被探索画像ファイル名を指定してください。
7	被探索画像ファイルが存在しません。 '被探索画像ファイル名'
8	結果ファイル名を指定してください。
9	処理結果を出力するフォルダーが存在しません。 '結果ファイル名'
10	長さの単位は pixel, mm, inch の何れかを指定してください。 '長さの単位'
11	区切り文字は comma, tab, space の何れかを指定してください。 '区切り文字'
12	ページNoは数値を指定してください。 'ページNo'
13	マッチしたとみなす類似度は0～1の範囲の数値を指定してください。 'マッチしたとみなす類似度'
14	最大スレッド数は1以上の数値を指定してください。 '最大スレッド数'
15	読み込みリトライ回数を超えました。指定されたテンプレート画像ファイルは読み込めませんでした。 'テンプレート画像ファイル名'
16	指定されたテンプレート画像ファイルは画像として認識できません。 (対応していない画像フォーマット、画像ファイルではない、画像ファイルが壊れている、など) 'テンプレート画像ファイル名'
17	テンプレート画像の解像度の取得に失敗しました。
18	読み込みリトライ回数を超えました。指定された被探索画像ファイルは読み込めませんでした。 '被探索画像ファイル名'
19	指定された被探索画像ファイルは画像として認識できません。 (対応していない画像フォーマット、画像ファイルではない、画像ファイルが壊れている、など) '被探索画像ファイル名'
20	被探索画像の解像度の取得に失敗しました。
21	テンプレートマッチング処理に必要なメモリーを確保する事ができません。
99	例外が発生しました。 'エラーメッセージ'

注意事項

テンプレートマッチングは「ある座標に○○%似ている領域が存在する」と言う結果を出力するものです。「テンプレート画像が存在するかしないか」は判定しません。
「テンプレート画像が存在するかしないか」の判定は、類似度の閾値を設定して、類似度が閾値以上なら存在する、類似度が閾値を下回ったら存在しない。と言った判定となります。
長さの単位がpixel以外の時は、被探索画像の解像度を元に単位変換を行います。
テンプレート画像と被探索画像のピクセルフォーマット(色深度や透過情報など)が異なる時は、テンプレート画像のピクセルフォーマットを被探索画像のピクセルフォーマットに変換してからマッチング処理を行います。テンプレート画像のサイズ(ピクセル数)が大きい程、変換処理時間が長くなります。
テンプレート画像と被探索画像のDPIが異なる時は、被探索画像のDPIを基準にテンプレート画像をリサイズしてからマッチング処理を行います。テンプレート画像のサイズ(ピクセル数)が大きい程、リサイズ処理時間が長くなります。
テンプレート画像と被探索画像のサイズ(ピクセル数)が大きい程、マッチング処理時間が長くなります。マッチングの精度と処理時間のバランスが取れた画像サイズに調整してください。

ライセンスについて

MatchTemplateは、eDocArrangementの購入者にライセンスされます。試用については、eDocArrangementと同じ期間、試用できます。

動作に必要なライブラリー

.NET Framework 4.6.2 以降

Visual Studio 2017 の Microsoft Visual C++ 再頒布可能パッケージ (x86)

使用しているオープンソースライブラリー

OpenCvSharp 4.5.2 を使用しています。

更新履歴

2023/12/19 Version 1.2.2

対象外のスイッチを指定した時にエラーとなるように修正。
可変引数のスイッチの引数に対象外のスイッチが含まれていた時はエラーにしないように修正。

2021/06/23 Version 1.2.1

OpenCvSharpを 4.2.0 から 4.5.2 に更新。
.NET Frameworkを 4.6 から 4.6.2 に変更。

2020/07/29 Version 1.2.0

テンプレート画像ファイル名を1行1ファイル名で記述した、テンプレート画像リストファイル名を指定できる機能を追加。
テンプレート画像ファイルを複数指定した時の結果に含まれる「テンプレート画像ファイルのインデックス」を、テンプレート画像ファイル名に置き換える機能を追加。
マッチング処理中にメモリー確保に失敗した時、自動的に最大スレッド数を減らした後、メモリー確保に失敗したマッチング処理をリトライするよう変更。

2020/07/06 Version 1.1.3

テンプレート画像と被探索画像のピクセルフォーマット(色深度や透過情報など)が異なる時に、マッチング結果が 0 とだけ出力され、類似度や座標が出力されない事がある問題を修正。
テンプレート画像と被探索画像のピクセルフォーマット(色深度や透過情報など)が異なる時は、テンプレート画像のピクセルフォーマットを被探索画像のピクセルフォーマットに変換してからマッチング処理を行うよう変更。(前項の問題の対応)

2020/01/08 Version 1.1.2

OpenCvSharpを 4.1.1 から 4.2.0 に更新。

2019/10/30 Version 1.1.1

OpenCvSharpを 4.1.0 から 4.1.1 に更新。

2019/07/05 Version 1.1.0

テンプレート画像ファイルを複数指定できるよう変更。
スレッドを使用してマッチング処理を並列で実行するよう変更。
テンプレート画像と被探索画像のDPIが異なる時は、被探索画像のDPIを基準にテンプレート画像をリサイズしてからマッチング処理を行うよう変更。
OpenCvSharpを 4.0.0 から 4.1.0 に更新。
.NET Frameworkを 4.6.1 から 4.6 に変更。Windows 10などのOSであれば、.NET Frameworkを別途インストールする事無く使用できるようになりました。

2019/02/20 Version 1.0.0

新規リリース。