FAQ

Is pdfvision a PDF-to-text tool or a vision tool?

It is both, but the main idea is evidence. pdfvision extracts native text when it is available, then exposes layout, image/vector geometry, warnings, rendered images, OCR, search matches, and PDF feature metadata so an agent can decide whether text alone is enough.

Why is the extracted text empty?

The PDF may be scanned, image-heavy, encrypted, or built from custom glyph encodings. Check the overview fields and pages[].warnings, then retry with --render, --ocr, or --layout.

If the page has empty_but_visual_content, render or OCR it. If it has glyph warnings, compare the rendered page or OCR before trusting native text.

When should I use --layout?

Use it when the page has columns, tables, forms, footnotes, repeated headers or footers, vertical CJK text, or any content where placement changes meaning.

--layout is especially useful for papers, reports, financial statements, forms, and slide exports where the raw text stream can be visually out of order.

When should I use OCR?

Use --ocr when native text is missing, sparse, scan-like, or visibly different from the rendered page.

OCR is added beside native text; it does not replace it. Agents should compare native text, OCR text, confidence, and warnings.

When should I render a region instead of a whole page?

Use --render-region after search, layout, image boxes, vector boxes, or visual regions identify the area that matters. Cropping is better than full-page rendering when a model only needs to verify one clause, table cell, chart label, form value, or figure.

What are visual regions?

Visual regions are crop-ready page areas that likely contain a meaningful figure, chart, table, form section, annotation, diagram, or raster/vector cluster. They help agents discover where to look before sending images to a vision model.

Can pdfvision search PDFs?

Yes. --search emits pages[].matches[] with page, source, matched text, context, and bounding boxes when available. Search can cover native text, visible form-field values, clickable link targets, FreeText annotations, and OCR output when OCR is enabled.

What coordinate system does pdfvision use?

Boxes use raw unrotated pdf.js page-view units, with a top-left origin. The visible box is CropBox ∩ MediaBox when applicable, otherwise MediaBox. x grows right and y grows downward. Physical points = raw value × pages[].userUnit (or 1 when omitted); pixels = raw region × UserUnit × render scale. Bboxes pass unchanged to --render-region; rotated pages use the rotated pdf.js viewport transform.

Where does the cache live?

Results are cached under the operating system temp directory. Set PDFVISION_CACHE_DIR to a nonblank absolute path naming a dedicated directory; relative paths, ~, filesystem roots, home, the working directory, and shared temporary roots are refused. An owned .pdfvision-cache-root marker authorizes recursive clearing. Clear never adopts an unmarked custom root; with no override, it may adopt the active historical default only after recognized legacy-shape scans before and after hardening. On POSIX, group/other-writable unmarked roots are refused and ancestors must be readable/openable, current-user/root-owned, and non-writable-or-safely-sticky. After quarantine rename, st_dev mismatches refuse recursive removal, although the original pathname has moved; same-device bind mounts are not detected. Checks resist replacement under conventional POSIX mode semantics, but do not inspect ACL/network-filesystem permissions or exclude later root/same-UID replacement. Windows replacement resistance is best effort. Clearing is not coordinated with active OCR; retry an interrupted run. Use --no-cache to skip extraction and remote PDF caches; OCR support files still persist under the validated cache root.

How should I pass PDF passwords?

Prefer --password-stdin so the password does not appear in process arguments:

printf "your-password\n" | pdfvision encrypted.pdf --password-stdin --format json

Which output format should I use?

Use Markdown for a quick human-readable pass, JSON for tools and agent controllers, and XML for consumers or prompts built around explicit tags. Consider TOON when arrays of objects with identical scalar fields dominate, then compare the formats on your own documents and in the target model context.