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.local.engine;
031
032import org.openimaj.image.FImage;
033import org.openimaj.image.Image;
034import org.openimaj.image.analysis.pyramid.gaussian.GaussianPyramidOptions;
035import org.openimaj.image.feature.local.detector.dog.extractor.DominantOrientationExtractor;
036import org.openimaj.image.feature.local.detector.pyramid.BasicOctaveExtremaFinder;
037import org.openimaj.image.processor.SinglebandImageProcessor;
038
039/**
040 * Options for controlling SIFT feature localisation and extraction. Default
041 * values are based on Lowe's papers.
042 * 
043 * @author Jonathon Hare (jsh2@ecs.soton.ac.uk)
044 * 
045 * @param <IMAGE>
046 *            Type of image processed by the {@link Engine} associated with
047 *            these options.
048 */
049public class DoGSIFTEngineOptions<IMAGE extends Image<?, IMAGE> & SinglebandImageProcessor.Processable<Float, FImage, IMAGE>>
050                extends GaussianPyramidOptions<IMAGE>
051{
052        /**
053         * The threshold on the ratio of the Eigenvalues of the Hessian matrix (Lowe
054         * IJCV, p.12)
055         */
056        protected float eigenvalueRatio = BasicOctaveExtremaFinder.DEFAULT_EIGENVALUE_RATIO;
057
058        /** Threshold on the magnitude of detected points (Lowe IJCV, p.11) */
059        protected float magnitudeThreshold = BasicOctaveExtremaFinder.DEFAULT_MAGNITUDE_THRESHOLD;
060
061        /**
062         * The magnification factor determining the size of a spatial SIFT bin
063         * relative to the scale. The overall sampling size is related to the number
064         * of spatial bins.
065         */
066        protected float magnificationFactor = 3;
067
068        /**
069         * Threshold for peak detection in the orientation histogram. A value of 1.0
070         * would result in only a single peak being detected.
071         */
072        protected float peakThreshold = DominantOrientationExtractor.DEFAULT_PEAK_THRESHOLD;
073
074        /**
075         * The number of orientation histogram bins for finding the dominant
076         * orientations; Lowe's IJCV paper (p.13) suggests 36 bins.
077         */
078        protected int numOriHistBins = 36;
079
080        /**
081         * The value for weighting the scaling Gaussian of the orientation histogram
082         * relative to the keypoint scale. Lowe's IJCV paper (p.13) suggests 1.5.
083         */
084        protected float scaling = 1.5f;
085
086        /**
087         * The number of iterations of the smoothing filter. The vlfeat SIFT
088         * implementation uses 6.
089         */
090        protected int smoothingIterations = 6;
091
092        /**
093         * The size of the sampling window relative to the sampling scale. Lowe's
094         * ICCV paper suggests 3;
095         */
096        protected float samplingSize = 3.0f;
097
098        /** The number of orientation bins (default 8) */
099        protected int numOriBins = 8;
100
101        /** The number of spatial bins in each direction (default 4) */
102        protected int numSpatialBins = 4;
103
104        /** Threshold for the maximum value allowed in the histogram (default 0.2) */
105        protected float valueThreshold = 0.2f;
106
107        /**
108         * The width of the Gaussian used for weighting samples, relative to the
109         * half-width of the sampling window (default 1.0).
110         */
111        protected float gaussianSigma = 1.0f;
112
113        /**
114         * Get the threshold on the ratio of the Eigenvalues of the Hessian matrix
115         * (Lowe IJCV, p.12)
116         * 
117         * @return the eigenvalue ratio threshold
118         */
119        public float getEigenvalueRatio() {
120                return eigenvalueRatio;
121        }
122
123        /**
124         * Set the threshold on the ratio of the Eigenvalues of the Hessian matrix
125         * (Lowe IJCV, p.12)
126         * 
127         * @param eigenvalueRatio
128         *            the eigenvalueRatio to set
129         */
130        public void setEigenvalueRatio(float eigenvalueRatio) {
131                this.eigenvalueRatio = eigenvalueRatio;
132        }
133
134        /**
135         * Get the threshold on the magnitude of detected points (Lowe IJCV, p.11)
136         * 
137         * @return the magnitude threshold
138         */
139        public float getMagnitudeThreshold() {
140                return magnitudeThreshold;
141        }
142
143        /**
144         * Set the threshold on the magnitude of detected points (Lowe IJCV, p.11)
145         * 
146         * @param magnitudeThreshold
147         *            the magnitude threshold to set
148         */
149        public void setMagnitudeThreshold(float magnitudeThreshold) {
150                this.magnitudeThreshold = magnitudeThreshold;
151        }
152
153        /**
154         * Get the magnification factor determining the size of a spatial SIFT bin
155         * relative to the scale. The overall sampling size is related to the number
156         * of spatial bins.
157         * 
158         * @return the magnification factor
159         */
160        public float getMagnificationFactor() {
161                return magnificationFactor;
162        }
163
164        /**
165         * Set the magnification factor determining the size of a spatial SIFT bin
166         * relative to the scale. The overall sampling size is related to the number
167         * of spatial bins.
168         * 
169         * @param magnificationFactor
170         *            the magnification factor to set
171         */
172        public void setMagnificationFactor(float magnificationFactor) {
173                this.magnificationFactor = magnificationFactor;
174        }
175
176        /**
177         * Get the threshold for peak detection in the orientation histogram. A
178         * value of 1.0 would result in only a single peak being detected.
179         * 
180         * @return the peak detection threshold
181         */
182        public float getPeakThreshold() {
183                return peakThreshold;
184        }
185
186        /**
187         * Set the threshold for peak detection in the orientation histogram. A
188         * value of 1.0 would result in only a single peak being detected.
189         * 
190         * @param peakThreshold
191         *            the peak detection threshold to set
192         */
193        public void setPeakThreshold(float peakThreshold) {
194                this.peakThreshold = peakThreshold;
195        }
196
197        /**
198         * Get the number of orientation histogram bins for finding the dominant
199         * orientations; Lowe's IJCV paper (p.13) suggests 36 bins.
200         * 
201         * @return the number of orientation histogram bins
202         */
203        public int getNumOriHistBins() {
204                return numOriHistBins;
205        }
206
207        /**
208         * Set the number of orientation histogram bins for finding the dominant
209         * orientations; Lowe's IJCV paper (p.13) suggests 36 bins.
210         * 
211         * @param numOriHistBins
212         *            the number of orientation histogram bins to set
213         */
214        public void setNumOriHistBins(int numOriHistBins) {
215                this.numOriHistBins = numOriHistBins;
216        }
217
218        /**
219         * Get the value for weighting the scaling Gaussian of the orientation
220         * histogram relative to the keypoint scale. Lowe's IJCV paper (p.13)
221         * suggests 1.5.
222         * 
223         * @return the scaling amount
224         */
225        public float getScaling() {
226                return scaling;
227        }
228
229        /**
230         * Set the value for weighting the scaling Gaussian of the orientation
231         * histogram relative to the keypoint scale. Lowe's IJCV paper (p.13)
232         * suggests 1.5.
233         * 
234         * @param scaling
235         *            the scaling amount to set
236         */
237        public void setScaling(float scaling) {
238                this.scaling = scaling;
239        }
240
241        /**
242         * Get the number of iterations of the smoothing filter. The vlfeat SIFT
243         * implementation uses 6.
244         * 
245         * @return the number of smoothing iterations
246         */
247        public int getSmoothingIterations() {
248                return smoothingIterations;
249        }
250
251        /**
252         * Set the number of iterations of the smoothing filter. The vlfeat SIFT
253         * implementation uses 6.
254         * 
255         * @param smoothingIterations
256         *            the number of smoothing iterations to set
257         */
258        public void setSmoothingIterations(int smoothingIterations) {
259                this.smoothingIterations = smoothingIterations;
260        }
261
262        /**
263         * Get the size of the sampling window relative to the sampling scale.
264         * Lowe's ICCV paper suggests 3;
265         * 
266         * @return the sampling size
267         */
268        public float getSamplingSize() {
269                return samplingSize;
270        }
271
272        /**
273         * Set the size of the sampling window relative to the sampling scale.
274         * Lowe's ICCV paper suggests 3;
275         * 
276         * @param samplingSize
277         *            the sampling size to set
278         */
279        public void setSamplingSize(float samplingSize) {
280                this.samplingSize = samplingSize;
281        }
282
283        /**
284         * Get the number of orientation bins (default 8) in the SIFT feature
285         * 
286         * @return the number of orientation bins
287         */
288        public int getNumOriBins() {
289                return numOriBins;
290        }
291
292        /**
293         * Set the number of orientation bins (default 8) in the SIFT feature
294         * 
295         * @param numOriBins
296         *            the number of orientation bins to set
297         */
298        public void setNumOriBins(int numOriBins) {
299                this.numOriBins = numOriBins;
300        }
301
302        /**
303         * Get the number of spatial bins in each direction (default 4) in the SIFT
304         * feature
305         * 
306         * @return the number of spatial bins
307         */
308        public int getNumSpatialBins() {
309                return numSpatialBins;
310        }
311
312        /**
313         * Set the number of spatial bins in each direction (default 4) in the SIFT
314         * feature
315         * 
316         * @param numSpatialBins
317         *            the number of spatial bins to set
318         */
319        public void setNumSpatialBins(int numSpatialBins) {
320                this.numSpatialBins = numSpatialBins;
321        }
322
323        /**
324         * Get the threshold for the maximum value allowed in the histogram (default
325         * 0.2)
326         * 
327         * @return the threshold
328         */
329        public float getValueThreshold() {
330                return valueThreshold;
331        }
332
333        /**
334         * Set the threshold for the maximum value allowed in the histogram (default
335         * 0.2)
336         * 
337         * @param valueThreshold
338         *            the threshold to set
339         */
340        public void setValueThreshold(float valueThreshold) {
341                this.valueThreshold = valueThreshold;
342        }
343
344        /**
345         * Get the width of the Gaussian used for weighting samples, relative to the
346         * half-width of the sampling window (default 1.0).
347         * 
348         * @return the Gaussian width
349         */
350        public float getGaussianSigma() {
351                return gaussianSigma;
352        }
353
354        /**
355         * Get the width of the Gaussian used for weighting samples, relative to the
356         * half-width of the sampling window (default 1.0).
357         * 
358         * @param gaussianSigma
359         *            the Gaussian width to set
360         */
361        public void setGaussianSigma(float gaussianSigma) {
362                this.gaussianSigma = gaussianSigma;
363        }
364}