How Bounding Box Coordinates Work in LiteParse Output

LiteParse represents text locations using bounding boxes defined by x, y, width, and height coordinates measured in PDF points from the top-left corner of the page.

LiteParse, the high-performance Rust parser from the run-llama organization, extracts visible text from PDFs while preserving precise spatial metadata. Understanding the coordinate system is essential for building visual citation features, highlighting search results, or mapping text to rendered page images.

The TextItem Structure

The core data structure for spatial text data is the TextItem struct defined in crates/liteparse/src/types.rs [source]. This struct captures both the textual content and its geometric position on the page.

Core Coordinate Fields

Each TextItem contains five spatial properties measured in PDF points (1 point = 1/72 inch):

• x – Horizontal distance from the left edge of the page to the top-left corner of the bounding box.
• y – Vertical distance from the top edge of the page to the top-left corner of the bounding box.
• width – Horizontal extent of the text fragment.
• height – Vertical extent of the text fragment.
• rotation – Counter-clockwise rotation in degrees, adjusted for any page rotation applied during parsing.

When processing completes, the parser constructs a ParsedPage object containing a Vec<TextItem> (accessed as text_items), which the JSON formatter serializes directly into the textItems array in crates/liteparse/src/output/json.rs [source].

Coordinate System and Origin

LiteParse uses a Cartesian coordinate system aligned with the PDF specification:

• Origin – Located at the top-left corner of the page.
• X-axis – Increases to the right.
• Y-axis – Increases downward (unlike mathematical Cartesian coordinates).
• Units – All values are expressed in PDF points, matching the page-level width and height fields also present in the output.

This coordinate system is documented for implementers in the "Visual Citations with Bounding Boxes" guide at docs/src/content/docs/liteparse/guides/visual-citations.mdx [source].

Converting Points to Pixels for Rendering

Because computer screens and image processing workflows typically use pixels rather than points, you must apply a scale factor when rendering bounding boxes over screenshots or page rasterizations. The conversion formula follows standard PDF rendering conventions:

scale = dpi / 72
pixel_value = point_value * scale

For example, at 150 DPI, the scale factor is approximately 2.083. This conversion is demonstrated in the visual citations guide at docs/src/content/docs/liteparse/guides/visual-citations.mdx [source].

Reading Bounding Boxes in Code

Both the Node.js and Python bindings expose the bounding box coordinates as direct properties on text item objects.

Node.js / TypeScript

import { LiteParse, searchItems } from "@llamaindex/liteparse";

const parser = new LiteParse({ outputFormat: "json", dpi: 150 });
const result = await parser.parse("invoice.pdf");

for (const page of result.pages) {
  const matches = searchItems(page.textItems, { phrase: "Total Due" });
  for (const m of matches) {
    console.log(
      `Found "${m.text}" at (${m.x}, ${m.y}) size ${m.width}×${m.height}`
    );
  }
}

Python

from liteparse import LiteParse, search_items

parser = LiteParse()
result = parser.parse("invoice.pdf")

for page in result.pages:
    matches = search_items(page.text_items, "Total Due")
    for m in matches:
        print(f'Found "{m.text}" at ({m.x}, {m.y}) {m.width}×{m.height}')

Both examples access the x, y, width, and height fields directly from the text item objects returned by the library's search functions.

Summary

• Bounding box coordinates in LiteParse are defined by the TextItem struct in crates/liteparse/src/types.rs.
• Units are PDF points (1/72 inch), with the origin at the top-left corner of the page.
• Y-axis increases downward, matching standard PDF coordinate conventions.
• JSON output preserves these values directly in the textItems array via crates/liteparse/src/output/json.rs.
• Pixel conversion requires scaling by dpi / 72 when overlaying boxes on rendered images.
• Rotation is handled via the rotation field, accounting for both text and page rotation.

Frequently Asked Questions

What units does LiteParse use for bounding box coordinates?

LiteParse uses PDF points, where 1 point equals 1/72 of an inch. This matches the internal measurement system of the PDF specification and ensures consistent positioning regardless of device resolution. The width and height fields of each page are also expressed in these same units.

How do I convert LiteParse coordinates to pixel values for rendering?

Multiply each coordinate by a scale factor of dpi / 72. For example, at 144 DPI, multiply the point values by 2.0 to obtain pixel coordinates. This conversion is necessary when overlaying bounding boxes on rasterized page images or screenshots, as demonstrated in the visual citations guide.

Does LiteParse handle page rotation in bounding box coordinates?

Yes. The TextItem struct includes a rotation field representing counter-clockwise rotation in degrees. This value is pre-adjusted for any page-level rotation detected during parsing, so coordinates are always relative to the visual top-left of the rendered page, not necessarily the PDF's internal coordinate system.

Where is the coordinate origin located in LiteParse output?

The coordinate origin (0,0) is located at the top-left corner of the page. The X coordinate increases toward the right edge, while the Y coordinate increases toward the bottom edge. This top-left origin with downward Y-axis is consistent with PDF rendering conventions and most image processing coordinate systems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}