BFFaceFinder.h revision 7f81d9b6fa7f2ec161b682622db577a28c90b49f
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