# How Bounding Box Coordinates Work in LiteParse Output

> Understand how bounding box coordinates work in LiteParse output. Learn to interpret x, y, width, and height values for precise text location.

- Repository: [LlamaIndex/liteparse](https://github.com/run-llama/liteparse)
- Tags: internals
- Published: 2026-06-01

---

**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`](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/types.rs) [[source]](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/types.rs#L13-L25). 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`](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/output/json.rs) [[source]](https://github.com/run-llama/liteparse/blob/main/crates/liteparse/src/output/json.rs#L44-L52).

## 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]](https://github.com/run-llama/liteparse/blob/main/docs/src/content/docs/liteparse/guides/visual-citations.mdx#L31-L33).

## 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]](https://github.com/run-llama/liteparse/blob/main/docs/src/content/docs/liteparse/guides/visual-citations.mdx#L74-L88).

## 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

```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

```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`](https://github.com/run-llama/liteparse/blob/main/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`](https://github.com/run-llama/liteparse/blob/main/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.