auto import from //depot/cupcake/@135843
[android/platform/external/neven.git] / Embedded / common / src / b_APIEm / BFFaceFinder.h
1 /*
2  * Copyright (C) 2008 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 #ifndef bpi_BF_FACE_FINDER_EM_H
18 #define bpi_BF_FACE_FINDER_EM_H
19
20 /* ---- includes ----------------------------------------------------------- */
21
22 #include "b_BasicEm/Context.h"
23 #include "b_APIEm/FaceFinder.h"
24 #include "b_BitFeatureEm/ScanDetector.h"
25
26 /* ---- related objects  --------------------------------------------------- */
27
28 struct bpi_DCR;
29
30 /* ---- typedefs ----------------------------------------------------------- */
31
32 /* ---- constants ---------------------------------------------------------- */
33
34 /* data format version number */
35 #define bpi_BF_FACE_FINDER_VERSION 100
36
37 /* ---- object definition -------------------------------------------------- */
38
39 /** Face Finder using ractangle features */
40 struct bpi_BFFaceFinder
41 {
42         /* ---- private data --------------------------------------------------- */
43
44         /** base object */
45         struct bpi_FaceFinder baseE;
46
47         /* number of detected faces in last call of multiProcess in face data buffer */
48         uint32 detectedFacesE;
49
50         /* number of available faces in last call of multiProcess in face data buffer */
51         uint32 availableFacesE;
52
53         /* pointer to face data buffer */
54         int32* faceDataBufferE;
55
56         /* ---- public data ---------------------------------------------------- */
57
58         /* detector */
59         struct bbf_ScanDetector detectorE;
60 };
61
62 /* ---- associated objects ------------------------------------------------- */
63
64 /* ---- external functions ------------------------------------------------- */
65
66 /* ---- \ghd{ constructor/destructor } ------------------------------------- */
67
68 /** initializes module */
69 void bpi_BFFaceFinder_init( struct bbs_Context* cpA,
70                                                     struct bpi_BFFaceFinder* ptrA );
71
72 /** destroys module */
73 void bpi_BFFaceFinder_exit( struct bbs_Context* cpA,
74                                                     struct bpi_BFFaceFinder* ptrA );
75
76 /* ---- \ghd{ operators } -------------------------------------------------- */
77
78 /** copies module */
79 void bpi_BFFaceFinder_copy( struct bbs_Context* cpA,
80                                                     struct bpi_BFFaceFinder* ptrA, 
81                                                         const struct bpi_BFFaceFinder* srcPtrA );
82
83 /** determines equality of parameters */
84 flag bpi_BFFaceFinder_equal( struct bbs_Context* cpA,
85                                                          const struct bpi_BFFaceFinder* ptrA, 
86                                                          const struct bpi_BFFaceFinder* srcPtrA );
87
88 /* ---- \ghd{ query functions } -------------------------------------------- */
89
90 /** minimum eye distance (pixel) */
91 uint32 bpi_BFFaceFinder_getMinEyeDistance( const struct bpi_BFFaceFinder* ptrA );
92
93 /** maximum eye distance (pixel) */
94 uint32 bpi_BFFaceFinder_getMaxEyeDistance( const struct bpi_BFFaceFinder* ptrA );
95
96 /* ---- \ghd{ modify functions } ------------------------------------------- */
97
98 /** minimum eye distance (pixel) */
99 void bpi_BFFaceFinder_setMinEyeDistance( struct bbs_Context* cpA,
100                                                                                  struct bpi_BFFaceFinder* ptrA, 
101                                                                                  uint32 distA );
102
103 /** maximum eye distance (pixel) */
104 void bpi_BFFaceFinder_setMaxEyeDistance( struct bbs_Context* cpA,
105                                                                                  struct bpi_BFFaceFinder* ptrA, 
106                                                                                  uint32 distA );
107
108 /* ---- \ghd{ memory I/O } ------------------------------------------------- */
109
110 /** size object needs when written to memory */
111 uint32 bpi_BFFaceFinder_memSize( struct bbs_Context* cpA,
112                                                                  const struct bpi_BFFaceFinder* ptrA );
113
114 /** writes object to memory; returns number of 16-bit words written */
115 uint32 bpi_BFFaceFinder_memWrite( struct bbs_Context* cpA,
116                                                                   const struct bpi_BFFaceFinder* ptrA, 
117                                                               uint16* memPtrA );
118
119 /** reads object from memory; returns number of 16-bit words read 
120  * Note: Before executing this function the maximum image dimensions must be specified 
121  * through function bpi_BFFaceFinder_setMaxImageSize. This is to ensure proper allocation 
122  * of internal memory. Otherwise this function will cause an exception.
123  */
124 uint32 bpi_BFFaceFinder_memRead( struct bbs_Context* cpA,
125                                                                  struct bpi_BFFaceFinder* ptrA, 
126                                                                  const uint16* memPtrA,
127                                                              struct bbs_MemTbl* mtpA );
128
129 /* ---- \ghd{ exec functions } --------------------------------------------- */
130
131 /** processes image for single face detection; 
132  *  returns confidence ( 8.24 ) 
133  *  fills external id cluster with node positions and ids
134  *
135  *  If roiPtrA is NULL, the whole image is considered for processsing 
136  *  otherwise *roiPtrA specifies a section of the original image to which
137  *  processing is limited. All coordinates refer to that section and must 
138  *  eventually be adjusted externally.
139  *  The roi rectangle must not include pixels outside of the original image
140  *  (checked -> error). The rectangle may be of uneven width.
141  *
142  *  offsPtrA points to an offset vector (whole pixels) that is to be added to
143  *  cluster coordinates in order to obtain image coordinates
144  *
145  */
146 int32 bpi_BFFaceFinder_process( struct bbs_Context* cpA,
147                                                             const struct bpi_BFFaceFinder* ptrA, 
148                                                             void* imagePtrA,
149                                                             uint32 imageWidthA,
150                                                                 uint32 imageHeightA,
151                                                                 const struct bts_Int16Rect* roiPtrA,
152                                                                 struct bts_Int16Vec2D* offsPtrA,
153                                                                 struct bts_IdCluster2D* idClusterPtrA );
154
155 /** Processes integral image for multiple face detection; 
156  *  returns number of faces detected 
157  *  return pointer to faceBuffer (intermediate data format)
158  *  call getFace() to retrieve face information from buffer.
159  *  *faceDataBufferPtrA is set to the address of an internal buffer that is valid until the next image processing
160  *
161  *  Positions are sorted by confidence (highest confidence first)
162  *
163  *  When this function returns 0 (no face detected) faceDataBuffer
164  *  still contains one valid entry retrievable by getFace() that 
165  *  represents the most likely position. The confidence is then below
166  *  or equal 0.5.
167  *
168  *  If roiPtrA is NULL, the whole image is considered for processsing 
169  *  otherwise *roiPtrA specifies a section of the original image to which
170  *  processing is limited. All coordinates refer to that section and must 
171  *  eventually be adjusted externally.
172  *  The roi rectangle must not include pixels outside of the original image
173  *  (checked -> error). The rectangle may be of uneven width.
174  */
175 uint32 bpi_BFFaceFinder_multiProcess( struct bbs_Context* cpA,
176                                                                           const struct bpi_BFFaceFinder* ptrA, 
177                                                                           void* imagePtrA,
178                                                                           uint32 imageWidthA,
179                                                                           uint32 imageHeightA,
180                                                                           const struct bts_Int16Rect* roiPtrA );
181
182 /** Extracts a single face from a face buffer that was previously filled with face data by function 
183  *  multiProcess(). 
184  *  returns confidence ( 8.24 ) 
185  *  Fills external id cluster with node positions and ids
186  *
187  *  offsPtrA points to an offset vector (whole pixels) that is to be added to
188  *  cluster coordinates in order to obtain image coordinates
189  */
190 uint32 bpi_BFFaceFinder_getFace( struct bbs_Context* cpA,
191                                                                  const struct bpi_BFFaceFinder* ptrA, 
192                                                                  uint32 indexA,
193                                                                  struct bts_Int16Vec2D* offsPtrA,
194                                                                  struct bts_IdCluster2D* idClusterPtrA );
195
196 /** Extracts a single face from a face buffer that was previously filled with face data by function 
197  *  multiProcess(). 
198  *  returns confidence ( 8.24 ) 
199  *  provides 
200  *              - id cluster with node positions and ids
201  *              - confidence
202  */
203 void bpi_BFFaceFinder_getFaceDCR( struct bbs_Context* cpA,
204                                                                   const struct bpi_BFFaceFinder* ptrA, 
205                                                                   uint32 indexA,
206                                                                   struct bpi_DCR* dcrPtrA );
207
208 /** this function must be executed before calling _memRead */
209 void bpi_BFFaceFinder_setMaxImageSize( struct bbs_Context* cpA,
210                                                                            struct bpi_BFFaceFinder* ptrA, 
211                                                                            uint32 maxImageWidthA,
212                                                                            uint32 maxImageHeightA );
213
214 /** initializes some parameters prior to reading  
215  *  Overload of vpSetParams
216  *  wraps function setMaxImageSize
217  */ 
218 void bpi_BFFaceFinder_setParams( struct bbs_Context* cpA,
219                                                                  struct bpi_FaceFinder* ptrA, 
220                                                                  uint32 maxImageWidthA,
221                                                                  uint32 maxImageHeightA );
222
223 /** sets detection range
224  *  Overload of vpSetParams
225  */
226 void bpi_BFFaceFinder_setRange( struct bbs_Context* cpA,
227                                                                 struct bpi_FaceFinder* ptrA, 
228                                                                 uint32 minEyeDistanceA,
229                                                                 uint32 maxEyeDistanceA );
230
231 /** Single face processing function; returns confidence (8.24)  
232  *  Overload of vpProcess
233  *  wraps function process
234  */ 
235 int32 bpi_BFFaceFinder_processDcr( struct bbs_Context* cpA,
236                                                                    const struct bpi_FaceFinder* ptrA, 
237                                                            struct bpi_DCR* dcrPtrA );
238
239 /** Multiple face processing function; returns number of faces detected 
240  *  Overload of vpPutDcr
241  *  wraps function multiProcess
242  */ 
243 int32 bpi_BFFaceFinder_putDcr( struct bbs_Context* cpA,
244                                                            const struct bpi_FaceFinder* ptrA, 
245                                                            struct bpi_DCR* dcrPtrA );
246
247 /** Retrieves indexed face from face finder after calling PutDCR 
248  *  Overload of vpGetDcr
249  *  wraps function getFaceDCR
250  */ 
251 void bpi_BFFaceFinder_getDcr( struct bbs_Context* cpA,
252                                                           const struct bpi_FaceFinder* ptrA, 
253                                                           uint32 indexA,
254                                                           struct bpi_DCR* dcrPtrA );
255
256 #endif /* bpi_BF_FACE_FINDER_EM_H */