001/**
002 * Copyright (c) 2011, The University of Southampton and the individual contributors.
003 * All rights reserved.
004 *
005 * Redistribution and use in source and binary forms, with or without modification,
006 * are permitted provided that the following conditions are met:
007 *
008 *   *  Redistributions of source code must retain the above copyright notice,
009 *      this list of conditions and the following disclaimer.
010 *
011 *   *  Redistributions in binary form must reproduce the above copyright notice,
012 *      this list of conditions and the following disclaimer in the documentation
013 *      and/or other materials provided with the distribution.
014 *
015 *   *  Neither the name of the University of Southampton nor the names of its
016 *      contributors may be used to endorse or promote products derived from this
017 *      software without specific prior written permission.
018 *
019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
020 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
021 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
022 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
023 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
026 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
028 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package org.openimaj.image.feature.dense.gradient;
031
032import org.openimaj.citation.annotation.Reference;
033import org.openimaj.citation.annotation.ReferenceType;
034import org.openimaj.image.FImage;
035import org.openimaj.image.analyser.ImageAnalyser;
036import org.openimaj.image.analysis.algorithm.histogram.GradientOrientationHistogramExtractor;
037import org.openimaj.image.analysis.algorithm.histogram.binning.SpatialBinningStrategy;
038import org.openimaj.image.feature.dense.gradient.binning.FixedHOGStrategy;
039import org.openimaj.image.feature.dense.gradient.binning.FlexibleHOGStrategy;
040import org.openimaj.image.processing.convolution.FImageGradients;
041import org.openimaj.math.geometry.shape.Rectangle;
042import org.openimaj.math.statistics.distribution.Histogram;
043
044/**
045 * Implementation of an extractor for the Histogram of Oriented Gradients (HOG)
046 * feature for object detection. This implementation allows any kind of spatial
047 * layout to be used through different implementations of
048 * {@link SpatialBinningStrategy}s. HOG features can be efficiently extracted
049 * for many windows of the image.
050 * <p>
051 * The actual work of computing and normalising the descriptor is performed by
052 * the {@link SpatialBinningStrategy} (i.e. a {@link FixedHOGStrategy} or
053 * {@link FlexibleHOGStrategy}); this class just provides the objects required
054 * for efficient histogram computation (namely a
055 * {@link GradientOrientationHistogramExtractor}) for the image being analysed.
056 * <p>
057 * Normally, HOG features are computed using all gradients in the image, but
058 * this class makes it possible to only consider gradients along "edges" using
059 * the {@link #analyseImage(FImage, FImage)} method.
060 *
061 * @author Jonathon Hare (jsh2@ecs.soton.ac.uk)
062 */
063@Reference(
064                type = ReferenceType.Inproceedings,
065                author = { "Dalal, Navneet", "Triggs, Bill" },
066                title = "Histograms of Oriented Gradients for Human Detection",
067                year = "2005",
068                booktitle = "Proceedings of the 2005 IEEE Computer Society Conference on Computer Vision and Pattern Recognition (CVPR'05) - Volume 1 - Volume 01",
069                pages = { "886", "", "893" },
070                url = "http://dx.doi.org/10.1109/CVPR.2005.177",
071                publisher = "IEEE Computer Society",
072                series = "CVPR '05",
073                customData = {
074                                "isbn", "0-7695-2372-2",
075                                "numpages", "8",
076                                "doi", "10.1109/CVPR.2005.177",
077                                "acmid", "1069007",
078                                "address", "Washington, DC, USA"
079                })
080public class HOG implements ImageAnalyser<FImage> {
081        GradientOrientationHistogramExtractor extractor;
082        protected SpatialBinningStrategy strategy;
083
084        private transient Histogram currentHist;
085
086        /**
087         * Construct a new {@link HOG} with the 9 bins, using histogram
088         * interpolation and unsigned gradients. Use the given strategy to extract
089         * the actual features.
090         *
091         * @param strategy
092         *            the {@link SpatialBinningStrategy} to use to produce the
093         *            features
094         */
095        public HOG(SpatialBinningStrategy strategy)
096        {
097                this(9, true, FImageGradients.Mode.Unsigned, strategy);
098        }
099
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}