mrzmini 0.1.0__py3-none-any.whl

mrzmini/__init__.py

@@ -0,0 +1,17 @@
+'''
+mrzmini: a minimal-footprint reimplementation of PassportEye's MRZ
+detection and reading pipeline.
+
+Only depends on numpy + Pillow (plus the external ``tesseract`` binary for OCR).
+The public interface mirrors PassportEye:
+
+    from mrzmini import read_mrz
+    mrz = read_mrz('passport.jpg')
+    print(mrz.to_dict())
+
+Original algorithm and code: Konstantin Tretyakov, PassportEye (MIT License).
+'''
+from .text import MRZ
+from .image import read_mrz, MRZPipeline
+
+__all__ = ['read_mrz', 'MRZ', 'MRZPipeline']

mrzmini/__main__.py

@@ -0,0 +1,28 @@
+"""Command-line entry point for mrzmini.
+
+Usage:
+    mrzmini <image-or-pdf> [...]
+    python -m mrzmini <image-or-pdf> [...]
+"""
+import sys
+import json
+
+from mrzmini import read_mrz
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        return
+    for path in sys.argv[1:]:
+        print("=" * 60)
+        print(path)
+        mrz = read_mrz(path)
+        if mrz is None:
+            print("  No MRZ found.")
+            continue
+        print(json.dumps(mrz.to_dict(), indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

mrzmini/geometry.py

@@ -0,0 +1,241 @@
+'''
+mrzmini.geometry: RotatedBox geometry, adapted from PassportEye's
+``passporteye/util/geometry.py``.
+
+Changes vs upstream (to drop heavy dependencies), behaviour preserved:
+  * ``sklearn.decomposition.PCA`` -> a small numpy SVD (see :func:`_pca`).
+    The resulting box (center/width/height/angle) is invariant to the sign of
+    the principal components, so sklearn's ``svd_flip`` convention need not be
+    reproduced.
+  * ``skimage.transform`` (``rotate`` / ``SimilarityTransform``) ->
+    :mod:`mrzmini.imageproc`.
+  * The matplotlib ``plot`` method is removed.
+
+Author of original: Konstantin Tretyakov. License: MIT.
+'''
+import numpy as np
+
+from .imageproc import rotate as _rotate, SimilarityTransform
+
+
+def _pca(points):
+    """Return ``(mean, components)`` matching ``sklearn.decomposition.PCA(2).fit``.
+
+    ``components`` rows are the principal axes ordered by descending variance
+    (row 0 = longest axis). ``transform(x) = (x - mean) @ components.T``.
+    """
+    mean = points.mean(axis=0)
+    centered = points - mean
+    # full_matrices=False -> Vt has shape (min(n,2), 2); singular values descending.
+    _u, _s, vt = np.linalg.svd(centered, full_matrices=False)
+    components = vt
+    if components.shape[0] < 2:
+        # Degenerate (all points collinear with <2 dims of variance): complete
+        # the basis with an orthogonal vector so downstream maths is well-defined.
+        v0 = components[0]
+        components = np.vstack([v0, [-v0[1], v0[0]]])
+    return mean, components
+
+
+class RotatedBox(object):
+    """
+    RotatedBox represents a rectangular box centered at (cx,cy) with dimensions width x height,
+    rotated by angle radians counterclockwise.
+
+    >>> RotatedBox.from_points([[0,0], [2,1], [0,1], [2,0]])
+    RotatedBox(cx=1.0, cy=0.5, width=2.0, height=1.0, angle=0.0)
+    """
+
+    def __init__(self, center, width, height, angle, points=None):
+        """Creates a new RotatedBox.
+
+        :param points: This parameter may be used to indicate the set of points used to create the box.
+        """
+        self.center = np.asarray(center, dtype=np.float64)
+        self.width = width
+        self.height = height
+        self.angle = angle
+        self.points = points
+
+    def __repr__(self):
+        return "RotatedBox(cx={0}, cy={1}, width={2}, height={3}, angle={4})".format(self.cx, self.cy, self.width, self.height, self.angle)
+
+    @property
+    def cx(self):
+        return self.center[0]
+
+    @property
+    def cy(self):
+        return self.center[1]
+
+    @property
+    def area(self):
+        return self.width * self.height
+
+    def approx_equal(self, center, width, height, angle, tol=1e-6):
+        "Method mainly useful for testing"
+        return abs(self.cx - center[0]) < tol and abs(self.cy - center[1]) < tol and abs(self.width - width) < tol and \
+               abs(self.height - height) < tol and abs(self.angle - angle) < tol
+
+    def rotated(self, rotation_center, angle):
+        """Returns a RotatedBox that is obtained by rotating this box around a given center by a given angle.
+
+        >>> assert RotatedBox([2, 2], 2, 1, 0.1).rotated([1, 1], np.pi/2).approx_equal([0, 2], 2, 1, np.pi/2+0.1)
+        """
+        rot = np.array([[np.cos(angle), np.sin(angle)], [-np.sin(angle), np.cos(angle)]])
+        t = np.asarray(rotation_center, dtype=np.float64)
+        new_c = np.dot(rot.T, (self.center - t)) + t
+        return RotatedBox(new_c, self.width, self.height, (self.angle+angle) % (np.pi*2))
+
+    def as_poly(self, margin_width=0, margin_height=0):
+        """Converts this box to a polygon, i.e. 4x2 array, representing the four corners starting from lower left to upper left counterclockwise.
+
+        :param margin_width: The additional "margin" that will be added to the box along its width dimension (from both sides) before conversion.
+        :param margin_height: The additional "margin" that will be added to the box along its height dimension (from both sides) before conversion.
+
+        >>> RotatedBox([0, 0], 4, 2, 0).as_poly()
+        array([[-2., -1.],
+               [ 2., -1.],
+               [ 2.,  1.],
+               [-2.,  1.]])
+        >>> RotatedBox([0, 0], 4, 2, np.pi/2).as_poly()
+        array([[ 1., -2.],
+               [ 1.,  2.],
+               [-1.,  2.],
+               [-1., -2.]])
+        >>> RotatedBox([0, 0], 0, 0, np.pi/2).as_poly(2, 1)
+        array([[ 1., -2.],
+               [ 1.,  2.],
+               [-1.,  2.],
+               [-1., -2.]])
+        """
+        v_hor = (self.width/2 + margin_width)*np.array([np.cos(self.angle), np.sin(self.angle)])
+        v_vert = (self.height/2 + margin_height)*np.array([-np.sin(self.angle), np.cos(self.angle)])
+        c = np.array([self.cx, self.cy])
+        return np.vstack([c - v_hor - v_vert, c + v_hor - v_vert, c + v_hor + v_vert, c - v_hor + v_vert])
+
+    def extract_from_image(self, img, scale=1.0, margin_width=5, margin_height=5):
+        """Extracts the contents of this box from a given image.
+        For that the image is "unrotated" by the appropriate angle, and the corresponding part is extracted from it.
+
+        Returns an image with dimensions height*scale x width*scale.
+        Note that the box coordinates are interpreted as "image coordinates" (i.e. x is row and y is column),
+        and box angle is considered to be relative to the vertical (i.e. np.pi/2 is "normal orientation")
+
+        :param img: a numpy ndarray suitable for image processing.
+        :param scale: the RotatedBox is scaled by this value before performing the extraction.
+            This is necessary when, for example, the location of a particular feature is determined using a smaller image,
+            yet then the corresponding area needs to be extracted from the original, larger image.
+            The scale parameter in this case should be width_of_larger_image/width_of_smaller_image.
+        :param margin_width: The margin that should be added to the width dimension of the box from each size.
+            This value is given wrt actual box dimensions (i.e. not scaled).
+        :param margin_height: The margin that should be added to the height dimension of the box from each side.
+        :return: a numpy ndarray, corresponding to the extracted region (aligned straight).
+        """
+        rotate_by = (np.pi/2 - self.angle)*180/np.pi
+        img_rotated = _rotate(img, angle=rotate_by, center=[self.center[1]*scale, self.center[0]*scale], resize=True)
+        # The resizeable transform will shift the resulting image somewhat wrt original coordinates.
+        # When we cut out the box we will compensate for this shift.
+        shift_c, shift_r = self._compensate_rotation_shift(img, scale)
+
+        r1 = max(int((self.center[0] - self.height/2 - margin_height)*scale - shift_r), 0)
+        r2 = int((self.center[0] + self.height/2 + margin_height)*scale - shift_r)
+        c1 = max(int((self.center[1] - self.width/2 - margin_width)*scale - shift_c), 0)
+        c2 = int((self.center[1] + self.width/2 + margin_width)*scale - shift_c)
+        return img_rotated[r1:r2, c1:c2]
+
+    def _compensate_rotation_shift(self, img, scale):
+        """This is an auxiliary method used by extract_from_image.
+        It repeats the shift computation performed by skimage's resize-enabled rotate,
+        so that the box can be cut out at the right offset.
+        """
+        ctr = np.asarray([self.center[1]*scale, self.center[0]*scale])
+        tform1 = SimilarityTransform(translation=ctr)
+        tform2 = SimilarityTransform(rotation=np.pi/2 - self.angle)
+        tform3 = SimilarityTransform(translation=-ctr)
+        tform = tform3 + tform2 + tform1
+
+        rows, cols = img.shape[0], img.shape[1]
+        corners = np.array([
+            [0, 0],
+            [0, rows - 1],
+            [cols - 1, rows - 1],
+            [cols - 1, 0]
+        ])
+        corners = tform.inverse(corners)
+        minc = corners[:, 0].min()
+        minr = corners[:, 1].min()
+        maxc = corners[:, 0].max()
+        maxr = corners[:, 1].max()
+
+        # fit output image in new shape
+        translation = (minc, minr)
+        tform4 = SimilarityTransform(translation=translation)
+        tform = tform4 + tform
+        tform.params[2] = (0, 0, 1)
+
+        # Compute the shift of the transformed center wrt original
+        return (ctr - tform.inverse(ctr)).ravel().tolist()
+
+    @staticmethod
+    def from_points(points, box_type='bb'):
+        """
+        Interpret a given point cloud as a RotatedBox, using PCA to determine the potential orientation (the longest component becomes width)
+        This is basically an approximate version of a min-area-rectangle algorithm.
+
+        :param points: An n x 2 numpy array of coordinates.
+        :param box_type: The kind of method used to estimate the "box".
+            Possible values:
+                - `'bb'`, denoting the "bounding box" approach (min/max coordinates of the points correspond to box limits)
+                - `'mrz`, denoting a slightly modified technique, suited for MRZ zone detection from contour images.
+                          Here the assumption is that the upper and lower bounds of the box are better estimated as the
+                          10% and 90% quantile of the corresponding coordinates (rather than 0% and 100%, i.e. min and max).
+                          This helps against accidental noise in the contour.
+                          The `'mrz'` correction is only applied when there are at least 10 points in the set.
+        :returns: a RotatedBox, bounding the given set of points, oriented according to the principal components.
+
+        >>> RotatedBox.from_points([[0,0]])
+        RotatedBox(cx=0.0, cy=0.0, width=0.0, height=0.0, angle=0.0)
+        >>> assert RotatedBox.from_points([[0,0], [1,1], [2,2]]).approx_equal([1, 1], np.sqrt(8), 0, np.pi/4)
+        >>> assert RotatedBox.from_points([[0,0], [1,1], [0,1], [1,0]]).approx_equal([0.5, 0.5], 1, 1, 0.0) # The angle is rather arbitrary here
+        >>> assert RotatedBox.from_points([[0,0], [2,1], [0,1], [2,0]]).approx_equal([1, 0.5], 2, 1, 0)
+        >>> assert RotatedBox.from_points([[0,0], [2,4], [0,4], [2,0]]).approx_equal([1, 2], 4, 2, np.pi/2)
+        >>> assert RotatedBox.from_points([[0,0], [1,1.5], [2,0]]).approx_equal([1, 0.75], 2, 1.5, 0)
+        >>> assert RotatedBox.from_points([[0,0], [0,1], [1,1]]).approx_equal([0.25, 0.75], np.sqrt(2), np.sqrt(2)/2, np.pi/4)
+        """
+        points = np.asarray(points, dtype=np.float64)
+        if points.shape[0] == 1:
+            return RotatedBox(points[0], width=0.0, height=0.0, angle=0.0, points=points)
+
+        mean, components = _pca(points)
+        # Find the angle
+        angle = (np.arctan2(components[0, 1], components[0, 0]) % np.pi)
+        if abs(angle - np.pi) < angle:
+            # Here the angle is always between -pi and pi
+            # If the principal component happened to be oriented so that the angle happens to be > pi/2 by absolute value,
+            # we flip the direction
+            angle = angle - np.pi if angle > 0 else angle + np.pi
+        points_transformed = (points - mean) @ components.T
+        ll = np.min(points_transformed, 0)
+        ur = np.max(points_transformed, 0)
+        wh = ur - ll
+
+        # Now compute and return the bounding box
+        if box_type == 'bb' or (box_type == 'mrz' and points.shape[0] < 10):
+            # We know that if we rotate the points around mean, we get a box with bounds ur and ll
+            # The center of this box is (ur+ll)/2 + mean, which is not the same as the mean,
+            # hence to get the center of the original box we need to "unrotate" this box back.
+            return RotatedBox(np.dot(components.T, (ll+ur)/2) + mean, width=wh[0], height=wh[1], angle=angle, points=points)
+        elif box_type == 'mrz':
+            # When working with MRZ detection from contours, we may have minor "bumps" in the contour,
+            # that should be ignored at least along the long ("horizontal") side.
+            # To do that, we will use 10% and 90% quantiles as the bounds of the box instead of the max and min.
+            h_coord = sorted(points_transformed[:, 1])
+            n = len(h_coord)
+            bottom, top = h_coord[n // 10], h_coord[n * 9 // 10]
+            valid_points = np.logical_and(points_transformed[:, 1] >= bottom, points_transformed[:, 1] <= top)
+            rb = RotatedBox.from_points(points[valid_points, :], 'bb')
+            rb.points = points
+            return rb
+        else:
+            raise ValueError("Unknown parameter value: box_type=%s" % box_type)

mrzmini/image.py

@@ -0,0 +1,354 @@
+'''
+mrzmini.image: the MRZ extraction pipeline.
+
+Adapted from PassportEye's ``passporteye/mrz/image.py``. The pipeline structure
+and parameters are reproduced exactly; only the underlying image-processing
+calls are routed through :mod:`mrzmini.imageproc` (numpy/Pillow) instead of
+``skimage`` / ``imageio``, and PDF loading goes through :mod:`mrzmini.pdf`
+instead of ``pdfminer``.
+
+Author of original: Konstantin Tretyakov. License: MIT.
+'''
+import io
+
+import numpy as np
+
+from . import imageproc as ip
+from .pdf import extract_first_jpeg_in_pdf
+from .pipeline import Pipeline
+from .geometry import RotatedBox
+from .ocr import ocr
+from .text import MRZ
+
+
+class Loader(object):
+    """Loads `file` to `img`."""
+
+    __depends__ = []
+    __provides__ = ['img']
+
+    def __init__(self, file, as_gray=True, pdf_aware=True):
+        self.file = file
+        self.as_gray = as_gray
+        self.pdf_aware = pdf_aware
+
+    def _imread(self, file):
+        """Proxy to mrzmini.imageproc.imread_gray (replaces skimage.io.imread)."""
+        return ip.imread_gray(file)
+
+    def __call__(self):
+        if isinstance(self.file, str):
+            if self.pdf_aware and self.file.lower().endswith('.pdf'):
+                with open(self.file, 'rb') as f:
+                    img_data = extract_first_jpeg_in_pdf(f)
+                if img_data is None:
+                    return None
+                return self._imread(img_data)
+            else:
+                return self._imread(self.file)
+        elif isinstance(self.file, (bytes, io.IOBase)):
+            return self._imread(self.file)
+        return None
+
+
+class Scaler(object):
+    """Scales `image` down to `img_scaled` so that its width is at most 250."""
+
+    __depends__ = ['img']
+    __provides__ = ['img_small', 'scale_factor']
+
+    def __init__(self, max_width=250):
+        self.max_width = max_width
+
+    def __call__(self, img):
+        scale_factor = self.max_width / float(img.shape[1])
+        if scale_factor <= 1:
+            img_small = ip.rescale(img, scale_factor)
+        else:
+            scale_factor = 1.0
+            img_small = img
+        return img_small, scale_factor
+
+
+class BooneTransform(object):
+    """Processes `img_small` according to Hans Boone's method
+    (http://www.pyimagesearch.com/2015/11/30/detecting-machine-readable-zones-in-passport-images/)
+    Outputs a `img_binary` - a result of threshold_otsu(closing(sobel(black_tophat(img_small)))"""
+
+    __depends__ = ['img_small']
+    __provides__ = ['img_binary']
+
+    def __init__(self, square_size=5):
+        self.square_size = square_size
+
+    def __call__(self, img_small):
+        m = ip.square(self.square_size)
+        img_th = ip.black_tophat(img_small, m)
+        img_sob = abs(ip.sobel_v(img_th))
+        img_closed = ip.closing(img_sob, m)
+        threshold = ip.threshold_otsu(img_closed)
+        return img_closed > threshold
+
+
+class MRZBoxLocator(object):
+    """Extracts putative MRZs as RotatedBox instances from the contours of `img_binary`"""
+
+    __depends__ = ['img_binary']
+    __provides__ = ['boxes']
+
+    def __init__(self, max_boxes=4, min_points_in_contour=50, min_area=500, min_box_aspect=5, angle_tol=0.1,
+                 lineskip_tol=1.5, box_type='bb'):
+        self.max_boxes = max_boxes
+        self.min_points_in_contour = min_points_in_contour
+        self.min_area = min_area
+        self.min_box_aspect = min_box_aspect
+        self.angle_tol = angle_tol
+        self.lineskip_tol = lineskip_tol
+        self.box_type = box_type
+
+    def __call__(self, img_binary):
+        cs = ip.find_contours(img_binary, 0.5)
+
+        # Collect contours into RotatedBoxes
+        results = []
+        for c in cs:
+            # Now examine the bounding box. If it is too small, we ignore the contour
+            ll, ur = np.min(c, 0), np.max(c, 0)
+            wh = ur - ll
+            if wh[0] * wh[1] < self.min_area:
+                continue
+
+            # Finally, construct the rotatedbox. If its aspect ratio is too small, we ignore it
+            rb = RotatedBox.from_points(c, self.box_type)
+            if rb.height == 0 or rb.width / rb.height < self.min_box_aspect:
+                continue
+
+            # All tests fine, add to the list
+            results.append(rb)
+
+        # Next sort and leave only max_boxes largest boxes by area
+        results.sort(key=lambda x: -x.area)
+        return self._fixup_boxes(self._merge_boxes(results[0:self.max_boxes]))
+
+    def _are_aligned_angles(self, b1, b2):
+        "Are two boxes aligned according to their angle?"
+        return abs(b1 - b2) <= self.angle_tol or abs(np.pi - abs(b1 - b2)) <= self.angle_tol
+
+    def _are_nearby_parallel_boxes(self, b1, b2):
+        "Are two boxes nearby, parallel, and similar in width?"
+        if not self._are_aligned_angles(b1.angle, b2.angle):
+            return False
+        # Otherwise pick the smaller angle and see whether the two boxes are close according to the "up" direction wrt that angle
+        angle = min(b1.angle, b2.angle)
+        return abs(np.dot(b1.center - b2.center, [-np.sin(angle), np.cos(angle)])) < self.lineskip_tol * (
+            b1.height + b2.height) and (b1.width > 0) and (b2.width > 0) and (0.5 < b1.width / b2.width < 2.0)
+
+    def _merge_any_two_boxes(self, box_list):
+        """Given a list of boxes, finds two nearby parallel ones and merges them. Returns false if none found."""
+        n = len(box_list)
+        for i in range(n):
+            for j in range(i + 1, n):
+                if self._are_nearby_parallel_boxes(box_list[i], box_list[j]):
+                    # Remove the two boxes from the list, add a new one
+                    a, b = box_list[i], box_list[j]
+                    merged_points = np.vstack([a.points, b.points])
+                    merged_box = RotatedBox.from_points(merged_points, self.box_type)
+                    if merged_box.width / merged_box.height >= self.min_box_aspect:
+                        box_list.remove(a)
+                        box_list.remove(b)
+                        box_list.append(merged_box)
+                        return True
+        return False
+
+    def _merge_boxes(self, box_list):
+        """Mergest nearby parallel boxes in the given list."""
+        while self._merge_any_two_boxes(box_list):
+            pass
+        return box_list
+
+    def _fixup_boxes(self, box_list):
+        """If the box's angle is np.pi/2 +- 0.01, we shall round it to np.pi/2.
+
+        This way image extraction is fast and introduces no distortions.
+        and this may be more important than being perfectly straight
+        similar for 0 angle.
+        The box_list is fixed in-place (but also returned).
+        """
+        for box in box_list:
+            if abs(abs(box.angle) - np.pi / 2) <= 0.01:
+                box.angle = np.pi / 2
+            if abs(box.angle) <= 0.01:
+                box.angle = 0.0
+        return box_list
+
+
+class ExtractAllBoxes(object):
+    """Extract all the images from the boxes, for external OCR processing"""
+
+    __provides__ = ['rois']
+    __depends__ = ['boxes', 'img', 'scale_factor']
+
+    def __call__(self, boxes, img, scale_factor):
+        return [box.extract_from_image(img, 1.0 / scale_factor) for box in boxes]
+
+
+class FindFirstValidMRZ(object):
+    """Iterates over boxes found by MRZBoxLocator, passes them to BoxToMRZ, finds the first valid MRZ
+    or the best-scoring MRZ"""
+
+    __provides__ = ['box_idx', 'roi', 'text', 'mrz']
+    __depends__ = ['boxes', 'img', 'img_small', 'scale_factor', '__data__']
+
+    def __init__(self, use_original_image=True, extra_cmdline_params=''):
+        self.box_to_mrz = BoxToMRZ(use_original_image, extra_cmdline_params=extra_cmdline_params)
+
+    def __call__(self, boxes, img, img_small, scale_factor, data):
+        mrzs = []
+        data['__debug__mrz'] = []
+        for i, b in enumerate(boxes):
+            roi, text, mrz = self.box_to_mrz(b, img, img_small, scale_factor)
+            data['__debug__mrz'].append((roi, text, mrz))
+            if mrz.valid:
+                return i, roi, text, mrz
+            elif mrz.valid_score > 0:
+                mrzs.append((i, roi, text, mrz))
+        if not mrzs:
+            return None, None, None, None
+        else:
+            mrzs.sort(key=lambda x: x[3].valid_score)
+            return mrzs[-1]
+
+
+class BoxToMRZ(object):
+    """Extracts ROI from the image, corresponding to a box found by MRZBoxLocator, does OCR and MRZ parsing on this region."""
+
+    __provides__ = ['roi', 'text', 'mrz']
+    __depends__ = ['box', 'img', 'img_small', 'scale_factor']
+
+    def __init__(self, use_original_image=True, extra_cmdline_params=''):
+        """
+        :param use_original_image: when True, the ROI is extracted from img, otherwise from img_small
+        """
+        self.use_original_image = use_original_image
+        self.extra_cmdline_params = extra_cmdline_params
+
+    def __call__(self, box, img, img_small, scale_factor):
+        img = img if self.use_original_image else img_small
+        scale = 1.0 / scale_factor if self.use_original_image else 1.0
+        roi = box.extract_from_image(img, scale)
+        text = ocr(roi, extra_cmdline_params=self.extra_cmdline_params)
+
+        if '>>' in text or ('>' in text and '<' not in text):
+            # Most probably we need to reverse the ROI
+            roi = roi[::-1, ::-1]
+            text = ocr(roi, extra_cmdline_params=self.extra_cmdline_params)
+
+        if '<' not in text:
+            # Assume this is unrecoverable and stop here (TODO: this may be premature, although it saves time on useless stuff)
+            return roi, text, MRZ.from_ocr(text)
+
+        mrz = MRZ.from_ocr(text)
+        mrz.aux['method'] = 'direct'
+
+        # Now try improving the result via hacks
+        if not mrz.valid:
+            text, mrz = self._try_larger_image(roi, text, mrz)
+
+        # Sometimes the filter used for enlargement is important!
+        if not mrz.valid:
+            text, mrz = self._try_larger_image(roi, text, mrz, 1)
+
+        if not mrz.valid:
+            text, mrz = self._try_black_tophat(roi, text, mrz)
+
+        return roi, text, mrz
+
+    def _try_larger_image(self, roi, cur_text, cur_mrz, filter_order=3):
+        """Attempts to improve the OCR result by scaling the image. If the new mrz is better, returns it, otherwise returns
+        the old mrz."""
+        if roi.shape[1] <= 700:
+            scale_by = int(1050.0 / roi.shape[1] + 0.5)
+            roi_lg = ip.rescale(roi, scale_by, order=filter_order)
+            new_text = ocr(roi_lg, extra_cmdline_params=self.extra_cmdline_params)
+            new_mrz = MRZ.from_ocr(new_text)
+            new_mrz.aux['method'] = 'rescaled(%d)' % filter_order
+            if new_mrz.valid_score > cur_mrz.valid_score:
+                cur_mrz = new_mrz
+                cur_text = new_text
+        return cur_text, cur_mrz
+
+    def _try_black_tophat(self, roi, cur_text, cur_mrz):
+        roi_b = ip.black_tophat(roi, ip.disk(5))
+        # There are some examples where this line basically hangs for an undetermined amount of time.
+        new_text = ocr(roi_b, extra_cmdline_params=self.extra_cmdline_params)
+        new_mrz = MRZ.from_ocr(new_text)
+        if new_mrz.valid_score > cur_mrz.valid_score:
+            new_mrz.aux['method'] = 'black_tophat'
+            cur_text, cur_mrz = new_text, new_mrz
+
+        new_text, new_mrz = self._try_larger_image(roi_b, cur_text, cur_mrz)
+        if new_mrz.valid_score > cur_mrz.valid_score:
+            new_mrz.aux['method'] = 'black_tophat(rescaled(3))'
+            cur_text, cur_mrz = new_text, new_mrz
+
+        return cur_text, cur_mrz
+
+
+class TryOtherMaxWidth(object):
+    """
+    If mrz was not found so far in the current pipeline,
+    changes the max_width parameter of the scaler to 1000 and reruns the pipeline again.
+    """
+
+    __provides__ = ['mrz_final']
+    __depends__ = ['mrz', '__pipeline__']
+
+    def __init__(self, other_max_width=1000):
+        self.other_max_width = other_max_width
+
+    def __call__(self, mrz, __pipeline__):
+        # We'll only try this if we see that img_binary.mean() is very small or img.mean() is very large (i.e. image is mostly white).
+        if mrz is None and (__pipeline__['img_binary'].mean() < 0.01 or __pipeline__['img'].mean() > 0.95):
+            __pipeline__.replace_component('scaler', Scaler(self.other_max_width))
+            new_mrz = __pipeline__['mrz']
+            if new_mrz is not None:
+                new_mrz.aux['method'] = new_mrz.aux['method'] + '|max_width(%d)' % self.other_max_width
+            mrz = new_mrz
+        return mrz
+
+
+class MRZPipeline(Pipeline):
+    """This is the "currently best-performing" pipeline for parsing MRZ from a given image file."""
+
+    def __init__(self, file, extra_cmdline_params=''):
+        super(MRZPipeline, self).__init__()
+        self.version = '1.0'  # In principle we might have different pipelines in use, so possible backward compatibility is an issue
+        self.file = file
+        self.add_component('loader', Loader(file))
+        self.add_component('scaler', Scaler())
+        self.add_component('boone', BooneTransform())
+        self.add_component('box_locator', MRZBoxLocator())
+        self.add_component('mrz', FindFirstValidMRZ(extra_cmdline_params=extra_cmdline_params))
+        self.add_component('other_max_width', TryOtherMaxWidth())
+
+        # Step used by extract_mrz_rois (not even invoked by the standard result method)
+        self.add_component('extractor', ExtractAllBoxes())
+
+    @property
+    def result(self):
+        return self['mrz_final']
+
+
+def read_mrz(file, save_roi=False, extra_cmdline_params=''):
+    """The main interface function to this module, encapsulating the recognition pipeline.
+       Given an image filename, runs MRZPipeline on it, returning the parsed MRZ object.
+
+    :param file: A filename or a stream to read the file data from.
+    :param save_roi: when this is True, the .aux['roi'] field will contain the Region of Interest where the MRZ was parsed from.
+    :param extra_cmdline_params: extra parameters to the OCR.
+    """
+    p = MRZPipeline(file, extra_cmdline_params)
+    mrz = p.result
+    if mrz is not None and save_roi:
+        mrz.aux['roi'] = p['roi']
+    return mrz