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
}
]
}
]
}
confidencedefaults to 1 androtationto 0 when missing. LiteParse writesrotationonly 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,
textItemsandfontName, 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.