Library API

Three top-level functions cover almost everything: convert() for one file, convert_batch() for many, convert_merge() to combine several images into one PDF. Further down, every lower-level function they're built from, for programs that want to run just one pipeline stage.

Quick start

import scanlayer

result = scanlayer.convert("invoice.jpg", "invoice.pdf")
print(result.words_count, result.mean_confidence)

That's the whole surface most callers need. Everything below is detail on that call, its two siblings, and what's underneath them.

All three, plus configure(), configure_from_file(), get_settings(), and load_config_file(), import straight from the top-level package:

from scanlayer import convert, convert_batch, convert_merge, configure

convert()

def convert(
    input_path: str,
    output_path: Optional[str] = None,
    lang: Optional[str] = None,
    dpi: Optional[int] = None,
    jpeg_quality: Optional[int] = None,
    char_whitelist: Optional[str] = None,
    char_blacklist: Optional[str] = None,
    pdf_metadata: Optional[dict] = None,
    force: bool = False,
    orientation: "str | float | None" = None,
    output_format: str = "pdf",
    debug_image: bool = False,
) -> ConversionResult

Parameters

Orientation modes

orientation controls how the page is straightened before OCR:

• None (default): fully automatic: EXIF orientation tag, then Tesseract's orientation/script detection (OSD) for 0/90/180/270 rotation, then a fine deskew (a few degrees) via minAreaRect on the text pixels.
• "none": disables all of that. No EXIF transpose, no OSD, no deskew. The image is used exactly as loaded.
• a number (int or float, degrees, clockwise positive): skips auto-detection entirely and applies exactly that rotation. Useful for deterministic, reproducible output across a batch of identically-scanned pages.

Return value: ConversionResult

@dataclass
class ConversionResult:
    output_path: str
    words_count: int
    mean_confidence: float
    best_psm: Optional[int]
    early_exited: bool
    pdf_size_bytes: int
    elapsed_ms: float
    language_used: str
    output_format: str = "pdf"
    debug_image_path: Optional[str] = None
    column_count: int = 1

The blank-page gate

Before OCR runs at all, scanlayer checks whether the source image is near-uniform (grayscale standard deviation under config.DESKEW_MIN_STD, 5.0 by default). If it is, convert() raises BlankPageDetectedError instead of quietly producing an empty PDF, since a blank page is usually unexpected (wrong file, a scanner that fired on nothing).

try:
    result = scanlayer.convert("maybe_blank.jpg", "out.pdf")
except scanlayer.utils.errors.BlankPageDetectedError:
    result = scanlayer.convert("maybe_blank.jpg", "out.pdf", force=True)

convert_batch()

def convert_batch(
    inputs: "str | list[str]",
    output: Optional[str] = None,
    *,
    merge: bool = False,
    lang: Optional[str] = None,
    dpi: Optional[int] = None,
    jpeg_quality: Optional[int] = None,
    char_whitelist: Optional[str] = None,
    char_blacklist: Optional[str] = None,
    pdf_metadata: Optional[dict] = None,
    force: bool = False,
    orientation: "str | float | None" = None,
    output_format: str = "pdf",
    debug_image: bool = False,
    verbose: bool = False,
    quiet: bool = False,
) -> BatchResult

• inputs accepts a single pattern/path or a list, mixed extensions welcome: ["*.png", "*.jpg", "*.pdf", "specific.tiff"]. Each entry is glob-expanded; a literal path that doesn't match a glob passes through and is left for convert() to raise on if it doesn't exist. Any .pdf input is rasterized to one image per page first.
• output is a folder (created if it doesn't exist): one output file per input, named after the input's stem plus the output_format extension. If omitted, each output file is written next to its own input instead, same stem and extension rule, no shared folder needed. With merge=True, output is instead a single file path for the combined PDF, and output_format must stay "pdf"; output is required in that case, since there is no single input to derive a shared name from.
• Every other keyword argument is the same as convert(), applied to every file.
• verbose/quiet set the log level for the whole call, equivalent to configure(log_level="DEBUG"/"ERROR"). Mutually exclusive: passing both raises ValueError.

result = scanlayer.convert_batch(
    ["*.png", "*.jpg", "*.pdf"], "./converted/",
    lang="fra", force=True, quiet=True,
)
print(f"{result.succeeded} ok, {result.failed} failed")
for path, err in result.failures:
    print(f"  {path}: {err}")

Return value: BatchResult

@dataclass
class BatchResult:
    results: list[ConversionResult]
    failures: list[tuple[str, str]]

    @property
    def succeeded(self) -> int: ...
    @property
    def failed(self) -> int: ...
    @property
    def ok(self) -> bool: ...   # True if failures is empty

convert_merge()

def convert_merge(
    input_paths: list[str],
    output_path: str,
    lang: Optional[str] = None,
    dpi: Optional[int] = None,
    jpeg_quality: Optional[int] = None,
    char_whitelist: Optional[str] = None,
    char_blacklist: Optional[str] = None,
    pdf_metadata: Optional[dict] = None,
    force: bool = False,
    orientation: "str | float | None" = None,
) -> ConversionResult

Combines several source images into one multi-page searchable PDF, in argument order. PDF-only: there's no sensible schema for merging into txt/json/tsv/hocr; use convert() once per page, or a plain convert_batch() run without merge=True, if you need one of those formats for a multi-page source.

result = scanlayer.convert_merge(["a.jpg", "b.jpg", "c.jpg"], "combined.pdf")
print(result.words_count, "words across", result.column_count, "max columns")

Raises BlankPageDetectedError if any page is blank and force=False, checked per page. In the returned ConversionResult, best_psm is always None (no single meaningful PSM across a multi-page merge), and mean_confidence is word-count-weighted across every page.

Exceptions

from scanlayer.utils.validators import ValidationError
from scanlayer.utils.errors import PipelineError

try:
    result = scanlayer.convert("invoice.jpg", "invoice.pdf")
except ValidationError as exc:
    print(f"Bad input or environment: {exc}")
except PipelineError as exc:
    print(f"Conversion failed mid-run: {exc}")

Low-level API

Everything above wraps a fixed pipeline: validate, preprocess, OCR, order columns, build output. Most programs should stay at that level. The functions below are what convert() calls internally, exposed for programs that want to run just one stage.

image path
    |
    v
validators.validate_all()              (file exists, Tesseract found, output path OK)
    |
    v
preprocessing.enhance.preprocess()     -> PreprocessResult (background + ocr_image)
    |
    v
ocr.engine.extract_words()             -> OcrResult (Word list + stats)
    |
    v
layout.columns.reorder_reading_order() -> reordered Word list, column count
    |
    v
pdf.builder.build_searchable_pdf()     -> PDF on disk
  or
ocr.export.export_words()              -> txt / json / tsv / hocr string

preprocessing.enhance.preprocess()

from scanlayer.preprocessing.enhance import preprocess

result = preprocess(image, dpi=300, orientation=None)

Takes a PIL Image and returns a PreprocessResult:

ocr.engine.extract_words()

from scanlayer.ocr.engine import extract_words

ocr_result = extract_words(
    result.ocr_image, result.ocr_scale,
    effective_dpi=result.effective_dpi, lang="eng",
)

Runs Tesseract across config.TESSERACT_PSM_CANDIDATES ([3, 4, 6, 11] by default), in parallel threads by default, and keeps the candidate with the highest mean confidence. Stops early once a candidate clears config.PSM_EARLY_EXIT_CONFIDENCE (80% by default).

@dataclass
class Word:
    text: str
    x: float            # top-left corner, background image coordinates (pixels)
    y: float
    width: float
    height: float
    confidence: float
    line_id: int = -1   # combined block/paragraph/line index from Tesseract

layout.columns.reorder_reading_order()

from scanlayer.layout.columns import reorder_reading_order

ordered_words, column_count = reorder_reading_order(
    ocr_result.words, page_width=result.background.width,
)

Re-derives left-to-right, top-to-bottom reading order for genuine multi-column pages geometrically (from word positions), rather than trusting Tesseract's own block/line numbering, which frequently interleaves columns line by line. Tuned for prose-style layouts (articles, letters, reports), not tables: an invoice's line-item table has narrow per-row gutters that don't look like a page-wide column break, so this deliberately won't touch it.

Returns the words unchanged (and column_count=1) if config.MULTI_COLUMN_DETECTION is False, there isn't enough text to detect columns confidently, no gutter wide enough to trust is found, or the reorder would drop or duplicate a word (a safety fallback).

This is the same function convert() and convert_merge() call internally, before both PDF drawing and text export.

ocr.export: format-specific exporters

from scanlayer.ocr.export import to_text, to_json, to_tsv, to_hocr, export_words, FORMATS

pdf.builder: building a PDF from words you already have

from scanlayer.pdf.builder import build_searchable_pdf, build_searchable_pdf_multipage, PageInput

build_searchable_pdf(background, words, output_path, dpi, jpeg_quality=None, metadata=None, lang=None) -> int, builds a single-page searchable PDF: draws background as the page image, then overlays each Word as invisible text (PDF render mode 3), horizontally stretched to match its detected bounding box. Returns the written file's size in bytes. Raises PDFBuildError on a write failure.

build_searchable_pdf_multipage(pages, output_path, jpeg_quality=None, metadata=None) -> int, the same thing for several already-preprocessed-and-OCR'd pages, combined into one document:

@dataclass
class PageInput:
    background: Image.Image
    words: list[Word]
    dpi: int
    lang: Optional[str] = None

Each page can have different pixel dimensions, DPI, and OCR language (useful for a batch-scanned mixed-language document). metadata applies to the document as a whole. Raises PDFBuildError if pages is empty.

Validators, called directly

from scanlayer.utils.validators import (
    validate_all, validate_input_file, validate_output_path,
    validate_tesseract_environment, validate_image_readable,
)

convert() calls validate_all(input_path, output_path, output_format) up front, which runs, in order: validate_input_file (exists, readable, recognized extension, non-empty), validate_tesseract_environment (binary found and executable, tessdata_dir sane if configured), validate_output_path (parent directory exists and is writable), then validate_image_readable (Pillow can actually open it). Each is callable on its own, useful for pre-flighting a batch of files before running any OCR, to report every bad file up front instead of one at a time as the batch runs.

Full exception hierarchy

ValidationError (scanlayer.utils.validators)
├── InputFileError
├── OutputPathError
├── TesseractEnvironmentError
└── DependencyError

PipelineError (scanlayer.utils.errors)
├── OCRProcessingError
├── PDFBuildError
└── BlankPageDetectedError

ValidationError subclasses mean a precondition failed before any real work started. PipelineError subclasses mean a stage began and failed partway through, for an operational reason, not a bug. The CLI maps each one to a specific exit code, see CLI Reference.

utils.debug_image.build_debug_image()

from scanlayer.utils.debug_image import build_debug_image

overlay = build_debug_image(
    image,
    words,               # list of ocr.engine.Word
    best_psm=3,
    mean_confidence=92.4,
    language_used="fra+eng",
    exif_orientation=1,
    gross_rotation=0,
    rotation_note="",
)

Returns a new PIL image: a copy of image with per-word bounding boxes, each word’s confidence drawn above it (colored green/orange/red by threshold), and a run-summary header banner at the top. The input image is not modified. words expects the Word objects produced by extract_words() (each exposing x, y, width, height, and confidence). This is the function behind Debug Visualization and the --debug-image flag.

pdf.fonts.resolve_font()

from scanlayer.pdf.fonts import resolve_font

font_name = resolve_font("fra+eng")   # -> str, a registered reportlab font name

Returns the reportlab font name used for the invisible PDF text layer. If config.FONT_PATH is set it registers and returns that TTF, otherwise it auto-selects: a CJK CID font (chi_sim, chi_tra, jpn, kor), the bundled DejaVu Sans for Latin/Cyrillic/Greek/Vietnamese, or a Helvetica fallback. Fonts are registered once and reused, and a failed registration falls back gracefully instead of raising.

Putting the low-level pieces together

Roughly what convert() does internally, written out explicitly. A starting point if you need to insert your own step in the middle, see also Examples → Advanced.

from PIL import Image
from scanlayer.utils.validators import validate_all
from scanlayer.preprocessing.enhance import preprocess
from scanlayer.ocr.engine import extract_words
from scanlayer.layout.columns import reorder_reading_order
from scanlayer.pdf.builder import build_searchable_pdf
from scanlayer.utils.errors import BlankPageDetectedError

input_abs, output_abs = validate_all("invoice.jpg", "invoice.pdf", "pdf")

with Image.open(input_abs) as img:
    image = img.copy()

result = preprocess(image, dpi=300, orientation=None)

if result.likely_blank:
    raise BlankPageDetectedError("page looks blank, pass force logic here if needed")

ocr_result = extract_words(
    result.ocr_image, result.ocr_scale,
    effective_dpi=result.effective_dpi, lang="fra+eng",
)

words, column_count = reorder_reading_order(
    ocr_result.words, page_width=result.background.width,
)

build_searchable_pdf(result.background, words, output_abs, dpi=300)

For anything that doesn't need this level of control, scanlayer.convert() does all of the above, plus validation edge cases, logging, and blank-page/force logic, in one call.