pdf_ocr_vlm library

A pluggable OCR engine for dart_pdf_editor backed by a vision-language-model (VLM) OCR service.

Implements PdfOcrEngine so PdfEditor.applyOcr can turn a scanned, image-only page into one whose text can be selected, searched, copied, and extracted - without changing how the page looks.

Point VlmOcrEngine at a self-hosted state-of-the-art OCR model (see VlmOcrEngine.dotsOcr) or any HTTP service you wrap to the documented JSON contract.

Classes

VlmOcrEngine

A PdfOcrEngine that recognizes a page by POSTing its raster to an HTTP OCR service and mapping the returned boxes back into PDF user space.

VlmOcrInput

The rasterized page handed to a request builder. The page has already been rendered to a PNG (imageBase64 / imageDataUrl); the builder turns it into whatever JSON the target service expects.

VlmOcrWord

A single recognized fragment, positioned in raster pixels (top-left origin, y down - the natural output of an OCR model run on the PNG the engine sent). VlmOcrEngine converts these to PDF user space via PdfOcrPageImage.userSpaceRect.

Constants

dotsOcrLayoutPrompt → const String

The layout-parsing instruction dots.ocr is trained on: emit a JSON array of cells in reading order, each with a pixel bbox, a category, and the cell text.

dotsOcrTextCategories → const Set<String>

dots.ocr layout categories that carry plain, selectable text. Picture (no text), Table (text is HTML markup), and Formula (LaTeX) are left out by default; pass your own set to VlmOcrEngine.dotsOcr to include them.

Functions

defaultVlmRequestBody(VlmOcrInput input) → Object

The default request body for the simple JSON contract: a POST of the page PNG plus its dimensions and any hints. See the README for the matching response shape and a reference server.

defaultVlmResponseParser(Object? json, PdfOcrPageImage page) → List<VlmOcrWord>

The default response parser for the simple JSON contract.

dotsOcrResponseParser(Set<String> categories) → VlmOcrResponseParser

Builds a parser for dots.ocr's OpenAI-compatible responses, keeping only cells whose category is in categories.

openAiChatRequestBody(VlmOcrInput input) → Object

Builds an OpenAI-compatible chat-completions request that sends the page as an inline image and asks for OCR. Used by VlmOcrEngine.dotsOcr; reuse it (with a matching VlmOcrResponseParser) for other chat-style VLM gateways.

Typedefs

VlmOcrRequestBody = FutureOr<Object?> Function(VlmOcrInput input)

Builds the HTTP request body (a JSON-encodable object or a ready String) for one page. Override to target a service with a bespoke schema.

VlmOcrResponseParser = List<VlmOcrWord> Function(Object? json, PdfOcrPageImage page)

Parses a decoded JSON response into recognized words. Override to read a service's bespoke response shape.

Exceptions / Errors

VlmOcrException

Thrown when a remote OCR service is unreachable, returns a non-200 status, or returns a body this engine cannot parse.