Docs / Guides

Debug Visualization

A read-only diagnostic overlay showing exactly what OCR detected and how confident it was, the fastest way to tell whether a bad result is an OCR problem or something downstream.

Basics

bash

scanlayer invoice.jpg -o invoice.pdf --debug-image
# also produces invoice_debug.png

# -o is optional: without it, both files land next to the input
scanlayer invoice.jpg --debug-image
# writes invoice.pdf and invoice_debug.png

pythondebug_overlay.py

result = scanlayer.convert("invoice.jpg", "invoice.pdf", debug_image=True)
print(result.debug_image_path)

# output_path is optional too
result = scanlayer.convert("invoice.jpg", debug_image=True)
print(result.output_path, result.debug_image_path)

Saves an extra <output-stem>_debug.png next to the requested output, no matter which --format was used. It is a copy of the source image with the OCR result drawn on top; it never changes the actual output.

What's on it

A box around every word that made it into the output, colored by Tesseract confidence:

Color	Confidence	Meaning
Green	80 or above	High confidence, trust this text.
Amber / orange	50 to 79	Medium, usually correct, worth a skim for amounts, names, dates.
Red	`--min-confidence` (35 by default) up to 49	Low but kept, probably right, verify before relying on it.

A missing word is not always an OCR miss A word that fell below --min-confidence does not appear at all: it was detected and then discarded as noise. If an expected word is missing, rerun with a lower --min-confidence to see it appear (red box) and judge for yourself.

Also included: the confidence number printed above each box, and a header band with the PSM used, total word count, mean confidence, language(s), and the orientation correction actually applied.

When to reach for it

Output text looks wrong: is it an OCR problem (bad boxes) or something downstream?
A word is missing: never detected, or detected and dropped below --min-confidence?
Tuning --min-confidence / --lang / --orientation for a batch of similar documents.
The page seems mis-rotated: the header line shows exactly what correction was applied.