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