hocr library

hOCR OCR document import: parsing, native geometry, and binding onto canonical text snapshots.

hOCR is HTML with a class vocabulary for OCR results over scanned pages (Tesseract's default rich output). Unseal parses the reading subset — producer metadata, pages, content areas, paragraphs, lines and words in the nesting the producer declared, integer pixel boxes, the native baseline polynomial, text angle, scan resolution and the 0..100 word confidence — into an HocrDocument, and bindHocrToSnapshot maps its text onto the UTF-16 ranges of a host-provided canonical text snapshot, preserving OCR origin, confidence and ambiguity. Baselines and angles stay native with named projections; coordinates are never rotated. Unseal does not run OCR.

Classes

CanonicalTextSnapshot
The canonical text of one section occurrence, captured explicitly over materialized text and bound to the identity that produced it.
HocrAmbiguousUnit
One ambiguous mapped unit: its place and the bounded candidate ranges the target text offers. An alternative reading on the unit or an ancestor makes it ambiguous even with one target candidate.
HocrBaseline
A line's baseline polynomial, native: the stored coefficients in stored order (pn ... p0) in the line's frame, whose origin is the bottom-left corner of the line's box with y growing downward.
HocrBindLimits
Work bounds of one hOCR-to-snapshot binding. The projection scan is linear in the target text per searched unit; the budget keeps a hostile document from quadratic work and reports the refusal typed.
HocrBlock
One content area (ocr_carea, ocrx_block, or the deprecated ocr_column).
HocrBoundSpatialText
The transport view of a binding: pages, their document page indexes, outcome counts, ambiguities, and the target identity tuple — everything a host needs to persist or re-verify the binding without keeping the target text or the parsed document resident. The worker op returns this view; wire codecs encode it as structured-clone-safe maps.
HocrBox
An hOCR bbox: integer pixel coordinates in the image's top-left space, (x0, y0) upper-left and (x1, y1) lower-right as the spec defines them.
HocrConfidence
A word's declared x_wconf: the 0..100 value when the producer wrote a number, or the non-numeric token it wrote instead. A word that declares no x_wconf has no HocrConfidence at all, so absent, unknown and zero stay three different states.
HocrContainer
A role element that holds other role elements: a page, a block or a paragraph. The nesting is the producer's own; lines and words flatten it in document order.
HocrDocument
A parsed hOCR document: the producer metadata from head and the pages in document order.
HocrElement
One modeled hOCR element: its role token, HTML tag, optional id and box, language and direction attributes, text angle, and every title property the subset does not consume, verbatim.
HocrLine
One line (ocr_line, ocrx_line, or a Tesseract line-role class): its words, its own text, and the native baseline.
HocrPage
One ocr_page: its declared identity properties and its children in the nesting the producer declared.
HocrParagraph
One ocr_par.
HocrSnapshotBinding
The result of binding an hOCR document onto one canonical snapshot: the spatial pages whose zones address the target text's UTF-16 ranges, with the import's provenance and the full mapping outcome.
HocrTitleProperty
One property of an hOCR title attribute: the name and the value tokens exactly as written, quotes removed.
HocrUnitPlace
Where a mapped unit sits in the parsed document: the page, the line's index among that page's lines in document order, and the word's index inside its line — null for a line-level unit.
HocrWord
One ocrx_word.
PublicationRevision
The logical identity and exact revision of one publication.
SectionOccurrence
One occurrence of a content section inside a publication's reading order.
SpatialRect
A rectangle in the canonical top-left page space: the x and y fields place the upper-left corner, sizes grow right and down.
SpatialTextPage
One page of positioned text: the shared shape DjVu hidden text and imported ALTO both project onto.
SpatialTextProvenance
The provenance of a spatial text page: its origin, the OCR software when the source names one, and whether the source declared confidence values at all.
SpatialTextZone
One positioned text zone: a hierarchy kind, a rectangle in the page's canonical top-left space, and the UTF-16 code-unit range it selects in the page's canonical text.
SpatialZoneLookup
Range queries over one SpatialTextPage's zones: which zone holds a text offset, which zones overlap a text range, which region a zone belongs to.
TextProfile
The extraction profile a canonical text was produced under.

Enums

HocrFrameSource
Where a page's spatial frame came from.
SourceEvidence
How much the parser could verify about the exact source bytes a snapshot's identity claims.
SpatialTextOrigin
Where a spatial text page's zones came from.
SpatialUnit
The unit every coordinate of one spatial document is expressed in.
SpatialZoneKind
The hierarchy levels DjVu hidden text and ALTO share.

Constants

canonicalTextSchemaVersion → const int
The current canonical-text snapshot schema. Codec payloads carry it; a different value is a revision mismatch, not a best-effort decode.

Functions

bindableContent(String text) → String
The content a unit binds: its model text without leading and trailing ASCII whitespace (space, tab, LF, CR, FF). Non-ASCII spaces such as U+00A0 are content and stay. Empty means the unit binds nothing.
bindHocrToSnapshot({required HocrDocument document, required CanonicalTextSnapshot target, HocrBindLimits limits = const HocrBindLimits()}) → HocrSnapshotBinding
Binds document's positioned text onto target's canonical text: each word maps to the UTF-16 range its text selects in the target, lines whose words carry no text map their own text, parents aggregate their children's ranges, and every outcome stays observable.
parseHocrDocument(Uint8List bytes) → HocrDocument
Parses hOCR (HTML or XHTML) bytes into an HocrDocument under the subset doc/hocr.md fixes: producer metadata, pages, content areas, paragraphs, lines and words with the nesting the producer declared, integer boxes, native baselines, text angles, scan resolution, the 0..100 word confidence, and every unconsumed title property verbatim.
parseHocrTitle(String title, {required int maxProperties, required int maxTokens}) → List<HocrTitleProperty>
Parses an hOCR title attribute under the grammar doc/hocr.md fixes: ;-separated properties, the comma rule for kraken-style titles, quoted strings, letter-first lowercase names, no duplicates.

Exceptions / Errors

HocrException
Malformed, excessive, or inconsistent hOCR input.
HocrUnsupportedFeatureException
A structurally sound hOCR document that declares a feature outside the supported subset: an explicit order or cflow reading order.