docangle 4.4.0

First public release of docangle: it finds the rotation of a scanned or photographed Latin-script document page, anywhere in [-180°, +180°], and returns a confidence and a needs_review flag so uncertain pages can go to a person. A pre-processing step for OCR and archiving pipelines.

Install

git clone https://github.com/KazimMammadli/docangle && cd docangle
pip install -e .            # numpy, opencv-python-headless, onnxruntime
pip install -e ".[pdf]"     # + pypdfium2 for PDF input

Not on PyPI: the models are part of the repository, so install from a clone. Python 3.10 or newer.

Use

from docangle import get_pipeline

r = get_pipeline().predict("page.jpg")          # PDFs too: predict("scan.pdf", page=0)
print(r.angle, r.confidence, r.needs_review)
upright, r = get_pipeline().correct("page.jpg") # the original image, rotated upright

python -m docangle page.jpg -o upright.jpg

Measured results

• Wrong quadrant, simulated pages turned by any angle (3600 cases, four primary pools): 0.58 %, none of them accepted by the review rule on pages whose source is itself upright. Three external pools (2700 cases): 1.93 %, 6 accepted.
• Exact quarter turns of clean pages (700 cases, 7 pools): 0 wrong.
• Effect on OCR (12 Azerbaijani pages, 3 engines): OCR alone 33-68 % word F1, with docangle 97-99 %.
• Speed: median 35-45 ms per page for a JPEG file on a CPU; GPU 16.8 ms against 38.6 ms CPU for in-memory pages.

Every number comes from a command in this repository; sources are in reports/ and the full record is the book in docs/.

Weak spots: there is no labelled set of real phone photos of the intended documents yet; photographic conditions are simulated. Receipts photographed by phone flip in 2.7 % of cases (most are reviewed). See chapter 10.

Licence

Code: MIT. Own model weights: research and evaluation use; the PP-LCNet model: Apache-2.0. See models/README.md.

Full list of changes: CHANGELOG.md.