Scan Areas

Scan Areas let you draw regions on a form template image and configure each region with its own AI processing pipeline. Instead of full-page text extraction, each area is cropped and processed independently through one or more providers in sequence.

What Are Scan Areas?

A Scan Area is a rectangular region on your template image with:

A bounding box — the region to crop from the image
A prompt — instructions for what to extract or process
A provider pipeline — one or more AI providers that process the region in sequence
Optional vocabulary — value sets that constrain and guide the output

Think of it as "a region on the image with its own AI recipe." You can chain multiple providers: for example, Vizion extracts raw text, then GPT-4o cleans and structures it.

Accessing the Editor

Open a Form Template
Click the Scan Areas tab (or navigate to /form_templates/:id/scan_areas/edit)
The editor shows the template image with any existing scan areas overlaid

Drawing a Scan Area

Click Add Area or use the draw tool
Click and drag on the template image to define the region
The area appears as a colored rectangle with a name label
Drag corners or edges to resize; drag the center to move

Multi-Page Templates

For templates with multiple pages:

Use the page selector to switch between pages
Each scan area is automatically associated with the page it was drawn on
Areas only appear on their respective page
When executing, each area processes the image from its own page

Configuring a Scan Area

Select a scan area to open its configuration panel:

Field	Description
Name	A label for the area (e.g., "Invoice Total", "Header Block")
Prompt	Instructions sent to the AI provider, as plain text.
Prompt Mode	`plain` (raw text prompt) — `script` is reserved and currently treated as plain
Additional Context	Extra context prepended to every step's prompt (e.g., document type, expected format)
Providers	Ordered list of AI providers to process the region (see Pipeline section)
Vocabulary	Value sets that constrain output (e.g., valid city names, product codes)

Anchors: Keeping an Area on Target

You draw a scan area on the template, but it reads from the document you upload. If that document was printed or scanned even slightly offset, the area lands next to the content instead of on it — and you get an empty or wrong result.

An anchor fixes this. It is a small, visually distinctive mark you draw near the area — a printed label, a symbol, the corner of a box. When the document is read, Nocarta finds that mark on the uploaded image and moves the area by exactly the same distance the mark moved.

Adding an Anchor

Select the scan area and open Configure Area
Expand Anchor & Repositioning
Click Draw anchor, then drag a box around a distinctive mark near the area
Pick the Adjustment: Move only keeps the area's original size, Move and resize also scales it if the mark itself changed size
Optionally raise or lower the Minimum confidence (default 0.7)

The anchor appears as a dashed box with an anchor label, so you can always see which mark an area is pinned to. Clear anchor removes it.

Choosing a Good Mark

Do pick something with clear shapes, lines or text: a field label, a logo, a table corner, a bordered box
Do pick something unique on the page — if the same mark appears three times, a single anchor may pin to the wrong one
Don't pick blank paper or a plain stretch of background: with no detail there is nothing to recognise, and Nocarta will ask you to draw a different mark
Draw it big enough — very small marks cannot be found reliably, and you will be told so immediately

If the mark is not found, or is found with less confidence than your minimum, the area simply reads at its original position. Extraction is never blocked, and the result records that the anchor was not matched, together with the confidence, so you can see exactly what happened.

Border Guide Lines

Some tables have no printed rules at all, or rules so faint a scan loses them. Without lines to follow, a reader has to guess where one column ends and the next begins — which is where day-by-day grids go wrong. Border guide lines let you draw those lines yourself: Nocarta paints them onto the cropped region before the text is read.

You mark points on the area's own borders. A point on the left border becomes a horizontal line running left to right; a point on the top border becomes a vertical line running top to bottom.

Adding Lines

Select the area and open Configure Area
Expand Border guide lines
Tick Draw these lines on the crop
Click Add row line, then click the area's left border wherever a horizontal line belongs. Keep clicking to add more; press the button again to stop
Click Add column line and do the same along the top border
Save

Each line is listed with its position as a percentage and a Remove link, and Clear lines removes them all. The lines appear on the canvas as you add them, and Preview Crop shows exactly what the reader will receive.

Colour and Thickness

Lines are black and 2 px by default. Both are configurable — pick a colour that contrasts with the document, and note that 1 px can disappear when the crop is scaled down, which is why the default is 2. Thickness goes up to 8.

They Follow the Area

Positions are stored relative to the area itself, not to the page. If the area also has an anchor and moves to track a shifted document, the lines move with it and stay on the same rows and columns. That also means resizing the area keeps the lines proportionally in place — check them afterwards, since a resize changes what each percentage points at.

Do put a line between columns, not through the digits — a line drawn over a value hides it
Do use Preview Crop to confirm placement before running the pipeline
At most 40 lines per direction

Repeating Areas

Some documents repeat the same row a different number of times — three line items on one invoice, eleven on the next. Set Occurrences to Repeating in the Anchor section and the area stops being a single region: every occurrence of its anchor mark is located on the uploaded document, and the pipeline runs once per occurrence.

Each occurrence produces its own result, in reading order (top to bottom, left to right)
If the area fills a form field, the results are combined into it, one per line
If nothing is found, the run is still recorded so "no repeats found" is visible rather than silent

Because the marks repeat by definition, choose one that is distinctive against the rest of the page — the row label, not the plain ruling line.

Find Repeating Marks

The toolbar's Find Repeating Marks button creates many areas at once, at design time:

Click Find Repeating Marks
Drag a box around one of the repeating marks
Every occurrence is highlighted with a dashed box and a match percentage, so you can confirm the count before creating anything
Drag the region you actually want to read, next to the first highlighted mark
That same offset is applied to every occurrence: you get one scan area per mark, each already anchored to its own
Adjust names or prompts as needed, then Save

Nothing is saved until you click Save, so you can try a different mark freely.

Provider Pipeline

Each scan area can have multiple providers that run in sequence. The output of one step can be passed to the next.

Available Providers

Provider	Type	Best For
Vizion	Built-in text extraction	General text extraction from images
St0rm	Built-in Vision	Complex layouts, handwriting, tables
B3ast	Built-in Document AI	Structured document parsing (tables, sections)
LLM Config	User-configured	Any provider you've set up (OpenAI, Anthropic, Gemini, Ollama, etc.)

Step Roles

Role	Receives Image?	Receives Previous Output?	Typical Use
Extract	Yes	No	First step — read text from the image
Refine	Optional	Yes	Clean, format, or restructure extracted text
Validate	Optional	Yes	Check extracted data against rules
Transform	No	Yes	Convert output to a different format

Example Pipelines

Pattern	Steps	Use Case
Single provider	Vizion (extract)	Simple text extraction
Extract + Refine	Vizion (extract) → GPT-4o (refine)	Text extraction reads the raw content, LLM cleans it
Extract + Validate	St0rm (extract) → LLM (validate)	Vision reads image, LLM checks accuracy
Full pipeline	B3ast (extract) → Vizion (extract) → GPT-4o (refine)	Structure + text extraction, then merge

Try Pipeline

Before saving, you can test your pipeline configuration live:

Configure the scan area's providers and prompt
Click Try Pipeline
The pipeline executes asynchronously and streams results step-by-step
Each step shows: provider name, role, extracted text, confidence score, and duration
Errors are shown inline with the failing step highlighted

You can test against:

Template image — the original form template image
Instance image — a filled-in form instance image (select an instance)

LLM Config Steps That Run on Your Desktop

An LLM Config step bound to a configuration that only your machine can reach — a localhost Ollama / local vLLM, or a cloud key protected by your vault's master password — does not run on Nocarta's servers. Instead:

The step shows "Queued — waiting for your desktop" and the job enters a durable queue
Nocarta Desktop picks it up (immediately if open, or after you confirm the queued backlog at app open), runs the interpretation against your LLM, and the result streams back into the editor or the instance — bulk fills work the same way, one job per instance
If your LLM fails, you see the real reason (rate limit, endpoint down, rejected key) — and the step can optionally retry on Nocarta AI if the configuration enables fallback
You can watch or cancel queued jobs from Settings → Preferences → LLM Configuration on any device

The scan area result page records who interpreted it — your LLM (and whether it ran on your desktop) or Nocarta AI — so results are always auditable. Cloud configurations with server-readable (Tier 1) keys skip the queue entirely: Nocarta's servers call your endpoint directly with the extracted text. See AI Assistant & LLM Configuration for the full routing rules.

Vocabulary (Output Constraints)

Attach Value Sets to a scan area to constrain the AI output. The vocabulary is compiled into the prompt so the provider knows which values are valid.

Example: If a scan area reads a "City" field, attach a value set containing valid city names. The AI will prefer matching entries from the list rather than inventing values.

Settings

Setting	Description
Enabled	Whether this scan area runs during batch execution
Stop on error	Halt the pipeline if any step fails (default: true)
Output format	`text`, `json`, or `field_mapping`
Target fields	Form fields to fill with the scan area's output (for field_mapping mode)

Prompt Assembly

Each step's final prompt is built in this order:

Additional context (if set)
Vocabulary (compiled from attached value sets)
Previous step output (for refine/validate/transform roles)
Prompt text (the scan area's prompt or a per-step override)

If no prompt is provided, the default is: "Extract ALL text from this image region. Return the text exactly as it appears."

Execution Flow

When a scan area pipeline runs:

The template/instance image is loaded
The bounding region is cropped from the image
Each provider step executes in order:
- The prompt is assembled with context, vocabulary, and previous output
- The provider processes the cropped image + prompt
- The result (text + confidence) is recorded
- Progress is broadcast via ActionCable for real-time UI updates
The final result is the output of the last step