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 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
@@ -0,0 +1,6 @@
1
+ """Allow `python -m obliq_ocr` invocation."""
2
+
3
+ from obliq_ocr.cli import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
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
+ [![CI](https://github.com/OBLIQ-in/obliq-OCR/actions/workflows/ci.yml/badge.svg)](https://github.com/OBLIQ-in/obliq-OCR/actions/workflows/ci.yml)
48
+ [![PyPI](https://img.shields.io/pypi/v/obliq-ocr)](https://pypi.org/project/obliq-ocr/)
49
+ [![Python 3.10 | 3.11 | 3.12](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://github.com/OBLIQ-in/obliq-OCR/actions/workflows/ci.yml)
50
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](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,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ obliq-ocr = obliq_ocr.cli:main