references/output_formats.md
LiteParse 2.15.0 Output Formats
Text and Markdown
lit parse document.pdf --format text produces layout-preserved plain text;
--format markdown reconstructs headings, lists, tables and links heuristically.
Python result.text contains the selected document output, while each page has
text and markdown fields. Text items remain available in every output mode.
Markdown's default image_mode="placeholder" emits image references, not image
files. Use extract_images=True, image_output_dir="images" (CLI
--extract-images --image-output-dir images) to save bytes; image_mode="off"
removes Markdown references. JSON carries image metadata, never image bytes.
Native CLI JSON is not the Python object schema
lit parse document.pdf --format json --no-ocr -o document.json
A minimal 2.15.0 native-text result has this shape (illustrative values):
{
"total_pages": 1,
"pages": [{
"page": 1,
"width": 612.0,
"height": 792.0,
"text": "Materials and Methods",
"text_items": [{
"text": "Materials and Methods",
"x": 72.0,
"y": 120.28,
"width": 242.76,
"height": 26.78,
"font_name": "Helvetica",
"font_size": 24.0,
"confidence": 1.0
}]
}]
}
There is no top-level text and the page-number key is page, not
page_num. Optional fields may be absent. total_pages counts source pages
before selection/capping, not len(pages). When present, CLI page_errors
entries use page and message. Python uses PageError.page_number.
--extract-blocks, --extract-annotations, --extract-form-fields,
--extract-structure-tree, --extract-vector-graphics, and --complexity add
opt-in page fields. These can enlarge output substantially. --extract-text-metadata
adds rotation and richer glyph/font metadata. Read the
released serializer
for the full schema. npm's CLI also uses snake_case; Node library objects use camelCase.
Python and the bundled batch wrapper
Python exposes result.text, result.total_pages, result.pages,
result.page_errors; page objects expose page_num, text_items, text,
markdown, dimensions and optional metadata. result.num_pages == len(result.pages).
result.get_page(1) returns None if page 1 was not parsed.
The bundled scripts/batch_parse_dir.py deliberately emits a compact custom
JSON subset: text, total_pages, page_errors, and pages with page_num,
width, height, text, markdown, page_label, and basic text_items.
It excludes image bytes and optional rich metadata. Use native CLI JSON when
that schema or advanced extraction fields are required. The wrapper rejects
partial-page results, page-count truncation and existing output files, reports failures
and exits nonzero. For more than the default 1000 pages, use the native CLI/API
with an explicit max_pages and reconcile the returned pages.
It mirrors input subdirectories and appends the output extension to the whole
source name, e.g. supplement/paper.pdf.json.
Boxes, confidence, and validation
- Text-item boxes are
(x, y, width, height)in top-left page viewport coordinates, at 72 units per inch; right/down are positive. Store each page's dimensions. - For a screenshot of width
Wpxand heightHpx, scale x/width byWpx / page.widthand y/height byHpx / page.height. Rotations/crops must use the same parser settings. Never overlay raw PDF coordinates onto a 150-DPI image. - HTTP OCR returns
[x1, y1, x2, y2]in uploaded-image pixels. LiteParse maps these into page coordinates and merges native/OCR text. - A text item may be a multiword span; Python
emit_word_boxes=Trueopts intoitem.words. The default does not promise per-token boxes. - Python native-text
confidencemay beNone; CLI JSON substitutes 1.0. OCR scores are normalized to 0–1, but are not calibrated probabilities or a guarantee of a correct scientific transcription. Confidence alone cannot identify OCR provenance. - Compare requested page numbers with returned pages and inspect
page_errors. Review tables, units, equations and multi-column reading order against PNGs. Keep low-confidence source evidence available for review rather than silently discarding it from an allegedly complete corpus.
from liteparse import search_items
page = result.get_page(1)
hits = search_items(page.text_items, "Supplementary Table 1") if page else []
for hit in hits:
print(hit.text, hit.x, hit.y, hit.width, hit.height)
Reviewed 2026-10-01 against 2.15.0 source and synthetic PDF/PNG runtime fixtures.