bagOfFeatures

bag of visual words オブジェクト

このページをすべて展開する

説明

イメージのカテゴリ分類、画像検索、または Visual simultaneous localization and mapping (vSLAM) でのループ閉じ込み検出に使用する bag of visual words を構築できます。

作成

構文

bag = bagOfFeatures(imds)

bag = bagOfFeatures(imds,'CustomExtractor',extractorFcn)

bag = bagOfFeatures(imds,Name=Value)

説明

例

bag = bagOfFeatures(imds) は、bag of features オブジェクトを返します。bag 出力オブジェクトは、imds 入力のサンプルを使用して生成されます。既定では、ビジュアルボキャブラリは imds 内のイメージから抽出された SURF 特徴から作成されます。

bag = bagOfFeatures(imds,'CustomExtractor',extractorFcn) は、カスタム特徴抽出器関数を使用して imds のイメージから特徴を抽出する bag of features を返します。extractorFcn はカスタム特徴抽出関数の関数ハンドルです。

bag = bagOfFeatures(imds,Name=Value) は、前の構文にある引数の任意の組み合わせに加えて、名前と値の引数を 1 つ以上使用してオプションを指定します。たとえば、bag = bagOfFeatures(imds,Verbose=true) は、さらに Verbose を true に設定します。

このオブジェクトは、複数の MATLAB^® ワーカーを使用する並列計算をサポートします。Computer Vision Toolbox の基本設定ダイアログボックスから並列計算を有効にします。Computer Vision Toolbox™ の基本設定を開くには、[ホーム] タブの [環境] セクションで [基本設定] をクリックします。次に、Computer Vision Toolbox を選択します。

入力引数

すべて展開する

`imds` — イメージ
`ImageDatastore` オブジェクト

イメージ。ImageDatastore オブジェクトとして指定します。bagOfFeatures は、imds オブジェクトに含まれるイメージから、同数の最も強い特徴を抽出します。最も強い特徴の数は次のように定義されます。

number of strongest features = min(各セットで検出された特徴の数) x StrongestFraction

オブジェクトは StrongestFeatures プロパティから StrongestFraction の値を読み取ります。

`extractorFcn` — カスタム特徴抽出器関数
関数ハンドル

カスタム特徴抽出器関数。関数ハンドルとして指定します。このカスタム関数は、特徴を抽出し、オブジェクトのビジュアルボキャブラリを学習します。

関数 extractorFcn はファイルの関数ハンドルとして指定しなければなりません。

extractorFcn = @exampleBagOfFeaturesExtractor;
bag = bagOfFeatures(imds,CustomExtractor=extractorFcn)

exampleBagOfFeaturesExtractor は MATLAB 関数です。次に例を示します。

function [features,featureMetrics,location] = exampleBagOfFeaturesExtractor(img)
...

関数はパス上にあるか、現在の作業ディレクトリ内になければなりません。引数は次のように定義されます。

引数	入力/出力	説明
`img`	入力	バイナリ、グレースケールまたはトゥルーカラーイメージ。入力イメージは最初に `bagOfFeatures` に渡されたイメージセットから取得されます。
`features`	出力	`binaryFeatures` オブジェクト。 M 行 N 列のイメージ特徴の数値行列。M は特徴の数、N は各特徴ベクトルの長さを示します。特徴の長さ N は、ゼロより大きくなければならず、`bagOfFeatures` の作成プロセスの間に処理されるすべてのイメージにおいて同じでなければなりません。イメージから特徴を抽出できない場合、空の特徴行列と、空の特徴メトリクスベクトルを指定してください。空の行列とベクトルは、たとえば特徴抽出用のキーポイントが見つからなかった場合などに使用します。数値、実数および非スパース。
`featureMetrics`	出力	各特徴ベクトルの強さを示す特徴メトリクスからなる、M 行 1 列のベクトル。 `bagOfFeatures` フレームワークの `'SelectStrongest'` 基準を適用するために使用されます。数値、実数および非スパース。
`location`	出力	1 ベースの [x y] 値からなる、M 行 2 列の行列。 [x y] 値には小数値も指定できます。数値、実数および非スパース。

カスタム抽出器関数とその入出力の要件の詳細については、カスタム特徴抽出器の作成を参照してください。

MATLAB コマンドラインに次のコマンドを入力すると、関数ファイルの例を開いてテンプレートとして使用できます。

edit('exampleBagOfFeaturesExtractor.m')

プロパティ

すべて展開する

`CustomExtractor` — カスタム抽出関数
関数ハンドル

カスタム特徴抽出器関数。関数ハンドルとして指定します。カスタム特徴抽出器関数は、bagOfFeatures のビジュアルボキャブラリを学習するために使用される特徴を抽出します。カスタム特徴抽出関数には 'CustomExtractor' と関数ハンドル extractorFcn を指定しなければなりません。

関数 extractorFcn はファイルの関数ハンドルとして指定しなければなりません。

extractorFcn = @exampleBagOfFeaturesExtractor;
bag = bagOfFeatures(imds,CustomExtractor=extractorFcn)

exampleBagOfFeaturesExtractor は次のような MATLAB 関数です。

function [features,featureMetrics] = exampleBagOfFeaturesExtractor(img)
...

関数はパス上にあるか、現在の作業ディレクトリ内になければなりません。

カスタム抽出器関数とその入出力の要件の詳細については、カスタム特徴抽出器の作成を参照してください。MATLAB コマンドラインに次のコマンドを入力すると、関数ファイルの例を開いてテンプレートとして使用できます。

edit('exampleBagOfFeaturesExtractor.m')

`TreeProperties` — ボキャブラリツリープロパティ
`[1 500]` (既定値) | 2 要素ベクトル

ボキャブラリツリープロパティ。[numLevels branchingFactor] の形式で 2 要素のベクトルとして指定します。numLevels は、ボキャブラリツリーのレベル数を指定する整数です。branchingFactor は、ツリー内の連続するレベルでのボキャブラリ増加量を制御するための係数を指定する整数です。ボキャブラリツリーで表されるビジュアルワードの最大数は branchingFactor^numLevels です。numLevels の標準値は 1 ～ 6 です。branchingFactor の標準値は 10 ～ 500 です。経験的解析を使用して、最適な値を選択します。

より大きなボキャブラリを生成するには、分岐因子を増やします。ボキャブラリを増やすと、分類と画像検索の精度が向上しますが、イメージのエンコード時間が長くなります。複数レベルのボキャブラリツリーを使用して、およそ 10,000 ビジュアルワードまたはそれ以上のボキャブラリを作成できます。マルチレベルツリーは、多数のボキャブラリをもつイメージのエンコードに必要な時間を短縮しますが、作成に時間がかかります。ボキャブラリに 100 ～ 1,000 のビジュアルワードしか含まれない場合、単一レベルのツリーを使用できます。

`StrongestFeatures` — 最も強い特徴の割合
`0.8` (既定値) | [`0,1`]

最も強い特徴の割合。'StrongestFeatures' と範囲 [0,1] の値で構成されるコンマ区切りのペアとして指定します。この値は、imds 入力の各ラベルから使用する最も強い特徴の割合を表します。

`Verbose` — 画面への進行状況表示の有効化
`true` (既定値) | false

画面への進行状況表示の有効化。'Verbose' と logical true または false で構成されるコンマ区切りのペアとして指定します。

`PointSelection` — 点の位置を選択する方法
`"Grid"` (既定値) | `"Detector"`

SURF 特徴抽出で点の位置を選択する方法。'PointSelection' と、"Grid" または "Detector" で構成されるコンマ区切りのペアとして指定します。特徴抽出には 2 つの段階があります。まず、PointSelection プロパティを使用して、点の位置を選択する方法 (SURF "Detector" または "Grid") を選択します。次の段階で、特徴を抽出します。特徴抽出では、両方の点選択方法に SURF 抽出器を使用します。

PointSelection を "Detector" に設定すると、Speeded-Up Robust Features (SURF) 検出器を使用して特徴点が選択されます。そうでない場合、事前定義のグリッドで 'GridStep' によって定義された間隔で点が選択されます。このプロパティは、CustomExtractor プロパティを使用してカスタム抽出器を指定していない場合にのみ適用されます。

`GridStep` — グリッドステップサイズ
`[8 8]` (既定値) | 1 行 2 列のベクトル [x y]

ピクセル単位のグリップステップサイズ。"Grid" と 1 行 2 列のベクトル [x y] で構成されるコンマ区切りのペアとして指定します。このプロパティは、PointSelection を "Grid" に設定し、CustomExtractor プロパティを使用してカスタム抽出器を指定していない場合にのみ適用されます。x および y 方向のステップは、等間隔グリッドの間隔を定義します。グリッドラインの交点は、特徴抽出の位置を定義します。

`BlockWidth` — 直立の SURF 記述子を抽出するパッチサイズ
`[32 64 96 128]` (既定値) | 1 行 N 列のベクトル

直立の SURF 記述子を抽出するパッチサイズ。'BlockWidth' と N 個のブロック幅からなる 1 行 N 列のベクトルで構成されるコンマ区切りのペアとして指定します。このプロパティは、CustomExtractor プロパティを使用してカスタム抽出器を指定していない場合にのみ適用されます。ベクトルの各要素は正方形ブロックのサイズに対応し、関数はこれらの正方形ブロックから直立の SURF 記述子を抽出します。複数の正方形のサイズを使用して、マルチスケールの特徴を抽出します。グリッドの各抽出点に対して、指定されたすべての正方形を使用します。このプロパティは PointSelection を "Grid" に設定した場合にのみ適用されます。ブロック幅は、特徴のスケールに対応します。BlockWidth の最小値は 32 ピクセルです。

`Upright` — SURF 特徴ベクトルの向き
`true` (既定値) | `false`

SURF 特徴ベクトルの向き。logical スカラーとして指定します。このプロパティは、CustomExtractor プロパティを使用してカスタム抽出器を指定していない場合にのみ適用されます。SURF 特徴ベクトルの向きを推定する必要がない場合には、このプロパティを true に設定します。回転の情報を取得するためにイメージ記述子が必要な場合には、このプロパティを false に設定します。

オブジェクト関数

encode Create histogram of visual word occurrences

例

すべて折りたたむ

bag of visual words の作成

この例では次を使用します。

ライブスクリプトを開く

イメージデータストアを作成します。

setDir  = fullfile(toolboxdir('vision'),'visiondata','imageSets');
imds = imageDatastore(setDir,'IncludeSubfolders',true,'LabelSource',...
    'foldernames');

bag of features を作成します。この処理には数分かかることがあります。

bag = bagOfFeatures(imds);

Creating Bag-Of-Features.
-------------------------
* Image category 1: books
* Image category 2: cups
* Selecting feature point locations using the Grid method.
* Extracting SURF features from the selected feature point locations.
** The GridStep is [8 8] and the BlockWidth is [32 64 96 128].

* Extracting features from 12 images...done. Extracted 230400 features.

* Keeping 80 percent of the strongest features from each category.

* Creating a 500 word visual vocabulary.
* Number of levels: 1
* Branching factor: 500
* Number of clustering steps: 1

* [Step 1/1] Clustering vocabulary level 1.
* Number of features          : 184320
* Number of clusters          : 500
* Initializing cluster centers...100.00%.
* Clustering...completed 26/100 iterations (~1.54 seconds/iteration)...converged in 26 iterations.

* Finished creating Bag-Of-Features

イメージの 1 つについて、ビジュアルワードの出現のヒストグラムを計算します。このヒストグラムを特徴ベクトルとして格納します。

img = readimage(imds, 1);
featureVector = encode(bag,img);

Encoding images using Bag-Of-Features.
--------------------------------------
* Encoding an image...done.

カスタム特徴抽出器を使用した bag of features の作成

ライブスクリプトを開く

イメージデータストアを作成します。

setDir  = fullfile(toolboxdir('vision'),'visiondata','imageSets');
imds = imageDatastore(setDir,'IncludeSubfolders',true,'LabelSource',...
    'foldernames');

カスタム特徴抽出器を指定します。

extractor = @exampleBagOfFeaturesExtractor;
bag = bagOfFeatures(imds,'CustomExtractor',extractor)

Creating Bag-Of-Features.
-------------------------
* Image category 1: books
* Image category 2: cups
* Extracting features using a custom feature extraction function: exampleBagOfFeaturesExtractor.

* Extracting features from 12 images...done. Extracted 230400 features.

* Keeping 80 percent of the strongest features from each category.

* Creating a 500 word visual vocabulary.
* Number of levels: 1
* Branching factor: 500
* Number of clustering steps: 1

* [Step 1/1] Clustering vocabulary level 1.
* Number of features          : 184320
* Number of clusters          : 500
* Initializing cluster centers...100.00%.
* Clustering...completed 19/100 iterations (~1.50 seconds/iteration)...converged in 19 iterations.

* Finished creating Bag-Of-Features

bag = 
  bagOfFeatures with properties:

      CustomExtractor: @exampleBagOfFeaturesExtractor
       NumVisualWords: 500
       TreeProperties: [1 500]
    StrongestFeatures: 0.8000

参照

[1] Csurka, G., D. Christopher, F. Lixin, W. Jutta, and B. Cédric. "Visual categorization with bags of keypoints." Workshop on statistical learning in computer vision, ECCV, 2004, pp. 1-2.

[2] Nister, D., and H. Stewenius. "Scalable Recognition with a Vocabulary Tree." Proceedings of the IEEE Computer Society Conference on Computer Vision and Pattern Recognition, 2006, vol. 2, pp. 2161–2168.

拡張機能

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

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

コード生成では、関数 bagOfFeatures は入力として ImageDatastore オブジェクトをサポートしません。代わりに、フィールド Images と Labels をもつ構造体として入力を指定します。Images フィールドには、グレースケールまたは RGB カラーイメージの cell 配列が含まれていなければなりません。Labels フィールドには、categorical 配列として格納されたイメージラベルが含まれていなければなりません。

自動並列サポート
Parallel Computing Toolbox™ を使用して自動的に並列計算を実行することで、コードを高速化します。

並列実行するには、'UseParallel' を true に設定するか、Computer Vision Toolbox の基本設定を使用して既定でこれを有効にします。

詳細については、Parallel Computing Toolbox のサポートを参照してください。

バージョン履歴

R2014b で導入

参考

imageDatastore | imageCategoryClassifier | trainImageCategoryClassifier

bagOfFeatures

説明

作成

構文

説明

入力引数

imds — イメージ ImageDatastore オブジェクト

extractorFcn — カスタム特徴抽出器関数 関数ハンドル

プロパティ

CustomExtractor — カスタム抽出関数 関数ハンドル

TreeProperties — ボキャブラリ ツリー プロパティ [1 500] (既定値) | 2 要素ベクトル

StrongestFeatures — 最も強い特徴の割合 0.8 (既定値) | [0,1]

Verbose — 画面への進行状況表示の有効化 true (既定値) | false

PointSelection — 点の位置を選択する方法 "Grid" (既定値) | "Detector"

GridStep — グリッド ステップ サイズ [8 8] (既定値) | 1 行 2 列のベクトル [x y]

BlockWidth — 直立の SURF 記述子を抽出するパッチ サイズ [32 64 96 128] (既定値) | 1 行 N 列のベクトル

Upright — SURF 特徴ベクトルの向き true (既定値) | false