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 %ignore fp_minutia;
 115
 116 /* Needed to get correct output from
 117    fp_dscv_print_get_driver_id and fp_dev_get_devtype */
 118 typedef unsigned int uint32_t;
 119 /* fp_driver_get_driver_id, fp_dscv_print_get_driver_id, fp_print_data_get_driver_id*/
 120 typedef unsigned short int uint16_t;
 121
 122 /* Fprint.get_data() */
 123 %cstring_output_allocate_size(char **print_data, int *len, free(*($1)));
 124 %inline %{
 125 void pyfp_print_get_data(char **print_data, int *len, struct fp_print_data *print)
 126 {
 127         *len = fp_print_data_get_data(print, (unsigned char**)print_data);
 128 }
 129 %}
 130 %ignore fp_print_data_get_data;
 131
 132 /* Img.get_data() */
 133 %cstring_output_allocate_size(char **img_data, int *len, "");
 134 %inline %{
 135 void pyfp_img_get_data(char **img_data, int *len, struct fp_img *img)
 136 {
 137         *img_data = fp_img_get_data(img);
 138         *len = fp_img_get_width(img) * fp_img_get_height(img);
 139 }
 140 %}
 141 %ignore fp_img_get_data;
 142
 143 /* Image.get_rgb_data() */
 144 %cstring_output_allocate_size(char **img_rgb_data, int *len, free(*($1)));
 145 %inline %{
 146 void pyfp_img_get_rgb_data(char **img_rgb_data, int *len, struct fp_img *img)
 147 {
 148         unsigned int i, j = 0;
 149         unsigned char *img_data = fp_img_get_data(img);
 150         *len = fp_img_get_width(img) * fp_img_get_height(img) * 3;
 151         (*img_rgb_data) = malloc(*len);
 152         for (i = 0; i < (*len)/3; i++) {
 153                 (*img_rgb_data)[j++] = img_data[i];
 154                 (*img_rgb_data)[j++] = img_data[i];
 155                 (*img_rgb_data)[j++] = img_data[i];
 156         }
 157 }
 158 %}
 159
 160 /* Wrappers to let Python yield the thread */
 161 %inline %{
 162 int pyfp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data, struct fp_img **img)
 163 {
 164         int ret;
 165         Py_BEGIN_ALLOW_THREADS
 166         ret = fp_enroll_finger_img(dev, print_data, img);
 167         Py_END_ALLOW_THREADS
 168         return ret;
 169 }
 170 int pyfp_verify_finger_img(struct fp_dev *dev, struct fp_print_data *enrolled_print, struct fp_img **img)
 171 {
 172         int ret;
 173         Py_BEGIN_ALLOW_THREADS
 174         ret = fp_verify_finger_img(dev, enrolled_print, img);
 175         Py_END_ALLOW_THREADS
 176         return ret;
 177 }
 178 int pyfp_identify_finger_img(struct fp_dev *dev, struct fp_print_data **print_gallery, size_t *match_offset, struct fp_img **img)
 179 {
 180         int ret;
 181         Py_BEGIN_ALLOW_THREADS
 182         ret = fp_identify_finger_img(dev, print_gallery, match_offset, img);
 183         Py_END_ALLOW_THREADS
 184         return ret;
 185 }
 186 int pyfp_dev_img_capture(struct fp_dev *dev, int unconditional, struct fp_img **image)
 187 {
 188         int ret;
 189         Py_BEGIN_ALLOW_THREADS
 190         ret = fp_dev_img_capture(dev, unconditional, image);
 191         Py_END_ALLOW_THREADS
 192         return ret;
 193 }
 194 %}
 195 %ignore fp_enroll_finger_img;
 196 %ignore fp_enroll_finger;
 197 %ignore fp_verify_finger_img;
 198 %ignore fp_verify_finger;
 199 %ignore fp_identify_finger_img;
 200 %ignore fp_identify_finger;
 201 %ignore fp_dev_img_capture;
 202
 203 /* --- partial copy of <libfprint/fprint.h> --- */
 204
 205 /*
 206  * Main definitions for libfprint
 207  * Copyright (C) 2007 Daniel Drake <dsd@gentoo.org>
 208  *
 209  * This library is free software; you can redistribute it and/or
 210  * modify it under the terms of the GNU Lesser General Public
 211  * License as published by the Free Software Foundation; either
 212  * version 2.1 of the License, or (at your option) any later version.
 213  *
 214  * This library is distributed in the hope that it will be useful,
 215  * but WITHOUT ANY WARRANTY; without even the implied warranty of
 216  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 217  * Lesser General Public License for more details.
 218  *
 219  * You should have received a copy of the GNU Lesser General Public
 220  * License along with this library; if not, write to the Free Software
 221  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 222  */
 223
 224 /* structs that applications are not allowed to peek into */
 225 struct fp_dscv_dev;
 226 struct fp_dscv_print;
 227 struct fp_dev;
 228 struct fp_driver;
 229 struct fp_print_data;
 230 struct fp_img;
 231
 232 /* misc/general stuff */
 233
 234 /** \ingroup print_data
 235  * Numeric codes used to refer to fingers (and thumbs) of a human. These are
 236  * purposely not available as strings, to avoid getting the library tangled up
 237  * in localization efforts.
 238  */
 239 enum fp_finger {
 240         LEFT_THUMB = 1, /** thumb (left hand) */
 241         LEFT_INDEX, /** index finger (left hand) */
 242         LEFT_MIDDLE, /** middle finger (left hand) */
 243         LEFT_RING, /** ring finger (left hand) */
 244         LEFT_LITTLE, /** little finger (left hand) */
 245         RIGHT_THUMB, /** thumb (right hand) */
 246         RIGHT_INDEX, /** index finger (right hand) */
 247         RIGHT_MIDDLE, /** middle finger (right hand) */
 248         RIGHT_RING, /** ring finger (right hand) */
 249         RIGHT_LITTLE, /** little finger (right hand) */
 250 };
 251
 252 /* Drivers */
 253 const char *fp_driver_get_name(struct fp_driver *drv);
 254 const char *fp_driver_get_full_name(struct fp_driver *drv);
 255 uint16_t fp_driver_get_driver_id(struct fp_driver *drv);
 256
 257 /* Device discovery */
 258 struct fp_dscv_dev **fp_discover_devs(void);
 259 void fp_dscv_devs_free(struct fp_dscv_dev **devs);
 260 struct fp_driver *fp_dscv_dev_get_driver(struct fp_dscv_dev *dev);
 261 uint32_t fp_dscv_dev_get_devtype(struct fp_dscv_dev *dev);
 262 int fp_dscv_dev_supports_print_data(struct fp_dscv_dev *dev,
 263         struct fp_print_data *print);
 264 int fp_dscv_dev_supports_dscv_print(struct fp_dscv_dev *dev,
 265         struct fp_dscv_print *print);
 266 struct fp_dscv_dev *fp_dscv_dev_for_print_data(struct fp_dscv_dev **devs,
 267         struct fp_print_data *print);
 268 struct fp_dscv_dev *fp_dscv_dev_for_dscv_print(struct fp_dscv_dev **devs,
 269         struct fp_dscv_print *print);
 270
 271 static inline uint16_t fp_dscv_dev_get_driver_id(struct fp_dscv_dev *dev)
 272 {
 273         return fp_driver_get_driver_id(fp_dscv_dev_get_driver(dev));
 274 }
 275
 276 /* Print discovery */
 277 struct fp_dscv_print **fp_discover_prints(void);
 278 void fp_dscv_prints_free(struct fp_dscv_print **prints);
 279 uint16_t fp_dscv_print_get_driver_id(struct fp_dscv_print *print);
 280 uint32_t fp_dscv_print_get_devtype(struct fp_dscv_print *print);
 281 enum fp_finger fp_dscv_print_get_finger(struct fp_dscv_print *print);
 282 int fp_dscv_print_delete(struct fp_dscv_print *print);
 283
 284 /* Device handling */
 285 struct fp_dev *fp_dev_open(struct fp_dscv_dev *ddev);
 286 void fp_dev_close(struct fp_dev *dev);
 287 struct fp_driver *fp_dev_get_driver(struct fp_dev *dev);
 288 int fp_dev_get_nr_enroll_stages(struct fp_dev *dev);
 289 uint32_t fp_dev_get_devtype(struct fp_dev *dev);
 290 int fp_dev_supports_print_data(struct fp_dev *dev, struct fp_print_data *data);
 291 int fp_dev_supports_dscv_print(struct fp_dev *dev, struct fp_dscv_print *print);
 292
 293 int fp_dev_supports_imaging(struct fp_dev *dev);
 294 int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
 295         struct fp_img **image);
 296 int fp_dev_get_img_width(struct fp_dev *dev);
 297 int fp_dev_get_img_height(struct fp_dev *dev);
 298
 299 /** \ingroup dev
 300  * Enrollment result codes returned from fp_enroll_finger().
 301  * Result codes with RETRY in the name suggest that the scan failed due to
 302  * user error. Applications will generally want to inform the user of the
 303  * problem and then retry the enrollment stage. For more info on the semantics
 304  * of interpreting these result codes and tracking enrollment process, see
 305  * \ref enrolling.
 306  */
 307 enum fp_enroll_result {
 308         /** Enrollment completed successfully, the enrollment data has been
 309          * returned to the caller. */
 310         FP_ENROLL_COMPLETE = 1,
 311         /** Enrollment failed due to incomprehensible data; this may occur when
 312          * the user scans a different finger on each enroll stage. */
 313         FP_ENROLL_FAIL,
 314         /** Enroll stage passed; more stages are need to complete the process. */
 315         FP_ENROLL_PASS,
 316         /** The enrollment scan did not succeed due to poor scan quality or
 317          * other general user scanning problem. */
 318         FP_ENROLL_RETRY = 100,
 319         /** The enrollment scan did not succeed because the finger swipe was
 320          * too short. */
 321         FP_ENROLL_RETRY_TOO_SHORT,
 322         /** The enrollment scan did not succeed because the finger was not
 323          * centered on the scanner. */
 324         FP_ENROLL_RETRY_CENTER_FINGER,
 325         /** The verification scan did not succeed due to quality or pressure
 326          * problems; the user should remove their finger from the scanner before
 327          * retrying. */
 328         FP_ENROLL_RETRY_REMOVE_FINGER,
 329 };
 330
 331 int fp_enroll_finger_img(struct fp_dev *dev, struct fp_print_data **print_data,
 332         struct fp_img **img);
 333
 334 /** \ingroup dev
 335  * Performs an enroll stage. See \ref enrolling for an explanation of enroll
 336  * stages. This function is just a shortcut to calling fp_enroll_finger_img()
 337  * with a NULL image parameter. Be sure to read the description of
 338  * fp_enroll_finger_img() in order to understand its behaviour.
 339  *
 340  * \param dev the device
 341  * \param print_data a location to return the resultant enrollment data from
 342  * the final stage. Must be freed with fp_print_data_free() after use.
 343  * \return negative code on error, otherwise a code from #fp_enroll_result
 344  */
 345 static inline int fp_enroll_finger(struct fp_dev *dev,
 346         struct fp_print_data **print_data)
 347 {
 348         return fp_enroll_finger_img(dev, print_data, NULL);
 349 }
 350
 351 /** \ingroup dev
 352  * Verification result codes returned from fp_verify_finger(). Return codes
 353  * are also shared with fp_identify_finger().
 354  * Result codes with RETRY in the name suggest that the scan failed due to
 355  * user error. Applications will generally want to inform the user of the
 356  * problem and then retry the verify operation.
 357  */
 358 enum fp_verify_result {
 359         /** The scan completed successfully, but the newly scanned fingerprint
 360          * does not match the fingerprint being verified against.
 361          * In the case of identification, this return code indicates that the
 362          * scanned finger could not be found in the print gallery. */
 363         FP_VERIFY_NO_MATCH = 0,
 364         /** The scan completed successfully and the newly scanned fingerprint does
 365          * match the fingerprint being verified, or in the case of identification,
 366          * the scanned fingerprint was found in the print gallery. */
 367         FP_VERIFY_MATCH = 1,
 368         /** The scan did not succeed due to poor scan quality or other general
 369          * user scanning problem. */
 370         FP_VERIFY_RETRY = FP_ENROLL_RETRY,
 371         /** The scan did not succeed because the finger swipe was too short. */
 372         FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
 373         /** The scan did not succeed because the finger was not centered on the
 374          * scanner. */
 375         FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
 376         /** The scan did not succeed due to quality or pressure problems; the user
 377          * should remove their finger from the scanner before retrying. */
 378         FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
 379 };
 380
 381 int fp_verify_finger_img(struct fp_dev *dev,
 382         struct fp_print_data *enrolled_print, struct fp_img **img);
 383
 384 /** \ingroup dev
 385  * Performs a new scan and verify it against a previously enrolled print. This
 386  * function is just a shortcut to calling fp_verify_finger_img() with a NULL
 387  * image output parameter.
 388  * \param dev the device to perform the scan.
 389  * \param enrolled_print the print to verify against. Must have been previously
 390  * enrolled with a device compatible to the device selected to perform the scan.
 391  * \return negative code on error, otherwise a code from #fp_verify_result
 392  * \sa fp_verify_finger_img()
 393  */
 394 static inline int fp_verify_finger(struct fp_dev *dev,
 395         struct fp_print_data *enrolled_print)
 396 {
 397         return fp_verify_finger_img(dev, enrolled_print, NULL);
 398 }
 399
 400 int fp_dev_supports_identification(struct fp_dev *dev);
 401 int fp_identify_finger_img(struct fp_dev *dev,
 402         struct fp_print_data **print_gallery, size_t *match_offset,
 403         struct fp_img **img);
 404
 405 /** \ingroup dev
 406  * Performs a new scan and attempts to identify the scanned finger against a
 407  * collection of previously enrolled fingerprints. This function is just a
 408  * shortcut to calling fp_identify_finger_img() with a NULL image output
 409  * parameter.
 410  * \param dev the device to perform the scan.
 411  * \param print_gallery NULL-terminated array of pointers to the prints to
 412  * identify against. Each one must have been previously enrolled with a device
 413  * compatible to the device selected to perform the scan.
 414  * \param match_offset output location to store the array index of the matched
 415  * gallery print (if any was found). Only valid if FP_VERIFY_MATCH was
 416  * returned.
 417  * \return negative code on error, otherwise a code from #fp_verify_result
 418  * \sa fp_identify_finger_img()
 419  */
 420 static inline int fp_identify_finger(struct fp_dev *dev,
 421         struct fp_print_data **print_gallery, size_t *match_offset)
 422 {
 423         return fp_identify_finger_img(dev, print_gallery, match_offset, NULL);
 424 }
 425
 426 /* Data handling */
 427 int fp_print_data_load(struct fp_dev *dev, enum fp_finger finger,
 428         struct fp_print_data **data);
 429 int fp_print_data_from_dscv_print(struct fp_dscv_print *print,
 430         struct fp_print_data **data);
 431 int fp_print_data_save(struct fp_print_data *data, enum fp_finger finger);
 432 int fp_print_data_delete(struct fp_dev *dev, enum fp_finger finger);
 433 void fp_print_data_free(struct fp_print_data *data);
 434 size_t fp_print_data_get_data(struct fp_print_data *data, unsigned char **ret);
 435 struct fp_print_data *fp_print_data_from_data(unsigned char *buf,
 436         size_t buflen);
 437 uint16_t fp_print_data_get_driver_id(struct fp_print_data *data);
 438 uint32_t fp_print_data_get_devtype(struct fp_print_data *data);
 439
 440 /* Image handling */
 441
 442 /** \ingroup img */
 443 /*
 444 struct fp_minutia {
 445         int x;
 446         int y;
 447         int ex;
 448         int ey;
 449         int direction;
 450         double reliability;
 451         int type;
 452         int appearing;
 453         int feature_id;
 454         int *nbrs;
 455         int *ridge_counts;
 456         int num_nbrs;
 457 };
 458 */
 459 int fp_img_get_height(struct fp_img *img);
 460 int fp_img_get_width(struct fp_img *img);
 461 unsigned char *fp_img_get_data(struct fp_img *img);
 462 int fp_img_save_to_file(struct fp_img *img, char *path);
 463 void fp_img_standardize(struct fp_img *img);
 464 struct fp_img *fp_img_binarize(struct fp_img *img);
 465 struct fp_minutia **fp_img_get_minutiae(struct fp_img *img, int *nr_minutiae);
 466 void fp_img_free(struct fp_img *img);
 467
 468 /* Library */
 469 int fp_init(void);
 470 void fp_exit(void);
 471
 472
 473 /* -------- END OF COPY ---------- */
 474
 475
 476 /* Device.identify_finger() */
 477 %inline %{
 478 struct pyfp_print_data_array {
 479         size_t size;
 480         size_t used;
 481         struct fp_print_data * list[0];
 482 };
 483 %}
 484 %extend pyfp_print_data_array {
 485         pyfp_print_data_array(size_t size)
 486         {
 487                 struct pyfp_print_data_array *x;
 488                 x = calloc(1, sizeof(struct pyfp_print_data_array) +
 489                                 sizeof(struct fp_print_data *) * (size + 1)); /* +1 for NULL termination */
 490                 x->size = size;
 491                 return x;
 492         }
 493         ~pyfp_print_data_array()
 494         {
 495                 free($self);
 496         }
 497         void append(struct fp_print_data *print)
 498         {
 499                 if ($self->size <= $self->used) {
 500                         PyErr_SetString(PyExc_OverflowError, "programming error: pyfp_print_data_array list overflow");
 501                         return;
 502                 }
 503                 $self->list[$self->used] = print;
 504                 $self->used++;
 505         }
 506         struct fp_print_data ** pyfp_print_data_array_list_get()
 507         {
 508                 return $self->list;
 509         }
 510 };
 511
 512 %inline %{
 513
 514 /* DiscoveredDevices.__init__() */
 515 struct fp_dscv_dev * pyfp_deref_dscv_dev_ptr (struct fp_dscv_dev **ptr, int i)
 516 {
 517         return ptr[i];
 518 }
 519
 520 /* class DiscoveredPrints(list): */
 521 struct fp_dscv_print * pyfp_deref_dscv_print_ptr(struct fp_dscv_print **ptr, int i)
 522 {
 523         return ptr[i];
 524 }
 525
 526
 527 %}