bagOfFeatures

Bag of visual words object

expand all in page

Description

Manage your image collections and partition them into training and validation sets. You can construct a bag of visual words for use in image category classification. The training and classification includes support for Parallel Computing Toolbox™.

Creation

Syntax

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

Description

example

bag = bagOfFeatures(imds) returns a bag of features object. The bag output object is generated using samples from the imds input. By default, the visual vocabulary is created from SURF features extracted from images in imds.

bag = bagOfFeatures(imds,'CustomExtractor',extractorFcn) returns a bag of features that uses a custom feature extractor function to extract features from images in imds. extractorFcn is a function handle to a custom feature extraction function.

bag = bagOfFeatures(imds,Name,Value) sets properties using one or more name-value pairs. Enclose each property name in quotes. For example, bag = bagOfFeatures('Verbose',true)

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

Input Arguments

expand all

Images, specified as an ImageDatastore object. 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(1)
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')

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 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 either '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.

Object Functions

encodeCreate histogram of visual word occurrences

Examples

collapse all

This example uses:

Open Live Script

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);
Open Live Script

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 37/100 iterations (~0.30 seconds/iteration)...converged in 37 iterations.

* Finished creating Bag-Of-Features

bag = 
  bagOfFeatures with properties:

      CustomExtractor: @exampleBagOfFeaturesExtractor
       VocabularySize: 500
    StrongestFeatures: 0.8000

Extended Capabilities

See Also

| |

Topics

Introduced in R2014b

Computer Vision Toolbox Documentation

Support