# How to Get X/Y Position Coordinates for Extracted Text in pdf-inspector

> Discover how to get X/Y position coordinates for extracted text in pdf-inspector using TextItem structs and extract_text_with_positions functions. Learn PDF point measurements.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-08-10

---

**pdf-inspector exposes every text element's exact coordinates through `TextItem` structs returned by the `extract_text_with_positions*` family of functions, with `x` and `y` values measured in PDF points from the bottom-left origin.**

The `firecrawl/pdf-inspector` repository is a Rust-based PDF parsing library that preserves spatial information during text extraction. Unlike simple text dumpers, it tracks where each glyph appears on the page—essential for layout analysis, OCR verification, and document reconstruction workflows.

## Where Coordinates Are Stored: The TextItem Struct

Position data lives in [`src/types.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/types.rs), where the `TextItem` struct defines the schema for extracted text elements:

```rust
pub struct TextItem {
    pub text: String,
    pub x: f32,        // horizontal position in PDF points
    pub y: f32,        // vertical position in PDF points
    pub page: u32,     // 1-indexed page number
    pub font: Option<String>,
    pub size: Option<f32>,
    // ... additional metadata
}

```

Coordinates use the **standard PDF coordinate system**: origin at the bottom-left corner of the page, with Y increasing upward. One point equals 1/72 of an inch.

## The Extraction Pipeline

The core logic resides in [`src/extractor/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/extractor/mod.rs). The pipeline follows this sequence:

1. **Document loading** — `load_document_from_path_with_password` or `load_document_from_mem` parses the PDF structure
2. **Font mapping** — `FontCMaps::from_doc` builds glyph-to-Unicode conversion tables
3. **Content stream processing** — `extract_positioned_text_impl` walks text-showing operators (`Tj`, `TJ`)
4. **Matrix transformation** — the current text matrix converts glyph positions to page-space coordinates
5. **Struct population** — `TextItem` fields are filled and collected into `Vec<TextItem>`

The implementation automatically handles page rotation, scaling, and MediaBox offsets. You receive coordinates in normalized, upright space regardless of how the PDF was constructed.

## Public APIs for Position-Aware Extraction

These functions are re-exported from [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs):

- **`extract_text_with_positions(path)`** — all pages, file-based
- **`extract_text_with_positions_pages(path, page_filter)`** — subset of 1-indexed pages
- **`extract_text_with_positions_mem(buffer)`** — in-memory PDF
- **`extract_text_with_positions_mem_pages(buffer, page_filter)`** — in-memory with page filter

Each returns `Result<Vec<TextItem>, PdfError>` containing the full position metadata.

## Code Examples

### Rust: Extracting Coordinates from File

```rust
use pdf_inspector::{extract_text_with_positions, TextItem};

fn main() -> Result<(), pdf_inspector::PdfError> {
    let items: Vec<TextItem> = extract_text_with_positions("invoice.pdf")?;
    
    for item in items {
        println!(
            "Page {} | ({:.2}, {:.2}) | \"{}\"",
            item.page, item.x, item.y, item.text
        );
    }
    Ok(())
}

```

### Python: Using the PyO3 Bindings

The Python bindings in [`src/python.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/python.rs) expose identical functionality through `PyTextItem` objects:

```python
import pdf_inspector

items = pdf_inspector.extract_text_with_positions("invoice.pdf")

for itm in items:
    print(f"Page {itm.page} | ({itm.x:.2f}, {itm.y:.2f}) | \"{itm.text}\"")

```

### Filtering by Specific Pages

For targeted extraction (pages 2 and 4 only):

```python

# Python

items = pdf_inspector.extract_text_with_positions("document.pdf", pages=[2, 4])

```

```rust
// Rust
use std::collections::HashSet;

let mut pages = HashSet::new();
pages.insert(2);
pages.insert(4);

let items = extract_text_with_positions_pages("document.pdf", Some(&pages))?;

```

## Working with PDF Coordinates

### Unit Conversions

PDF points are the native unit. Convert as needed:

```rust
let inches = item.x / 72.0;
let centimeters = item.x / 72.0 * 2.54;

```

### Coordinate Transformations

For top-down coordinate systems (common in UI frameworks), flip the Y axis:

```rust
// Assuming standard US Letter page (792 pt height)
let page_height = 792.0;
let y_from_top = page_height - item.y;

```

Relying on `MediaBox` dimensions from the PDF itself is more robust than hardcoded values.

### Performance Characteristics

Position-aware extraction incurs minimal overhead. The coordinate calculations piggyback on matrix operations already performed during text rendering. Use the `*_mem` variants when processing PDFs from network streams or databases to eliminate redundant I/O.

## Summary

- **Data structure**: `TextItem` in [`src/types.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/types.rs) holds `x: f32` and `y: f32` fields
- **Entry points**: `extract_text_with_positions*` functions in [`src/extractor/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/extractor/mod.rs)
- **Coordinate system**: PDF points, bottom-left origin, pre-normalized for rotation
- **Language support**: Native Rust API with equivalent Python bindings in [`src/python.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/python.rs)
- **Page filtering**: `*_pages` variants accept `HashSet<u32>` (Rust) or `list[int]` (Python)

## Frequently Asked Questions

### What units are the X and Y coordinates in?

PDF points, where 1 point = 1/72 inch ≈ 0.3528 mm. These are the native units of the PDF specification and require no transformation for accurate spatial calculations.

### Do I need to handle page rotation manually?

No. The extraction pipeline in [`src/extractor/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/extractor/mod.rs) applies the page's rotation matrix before populating `TextItem`. The coordinates you receive are always in upright, readable orientation regardless of how the PDF was authored.

### Can I get coordinates for a specific region of a page?

pdf-inspector returns all text items with their positions. Apply bounding-box filtering in your consumer code:

```python
items = pdf_inspector.extract_text_with_positions("doc.pdf")
region_items = [i for i in items if 100 < i.x < 300 and 500 < i.y < 700]

```

Built-in region filtering is not exposed in the current API surface.

### Are the coordinates precise enough for exact glyph placement?

Yes. The values derive from the PDF content stream's text matrices, which define glyph positioning at the specification level. Sub-point precision is preserved through the `f32` fields.