scanlayer 1.0.0__tar.gz

scanlayer-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scanlayer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scanlayer-1.0.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: scanlayer
+Version: 1.0.0
+Summary: Image (scan/photo) to searchable PDF, or raw OCR export, via Tesseract.
+Requires-Python: >=3.9
+License-File: LICENSE.md
+Requires-Dist: pytesseract>=0.3.10
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: reportlab>=4.0.0
+Requires-Dist: opencv-python-headless>=4.8.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pdf2image>=1.17.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=6.0; extra == "yaml"
+Dynamic: license-file

scanlayer-1.0.0/README.md

@@ -0,0 +1,208 @@
+<div align="center">
+<img src="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>
+</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)](#)
+![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/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
+
+---
+
+## What it does
+
+A scanned invoice, a phone photo of a letter, a stack of photographed pages:
+scanlayer runs it through [Tesseract OCR](https://github.com/tesseract-ocr/tesseract)
+and gives you back either:
+
+- a **searchable PDF**: the original page image, with an invisible, precisely
+  positioned text layer over it, so you can select and search text exactly
+  where it visually appears, or
+- the **raw OCR result** as `txt`, `json`, `tsv`, or `hocr`: text, per-word
+  confidence, and bounding boxes, no PDF built at all.
+
+Along the way it automatically straightens rotated/skewed pages, corrects
+uneven lighting, denoises and sharpens for OCR accuracy without touching what
+you actually see in the output, reconstructs correct reading order on
+genuine multi-column pages, and races several OCR configurations against
+each other to pick the most confident result.
+
+| | |
+|---|---|
+| **Two interfaces, one engine** | `scanlayer` CLI and `import scanlayer` call the exact same pipeline |
+| **Five output formats** | Searchable `pdf`, or raw `txt` / `json` / `tsv` / `hocr` |
+| **Real column detection** | Two-column articles/letters read in correct order, not interleaved |
+| **Batch, merge, native PDF input** | Convert a folder in one call, merge pages into one PDF, or `--dry-run` a batch before spending time on OCR |
+| **One configuration surface** | `configure()`, a JSON/YAML profile, or CLI flags, documented precedence |
+| **Debug overlay** | `--debug-image` draws every word, color-coded by confidence |
+
+See the [feature catalog](https://Hyacinthe-primus.github.io/scanlayer/features.html) for the complete list, and
+[Roadmap & Limitations](https://Hyacinthe-primus.github.io/scanlayer/roadmap.html) for what's deliberately out of
+scope or not built yet.
+
+## Requirements
+
+- Python 3.9+
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) (a separate, system-level install, see below)
+- [poppler](https://poppler.freedesktop.org/) *only if* you feed scanlayer a native `.pdf` file directly
+
+```bash
+# Debian / Ubuntu
+sudo apt install tesseract-ocr poppler-utils
+
+# macOS (Homebrew)
+brew install tesseract poppler
+
+# Windows: Tesseract -> https://github.com/tesseract-ocr/tesseract/wiki
+#          poppler    -> download a release, add its bin/ to PATH
+```
+
+Full detail, including how scanlayer locates the Tesseract binary
+automatically and how to bundle your own, is in
+[Installation](https://Hyacinthe-primus.github.io/scanlayer/installation.html) and [Bundling Tesseract](https://Hyacinthe-primus.github.io/scanlayer/bundling-tesseract.html).
+
+## Install
+
+```bash
+pip install scanlayer
+```
+
+This installs the `scanlayer` console command and makes `import scanlayer`
+available anywhere on the machine.
+
+Working on scanlayer itself, or want to run it straight from a checkout with
+no install at all?
+
+```bash
+git clone https://github.com/Hyacinthe-primus/scanlayer.git
+cd scanlayer                        # the repo root, which contains requirements.txt
+pip install -r requirements.txt
+python -m scanlayer invoice.jpg -o invoice.pdf   # works with no install at all
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor setup
+(editable install and running the test suite).
+
+## Quick start
+
+**As a CLI:**
+
+```bash
+scanlayer invoice.jpg -o invoice.pdf --lang fra+eng --dpi 300
+```
+
+**As a library:**
+
+```python
+import scanlayer
+
+result = scanlayer.convert("invoice.jpg", "invoice.pdf", lang="fra+eng", dpi=300)
+print(f"{result.words_count} words, {result.mean_confidence:.1f}% confidence")
+```
+
+Every CLI flag and library keyword argument in this project are named to
+match each other (`--lang` ↔ `lang=`, `--dpi` ↔ `dpi=`, and so on), see
+[Examples](https://Hyacinthe-primus.github.io/scanlayer/examples.html) for every
+feature shown both ways, side by side, and
+[CLI Reference](https://Hyacinthe-primus.github.io/scanlayer/cli-reference.html) /
+[Library API](https://Hyacinthe-primus.github.io/scanlayer/library-api.html) for
+the complete details of each.
+
+A few more common cases:
+
+```bash
+# Batch-convert a folder
+scanlayer *.jpg -o ./converted/
+
+# Merge several photographed pages into one searchable PDF
+scanlayer page1.jpg page2.jpg page3.jpg -o report.pdf --merge
+
+# Export raw OCR text/JSON instead of a PDF
+scanlayer invoice.jpg -o invoice.json --format json
+
+# See what OCR actually detected, color-coded by confidence
+scanlayer invoice.jpg --debug-image
+
+# Validate a batch before spending time on OCR: files exist,
+# Tesseract reachable, output paths writable
+scanlayer *.jpg -o ./converted/ --dry-run
+```
+
+```python
+import scanlayer
+
+# Batch
+result = scanlayer.convert_batch(["*.jpg"], "./converted/")
+
+# Merge
+scanlayer.convert_merge(["page1.jpg", "page2.jpg", "page3.jpg"], "report.pdf")
+
+# Raw export
+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
+
+```
+.
+├── .github/           # FUNDING.yml
+├── scanlayer/         # library source
+│   ├── __init__.py
+│   ├── __main__.py    # enables `python -m scanlayer`
+│   ├── main.py        # public API: convert()/convert_batch()/convert_merge()
+│   ├── config.py
+│   ├── cli/           # argparse CLI: parser.py, run.py, dry_run.py
+│   ├── fonts/         # bundled DejaVu Sans for the PDF text layer
+│   ├── preprocessing/
+│   ├── ocr/
+│   ├── layout/
+│   ├── pdf/
+│   └── utils/
+├── tests/             # pytest suite
+├── pyproject.toml
+├── requirements.txt
+├── README.md
+├── CONTRIBUTING.md
+├── SECURITY.md
+└── LICENSE.md
+```
+
+## Contributing
+
+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.
+
+## License
+
+[MIT](LICENSE.md).

scanlayer-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scanlayer"
+version = "1.0.0"
+description = "Image (scan/photo) to searchable PDF, or raw OCR export, via Tesseract."
+requires-python = ">=3.9"
+dependencies = [
+    "pytesseract>=0.3.10",
+    "Pillow>=10.0.0",
+    "reportlab>=4.0.0",
+    "opencv-python-headless>=4.8.0",
+    "numpy>=1.24.0",
+    "pdf2image>=1.17.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+yaml = ["PyYAML>=6.0"]
+
+[project.scripts]
+scanlayer = "scanlayer.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["scanlayer*"]
+
+[tool.setuptools.package-data]
+scanlayer = ["fonts/*.ttf"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B"]
+ignore = ["B008", "B904"]

scanlayer-1.0.0/scanlayer/__init__.py

@@ -0,0 +1,32 @@
+"""
+scanlayer: turn a scanned or photographed document into a searchable PDF,
+or export the raw OCR result as text, JSON, TSV, or hOCR.
+
+Usage:
+
+    import scanlayer
+
+    result = scanlayer.convert("invoice.jpg", "invoice.pdf")
+    print(result.words_count, result.mean_confidence)
+
+For batch processing, use convert_batch() which handles mixed extensions
+and never raises for a single bad file.
+
+Tesseract is located automatically. Use configure() to override:
+
+    scanlayer.configure(tesseract_cmd="/path/to/tesseract", lang="eng")
+
+See scanlayer.config.configure for the full list of options.
+"""
+
+from scanlayer.config import configure, configure_from_file, get_settings, load_config_file
+from scanlayer.main import BatchResult, ConversionResult, convert, convert_batch, convert_merge
+
+__all__ = [
+    "configure", "configure_from_file", "load_config_file", "get_settings",
+    "convert", "ConversionResult",
+    "convert_batch", "BatchResult",
+    "convert_merge",
+]
+
+__version__ = "1.0.0"

scanlayer-1.0.0/scanlayer/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for `python -m scanlayer`.
+
+Avoids double-importing main.py since __init__.py already imports it.
+"""
+
+from scanlayer.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scanlayer-1.0.0/scanlayer/cli/__init__.py

@@ -0,0 +1,10 @@
+"""
+CLI entry point for scanlayer.
+
+Exit codes: 0=success, 1=user error, 2=env error, 3=unexpected,
+4=processing error, 5=partial batch failure.
+"""
+
+from scanlayer.cli.run import main
+
+__all__ = ["main"]

scanlayer-1.0.0/scanlayer/cli/dry_run.py

@@ -0,0 +1,191 @@
+"""
+Exit codes and --dry-run validation logic for the scanlayer CLI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Optional
+
+from scanlayer.main import _default_output_path
+from scanlayer.utils.errors import BlankPageDetectedError, PipelineError
+from scanlayer.utils.logger import log_error
+from scanlayer.utils.validators import (
+    DependencyError,
+    InputFileError,
+    OutputPathError,
+    TesseractEnvironmentError,
+    ValidationError,
+    validate_image_readable,
+    validate_input_file,
+    validate_output_path,
+    validate_tesseract_environment,
+)
+
+EXIT_OK = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+EXIT_UNEXPECTED_ERROR = 3
+EXIT_PROCESSING_ERROR = 4
+EXIT_PARTIAL_BATCH = 5
+
+def _exit_code_for(exc: Exception) -> int:
+    if isinstance(exc, (InputFileError, OutputPathError)):
+        return EXIT_USER_ERROR
+    if isinstance(exc, (TesseractEnvironmentError, DependencyError)):
+        return EXIT_ENV_ERROR
+    if isinstance(exc, ValidationError):
+        return EXIT_USER_ERROR
+    if isinstance(exc, BlankPageDetectedError):
+        return EXIT_USER_ERROR  # not a bug/env issue, user needs to pass --force
+    if isinstance(exc, PipelineError):
+        return EXIT_PROCESSING_ERROR
+    return EXIT_UNEXPECTED_ERROR
+
+
+def _dry_run_resolve_output_path(
+    output_arg: str, input_path: str, is_batch: bool, output_format: str = "pdf"
+) -> "tuple[str, Optional[str]]":
+    """Like _resolve_output_path(), but never touches the filesystem.
+
+    _resolve_output_path() calls os.makedirs() as a side effect for
+    folder-style -o, which --dry-run must not do. Returns
+    (resolved_output_path, folder_or_None) – folder is set when this
+    is the auto-created-folder case, so the caller can validate it
+    without creating it.
+    """
+    if output_arg is None:
+        return _default_output_path(input_path, output_format), None
+    is_folder = is_batch or output_arg.endswith(("/", "\\")) or os.path.isdir(output_arg)
+    if is_folder:
+        stem = os.path.splitext(os.path.basename(input_path))[0]
+        return os.path.join(output_arg, f"{stem}.{output_format}"), output_arg
+    return output_arg, None
+
+
+def _nearest_existing_dir(path: str) -> str:
+    """Walk up from `path` to the nearest ancestor that already
+    exists. Used to check whether os.makedirs(path) would succeed
+    without actually calling it.
+    """
+    path = os.path.abspath(path)
+    while not os.path.isdir(path):
+        parent = os.path.dirname(path)
+        if parent == path:
+            return path
+        path = parent
+    return path
+
+
+def _check_output_folder_creatable(folder: str) -> None:
+    """Dry-run equivalent of the os.makedirs(exist_ok=True) a real
+    batch run does for folder-style -o: confirms the folder (or its
+    nearest existing ancestor, standing in for what makedirs would
+    need to write into) is writable, without creating anything.
+    """
+    if os.path.exists(folder):
+        if not os.path.isdir(folder):
+            raise OutputPathError(
+                f"The output path points to a file, not a directory: {folder}"
+            )
+        target = folder
+    else:
+        target = _nearest_existing_dir(folder)
+    if os.access(target, os.W_OK) is False:
+        raise OutputPathError(f"Output directory is not writable: {target}")
+
+
+def _dry_run_validate_one(
+    input_path: str, output_path: str, folder: "Optional[str]", output_format: str
+) -> None:
+    """Same checks as validate_all(), fastest first, but uses the
+    dry-run folder check instead of validate_output_path() when the
+    output path is an auto-created batch folder that may not exist
+    yet (validate_output_path() would otherwise reject it for a
+    reason a real run would just fix by creating the folder).
+    """
+    input_abs = validate_input_file(input_path)
+    validate_tesseract_environment()
+    if folder is not None:
+        _check_output_folder_creatable(folder)
+    else:
+        validate_output_path(output_path, expected_ext=f".{output_format}")
+    validate_image_readable(input_abs)
+
+
+def _run_dry_run(
+    expanded_inputs: list[str], args: argparse.Namespace, log
+) -> int:
+    """Validate a batch (files exist/readable, Tesseract reachable,
+    output paths writable) without running OCR or writing anything.
+
+    Non-merge: mirrors the exit-code behavior of the real conversion
+    loop in main() – a single input's failure returns that failure's
+    own exit code immediately, multi-input runs collect every
+    failure and return EXIT_PARTIAL_BATCH if any file failed.
+
+    --merge: mirrors convert_merge(), which combines all pages into
+    ONE output and aborts on the first bad page rather than
+    collecting per-file failures, so dry-run does the same (fail
+    fast on the first bad page, no EXIT_PARTIAL_BATCH here).
+    """
+    is_batch = len(expanded_inputs) > 1
+
+    if args.merge:
+        # main() already rejects args.merge with args.output is None
+        # before _run_dry_run is reached.
+        try:
+            validate_output_path(args.output, expected_ext=".pdf")
+        except ValidationError as exc:
+            log_error(log, f"'--output': {exc}")
+            return _exit_code_for(exc)
+        try:
+            validate_tesseract_environment()
+        except ValidationError as exc:
+            log_error(log, f"'--merge': {exc}")
+            return _exit_code_for(exc)
+
+        for input_path in expanded_inputs:
+            try:
+                input_abs = validate_input_file(input_path)
+                validate_image_readable(input_abs)
+            except ValidationError as exc:
+                log_error(log, f"'{input_path}': {exc}")
+                return _exit_code_for(exc)
+
+        log.info(
+            f"dry-run: {len(expanded_inputs)} file(s) OK for --merge "
+            f"into {args.output}, no output written."
+        )
+        return EXIT_OK
+
+    failures: list[tuple[str, str]] = []
+    last_exit_code = EXIT_OK
+
+    for input_path in expanded_inputs:
+        output_path, folder = _dry_run_resolve_output_path(
+            args.output, input_path, is_batch, args.format
+        )
+        try:
+            _dry_run_validate_one(input_path, output_path, folder, args.format)
+        except Exception as exc:
+            code = _exit_code_for(exc)
+            log_error(log, f"'{input_path}': {exc}")
+            failures.append((input_path, str(exc)))
+            last_exit_code = code
+            if not is_batch:
+                return last_exit_code
+
+    if failures:
+        if is_batch:
+            log_error(
+                log,
+                f"dry-run: {len(failures)}/{len(expanded_inputs)} "
+                f"file(s) failed validation.",
+            )
+            return EXIT_PARTIAL_BATCH
+        return last_exit_code
+
+    log.info(f"dry-run: {len(expanded_inputs)} file(s) OK, no output written.")
+    return EXIT_OK