Search and Region Zoom

pdfvision can find text evidence first, then render only the matching region. This is useful when an agent needs to verify a clause, table cell, figure label, form value, or OCR result without sending a full page image to a vision model.

This is one of the most agent-friendly workflows in pdfvision: use text search as a cheap locator, then switch to visual evidence only where it matters.

Search a PDF

pdfvision report.pdf --search "revenue" --json

Matches are emitted in pages[].matches[]. Each match includes the page number, query, source, text snippet, and a bounding box when pdfvision can locate the visible area.

Markdown output also shows a per-page Search matches table when --search is used. Use JSON, XML, or TOON when a downstream tool needs to consume the coordinates directly.

Add --matches-only for a compact flat report without page bodies. If any selected page has a non-default PDF /UserUnit, the report preserves it as pageUserUnits: [{ page, userUnit }] in JSON/TOON, equivalent <pageUserUnits> entries in XML, and a Page UserUnits summary in Markdown. The metadata is omitted when every selected page uses UserUnit 1.

Compact output still retains optional diagnostics for every selected page with warnings or non-OK native or visual quality, including pages with no hits and searches with zero total results. JSON/TOON expose pageDiagnostics with raw quality and complete warnings; XML and Markdown present the same information in compact diagnostic sections. Inspect it before treating a hit or miss as visible evidence. Native quality describes native text only and does not rule out OCR or field hits. When applicable, unreadableSource keeps document-wide XFA placeholder scope and recovery guidance; rendering a confirmed XFA placeholder only renders the placeholder, so open it in Adobe Acrobat/Reader instead.

Repeat --search to run multiple queries in one pass:

pdfvision paper.pdf --search "transformer" --search "attention" --json

By default, search is literal, case-insensitive, and NFKC-aware. Add regex or exact-case matching only when the task needs it:

pdfvision report.pdf --search "Q[1-4] revenue" --search-regex --json
pdfvision report.pdf --search "PDF" --search-case-sensitive --json

Good search targets include:

• contract clauses and policy terms.
• financial metric labels.
• table row names.
• form values.
• figure captions and chart labels.
• OCR text on scanned pages.
• multilingual terms whose Unicode form may vary.

What Search Covers

Search can match:

• native PDF text.
• text, choice, checkbox, and radio values from --form-fields.
• clickable link targets from --links.
• visible FreeText annotation contents from --annotations.
• OCR text from --ocr, using OCR word boxes when available.

OCR matches that duplicate native, form-field, link, or annotation matches are suppressed so agents do not see the same visible text twice. A link hit is suppressed the same way only when its visible anchor text restates the target, such as a URL printed as itself; a prose anchor that merely shares a word with its target keeps both hits, because the sentence and the target are different evidence.

A native hit's context quotes the line as the page body renders it — which matters most for right-to-left scripts, where the reconstruction supplies the word spacing and bracket direction that the raw match text lacks. The quoted line is used only when it clearly is the match's line (it must cover most of the match box and contain the matched string); a hit stitched across lines, or one the reconstruction assigned elsewhere, falls back to the raw span join the context has always been.

The match source helps the agent decide how much to trust it:

• native: text came from the PDF text layer.
• formField: text came from a visible widget value, display value, or checkbox/radio export value.
• link: text came from a clickable link target.
• annotation: text came from a visible FreeText annotation.
• ocr: text came from page pixels and may need confidence review.

For multi-query searches, queryIndex lets the caller map each hit back to the repeated --search flag that produced it.

Render the Matching Region

Take a match bbox and pass it to --render-region:

pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-output ./crops --json

--render-region requires exactly one selected page. The region uses raw unrotated page-view units with a top-left origin, and it must stay within the page bounds. Physical points = raw value × pages[].userUnit (or 1 when omitted); pixels = raw region × UserUnit × render scale.

Use --render-scale when the crop contains small labels, superscripts, dense table cells, or chart legends:

pdfvision report.pdf --pages 3 --render --render-region 120,180,360,140 --render-scale 3 --render-output ./crops --json

For best crops, add padding around a match bbox before passing it to --render-region. A little surrounding context helps vision models read labels, row headers, and nearby explanatory text.

Agent Workflow

1. Run --search to locate candidate evidence.
2. Inspect pages[].matches[] and choose the bbox with the right source and page.
3. Re-run with --pages, --render, and --render-region for a visual crop.
4. Ask the vision model to compare the crop against the native text, OCR text, or extracted table data.

For visual regions that are not text-searchable, use Rendering and OCR with --visual-regions or --render-visual-regions.

Example: Auditable Claim Check

pdfvision annual-report.pdf --search "Net sales" --search "Operating income" --layout --json

An agent can inspect pages[].matches[], choose the hit with the right page and surrounding context, then request a crop:

pdfvision annual-report.pdf --pages 42 --render --render-region 72,180,468,180 --render-output ./evidence --json

The final answer can cite both extracted text and the rendered evidence region.