wormocr 1.0.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.
Files changed (48) hide show
  1. wormocr/__init__.py +18 -0
  2. wormocr/__main__.py +4 -0
  3. wormocr/api.py +229 -0
  4. wormocr/benchmark/__init__.py +5 -0
  5. wormocr/benchmark/report.py +403 -0
  6. wormocr/checkpoints.py +55 -0
  7. wormocr/cli.py +308 -0
  8. wormocr/config.py +220 -0
  9. wormocr/data/__init__.py +5 -0
  10. wormocr/data/dataset.py +110 -0
  11. wormocr/data/fonts.py +173 -0
  12. wormocr/data/handwriting.py +304 -0
  13. wormocr/data/lexicon.py +105 -0
  14. wormocr/data/lexicon_medical.py +48 -0
  15. wormocr/data/mixed.py +211 -0
  16. wormocr/data/synthetic.py +445 -0
  17. wormocr/detection/__init__.py +5 -0
  18. wormocr/detection/lines.py +382 -0
  19. wormocr/evaluation/__init__.py +5 -0
  20. wormocr/evaluation/errors.py +145 -0
  21. wormocr/evaluation/metrics.py +105 -0
  22. wormocr/evaluation/robustness.py +43 -0
  23. wormocr/exceptions.py +25 -0
  24. wormocr/export/__init__.py +5 -0
  25. wormocr/export/onnx_export.py +75 -0
  26. wormocr/hub.py +157 -0
  27. wormocr/inference/__init__.py +5 -0
  28. wormocr/inference/decode.py +113 -0
  29. wormocr/inference/engine.py +122 -0
  30. wormocr/models/__init__.py +5 -0
  31. wormocr/models/crnn.py +236 -0
  32. wormocr/preprocessing.py +135 -0
  33. wormocr/py.typed +0 -0
  34. wormocr/runtime.py +56 -0
  35. wormocr/training/__init__.py +5 -0
  36. wormocr/training/loop.py +645 -0
  37. wormocr/vocabulary.py +69 -0
  38. wormocr/web/__init__.py +5 -0
  39. wormocr/web/server.py +505 -0
  40. wormocr/web/static/app.js +514 -0
  41. wormocr/web/static/index.html +141 -0
  42. wormocr/web/static/style.css +379 -0
  43. wormocr-1.0.0.dist-info/METADATA +377 -0
  44. wormocr-1.0.0.dist-info/RECORD +48 -0
  45. wormocr-1.0.0.dist-info/WHEEL +5 -0
  46. wormocr-1.0.0.dist-info/entry_points.txt +2 -0
  47. wormocr-1.0.0.dist-info/licenses/LICENSE +21 -0
  48. wormocr-1.0.0.dist-info/top_level.txt +1 -0
wormocr/vocabulary.py ADDED
@@ -0,0 +1,69 @@
1
+ """Character vocabulary for CTC recognition.
2
+
3
+ Index 0 is the CTC blank. Every other index is one character from the charset.
4
+ The charset is stored in checkpoints so a later code change cannot silently
5
+ remap an older model.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+
11
+ def default_charset() -> str:
12
+ """Printable ASCII, including space. This is the English v1 vocabulary."""
13
+ return " " + "".join(chr(code) for code in range(33, 127))
14
+
15
+
16
+ def ctc_time_needed(text: str) -> int:
17
+ """Minimum frames so CTC can emit the text, including a blank between repeats."""
18
+ if not text:
19
+ return 0
20
+ gaps = sum(left == right for left, right in zip(text, text[1:]))
21
+ return len(text) + gaps
22
+
23
+
24
+ class Vocabulary:
25
+ def __init__(self, charset: str | None = None) -> None:
26
+ text = default_charset() if charset is None else charset
27
+ if not text:
28
+ raise ValueError("charset is empty")
29
+ if len(set(text)) != len(text):
30
+ raise ValueError("charset contains duplicate characters")
31
+ if any(ord(char) < 32 for char in text):
32
+ raise ValueError("charset cannot contain control characters")
33
+ self.charset = text
34
+ self.blank = 0
35
+ self.itos: list[str] = ["", *text]
36
+ self.stoi = {char: index + 1 for index, char in enumerate(text)}
37
+
38
+ @property
39
+ def size(self) -> int:
40
+ return len(self.itos)
41
+
42
+ def encode(self, text: str) -> list[int]:
43
+ try:
44
+ return [self.stoi[char] for char in text]
45
+ except KeyError as exc:
46
+ character = exc.args[0]
47
+ raise ValueError(
48
+ f"character {character!r} is outside the wormOCR charset"
49
+ ) from exc
50
+
51
+ def decode(self, indices: list[int]) -> str:
52
+ parts: list[str] = []
53
+ for index in indices:
54
+ if index == self.blank:
55
+ continue
56
+ if index < 0 or index >= len(self.itos):
57
+ raise ValueError(f"class index {index} is outside the charset")
58
+ parts.append(self.itos[index])
59
+ return "".join(parts)
60
+
61
+ def to_dict(self) -> dict[str, str]:
62
+ return {"charset": self.charset}
63
+
64
+ @classmethod
65
+ def from_dict(cls, payload: dict) -> "Vocabulary":
66
+ charset = payload.get("charset")
67
+ if not isinstance(charset, str) or not charset:
68
+ raise ValueError("checkpoint vocabulary is missing a charset")
69
+ return cls(charset)
@@ -0,0 +1,5 @@
1
+ """Local web UI for trying wormOCR in a browser."""
2
+
3
+ from wormocr.web.server import describe_engine, make_server, serve
4
+
5
+ __all__ = ["describe_engine", "make_server", "serve"]
wormocr/web/server.py ADDED
@@ -0,0 +1,505 @@
1
+ """A small standard-library HTTP server for the browser UI.
2
+
3
+ The server binds to localhost by default. Uploaded files are processed in
4
+ memory or in a temporary file that is deleted after the request.
5
+
6
+ `/api/ocr/stream` runs the same pipeline as `OCR.predict`, one step at a time,
7
+ and writes one JSON event per line (NDJSON) as each step finishes.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import base64
13
+ import io
14
+ import json
15
+ import mimetypes
16
+ import os
17
+ import tempfile
18
+ import threading
19
+ import time
20
+ from collections.abc import Iterator
21
+ from http import HTTPStatus
22
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
23
+ from pathlib import Path
24
+ from urllib.parse import parse_qs, urlparse
25
+
26
+ import torch
27
+ from PIL import Image, ImageOps, UnidentifiedImageError
28
+
29
+ from wormocr.detection.lines import segment_page
30
+ from wormocr.exceptions import RecognitionError, WormOCRError
31
+ from wormocr.preprocessing import looks_like_line, prepare_line
32
+
33
+ STATIC_DIR = Path(__file__).resolve().parent / "static"
34
+ MAX_UPLOAD_BYTES = 25 * 1024 * 1024
35
+ MAX_PDF_PAGES = 20
36
+ MAX_LINES_PER_PAGE = 400
37
+ PDF_SCALE = 2.0
38
+ PREVIEW_MAX_SIDE = 1600
39
+ IMAGE_SUFFIXES = {".png", ".jpg", ".jpeg", ".bmp", ".tif", ".tiff", ".webp", ".gif"}
40
+
41
+
42
+ def _preview(image: Image.Image) -> str:
43
+ preview = image.convert("RGB")
44
+ preview.thumbnail((PREVIEW_MAX_SIDE, PREVIEW_MAX_SIDE), Image.Resampling.BILINEAR, reducing_gap=2.0)
45
+ buffer = io.BytesIO()
46
+ preview.save(buffer, format="JPEG", quality=82)
47
+ return "data:image/jpeg;base64," + base64.b64encode(buffer.getvalue()).decode("ascii")
48
+
49
+
50
+ def _ms(started: float) -> float:
51
+ return round((time.perf_counter() - started) * 1000.0, 1)
52
+
53
+
54
+ def _log(stage: str, message: str, **extra) -> dict:
55
+ return {"type": "log", "stage": stage, "message": message, **extra}
56
+
57
+
58
+ class OCRService:
59
+ """Holds one loaded line engine and serializes calls to it."""
60
+
61
+ def __init__(self, engine, model_info: dict) -> None:
62
+ self.engine = engine
63
+ self.model_info = model_info
64
+ self._lock = threading.Lock()
65
+
66
+ def stream(self, data: bytes, filename: str, mode: str) -> Iterator[dict]:
67
+ started = time.perf_counter()
68
+ timings = {"decode": 0.0, "layout": 0.0, "recognize": 0.0}
69
+ info = self.model_info
70
+ yield {"type": "start", "filename": filename, "bytes": len(data), "mode": mode, "model": info}
71
+ yield _log("upload", f"Received {filename} ({len(data) / 1024:.0f} KB)")
72
+ yield _log(
73
+ "model",
74
+ f"{info['name']} ready: {info['parameters']:,} parameters, "
75
+ f"{info.get('architecture', 'CRNN + CTC')}, on {info['device']}",
76
+ )
77
+
78
+ suffix = Path(filename).suffix.lower()
79
+ is_pdf = suffix == ".pdf" or data[:5] == b"%PDF-"
80
+ if not is_pdf and suffix and suffix not in IMAGE_SUFFIXES:
81
+ raise WormOCRError(f"unsupported file type {suffix!r}. Upload a PDF or an image.")
82
+
83
+ pages_text: list[str] = []
84
+ confidences: list[float] = []
85
+ warnings: list[str] = []
86
+ line_total = 0
87
+ with self._lock:
88
+ step = time.perf_counter()
89
+ if is_pdf:
90
+ pages = self._pdf_pages(data)
91
+ yield _log(
92
+ "decode",
93
+ f"Rendered {len(pages)} PDF page(s) at {PDF_SCALE:g}x scale with pdfium",
94
+ ms=_ms(step),
95
+ )
96
+ else:
97
+ pages = None
98
+ page_count = len(pages) if pages is not None else 1
99
+ timings["decode"] += _ms(step)
100
+ yield {"type": "document", "kind": "pdf" if is_pdf else "image", "pages": page_count}
101
+
102
+ for index in range(page_count):
103
+ step = time.perf_counter()
104
+ if pages is None:
105
+ image = self._image(data)
106
+ yield _log("decode", f"Decoded image: {image.width}x{image.height} px", ms=_ms(step))
107
+ else:
108
+ image = pages[index]
109
+ yield _log("decode", f"Page {index + 1}/{page_count}: {image.width}x{image.height} px", page=index)
110
+ timings["decode"] += _ms(step)
111
+ yield {
112
+ "type": "page",
113
+ "page": index,
114
+ "width": image.width,
115
+ "height": image.height,
116
+ "preview": _preview(image),
117
+ }
118
+
119
+ page_lines: list[dict] = []
120
+ for event in self._recognize_page(image, index, mode, timings, warnings, page_lines):
121
+ yield event
122
+ line_total += len(page_lines)
123
+ confidences.extend(line["confidence"] for line in page_lines)
124
+ page_text = "\n".join(line["text"] for line in page_lines)
125
+ pages_text.append(page_text)
126
+ yield {"type": "page_done", "page": index, "text": page_text}
127
+
128
+ mean = sum(confidences) / len(confidences) if confidences else None
129
+ elapsed = _ms(started)
130
+ summary = f"Done in {elapsed / 1000:.2f} s: {line_total} line(s)"
131
+ if mean is not None:
132
+ summary += f", mean confidence {mean * 100:.1f}%"
133
+ yield _log("done", summary)
134
+ yield {
135
+ "type": "done",
136
+ "text": "\n\n".join(pages_text),
137
+ "line_count": line_total,
138
+ "mean_confidence": mean,
139
+ "elapsed_ms": elapsed,
140
+ "timings": timings,
141
+ "warnings": warnings,
142
+ }
143
+
144
+ def _recognize_page(
145
+ self,
146
+ image: Image.Image,
147
+ page: int,
148
+ mode: str,
149
+ timings: dict,
150
+ warnings: list[str],
151
+ page_lines: list[dict],
152
+ ) -> Iterator[dict]:
153
+ engine = self.engine
154
+ step = time.perf_counter()
155
+ single = mode == "line" or (mode == "auto" and looks_like_line(image))
156
+ if single:
157
+ reason = "forced by mode" if mode == "line" else f"image is only {image.height} px tall"
158
+ yield _log("layout", f"Single-line mode ({reason}); skipping line detection", page=page)
159
+ boxes = [(0, 0, image.width, image.height)]
160
+ crops = [image]
161
+ layout_name, angle = "line", 0.0
162
+ else:
163
+ if mode == "auto":
164
+ yield _log("layout", "Auto mode chose page layout: the image is taller than one text line", page=page)
165
+ layout = segment_page(image)
166
+ angle = layout.angle
167
+ layout_name = layout.layout
168
+ yield _log(
169
+ "layout",
170
+ f"Deskew: rotated {angle:+.1f} degrees" if angle else "Deskew: page is straight, no rotation needed",
171
+ page=page,
172
+ )
173
+ boxes = [box.as_xywh() for box in layout.boxes]
174
+ crops = list(layout.crops)
175
+ if not crops:
176
+ message = "No text lines detected; reading the whole image as one line"
177
+ warnings.append(message)
178
+ yield _log("layout", message, page=page, level="warn")
179
+ boxes, crops, layout_name = [(0, 0, image.width, image.height)], [image], "fallback-line"
180
+ elif len(crops) > MAX_LINES_PER_PAGE:
181
+ message = f"More than {MAX_LINES_PER_PAGE} regions found; keeping the first {MAX_LINES_PER_PAGE}"
182
+ warnings.append(message)
183
+ yield _log("layout", message, page=page, level="warn")
184
+ boxes, crops = boxes[:MAX_LINES_PER_PAGE], crops[:MAX_LINES_PER_PAGE]
185
+ yield _log(
186
+ "layout",
187
+ f"Projection profile found {len(crops)} text line(s), {layout_name} reading order",
188
+ page=page,
189
+ ms=_ms(step),
190
+ )
191
+ timings["layout"] += _ms(step)
192
+ yield {
193
+ "type": "layout",
194
+ "page": page,
195
+ "layout": layout_name,
196
+ "angle": angle,
197
+ "boxes": [{"x": b[0], "y": b[1], "width": b[2], "height": b[3]} for b in boxes],
198
+ }
199
+
200
+ batch_size = max(1, int(getattr(engine, "batch_size", 8)))
201
+ batches = (len(crops) + batch_size - 1) // batch_size
202
+ for batch_index, start in enumerate(range(0, len(crops), batch_size)):
203
+ chunk = crops[start : start + batch_size]
204
+ frames = [self._frames(crop) for crop in chunk]
205
+ step = time.perf_counter()
206
+ recognized = engine.recognize(chunk)
207
+ spent = _ms(step)
208
+ timings["recognize"] += spent
209
+ yield _log(
210
+ "recognize",
211
+ f"Batch {batch_index + 1}/{batches}: {len(chunk)} line(s), CNN + BiGRU + greedy CTC, "
212
+ f"{min(frames)}-{max(frames)} time steps",
213
+ page=page,
214
+ ms=spent,
215
+ )
216
+ for offset, item in enumerate(recognized):
217
+ order = start + offset
218
+ x, y, width, height = boxes[order]
219
+ line = {
220
+ "page": page,
221
+ "order": order,
222
+ "text": str(item["text"]),
223
+ "confidence": float(item["confidence"]),
224
+ "bbox": {"x": x, "y": y, "width": width, "height": height},
225
+ "frames": frames[offset],
226
+ }
227
+ page_lines.append(line)
228
+ yield {"type": "line", **line}
229
+
230
+ def _frames(self, crop: Image.Image) -> int:
231
+ engine = self.engine
232
+ tensor, _ = prepare_line(crop, height=engine.image_height, align=2, max_width=engine.max_width)
233
+ width = torch.tensor([int(tensor.shape[-1])], dtype=torch.long)
234
+ return int(engine.model.output_lengths(width)[0])
235
+
236
+ def run(self, data: bytes, filename: str, mode: str) -> dict:
237
+ """Run the stream to completion and return one combined result."""
238
+ pages: dict[int, dict] = {}
239
+ kind = "image"
240
+ final: dict = {}
241
+ for event in self.stream(data, filename, mode):
242
+ kind_of = event["type"]
243
+ if kind_of == "document":
244
+ kind = event["kind"]
245
+ elif kind_of == "page":
246
+ pages[event["page"]] = {
247
+ "preview": event["preview"],
248
+ "image_width": event["width"],
249
+ "image_height": event["height"],
250
+ "lines": [],
251
+ "text": "",
252
+ }
253
+ elif kind_of == "layout":
254
+ pages[event["page"]].update(layout=event["layout"], deskew_degrees=event["angle"])
255
+ elif kind_of == "line":
256
+ pages[event["page"]]["lines"].append({k: v for k, v in event.items() if k != "type"})
257
+ elif kind_of == "page_done":
258
+ pages[event["page"]]["text"] = event["text"]
259
+ elif kind_of == "done":
260
+ final = event
261
+ return {
262
+ "filename": filename,
263
+ "kind": kind,
264
+ "mode": mode,
265
+ "text": final.get("text", ""),
266
+ "pages": [pages[index] for index in sorted(pages)],
267
+ "line_count": final.get("line_count", 0),
268
+ "mean_confidence": final.get("mean_confidence"),
269
+ "elapsed_ms": final.get("elapsed_ms"),
270
+ "timings": final.get("timings", {}),
271
+ "warnings": final.get("warnings", []),
272
+ "model": self.model_info,
273
+ }
274
+
275
+ @staticmethod
276
+ def _image(data: bytes) -> Image.Image:
277
+ try:
278
+ image = Image.open(io.BytesIO(data))
279
+ image.load()
280
+ except (UnidentifiedImageError, OSError) as exc:
281
+ raise WormOCRError("the upload is not a readable image") from exc
282
+ return ImageOps.exif_transpose(image).convert("RGB")
283
+
284
+ @staticmethod
285
+ def _pdf_pages(data: bytes) -> list[Image.Image]:
286
+ try:
287
+ import pypdfium2 as pdfium
288
+ except ImportError as exc:
289
+ raise RecognitionError(
290
+ "Reading PDFs requires the optional package pypdfium2. Install it with: pip install pypdfium2"
291
+ ) from exc
292
+ handle = tempfile.NamedTemporaryFile(suffix=".pdf", delete=False)
293
+ path = Path(handle.name)
294
+ try:
295
+ with handle:
296
+ handle.write(data)
297
+ try:
298
+ document = pdfium.PdfDocument(str(path))
299
+ except Exception as exc: # noqa: BLE001
300
+ raise WormOCRError("the upload is not a readable PDF") from exc
301
+ try:
302
+ count = len(document)
303
+ if count == 0:
304
+ raise WormOCRError("the PDF has no pages")
305
+ if count > MAX_PDF_PAGES:
306
+ raise WormOCRError(f"the PDF has {count} pages; the web UI accepts up to {MAX_PDF_PAGES}")
307
+ images = [document[index].render(scale=PDF_SCALE).to_pil().convert("RGB") for index in range(count)]
308
+ finally:
309
+ document.close()
310
+ finally:
311
+ path.unlink(missing_ok=True)
312
+ return images
313
+
314
+
315
+ def _handler(service: OCRService) -> type[BaseHTTPRequestHandler]:
316
+ class Handler(BaseHTTPRequestHandler):
317
+ server_version = "wormOCR"
318
+
319
+ def log_message(self, format: str, *args) -> None: # noqa: A002
320
+ pass
321
+
322
+ def _send(self, status: int, body: bytes, content_type: str) -> None:
323
+ self.send_response(status)
324
+ self.send_header("Content-Type", content_type)
325
+ self.send_header("Content-Length", str(len(body)))
326
+ self.send_header("Cache-Control", "no-store")
327
+ self.send_header("X-Content-Type-Options", "nosniff")
328
+ self.end_headers()
329
+ self.wfile.write(body)
330
+
331
+ def _json(self, status: int, payload: dict) -> None:
332
+ self._send(status, json.dumps(payload).encode("utf-8"), "application/json")
333
+
334
+ def do_GET(self) -> None: # noqa: N802
335
+ path = urlparse(self.path).path
336
+ if path == "/api/health":
337
+ self._json(HTTPStatus.OK, {"status": "ok", "model": service.model_info})
338
+ return
339
+ name = "index.html" if path in {"/", "/index.html"} else path.removeprefix("/static/")
340
+ target = (STATIC_DIR / name).resolve()
341
+ if STATIC_DIR not in target.parents or not target.is_file():
342
+ self._json(HTTPStatus.NOT_FOUND, {"error": "not found"})
343
+ return
344
+ content_type = mimetypes.guess_type(target.name)[0] or "application/octet-stream"
345
+ if content_type.startswith("text/") or content_type.endswith("javascript"):
346
+ content_type += "; charset=utf-8"
347
+ self._send(HTTPStatus.OK, target.read_bytes(), content_type)
348
+
349
+ def _read_upload(self) -> tuple[bytes, str, str] | None:
350
+ query = parse_qs(urlparse(self.path).query)
351
+ mode = query.get("mode", ["auto"])[0]
352
+ filename = query.get("filename", ["upload"])[0]
353
+ if mode not in {"auto", "line", "page"}:
354
+ self._json(HTTPStatus.BAD_REQUEST, {"error": "mode must be auto, line, or page"})
355
+ return None
356
+ length = int(self.headers.get("Content-Length") or 0)
357
+ if length <= 0:
358
+ self._json(HTTPStatus.BAD_REQUEST, {"error": "empty upload"})
359
+ return None
360
+ if length > MAX_UPLOAD_BYTES:
361
+ self._json(HTTPStatus.REQUEST_ENTITY_TOO_LARGE, {"error": "files up to 25 MB are accepted"})
362
+ return None
363
+ return self.rfile.read(length), filename, mode
364
+
365
+ def do_POST(self) -> None: # noqa: N802
366
+ path = urlparse(self.path).path
367
+ if path == "/api/ocr":
368
+ upload = self._read_upload()
369
+ if upload is None:
370
+ return
371
+ try:
372
+ payload = service.run(*upload)
373
+ except WormOCRError as exc:
374
+ self._json(HTTPStatus.UNPROCESSABLE_ENTITY, {"error": str(exc)})
375
+ return
376
+ except Exception as exc: # noqa: BLE001
377
+ self._json(HTTPStatus.INTERNAL_SERVER_ERROR, {"error": f"recognition failed: {exc}"})
378
+ return
379
+ self._json(HTTPStatus.OK, payload)
380
+ return
381
+ if path == "/api/ocr/stream":
382
+ upload = self._read_upload()
383
+ if upload is None:
384
+ return
385
+ self._stream(*upload)
386
+ return
387
+ self._json(HTTPStatus.NOT_FOUND, {"error": "not found"})
388
+
389
+ def _stream(self, data: bytes, filename: str, mode: str) -> None:
390
+ self.send_response(HTTPStatus.OK)
391
+ self.send_header("Content-Type", "application/x-ndjson; charset=utf-8")
392
+ self.send_header("Cache-Control", "no-store")
393
+ self.send_header("X-Content-Type-Options", "nosniff")
394
+ self.send_header("Connection", "close")
395
+ self.end_headers()
396
+ self.close_connection = True
397
+ clock = time.perf_counter()
398
+
399
+ def emit(event: dict) -> None:
400
+ event.setdefault("t", round((time.perf_counter() - clock) * 1000.0, 1))
401
+ self.wfile.write((json.dumps(event) + "\n").encode("utf-8"))
402
+ self.wfile.flush()
403
+
404
+ try:
405
+ for event in service.stream(data, filename, mode):
406
+ emit(event)
407
+ except (BrokenPipeError, ConnectionResetError):
408
+ return
409
+ except WormOCRError as exc:
410
+ emit({"type": "error", "message": str(exc)})
411
+ except Exception as exc: # noqa: BLE001
412
+ emit({"type": "error", "message": f"recognition failed: {exc}"})
413
+
414
+ return Handler
415
+
416
+
417
+ def make_server(engine, model_info: dict, host: str = "127.0.0.1", port: int = 8000) -> ThreadingHTTPServer:
418
+ return ThreadingHTTPServer((host, port), _handler(OCRService(engine, model_info)))
419
+
420
+
421
+ def describe_engine(engine, name: str, device: str) -> dict:
422
+ from wormocr.models.crnn import count_parameters
423
+
424
+ model_cfg = engine.config.get("model", {})
425
+ hidden = model_cfg.get("rnn_hidden")
426
+ layers = model_cfg.get("rnn_layers")
427
+ architecture = "CNN encoder, "
428
+ architecture += f"{layers}-layer BiGRU ({hidden} hidden), " if hidden and layers else "BiGRU, "
429
+ architecture += "CTC head"
430
+ return {
431
+ "name": name,
432
+ "parameters": count_parameters(engine.model),
433
+ "maturity": engine.maturity,
434
+ "device": device,
435
+ "architecture": architecture,
436
+ "charset_size": engine.vocabulary.size - 1,
437
+ "image_height": engine.image_height,
438
+ }
439
+
440
+
441
+ def default_threads() -> int:
442
+ """Half the logical CPUs, capped at 16.
443
+
444
+ PyTorch defaults to every logical CPU, which oversubscribes the GRU on
445
+ hybrid and hyper-threaded CPUs and makes recognition slower, not faster.
446
+ """
447
+ return max(1, min(16, (os.cpu_count() or 2) // 2))
448
+
449
+
450
+ def disable_power_throttling() -> bool:
451
+ """Opt the process out of Windows EcoQoS execution-speed throttling.
452
+
453
+ Windows moves windowless background processes such as this server onto
454
+ efficiency cores after a few seconds, which makes OCR 2-3x slower.
455
+ """
456
+ if os.name != "nt":
457
+ return False
458
+ import ctypes
459
+ from ctypes import wintypes
460
+
461
+ class PowerThrottlingState(ctypes.Structure):
462
+ _fields_ = [("Version", wintypes.ULONG), ("ControlMask", wintypes.ULONG), ("StateMask", wintypes.ULONG)]
463
+
464
+ process_power_throttling = 4
465
+ execution_speed = 0x1
466
+ state = PowerThrottlingState(1, execution_speed, 0)
467
+ try:
468
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
469
+ kernel32.GetCurrentProcess.restype = wintypes.HANDLE
470
+ kernel32.SetProcessInformation.argtypes = [wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD]
471
+ kernel32.SetProcessInformation.restype = wintypes.BOOL
472
+ return bool(
473
+ kernel32.SetProcessInformation(
474
+ kernel32.GetCurrentProcess(), process_power_throttling, ctypes.byref(state), ctypes.sizeof(state)
475
+ )
476
+ )
477
+ except (AttributeError, OSError):
478
+ return False
479
+
480
+
481
+ def serve(
482
+ model: str = "wormocr-2M",
483
+ checkpoint: str | None = None,
484
+ device: str | None = "cpu",
485
+ host: str = "127.0.0.1",
486
+ port: int = 8000,
487
+ threads: int | None = None,
488
+ ) -> None:
489
+ from wormocr.api import OCR
490
+
491
+ disable_power_throttling()
492
+ torch.set_num_threads(int(threads) if threads else default_threads())
493
+ engine = OCR(model=model, checkpoint=checkpoint, device=device).engine
494
+ engine.batch_size = 16
495
+ info = describe_engine(engine, model if model.lower().startswith("wormocr") else f"wormOCR {model}", str(engine.device))
496
+ info["threads"] = torch.get_num_threads()
497
+ server = make_server(engine, info, host, port)
498
+ print(f"{info['name']} ({info['parameters'] / 1e6:.2f}M parameters) ready at http://{host}:{port}", flush=True)
499
+ print("Press Ctrl+C to stop.", flush=True)
500
+ try:
501
+ server.serve_forever()
502
+ except KeyboardInterrupt:
503
+ pass
504
+ finally:
505
+ server.server_close()