alto library
ALTO OCR document import: parsing, verified scaling, and binding onto canonical text snapshots.
ALTO is a sidecar format for OCR results over scanned pages. Unseal
parses the supported subset (namespaces v2, v3, v4; pixel, mm10 and
inch1200 units; pages, text and non-text blocks, lines, strings with
confidence) into an ALTO document, and bindAltoToSnapshot maps its
positioned words onto the UTF-16 ranges of a host-provided canonical
text snapshot, preserving OCR origin and confidence. Coordinate
conversion only happens through a verified scale; physical units
without verifiable evidence refuse to convert.
Classes
- AltoAmbiguousWord
- One ambiguous word: its place in the imported document and every candidate range the target text offers.
- AltoBindLimits
- Work bounds of one ALTO-to-snapshot binding. The projection scan is linear in the target text per searched word; the budget keeps a hostile document from quadratic work and reports the refusal typed.
- AltoBlock
- One ALTO block with its rectangle and, for text blocks, its lines.
- AltoBoundSpatialText
- The transport view of a binding: pages, outcome counts, ambiguities, provenance, 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 ops return this view; wire codecs encode it as structured-clone-safe maps.
- AltoDocument
- A parsed ALTO document: the OCR sidecar's declared description, pages, and positioned content.
- AltoLine
-
One ALTO
TextLinewith its strings. - AltoPage
- One ALTO page: declared dimensions, quality figures, and its blocks.
- AltoScale
- A verified conversion from one ALTO document's coordinates into pixel space.
- AltoSnapshotBinding
- The result of binding an ALTO document onto one canonical snapshot: spatial pages whose zones address the target text's UTF-16 ranges, with the import's provenance and the full mapping outcome.
- AltoString
-
One ALTO
String: a recognized word with its geometry, content, and confidence figures. - SpatialRect
-
A rectangle in the canonical top-left page space: the
xandyfields 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.
Enums
- AltoBlockKind
- The block kinds the supported ALTO subset distinguishes.
- 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.
Functions
-
bindAltoToSnapshot(
{required AltoDocument document, required CanonicalTextSnapshot target, AltoBindLimits limits = const AltoBindLimits()}) → AltoSnapshotBinding -
Binds
document's positioned words ontotarget's canonical text: each ALTOStringmaps to the UTF-16 range its content selects in the target, lines and text blocks aggregate their children's ranges, and every outcome stays observable. -
parseAltoDocument(
Uint8List bytes) → AltoDocument -
Parses ALTO XML bytes into an AltoDocument under the declared
subset: namespaces v2, v3 and v4, the
Descriptionfigures (MeasurementUnit, OCR software, source image), and the positioned content (Page> block kinds >TextLine>String/SP).
Exceptions / Errors
- AltoException
- Malformed, excessive, or out-of-subset ALTO input.
- AltoUnitConversionException
- A coordinate conversion that cannot be verified: the document's unit is physical and no verifiable scale (dpi or page-dimension agreement) was supplied.
- AltoUnsupportedFeatureException
- A structurally valid ALTO document whose declared version, namespace, or feature set sits outside the supported subset.