1 // Copyright (C) 2011 Davis E. King (davis@dlib.net) 2 // License: Boost Software License See LICENSE.txt for the full license. 3 #undef DLIB_PROJECTION_HASh_ABSTRACT_Hh_ 4 #ifdef DLIB_PROJECTION_HASh_ABSTRACT_Hh_ 5 6 #include "../matrix.h" 7 8 namespace dlib 9 { 10 11 // ---------------------------------------------------------------------------------------- 12 13 class projection_hash 14 { 15 /*! 16 WHAT THIS OBJECT REPRESENTS 17 This is a tool for hashing elements of a vector space into the integers. 18 It is intended to represent locality sensitive hashing functions such as 19 the popular random projection hashing method. 20 21 In particular, it represents hash functions of the form: 22 hash bit 0 = sign(rowm(P*v + O,0)) 23 hash bit 1 = sign(rowm(P*v + O,1)) 24 hash bit 2 = sign(rowm(P*v + O,2)) 25 ... 26 Where v is the vector to be hashed. The parameters of the projection 27 hash are the P and O matrices. 28 29 THREAD SAFETY 30 The const members of this object can be called concurrently from multiple 31 threads, however, any operation that modifies the state of an instance of 32 this object must serialize access to that instance. 33 !*/ 34 public: 35 36 projection_hash( 37 ); 38 /*! 39 ensures 40 - #get_projection_matrix().size() == 0 41 - #get_offset_matrix().size() == 0 42 !*/ 43 44 template <typename EXP1, typename EXP2> 45 projection_hash( 46 const matrix_exp<EXP1>& proj, 47 const matrix_exp<EXP2>& offset 48 ); 49 /*! 50 requires 51 - proj.nr() == offset.nr() 52 ensures 53 - #get_projection_matrix() == proj 54 - #get_offset_matrix() == offset 55 !*/ 56 57 const matrix<double>& get_projection_matrix ( 58 ) const; 59 /*! 60 ensures 61 - returns the P matrix discussed above in the WHAT THIS OBJECT REPRESENTS 62 section. 63 !*/ 64 65 const matrix<double,0,1>& get_offset_matrix ( 66 ) const; 67 /*! 68 ensures 69 - returns the O matrix discussed above in the WHAT THIS OBJECT REPRESENTS 70 section. 71 !*/ 72 73 unsigned long num_hash_bins ( 74 ) const; 75 /*! 76 ensures 77 - returns the number of possible outputs from this hashing function. 78 - Specifically, returns: std::pow(2, get_offset_matrix().size()) 79 !*/ 80 81 template <typename EXP> 82 unsigned long operator() ( 83 const matrix_exp<EXP>& v 84 ) const; 85 /*! 86 requires 87 - is_col_vector(v) == true 88 - v.size() == get_projection_matrix().nc() 89 - v.size() > 0 90 ensures 91 - hashes v into the range [0, num_hash_bins()) using the method 92 discussed in the WHAT THIS OBJECT REPRESENTS section. 93 !*/ 94 }; 95 96 // ---------------------------------------------------------------------------------------- 97 98 void serialize ( 99 const projection_hash& item, 100 std::ostream& out 101 ); 102 /*! 103 provides serialization support 104 !*/ 105 106 void deserialize ( 107 projection_hash& item, 108 std::istream& in 109 ); 110 /*! 111 provides deserialization support 112 !*/ 113 114 // ---------------------------------------------------------------------------------------- 115 116 } 117 118 #endif // DLIB_PROJECTION_HASh_ABSTRACT_Hh_ 119 120