Installation#
From PyPI (recommended)#
pip install pagescan
That installs the core package with all Python dependencies. The pre-trained models (~50 MB total) download automatically from Hugging Face Hub on first use and cache under ~/.cache/huggingface/.
Optional system dependency: Tesseract#
For the OCR-based orientation cross-check, install Tesseract:
Ubuntu / Debian:
sudo apt install tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng
macOS:
brew install tesseract
Windows: download from UB-Mannheim’s Tesseract distribution.
Tesseract is optional. Without it, pagescan still works — orientation falls back to a CNN-only heuristic that is slightly less robust on 180° rotations of text-heavy pages.
Optional [ml] extras#
The default detection cascade (YOLO11 + HQ-SAM) needs PyTorch:
pip install "pagescan[ml]"
This pulls in torch and segment-anything-hq. Without [ml], pagescan automatically falls back to the legacy SA24 + LCNet ONNX detection chain (slightly weaker on hard cases, no torch required).
Development install#
Clone the repository and install with the [dev] extras for the test and lint toolchain:
git clone https://github.com/7RPlus-GmbH/pagescan.git
cd pagescan
pip install -e ".[dev,ml,docs]"
Extras group |
Adds |
Use when |
|---|---|---|
|
torch, segment-anything-hq |
Running the YOLO + HQ-SAM cascade |
|
pytest, ruff, mypy |
Running the test suite and quality gates |
|
sphinx, pydata-sphinx-theme, myst-parser, … |
Building this documentation site |
Verifying the install#
python -c "import pagescan; print(pagescan.__version__)"
Where weights are cached#
The cascade weights (yolo_doc_v1.onnx, sam_hq_vit_b.pth, …) live under:
~/.cache/huggingface/hub/models--7rplus--pagescan-weights/
To override the cache location, set HF_HOME or HUGGINGFACE_HUB_CACHE. To override pagescan’s own cache scratch directory for legacy weights, set PAGESCAN_CACHE.