Guide

Highlight extracted PDF fields using source bounding boxes

All guides

A source highlight connects a field in an extracted object to a region on a document page. To draw it correctly, use the anchor’s page number, corner coordinates and page dimensions, then scale that rectangle to the displayed page. The highlight should help a reviewer inspect the answer and its surrounding labels.

An attached citation is not proof that the requested field is correct. For example, a subtotal may be visibly located on the page while still being the wrong answer for invoice total. This guide keeps geometry and grounding status separate, with a downloadable function for an uncropped page in the same orientation as the anchor.

Read the field pointer and grounding state first

Look up a field in result.fields, for example /total or /line_items/0/amount. Pointers identify leaves in the response, not text-search terms. An anchor contains a one-based page, bbox, page_dims and snippet; absent metadata should produce an explicit unavailable state in your interface.

The API distinguishes three grounding states. Show a text label as well as color so a reviewer can tell them apart. Preserve the original value, field state, confidence and conflict flag alongside this source view. A missing or null field needs an explanation rather than a rectangle suggesting that a value was found.

Read the field pointer and grounding state first
GroundingMeaningReview interface
verifiedThe value itself was located inside the cited region.Label “Value located in source”; inspect whether the surrounding context matches the requested field.
citedA citation is attached, but the value was not confirmed there.Label “Citation; value unconfirmed”; keep the distinction visible.
ungroundedNo accepted source span.Show “No confirmed source location”; allow manual page navigation.

Convert corner coordinates into a display rectangle

Velrim anchors use a top-left origin. bbox is [x0, y0, x1, y1], not [x, y, width, height], and coordinates are in the units of page_dims. Compute width as x1 − x0 and height as y1 − y0. Multiply horizontal coordinates by displayed width divided by page width; apply the corresponding height scale vertically.

For a synthetic 600 × 800 page and box [100, 200, 300, 240], a 300 × 400 display produces left 50, top 100, width 100 and height 20 CSS pixels. The helper returns null for the wrong page, unusable geometry, unavailable grounding or a materially different aspect ratio. Download source-highlight.ts.

source-highlight.ts
import type { ResponseField } from '@velrim/sdk';
/** Scale a top-left anchor onto an uncropped page with matching orientation. */
export function sourceHighlight(field: ResponseField, page: number, width: number, height: number) {
const anchor = field.anchor;
if (
field.state !== 'present' ||
!anchor ||
anchor.page !== page ||
!Number.isInteger(page) ||
page < 1 ||
field.grounding === 'ungrounded' ||
(field.grounding !== 'verified' && field.grounding !== 'cited')
)
return null;
const { width: pw, height: ph } = anchor.page_dims;
const [x0, y0, x1, y1] = anchor.bbox;
if (
![width, height, pw, ph, x0, y0, x1, y1].every(Number.isFinite) ||
Math.min(width, height, pw, ph) <= 0 ||
x0 < 0 ||
y0 < 0 ||
x1 <= x0 ||
y1 <= y0 ||
x1 > pw ||
y1 > ph
)
return null;
// A mismatch usually means letterboxing, a crop, or an orientation change.
if (Math.abs(width / height / (pw / ph) - 1) > 0.01) return null;
return {
left: (x0 * width) / pw,
top: (y0 * height) / ph,
width: ((x1 - x0) * width) / pw,
height: ((y1 - y0) * height) / ph,
label:
field.grounding === 'verified' ? 'Value located in source' : 'Citation; value unconfirmed',
};
}

Run the geometry example without a PDF or API key

Save source-highlight.ts in a TypeScript project with npm install @velrim/sdk and npm install --save-dev tsx. Save the caller below as demo-highlight.ts, then run npx tsx demo-highlight.ts. It uses a synthetic anchor and prints the 50/100/100/20 rectangle from the calculation above. No network request or PDF rendering occurs.

demo-highlight.ts
import { sourceHighlight } from './source-highlight';
console.log(sourceHighlight({
state: 'present', value: '125.00', reason: null, grounding: 'cited',
anchor: { page: 1, bbox: [100, 200, 300, 240], snippet: '125.00',
page_dims: { width: 600, height: 800 } },
}, 1, 300, 400));

Place the overlay on the page, then handle zoom

Use a relatively positioned wrapper that exactly matches the displayed page content. Place an absolutely positioned overlay inside it using the returned left, top, width and height in pixels. The wrapper must exclude viewer toolbars, margins and letterboxing. Recompute after page resize or zoom, for example with a ResizeObserver. If the page is lazy-loaded, wait until its display dimensions are known.

Use CSS display pixels for the overlay, not the canvas backing-store dimensions. A high-DPI canvas may have twice as many backing pixels as CSS pixels. Mozilla’s PDF.js rendering example shows that distinction and explains viewport scale and rotation. PDF.js also transforms raw PDF coordinates from a bottom-left origin; do not apply a second origin flip to these already top-left anchors.

The helper does not transform crops or rotations. Matching aspect ratios cannot detect a 180-degree rotation. If the viewer rotates or crops a page, apply the same known transform to all four anchor corners and take their display bounds, or show the unrotated full page for review. Validate on representative rotated and cropped documents before enabling that path.

Make source inspection usable without relying on the box

Keep a keyboard-accessible “View source” control next to each field. Move to the anchor’s page and provide a visible status label and snippet as text. Render snippets with your framework’s normal text escaping, never as HTML. A passive highlight can use pointer-events: none so it does not block page selection.

Test first and last pages, narrow layouts, zoom, high-DPI displays, absent anchors, invalid dimensions and each grounding state. If geometry cannot be displayed, say that the source location is unavailable in this view; do not silently replace it with a fabricated box. This example’s numeric tests establish the coordinate conversion, not the visual accuracy of every PDF renderer.

Use this alongside the invoice CSV example or n8n review routing. The response reference defines the envelope; /reliability describes confidence evidence and its document-class limits.

Written by Velrim.