From 62edc15cd766d701728996ed6a41fb43b4d528b4 Mon Sep 17 00:00:00 2001 From: Jim Barlow Date: Sat, 18 Jan 2014 22:29:20 -0800 Subject: [PATCH 1/5] Implement ctypes wrapper around Leptonica to access its deskew function A few design notes: Leptonica's deskew is far superior to ImageMagick's convert -deskew command -- around 30-40x faster. Subjectively the output appears to this contributor to be of higher quality as well. The difference is the algorithm: ImageMagick uses the complex Hough transform to find the skew angle, while Leptonica uses the simpler method, Postl's variance of differential line sums -- conceptually, shear the image and check for straight horizontal. In this case simplicity wins. Finding the skew angle is the bulk of the work. Leptonica's author explains the advantages of his approach here: http://www.leptonica.com/skew-measurement.html Leptonica is the low-level library that Tesseract depends on. Hence, this project already depends on Leptonica. Leptonica can read and write most common image file types on its own. Unfortunately its error handling is poor: it seldom returns any meaningful error codes. The best it manages is writing messages to stderr, which in the context of a verbose script is just confusing since the error's source is not indicated. The problem is compounded by Tesseract's use of Leptonica, which will produce exactly the same errors in some cases. So we trap stderr between calls to Leptonica and parse it for a few different types of error message. leptonica.py is Python 2/3 compatible and set up to provide access to other Leptonica functions as needed. Of particular interest are its orientation detection (including flip and rotation errors) which it does by comparing text ascenders to descenders. There is a PyPI "pylepthonica" package, however it is out of date by a few years, and it implements all of Leptonica with Python wrappers -- so it is massive, with one .py file at 2.5 MB. This module is loosely inspired by pyleptonica but more modern, up to date, and contains only limited functionality. --- src/leptonica.py | 246 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 src/leptonica.py diff --git a/src/leptonica.py b/src/leptonica.py new file mode 100644 index 00000000..f49cf097 --- /dev/null +++ b/src/leptonica.py @@ -0,0 +1,246 @@ +#!/usr/bin/env python2 +# -*- coding: utf-8 -*- +# +# © 2013-14: jbarlow83 from Github (https://github.com/jbarlow83) +# +# +# Use Leptonica to detect find and remove page skew. Leptonica uses the method +# of differential square sums, which its author claim is faster and more robust +# than the Hough transform used by ImageMagick. + +from __future__ import print_function, absolute_import, division +import argparse +import ctypes as C +import sys +import os +from tempfile import TemporaryFile + + +def stderr(*objs): + """Python 2/3 compatible print to stderr. + """ + print("leptonica.py:", *objs, file=sys.stderr) + + +from ctypes.util import find_library +lept_lib = find_library('lept') +if not lept_lib: + stderr("Could not find the Leptonica library") + sys.exit(3) +try: + lept = C.cdll.LoadLibrary(lept_lib) +except Exception: + stderr("Could not load the Leptonica library from %s", lept_lib) + sys.exit(3) + + +class _PIXCOLORMAP(C.Structure): + """struct PixColormap from Leptonica src/pix.h + """ + + _fields_ = [ + ("array", C.c_void_p), + ("depth", C.c_int32), + ("nalloc", C.c_int32), + ("n", C.c_int32) + ] + + +class _PIX(C.Structure): + """struct Pix from Leptonica src/pix.h + """ + + _fields_ = [ + ("w", C.c_uint32), + ("h", C.c_uint32), + ("d", C.c_uint32), + ("wpl", C.c_uint32), + ("refcount", C.c_uint32), + ("xres", C.c_int32), + ("yres", C.c_int32), + ("informat", C.c_int32), + ("text", C.POINTER(C.c_char)), + ("colormap", C.POINTER(_PIXCOLORMAP)), + ("data", C.POINTER(C.c_uint32)) + ] + + +PIX = C.POINTER(_PIX) + +lept.pixRead.argtypes = [C.c_char_p] +lept.pixRead.restype = PIX +lept.pixScale.argtypes = [PIX, C.c_float, C.c_float] +lept.pixScale.restype = PIX +lept.pixDeskew.argtypes = [PIX, C.c_int32] +lept.pixDeskew.restype = PIX +lept.pixWriteImpliedFormat.argtypes = [C.c_char_p, PIX, C.c_int32, C.c_int32] +lept.pixWriteImpliedFormat.restype = C.c_int32 +lept.pixDestroy.argtypes = [C.POINTER(PIX)] +lept.pixDestroy.restype = None +lept.getLeptonicaVersion.argtypes = [] +lept.getLeptonicaVersion.restype = C.c_char_p + + +class Leptonica(object): + """Context manager to trap errors reported by Leptonica. + + Leptonica's error return codes are unreliable to the point of being + almost useless. It does, however, write errors to stderr provided that is + not disabled at its compile time. Fortunately this is done using error + macros so it is very self-consistent. + + This context manager redirects stderr to a temporary file which is then + read and parsed for error messages. As a side benefit, debug messages + from Leptonica are also suppressed. + + """ + def __enter__(self): + self.tmpfile = TemporaryFile() + + # Save the old stderr, and redirect stderr to temporary file + self.old_stderr_fileno = os.dup(sys.stderr.fileno()) + os.dup2(self.tmpfile.fileno(), sys.stderr.fileno()) + return + + def __exit__(self, type, value, traceback): + # Restore old stderr + os.dup2(self.old_stderr_fileno, sys.stderr.fileno()) + + # Get data from tmpfile (in with block to ensure it is closed) + with self.tmpfile as tmpfile: + tmpfile.seek(0) + leptonica_output = tmpfile.read().decode(errors='replace') + + # If there are Python errors, let them bubble up + if type: + stderr(leptonica_output) + return False + + # If there are Leptonica errors, wrap them in Python excpetions + if 'Error' in leptonica_output: + if 'image file not found' in leptonica_output: + raise LeptonicaIOError() + if 'pixWrite: stream not opened' in leptonica_output: + raise LeptonicaIOError() + raise LeptonicaError(leptonica_output) + + return False + + +class LeptonicaError(Exception): + pass + + +class LeptonicaIOError(LeptonicaError): + pass + + +def pixRead(filename): + """Load an image file into a PIX object. + + Leptonica can load TIFF, PNM (PBM, PGM, PPM), PNG, and JPEG. If loading + fails then the object will wrap a C null pointer. + + """ + with Leptonica(): + return lept.pixRead(filename.encode(sys.getfilesystemencoding())) + + +def pixScale(pix, scalex, scaley): + """Returns the pix object rescaled according to the proportions given.""" + with Leptonica(): + return lept.pixScale(pix, scalex, scaley) + + +def pixDeskew(pix, reduction_factor=0): + """Returns the deskewed pix object. + + A clone of the original is returned when the algorithm cannot find a skew + angle with sufficient confidence. + + reduction_factor -- amount to downsample (0 for default) when searching + for skew angle + + """ + with Leptonica(): + return lept.pixDeskew(pix, reduction_factor) + + +def pixWriteImpliedFormat(filename, pix, jpeg_quality=0, jpeg_progressive=0): + """Write pix to the filename, with the extension indicating format. + + jpeg_quality -- quality (iff JPEG; 1 - 100, 0 for default) + jpeg_ progressive -- (iff JPEG; 0 for baseline seq., 1 for progressive) + + """ + with Leptonica(): + lept.pixWriteImpliedFormat( + filename.encode(sys.getfilesystemencoding()), + pix, jpeg_quality, jpeg_progressive) + + +def pixDestroy(pix): + """Destroy the pix object. + + Function signature is pixDestroy(struct Pix **), hence C.byref() to pass + the address of the pointer. + + """ + with Leptonica(): + lept.pixDestroy(C.byref(pix)) + + +def getLeptonicaVersion(): + """Get Leptonica version string. + + Caveat: Leptonica expects the caller to free this memory. We don't, + since that would involve binding to libc to access libc.free(), + a pointless effort to reclaim 100 bytes of memory. + + """ + return lept.getLeptonicaVersion().decode() + + +def deskew(args): + try: + pix_source = pixRead(args.infile) + except LeptonicaIOError: + stderr("Failed to open file: %s" % args.infile) + sys.exit(2) + + if args.dpi < 150: + reduction_factor = 1 # Don't downsample too much if DPI is already low + else: + reduction_factor = 0 # Use default + pix_deskewed = pixDeskew(pix_source, reduction_factor) + + try: + pixWriteImpliedFormat(args.outfile, pix_deskewed) + except LeptonicaIOError: + stderr("Failed to open destination file: %s" % args.outfile) + sys.exit(5) + pixDestroy(pix_source) + pixDestroy(pix_deskewed) + + +if __name__ == '__main__': + parser = argparse.ArgumentParser( + description="Python wrapper to access Leptonica") + + subparsers = parser.add_subparsers(title='commands', + description='supported operations') + + parser_deskew = subparsers.add_parser('deskew') + parser_deskew.add_argument('-r', '--dpi', dest='dpi', action='store', + type=int, default=300, help='input resolution') + parser_deskew.add_argument('infile', help='image to deskew') + parser_deskew.add_argument('outfile', help='deskewed output image') + parser_deskew.set_defaults(func=deskew) + + args = parser.parse_args() + + if getLeptonicaVersion() != u'leptonica-1.69': + print("Unexpected leptonica version: %s" % getLeptonicaVersion()) + + args.func(args) + From 670343497677ac44b52b66ed1daedc2876442a46 Mon Sep 17 00:00:00 2001 From: Jim Barlow Date: Sun, 19 Jan 2014 13:31:02 -0800 Subject: [PATCH 2/5] Replace ImageMagick-convert with Leptonica --- src/ocrPage.sh | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/ocrPage.sh b/src/ocrPage.sh index 04685641..8e61c246 100755 --- a/src/ocrPage.sh +++ b/src/ocrPage.sh @@ -166,8 +166,7 @@ widthCurImg=$(($dpi*$widthPDF/72)) heightCurImg=$(($dpi*$heightPDF/72)) if [ "$PREPROCESS_DESKEW" -eq "1" ]; then [ $VERBOSITY -ge $LOG_DEBUG ] && echo "Page $page: Deskewing image" - ! convert "$curImgPixmap" -deskew 40% -gravity center -extent ${widthCurImg}x${heightCurImg} "$curImgPixmapDeskewed" \ - && echo "Could not deskew \"$curImgPixmap\". Exiting..." && exit $EXIT_OTHER_ERROR + ! python2 $SRC/deskew.py -r $dpi "$curImgPixmap" "$curImgPixmapDeskewed" && exit $? else ln -s `basename "$curImgPixmap"` "$curImgPixmapDeskewed" fi From 8cfbdaf0d022dea822e76f1b93bf6a672f5ac07d Mon Sep 17 00:00:00 2001 From: Jim Barlow Date: Sun, 19 Jan 2014 19:06:19 -0800 Subject: [PATCH 3/5] Fix a silly typo, and other minor cleanup --- src/leptonica.py | 18 +++++++++--------- src/ocrPage.sh | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/leptonica.py b/src/leptonica.py index f49cf097..10e69f48 100644 --- a/src/leptonica.py +++ b/src/leptonica.py @@ -81,7 +81,7 @@ lept.getLeptonicaVersion.argtypes = [] lept.getLeptonicaVersion.restype = C.c_char_p -class Leptonica(object): +class LeptonicaErrorTrap(object): """Context manager to trap errors reported by Leptonica. Leptonica's error return codes are unreliable to the point of being @@ -102,17 +102,17 @@ class Leptonica(object): os.dup2(self.tmpfile.fileno(), sys.stderr.fileno()) return - def __exit__(self, type, value, traceback): + def __exit__(self, exc_type, exc_value, traceback): # Restore old stderr os.dup2(self.old_stderr_fileno, sys.stderr.fileno()) # Get data from tmpfile (in with block to ensure it is closed) with self.tmpfile as tmpfile: - tmpfile.seek(0) + tmpfile.seek(0) # Cursor will be at end, so move back to beginning leptonica_output = tmpfile.read().decode(errors='replace') # If there are Python errors, let them bubble up - if type: + if exc_type: stderr(leptonica_output) return False @@ -142,13 +142,13 @@ def pixRead(filename): fails then the object will wrap a C null pointer. """ - with Leptonica(): + with LeptonicaErrorTrap(): return lept.pixRead(filename.encode(sys.getfilesystemencoding())) def pixScale(pix, scalex, scaley): """Returns the pix object rescaled according to the proportions given.""" - with Leptonica(): + with LeptonicaErrorTrap(): return lept.pixScale(pix, scalex, scaley) @@ -162,7 +162,7 @@ def pixDeskew(pix, reduction_factor=0): for skew angle """ - with Leptonica(): + with LeptonicaErrorTrap(): return lept.pixDeskew(pix, reduction_factor) @@ -173,7 +173,7 @@ def pixWriteImpliedFormat(filename, pix, jpeg_quality=0, jpeg_progressive=0): jpeg_ progressive -- (iff JPEG; 0 for baseline seq., 1 for progressive) """ - with Leptonica(): + with LeptonicaErrorTrap(): lept.pixWriteImpliedFormat( filename.encode(sys.getfilesystemencoding()), pix, jpeg_quality, jpeg_progressive) @@ -186,7 +186,7 @@ def pixDestroy(pix): the address of the pointer. """ - with Leptonica(): + with LeptonicaErrorTrap(): lept.pixDestroy(C.byref(pix)) diff --git a/src/ocrPage.sh b/src/ocrPage.sh index 8e61c246..6f9f1612 100755 --- a/src/ocrPage.sh +++ b/src/ocrPage.sh @@ -166,7 +166,7 @@ widthCurImg=$(($dpi*$widthPDF/72)) heightCurImg=$(($dpi*$heightPDF/72)) if [ "$PREPROCESS_DESKEW" -eq "1" ]; then [ $VERBOSITY -ge $LOG_DEBUG ] && echo "Page $page: Deskewing image" - ! python2 $SRC/deskew.py -r $dpi "$curImgPixmap" "$curImgPixmapDeskewed" && exit $? + ! python2 $SRC/leptonica.py deskew -r $dpi "$curImgPixmap" "$curImgPixmapDeskewed" && exit $? else ln -s `basename "$curImgPixmap"` "$curImgPixmapDeskewed" fi From 5ace6906c73f475e3208459794a41eadb946999d Mon Sep 17 00:00:00 2001 From: Jim Barlow Date: Tue, 21 Jan 2014 20:25:47 -0800 Subject: [PATCH 4/5] Bug fix: leptonica generates .png when asked to produce .pbm/pgm/ppm Leptonica does not interpret those extensions correctly. However, when asked to produce a .pnm file, it will produce the expected .pbm/pgm/ppm file depending on the input. So ask it to produce a .pnm and then adjust the extension. And add a test case. --- src/leptonica.py | 41 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/src/leptonica.py b/src/leptonica.py index 10e69f48..ee0c642e 100644 --- a/src/leptonica.py +++ b/src/leptonica.py @@ -170,14 +170,26 @@ def pixWriteImpliedFormat(filename, pix, jpeg_quality=0, jpeg_progressive=0): """Write pix to the filename, with the extension indicating format. jpeg_quality -- quality (iff JPEG; 1 - 100, 0 for default) - jpeg_ progressive -- (iff JPEG; 0 for baseline seq., 1 for progressive) + jpeg_progressive -- (iff JPEG; 0 for baseline seq., 1 for progressive) """ + fileroot, extension = os.path.splitext(filename) + fix_pnm = False + if extension.lower() in ('.pbm', '.pgm', '.ppm'): + # Leptonica does not process handle these extensions correctly, but + # does handle .pnm correctly. Add another .pnm suffix. + filename += '.pnm' + fix_pnm = True + with LeptonicaErrorTrap(): lept.pixWriteImpliedFormat( filename.encode(sys.getfilesystemencoding()), pix, jpeg_quality, jpeg_progressive) + if fix_pnm: + from shutil import move + move(filename, filename[:-4]) # Remove .pnm suffix + def pixDestroy(pix): """Destroy the pix object. @@ -244,3 +256,30 @@ if __name__ == '__main__': args.func(args) + +def _test_output(mode, extension, im_format): + from PIL import Image + from tempfile import NamedTemporaryFile + + with NamedTemporaryFile(prefix='test-lept-pnm', suffix=extension, delete=True) as tmpfile: + im = Image.new(mode=mode, size=(100, 100)) + im.save(tmpfile) + + pix = pixRead(tmpfile.name) + pixWriteImpliedFormat(tmpfile.name, pix) + pixDestroy(pix) + + im_roundtrip = Image.open(tmpfile.name) + assert im_roundtrip.mode == im.mode, "leptonica mode differs" + assert im_roundtrip.format == im_format, \ + "{0}: leptonica produced a {1}".format( + extension, + im_roundtrip.format) + + +def test_pnm_output(): + params = [['1', '.pbm', 'PPM'], ['L', '.pgm', 'PPM'], + ['RGB', '.ppm', 'PPM']] + for param in params: + _test_output(*param) + From 112fb5098bfcddd6a5d23a620d47623170f6db38 Mon Sep 17 00:00:00 2001 From: Jim Barlow Date: Tue, 21 Jan 2014 21:36:41 -0800 Subject: [PATCH 5/5] Expose pixFindSkew API --- src/leptonica.py | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/src/leptonica.py b/src/leptonica.py index ee0c642e..c834ee74 100644 --- a/src/leptonica.py +++ b/src/leptonica.py @@ -73,6 +73,8 @@ lept.pixScale.argtypes = [PIX, C.c_float, C.c_float] lept.pixScale.restype = PIX lept.pixDeskew.argtypes = [PIX, C.c_int32] lept.pixDeskew.restype = PIX +lept.pixFindSkew.argtypes = [PIX, C.POINTER(C.c_float), C.POINTER(C.c_float)] +lept.pixFindSkew.restype = C.c_int32 lept.pixWriteImpliedFormat.argtypes = [C.c_char_p, PIX, C.c_int32, C.c_int32] lept.pixWriteImpliedFormat.restype = C.c_int32 lept.pixDestroy.argtypes = [C.POINTER(PIX)] @@ -166,6 +168,22 @@ def pixDeskew(pix, reduction_factor=0): return lept.pixDeskew(pix, reduction_factor) +def pixFindSkew(pix): + """Returns a tuple (deskew angle in degrees, confidence value). + + Returns (None, None) if no angle is available. + + """ + with LeptonicaErrorTrap(): + angle = C.c_float(0.0) + confidence = C.c_float(0.0) + result = lept.pixFindSkew(pix, C.byref(angle), C.byref(confidence)) + if result == 0: + return (angle.value, confidence.value) + else: + return (None, None) + + def pixWriteImpliedFormat(filename, pix, jpeg_quality=0, jpeg_progressive=0): """Write pix to the filename, with the extension indicating format. @@ -283,3 +301,30 @@ def test_pnm_output(): for param in params: _test_output(*param) + +def test_skew_angle(): + from PIL import Image, ImageDraw + from tempfile import NamedTemporaryFile + + im = Image.new(mode='1', size=(1000, 1000), color=1) + + draw = ImageDraw.Draw(im) + for n in range(20): + draw.line([(50, 25 + 50*n), (950, 25 + 50*n)], width=1) + del draw + + test_angles = [0.1 * ang for ang in range(1, 10)] + \ + [float(ang) for ang in range(1, 7)] + test_angles += [-ang for ang in test_angles] + test_angles = sorted(test_angles) + + for rotate_angle in test_angles: + rotated_im = im.rotate(rotate_angle) + with NamedTemporaryFile(prefix='lept-skew', suffix='.png', delete=True) as tmpfile: + rotated_im.save(tmpfile) + pix = pixRead(tmpfile.name) + angle, confidence = pixFindSkew(pix) + pixDestroy(pix) + print('{0} {1} {2}'.format(rotate_angle, angle, confidence), file=sys.stderr) + +