pyfprint/pyfprint_swig.i

   1 /*
   2 ############################################################################
   3 #    Copyright (C) 2008 by Lukas Sandström                                 #
   4 #    luksan@gmail.com                                                      #
   5 #                                                                          #
   6 #    This program is free software; you can redistribute it and/or modify  #
   7 #    it under the terms of the GNU General Public License as published by  #
   8 #    the Free Software Foundation; either version 2 of the License, or     #
   9 #    (at your option) any later version.                                   #
  10 #                                                                          #
  11 #    This program is distributed in the hope that it will be useful,       #
  12 #    but WITHOUT ANY WARRANTY; without even the implied warranty of        #
  13 #    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         #
  14 #    GNU General Public License for more details.                          #
  15 #                                                                          #
  16 #    You should have received a copy of the GNU General Public License     #
  17 #    along with this program; if not, write to the                         #
  18 #    Free Software Foundation, Inc.,                                       #
  19 #    59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             #
  20 ############################################################################
  21 */
  22
  23 %module pyfprint_swig
  24 %{
  25 #include <libfprint/fprint.h>
  26 #include <errno.h>
  27 %}
  28
  29 %feature("autodoc", "1");
  30
  31 %include <typemaps.i>
  32 %include <cdata.i>
  33 %include <carrays.i>
  34 %include <cstring.i>
  35
  36 %nodefaultctor;
  37
  38 /* fp_dev_img_capture,  fp_enroll_finger_img, fp_verify_finger_img, fp_identify_finger_img */
  39 %typemap(argout) struct fp_img ** {
  40     PyObject *o;
  41     o = SWIG_NewPointerObj(*$1, $*1_descriptor, 1);
  42     $result = SWIG_AppendOutput($result, o);
  43     /* FIXME: is a PY_DECREF(o) needed here ?*/
  44 }
  45 %typemap(in, numinputs=0) struct fp_img **(struct fp_img *img) {
  46     $1 = &img;
  47 }
  48
  49 /* fp_enroll_finger_img */
  50 %typemap(argout) struct fp_print_data **print_data = struct fp_img **;
  51 %typemap(in, numinputs=0) struct fp_print_data **print_data(struct fp_print_data *data) {
  52     $1 = &data;
  53 }
  54
  55 /* fp_print_data_load, fp_print_data_from_dscv_print */
  56 %apply struct fp_print_data **print_data { struct fp_print_data **data };
  57
  58 /* fp_identify_finger */
  59 %apply unsigned long *OUTPUT { size_t *match_offset };
  60
  61 /* fp_print_data_from_data */
  62 %apply (char *STRING, int LENGTH) { (unsigned char *buf, size_t buflen) };
  63
  64 /* fp_img_get_minutiae */
  65 %apply int *OUTPUT { int *nr_minutiae };
  66
  67 /* Tell SWIG that we're freeing the pointers */
  68 %delobject fp_dscv_devs_free;
  69 %delobject fp_img_free;
  70 %delobject fp_print_data_free;
  71 %delobject fp_dscv_prints_free;
  72 %delobject fp_dev_close;
  73 %delobject pyfp_free_print_data_array;
  74
  75 /* Tell SWIG that we're allocating new objects */
  76 %newobject pyfp_alloc_print_data_array;
  77 %newobject fp_dev_open;
  78
  79 /* Image.get_minutiae() */
  80 %inline %{
  81 struct fp_minutia * pyfp_deref_minutiae(struct fp_minutia **ptr, int i)
  82 {
  83         return ptr[i];
  84 }
  85
  86 %}
  87 /* The struct needs to be redefined as const, otherwise swig will generate _set_ methods for the members. */
  88 struct fp_minutia {
  89         const int x;
  90         const int y;
  91         const int ex;
  92         const int ey;
  93         const int direction;
  94         const double reliability;
  95         const int type;
  96         const int appearing;
  97         const int feature_id;
  98         int * const nbrs;
  99         int * const ridge_counts;
 100         const int num_nbrs;
 101
 102         %extend {
 103                 /* A constructor that accepts pre-allocated structs */
 104                 fp_minutia(struct fp_minutia *ptr)
 105                 {
 106                         return ptr;
 107                 }
 108                 ~fp_minutia()
 109                 {
 110                         /* Don't free() fp_minutia *. They are free'd together with the fp_img. */ ;
 111                 }
 112         };
 113 };
 114
 115 /* Needed to get correct output from
 116    fp_dscv_print_get_driver_id and fp_dev_get_devtype */
 117 typedef unsigned int uint32_t;
 118 /* fp_driver_get_driver_id, fp_dscv_print_get_driver_id, fp_print_data_get_driver_id*/
 119 typedef unsigned short int uint16_t;
 120
 121 /* Fprint.get_data() */
 122 %cstring_output_allocate_size(char **print_data, int *len, free(*($1)));
 123 %inline %{
 124 void pyfp_print_get_data(char **print_data, int *len, struct fp_print_data *print)
 125 {
 126         *len = fp_print_data_get_data(print, (unsigned char**)print_data);
 127 }
 128 %}
 129
 130 /* Img.get_data() */
 131 %cstring_output_allocate_size(char **img_data, int *len, "");
 132 %inline %{
 133 void pyfp_img_get_data(char **img_data, int *len, struct fp_img *img)
 134 {
 135         *img_data = fp_img_get_data(img);
 136         *len = fp_img_get_width(img) * fp_img_get_height(img);
 137 }
 138 %}
 139
 140 /* Image.get_rgb_data() */
 141 %cstring_output_allocate_size(char **img_rgb_data, int *len, free(*($1)));
 142 %inline %{
 143 void pyfp_img_get_rgb_data(char **img_rgb_data, int *len, struct fp_img *img)
 144 {
 145         unsigned int i, j = 0;
 146         unsigned char *img_data = fp_img_get_data(img);
 147         *len = fp_img_get_width(img) * fp_img_get_height(img) * 3;
 148         (*img_rgb_data) = malloc(*len);
 149         for (i = 0; i < (*len)/3; i++) {
 150                 (*img_rgb_data)[j++] = img_data[i];
 151                 (*img_rgb_data)[j++] = img_data[i];
 152                 (*img_rgb_data)[j++] = img_data[i];
 153         }
 154 }
 155 %}
 156
 157 /* Wrappers to let Python yield the thread */
 158 %inline %{
 159 int pyfp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data, struct fp_img **img)
 160 {
 161         int ret;
 162         Py_BEGIN_ALLOW_THREADS
 163         ret = fp_enroll_finger_img(dev, print_data, img);
 164         Py_END_ALLOW_THREADS
 165         return ret;
 166 }
 167 int pyfp_verify_finger_img(struct fp_dev *dev, struct fp_print_data *enrolled_print, struct fp_img **img)
 168 {
 169         int ret;
 170         Py_BEGIN_ALLOW_THREADS
 171         ret = fp_verify_finger_img(dev, enrolled_print, img);
 172         Py_END_ALLOW_THREADS
 173         return ret;
 174 }
 175 int pyfp_identify_finger_img(struct fp_dev *dev, struct fp_print_data **print_gallery, size_t *match_offset, struct fp_img **img)
 176 {
 177         int ret;
 178         Py_BEGIN_ALLOW_THREADS
 179         ret = fp_identify_finger_img(dev, print_gallery, match_offset, img);
 180         Py_END_ALLOW_THREADS
 181         return ret;
 182 }
 183 int pyfp_dev_img_capture(struct fp_dev *dev, int unconditional, struct fp_img **image)
 184 {
 185         int ret;
 186         Py_BEGIN_ALLOW_THREADS
 187         ret = fp_dev_img_capture(dev, unconditional, image);
 188         Py_END_ALLOW_THREADS
 189         return ret;
 190 }
 191 %}
 192
 193 /* Device.identify_finger() */
 194 %inline %{
 195 struct pyfp_print_data_array {
 196         size_t size;
 197         size_t used;
 198         struct fp_print_data * list[0];
 199 };
 200 %}
 201 %extend pyfp_print_data_array {
 202         pyfp_print_data_array(size_t size)
 203         {
 204                 struct pyfp_print_data_array *x;
 205                 x = calloc(1, sizeof(struct pyfp_print_data_array) +
 206                                 sizeof(struct fp_print_data *) * (size + 1)); /* +1 for NULL termination */
 207                 x->size = size;
 208                 return x;
 209         }
 210         ~pyfp_print_data_array()
 211         {
 212                 free($self);
 213         }
 214         void append(struct fp_print_data *print)
 215         {
 216                 if ($self->size <= $self->used) {
 217                         PyErr_SetString(PyExc_OverflowError, "programming error: pyfp_print_data_array list overflow");
 218                         return;
 219                 }
 220                 $self->list[$self->used] = print;
 221                 $self->used++;
 222         }
 223         struct fp_print_data ** pyfp_print_data_array_list_get()
 224         {
 225                 return $self->list;
 226         }
 227 };
 228
 229 %inline %{
 230
 231 /* DiscoveredDevices.__init__() */
 232 struct fp_dscv_dev * pyfp_deref_dscv_dev_ptr (struct fp_dscv_dev **ptr, int i)
 233 {
 234         return ptr[i];
 235 }
 236
 237 /* class DiscoveredPrints(list): */
 238 struct fp_dscv_print * pyfp_deref_dscv_print_ptr(struct fp_dscv_print **ptr, int i)
 239 {
 240         return ptr[i];
 241 }
 242
 243 %}
 244
 245 /* --- partial copy of <libfprint/fprint.h> --- */
 246
 247 /*
 248  * Main definitions for libfprint
 249  * Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
 250  *
 251  * This library is free software; you can redistribute it and/or
 252  * modify it under the terms of the GNU Lesser General Public
 253  * License as published by the Free Software Foundation; either
 254  * version 2.1 of the License, or (at your option) any later version.
 255  *
 256  * This library is distributed in the hope that it will be useful,
 257  * but WITHOUT ANY WARRANTY; without even the implied warranty of
 258  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 259  * Lesser General Public License for more details.
 260  *
 261  * You should have received a copy of the GNU Lesser General Public
 262  * License along with this library; if not, write to the Free Software
 263  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 264  */
 265
 266 /* structs that applications are not allowed to peek into */
 267 struct fp_dscv_dev;
 268 struct fp_dscv_print;
 269 struct fp_dev;
 270 struct fp_driver;
 271 struct fp_print_data;
 272 struct fp_img;
 273
 274 /* misc/general stuff */
 275
 276 /** \ingroup print_data
 277  * Numeric codes used to refer to fingers (and thumbs) of a human. These are
 278  * purposely not available as strings, to avoid getting the library tangled up
 279  * in localization efforts.
 280  */
 281 enum fp_finger {
 282         LEFT_THUMB = 1, /** thumb (left hand) */
 283         LEFT_INDEX, /** index finger (left hand) */
 284         LEFT_MIDDLE, /** middle finger (left hand) */
 285         LEFT_RING, /** ring finger (left hand) */
 286         LEFT_LITTLE, /** little finger (left hand) */
 287         RIGHT_THUMB, /** thumb (right hand) */
 288         RIGHT_INDEX, /** index finger (right hand) */
 289         RIGHT_MIDDLE, /** middle finger (right hand) */
 290         RIGHT_RING, /** ring finger (right hand) */
 291         RIGHT_LITTLE, /** little finger (right hand) */
 292 };
 293
 294 /* Drivers */
 295 const char *fp_driver_get_name(struct fp_driver *drv);
 296 const char *fp_driver_get_full_name(struct fp_driver *drv);
 297 uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
 298
 299 /* Device discovery */
 300 struct fp_dscv_dev **fp_discover_devs(void);
 301 void fp_dscv_devs_free(struct fp_dscv_dev **devs);
 302 struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
 303 uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
 304 int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
 305         struct fp_print_data *print);
 306 int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
 307         struct fp_dscv_print *print);
 308 struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
 309         struct fp_print_data *print);
 310 struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
 311         struct fp_dscv_print *print);
 312
 313 static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
 314 {
 315         return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
 316 }
 317
 318 /* Print discovery */
 319 struct fp_dscv_print **fp_discover_prints(void);
 320 void fp_dscv_prints_free(struct fp_dscv_print **prints);
 321 uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print);
 322 uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print);
 323 enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print);
 324 int fp_dscv_print_delete(struct fp_dscv_print *print);
 325
 326 /* Device handling */
 327 struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
 328 void fp_dev_close(struct fp_dev *dev);
 329 struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
 330 int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
 331 uint32_t fp_dev_get_devtype(struct fp_dev *dev);
 332 int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
 333 int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
 334
 335 int fp_dev_supports_imaging(struct fp_dev *dev);
 336 int fp_dev_get_img_width(struct fp_dev *dev);
 337 int fp_dev_get_img_height(struct fp_dev *dev);
 338
 339 /** \ingroup dev
 340  * Enrollment result codes returned from fp_enroll_finger().
 341  * Result codes with RETRY in the name suggest that the scan failed due to
 342  * user error. Applications will generally want to inform the user of the
 343  * problem and then retry the enrollment stage. For more info on the semantics
 344  * of interpreting these result codes and tracking enrollment process, see
 345  * \ref enrolling.
 346  */
 347 enum fp_enroll_result {
 348         /** Enrollment completed successfully, the enrollment data has been
 349          * returned to the caller. */
 350         FP_ENROLL_COMPLETE = 1,
 351         /** Enrollment failed due to incomprehensible data; this may occur when
 352          * the user scans a different finger on each enroll stage. */
 353         FP_ENROLL_FAIL,
 354         /** Enroll stage passed; more stages are need to complete the process. */
 355         FP_ENROLL_PASS,
 356         /** The enrollment scan did not succeed due to poor scan quality or
 357          * other general user scanning problem. */
 358         FP_ENROLL_RETRY = 100,
 359         /** The enrollment scan did not succeed because the finger swipe was
 360          * too short. */
 361         FP_ENROLL_RETRY_TOO_SHORT,
 362         /** The enrollment scan did not succeed because the finger was not
 363          * centered on the scanner. */
 364         FP_ENROLL_RETRY_CENTER_FINGER,
 365         /** The verification scan did not succeed due to quality or pressure
 366          * problems; the user should remove their finger from the scanner before
 367          * retrying. */
 368         FP_ENROLL_RETRY_REMOVE_FINGER,
 369 };
 370
 371 /** \ingroup dev
 372  * Verification result codes returned from fp_verify_finger(). Return codes
 373  * are also shared with fp_identify_finger().
 374  * Result codes with RETRY in the name suggest that the scan failed due to
 375  * user error. Applications will generally want to inform the user of the
 376  * problem and then retry the verify operation.
 377  */
 378 enum fp_verify_result {
 379         /** The scan completed successfully, but the newly scanned fingerprint
 380          * does not match the fingerprint being verified against.
 381          * In the case of identification, this return code indicates that the
 382          * scanned finger could not be found in the print gallery. */
 383         FP_VERIFY_NO_MATCH = 0,
 384         /** The scan completed successfully and the newly scanned fingerprint does
 385          * match the fingerprint being verified, or in the case of identification,
 386          * the scanned fingerprint was found in the print gallery. */
 387         FP_VERIFY_MATCH = 1,
 388         /** The scan did not succeed due to poor scan quality or other general
 389          * user scanning problem. */
 390         FP_VERIFY_RETRY = FP_ENROLL_RETRY,
 391         /** The scan did not succeed because the finger swipe was too short. */
 392         FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
 393         /** The scan did not succeed because the finger was not centered on the
 394          * scanner. */
 395         FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
 396         /** The scan did not succeed due to quality or pressure problems; the user
 397          * should remove their finger from the scanner before retrying. */
 398         FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
 399 };
 400
 401 int fp_dev_supports_identification(struct fp_dev *dev);
 402
 403 /* Data handling */
 404 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
 405         struct fp_print_data **data);
 406 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
 407         struct fp_print_data **data);
 408 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
 409 int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger);
 410 void fp_print_data_free(struct fp_print_data *data);
 411 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
 412         size_t buflen);
 413 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
 414 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
 415
 416 /* Image handling */
 417
 418 int fp_img_get_height(struct fp_img *img);
 419 int fp_img_get_width(struct fp_img *img);
 420 int fp_img_save_to_file(struct fp_img *img, char *path);
 421 void fp_img_standardize(struct fp_img *img);
 422 struct fp_img *fp_img_binarize(struct fp_img *img);
 423 struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
 424 void fp_img_free(struct fp_img *img);
 425
 426 /* Library */
 427 int fp_init(void);
 428 void fp_exit(void);
 429
 430 /* -------- END OF COPY ---------- */