obliq-ocr 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of obliq-ocr might be problematic. Click here for more details.
- obliq_ocr/__init__.py +43 -0
- obliq_ocr/__main__.py +6 -0
- obliq_ocr/_version.py +24 -0
- obliq_ocr/cli.py +91 -0
- obliq_ocr/core.py +240 -0
- obliq_ocr/engine.py +122 -0
- obliq_ocr/parser.py +238 -0
- obliq_ocr/py.typed +0 -0
- obliq_ocr/schemas.py +154 -0
- obliq_ocr/utils.py +181 -0
- obliq_ocr-0.1.0.dist-info/METADATA +209 -0
- obliq_ocr-0.1.0.dist-info/RECORD +14 -0
- obliq_ocr-0.1.0.dist-info/WHEEL +4 -0
- obliq_ocr-0.1.0.dist-info/entry_points.txt +2 -0
obliq_ocr/__init__.py
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""
|
|
2
|
+
obliq_ocr – Page-aware OCR and document parsing pipeline.
|
|
3
|
+
|
|
4
|
+
Combines PyMuPDF (digital text layer) with RapidOCR (PP-OCR / ONNX Runtime)
|
|
5
|
+
to extract structured text from PDFs and images on a per-page basis.
|
|
6
|
+
|
|
7
|
+
Quick start
|
|
8
|
+
-----------
|
|
9
|
+
>>> from obliq_ocr import parse_document
|
|
10
|
+
>>> result = parse_document("invoice.pdf")
|
|
11
|
+
>>> print(result.full_text())
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
try:
|
|
15
|
+
from obliq_ocr._version import __version__
|
|
16
|
+
except ImportError:
|
|
17
|
+
try:
|
|
18
|
+
from importlib.metadata import version
|
|
19
|
+
|
|
20
|
+
__version__ = version("obliq-ocr")
|
|
21
|
+
except Exception:
|
|
22
|
+
__version__ = "0.1.0.dev0"
|
|
23
|
+
|
|
24
|
+
from obliq_ocr.core import DocResult, PageResult, save_result
|
|
25
|
+
from obliq_ocr.core import extract_document as parse_document # primary public API
|
|
26
|
+
from obliq_ocr.engine import build_ocr, detect_device
|
|
27
|
+
from obliq_ocr.schemas import BoundingBox, DocumentOutput, PageOutput
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
# Primary entrypoint
|
|
31
|
+
"parse_document",
|
|
32
|
+
# Result objects
|
|
33
|
+
"DocResult",
|
|
34
|
+
"PageResult",
|
|
35
|
+
"save_result",
|
|
36
|
+
# Engine helpers
|
|
37
|
+
"build_ocr",
|
|
38
|
+
"detect_device",
|
|
39
|
+
# Schema / output types
|
|
40
|
+
"DocumentOutput",
|
|
41
|
+
"PageOutput",
|
|
42
|
+
"BoundingBox",
|
|
43
|
+
]
|
obliq_ocr/__main__.py
ADDED
obliq_ocr/_version.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# file generated by vcs-versioning
|
|
2
|
+
# don't change, don't track in version control
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
__all__ = [
|
|
6
|
+
"__version__",
|
|
7
|
+
"__version_tuple__",
|
|
8
|
+
"version",
|
|
9
|
+
"version_tuple",
|
|
10
|
+
"__commit_id__",
|
|
11
|
+
"commit_id",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
version: str
|
|
15
|
+
__version__: str
|
|
16
|
+
__version_tuple__: tuple[int | str, ...]
|
|
17
|
+
version_tuple: tuple[int | str, ...]
|
|
18
|
+
commit_id: str | None
|
|
19
|
+
__commit_id__: str | None
|
|
20
|
+
|
|
21
|
+
__version__ = version = '0.1.0'
|
|
22
|
+
__version_tuple__ = version_tuple = (0, 1, 0)
|
|
23
|
+
|
|
24
|
+
__commit_id__ = commit_id = None
|
obliq_ocr/cli.py
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"""
|
|
2
|
+
cli.py – Command-line interface for obliq-OCR.
|
|
3
|
+
|
|
4
|
+
Usage
|
|
5
|
+
-----
|
|
6
|
+
::
|
|
7
|
+
|
|
8
|
+
python -m obliq_ocr path/to/document.pdf
|
|
9
|
+
python -m obliq_ocr path/to/scan.jpg --device cpu --output-dir results/
|
|
10
|
+
python -m obliq_ocr path/to/doc.pdf --quiet
|
|
11
|
+
|
|
12
|
+
This is also exposed as the ``obliq-ocr`` console script (see pyproject.toml).
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import argparse
|
|
18
|
+
import sys
|
|
19
|
+
import time
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _build_parser() -> argparse.ArgumentParser:
|
|
24
|
+
p = argparse.ArgumentParser(
|
|
25
|
+
prog="obliq-ocr",
|
|
26
|
+
description="Page-aware OCR and document parsing pipeline (PyMuPDF + RapidOCR).",
|
|
27
|
+
)
|
|
28
|
+
p.add_argument(
|
|
29
|
+
"input",
|
|
30
|
+
metavar="FILE",
|
|
31
|
+
help="PDF or image file to process.",
|
|
32
|
+
)
|
|
33
|
+
p.add_argument(
|
|
34
|
+
"--output-dir",
|
|
35
|
+
default="outputs",
|
|
36
|
+
metavar="DIR",
|
|
37
|
+
help="Directory to write JSON and TXT output files. Default: outputs/",
|
|
38
|
+
)
|
|
39
|
+
p.add_argument(
|
|
40
|
+
"--device",
|
|
41
|
+
choices=["auto", "cpu", "cuda"],
|
|
42
|
+
default="auto",
|
|
43
|
+
help="Compute device for OCR inference. Default: auto",
|
|
44
|
+
)
|
|
45
|
+
p.add_argument(
|
|
46
|
+
"--quiet",
|
|
47
|
+
action="store_true",
|
|
48
|
+
help="Suppress per-page progress output.",
|
|
49
|
+
)
|
|
50
|
+
return p
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def main(argv=None):
|
|
54
|
+
args = _build_parser().parse_args(argv)
|
|
55
|
+
|
|
56
|
+
from obliq_ocr.core import extract_document, save_result # lazy import
|
|
57
|
+
|
|
58
|
+
input_path = Path(args.input)
|
|
59
|
+
force_device = None if args.device == "auto" else args.device
|
|
60
|
+
|
|
61
|
+
t0 = time.perf_counter()
|
|
62
|
+
try:
|
|
63
|
+
result = extract_document(
|
|
64
|
+
input_path,
|
|
65
|
+
force_device=force_device,
|
|
66
|
+
verbose=not args.quiet,
|
|
67
|
+
)
|
|
68
|
+
except FileNotFoundError as exc:
|
|
69
|
+
print(f"ERROR: {exc}", file=sys.stderr)
|
|
70
|
+
sys.exit(1)
|
|
71
|
+
except ValueError as exc:
|
|
72
|
+
print(f"ERROR: {exc}", file=sys.stderr)
|
|
73
|
+
sys.exit(1)
|
|
74
|
+
|
|
75
|
+
total = time.perf_counter() - t0
|
|
76
|
+
|
|
77
|
+
n_ocr = sum(p.method == "ocr" for p in result.pages)
|
|
78
|
+
n_text = sum(p.method == "text_layer" for p in result.pages)
|
|
79
|
+
n_blank = sum(p.method == "blank" for p in result.pages)
|
|
80
|
+
|
|
81
|
+
print(
|
|
82
|
+
f"\n{len(result.pages)} pages | {n_ocr} OCR | {n_text} text layer "
|
|
83
|
+
f"| {n_blank} blank | {total:.2f}s total on {result.device}"
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
json_path, txt_path = save_result(result, out_dir=args.output_dir)
|
|
87
|
+
print(f"saved: {json_path} {txt_path}")
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
if __name__ == "__main__":
|
|
91
|
+
main()
|
obliq_ocr/core.py
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
"""
|
|
2
|
+
core.py – Main pipeline orchestration for the obliq-OCR package.
|
|
3
|
+
|
|
4
|
+
Public API
|
|
5
|
+
----------
|
|
6
|
+
:func:`extract_document` (aliased as ``parse_document`` in ``__init__.py``)
|
|
7
|
+
Parse a PDF or image file and return a :class:`DocResult`.
|
|
8
|
+
|
|
9
|
+
:class:`DocResult` / :class:`PageResult`
|
|
10
|
+
Lightweight result dataclasses retained for backwards-compatibility
|
|
11
|
+
with the original notebook output format. The richer typed schema is
|
|
12
|
+
in :mod:`obliq_ocr.schemas`.
|
|
13
|
+
|
|
14
|
+
:func:`save_result`
|
|
15
|
+
Write JSON and plain-text representations to disk.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import json
|
|
21
|
+
import time
|
|
22
|
+
from dataclasses import asdict, dataclass, field
|
|
23
|
+
from pathlib import Path
|
|
24
|
+
from typing import List, Optional
|
|
25
|
+
|
|
26
|
+
from obliq_ocr.engine import detect_device, get_ocr_engine
|
|
27
|
+
from obliq_ocr.parser import (
|
|
28
|
+
iter_pages,
|
|
29
|
+
ocr_extract,
|
|
30
|
+
render_page,
|
|
31
|
+
text_layer_extract,
|
|
32
|
+
triage_page,
|
|
33
|
+
)
|
|
34
|
+
from obliq_ocr.utils import is_blank_image
|
|
35
|
+
|
|
36
|
+
# ---------------------------------------------------------------------------
|
|
37
|
+
# Result dataclasses (notebook-compatible)
|
|
38
|
+
# ---------------------------------------------------------------------------
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass
|
|
42
|
+
class PageResult:
|
|
43
|
+
"""Per-page extraction result.
|
|
44
|
+
|
|
45
|
+
Parameters
|
|
46
|
+
----------
|
|
47
|
+
page:
|
|
48
|
+
1-indexed page number.
|
|
49
|
+
method:
|
|
50
|
+
``"text_layer"``, ``"ocr"``, or ``"blank"``.
|
|
51
|
+
reason:
|
|
52
|
+
Human-readable triage reason.
|
|
53
|
+
text:
|
|
54
|
+
Extracted text (reading-order, columns separated by `` | ``).
|
|
55
|
+
n_chars:
|
|
56
|
+
Character count of *text*.
|
|
57
|
+
confidence:
|
|
58
|
+
Mean OCR confidence in ``[0, 1]``, or ``None`` for text-layer pages.
|
|
59
|
+
seconds:
|
|
60
|
+
Wall-clock processing time for this page.
|
|
61
|
+
"""
|
|
62
|
+
|
|
63
|
+
page: int
|
|
64
|
+
method: str
|
|
65
|
+
reason: str
|
|
66
|
+
text: str
|
|
67
|
+
n_chars: int
|
|
68
|
+
confidence: Optional[float]
|
|
69
|
+
seconds: float
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass
|
|
73
|
+
class DocResult:
|
|
74
|
+
"""Top-level result for a parsed document.
|
|
75
|
+
|
|
76
|
+
Parameters
|
|
77
|
+
----------
|
|
78
|
+
source:
|
|
79
|
+
Base filename of the input document.
|
|
80
|
+
device:
|
|
81
|
+
``"CPU"`` or ``"CUDA"``.
|
|
82
|
+
pages:
|
|
83
|
+
Ordered list of :class:`PageResult` objects.
|
|
84
|
+
"""
|
|
85
|
+
|
|
86
|
+
source: str
|
|
87
|
+
device: str
|
|
88
|
+
pages: List[PageResult] = field(default_factory=list)
|
|
89
|
+
|
|
90
|
+
def full_text(self) -> str:
|
|
91
|
+
"""Return all pages concatenated with page-number headers."""
|
|
92
|
+
parts = [f"===== PAGE {p.page} [{p.method}] =====\n{p.text}" for p in self.pages]
|
|
93
|
+
return "\n\n".join(parts)
|
|
94
|
+
|
|
95
|
+
def to_dict(self) -> dict:
|
|
96
|
+
return {
|
|
97
|
+
"source": self.source,
|
|
98
|
+
"device": self.device,
|
|
99
|
+
"pages": [asdict(p) for p in self.pages],
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
# ---------------------------------------------------------------------------
|
|
104
|
+
# Main pipeline
|
|
105
|
+
# ---------------------------------------------------------------------------
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def extract_document(
|
|
109
|
+
path,
|
|
110
|
+
*,
|
|
111
|
+
force_device: Optional[str] = None,
|
|
112
|
+
verbose: bool = True,
|
|
113
|
+
) -> DocResult:
|
|
114
|
+
"""Parse a PDF or image file and return a :class:`DocResult`.
|
|
115
|
+
|
|
116
|
+
This is the primary public entrypoint, aliased as ``parse_document``
|
|
117
|
+
in :mod:`obliq_ocr.__init__`.
|
|
118
|
+
|
|
119
|
+
Parameters
|
|
120
|
+
----------
|
|
121
|
+
path:
|
|
122
|
+
``str`` or :class:`pathlib.Path` pointing to the document to parse.
|
|
123
|
+
Supported formats: PDF, JPEG, PNG, TIFF, BMP, WebP.
|
|
124
|
+
force_device:
|
|
125
|
+
``"cpu"``, ``"cuda"``, or ``None`` (auto-detect). Overrides the
|
|
126
|
+
``OBLIQ_OCR_DEVICE`` environment variable.
|
|
127
|
+
verbose:
|
|
128
|
+
Print per-page progress to stdout. Default ``True``.
|
|
129
|
+
|
|
130
|
+
Returns
|
|
131
|
+
-------
|
|
132
|
+
DocResult
|
|
133
|
+
Structured result with one :class:`PageResult` per page.
|
|
134
|
+
|
|
135
|
+
Raises
|
|
136
|
+
------
|
|
137
|
+
FileNotFoundError
|
|
138
|
+
If *path* does not exist.
|
|
139
|
+
ValueError
|
|
140
|
+
If the file is password-protected.
|
|
141
|
+
"""
|
|
142
|
+
path = Path(path)
|
|
143
|
+
if not path.exists():
|
|
144
|
+
raise FileNotFoundError(f"Input file not found: {path}")
|
|
145
|
+
|
|
146
|
+
use_cuda = detect_device(force=force_device)
|
|
147
|
+
ocr_engine = get_ocr_engine(use_cuda=use_cuda)
|
|
148
|
+
device_label = "CUDA" if use_cuda else "CPU"
|
|
149
|
+
|
|
150
|
+
res = DocResult(source=path.name, device=device_label)
|
|
151
|
+
|
|
152
|
+
for page_no, pdf_page, img in iter_pages(path):
|
|
153
|
+
t0 = time.perf_counter()
|
|
154
|
+
|
|
155
|
+
if pdf_page is not None:
|
|
156
|
+
# ── digital PDF page ──────────────────────────────────────────
|
|
157
|
+
use_text, reason = triage_page(pdf_page)
|
|
158
|
+
if use_text:
|
|
159
|
+
text, _ = text_layer_extract(pdf_page)
|
|
160
|
+
pr = PageResult(
|
|
161
|
+
page=page_no,
|
|
162
|
+
method="text_layer",
|
|
163
|
+
reason=reason,
|
|
164
|
+
text=text,
|
|
165
|
+
n_chars=len(text),
|
|
166
|
+
confidence=None,
|
|
167
|
+
seconds=time.perf_counter() - t0,
|
|
168
|
+
)
|
|
169
|
+
res.pages.append(pr)
|
|
170
|
+
if verbose:
|
|
171
|
+
print(f"page {page_no:>3}: text_layer {pr.seconds * 1000:7.1f} ms ({reason})")
|
|
172
|
+
continue
|
|
173
|
+
# Fall through: render and OCR
|
|
174
|
+
img = render_page(pdf_page)
|
|
175
|
+
else:
|
|
176
|
+
# ── standalone image input ────────────────────────────────────
|
|
177
|
+
reason = "image file"
|
|
178
|
+
if img is None:
|
|
179
|
+
continue
|
|
180
|
+
if is_blank_image(img):
|
|
181
|
+
pr = PageResult(
|
|
182
|
+
page=page_no,
|
|
183
|
+
method="blank",
|
|
184
|
+
reason=reason + ", blank page",
|
|
185
|
+
text="",
|
|
186
|
+
n_chars=0,
|
|
187
|
+
confidence=None,
|
|
188
|
+
seconds=time.perf_counter() - t0,
|
|
189
|
+
)
|
|
190
|
+
else:
|
|
191
|
+
text, _elements, conf = ocr_extract(img, ocr_engine)
|
|
192
|
+
pr = PageResult(
|
|
193
|
+
page=page_no,
|
|
194
|
+
method="ocr",
|
|
195
|
+
reason=reason,
|
|
196
|
+
text=text,
|
|
197
|
+
n_chars=len(text),
|
|
198
|
+
confidence=conf,
|
|
199
|
+
seconds=time.perf_counter() - t0,
|
|
200
|
+
)
|
|
201
|
+
|
|
202
|
+
res.pages.append(pr)
|
|
203
|
+
if verbose:
|
|
204
|
+
conf_str = f"conf {pr.confidence:.2f}" if pr.confidence is not None else ""
|
|
205
|
+
print(
|
|
206
|
+
f"page {page_no:>3}: {pr.method:<11} {pr.seconds * 1000:7.1f} ms"
|
|
207
|
+
f" ({reason}) {conf_str}"
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
return res
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
# ---------------------------------------------------------------------------
|
|
214
|
+
# Persistence helpers
|
|
215
|
+
# ---------------------------------------------------------------------------
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def save_result(res: DocResult, out_dir: str = "outputs") -> tuple[Path, Path]:
|
|
219
|
+
"""Write JSON and plain-text files for *res* to *out_dir*.
|
|
220
|
+
|
|
221
|
+
Parameters
|
|
222
|
+
----------
|
|
223
|
+
res:
|
|
224
|
+
A :class:`DocResult` returned by :func:`extract_document`.
|
|
225
|
+
out_dir:
|
|
226
|
+
Directory path (created automatically if it does not exist).
|
|
227
|
+
|
|
228
|
+
Returns
|
|
229
|
+
-------
|
|
230
|
+
(json_path, txt_path)
|
|
231
|
+
Paths to the saved files.
|
|
232
|
+
"""
|
|
233
|
+
out = Path(out_dir)
|
|
234
|
+
out.mkdir(parents=True, exist_ok=True)
|
|
235
|
+
stem = Path(res.source).stem
|
|
236
|
+
json_path = out / f"{stem}.json"
|
|
237
|
+
txt_path = out / f"{stem}.txt"
|
|
238
|
+
json_path.write_text(json.dumps(res.to_dict(), indent=2, ensure_ascii=False), encoding="utf-8")
|
|
239
|
+
txt_path.write_text(res.full_text(), encoding="utf-8")
|
|
240
|
+
return json_path, txt_path
|
obliq_ocr/engine.py
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
"""
|
|
2
|
+
engine.py – OCR engine initialisation and device detection.
|
|
3
|
+
|
|
4
|
+
Loads RapidOCR once and exposes a singleton-style accessor so that
|
|
5
|
+
the expensive model-loading step is only performed on first use.
|
|
6
|
+
|
|
7
|
+
ONNX Runtime execution provider selection
|
|
8
|
+
------------------------------------------
|
|
9
|
+
* If ``onnxruntime-gpu`` is installed **and** ``CUDAExecutionProvider``
|
|
10
|
+
is present, CUDA is used automatically.
|
|
11
|
+
* Set the ``OBLIQ_OCR_DEVICE`` environment variable to ``"cpu"`` or
|
|
12
|
+
``"cuda"`` to override auto-detection.
|
|
13
|
+
* ``FORCE_DEVICE`` parameter in :func:`build_ocr` accepts the same values.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import os
|
|
19
|
+
from typing import Optional
|
|
20
|
+
|
|
21
|
+
import onnxruntime as ort
|
|
22
|
+
|
|
23
|
+
# ── configuration knobs (can be overridden before the first import) ──────────
|
|
24
|
+
OCR_MIN_SCORE: float = 0.5 # drop OCR boxes below this confidence
|
|
25
|
+
# ────────────────────────────────────────────────────────────────────────────
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def detect_device(force: Optional[str] = None) -> bool:
|
|
29
|
+
"""Return ``True`` if CUDA should be used for OCR inference.
|
|
30
|
+
|
|
31
|
+
Parameters
|
|
32
|
+
----------
|
|
33
|
+
force:
|
|
34
|
+
``"cpu"`` to always use CPU, ``"cuda"`` to require GPU, or
|
|
35
|
+
``None`` (default) for automatic detection.
|
|
36
|
+
|
|
37
|
+
Raises
|
|
38
|
+
------
|
|
39
|
+
RuntimeError
|
|
40
|
+
If ``force="cuda"`` is requested but CUDA is unavailable.
|
|
41
|
+
"""
|
|
42
|
+
env_override = os.environ.get("OBLIQ_OCR_DEVICE", "").strip().lower()
|
|
43
|
+
effective = (force or env_override or "auto").lower()
|
|
44
|
+
|
|
45
|
+
providers = ort.get_available_providers()
|
|
46
|
+
cuda_available = "CUDAExecutionProvider" in providers
|
|
47
|
+
|
|
48
|
+
if effective == "cuda":
|
|
49
|
+
if not cuda_available:
|
|
50
|
+
raise RuntimeError(
|
|
51
|
+
"CUDA requested (OBLIQ_OCR_DEVICE=cuda / force='cuda') "
|
|
52
|
+
"but CUDAExecutionProvider is not available. "
|
|
53
|
+
"Install onnxruntime-gpu and ensure CUDA drivers are present."
|
|
54
|
+
)
|
|
55
|
+
return True
|
|
56
|
+
if effective == "cpu":
|
|
57
|
+
return False
|
|
58
|
+
# auto
|
|
59
|
+
return cuda_available
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def build_ocr(use_cuda: bool = False):
|
|
63
|
+
"""Instantiate and return a :class:`rapidocr_onnxruntime.RapidOCR` engine.
|
|
64
|
+
|
|
65
|
+
Falls back silently to CPU if GPU initialisation fails.
|
|
66
|
+
|
|
67
|
+
Parameters
|
|
68
|
+
----------
|
|
69
|
+
use_cuda:
|
|
70
|
+
Whether to request CUDA execution providers for all three sub-models
|
|
71
|
+
(detection, classification, recognition).
|
|
72
|
+
|
|
73
|
+
Returns
|
|
74
|
+
-------
|
|
75
|
+
rapidocr_onnxruntime.RapidOCR
|
|
76
|
+
A configured OCR engine ready for inference.
|
|
77
|
+
"""
|
|
78
|
+
from rapidocr_onnxruntime import (
|
|
79
|
+
RapidOCR, # imported here to keep the module importable without rapidocr installed
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
kw = dict(
|
|
83
|
+
det_use_cuda=use_cuda,
|
|
84
|
+
cls_use_cuda=use_cuda,
|
|
85
|
+
rec_use_cuda=use_cuda,
|
|
86
|
+
det_limit_side_len=1280,
|
|
87
|
+
det_limit_type="max",
|
|
88
|
+
# Passing None tells RapidOCR to use its own bundled model paths.
|
|
89
|
+
det_model_path=None,
|
|
90
|
+
cls_model_path=None,
|
|
91
|
+
rec_model_path=None,
|
|
92
|
+
text_score=OCR_MIN_SCORE,
|
|
93
|
+
)
|
|
94
|
+
try:
|
|
95
|
+
return RapidOCR(**kw)
|
|
96
|
+
except Exception as exc: # any GPU-init problem → safe CPU fallback
|
|
97
|
+
print(f"[obliq_ocr] OCR GPU init failed ({exc!r:.120}); falling back to CPU.")
|
|
98
|
+
kw.update(det_use_cuda=False, cls_use_cuda=False, rec_use_cuda=False)
|
|
99
|
+
return RapidOCR(**kw)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
# ---------------------------------------------------------------------------
|
|
103
|
+
# Module-level lazy singleton – avoids re-loading models on every call.
|
|
104
|
+
# ---------------------------------------------------------------------------
|
|
105
|
+
_ocr_engine = None
|
|
106
|
+
_ocr_engine_cuda: Optional[bool] = None
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def get_ocr_engine(use_cuda: bool = False):
|
|
110
|
+
"""Return the module-level OCR engine, initialising it on first call.
|
|
111
|
+
|
|
112
|
+
Parameters
|
|
113
|
+
----------
|
|
114
|
+
use_cuda:
|
|
115
|
+
Passed to :func:`build_ocr` on first initialisation. Ignored on
|
|
116
|
+
subsequent calls (the engine is reused as-is).
|
|
117
|
+
"""
|
|
118
|
+
global _ocr_engine, _ocr_engine_cuda
|
|
119
|
+
if _ocr_engine is None or _ocr_engine_cuda != use_cuda:
|
|
120
|
+
_ocr_engine = build_ocr(use_cuda)
|
|
121
|
+
_ocr_engine_cuda = use_cuda
|
|
122
|
+
return _ocr_engine
|
obliq_ocr/parser.py
ADDED
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
"""
|
|
2
|
+
parser.py – Page-level triage and text extraction logic.
|
|
3
|
+
|
|
4
|
+
This module contains the per-page decision logic:
|
|
5
|
+
|
|
6
|
+
* :func:`triage_page` – decides *text layer* vs *OCR* vs *blank*.
|
|
7
|
+
* :func:`text_layer_extract` – extracts words from PyMuPDF's text layer
|
|
8
|
+
and re-assembles them into reading-order lines.
|
|
9
|
+
* :func:`render_page` – rasterises a PDF page to an RGB NumPy array.
|
|
10
|
+
* :func:`ocr_extract` – runs RapidOCR and returns structured elements.
|
|
11
|
+
* :func:`iter_pages` – yields ``(page_no, pdf_page, image_array)``
|
|
12
|
+
tuples for both PDF and standalone-image inputs.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import re
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
from typing import Any, Iterator, List, Optional, Tuple
|
|
20
|
+
|
|
21
|
+
import numpy as np
|
|
22
|
+
|
|
23
|
+
from obliq_ocr.schemas import TextElement
|
|
24
|
+
from obliq_ocr.utils import (
|
|
25
|
+
WordBox,
|
|
26
|
+
fit_image,
|
|
27
|
+
garbage_ratio,
|
|
28
|
+
image_cover,
|
|
29
|
+
words_to_lines,
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
# ── knobs ────────────────────────────────────────────────────────────────────
|
|
33
|
+
OCR_DPI: int = 200 # 150 = faster, 300 = tiny print / poor scans
|
|
34
|
+
MIN_TEXT_CHARS: int = 40 # fewer non-space chars than this → treat page as scanned
|
|
35
|
+
GARBAGE_MAX: float = 0.15 # share of junk characters allowed before OCR fallback
|
|
36
|
+
IMG_COVER_MAX: float = 0.60 # page mostly covered by an image …
|
|
37
|
+
IMG_MIN_CHARS: int = 200 # … and not much real text → treat as scanned
|
|
38
|
+
IMG_EXTENSIONS = {".jpg", ".jpeg", ".png", ".bmp", ".tif", ".tiff", ".webp"}
|
|
39
|
+
# ─────────────────────────────────────────────────────────────────────────────
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
# ---------------------------------------------------------------------------
|
|
43
|
+
# Page triage
|
|
44
|
+
# ---------------------------------------------------------------------------
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def triage_page(page) -> Tuple[bool, str]:
|
|
48
|
+
"""Decide whether to use the PDF text layer or fall back to OCR.
|
|
49
|
+
|
|
50
|
+
Parameters
|
|
51
|
+
----------
|
|
52
|
+
page:
|
|
53
|
+
A :class:`pymupdf.Page` object.
|
|
54
|
+
|
|
55
|
+
Returns
|
|
56
|
+
-------
|
|
57
|
+
(use_text_layer, reason)
|
|
58
|
+
``use_text_layer=True`` means the digital text layer is usable;
|
|
59
|
+
``False`` means the page should be rasterised and OCR'd.
|
|
60
|
+
"""
|
|
61
|
+
text = page.get_text("text")
|
|
62
|
+
n = len(re.sub(r"\s", "", text))
|
|
63
|
+
|
|
64
|
+
if n < MIN_TEXT_CHARS:
|
|
65
|
+
return False, f"only {n} text chars"
|
|
66
|
+
|
|
67
|
+
g = garbage_ratio(text)
|
|
68
|
+
if g > GARBAGE_MAX:
|
|
69
|
+
return False, f"garbled text layer ({g:.0%} junk)"
|
|
70
|
+
|
|
71
|
+
cover = image_cover(page)
|
|
72
|
+
if cover > IMG_COVER_MAX and n < IMG_MIN_CHARS:
|
|
73
|
+
return False, f"full-page image + thin text ({n} chars)"
|
|
74
|
+
|
|
75
|
+
return True, f"{n} chars, image cover {cover:.0%}"
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
# ---------------------------------------------------------------------------
|
|
79
|
+
# Digital text-layer extraction
|
|
80
|
+
# ---------------------------------------------------------------------------
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def text_layer_extract(page) -> Tuple[str, List[TextElement]]:
|
|
84
|
+
"""Extract text from the PDF text layer and return (text, elements).
|
|
85
|
+
|
|
86
|
+
Words are re-grouped into reading-order lines by :func:`words_to_lines`.
|
|
87
|
+
Each word becomes a :class:`TextElement` with its bounding box; confidence
|
|
88
|
+
is ``None`` because PyMuPDF does not supply a score.
|
|
89
|
+
|
|
90
|
+
Parameters
|
|
91
|
+
----------
|
|
92
|
+
page:
|
|
93
|
+
A :class:`pymupdf.Page` object.
|
|
94
|
+
|
|
95
|
+
Returns
|
|
96
|
+
-------
|
|
97
|
+
(text, elements)
|
|
98
|
+
*text* is the full page text; *elements* contains per-word boxes.
|
|
99
|
+
"""
|
|
100
|
+
raw_words = page.get_text("words") # list of (x0, y0, x1, y1, word, …)
|
|
101
|
+
word_boxes: List[WordBox] = [(w[0], w[1], w[2], w[3], w[4]) for w in raw_words]
|
|
102
|
+
|
|
103
|
+
elements: List[TextElement] = [
|
|
104
|
+
TextElement(
|
|
105
|
+
text=wb[4],
|
|
106
|
+
bbox=[wb[0], wb[1], wb[2], wb[3]],
|
|
107
|
+
confidence=None,
|
|
108
|
+
)
|
|
109
|
+
for wb in word_boxes
|
|
110
|
+
]
|
|
111
|
+
text = words_to_lines(word_boxes)
|
|
112
|
+
return text, elements
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
# ---------------------------------------------------------------------------
|
|
116
|
+
# Rasterisation
|
|
117
|
+
# ---------------------------------------------------------------------------
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def render_page(page) -> np.ndarray:
|
|
121
|
+
"""Rasterise *page* to an RGB NumPy array at :data:`OCR_DPI`.
|
|
122
|
+
|
|
123
|
+
The result is downscaled if its longest side exceeds
|
|
124
|
+
:data:`obliq_ocr.utils.MAX_SIDE_PX`.
|
|
125
|
+
|
|
126
|
+
Parameters
|
|
127
|
+
----------
|
|
128
|
+
page:
|
|
129
|
+
A :class:`pymupdf.Page` object.
|
|
130
|
+
|
|
131
|
+
Returns
|
|
132
|
+
-------
|
|
133
|
+
np.ndarray
|
|
134
|
+
``uint8`` array of shape ``(H, W, 3)``.
|
|
135
|
+
"""
|
|
136
|
+
import pymupdf # local import so the module is importable without pymupdf
|
|
137
|
+
|
|
138
|
+
pix = page.get_pixmap(dpi=OCR_DPI, colorspace=pymupdf.csRGB, alpha=False)
|
|
139
|
+
img = np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.h, pix.w, 3)
|
|
140
|
+
return fit_image(img)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
# ---------------------------------------------------------------------------
|
|
144
|
+
# OCR extraction
|
|
145
|
+
# ---------------------------------------------------------------------------
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def ocr_extract(
|
|
149
|
+
img: np.ndarray,
|
|
150
|
+
ocr_engine,
|
|
151
|
+
) -> Tuple[str, List[TextElement], Optional[float]]:
|
|
152
|
+
"""Run RapidOCR on *img* and return ``(text, elements, mean_confidence)``.
|
|
153
|
+
|
|
154
|
+
Bounding boxes are converted from the quad format returned by PP-OCR
|
|
155
|
+
(four ``[x, y]`` corner points) to axis-aligned ``[x0, y0, x1, y1]``.
|
|
156
|
+
|
|
157
|
+
Parameters
|
|
158
|
+
----------
|
|
159
|
+
img:
|
|
160
|
+
``uint8`` RGB NumPy array.
|
|
161
|
+
ocr_engine:
|
|
162
|
+
A :class:`rapidocr_onnxruntime.RapidOCR` instance.
|
|
163
|
+
|
|
164
|
+
Returns
|
|
165
|
+
-------
|
|
166
|
+
(text, elements, mean_confidence)
|
|
167
|
+
*text* is the full page text; *elements* contains per-box results;
|
|
168
|
+
*mean_confidence* is the mean score across all boxes, or ``None``
|
|
169
|
+
if no boxes were detected.
|
|
170
|
+
"""
|
|
171
|
+
result, _ = ocr_engine(img)
|
|
172
|
+
if not result:
|
|
173
|
+
return "", [], None
|
|
174
|
+
|
|
175
|
+
items: List[WordBox] = []
|
|
176
|
+
elements: List[TextElement] = []
|
|
177
|
+
scores: List[float] = []
|
|
178
|
+
|
|
179
|
+
for box, txt, score in result:
|
|
180
|
+
xs = [p[0] for p in box]
|
|
181
|
+
ys = [p[1] for p in box]
|
|
182
|
+
x0, y0, x1, y1 = min(xs), min(ys), max(xs), max(ys)
|
|
183
|
+
items.append((x0, y0, x1, y1, txt))
|
|
184
|
+
elements.append(
|
|
185
|
+
TextElement(
|
|
186
|
+
text=txt,
|
|
187
|
+
bbox=[x0, y0, x1, y1],
|
|
188
|
+
confidence=float(score),
|
|
189
|
+
)
|
|
190
|
+
)
|
|
191
|
+
scores.append(float(score))
|
|
192
|
+
|
|
193
|
+
text = words_to_lines(items)
|
|
194
|
+
mean_conf = float(np.mean(scores)) if scores else None
|
|
195
|
+
return text, elements, mean_conf
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
# ---------------------------------------------------------------------------
|
|
199
|
+
# Multi-format page iterator
|
|
200
|
+
# ---------------------------------------------------------------------------
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def iter_pages(
|
|
204
|
+
path: Path,
|
|
205
|
+
) -> Iterator[Tuple[int, object, Optional[np.ndarray]]]:
|
|
206
|
+
"""Yield ``(page_no, pdf_page_or_None, image_array_or_None)`` for every page.
|
|
207
|
+
|
|
208
|
+
Handles:
|
|
209
|
+
* Multi-page PDFs (via PyMuPDF)
|
|
210
|
+
* Single or multi-frame image files (JPEG, PNG, TIFF, …)
|
|
211
|
+
* Password-protected PDFs → raises :class:`ValueError`
|
|
212
|
+
|
|
213
|
+
Parameters
|
|
214
|
+
----------
|
|
215
|
+
path:
|
|
216
|
+
Path to the input file.
|
|
217
|
+
|
|
218
|
+
Yields
|
|
219
|
+
------
|
|
220
|
+
(page_no, page, img)
|
|
221
|
+
*page_no* is 1-indexed. Exactly one of *page* or *img* is not ``None``.
|
|
222
|
+
"""
|
|
223
|
+
from PIL import Image, ImageOps, ImageSequence # local import
|
|
224
|
+
|
|
225
|
+
if path.suffix.lower() in IMG_EXTENSIONS:
|
|
226
|
+
im = Image.open(path)
|
|
227
|
+
for i, frame in enumerate(ImageSequence.Iterator(im), start=1):
|
|
228
|
+
frame = ImageOps.exif_transpose(frame.convert("RGB"))
|
|
229
|
+
yield i, None, fit_image(np.array(frame))
|
|
230
|
+
else:
|
|
231
|
+
import pymupdf # local import
|
|
232
|
+
|
|
233
|
+
doc = pymupdf.open(str(path))
|
|
234
|
+
if doc.needs_pass:
|
|
235
|
+
raise ValueError(f"{path.name!r} is password-protected.")
|
|
236
|
+
page: Any
|
|
237
|
+
for i, page in enumerate(doc, start=1): # type: ignore[arg-type]
|
|
238
|
+
yield i, page, None
|
obliq_ocr/py.typed
ADDED
|
File without changes
|
obliq_ocr/schemas.py
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
"""
|
|
2
|
+
schemas.py – Structured output types for the obliq-OCR pipeline.
|
|
3
|
+
|
|
4
|
+
These dataclasses define the public output schema returned by
|
|
5
|
+
:func:`obliq_ocr.parse_document`. All fields are serialisable via
|
|
6
|
+
:func:`dataclasses.asdict`.
|
|
7
|
+
|
|
8
|
+
Output schema
|
|
9
|
+
-------------
|
|
10
|
+
.. code-block:: json
|
|
11
|
+
|
|
12
|
+
{
|
|
13
|
+
"file_name": "invoice.pdf",
|
|
14
|
+
"device": "CPU",
|
|
15
|
+
"pages": [
|
|
16
|
+
{
|
|
17
|
+
"page_number": 1,
|
|
18
|
+
"method": "ocr",
|
|
19
|
+
"reason": "only 3 text chars",
|
|
20
|
+
"confidence": 0.87,
|
|
21
|
+
"processing_seconds": 2.65,
|
|
22
|
+
"elements": [
|
|
23
|
+
{
|
|
24
|
+
"text": "Invoice Number: 12345",
|
|
25
|
+
"bbox": [50.0, 80.0, 300.0, 110.0],
|
|
26
|
+
"confidence": 0.98
|
|
27
|
+
}
|
|
28
|
+
],
|
|
29
|
+
"text": "Invoice Number: 12345"
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
Coordinate system
|
|
35
|
+
-----------------
|
|
36
|
+
All bounding boxes use ``[x0, y0, x1, y1]`` in *points* (1/72 inch) for
|
|
37
|
+
digital pages, and in *pixels* at the configured render DPI for scanned
|
|
38
|
+
pages. ``x0/y0`` is the top-left corner; ``x1/y1`` is the bottom-right.
|
|
39
|
+
Page numbering is **1-indexed** (first page = 1).
|
|
40
|
+
|
|
41
|
+
Confidence scores
|
|
42
|
+
-----------------
|
|
43
|
+
``confidence`` is the mean score across all RapidOCR boxes on the page
|
|
44
|
+
(range 0.0–1.0). It is ``null`` (``None``) for digital pages that were
|
|
45
|
+
extracted directly from the PDF text layer, because PyMuPDF does not
|
|
46
|
+
produce a confidence value.
|
|
47
|
+
"""
|
|
48
|
+
|
|
49
|
+
from __future__ import annotations
|
|
50
|
+
|
|
51
|
+
from dataclasses import asdict, dataclass, field
|
|
52
|
+
from typing import List, Optional
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
@dataclass
|
|
56
|
+
class BoundingBox:
|
|
57
|
+
"""Axis-aligned bounding box ``[x0, y0, x1, y1]``."""
|
|
58
|
+
|
|
59
|
+
x0: float
|
|
60
|
+
y0: float
|
|
61
|
+
x1: float
|
|
62
|
+
y1: float
|
|
63
|
+
|
|
64
|
+
def as_list(self) -> List[float]:
|
|
65
|
+
"""Return ``[x0, y0, x1, y1]`` for JSON serialisation."""
|
|
66
|
+
return [self.x0, self.y0, self.x1, self.y1]
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@dataclass
|
|
70
|
+
class TextElement:
|
|
71
|
+
"""A single text region (word group / OCR box) on a page.
|
|
72
|
+
|
|
73
|
+
Parameters
|
|
74
|
+
----------
|
|
75
|
+
text:
|
|
76
|
+
Extracted text string.
|
|
77
|
+
bbox:
|
|
78
|
+
``[x0, y0, x1, y1]`` bounding box (see module docstring for units).
|
|
79
|
+
confidence:
|
|
80
|
+
Model confidence in range ``[0, 1]``, or ``None`` for text-layer
|
|
81
|
+
elements where PyMuPDF does not supply a score.
|
|
82
|
+
"""
|
|
83
|
+
|
|
84
|
+
text: str
|
|
85
|
+
bbox: List[float] # [x0, y0, x1, y1]
|
|
86
|
+
confidence: Optional[float] = None
|
|
87
|
+
|
|
88
|
+
def to_dict(self):
|
|
89
|
+
return asdict(self)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
@dataclass
|
|
93
|
+
class PageOutput:
|
|
94
|
+
"""Structured result for a single page.
|
|
95
|
+
|
|
96
|
+
Parameters
|
|
97
|
+
----------
|
|
98
|
+
page_number:
|
|
99
|
+
1-indexed page number.
|
|
100
|
+
method:
|
|
101
|
+
How text was extracted: ``"text_layer"``, ``"ocr"``, or ``"blank"``.
|
|
102
|
+
reason:
|
|
103
|
+
Human-readable explanation of why that method was chosen, e.g.
|
|
104
|
+
``"only 3 text chars"`` or ``"garbled text layer (20% junk)"``.
|
|
105
|
+
text:
|
|
106
|
+
Full page text, re-assembled into reading order. Column gaps are
|
|
107
|
+
represented as `` | `` so table rows remain readable.
|
|
108
|
+
elements:
|
|
109
|
+
Individual text regions with bounding boxes and per-element
|
|
110
|
+
confidence scores. Empty list for blank pages.
|
|
111
|
+
confidence:
|
|
112
|
+
Mean OCR confidence for the page (``None`` for text-layer pages).
|
|
113
|
+
processing_seconds:
|
|
114
|
+
Wall-clock time to process this page.
|
|
115
|
+
"""
|
|
116
|
+
|
|
117
|
+
page_number: int
|
|
118
|
+
method: str # "text_layer" | "ocr" | "blank"
|
|
119
|
+
reason: str
|
|
120
|
+
text: str
|
|
121
|
+
elements: List[TextElement] = field(default_factory=list)
|
|
122
|
+
confidence: Optional[float] = None
|
|
123
|
+
processing_seconds: float = 0.0
|
|
124
|
+
|
|
125
|
+
def to_dict(self):
|
|
126
|
+
d = asdict(self)
|
|
127
|
+
return d
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
@dataclass
|
|
131
|
+
class DocumentOutput:
|
|
132
|
+
"""Top-level structured output for a parsed document.
|
|
133
|
+
|
|
134
|
+
Parameters
|
|
135
|
+
----------
|
|
136
|
+
file_name:
|
|
137
|
+
Base name of the source file (no directory path).
|
|
138
|
+
device:
|
|
139
|
+
Compute device used for OCR: ``"CPU"`` or ``"CUDA"``.
|
|
140
|
+
pages:
|
|
141
|
+
Ordered list of :class:`PageOutput` objects, one per page.
|
|
142
|
+
"""
|
|
143
|
+
|
|
144
|
+
file_name: str
|
|
145
|
+
device: str
|
|
146
|
+
pages: List[PageOutput] = field(default_factory=list)
|
|
147
|
+
|
|
148
|
+
def full_text(self) -> str:
|
|
149
|
+
"""Concatenate all pages into a single string with page headers."""
|
|
150
|
+
parts = [f"===== PAGE {p.page_number} [{p.method}] =====\n{p.text}" for p in self.pages]
|
|
151
|
+
return "\n\n".join(parts)
|
|
152
|
+
|
|
153
|
+
def to_dict(self):
|
|
154
|
+
return asdict(self)
|
obliq_ocr/utils.py
ADDED
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
"""
|
|
2
|
+
utils.py – Low-level helper utilities for the obliq-OCR pipeline.
|
|
3
|
+
|
|
4
|
+
Contains:
|
|
5
|
+
- ``words_to_lines`` : groups word-level boxes into visual reading-order lines.
|
|
6
|
+
- ``garbage_ratio`` : measures how much junk is in a PDF text layer.
|
|
7
|
+
- ``image_cover`` : fraction of a PDF page covered by embedded images.
|
|
8
|
+
- ``fit_image`` : downscale an ndarray so its longest side ≤ MAX_SIDE_PX.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from typing import List, Tuple
|
|
14
|
+
|
|
15
|
+
import numpy as np
|
|
16
|
+
|
|
17
|
+
# ── knobs ────────────────────────────────────────────────────────────────────
|
|
18
|
+
COL_GAP_FACTOR: float = 1.0 # gap (in line-heights) that becomes " | "
|
|
19
|
+
MAX_SIDE_PX: int = 3200 # cap rendered page size
|
|
20
|
+
# ─────────────────────────────────────────────────────────────────────────────
|
|
21
|
+
|
|
22
|
+
# Type alias: (x0, y0, x1, y1, text)
|
|
23
|
+
WordBox = Tuple[float, float, float, float, str]
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def words_to_lines(
|
|
27
|
+
items: List[WordBox],
|
|
28
|
+
gap_factor: float = COL_GAP_FACTOR,
|
|
29
|
+
) -> str:
|
|
30
|
+
"""Regroup word-level boxes into visual reading-order lines.
|
|
31
|
+
|
|
32
|
+
Wide horizontal gaps between words on the same line become `` | `` so
|
|
33
|
+
table columns are preserved when the text is fed to a downstream LLM.
|
|
34
|
+
|
|
35
|
+
Parameters
|
|
36
|
+
----------
|
|
37
|
+
items:
|
|
38
|
+
List of ``(x0, y0, x1, y1, text)`` tuples in any order.
|
|
39
|
+
gap_factor:
|
|
40
|
+
Number of line-heights that constitutes a "column gap". Default 1.0.
|
|
41
|
+
|
|
42
|
+
Returns
|
|
43
|
+
-------
|
|
44
|
+
str
|
|
45
|
+
Multi-line string, one visual row per line.
|
|
46
|
+
"""
|
|
47
|
+
items = [it for it in items if it[4].strip()]
|
|
48
|
+
if not items:
|
|
49
|
+
return ""
|
|
50
|
+
|
|
51
|
+
# Sort top-to-bottom, then left-to-right within a row
|
|
52
|
+
items.sort(key=lambda t: ((t[1] + t[3]) / 2, t[0]))
|
|
53
|
+
|
|
54
|
+
lines: List[List[WordBox]] = []
|
|
55
|
+
cur: List[WordBox] = []
|
|
56
|
+
cur_y: float = 0.0
|
|
57
|
+
cur_h: float = 0.0
|
|
58
|
+
|
|
59
|
+
for it in items:
|
|
60
|
+
yc = (it[1] + it[3]) / 2
|
|
61
|
+
h = max(it[3] - it[1], 1.0)
|
|
62
|
+
if cur and abs(yc - cur_y) <= 0.6 * cur_h:
|
|
63
|
+
cur.append(it)
|
|
64
|
+
n = len(cur)
|
|
65
|
+
cur_y = cur_y + (yc - cur_y) / n # running mean
|
|
66
|
+
cur_h = max(cur_h, h) if n < 3 else cur_h
|
|
67
|
+
else:
|
|
68
|
+
if cur:
|
|
69
|
+
lines.append(cur)
|
|
70
|
+
cur, cur_y, cur_h = [it], yc, h
|
|
71
|
+
|
|
72
|
+
if cur:
|
|
73
|
+
lines.append(cur)
|
|
74
|
+
|
|
75
|
+
out: List[str] = []
|
|
76
|
+
for ln in lines:
|
|
77
|
+
ln.sort(key=lambda t: t[0])
|
|
78
|
+
h = float(np.median([max(t[3] - t[1], 1.0) for t in ln]))
|
|
79
|
+
s = ln[0][4]
|
|
80
|
+
for prev, nxt in zip(ln, ln[1:]):
|
|
81
|
+
gap = nxt[0] - prev[2]
|
|
82
|
+
s += (" | " if gap > gap_factor * h else " ") + nxt[4]
|
|
83
|
+
out.append(s.strip())
|
|
84
|
+
|
|
85
|
+
return "\n".join(out)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def garbage_ratio(text: str) -> float:
|
|
89
|
+
"""Return the fraction of non-whitespace characters that are junk.
|
|
90
|
+
|
|
91
|
+
"Junk" means:
|
|
92
|
+
* Unicode replacement character ``\\ufffd``
|
|
93
|
+
* Control characters (``ord < 32``)
|
|
94
|
+
* Private-use Unicode range ``U+E000–U+F8FF``
|
|
95
|
+
* ``(cid:…)`` sequences emitted by some PDF renderers (counted × 3)
|
|
96
|
+
|
|
97
|
+
Parameters
|
|
98
|
+
----------
|
|
99
|
+
text:
|
|
100
|
+
Raw text extracted by PyMuPDF.
|
|
101
|
+
|
|
102
|
+
Returns
|
|
103
|
+
-------
|
|
104
|
+
float
|
|
105
|
+
Value in ``[0.0, 1.0]``; higher means more garbage.
|
|
106
|
+
"""
|
|
107
|
+
chars = [c for c in text if not c.isspace()]
|
|
108
|
+
if not chars:
|
|
109
|
+
return 1.0
|
|
110
|
+
bad = sum(1 for c in chars if c == "\ufffd" or (ord(c) < 32) or 0xE000 <= ord(c) <= 0xF8FF)
|
|
111
|
+
bad += 3 * text.count("(cid:")
|
|
112
|
+
return min(bad / len(chars), 1.0)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def image_cover(page) -> float: # page: pymupdf.Page
|
|
116
|
+
"""Return the fraction of *page* area covered by embedded raster images.
|
|
117
|
+
|
|
118
|
+
Parameters
|
|
119
|
+
----------
|
|
120
|
+
page:
|
|
121
|
+
A :class:`pymupdf.Page` object.
|
|
122
|
+
|
|
123
|
+
Returns
|
|
124
|
+
-------
|
|
125
|
+
float
|
|
126
|
+
Value in ``[0.0, 1.0]``.
|
|
127
|
+
"""
|
|
128
|
+
import pymupdf # local import keeps utils importable without pymupdf
|
|
129
|
+
|
|
130
|
+
area = page.rect.width * page.rect.height
|
|
131
|
+
if area <= 0:
|
|
132
|
+
return 0.0
|
|
133
|
+
try:
|
|
134
|
+
covered = sum(
|
|
135
|
+
pymupdf.Rect(i["bbox"]).intersect(page.rect).get_area() for i in page.get_image_info()
|
|
136
|
+
)
|
|
137
|
+
except Exception:
|
|
138
|
+
return 0.0
|
|
139
|
+
return min(covered / area, 1.0)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def fit_image(img: np.ndarray, max_side: int = MAX_SIDE_PX) -> np.ndarray:
|
|
143
|
+
"""Downscale *img* so its longest side is at most *max_side* pixels.
|
|
144
|
+
|
|
145
|
+
Uses LANCZOS resampling. Returns *img* unchanged if it already fits.
|
|
146
|
+
|
|
147
|
+
Parameters
|
|
148
|
+
----------
|
|
149
|
+
img:
|
|
150
|
+
``uint8`` NumPy array of shape ``(H, W, C)``.
|
|
151
|
+
max_side:
|
|
152
|
+
Maximum pixel dimension (height or width).
|
|
153
|
+
|
|
154
|
+
Returns
|
|
155
|
+
-------
|
|
156
|
+
np.ndarray
|
|
157
|
+
Possibly resized array, same dtype.
|
|
158
|
+
"""
|
|
159
|
+
from PIL import Image # local import
|
|
160
|
+
|
|
161
|
+
h, w = img.shape[:2]
|
|
162
|
+
m = max(h, w)
|
|
163
|
+
if m <= max_side:
|
|
164
|
+
return img
|
|
165
|
+
s = max_side / m
|
|
166
|
+
return np.array(Image.fromarray(img).resize((int(w * s), int(h * s)), Image.Resampling.LANCZOS))
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def is_blank_image(img: np.ndarray, std_threshold: float = 3.0) -> bool:
|
|
170
|
+
"""Return ``True`` if *img* looks like a blank (white/black) page.
|
|
171
|
+
|
|
172
|
+
Parameters
|
|
173
|
+
----------
|
|
174
|
+
img:
|
|
175
|
+
RGB ``uint8`` NumPy array.
|
|
176
|
+
std_threshold:
|
|
177
|
+
Pages whose grayscale standard deviation is below this value are
|
|
178
|
+
considered blank. Default 3.0.
|
|
179
|
+
"""
|
|
180
|
+
g = img.mean(axis=2)
|
|
181
|
+
return bool(g.std() < std_threshold)
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: obliq-ocr
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Page-aware OCR and document-parsing pipeline combining PyMuPDF and RapidOCR.
|
|
5
|
+
Project-URL: Homepage, https://github.com/OBLIQ-in/obliq-OCR
|
|
6
|
+
Project-URL: Documentation, https://obliq-in.github.io/obliq-OCR/
|
|
7
|
+
Project-URL: Repository, https://github.com/OBLIQ-in/obliq-OCR
|
|
8
|
+
Project-URL: Issues, https://github.com/OBLIQ-in/obliq-OCR/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/OBLIQ-in/obliq-OCR/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: Rahul Kate <rahulkate173@gmail.com>, Abhiraj Adhikary <abhirajadhikary06@gmail.com>, Naman Jha <abhirajadhikary06@gmail.com>
|
|
11
|
+
License: MIT
|
|
12
|
+
Keywords: document-parsing,ocr,pdf,pymupdf,rapidocr
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Image Recognition
|
|
22
|
+
Classifier: Topic :: Text Processing
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Requires-Dist: numpy>=1.24.0
|
|
25
|
+
Requires-Dist: onnxruntime<2.0.0,>=1.17.0
|
|
26
|
+
Requires-Dist: pillow>=10.0.0
|
|
27
|
+
Requires-Dist: pymupdf>=1.24.0
|
|
28
|
+
Requires-Dist: rapidocr-onnxruntime>=1.3.18
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: hatch-vcs>=0.4.0; extra == 'dev'
|
|
31
|
+
Requires-Dist: hatchling>=1.25.0; extra == 'dev'
|
|
32
|
+
Requires-Dist: mypy>=1.10.0; extra == 'dev'
|
|
33
|
+
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
|
|
34
|
+
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
|
|
35
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
36
|
+
Requires-Dist: ruff>=0.4.0; extra == 'dev'
|
|
37
|
+
Provides-Extra: gpu
|
|
38
|
+
Requires-Dist: onnxruntime-gpu<2.0.0,>=1.17.0; extra == 'gpu'
|
|
39
|
+
Provides-Extra: test
|
|
40
|
+
Requires-Dist: jiwer>=3.0.0; extra == 'test'
|
|
41
|
+
Requires-Dist: pytest-cov>=4.0; extra == 'test'
|
|
42
|
+
Requires-Dist: pytest>7.0; extra == 'test'
|
|
43
|
+
Description-Content-Type: text/markdown
|
|
44
|
+
|
|
45
|
+
# obliq-ocr
|
|
46
|
+
|
|
47
|
+
[](https://github.com/OBLIQ-in/obliq-OCR/actions/workflows/ci.yml)
|
|
48
|
+
[](https://pypi.org/project/obliq-ocr/)
|
|
49
|
+
[](https://github.com/OBLIQ-in/obliq-OCR/actions/workflows/ci.yml)
|
|
50
|
+
[](https://github.com/OBLIQ-in/obliq-OCR/blob/main/pyproject.toml)
|
|
51
|
+
|
|
52
|
+
Pulls the text out of PDFs and scans, one page at a time. Pages that already
|
|
53
|
+
have digital text are read straight from the PDF in milliseconds; scanned
|
|
54
|
+
pages go through OCR ([RapidOCR](https://github.com/RapidAI/RapidOCR), PP-OCRv4
|
|
55
|
+
on ONNX Runtime). A file that mixes both is handled without any settings.
|
|
56
|
+
|
|
57
|
+
It was built at [OBLIQ](https://github.com/OBLIQ-in) for the documents CA
|
|
58
|
+
firms get from their clients: tax invoices, bills, challans, e-way bills and
|
|
59
|
+
compiled PDFs. It's for Python developers who need that text as plain strings
|
|
60
|
+
or JSON, and its output is meant to be checked by a person before it's used.
|
|
61
|
+
|
|
62
|
+
## Install
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pip install obliq-ocr
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- **Python 3.10, 3.11 or 3.12.** The OCR engine doesn't install on 3.13 yet.
|
|
69
|
+
- **Linux and Windows** are tested. macOS should work but isn't tested.
|
|
70
|
+
- Runs on CPU. For an NVIDIA GPU, see [GPU](#gpu).
|
|
71
|
+
|
|
72
|
+
The first release isn't on PyPI yet. Until it is, install from GitHub:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
pip install "git+https://github.com/OBLIQ-in/obliq-OCR.git"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Quickstart
|
|
79
|
+
|
|
80
|
+
<!-- quickstart: tests/test_readme.py runs this block exactly as written -->
|
|
81
|
+
```python
|
|
82
|
+
from obliq_ocr import parse_document, save_result
|
|
83
|
+
|
|
84
|
+
result = parse_document("invoice.pdf") # a PDF or an image
|
|
85
|
+
|
|
86
|
+
for page in result.pages:
|
|
87
|
+
print(page.page, page.method, page.confidence)
|
|
88
|
+
|
|
89
|
+
print(result.full_text())
|
|
90
|
+
save_result(result, out_dir="outputs") # outputs/invoice.json and outputs/invoice.txt
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`parse_document` prints one progress line per page; pass `verbose=False` to
|
|
94
|
+
turn that off.
|
|
95
|
+
|
|
96
|
+
## Supported files
|
|
97
|
+
|
|
98
|
+
| Type | Extensions | Notes |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| PDF | `.pdf` | Digital, scanned or mixed. Password-protected PDFs raise `ValueError`. |
|
|
101
|
+
| Images | `.jpg` `.jpeg` `.png` `.bmp` `.tif` `.tiff` `.webp` | Each frame of a multi-page TIFF is a page. Phone photos are turned upright using their EXIF data. |
|
|
102
|
+
|
|
103
|
+
## Sample output
|
|
104
|
+
|
|
105
|
+
`save_result` writes this JSON (the same as `result.to_dict()`). This is the
|
|
106
|
+
real output for a two-page test PDF where page 1 is digital and page 2 is a
|
|
107
|
+
scan:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"source": "invoice.pdf",
|
|
112
|
+
"device": "CPU",
|
|
113
|
+
"pages": [
|
|
114
|
+
{
|
|
115
|
+
"page": 1,
|
|
116
|
+
"method": "text_layer",
|
|
117
|
+
"reason": "97 chars, image cover 0%",
|
|
118
|
+
"text": "Mixed document digital page.\nThis page contains native text layer elements.\nIt should be extracted via text layer.",
|
|
119
|
+
"n_chars": 114,
|
|
120
|
+
"confidence": null,
|
|
121
|
+
"seconds": 0.018
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
"page": 2,
|
|
125
|
+
"method": "ocr",
|
|
126
|
+
"reason": "only 0 text chars",
|
|
127
|
+
"text": "Mixed document scanned page.",
|
|
128
|
+
"n_chars": 28,
|
|
129
|
+
"confidence": 1.0,
|
|
130
|
+
"seconds": 0.516
|
|
131
|
+
}
|
|
132
|
+
]
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
`method` is `text_layer`, `ocr` or `blank`. `confidence` is the average OCR
|
|
137
|
+
score from 0 to 1, and `null` for pages that weren't OCR'd. Every field and
|
|
138
|
+
error is explained in the
|
|
139
|
+
[architecture doc](https://github.com/OBLIQ-in/obliq-OCR/blob/main/docs/architecture.md).
|
|
140
|
+
|
|
141
|
+
## Command line
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
obliq-ocr invoice.pdf # writes outputs/invoice.json and .txt
|
|
145
|
+
obliq-ocr scan.pdf --output-dir results --device cpu # choose folder and device
|
|
146
|
+
obliq-ocr scan.pdf --quiet # no per-page progress
|
|
147
|
+
python -m obliq_ocr invoice.pdf # same thing, as a module
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## GPU
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
pip uninstall -y onnxruntime
|
|
154
|
+
pip install "obliq-ocr[gpu]"
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The CPU and GPU builds of ONNX Runtime can't be installed together, which is
|
|
158
|
+
why the first command is needed. obliq-ocr uses CUDA when it's available; set
|
|
159
|
+
`OBLIQ_OCR_DEVICE=cpu` or `cuda`, or pass `force_device="cpu"` or `"cuda"`, to
|
|
160
|
+
choose.
|
|
161
|
+
|
|
162
|
+
## Limitations
|
|
163
|
+
|
|
164
|
+
The [model card](https://github.com/OBLIQ-in/obliq-OCR/blob/main/MODEL_CARD.md)
|
|
165
|
+
has the measurements. In short:
|
|
166
|
+
|
|
167
|
+
- Scanned pages can't produce `₹` or Hindi and other Indian scripts. Digital
|
|
168
|
+
PDFs keep them.
|
|
169
|
+
- Handwriting isn't supported.
|
|
170
|
+
- Low-resolution or skewed scans can change digits and drop whole lines.
|
|
171
|
+
- A high `confidence` doesn't mean the text is right: check key values.
|
|
172
|
+
- The output has no coordinates yet ([#71](https://github.com/OBLIQ-in/obliq-OCR/issues/71)).
|
|
173
|
+
|
|
174
|
+
## Documentation
|
|
175
|
+
|
|
176
|
+
- [Architecture and output schema](https://github.com/OBLIQ-in/obliq-OCR/blob/main/docs/architecture.md): how pages are routed, every output field, errors
|
|
177
|
+
- [Model card](https://github.com/OBLIQ-in/obliq-OCR/blob/main/MODEL_CARD.md): models, versions, measured accuracy, limitations
|
|
178
|
+
- [Benchmark](https://github.com/OBLIQ-in/obliq-OCR/blob/main/BENCHMARK.md): speed and memory against other OCR engines
|
|
179
|
+
- [Changelog](https://github.com/OBLIQ-in/obliq-OCR/blob/main/CHANGELOG.md)
|
|
180
|
+
- [Release guide](https://github.com/OBLIQ-in/obliq-OCR/blob/main/docs/RELEASE_GUIDE.md), for maintainers
|
|
181
|
+
- [Security policy](https://github.com/OBLIQ-in/obliq-OCR/blob/main/SECURITY.md): how to report a vulnerability privately
|
|
182
|
+
|
|
183
|
+
## Contributing
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
git clone https://github.com/OBLIQ-in/obliq-OCR.git
|
|
187
|
+
cd obliq-OCR
|
|
188
|
+
python -m venv .venv # Python 3.10 to 3.12
|
|
189
|
+
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
190
|
+
pip install -e ".[dev,test]"
|
|
191
|
+
pre-commit install
|
|
192
|
+
python tests/scripts/generate_fixtures.py # synthetic test PDFs
|
|
193
|
+
pytest
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
- Branch off `main` and open a PR. PR titles follow
|
|
197
|
+
[Conventional Commits](https://www.conventionalcommits.org) (`docs: …`,
|
|
198
|
+
`fix: …`, `feat: …`). If the PR has a single commit, its message must follow
|
|
199
|
+
the same format.
|
|
200
|
+
- CI runs ruff, mypy, the tests on Python 3.10 to 3.12, an accuracy gate and a
|
|
201
|
+
link check.
|
|
202
|
+
- Never commit real client documents or anything with personal data. Test
|
|
203
|
+
files must be synthetic or fully anonymised.
|
|
204
|
+
|
|
205
|
+
Questions and bugs go to [GitHub issues](https://github.com/OBLIQ-in/obliq-OCR/issues).
|
|
206
|
+
|
|
207
|
+
## License
|
|
208
|
+
|
|
209
|
+
MIT
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
obliq_ocr/__init__.py,sha256=A18ffa4hEMQy74QYYq-ovleC_KTiAzBbQlth4nS8CZ8,1137
|
|
2
|
+
obliq_ocr/__main__.py,sha256=r9NQQRC03bvK_es2SKnx-F_z9a6eQ8eD2oJ1_1f2izQ,117
|
|
3
|
+
obliq_ocr/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
|
|
4
|
+
obliq_ocr/cli.py,sha256=7pgTnXGLl_esEq1jB3V-oXqngLecA_H4tJugBJNHxrY,2408
|
|
5
|
+
obliq_ocr/core.py,sha256=ATApVth9Y5Ck319bQWuTXd0db8jouPyIMNdw67di1do,7244
|
|
6
|
+
obliq_ocr/engine.py,sha256=-z_zGdFfYwSmqkfrm8L2pyiCHVuBTRnoIvJNclU8SG8,4239
|
|
7
|
+
obliq_ocr/parser.py,sha256=606Y7abl0kVczGgfBsEjoSE5MVitqvS0Owp2890E8XE,7933
|
|
8
|
+
obliq_ocr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
obliq_ocr/schemas.py,sha256=nrOfcMTI7juEC_kUv9gWUZKuw3zZYCWrDWMBxtU0Ig0,4365
|
|
10
|
+
obliq_ocr/utils.py,sha256=OquukfW6Cldv7XRwW6VPCdYN909jr-eQtR0Eygkjufw,5497
|
|
11
|
+
obliq_ocr-0.1.0.dist-info/METADATA,sha256=cqHmjaPRe2k8WdnPjzPJD1XpakjUoludwqCc2l9kYJE,8218
|
|
12
|
+
obliq_ocr-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
13
|
+
obliq_ocr-0.1.0.dist-info/entry_points.txt,sha256=Uv94YfNPS3Vg04syqS38e9t6eWN8OVtagmgdOma4rzs,49
|
|
14
|
+
obliq_ocr-0.1.0.dist-info/RECORD,,
|