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.dsift;
31
32 import org.openimaj.feature.local.list.LocalFeatureList;
33 import org.openimaj.image.Image;
34 import org.openimaj.image.analyser.ImageAnalyser;
35 import org.openimaj.math.geometry.shape.Rectangle;
36
37 /**
38 * Base class for implementations of a dense SIFT feature extractors.
39 *
40 * @see "http://www.vlfeat.org/api/dsift.html#dsift-usage"
41 *
42 * @author Jonathon Hare (jsh2@ecs.soton.ac.uk)
43 *
44 * @param <IMAGE>
45 * Type of image being processed
46 */
47 public abstract class AbstractDenseSIFT<IMAGE extends Image<?, IMAGE>> implements ImageAnalyser<IMAGE>, Cloneable {
48
49 /**
50 * Compute the dense sift descriptors inside the bounds rectangle of the
51 * given image.
52 *
53 * @param image
54 * the image
55 * @param bounds
56 * the bounds rectangle
57 */
58 public abstract void analyseImage(IMAGE image, Rectangle bounds);
59
60 /**
61 * Compute the dense sift descriptors of the given image. The entire image
62 * will be sampled.
63 *
64 * @param image
65 * the image
66 */
67 @Override
68 public final void analyseImage(IMAGE image) {
69 analyseImage(image, image.getBounds());
70 }
71
72 /**
73 * Get the SIFT descriptors from the previous call to
74 * {@link #analyseImage(Image)} or {@link #analyseImage(Image, Rectangle)}
75 * in the form of a list of local features with float vectors.
76 *
77 * @return a list of {@link FloatDSIFTKeypoint}s.
78 */
79 public abstract LocalFeatureList<FloatDSIFTKeypoint> getFloatKeypoints();
80
81 /**
82 * Get the SIFT descriptors from the previous call to
83 * {@link #analyseImage(Image)} or {@link #analyseImage(Image, Rectangle)}
84 * in the form of a list of local features with byte vectors.
85 *
86 * @return a list of {@link ByteDSIFTKeypoint}s.
87 */
88 public abstract LocalFeatureList<ByteDSIFTKeypoint> getByteKeypoints();
89
90 /**
91 * Get the SIFT descriptors from the previous call to
92 * {@link #analyseImage(Image)} or {@link #analyseImage(Image, Rectangle)}
93 * in the form of a list of local features with float vectors. Only the
94 * features with an energy above the given threshold will be returned.
95 *
96 * @param energyThreshold
97 * the threshold on the feature energy
98 *
99 * @return a list of {@link FloatDSIFTKeypoint}s.
100 */
101 public abstract LocalFeatureList<FloatDSIFTKeypoint> getFloatKeypoints(float energyThreshold);
102
103 /**
104 * Get the SIFT descriptors from the previous call to
105 * {@link #analyseImage(Image)} or {@link #analyseImage(Image, Rectangle)}
106 * in the form of a list of local features with byte vectors. Only the
107 * features with an energy above the given threshold will be returned.
108 *
109 * @param energyThreshold
110 * the threshold on the feature energy
111 *
112 * @return a list of {@link ByteDSIFTKeypoint}s.
113 */
114 public abstract LocalFeatureList<ByteDSIFTKeypoint> getByteKeypoints(float energyThreshold);
115
116 @SuppressWarnings("unchecked")
117 @Override
118 public AbstractDenseSIFT<IMAGE> clone() {
119 try {
120 return (AbstractDenseSIFT<IMAGE>) super.clone();
121 } catch (final CloneNotSupportedException e) {
122 throw new AssertionError(e);
123 }
124 }
125
126 /**
127 * (Optional operation) Set the width of a single bin of the sampling window
128 * (in pixels). Sampling window width is this multiplied by
129 * {@link #getNumBinsX()}.
130 *
131 * @param size
132 * size to set
133 */
134 public abstract void setBinWidth(int size);
135
136 /**
137 * (Optional operation) Set the height of a single bin of the sampling
138 * window (in pixels). Sampling window height is this multiplied by
139 * {@link #getNumBinsY()}.
140 *
141 * @param size
142 * size to set
143 */
144 public abstract void setBinHeight(int size);
145
146 /**
147 * (Optional operation) Get the width of a single bin of the sampling window
148 * (in pixels). Sampling window width is this multiplied by
149 * {@link #getNumBinsX()}.
150 *
151 * @return the bin width
152 */
153 public abstract int getBinWidth();
154
155 /**
156 * (Optional operation) Get the height of a single bin of the sampling
157 * window (in pixels). Sampling window height is this multiplied by
158 * {@link #getNumBinsY()}.
159 *
160 * @return the bin height
161 */
162 public abstract int getBinHeight();
163
164 /**
165 * Get the number of spatial bins in the X direction
166 *
167 * @return the number of bins in the x direction
168 */
169 public abstract int getNumBinsX();
170
171 /**
172 * Get the number of spatial bins in the Y direction
173 *
174 * @return the number of bins in the y direction
175 */
176 public abstract int getNumBinsY();
177
178 /**
179 * Get the number of orientation bins
180 *
181 * @return the number of orientation bins
182 */
183 public abstract int getNumOriBins();
184
185 /**
186 * Get the computed raw dense SIFT descriptors from the previous call to
187 * {@link #analyseImage(Image)} or {@link #analyseImage(Image, Rectangle)} .
188 *
189 * @return the descriptors.
190 */
191 public abstract float[][] getDescriptors();
192 }