File size: 10,461 Bytes
9375c9a |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 |
// Copyright (C) 2011 Davis E. King ([email protected])
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_HASHED_IMAGE_FEATUrES_ABSTRACT_Hh_
#ifdef DLIB_HASHED_IMAGE_FEATUrES_ABSTRACT_Hh_
#include "../lsh/projection_hash_abstract.h"
#include <vector>
#include "../matrix.h"
#include "../statistics.h"
namespace dlib
{
// ----------------------------------------------------------------------------------------
template <
typename feature_extractor,
typename hash_function_type_ = projection_hash
>
class hashed_feature_image : noncopyable
{
/*!
REQUIREMENTS ON feature_extractor
- must be an object with an interface compatible with dlib::hog_image
REQUIREMENTS ON hash_function_type_
- must be an object with an interface compatible with projection_hash
INITIAL VALUE
- size() == 0
- uses_uniform_feature_weights() == false
WHAT THIS OBJECT REPRESENTS
This object is a tool for performing image feature extraction. In
particular, it wraps another image feature extractor and converts the
wrapped image feature vectors into sparse indicator vectors. It does this
by hashing each feature vector into the range [0, get_num_dimensions()-1]
and then returns a new vector which is zero everywhere except for the
position determined by the hash.
THREAD SAFETY
Concurrent access to an instance of this object is not safe and should be protected
by a mutex lock except for the case where you are copying the configuration
(via copy_configuration()) of a hashed_feature_image object to many other threads.
In this case, it is safe to copy the configuration of a shared object so long
as no other operations are performed on it.
NOTATION
let BASE_FE denote the base feature_extractor object contained inside
the hashed_feature_image.
!*/
public:
typedef feature_extractor feature_extractor_type;
typedef hash_function_type_ hash_function_type;
typedef std::vector<std::pair<unsigned int,double> > descriptor_type;
hashed_feature_image (
);
/*!
ensures
- this object is properly initialized
!*/
void clear (
);
/*!
ensures
- this object will have its initial value
!*/
void set_hash (
const hash_function_type& hash
);
/*!
ensures
- #get_hash() == hash
!*/
const hash_function_type& get_hash (
) const;
/*!
ensures
- returns the hash function used by this object to hash
base feature vectors into integers.
!*/
void copy_configuration (
const feature_extractor& item
);
/*!
ensures
- performs BASE_FE.copy_configuration(item)
!*/
void copy_configuration (
const hashed_feature_image& item
);
/*!
ensures
- copies all the state information of item into *this, except for state
information populated by load(). More precisely, given two hashed_feature_image
objects H1 and H2, the following sequence of instructions should always
result in both of them having the exact same state.
H2.copy_configuration(H1);
H1.load(img);
H2.load(img);
!*/
template <
typename image_type
>
void load (
const image_type& img
);
/*!
requires
- image_type == any type that can be supplied to feature_extractor::load()
ensures
- performs BASE_FE.load(img)
i.e. does feature extraction. The features can be accessed using
operator() as defined below.
!*/
size_t size (
) const;
/*!
ensures
- returns BASE_FE.size()
!*/
long nr (
) const;
/*!
ensures
- returns BASE_FE.nr()
!*/
long nc (
) const;
/*!
ensures
- returns BASE_FE.nc()
!*/
long get_num_dimensions (
) const;
/*!
ensures
- returns the dimensionality of the feature vectors returned by operator().
In this case, this is the number of hash bins. That is, get_hash().num_hash_bins()
!*/
void use_relative_feature_weights (
);
/*!
ensures
- #uses_uniform_feature_weights() == false
!*/
void use_uniform_feature_weights (
);
/*!
ensures
- #uses_uniform_feature_weights() == true
!*/
bool uses_uniform_feature_weights (
) const;
/*!
ensures
- returns true if this object weights each feature with a value of 1 and
false if it uses a weighting of 1/N where N is the number of occurrences
of the feature in an image (note that we normalize N so that it is
invariant to the size of the image given to load()).
!*/
const descriptor_type& operator() (
long row,
long col
) const;
/*!
requires
- 0 <= row < nr()
- 0 <= col < nc()
- It must be legal to evaluate expressions of the form: get_hash()(BASE_FE(row,col))
(e.g. the hash function must be properly configured to process the feature
vectors produced by the base feature extractor)
ensures
- hashes BASE_FE(row,col) and returns the resulting indicator vector.
- To be precise, this function returns a sparse vector V such that:
- V.size() == 1
- V[0].first == get_hash()(BASE_FE(row,col))
- if (uses_uniform_feature_weights()) then
- V[0].second == 1
- else
- V[0].second == 1/N where N is the number of times a feature in
hash bin V[0].first was observed in the image given to load().
Note that we scale all the counts so that they are invariant to
the size of the image.
!*/
const rectangle get_block_rect (
long row,
long col
) const;
/*!
ensures
- returns BASE_FE.get_block_rect(row,col)
I.e. returns a rectangle that tells you what part of the original image is associated
with a particular feature vector.
!*/
const point image_to_feat_space (
const point& p
) const;
/*!
ensures
- returns BASE_FE.image_to_feat_space(p)
I.e. Each local feature is extracted from a certain point in the input image.
This function returns the identity of the local feature corresponding
to the image location p. Or in other words, let P == image_to_feat_space(p),
then (*this)(P.y(),P.x()) == the local feature closest to, or centered at,
the point p in the input image. Note that some image points might not have
corresponding feature locations. E.g. border points or points outside the
image. In these cases the returned point will be outside get_rect(*this).
!*/
const rectangle image_to_feat_space (
const rectangle& rect
) const;
/*!
ensures
- returns BASE_FE.image_to_feat_space(rect)
I.e. returns rectangle(image_to_feat_space(rect.tl_corner()), image_to_feat_space(rect.br_corner()));
(i.e. maps a rectangle from image space to feature space)
!*/
const point feat_to_image_space (
const point& p
) const;
/*!
ensures
- returns BASE_FE.feat_to_image_space(p)
I.e. returns the location in the input image space corresponding to the center
of the local feature at point p. In other words, this function computes
the inverse of image_to_feat_space(). Note that it may only do so approximately,
since more than one image location might correspond to the same local feature.
That is, image_to_feat_space() might not be invertible so this function gives
the closest possible result.
!*/
const rectangle feat_to_image_space (
const rectangle& rect
) const;
/*!
ensures
- returns BASE_FE.feat_to_image_space(rect)
I.e. return rectangle(feat_to_image_space(rect.tl_corner()), feat_to_image_space(rect.br_corner()));
(i.e. maps a rectangle from feature space to image space)
!*/
};
// ----------------------------------------------------------------------------------------
template <
typename T,
typename U
>
void serialize (
const hashed_feature_image<T,U>& item,
std::ostream& out
);
/*!
provides serialization support
!*/
// ----------------------------------------------------------------------------------------
template <
typename T,
typename U
>
void deserialize (
hashed_feature_image<T,U>& item,
std::istream& in
);
/*!
provides deserialization support
!*/
// ----------------------------------------------------------------------------------------
}
#endif // DLIB_HASHED_IMAGE_FEATUrES_ABSTRACT_Hh_
|