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
28struct 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 */
40struct 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 */
69void bpi_BFFaceFinder_init( struct bbs_Context* cpA,
70						    struct bpi_BFFaceFinder* ptrA );
71
72/** destroys module */
73void bpi_BFFaceFinder_exit( struct bbs_Context* cpA,
74						    struct bpi_BFFaceFinder* ptrA );
75
76/* ---- \ghd{ operators } -------------------------------------------------- */
77
78/** copies module */
79void bpi_BFFaceFinder_copy( struct bbs_Context* cpA,
80						    struct bpi_BFFaceFinder* ptrA,
81							const struct bpi_BFFaceFinder* srcPtrA );
82
83/** determines equality of parameters */
84flag 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) */
91uint32 bpi_BFFaceFinder_getMinEyeDistance( const struct bpi_BFFaceFinder* ptrA );
92
93/** maximum eye distance (pixel) */
94uint32 bpi_BFFaceFinder_getMaxEyeDistance( const struct bpi_BFFaceFinder* ptrA );
95
96/* ---- \ghd{ modify functions } ------------------------------------------- */
97
98/** minimum eye distance (pixel) */
99void bpi_BFFaceFinder_setMinEyeDistance( struct bbs_Context* cpA,
100										 struct bpi_BFFaceFinder* ptrA,
101										 uint32 distA );
102
103/** maximum eye distance (pixel) */
104void 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 */
111uint32 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 */
115uint32 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 */
124uint32 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 */
146int32 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 */
175uint32 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 */
190uint32 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 */
203void 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 */
209void 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 */
218void 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 */
226void 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 */
235int32 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 */
243int32 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 */
251void 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 */
257