PyPI - scanlayer - Versions diffs - 1.0.2__tar.gz → 1.1.0__tar.gz - Mend

scanlayer 1.0.2tar.gz → 1.1.0tar.gz

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 (44) hide show

{scanlayer-1.0.2/scanlayer.egg-info → scanlayer-1.1.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanlayer
-Version: 1.0.2
+Version: 1.1.0
 Summary: Image (scan/photo) to searchable PDF, or raw OCR export, via Tesseract.
 Author: Hyacinthe-primus
 Author-email: Hyacinthe-primus <hyacintheatho91@gmail.com>
@@ -19,27 +19,35 @@ Requires-Dist: numpy>=1.24.0
 Requires-Dist: pdf2image>=1.17.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1; extra == "test"
 Provides-Extra: yaml
 Requires-Dist: PyYAML>=6.0; extra == "yaml"
 Dynamic: license-file
 <div align="center">
-<img src="scanlayer.png" alt="scanlayer" width="110"/>
+<img src="https://raw.githubusercontent.com/Hyacinthe-primus/scanlayer/main/scanlayer.png" alt="scanlayer" width="110"/>
 <h1>scanlayer</h1>
-<p><em>Scanned image or photographed document &rarr; searchable PDF, or raw OCR text/JSON/TSV/hOCR.</em></p>
+<p><em> Turn scanned image or photographed document into searchable PDF, or raw OCR text/JSON/TSV/hOCR.</em></p>
 </div>
 **Turn a scanned image or photographed document into a searchable PDF**, or
 export the raw OCR result as plain text, JSON, TSV, or hOCR. Use it as a
 command-line tool or as a Python library; both are the same engine underneath.
-[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](#)
+[![PyPI version](https://badge.fury.io/py/scanlayer.svg)](https://badge.fury.io/py/scanlayer)
+[![codecov](https://codecov.io/gh/Hyacinthe-primus/scanlayer/branch/main/graph/badge.svg)](https://codecov.io/gh/Hyacinthe-primus/scanlayer)
+[![Python](https://img.shields.io/badge/python-3.9%2B-3776AB)](#)
 ![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
 [![](https://img.shields.io/badge/-documentation-green)](https://Hyacinthe-primus.github.io/scanlayer/)
+[![GitHub last commit](https://img.shields.io/github/last-commit/Hyacinthe-primus/scanlayer)](https://github.com/Hyacinthe-primus/scanlayer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
 ---
+## Documentation
+[Full documentation](https://Hyacinthe-primus.github.io/scanlayer/) – installation, CLI & API reference, configuration, output formats, examples, and troubleshooting.
 ## What it does
 A scanned invoice, a phone photo of a letter, a stack of photographed pages:
@@ -172,28 +180,6 @@ scanlayer.convert_merge(["page1.jpg", "page2.jpg", "page3.jpg"], "report.pdf")
 scanlayer.convert("invoice.jpg", "invoice.json", output_format="json")
 ```
-## Documentation
-| | |
-|---|---|
-| **[Installation](https://Hyacinthe-primus.github.io/scanlayer/installation.html)** | Tesseract, poppler, and the two ways to install scanlayer itself |
-| **[Examples](https://Hyacinthe-primus.github.io/scanlayer/examples.html)** | Every feature, CLI and library side by side |
-| **[CLI Reference](https://Hyacinthe-primus.github.io/scanlayer/cli-reference.html)** | Every flag and exit code |
-| **[Library API](https://Hyacinthe-primus.github.io/scanlayer/library-api.html)** | `convert()`, `convert_batch()`, `convert_merge()`, exceptions, and the full low-level pipeline API |
-| **[Feature Catalog](https://Hyacinthe-primus.github.io/scanlayer/features.html)** | Everything scanlayer does, by pipeline stage |
-| **[Configuration](https://Hyacinthe-primus.github.io/scanlayer/configuration.html)** | `configure()`, config files, precedence, every tunable |
-| **[Output Formats](https://Hyacinthe-primus.github.io/scanlayer/output-formats.html)** | The `pdf`/`txt`/`json`/`tsv`/`hocr` schemas |
-| **[Multi-Page & Merge](https://Hyacinthe-primus.github.io/scanlayer/multi-page-merge.html)** | Batching, merging, native PDF input |
-| **[Debug Visualization](https://Hyacinthe-primus.github.io/scanlayer/debug-visualization.html)** | Reading the `--debug-image` confidence overlay |
-| **[Bundling Tesseract](https://Hyacinthe-primus.github.io/scanlayer/bundling-tesseract.html)** | Shipping your own Tesseract binary |
-| **[Troubleshooting](https://Hyacinthe-primus.github.io/scanlayer/troubleshooting.html)** | Common errors and fixes |
-| **[Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html)** | What's missing and what's deliberately out of scope |
-The site is published from the `gh-pages` branch at
-https://Hyacinthe-primus.github.io/scanlayer/. To browse it locally, open
-`index.html` in a `gh-pages` worktree (e.g. `git worktree add <path> gh-pages`);
-it has no build step or server-side dependency.
 ## Repository layout
 ```
@@ -226,8 +212,20 @@ Bug reports, fixes, and feature discussions are welcome: see
 [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development
 environment and what to include in a pull request. There is a `tests/`
 directory (now including `utils/validators.py` and the `--dry-run` flag, with
-cross-platform coverage for Tesseract discovery on Windows/macOS/Linux) and it runs with `pytest`, but no CI yet; see [Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html) and the [Adding tests](CONTRIBUTING.md#adding-tests) section of the contributing guide for where coverage is thinnest.
+cross-platform coverage for Tesseract discovery on Windows/macOS/Linux) and it runs with `pytest` automatically in CI on every push and pull request; see [Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html) and the [Adding tests](CONTRIBUTING.md#adding-tests) section of the contributing guide for where coverage is thinnest.
+## Support the project
+scanlayer is free and MIT-licensed, maintained in spare time. If it saves you
+time, there is no fee – but a little support goes a long way:
+- **Star the repository** – the simplest signal that the project is worth
+  maintaining.
+- **Report bugs or request features** by opening a
+  [GitHub Issue](https://github.com/Hyacinthe-primus/scanlayer/issues).
+- **Contribute** a fix, test, or example – see
+  [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
-[MIT](LICENSE.md).
+This project is licensed under the [MIT License](LICENSE.md).

{scanlayer-1.0.2 → scanlayer-1.1.0}/README.md RENAMED Viewed

@@ -1,20 +1,27 @@
 <div align="center">
-<img src="scanlayer.png" alt="scanlayer" width="110"/>
+<img src="https://raw.githubusercontent.com/Hyacinthe-primus/scanlayer/main/scanlayer.png" alt="scanlayer" width="110"/>
 <h1>scanlayer</h1>
-<p><em>Scanned image or photographed document &rarr; searchable PDF, or raw OCR text/JSON/TSV/hOCR.</em></p>
+<p><em> Turn scanned image or photographed document into searchable PDF, or raw OCR text/JSON/TSV/hOCR.</em></p>
 </div>
 **Turn a scanned image or photographed document into a searchable PDF**, or
 export the raw OCR result as plain text, JSON, TSV, or hOCR. Use it as a
 command-line tool or as a Python library; both are the same engine underneath.
-[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](#)
+[![PyPI version](https://badge.fury.io/py/scanlayer.svg)](https://badge.fury.io/py/scanlayer)
+[![codecov](https://codecov.io/gh/Hyacinthe-primus/scanlayer/branch/main/graph/badge.svg)](https://codecov.io/gh/Hyacinthe-primus/scanlayer)
+[![Python](https://img.shields.io/badge/python-3.9%2B-3776AB)](#)
 ![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
 [![](https://img.shields.io/badge/-documentation-green)](https://Hyacinthe-primus.github.io/scanlayer/)
+[![GitHub last commit](https://img.shields.io/github/last-commit/Hyacinthe-primus/scanlayer)](https://github.com/Hyacinthe-primus/scanlayer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
 ---
+## Documentation
+[Full documentation](https://Hyacinthe-primus.github.io/scanlayer/) – installation, CLI & API reference, configuration, output formats, examples, and troubleshooting.
 ## What it does
 A scanned invoice, a phone photo of a letter, a stack of photographed pages:
@@ -147,28 +154,6 @@ scanlayer.convert_merge(["page1.jpg", "page2.jpg", "page3.jpg"], "report.pdf")
 scanlayer.convert("invoice.jpg", "invoice.json", output_format="json")
 ```
-## Documentation
-| | |
-|---|---|
-| **[Installation](https://Hyacinthe-primus.github.io/scanlayer/installation.html)** | Tesseract, poppler, and the two ways to install scanlayer itself |
-| **[Examples](https://Hyacinthe-primus.github.io/scanlayer/examples.html)** | Every feature, CLI and library side by side |
-| **[CLI Reference](https://Hyacinthe-primus.github.io/scanlayer/cli-reference.html)** | Every flag and exit code |
-| **[Library API](https://Hyacinthe-primus.github.io/scanlayer/library-api.html)** | `convert()`, `convert_batch()`, `convert_merge()`, exceptions, and the full low-level pipeline API |
-| **[Feature Catalog](https://Hyacinthe-primus.github.io/scanlayer/features.html)** | Everything scanlayer does, by pipeline stage |
-| **[Configuration](https://Hyacinthe-primus.github.io/scanlayer/configuration.html)** | `configure()`, config files, precedence, every tunable |
-| **[Output Formats](https://Hyacinthe-primus.github.io/scanlayer/output-formats.html)** | The `pdf`/`txt`/`json`/`tsv`/`hocr` schemas |
-| **[Multi-Page & Merge](https://Hyacinthe-primus.github.io/scanlayer/multi-page-merge.html)** | Batching, merging, native PDF input |
-| **[Debug Visualization](https://Hyacinthe-primus.github.io/scanlayer/debug-visualization.html)** | Reading the `--debug-image` confidence overlay |
-| **[Bundling Tesseract](https://Hyacinthe-primus.github.io/scanlayer/bundling-tesseract.html)** | Shipping your own Tesseract binary |
-| **[Troubleshooting](https://Hyacinthe-primus.github.io/scanlayer/troubleshooting.html)** | Common errors and fixes |
-| **[Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html)** | What's missing and what's deliberately out of scope |
-The site is published from the `gh-pages` branch at
-https://Hyacinthe-primus.github.io/scanlayer/. To browse it locally, open
-`index.html` in a `gh-pages` worktree (e.g. `git worktree add <path> gh-pages`);
-it has no build step or server-side dependency.
 ## Repository layout
 ```
@@ -201,8 +186,20 @@ Bug reports, fixes, and feature discussions are welcome: see
 [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development
 environment and what to include in a pull request. There is a `tests/`
 directory (now including `utils/validators.py` and the `--dry-run` flag, with
-cross-platform coverage for Tesseract discovery on Windows/macOS/Linux) and it runs with `pytest`, but no CI yet; see [Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html) and the [Adding tests](CONTRIBUTING.md#adding-tests) section of the contributing guide for where coverage is thinnest.
+cross-platform coverage for Tesseract discovery on Windows/macOS/Linux) and it runs with `pytest` automatically in CI on every push and pull request; see [Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html) and the [Adding tests](CONTRIBUTING.md#adding-tests) section of the contributing guide for where coverage is thinnest.
+## Support the project
+scanlayer is free and MIT-licensed, maintained in spare time. If it saves you
+time, there is no fee – but a little support goes a long way:
+- **Star the repository** – the simplest signal that the project is worth
+  maintaining.
+- **Report bugs or request features** by opening a
+  [GitHub Issue](https://github.com/Hyacinthe-primus/scanlayer/issues).
+- **Contribute** a fix, test, or example – see
+  [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
-[MIT](LICENSE.md).
+This project is licensed under the [MIT License](LICENSE.md).

{scanlayer-1.0.2 → scanlayer-1.1.0}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "scanlayer"
-version = "1.0.2"
+version = "1.1.0"
 description = "Image (scan/photo) to searchable PDF, or raw OCR export, via Tesseract."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -23,7 +23,7 @@ dependencies = [
 ]
 [project.optional-dependencies]
-test = ["pytest>=7.0"]
+test = ["pytest>=7.0", "pytest-cov>=4.1"]
 yaml = ["PyYAML>=6.0"]
 [project.scripts]

{scanlayer-1.0.2 → scanlayer-1.1.0}/scanlayer/cli/parser.py RENAMED Viewed

@@ -77,6 +77,14 @@ def _build_parser() -> argparse.ArgumentParser:
              "multi-page PDF input. Only with --format pdf. -o must "
              "be a file path, not a folder.",
     )
+    io_group.add_argument(
+        "--workers", type=int, default=None, metavar="N",
+        help="With --merge: process up to N pages at the same time "
+             f"(1-{config.MERGE_WORKERS_LIMIT}, default {config.MERGE_WORKERS}; "
+             "1 = one page at a time). Only changes speed: page order "
+             "and OCR output are the same. Ignored without --merge. "
+             "Equivalent to configure(merge_workers=N).",
+    )
     io_group.add_argument(
         "--config", default=None,
         help="Path to a .yaml/.yml/.json config profile applied via "

{scanlayer-1.0.2 → scanlayer-1.1.0}/scanlayer/cli/run.py RENAMED Viewed

@@ -21,7 +21,7 @@ from scanlayer.cli.dry_run import (
 )
 from scanlayer.cli.parser import _build_parser
 from scanlayer.main import _expand_pdf_input, _resolve_output_path, convert, convert_merge
-from scanlayer.utils.logger import get_logger, log_error
+from scanlayer.utils.logger import get_logger, log_error, log_warning
 def main(argv: list[str] = None) -> int:
@@ -112,6 +112,12 @@ def main(argv: list[str] = None) -> int:
     if args.merge and (args.output.endswith(("/", "\\")) or os.path.isdir(args.output)):
         log_error(log, "--merge requires -o/--output to be a file path, not a folder.")
         return EXIT_USER_ERROR
+    if args.workers is not None:
+        if args.workers < 1:
+            log_error(log, f"--workers must be 1 or more. Got {args.workers}.")
+            return EXIT_USER_ERROR
+        if not args.merge:
+            log_warning(log, "--workers only applies with --merge, ignoring it.")
     raw_inputs: list[str] = []
     for pat in args.input:
@@ -147,6 +153,7 @@ def main(argv: list[str] = None) -> int:
                     pdf_metadata=pdf_metadata,
                     force=args.force,
                     orientation=orientation_value,
+                    workers=args.workers,
                 )
                 return EXIT_OK
             except Exception as exc:

{scanlayer-1.0.2 → scanlayer-1.1.0}/scanlayer/config.py RENAMED Viewed

@@ -89,6 +89,12 @@ PSM_EARLY_EXIT_CONFIDENCE = 80.0
 PSM_PARALLEL = True
 PSM_MAX_WORKERS = None
+# Pages processed concurrently by convert_merge()/--merge. 1 = one page at
+# a time. Each page already races several Tesseract processes, so this is
+# kept small; MERGE_WORKERS_LIMIT is a hard ceiling that is not configurable.
+MERGE_WORKERS = 3
+MERGE_WORKERS_LIMIT = 4
 OCR_TIMEOUT_SECONDS = 45
 # PSM candidates: engine.py runs one pass per PSM, keeps highest mean confidence.
@@ -161,6 +167,7 @@ _CONFIGURABLE_KEYS = {
     "psm_early_exit_confidence": "PSM_EARLY_EXIT_CONFIDENCE",
     "psm_parallel": "PSM_PARALLEL",
     "psm_max_workers": "PSM_MAX_WORKERS",
+    "merge_workers": "MERGE_WORKERS",
     "ocr_timeout_seconds": "OCR_TIMEOUT_SECONDS",
     "char_whitelist": "TESSERACT_CHAR_WHITELIST",
     "char_blacklist": "TESSERACT_CHAR_BLACKLIST",

{scanlayer-1.0.2 → scanlayer-1.1.0}/scanlayer/main.py RENAMED Viewed

@@ -9,7 +9,9 @@ from __future__ import annotations
 import glob
 import os
 import tempfile
+import threading
 import time
+from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
 from typing import Optional
@@ -17,7 +19,7 @@ from PIL import Image
 from scanlayer import config
 from scanlayer.layout.columns import reorder_reading_order
-from scanlayer.ocr.engine import extract_words
+from scanlayer.ocr.engine import extract_words, use_configured_tesseract
 from scanlayer.ocr.export import FORMATS, export_words
 from scanlayer.pdf.builder import build_searchable_pdf, build_searchable_pdf_multipage
 from scanlayer.preprocessing.enhance import preprocess
@@ -422,10 +424,12 @@ def _process_page_for_merge(
     char_blacklist: Optional[str],
     orientation: "str | float | None",
     force: bool,
+    ocr_slots: Optional[threading.Semaphore] = None,
 ):
     """Run preprocessing + OCR for one page of a --merge run.
     Returns (PageInput, stats_dict). Does not touch the output path.
+    Safe to call from several threads at once.
     """
     from scanlayer.pdf.builder import PageInput
@@ -467,6 +471,7 @@ def _process_page_for_merge(
     ocr_result = extract_words(
         result.ocr_image, result.ocr_scale, effective_dpi=result.effective_dpi,
         lang=lang, char_whitelist=char_whitelist, char_blacklist=char_blacklist,
+        ocr_slots=ocr_slots,
     )
     ocr_result.words, column_count = reorder_reading_order(
         ocr_result.words, page_width=result.background.width,
@@ -487,6 +492,86 @@ def _process_page_for_merge(
     return page, stats
+def _resolve_merge_workers(workers: Optional[int], page_count: int) -> int:
+    """How many pages a merge run processes at once (always >= 1).
+    None means config.MERGE_WORKERS. The result never exceeds
+    config.MERGE_WORKERS_LIMIT, the page count, or the CPU count.
+    """
+    requested = config.MERGE_WORKERS if workers is None else workers
+    if isinstance(requested, bool) or not isinstance(requested, int) or requested < 1:
+        raise ValueError(f"workers must be an integer >= 1, got {requested!r}.")
+    limit = config.MERGE_WORKERS_LIMIT
+    if requested > limit:
+        log_warning(
+            get_logger("main"),
+            f"workers={requested} is above the maximum of {limit}, using {limit}.",
+        )
+    return max(1, min(requested, limit, page_count, os.cpu_count() or 1))
+def _process_pages_for_merge(
+    input_paths: list[str],
+    workers: int,
+    lang: Optional[str],
+    dpi: Optional[int],
+    char_whitelist: Optional[str],
+    char_blacklist: Optional[str],
+    orientation: "str | float | None",
+    force: bool,
+) -> list:
+    """Run preprocessing + OCR for every page of a merge run.
+    Returns [(PageInput, stats), ...] in input order, whatever order the
+    pages finish in. If a page fails, the failure of the first bad page in
+    input order is raised and pages that have not started yet are dropped.
+    With workers == 1 pages are processed one at a time on the calling
+    thread, exactly as before.
+    """
+    log = get_logger("main")
+    page_args = (lang, dpi, char_whitelist, char_blacklist, orientation, force)
+    use_configured_tesseract()
+    def _done(input_path: str, stats: dict) -> None:
+        log.info(
+            f"'{input_path}': {stats['words']} words "
+            f"(mean confidence {stats['mean_conf']:.1f}%"
+            + (f", {stats['columns']} columns" if stats["columns"] > 1 else "")
+            + ")"
+        )
+    results: list = []
+    if workers <= 1:
+        for input_path in input_paths:
+            page, stats = _process_page_for_merge(input_path, *page_args)
+            _done(input_path, stats)
+            results.append((page, stats))
+        return results
+    # Every page already races several Tesseract processes. This shared
+    # semaphore keeps the total at the CPU count, so concurrent pages cannot
+    # starve each other into the per-call OCR timeout.
+    ocr_slots = threading.BoundedSemaphore(os.cpu_count() or 1)
+    log.info(f"Processing {len(input_paths)} page(s) with {workers} parallel workers.")
+    executor = ThreadPoolExecutor(max_workers=workers, thread_name_prefix="scanlayer-page")
+    try:
+        futures = [
+            executor.submit(
+                _process_page_for_merge, input_path, *page_args, ocr_slots=ocr_slots,
+            )
+            for input_path in input_paths
+        ]
+        for input_path, future in zip(input_paths, futures):
+            page, stats = future.result()
+            _done(input_path, stats)
+            results.append((page, stats))
+    finally:
+        executor.shutdown(wait=True, cancel_futures=True)
+    return results
 def convert_merge(
     input_paths: list[str],
     output_path: str,
@@ -498,15 +583,22 @@ def convert_merge(
     pdf_metadata: Optional[dict] = None,
     force: bool = False,
     orientation: "str | float | None" = None,
+    workers: Optional[int] = None,
 ) -> ConversionResult:
     """Combine several images into one multi-page searchable PDF.
     PDF-only. Raises BlankPageDetectedError if any page is blank and
     force=False.
+    workers: pages processed concurrently, 1 to config.MERGE_WORKERS_LIMIT
+        (4). None uses config.MERGE_WORKERS (default 3). 1 processes one
+        page at a time. It only changes speed: page order and OCR output are
+        the same for any value.
     """
     if not input_paths:
         raise ValueError("convert_merge() called with no input paths.")
+    worker_count = _resolve_merge_workers(workers, len(input_paths))
     log = get_logger("main")
     t0 = time.perf_counter()
@@ -518,22 +610,16 @@ def convert_merge(
     conf_weighted_sum = 0.0
     conf_weight_n = 0
     max_columns = 1
-    for input_path in input_paths:
-        page, stats = _process_page_for_merge(
-            input_path, lang, dpi, char_whitelist, char_blacklist, orientation, force,
-        )
+    for page, stats in _process_pages_for_merge(
+        input_paths, worker_count, lang, dpi, char_whitelist, char_blacklist,
+        orientation, force,
+    ):
         pages.append(page)
         total_words += stats["words"]
         if stats["words"]:
             conf_weighted_sum += stats["mean_conf"] * stats["words"]
             conf_weight_n += stats["words"]
         max_columns = max(max_columns, stats["columns"])
-        log.info(
-            f"'{input_path}': {stats['words']} words "
-            f"(mean confidence {stats['mean_conf']:.1f}%"
-            + (f", {stats['columns']} columns" if stats["columns"] > 1 else "")
-            + ")"
-        )
     output_size_bytes = build_searchable_pdf_multipage(
         pages, output_abs, jpeg_quality=jpeg_quality, metadata=pdf_metadata,
@@ -577,6 +663,7 @@ def convert_batch(
     orientation: "str | float | None" = None,
     output_format: str = "pdf",
     debug_image: bool = False,
+    workers: Optional[int] = None,
     verbose: bool = False,
     quiet: bool = False,
 ) -> BatchResult:
@@ -588,6 +675,8 @@ def convert_batch(
         (same directory/stem, extension from output_format). Not valid
         with merge=True, which needs one explicit shared output path.
     merge: combine all inputs into one multi-page PDF.
+    workers: with merge=True, pages processed concurrently (see
+        convert_merge()). Ignored without merge.
     verbose/quiet: set log level for the call.
     Never raises for per-file failures. Check BatchResult.failures.
@@ -636,6 +725,7 @@ def convert_batch(
                     lang=lang, dpi=dpi, jpeg_quality=jpeg_quality,
                     char_whitelist=char_whitelist, char_blacklist=char_blacklist,
                     pdf_metadata=pdf_metadata, force=force, orientation=orientation,
+                    workers=workers,
                 ))
             except Exception as exc:
                 failures.append(("<merge>", str(exc)))

{scanlayer-1.0.2 → scanlayer-1.1.0}/scanlayer/ocr/engine.py RENAMED Viewed

@@ -8,6 +8,7 @@ confidence. Supports early-exit and parallel execution via threads.
 from __future__ import annotations
 import os
+import threading
 import time
 import unicodedata
 from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
@@ -168,8 +169,29 @@ def _run_ocr(
     )
-def _safe_run_ocr(*args, psm: int, **kwargs) -> tuple[PsmAttempt | None, Exception | None]:
-    """Run one PSM candidate, converting exceptions into return values."""
+def use_configured_tesseract() -> None:
+    """Point pytesseract at config.TESSERACT_CMD.
+    pytesseract keeps the binary path in a module global, and
+    preprocessing's OSD call runs before the first extract_words(), so
+    callers that start concurrent work set it once up front.
+    """
+    pytesseract.pytesseract.tesseract_cmd = config.TESSERACT_CMD
+def _safe_run_ocr(
+    *args,
+    psm: int,
+    ocr_slots: Optional[threading.Semaphore] = None,
+    **kwargs,
+) -> tuple[PsmAttempt | None, Exception | None]:
+    """Run one PSM candidate, converting exceptions into return values.
+    With ocr_slots, waits for a free slot first, so the Tesseract timeout
+    only starts counting once the process actually runs.
+    """
+    if ocr_slots is not None:
+        ocr_slots.acquire()
     try:
         return _run_ocr(*args, **kwargs), None
     except pytesseract.TesseractNotFoundError as exc:
@@ -183,6 +205,9 @@ def _safe_run_ocr(*args, psm: int, **kwargs) -> tuple[PsmAttempt | None, Excepti
     except Exception as exc:  # genuinely unexpected, still surfaced, not swallowed
         log_warning(log, f"PSM {psm}, unexpected error ({type(exc).__name__}: {exc})")
         return None, exc
+    finally:
+        if ocr_slots is not None:
+            ocr_slots.release()
 def extract_words(
@@ -192,16 +217,21 @@ def extract_words(
     lang: Optional[str] = None,
     char_whitelist: Optional[str] = None,
     char_blacklist: Optional[str] = None,
+    ocr_slots: Optional[threading.Semaphore] = None,
 ) -> OcrResult:
     """Run OCR with automatic PSM selection.
+    ocr_slots, if given, is shared by concurrent callers (convert_merge()
+    processing several pages at once) and bounds how many Tesseract passes
+    run at the same time. It never changes which result is selected.
     Raises OCRProcessingError if every PSM candidate fails.
     """
     lang = lang or config.DEFAULT_OCR_LANG
     wl = char_whitelist if char_whitelist is not None else config.TESSERACT_CHAR_WHITELIST
     bl = char_blacklist if char_blacklist is not None else config.TESSERACT_CHAR_BLACKLIST
-    pytesseract.pytesseract.tesseract_cmd = config.TESSERACT_CMD
+    use_configured_tesseract()
     tess_base = f'--tessdata-dir "{config.TESSDATA_DIR}"' if config.TESSDATA_DIR else ""
     psm_candidates = list(config.TESSERACT_PSM_CANDIDATES)
@@ -224,7 +254,7 @@ def extract_words(
         if len(psm_candidates) == 1:
             attempt, error = _safe_run_ocr(
                 ocr_image, lang, psm_candidates[0], tess_base,
-                effective_dpi, wl, bl, psm=psm_candidates[0],
+                effective_dpi, wl, bl, psm=psm_candidates[0], ocr_slots=ocr_slots,
             )
             if attempt is not None:
                 attempts.append(attempt)
@@ -236,12 +266,13 @@ def extract_words(
             max_workers = config.PSM_MAX_WORKERS or min(32, (os.cpu_count() or 1) + 4)
             max_workers = min(max_workers, len(psm_candidates))
             can_skip_unstarted = max_workers < len(psm_candidates)
+            order = {psm: i for i, psm in enumerate(psm_candidates)}
             executor = ThreadPoolExecutor(max_workers=max_workers)
             futures = {
                 executor.submit(
                     _safe_run_ocr, ocr_image, lang, psm, tess_base,
-                    effective_dpi, wl, bl, psm=psm,
+                    effective_dpi, wl, bl, psm=psm, ocr_slots=ocr_slots,
                 ): psm
                 for psm in psm_candidates
             }
@@ -253,7 +284,14 @@ def extract_words(
                         attempt, error = future.result()
                         if attempt is not None:
                             attempts.append(attempt)
-                            if best is None or attempt.mean_confidence > best.mean_confidence:
+                            if (
+                                best is None
+                                or attempt.mean_confidence > best.mean_confidence
+                                or (
+                                    attempt.mean_confidence == best.mean_confidence
+                                    and order[attempt.psm] < order[best.psm]
+                                )
+                            ):
                                 best = attempt
                         else:
                             errors.append(error)
@@ -277,7 +315,7 @@ def extract_words(
             for psm in psm_candidates:
                 attempt, error = _safe_run_ocr(
                     ocr_image, lang, psm, tess_base,
-                    effective_dpi, wl, bl, psm=psm,
+                    effective_dpi, wl, bl, psm=psm, ocr_slots=ocr_slots,
                 )
                 if attempt is not None:
                     attempts.append(attempt)

{scanlayer-1.0.2 → scanlayer-1.1.0}/scanlayer/pdf/fonts.py RENAMED Viewed

@@ -12,6 +12,7 @@ Set config.FONT_PATH to force a specific TTF and skip auto-selection.
 from __future__ import annotations
 import os
+import sys
 from reportlab.pdfbase import pdfmetrics
 from reportlab.pdfbase.cidfonts import UnicodeCIDFont
@@ -25,7 +26,9 @@ log = get_logger(__name__)
 FALLBACK_FONT = "Helvetica"
 _UNICODE_TTF_NAME = "ScanlayerUnicode"
-_UNICODE_TTF_PATH = os.path.join(os.path.dirname(__file__), "..", "fonts", "DejaVuSans.ttf")
+_scanlayer_root = os.path.dirname(os.path.dirname(__file__))
+_bundle_root = getattr(sys, "_MEIPASS", os.path.dirname(_scanlayer_root))
+_UNICODE_TTF_PATH = os.path.join(_bundle_root, "scanlayer", "fonts", "DejaVuSans.ttf")
 _CUSTOM_TTF_NAME = "ScanlayerCustom"
 _custom_registered_path: str | None = None

{scanlayer-1.0.2 → scanlayer-1.1.0/scanlayer.egg-info}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanlayer
-Version: 1.0.2
+Version: 1.1.0
 Summary: Image (scan/photo) to searchable PDF, or raw OCR export, via Tesseract.
 Author: Hyacinthe-primus
 Author-email: Hyacinthe-primus <hyacintheatho91@gmail.com>
@@ -19,27 +19,35 @@ Requires-Dist: numpy>=1.24.0
 Requires-Dist: pdf2image>=1.17.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1; extra == "test"
 Provides-Extra: yaml
 Requires-Dist: PyYAML>=6.0; extra == "yaml"
 Dynamic: license-file
 <div align="center">
-<img src="scanlayer.png" alt="scanlayer" width="110"/>
+<img src="https://raw.githubusercontent.com/Hyacinthe-primus/scanlayer/main/scanlayer.png" alt="scanlayer" width="110"/>
 <h1>scanlayer</h1>
-<p><em>Scanned image or photographed document &rarr; searchable PDF, or raw OCR text/JSON/TSV/hOCR.</em></p>
+<p><em> Turn scanned image or photographed document into searchable PDF, or raw OCR text/JSON/TSV/hOCR.</em></p>
 </div>
 **Turn a scanned image or photographed document into a searchable PDF**, or
 export the raw OCR result as plain text, JSON, TSV, or hOCR. Use it as a
 command-line tool or as a Python library; both are the same engine underneath.
-[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](#)
+[![PyPI version](https://badge.fury.io/py/scanlayer.svg)](https://badge.fury.io/py/scanlayer)
+[![codecov](https://codecov.io/gh/Hyacinthe-primus/scanlayer/branch/main/graph/badge.svg)](https://codecov.io/gh/Hyacinthe-primus/scanlayer)
+[![Python](https://img.shields.io/badge/python-3.9%2B-3776AB)](#)
 ![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
 [![](https://img.shields.io/badge/-documentation-green)](https://Hyacinthe-primus.github.io/scanlayer/)
+[![GitHub last commit](https://img.shields.io/github/last-commit/Hyacinthe-primus/scanlayer)](https://github.com/Hyacinthe-primus/scanlayer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
 ---
+## Documentation
+[Full documentation](https://Hyacinthe-primus.github.io/scanlayer/) – installation, CLI & API reference, configuration, output formats, examples, and troubleshooting.
 ## What it does
 A scanned invoice, a phone photo of a letter, a stack of photographed pages:
@@ -172,28 +180,6 @@ scanlayer.convert_merge(["page1.jpg", "page2.jpg", "page3.jpg"], "report.pdf")
 scanlayer.convert("invoice.jpg", "invoice.json", output_format="json")
 ```
-## Documentation
-| | |
-|---|---|
-| **[Installation](https://Hyacinthe-primus.github.io/scanlayer/installation.html)** | Tesseract, poppler, and the two ways to install scanlayer itself |
-| **[Examples](https://Hyacinthe-primus.github.io/scanlayer/examples.html)** | Every feature, CLI and library side by side |
-| **[CLI Reference](https://Hyacinthe-primus.github.io/scanlayer/cli-reference.html)** | Every flag and exit code |
-| **[Library API](https://Hyacinthe-primus.github.io/scanlayer/library-api.html)** | `convert()`, `convert_batch()`, `convert_merge()`, exceptions, and the full low-level pipeline API |
-| **[Feature Catalog](https://Hyacinthe-primus.github.io/scanlayer/features.html)** | Everything scanlayer does, by pipeline stage |
-| **[Configuration](https://Hyacinthe-primus.github.io/scanlayer/configuration.html)** | `configure()`, config files, precedence, every tunable |
-| **[Output Formats](https://Hyacinthe-primus.github.io/scanlayer/output-formats.html)** | The `pdf`/`txt`/`json`/`tsv`/`hocr` schemas |
-| **[Multi-Page & Merge](https://Hyacinthe-primus.github.io/scanlayer/multi-page-merge.html)** | Batching, merging, native PDF input |
-| **[Debug Visualization](https://Hyacinthe-primus.github.io/scanlayer/debug-visualization.html)** | Reading the `--debug-image` confidence overlay |
-| **[Bundling Tesseract](https://Hyacinthe-primus.github.io/scanlayer/bundling-tesseract.html)** | Shipping your own Tesseract binary |
-| **[Troubleshooting](https://Hyacinthe-primus.github.io/scanlayer/troubleshooting.html)** | Common errors and fixes |
-| **[Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html)** | What's missing and what's deliberately out of scope |
-The site is published from the `gh-pages` branch at
-https://Hyacinthe-primus.github.io/scanlayer/. To browse it locally, open
-`index.html` in a `gh-pages` worktree (e.g. `git worktree add <path> gh-pages`);
-it has no build step or server-side dependency.
 ## Repository layout
 ```
@@ -226,8 +212,20 @@ Bug reports, fixes, and feature discussions are welcome: see
 [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development
 environment and what to include in a pull request. There is a `tests/`
 directory (now including `utils/validators.py` and the `--dry-run` flag, with
-cross-platform coverage for Tesseract discovery on Windows/macOS/Linux) and it runs with `pytest`, but no CI yet; see [Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html) and the [Adding tests](CONTRIBUTING.md#adding-tests) section of the contributing guide for where coverage is thinnest.
+cross-platform coverage for Tesseract discovery on Windows/macOS/Linux) and it runs with `pytest` automatically in CI on every push and pull request; see [Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html) and the [Adding tests](CONTRIBUTING.md#adding-tests) section of the contributing guide for where coverage is thinnest.
+## Support the project
+scanlayer is free and MIT-licensed, maintained in spare time. If it saves you
+time, there is no fee – but a little support goes a long way:
+- **Star the repository** – the simplest signal that the project is worth
+  maintaining.
+- **Report bugs or request features** by opening a
+  [GitHub Issue](https://github.com/Hyacinthe-primus/scanlayer/issues).
+- **Contribute** a fix, test, or example – see
+  [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
-[MIT](LICENSE.md).
+This project is licensed under the [MIT License](LICENSE.md).

{scanlayer-1.0.2 → scanlayer-1.1.0}/scanlayer.egg-info/SOURCES.txt RENAMED Viewed

@@ -37,5 +37,6 @@ tests/test_dry_run.py
 tests/test_export.py
 tests/test_fonts.py
 tests/test_main_integration.py
+tests/test_merge_workers.py
 tests/test_pdf_builder.py
 tests/test_validators.py

{scanlayer-1.0.2 → scanlayer-1.1.0}/scanlayer.egg-info/requires.txt RENAMED Viewed

@@ -7,6 +7,7 @@ pdf2image>=1.17.0
 [test]
 pytest>=7.0
+pytest-cov>=4.1
 [yaml]
 PyYAML>=6.0

scanlayer-1.1.0/tests/test_merge_workers.py ADDED Viewed

@@ -0,0 +1,316 @@
+"""Tests for processing several pages of a --merge run at once.
+Everything here fakes the per-page work, so no Tesseract is needed: the
+point is the scheduling (order, real concurrency, the worker cap, error
+reporting, the shared OCR slot limit), not the OCR itself.
+"""
+import os
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+import numpy as np
+import pytest
+from scanlayer import config
+from scanlayer import main as main_module
+from scanlayer.cli import main
+from scanlayer.cli.dry_run import EXIT_OK, EXIT_USER_ERROR
+from scanlayer.ocr import engine
+from scanlayer.utils.errors import BlankPageDetectedError, OCRProcessingError
+STATS = {"words": 1, "mean_conf": 90.0, "best_psm": 3, "columns": 1}
+class FakePages:
+    """Stands in for _process_page_for_merge and records how it was called."""
+    def __init__(self, sleep=0.0, delays=None, errors=None):
+        self.sleep = sleep
+        self.delays = delays or {}
+        self.errors = errors or {}
+        self.lock = threading.Lock()
+        self.running = 0
+        self.max_running = 0
+        self.started = []
+        self.thread_ids = set()
+        self.slots = []
+    def __call__(
+        self, input_path, lang, dpi, whitelist, blacklist, orientation, force,
+        ocr_slots=None,
+    ):
+        with self.lock:
+            self.started.append(input_path)
+            self.running += 1
+            self.max_running = max(self.max_running, self.running)
+            self.thread_ids.add(threading.get_ident())
+            self.slots.append(ocr_slots)
+        try:
+            time.sleep(self.delays.get(input_path, self.sleep))
+            if input_path in self.errors:
+                raise self.errors[input_path]
+            return f"page:{input_path}", dict(STATS)
+        finally:
+            with self.lock:
+                self.running -= 1
+@pytest.fixture
+def merge_env(monkeypatch, tmp_path):
+    """Fake page processing + PDF writer, 8 CPUs, returns (run, built)."""
+    built = []
+    def fake_build(pages, output_path, jpeg_quality=None, metadata=None):
+        built.append(list(pages))
+        return 123
+    monkeypatch.setattr(main_module, "build_searchable_pdf_multipage", fake_build)
+    monkeypatch.setattr(os, "cpu_count", lambda: 8)
+    def run(fake, count, **kwargs):
+        monkeypatch.setattr(main_module, "_process_page_for_merge", fake)
+        paths = [f"p{i}" for i in range(count)]
+        return main_module.convert_merge(paths, str(tmp_path / "out.pdf"), **kwargs)
+    return run, built
+def test_pages_keep_input_order_when_they_finish_out_of_order(merge_env):
+    run, built = merge_env
+    fake = FakePages(delays={"p0": 0.15, "p1": 0.1, "p2": 0.05})
+    run(fake, 6, workers=3)
+    assert built == [[f"page:p{i}" for i in range(6)]]
+def test_pages_really_run_concurrently(merge_env):
+    run, _ = merge_env
+    fake = FakePages(sleep=0.1)
+    run(fake, 6, workers=3)
+    assert fake.max_running == 3
+def test_workers_above_the_limit_are_capped(merge_env):
+    run, _ = merge_env
+    fake = FakePages(sleep=0.05)
+    run(fake, 10, workers=10)
+    assert fake.max_running == config.MERGE_WORKERS_LIMIT == 4
+def test_one_worker_runs_on_the_calling_thread_without_slots(merge_env):
+    run, built = merge_env
+    fake = FakePages(sleep=0.01)
+    run(fake, 4, workers=1)
+    assert fake.max_running == 1
+    assert fake.thread_ids == {threading.get_ident()}
+    assert fake.slots == [None] * 4
+    assert built == [[f"page:p{i}" for i in range(4)]]
+def test_default_comes_from_configure(merge_env):
+    run, _ = merge_env
+    config.configure(merge_workers=2)
+    fake = FakePages(sleep=0.1)
+    run(fake, 6)
+    assert fake.max_running == 2
+def test_default_is_three(merge_env):
+    run, _ = merge_env
+    fake = FakePages(sleep=0.1)
+    run(fake, 6)
+    assert fake.max_running == 3
+def test_workers_never_exceed_the_cpu_count(merge_env, monkeypatch):
+    run, _ = merge_env
+    monkeypatch.setattr(os, "cpu_count", lambda: 2)
+    fake = FakePages(sleep=0.1)
+    run(fake, 6, workers=4)
+    assert fake.max_running == 2
+def test_workers_never_exceed_the_page_count(merge_env):
+    run, _ = merge_env
+    fake = FakePages(sleep=0.05)
+    run(fake, 2, workers=4)
+    assert fake.max_running == 2
+@pytest.mark.parametrize("bad", [0, -1, 1.5, True, "3"])
+def test_invalid_workers_rejected_before_any_work(merge_env, bad):
+    run, built = merge_env
+    fake = FakePages()
+    with pytest.raises(ValueError, match="workers"):
+        run(fake, 3, workers=bad)
+    assert fake.started == []
+    assert built == []
+def test_first_bad_page_in_input_order_is_the_one_reported(merge_env):
+    run, built = merge_env
+    fake = FakePages(
+        delays={"p0": 0.2, "p1": 0.1},
+        errors={
+            "p1": BlankPageDetectedError("p1 is blank"),
+            "p2": BlankPageDetectedError("p2 is blank"),
+        },
+    )
+    with pytest.raises(BlankPageDetectedError, match="p1 is blank"):
+        run(fake, 4, workers=3)
+    assert built == []
+def test_a_failure_drops_pages_that_have_not_started(merge_env):
+    run, built = merge_env
+    fake = FakePages(
+        sleep=0.05, delays={"p0": 0.0}, errors={"p0": OCRProcessingError("boom")},
+    )
+    with pytest.raises(OCRProcessingError, match="boom"):
+        run(fake, 20, workers=2)
+    assert len(fake.started) < 20
+    assert built == []
+def test_concurrent_pages_share_one_slot_pool_sized_to_the_cpu_count(merge_env):
+    run, _ = merge_env
+    fake = FakePages(sleep=0.02)
+    run(fake, 5, workers=3)
+    slots = fake.slots[0]
+    assert slots is not None and all(s is slots for s in fake.slots)
+    free = sum(1 for _ in range(20) if slots.acquire(blocking=False))
+    assert free == 8
+def test_convert_batch_passes_workers_to_merge(monkeypatch, tmp_path, text_image):
+    seen = {}
+    def fake_merge(**kwargs):
+        seen.update(kwargs)
+        return "result"
+    monkeypatch.setattr(main_module, "convert_merge", fake_merge)
+    batch = main_module.convert_batch(
+        [text_image, text_image], str(tmp_path / "out.pdf"), merge=True, workers=2,
+    )
+    assert seen["workers"] == 2
+    assert batch.results == ["result"]
+def _fake_psm_runner(calls):
+    def fake(*args, psm, ocr_slots=None, **kwargs):
+        calls.append((psm, ocr_slots))
+        return engine.PsmAttempt(psm=psm, words=[], mean_confidence=0.0, elapsed_ms=0.0), None
+    return fake
+@pytest.mark.parametrize(
+    "settings",
+    [
+        {"psm_candidates": [3]},
+        {"psm_candidates": [3, 4, 6, 11], "psm_parallel": True},
+        {"psm_candidates": [3, 4, 6, 11], "psm_parallel": False},
+    ],
+)
+def test_every_psm_pass_gets_the_shared_slots(monkeypatch, settings):
+    calls = []
+    monkeypatch.setattr(engine, "_safe_run_ocr", _fake_psm_runner(calls))
+    config.configure(**settings)
+    slots = threading.BoundedSemaphore(2)
+    engine.extract_words(
+        np.zeros((10, 10), dtype=np.uint8), 1.0, 300, ocr_slots=slots,
+    )
+    assert len(calls) == len(settings["psm_candidates"])
+    assert all(s is slots for _, s in calls)
+def _racing_psm_runner(confidence, delays):
+    def fake(*args, psm, ocr_slots=None, **kwargs):
+        time.sleep(delays.get(psm, 0.0))
+        attempt = engine.PsmAttempt(
+            psm=psm, words=[], mean_confidence=confidence[psm], elapsed_ms=0.0,
+        )
+        return attempt, None
+    return fake
+def test_psm_tie_goes_to_the_first_candidate_even_if_it_finishes_last(monkeypatch):
+    monkeypatch.setattr(
+        engine,
+        "_safe_run_ocr",
+        _racing_psm_runner({3: 50.0, 4: 50.0, 6: 50.0, 11: 50.0}, {3: 0.15}),
+    )
+    config.configure(psm_candidates=[3, 4, 6, 11], psm_parallel=True)
+    result = engine.extract_words(np.zeros((10, 10), dtype=np.uint8), 1.0, 300)
+    assert result.best_psm == 3
+def test_psm_higher_confidence_still_beats_an_earlier_candidate(monkeypatch):
+    monkeypatch.setattr(
+        engine,
+        "_safe_run_ocr",
+        _racing_psm_runner({3: 40.0, 4: 40.0, 6: 60.0, 11: 40.0}, {6: 0.15}),
+    )
+    config.configure(psm_candidates=[3, 4, 6, 11], psm_parallel=True)
+    result = engine.extract_words(np.zeros((10, 10), dtype=np.uint8), 1.0, 300)
+    assert result.best_psm == 6
+def test_slots_bound_concurrent_tesseract_passes_and_are_released(monkeypatch):
+    lock = threading.Lock()
+    state = {"running": 0, "max": 0}
+    def fake_run_ocr(*args, **kwargs):
+        with lock:
+            state["running"] += 1
+            state["max"] = max(state["max"], state["running"])
+        time.sleep(0.03)
+        with lock:
+            state["running"] -= 1
+        if kwargs.get("fail"):
+            raise OCRProcessingError("timeout")
+        return engine.PsmAttempt(psm=3, words=[], mean_confidence=0.0, elapsed_ms=0.0)
+    monkeypatch.setattr(engine, "_run_ocr", fake_run_ocr)
+    slots = threading.BoundedSemaphore(2)
+    def one(_):
+        return engine._safe_run_ocr(None, "eng", 3, "", 300, None, None, psm=3, ocr_slots=slots)
+    with ThreadPoolExecutor(max_workers=6) as pool:
+        list(pool.map(one, range(6)))
+    assert state["max"] == 2
+    failing = engine._safe_run_ocr(
+        None, "eng", 3, "", 300, None, None, psm=3, ocr_slots=slots, fail=True,
+    )
+    assert failing[0] is None
+    assert sum(1 for _ in range(5) if slots.acquire(blocking=False)) == 2
+def test_workers_flag_parses():
+    from scanlayer.cli.parser import _build_parser
+    args = _build_parser().parse_args(["a.jpg", "-o", "x.pdf", "--merge", "--workers", "3"])
+    assert args.workers == 3
+    assert _build_parser().parse_args(["a.jpg"]).workers is None
+def test_cli_rejects_zero_workers(text_image, tmp_path):
+    out = tmp_path / "merged.pdf"
+    code = main([text_image, "-o", str(out), "--merge", "--workers", "0"])
+    assert code == EXIT_USER_ERROR
+def test_cli_passes_workers_to_convert_merge(monkeypatch, text_image, tmp_path):
+    import scanlayer.cli.run as run_module
+    seen = {}
+    monkeypatch.setattr(run_module, "convert_merge", lambda **kw: seen.update(kw))
+    out = tmp_path / "merged.pdf"
+    code = main([text_image, text_image, "-o", str(out), "--merge", "--workers", "2"])
+    assert code == EXIT_OK
+    assert seen["workers"] == 2