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 */ 257