vision.TemplateMatcher

イメージ内でのテンプレートの検出

説明

イメージ内でテンプレートを検出します。

1. vision.TemplateMatcher オブジェクトを作成し、そのプロパティを設定します。

2. 関数と同様に、引数を指定してオブジェクトを呼び出します。

System object の機能の詳細については、System object とはを参照してください。

作成

構文

tMatcher = vision.TemplateMatcher

tMatcher = vision.TemplateMatcher(Name,Value)

説明

tMatcher = vision.TemplateMatcher はテンプレート マッチング オブジェクト tMatcher を返します。このオブジェクトは、イメージの内部全体でテンプレートを 1 ピクセルの増分でシフトして、テンプレートのマッチングを実行します。

tMatcher = vision.TemplateMatcher(Name,Value) は、名前と値のペアを 1 つ以上使用してプロパティを設定します。各プロパティ名を引用符で囲みます。たとえば、tMatcher = vision.TemplateMatcher('Metric','Sum of absolute differences') です。

プロパティ

特に指定がない限り、プロパティは "調整不可能" です。つまり、オブジェクトの呼び出し後に値を変更することはできません。オブジェクトは呼び出すとロックされ、ロックを解除するには関数 release を使用します。

プロパティが "調整可能" の場合、その値をいつでも変更できます。

プロパティ値の変更の詳細については、System object を使用した MATLAB でのシステム設計を参照してください。

Metric — テンプレート マッチングのソースに使用されるメトリクス

'Sum of absolute differences' (既定値) | 'Sum of squared differences' | 'Maximum absolute difference'

テンプレート マッチングのソースに使用されるメトリクス。'Sum of absolute differences'、'Sum of squared differences'、または 'Maximum absolute difference' として指定します。

OutputValue — 出力のタイプ

'Best match location' (既定値) | 'Metric matrix'

出力のタイプ。'Metric matrix' または 'Best match location' として指定します。

SearchMethod — 2 つの入力の最小差を求める検索条件の指定

'Exhaustive' (既定値) | 'Three-step'

2 つの入力の最小差を求める検索条件の指定。'Exhaustive' または 'Three-step' として指定します。このプロパティを 'Exhaustive' に設定すると、オブジェクトはピクセルごとに最小差を検索します。このプロパティを 'Three-step' に設定すると、オブジェクトは徐々に減少するステップ サイズを使用して最小差を検索します。'Three-step' メソッドは 'Exhaustive' メソッドより計算量が少なくなりますが、最適な解を求められない場合があります。このプロパティは、OutputValue プロパティを 'Best match location' に設定した場合に適用されます。

BestMatchNeighborhoodOutputPort — メトリクス値の出力の有効化

false (既定値) | true

メトリクス値の出力の有効化。true または false として指定します。このプロパティは、OutputValue プロパティを 'Best match location' に設定した場合に適用されます。

NeighborhoodSize — メトリクス値のサイズ

3 (既定値) | 奇数

メトリクス値のサイズ。奇数として指定します。メトリクス値の N 行 N 列の行列のサイズ N は奇数です。たとえば、行列のサイズが 3 行 3 列の場合、このプロパティを 3 に設定します。このプロパティは、OutputValue プロパティを 'Best match location' に、BestMatchNeighborhoodOutputPort プロパティを true に設定した場合に適用されます。

ROIInputPort — 入力による ROI 指定の有効化

false (既定値) | true

入力による ROI 指定を有効化します。true または false として指定します。このプロパティを true に設定すると、テンプレート マッチングを実行する関心領域 (ROI) を定義できます。このプロパティを true に設定する場合は、ROI を指定しなければなりません。そうでない場合、入力イメージ全体が使用されます。

ROIValidityOutputPort — ROI の任意の部分が入力イメージの外側にあるかどうかを示すフラグの出力の有効化

false (既定値) | true

ROI の任意の部分が入力イメージの外側にあるかどうかを示すフラグの出力を有効化します。true または false として指定します。このプロパティを true に設定すると、オブジェクトは ROI フラグを返します。このフラグは、false に設定されている場合、ROI の一部が入力イメージの外側にあることを示します。このプロパティは、ROIInputPort プロパティを true に設定した場合に適用されます。

固定小数点プロパティ

RoundingMethod — 固定小数点演算の丸め手法

'Floor' (既定値) | 'Ceiling' | 'Convergent' | 'Nearest' | 'Round' | 'Simplest' | 'Zero'

固定小数点演算の丸め手法。'Floor'、'Ceiling'、'Convergent'、'Nearest'、'Round'、'Simplest'、または 'Zero' として指定します。

OverflowAction — 整数入力が範囲外の場合に実行するアクション

'Wrap' (既定値) | 'Saturate'

整数入力が範囲外の場合に実行するアクション。'Wrap' または 'Saturate' として指定します。

ProductDataType — 積のデータ型

'Same as input' (既定値) | 'Custom'

積のデータ型。'Same as input' または 'Custom' として指定します。

CustomProductDataType — 乗算の語長と小数部の長さ

numerictype(true,32,30) (既定値) | スケーリングされた numerictype オブジェクト

乗算の語長と小数部の長さ。スケーリングされた numerictype (Fixed-Point Designer) オブジェクトとして指定します。このプロパティは、AccumulatorDataType プロパティを 'Custom' に設定した場合にのみ適用されます。

AccumulatorDataType — アキュムレータのデータ型

'Same as product' (既定値) | 'Same as input' | 'Custom'

アキュムレータのデータ型。'Same as product'、'Same as input'、または 'Custom' として指定します。

CustomAccumulatorDataType — アキュムレータの語長と小数部の長さ

numerictype(true,32,30) (既定値) | スケーリングされた numerictype オブジェクト

アキュムレータの語長と小数部の長さ。スケーリングされた numerictype (Fixed-Point Designer) オブジェクトとして指定します。このプロパティは、AccumulatorDataType プロパティを 'Custom' に設定した場合にのみ適用されます。

使用法

構文

location = tMatcher(I,T)

[location,numberOfValues,numValid] = tMatcher(I,T,ROI)

[location,numberOfValues,numValid,ROIvalid] = tMatcher(I,T,ROI)

[location,ROIvalid] = tMatcher(I,T,ROI)

説明

location = tMatcher(I,T) は、イメージの左上隅を基準とした、イメージ行列 I とテンプレート行列 T 間のテンプレート最適一致の [x y] 位置座標を返します。オブジェクトは、イメージの内部全体でテンプレートを 1 ピクセルの増分でシフトして、位置を計算します。

[location,numberOfValues,numValid] = tMatcher(I,T,ROI) は、テンプレート最適一致の位置 location、最適一致に近いメトリクス値 numberOfValues、および論理フラグ numValid を返します。これは、OutputValue プロパティを 'Best match location' に、BestMatchNeighborhoodOutputPort プロパティを true に設定した場合に適用されます。

[location,numberOfValues,numValid,ROIvalid] = tMatcher(I,T,ROI) は、ROI が入力イメージ I の境界の外側にあるかどうかを示す論理フラグ ROIvalid も返します。これは、OutputValue プロパティを 'Best match location' に設定し、BestMatchNeighborhoodOutputPort、ROIInputPort および ROIValidityOutputPort プロパティを true に設定した場合に適用されます。

[location,ROIvalid] = tMatcher(I,T,ROI) は、指定された ROI が入力イメージ I の境界の外側にあるかどうかを示す論理フラグ ROIvalid も返します。これは、OutputValue プロパティを 'Best match location' に設定し、ROIInputPort プロパティと ROIValidityOutputPort プロパティの両方を true に設定した場合に適用されます。

入力引数

I — 入力イメージ

トゥルーカラー | M 行 N 列の 2 次元グレースケール イメージ

入力イメージ。2 次元グレースケールまたはトゥルカラー イメージとして指定します。TemplateMatcher オブジェクトのパフォーマンスは、入力の種類によって異なります。たとえば、データ型 double の入力を使用すると、パフォーマンスが高速化する可能性があります。

T — テンプレート

バイナリ イメージ | トゥルーカラー | M 行 N 列の 2 次元グレースケール イメージ

入力テンプレート。2 次元グレースケールまたはトゥルーカラー イメージとして指定します。

ROI — 入力 ROI

4 要素のベクトル

入力 ROI。4 要素ベクトル [x y width height] として指定します。最初の 2 つの要素は四角形 ROI の左上隅の座標を表します。

出力引数

location — テンプレート最適一致の位置

ベクトル

テンプレート最適一致の位置。(x,y) 形式のベクトルとして返されます。座標は、イメージの左上隅を基準としたテンプレートの中心を示します。詳細については、アルゴリズムを参照してください。

numberOfValues — メトリクス値

行列

メトリクス値行列。行列として返されます。numValid の値が false の場合、最適一致の近傍がメトリクス値行列 numberOfValues の境界を超えていることを示します。

numValid — 有効な近傍

true | false

有効な近傍。true または false として返されます。numValid の値が false の場合、最適一致の近傍がメトリクス値行列 numberOfValues の境界を超えていることを示します。

ROIvalid — 有効な ROI

true | false

有効な ROI 近傍。true または false として返されます。ROIvalid の値が false の場合、ROI が入力イメージの境界の外側にあることを示します。

オブジェクト関数

オブジェクト関数を使用するには、System object™ を最初の入力引数として指定します。たとえば、obj という名前の System object のシステム リソースを解放するには、次の構文を使用します。

release(obj)

すべての System object に共通

step	System object のアルゴリズムの実行
release	リソースを解放し、System object のプロパティ値と入力特性の変更を可能にします。
reset	System object の内部状態のリセット

例

映像安定化

この例では、ビデオ ストリームからカメラの動きの影響を排除する方法を説明します。

はじめに

この例では、まず追跡のターゲットを定義します。今の場合は自動車の後面とナンバー プレートです。また、動的な探索領域を設定しますが、その位置は、最後の既知のターゲット位置によって決まります。この領域内のみでターゲットを探索しますが、これによって、ターゲットの特定に必要な計算量が減ります。後続の各ビデオ フレームで、前のフレームと比べてターゲットがどれだけ動いたかを判定します。この情報を使用して望ましくないカメラの並進を排除し、画面の安定したビデオを生成します。

初期化

マルチメディア ファイルからビデオを読み取る System object™ を作成します。出力を、強度のみのビデオになるように設定します。

% Input video file which needs to be stabilized.
filename = "shaky_car.avi";

hVideoSource = VideoReader(filename);

ビデオ フレーム内におけるターゲットの最適一致の位置を計算する、テンプレート マッチング用 System object を作成します。この位置を使用して、連続したビデオ フレーム間の平行移動を求めます。

hTM = vision.TemplateMatcher("ROIInputPort", true, ...
                            "BestMatchNeighborhoodOutputPort", true);

元のビデオと安定化したビデオを表示する System object を作成します。

hVideoOut = vision.VideoPlayer("Name", "Video Stabilization");
hVideoOut.Position(1) = round(0.4*hVideoOut.Position(1));
hVideoOut.Position(2) = round(1.5*(hVideoOut.Position(2)));
hVideoOut.Position(3:4) = [650 350];

ここで、処理ループで使用されるいくつかの変数を初期化します。

pos.template_orig = [109 100]; % [x y] upper left corner
pos.template_size = [22 18];   % [width height]
pos.search_border = [15 10];   % max horizontal and vertical displacement
pos.template_center = floor((pos.template_size-1)/2);
pos.template_center_pos = (pos.template_orig + pos.template_center - 1);
W = hVideoSource.Width; % Width in pixels
H = hVideoSource.Height; % Height in pixels
BorderCols = [1:pos.search_border(1)+4 W-pos.search_border(1)+4:W];
BorderRows = [1:pos.search_border(2)+4 H-pos.search_border(2)+4:H];
sz = [W, H];
TargetRowIndices = ...
  pos.template_orig(2)-1:pos.template_orig(2)+pos.template_size(2)-2;
TargetColIndices = ...
  pos.template_orig(1)-1:pos.template_orig(1)+pos.template_size(1)-2;
SearchRegion = pos.template_orig - pos.search_border - 1;
Offset = [0 0];
Target = zeros(18,22);
firstTime = true;

ストリーム処理ループ

以下は、上記でインスタンス化したオブジェクトを使用して入力ビデオを安定化する、メインの処理ループです。

while hasFrame(hVideoSource)
    input = im2gray(im2double(readFrame(hVideoSource)));

    % Find location of Target in the input video frame
    if firstTime
      Idx = int32(pos.template_center_pos);
      MotionVector = [0 0];
      firstTime = false;
    else
      IdxPrev = Idx;

      ROI = [SearchRegion, pos.template_size+2*pos.search_border];
      Idx = hTM(input,Target,ROI);

      MotionVector = double(Idx-IdxPrev);
    end

    [Offset, SearchRegion] = updatesearch(sz, MotionVector, ...
        SearchRegion, Offset, pos);

    % Translate video frame to offset the camera motion
    Stabilized = imtranslate(input, Offset, "linear");

    Target = Stabilized(TargetRowIndices, TargetColIndices);

    % Add black border for display
    Stabilized(:, BorderCols) = 0;
    Stabilized(BorderRows, :) = 0;

    TargetRect = [pos.template_orig-Offset, pos.template_size];
    SearchRegionRect = [SearchRegion, pos.template_size + 2*pos.search_border];

    % Draw rectangles on input to show target and search region
    input = insertShape(input, "rectangle", [TargetRect; SearchRegionRect],...
                        "Color", "white");
    % Display the offset (displacement) values on the input image
    txt = sprintf("(%+05.1f,%+05.1f)", Offset);
    input = insertText(input(:,:,1),[191 215],txt,"FontSize",16, ...
                    "TextColor", "white", "BoxOpacity", 0);
    % Display video
    hVideoOut([input(:,:,1) Stabilized]);
end

まとめ

MATLAB® コマンド ラインから Computer Vision Toolbox™ の機能を使用すると、映像安定化のような複雑なシステムを簡単に実装できます。

付録

この例では次の補助関数が使用されています。

• updatesearch.m

アルゴリズム

テンプレート マッチングは一般に、大きいイメージ内で小さい領域を見つける場合に使用されます。領域はテンプレート イメージによって指定されます。テンプレート イメージは入力イメージと同じ大きさにすることができますが、入力イメージより小さくするのが一般的です。

オブジェクトは、イメージの左上隅に対する最適一致の座標を出力します。位置の [x y] 座標は、テンプレートの中心に対応します。ピクセル値が奇数に指定されたテンプレートを使用する場合、オブジェクトはテンプレートの中心を使用します。ピクセル値が偶数に指定されたテンプレートを使用する場合、オブジェクトは中心位置の左上のピクセルを使用します。次の表は、オブジェクトが奇数と偶数のテンプレートの位置 (LOC) をどのように出力するかを示します。

テンプレート内のピクセル数が奇数の場合	テンプレート内のピクセル数が偶数の場合

拡張機能

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限:

• MATLAB コード生成における System object (MATLAB Coder)を参照してください。

バージョン履歴

R2012a で導入

参考

opticalFlowHS | opticalFlowLKDoG | opticalFlowLK | opticalFlowFarneback | insertMarker