Skip to content
pdf-textlayer
Esc
↑↓navigate↵open⌘Jpreview
On this page

Adapters and other OCR engines

Read LiteParse JSON with the built-in adapter, or feed boxes from Textract, Azure Document Intelligence, Tesseract, or your own pipeline.

An adapter turns one OCR tool’s JSON into pages of text boxes. Adapters are part of the Rust core, so the CLI, Python, Node.js, and Rust read a given file the same way.

Name Source Reads
liteparse (default) LiteParse lit parse --format json pages[].text_items[] whose font_name is "OCR".

Pick the adapter with --from on the CLI, adapter= in Python, adapter: in Node.js, or an Adapter value in Rust.

LiteParse

lit parse input.pdf --format json --extract-text-metadata -o parsed.json

The adapter reads these fields from each item, and ignores the rest (font metrics, colors, blocks, annotations):

{
  "pages": [
    {
      "page": 1,
      "text_items": [
        {
          "text": "Hello",
          "x": 72.0,
          "y": 100.0,
          "width": 40.0,
          "height": 12.0,
          "font_name": "OCR",
          "confidence": 0.98,
          "rotation": 0.0
        }
      ]
    }
  ]
}
  • confidence defaults to 1 and rotation to 0 when missing. LiteParse writes rotation only with --extract-text-metadata; without it, rotated text is drawn horizontally inside its box.
  • Items with empty text, or a width or height of zero or less, are skipped.
  • A malformed page or item is skipped rather than failing the whole file.
  • The field names of older LiteParse versions, textItems and fontName, are still accepted.

Inspect or edit before writing

load_pages (Python) and loadPages (Node.js) return what the adapter read, so you can drop pages, fix text, or filter boxes before writing:

from pdf_textlayer import ParsedPage, load_pages, write_textlayer

pages = [
    ParsedPage(page.page_number, [box for box in page.boxes if len(box.text) > 1])
    for page in load_pages("parsed.json")
]
write_textlayer("input.pdf", pages, "output.pdf")
import { loadPages, writeTextLayer } from "pdf-textlayer";

const pages = (await loadPages("parsed.json")).map((page) => ({
  ...page,
  boxes: page.boxes.filter((box) => box.text.length > 1),
}));
await writeTextLayer("input.pdf", pages, "output.pdf");

Any other OCR engine

Every package takes boxes directly, so an engine without an adapter needs only a few lines of conversion. Convert its output to pdf-textlayer coordinates — PDF points, top-left origin, (x, y) at the box’s top-left corner — and call write_textlayer / writeTextLayer / write_text_layer.

For example, Tesseract’s TSV output (tesseract scan.png out tsv) gives word boxes in image pixels. Scale them by 72 / dpi:

import csv

from pdf_textlayer import ParsedPage, TextBox, write_textlayer

DPI = 300  # the resolution the page was rendered at for OCR
scale = 72 / DPI

boxes = []
with open("out.tsv", newline="") as tsv:
    for row in csv.DictReader(tsv, delimiter="\t", quoting=csv.QUOTE_NONE):
        if row["level"] == "5" and row["text"].strip():
            boxes.append(
                TextBox(
                    text=row["text"],
                    x=int(row["left"]) * scale,
                    y=int(row["top"]) * scale,
                    width=int(row["width"]) * scale,
                    height=int(row["height"]) * scale,
                    confidence=float(row["conf"]) / 100,
                )
            )

write_textlayer("scan.pdf", [ParsedPage(page_number=1, boxes=boxes)], "searchable.pdf")

Adding an adapter

Adapters live in crates/pdf-textlayer/src/adapters.rs. Add a variant to Adapter, its name, and a function that turns the tool’s JSON into Vec<ParsedPage>; every package picks it up. Pull requests for Azure Document Intelligence, Textract, hOCR, and others are welcome.

Was this page helpful?