Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

bagOfFeatures class

Bag of visual words object

Syntax

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

Description

bag = bagOfFeatures(imds) returns a bag of features object. The bag output object is generated using samples from the imds input.

bag = bagOfFeatures(imds,'CustomExtractor',extractorFcn) returns a bag of features that uses a custom feature extractor function to extract features from the output bag to learn its visual vocabulary. extractorFcn is a function handle to a custom feature extraction function.

bag = bagOfFeatures(imds,Name,Value) returns a bagOfFeatures object with additional properties specified by one or more Name,Value pair arguments.

This object supports parallel computing using multiple MATLAB® workers. Enable parallel computing from the Computer Vision System Toolbox Preferences dialog box. To open Computer Vision System Toolbox™ preferences, on the Home tab, in the Environment section, click Preferences. Then select Computer Vision System Toolbox.

Input Arguments

expand all

Images, specified as an imageDatastore objects. The bagOfFeatures extracts an equal number of strongest features from the images contained in the imds object.

number of strongest features = min(number of features found in each set) x StrongestFraction

The object obtains the StrongestFraction value from the 'StrongestFeatures' property.

Custom feature extractor function, specified the comma-separated pair consisting of 'CustomExtractor' and a function handle. This custom function extracts features from the output bagOfFeatures object to learn the visual vocabulary of the object.

The function, extractorFcn, must be specified as a function handle for a file:

extractorFcn = @exampleBagOfFeaturesExtractor;
bag = bagOfFeatures(imds,'CustomExtractor',extractorFcn)
where exampleBagOfFeaturesExtractor is a MATLAB function. For example:
function [features,featureMetrics] = exampleBagOfFeaturesExtractor(img)
...
The function must be on the path or in the current working directory.

For more details on the custom extractor function and its input and output requirements, see Create a Custom Feature Extractor.

You can open an example function file, and use it as a template by typing the following command at the MATLAB command-line:

edit('exampleBagOfFeaturesExtractor.m')

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'VocabularySize',500 sets the size of the visual words to include in the bag to 500.

expand all

Number of visual words to include in the bagOfFeatures object, specified as the comma-separated pair consisting of 'VocabularySize' and an integer scalar in the range [2, inf]. The VocabularySize value corresponds to K in the K-means clustering (Statistics and Machine Learning Toolbox) algorithm used to quantize features into the visual vocabulary.

Fraction of strongest features, specified as the comma-separated pair consisting of 'StrongestFeatures' and a value in the range [0,1]. The value represents the fraction of strongest features to use from each label in the imds input.

Enable progress display to screen, specified as the comma-separated pair consisting of 'Verbose' and the logical true or false.

Selection method for picking point locations for SURF feature extraction, specified as the comma-separated pair consisting of 'PointSelection' and the character vector 'Grid' or 'Detector'. There are two stages for feature extraction. First, you select a method for picking the point locations, (SURF 'Detector' or 'Grid'), with the PointSelection property. The second stage extracts the features. The feature extraction uses a SURF extractor for both point selection methods.

When you set PointSelection to 'Detector', the feature points are selected using a speeded up robust feature (SURF) detector. Otherwise, the points are picked on a predefined grid with spacing defined by 'GridStep'. This property applies only when you are not specifying a custom extractor with the CustomExtractor property.

Grid step size in pixels, specified as the comma-separated pair consisting of 'GridStep' and an 1-by-2 [x y] vector. This property applies only when you set PointSelection to 'Grid' and you are not specifying a custom extractor with the CustomExtractor property. The steps in the x and y directions define the spacing of a uniform grid. Intersections of the grid lines define locations for feature extraction.

Patch size to extract upright SURF descriptor, specified as the comma-separated pair consisting of 'BlockWidth' and a 1-by-N vector of N block widths. This property applies only when you are not specifying a custom extractor with the CustomExtractor property. Each element of the vector corresponds to the size of a square block from which the function extracts upright SURF descriptors. Use multiple square sizes to extract multiscale features. All the square specified are used for each extraction points on the grid. This property only applies when you set PointSelection to 'Grid'. The block width corresponds to the scale of the feature. The minimum BlockWidth is 32 pixels.

Orientation of SURF feature vector, specified as the comma-separated pair consisting of 'Upright' and a logical scalar. This property applies only when you are not specifying a custom extractor with the CustomExtractor property. Set this property to true when you do not need to estimate the orientation of the SURF feature vectors. Set it to false when you need the image descriptors to capture rotation information.

Properties

expand all

Custom feature extractor function, specified as a handle to a function. The custom feature extractor function extracts features used to learn the visual vocabulary for bagOfFeatures. You must specify 'CustomExtractor' and the function handle, extractorFcn, to a custom feature extraction function.

The function, extractorFcn, must be specified as a function handle for a file:

extractorFcn = @exampleBagOfFeaturesExtractor;
bag = bagOfFeatures(imds,'CustomExtractor',extractorFcn)
where exampleBagOfFeaturesExtractor is a MATLAB function such as:
function [features,featureMetrics] = exampleBagOfFeaturesExtractor(img)
...
The function must be on the path or in the current working directory.

For more details on the custom extractor function and it’s input and output requirements, see Create a Custom Feature Extractor. You can open an example function file, and use it as a template by typing the following command at the MATLAB command-line:

edit('exampleBagOfFeaturesExtractor.m')

Number of visual words to include in the bagOfFeatures object, specified as the comma-separated pair consisting of 'VocabularySize' and an integer scalar in the range [2, inf). The VocabularySize value corresponds to K in the k-Means Clustering (Statistics and Machine Learning Toolbox) algorithm used to quantize features into the visual vocabulary.

Fraction of strongest features, specified as the comma-separated pair consisting of 'StrongestFeatures' and a value in the range [0,1]. The value represents the strongest of strongest features to use from each labelcontained in imds input.

Selection method for picking point locations for SURF feature extraction, specified as the comma-separated pair consisting of 'PointSelection' and the character vector 'Grid' or 'Detector'. There are two stages for feature extraction. First, you select a method for picking the point locations, (SURF 'Detector' or 'Grid'), with the PointSelection property. The second stage extracts the features. The feature extraction uses a SURF extractor for both point selection methods.

When you set PointSelection to 'Detector', the feature points are selected using a speeded up robust feature (SURF) detector. Otherwise, the points are picked on a predefined grid with spacing defined by 'GridStep'. This property applies only when you are not specifying a custom extractor with the CustomExtractor property.

Grid step size in pixels, specified as the comma-separated pair consisting of 'GridStep' and an 1-by-2 [x y] vector. This property applies only when you set PointSelection to 'Grid'. The steps in the x and y directions define the spacing of a uniform grid. Intersections of the grid lines define locations for feature extraction.

Patch size to extract SURF descriptor, specified as the comma-separated pair consisting of 'BlockWidth' and a 1-by-N vector of N block widths. Each element of the vector corresponds to the size of a square block from which the function extracts SURF descriptors. Use multiple square sizes to extract multiscale features. All the square specified are used for each extraction points on the grid. This property only applies when you set PointSelection to 'Grid'. The block width corresponds to the scale of the feature. The minimum BlockWidth is 32 pixels.

Orientation of SURF feature vector, specified as the comma-separated pair consisting of 'Upright' and a logical scalar. This property applies only when you are not specifying a custom extractor with the CustomExtractor property. Set this property to true when you do not need to estimate the orientation of the SURF feature vectors. Set it to false when you need the image descriptors to capture rotation information.

Methods

encodeCreate histogram of visual word occurrences

Examples

expand all

Load two image sets.

setDir  = fullfile(toolboxdir('vision'),'visiondata','imageSets');
imgSets = imageSet(setDir,'recursive');

Pick the first two images from each image set to create training sets.

trainingSets = partition(imgSets,2);

Create the bag of features. This process can take a few minutes.

bag = bagOfFeatures(trainingSets,'Verbose',false);

Compute histogram of visual word occurrences for one of the images. Store the histogram as feature vector.

img = read(imgSets(1),1);
featureVector = encode(bag,img);

Load an image set.

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

Specify a custom feature extractor.

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.

* Using K-Means clustering to create a 500 word visual vocabulary.
* Number of features          : 184320
* Number of clusters (K)      : 500

* Initializing cluster centers...100.00%.
* Clustering...completed 32/100 iterations (~3.32 seconds/iteration)...converged in 32 iterations.

* Finished creating Bag-Of-Features
bag = 
  bagOfFeatures with properties:

      CustomExtractor: @exampleBagOfFeaturesExtractor
       VocabularySize: 500
    StrongestFeatures: 0.8000

References

Csurka, G., C. R. Dance, L. Fan, J. Willamowski, and C. Bray. Visual Categorization with Bags of Keypoints. Workshop on Statistical Learning in Computer Vision. 2004, ECCV 1 (1–22), 1–2.

Introduced in R2014b