Doc-Qual
Doc-Qual is a lightweight Python package for estimating whether a document image is ready for OCR before you spend time and money running OCR.
It computes a 0-100 OCR readiness score from interpretable image features:
| Feature | What it measures |
|---|---|
| Sharpness | Laplacian variance for blur detection |
| Noise | Gaussian residual noise estimate |
| Edges | Canny edge density for text-like structure |
| Skew | Hough-line based rotation estimate |
| Brightness | Exposure and contrast balance |
| Ridges | Hessian response for stroke-like structures |
Installation
Install directly from GitHub (PyPI release coming soon):
pip install git+https://github.com/PradeepMadhavankutty/doc-qual.git
For development:
git clone https://github.com/PradeepMadhavankutty/doc-qual.git
cd doc-qual
pip install -e ".[dev]"
Python Usage
from doc_qual import compute_doc_qual_score
result = compute_doc_qual_score("scan.jpg", verbose=False)
print(result.ocr_score)
print(result.passed)
print(result.recommendations)
CLI Usage
doc-qual path/to/image.jpg
doc-qual path/to/image.jpg --format json
doc-qual path/to/image.jpg --threshold 60
When --threshold is provided, the CLI exits with code 1 if the image score is below the threshold. This makes it useful in CI and batch document-processing pipelines.
Current Status
This is an alpha implementation with expert-calibrated default weights. The long-term research direction is to calibrate feature weights empirically against OCR character error rate across datasets and engines.
Development
pytest
ruff check .
python -m build
License
MIT
1 maintainer
Release files for Doc-Qual 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| doc_qual-0.1.0.tar.gz | 7.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| doc_qual-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 15.1 MB
Release files / doc_qual-0.1.0.tar.gz
| Download URL | doc_qual-0.1.0.tar.gz |
|---|---|
| Size | 7.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fefe8a34d0288f2efb3d8ac29d039e6151784929e3991a91256c8e0024fe5105
|
|
BLAKE2b-256 checksum How to use checksums |
683a5b6340df8f417ffd7b73e056408c522ffdbb1921cac25786307aaeee99a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
Release files / doc_qual-0.1.0-py3-none-any.whl
| Download URL | doc_qual-0.1.0-py3-none-any.whl |
|---|---|
| Size | 7.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
58a00f80e6914b0a85957a91b64bed80eca3749f39f458e15dfbbbfb9b012fc5
|
|
BLAKE2b-256 checksum How to use checksums |
53b478446e498c2a2bc6610145dbd28ef1727b30902e5d702de387f3e23a7882
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.11
|
