Rasura

Reading a document

What comes back when you open a file, and how much of it was recovered rather than read.

The document

JavaScript
const info = await doc.info()

documentKind is the first thing to branch on. A scanned document has pages and no paragraphs, so code that assumes text will find none and needs to say so rather than appear to work.

  • born-digital: text was extracted. Everything works.
  • scanned: images only. Editing text is not possible.
  • mixed: some pages of each, common in scanned-and-appended files.

taggedStatus reports whether a structure tree is present and whether edits have degraded it. Degraded is reported separately from absent, because a document that never had tags and one that lost them need different responses.

A page

JavaScript
const page = await doc.page(0)
page.paragraphs // reconstructed text, in reading order
page.blocks // every block including figures and rules
page.tables // detected tables, with row and column counts
page.images // image extents, and whether each is editable
page.mediaBox // the page box, in points

Each paragraph carries more than its text:

JavaScript
const [p] = page.paragraphs()
p.text // the characters
p.box // where it sits
p.lineCount // how many lines the document broke it into
p.leading // baseline to baseline, in points
p.alignment // left, right, centre or justified
p.textConfidence // exact, partial or none

textConfidence is the honest part. exact means every character came from a reliable mapping. partial means some glyphs were resolved by heuristic, usually a font with no /ToUnicode and a non-standard encoding. Text at partial is worth showing and worth flagging before anyone acts on it.

Reading order

Content order is not reading order. A two-column page usually stores the left column and the right column interleaved, because that is the order the producer drew them. Rasura uses the structure tree when the document has one and a recursive cut of the page geometry when it does not.

Which one was used is reported. Against tagged documents in the test corpus, geometry agrees with the structure tree 89.8% of the time, measured over 50 tagged files.

Leniencies

Real PDFs break the specification constantly, and viewers accept them silently. Rasura accepts them too, and tells you.

JavaScript
for (const l of info.leniencies) {
console.log(l.kind, l.offset, l.detail)
}
// bad-startxref 0 cross-reference chain unusable; rebuilding
// length-recovered 912 /Length said 200, the stream runs 214

For most callers this is diagnostic noise. For anyone building validation, archival or forensic tooling it is the most useful thing the library produces, and no viewer exposes it.