Troubleshooting#

Common issues, their root causes, and how to fix them. If your problem isn’t listed here, please open an issue with a minimal reproducer and (if possible) the input photo.

Installation#

ImportError: cannot import name 'sam_model_registry' from 'segment_anything_hq'#

The [ml] extras aren’t installed. pagescan still works without them — it falls back to the legacy ML chain. To enable the production cascade:

pip install "pagescan[ml]"

ModuleNotFoundError: No module named 'torch'#

Same root cause as above. The cascade requires PyTorch. If you don’t want the torch dependency, accept the fallback to the legacy chain — pagescan auto-detects.

pytesseract.TesseractNotFoundError: tesseract is not installed#

The Tesseract binary isn’t on PATH. pagescan only needs it for the orientation cross-check; without it, orientation falls back to a CNN-only heuristic that’s slightly weaker on 180° rotations.

To install (see Installation for OS-specific commands):

sudo apt install tesseract-ocr   # Linux
brew install tesseract           # macOS

Detection#

“It cropped off part of my document”#

This is the single most reported issue. Pagescan has an over-crop guard (min_doc_coverage, default 0.05) but the default may be too permissive for your distribution.

Raise the floor:

from pagescan import ScanConfig, scan
scan("photo.jpg", "out.pdf", config=ScanConfig(min_doc_coverage=0.15))

If the document still gets cropped, run with debug=True and inspect debug/corners.jpg to see what the model predicted:

ScanConfig(debug=True, debug_dir="./debug/")

“It detected the document but rotated it wrong”#

The orientation classifier got confused — usually because:

  1. The page has very little text (e.g. a form, a diagram).

  2. The page is in a language not in auto_orient’s OCR cross-check.

Disable auto-orient and rotate manually:

ScanConfig(auto_orient=False)

Or supply the right Tesseract language data with TESSDATA_PREFIX set to a directory containing deu.traineddata, fra.traineddata, etc.

“ML detection failed, falling back to contour”#

You’ll see log output like:

Detection: conservative

Causes:

  1. First-run download failed — check network access to huggingface.co. The first scan needs to fetch ~50 MB (and the 362 MB HQ-SAM checkpoint if [ml] is installed).

  2. YOLO confidence below threshold — the document is small, partially out of frame, or shot at an extreme angle. Lower detector_conf_threshold:

    ScanConfig(detector_conf_threshold=0.10)

  3. Validation guard rejected the quad — coverage, dimension, or parallelism failed. Bump min_doc_coverage down (carefully) or inspect with debug=True.

The conservative contour fallback is the safety net — it produces a reasonable result on most images even when ML fails, just with looser corner accuracy.

Output#

“PDF is way too big”#

Lower the JPEG quality:

ScanConfig(jpeg_quality=30)   # default is 50

A typical A4 scan at quality 30 is ~150 KB; at 50, ~250 KB; at 80, ~800 KB.

“Output is too small / too big on the page”#

Adjust the canvas dimensions and the margin:

ScanConfig(
    output_width=2480, output_height=3508,   # A4 @ 300 DPI (default)
    output_margin=100,                       # tighter margin = bigger document
)

“Output has weird colours / looks oversaturated”#

Disable enhancement entirely:

from pagescan import PRESET_RAW, scan
scan("photo.jpg", "out.pdf", config=PRESET_RAW)

Or selectively disable individual stages:

ScanConfig(white_balance=False, shadow_removal=False, enhance=False)

Performance#

“First scan takes 30+ seconds”#

One-time weight download:

  • YOLO ONNX: ~11 MB

  • HQ-SAM ViT-B: ~362 MB

After that, weights are cached under ~/.cache/huggingface/hub/ and load instantly. Pre-warm in CI or build steps:

from pagescan.detector import _ensure_model as ensure_detector
from pagescan.segmenter import _ensure_model as ensure_sam
ensure_detector()
ensure_sam()

“Each scan still takes 5+ seconds with the cascade”#

That’s expected for the v1 cascade on CPU. HQ-SAM ViT-B inference dominates. Options:

  1. Use the legacy chain — ScanConfig(use_cascade=False) runs at ~70 ms/image.

  2. Use the fast preset — PRESET_FAST skips ML entirely, ~30 ms/image.

  3. GPU — install a CUDA-enabled torch; HQ-SAM will use it automatically and drop to ~150 ms/image.

“Tests are slow / hanging”#

The default test suite uses use_ml=False and shouldn’t take more than 5 seconds total. If yours is slow, you likely have stale cached state or a debug log redirected to disk — clear pagescan_debug/ and ~/.cache/pagescan/.

Where to get help#

  • Read the API reference.

  • Search existing issues.

  • Open a new issue with: pagescan version, Python version, OS, a minimal reproducer, and the input photo (if you can share it) or a description of the document type and shooting conditions.