|
| 1 | +========================================================================== |
| 2 | +PassportEye: Python tools for image processing of identification documents |
| 3 | +========================================================================== |
| 4 | + |
| 5 | +The package provides tools for recognizing machine readable zones (MRZ) from scanned identification documents. |
| 6 | +The documents may be located rather arbitrarily on the page - the code tries to find anything resembling a MRZ |
| 7 | +and parse it from there. |
| 8 | + |
| 9 | +The recognition procedure may be rather slow - around 10 or more seconds for some documents. Its precision is |
| 10 | +not perfect, yet seemingly decent as far as test documents available to the developer were concerned - in |
| 11 | +around 80% of the cases, whenever there is a clearly visible MRZ on a page, the system will recognize it and extract the text |
| 12 | +to the best of the abilities of the underlying OCR engine (Google Tesseract). |
| 13 | + |
| 14 | +The failed examples seem to be most often either clearly badly scanned documents, where text is way too blurred, or, |
| 15 | +more seriously, some types of IDs (Romanian being one example), where the MRZ is too close to the remaining part of the card - |
| 16 | +a situation not accounted for too well by the current algorithm. |
| 17 | + |
| 18 | +Installation |
| 19 | +------------ |
| 20 | + |
| 21 | +If you have obtained this package in source form, you can install it using the standard approach of doing:: |
| 22 | + |
| 23 | + $ python setup.py install |
| 24 | + |
| 25 | +In addition, you must have the `Tesseract OCR <https://github.com/tesseract-ocr>`_ installed and added to the system path: the ``tesseract`` tool must be |
| 26 | +accessible at the command line. |
| 27 | + |
| 28 | +Usage |
| 29 | +----- |
| 30 | + |
| 31 | +On installation, the package installs a standalone tool ``mrz`` into your Python scripts path. Running:: |
| 32 | + |
| 33 | + $ mrz <filename> |
| 34 | + |
| 35 | +will process a given filename, extracting the MRZ information it finds and printing it out in tabular form. |
| 36 | +Running ``mrz --json <filename>`` will output the same information in JSON. Running ``mrz --save-roi <roi.png>`` will, |
| 37 | +in addition, extract the detected MRZ ("region of interest") into a separate png file for further exploration. |
| 38 | +Note that the tool provides a limited support for PDF files -- it attempts to extract the first DCT-encoded image |
| 39 | +from the PDF and applies the recognition on it. This seems to work fine with most scanner-produced one-page PDFs, but |
| 40 | +has not been tested extensively. |
| 41 | + |
| 42 | +In order to use the recognition function in Python code, simply do:: |
| 43 | + |
| 44 | + >> from passporteye import read_mrz |
| 45 | + >> mrz = read_mrz(image_filename) |
| 46 | + |
| 47 | +The returned object (unless it is None, which means no ROI was detected) contains the fields extracted from the MRZ along |
| 48 | +with some metainformation. For the description of the available fields, see the docstring for the `passporteye.mrz.text.MRZ` class. |
| 49 | +Note that you can convert the object to a dictionary using the ``to_dict()`` method. |
| 50 | + |
| 51 | +If you want to have the ROI reported alongside the MRZ, call the ``read_mrz`` function as follows:: |
| 52 | + |
| 53 | + >> mrz = read_mrz(image_filename, save_roi=True) |
| 54 | + |
| 55 | +The ROI can then be accessed as ``mrz.aux['roi']`` -- it is a numpy ndarray, representing the (grayscale) image region where the OCR was applied. |
| 56 | + |
| 57 | +For more flexibility, you may instead use a ``MRZPipeline`` object, which will provide you access to all intermediate computations as follows:: |
| 58 | + |
| 59 | + >> from passporteye.mrz.image import MRZPipeline |
| 60 | + >> p = MRZPipeline(filename) |
| 61 | + >> mrz = p.result |
| 62 | + |
| 63 | +The "pipeline" object stores the intermediate computations in its ``data`` dictionary. Although you need to understand the underlying algorithm |
| 64 | +to make sense of it, sometimes it may provide for insightful visualizations. This code, for example, will plot the binarized version of the original image |
| 65 | +which is used in the algorithm to extract ROIs alongside the boxes corresponding to the extracted ROIs:: |
| 66 | + |
| 67 | + >> imshow(p['img_binary']) |
| 68 | + >> for b in p['boxes']: |
| 69 | + .. plot(b.points[:,1], b.points[:,0], c='b') |
| 70 | + .. b.plot() |
| 71 | + |
| 72 | +Development |
| 73 | +----------- |
| 74 | + |
| 75 | +If you plan to develop or debug the package, consider installing it by using:: |
| 76 | + |
| 77 | + $ python setup.py develop |
| 78 | + |
| 79 | +rather than ``setup.py install``. The package contains a basic set of smoke tests. To run those you should first make sure you have |
| 80 | +`pytest` installed:: |
| 81 | + |
| 82 | + $ pip install pytest |
| 83 | + |
| 84 | +You can then run the tests by typing:: |
| 85 | + |
| 86 | + $ py.test |
| 87 | + |
| 88 | +At the root of the source distribution. |
| 89 | + |
| 90 | +The command-line script ``evaluate_mrz`` can be used to assess the performance of the current recognition pipeline on a set |
| 91 | +of sample images: this is useful if you want to see the effects of changes to the code. Just run:: |
| 92 | + |
| 93 | + $ evaluate_mrz -j 4 |
| 94 | + |
| 95 | +(where ``-j 4`` would request to use 4 cores in parallel). The same script may be used to run the recognition pipeline on a |
| 96 | +given directory of images, sorting successes and failures, see ``evaluate_mrz -h`` for options. |
| 97 | + |
| 98 | + |
| 99 | +Contributing |
| 100 | +------------ |
| 101 | + |
| 102 | +Feel free to contribute or report issues via Github: https://github.com/konstantint/PassportEye |
| 103 | + |
| 104 | +Copyright & License |
| 105 | +------------------- |
| 106 | + |
| 107 | +Copyright: 2016, Konstantin Tretyakov. |
| 108 | +License: MIT |
0 commit comments