1 /**
2 * Copyright (c) 2011, The University of Southampton and the individual contributors.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
7 *
8 * * Redistributions of source code must retain the above copyright notice,
9 * this list of conditions and the following disclaimer.
10 *
11 * * Redistributions in binary form must reproduce the above copyright notice,
12 * this list of conditions and the following disclaimer in the documentation
13 * and/or other materials provided with the distribution.
14 *
15 * * Neither the name of the University of Southampton nor the names of its
16 * contributors may be used to endorse or promote products derived from this
17 * software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
23 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
26 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 package org.openimaj.image.feature.dense.gradient;
31
32 import org.openimaj.citation.annotation.Reference;
33 import org.openimaj.citation.annotation.ReferenceType;
34 import org.openimaj.image.FImage;
35 import org.openimaj.image.analyser.ImageAnalyser;
36 import org.openimaj.image.analysis.algorithm.histogram.GradientOrientationHistogramExtractor;
37 import org.openimaj.image.analysis.algorithm.histogram.binning.SpatialBinningStrategy;
38 import org.openimaj.image.feature.dense.gradient.binning.FixedHOGStrategy;
39 import org.openimaj.image.feature.dense.gradient.binning.FlexibleHOGStrategy;
40 import org.openimaj.image.processing.convolution.FImageGradients;
41 import org.openimaj.math.geometry.shape.Rectangle;
42 import org.openimaj.math.statistics.distribution.Histogram;
43
44 /**
45 * Implementation of an extractor for the Histogram of Oriented Gradients (HOG)
46 * feature for object detection. This implementation allows any kind of spatial
47 * layout to be used through different implementations of
48 * {@link SpatialBinningStrategy}s. HOG features can be efficiently extracted
49 * for many windows of the image.
50 * <p>
51 * The actual work of computing and normalising the descriptor is performed by
52 * the {@link SpatialBinningStrategy} (i.e. a {@link FixedHOGStrategy} or
53 * {@link FlexibleHOGStrategy}); this class just provides the objects required
54 * for efficient histogram computation (namely a
55 * {@link GradientOrientationHistogramExtractor}) for the image being analysed.
56 * <p>
57 * Normally, HOG features are computed using all gradients in the image, but
58 * this class makes it possible to only consider gradients along "edges" using
59 * the {@link #analyseImage(FImage, FImage)} method.
60 *
61 * @author Jonathon Hare (jsh2@ecs.soton.ac.uk)
62 */
63 @Reference(
64 type = ReferenceType.Inproceedings,
65 author = { "Dalal, Navneet", "Triggs, Bill" },
66 title = "Histograms of Oriented Gradients for Human Detection",
67 year = "2005",
68 booktitle = "Proceedings of the 2005 IEEE Computer Society Conference on Computer Vision and Pattern Recognition (CVPR'05) - Volume 1 - Volume 01",
69 pages = { "886", "", "893" },
70 url = "http://dx.doi.org/10.1109/CVPR.2005.177",
71 publisher = "IEEE Computer Society",
72 series = "CVPR '05",
73 customData = {
74 "isbn", "0-7695-2372-2",
75 "numpages", "8",
76 "doi", "10.1109/CVPR.2005.177",
77 "acmid", "1069007",
78 "address", "Washington, DC, USA"
79 })
80 public class HOG implements ImageAnalyser<FImage> {
81 GradientOrientationHistogramExtractor extractor;
82 protected SpatialBinningStrategy strategy;
83
84 private transient Histogram currentHist;
85
86 /**
87 * Construct a new {@link HOG} with the 9 bins, using histogram
88 * interpolation and unsigned gradients. Use the given strategy to extract
89 * the actual features.
90 *
91 * @param strategy
92 * the {@link SpatialBinningStrategy} to use to produce the
93 * features
94 */
95 public HOG(SpatialBinningStrategy strategy)
96 {
97 this(9, true, FImageGradients.Mode.Unsigned, strategy);
98 }
99
100 /**
101 * Construct a new {@link HOG} with the given number of bins. Optionally
102 * perform linear interpolation across orientation bins. Histograms can also
103 * use either signed or unsigned gradients.
104 *
105 * @param nbins
106 * number of bins
107 * @param histogramInterpolation
108 * if true cyclic linear interpolation is used to share the
109 * magnitude across the two closest bins; if false only the
110 * closest bin will be filled.
111 * @param orientationMode
112 * the range of orientations to extract
113 * @param strategy
114 * the {@link SpatialBinningStrategy} to use to produce the
115 * features
116 */
117 public HOG(int nbins, boolean histogramInterpolation, FImageGradients.Mode orientationMode,
118 SpatialBinningStrategy strategy)
119 {
120 this.extractor = new GradientOrientationHistogramExtractor(nbins, histogramInterpolation, orientationMode);
121
122 this.strategy = strategy;
123 }
124
125 @Override
126 public void analyseImage(FImage image) {
127 extractor.analyseImage(image);
128 }
129
130 /**
131 * Analyse the given image, but construct the internal data such that the
132 * gradient magnitudes are multiplied by the given edge map before being
133 * accumulated. This could be used to suppress all magnitudes except those
134 * at edges; the resultant extracted histograms would only contain
135 * information about edge gradients.
136 *
137 * @param image
138 * the image to analyse
139 * @param edges
140 * the edge image
141 */
142 public void analyseImage(FImage image, FImage edges) {
143 extractor.analyseImage(image, edges);
144 }
145
146 /**
147 * Compute the HOG feature for the given window.
148 *
149 * @param rectangle
150 * the window
151 * @return the computed HOG feature
152 */
153 public Histogram getFeatureVector(Rectangle rectangle) {
154 return currentHist = strategy.extract(extractor, rectangle, currentHist);
155 }
156 }