lmpdf: Project Tracking Issue

[tlkahn]

lmpdf Project Tracker

A modern, safe Rust wrapper around Pdfium with macro-generated bindings, arena-based ownership, and honest threading.

Spec: doc/spec/lmpdf-spec.md
Roadmap: doc/roadmap.md
Design critique: doc/ideation/pdfium-render-critique-and-rewrite.md

Milestones

🔨 Infrastructure (Phases 0–2)

• Phase 0: Workspace Scaffolding #1 — Phase 0: Workspace Scaffolding
• Phase 1: The pdfium_ffi! Macro #2 — Phase 1: The pdfium_ffi! Macro
• Phase 2: Safe Wrappers + Minimal Document #3 — Phase 2: Safe Wrappers + Minimal Document

🚀 MVP — publish 0.1 (Phase 3)

• Phase 3: Rendering (MVP) — publish 0.1 #4 — Phase 3: Rendering (MVP)

📦 Core Features (Phases 4–7, after MVP)

• Expose coordinate conversion API (DeviceToPage / PageToDevice) #20 — Coordinate Conversion API (DeviceToPage / PageToDevice)
• Phase 4: Text Extraction #5 — Phase 4: Text Extraction
• Phase 5: Page Objects #6 — Phase 5: Page Objects
• Phase 6: Document Creation and Mutation #7 — Phase 6: Document Creation and Mutation
• Phase 7: Annotations and Forms #8 — Phase 7: Annotations and Forms

⚡ Platform & Performance (Phases 8–10, after MVP)

• Phase 8: PdfiumPool and Multi-Threading #9 — Phase 8: PdfiumPool and Multi-Threading
• Phase 9: lmpdf-bundle (Auto-Download Pdfium) #10 — Phase 9: lmpdf-bundle (Auto-Download Pdfium)
• Phase 10: WASM Backend #11 — Phase 10: WASM Backend

🏁 Completion (Phases 11–12)

• Phase 11: Remaining API Coverage #12 — Phase 11: Remaining API Coverage
• Phase 12: Polish and 1.0 Release #13 — Phase 12: Polish and 1.0 Release

Dependency Graph

Phase 0 ─── Phase 1 ─── Phase 2 ─── Phase 3 (MVP / publish 0.1)
                                        │
                                        ▼
                                   #20 (coord conversion)
                                        │
                         ┌──────────────┼──────────────┐
                         ▼              ▼              ▼
                      Phase 4       Phase 5        Phase 8
                      (text)       (objects)       (pool)
                         │              │
                         └──────┬───────┘
                                ▼
                            Phase 6
                           (creation)
                                │
                                ▼
                            Phase 7
                         (annotations)
                                │
                    ┌───────────┼───────────┐
                    ▼           ▼           ▼
                Phase 9     Phase 10    Phase 11
               (bundle)     (WASM)     (coverage)
                    │           │           │
                    └───────────┼───────────┘
                                ▼
                            Phase 12
                             (1.0)

Key Design Decisions

Decision	Choice
API scope	Full Pdfium coverage
WASM	First-class from day one
Async	Sync only (callers spawn_blocking)
Linking	Dynamic + Static + System + Bundled
Pdfium versions	Latest + 2 prior (3 versions)
Crate layout	Workspace: lmpdf-sys, lmpdf, lmpdf-bundle
Image crate	Latest only, optional feature
Ownership	Arena + generational handles (slotmap)
Threading	!Send types + built-in PdfiumPool

Reference Implementation

pdfium-render (v0.9.1) is the primary reference. Use it for:

• Test PDFs: 22 test fixtures in test/ — copy into lmpdf's test directory
• FFI signatures: src/bindings.rs (519 methods) is the most complete Rust-typed Pdfium FFI catalog; cross-reference when writing pdfium_ffi! declarations
• Pdfium C headers: Copy include/pdfium_{7763,7543,7350}/ rather than sourcing independently
• Implementation patterns: RenderConfig builder, pixel format conversion (src/utils.rs), WASM JS dispatcher, content regeneration strategy
• Known pitfalls: Drop ordering segfault (form before document), UTF-16LE encoding, null handle gaps, FPDFPageObj_Destroy double-free, bitmap stride alignment
• Examples as spec: 29 examples in examples/ serve as informal feature specification — port key ones per phase (see spec Appendix A)

Full details in the spec's Appendix A: Reference Implementation.

[lgsunnyvale]

What APIs are required for this feature: selecting a rectangle in a pdf view to get a data structure with:

• page number;
• coordinates of the selected rectangle;
• all elements (texts, images etc.) inside the rectangle, as well as their relative position/coordinates in the said rectangle.

I assume the coordinates must be associated with the DPI of the given pdf file.

[tlkahn]

What APIs are required for this feature: selecting a rectangle in a pdf view to get a data structure with:

• page number;
• coordinates of the selected rectangle;
• all elements (texts, images etc.) inside the rectangle, as well as their relative position/coordinates in the said rectangle.

I assume the coordinates must be associated with the DPI of the given pdf file.

Great question. This use case touches three pieces of work that are planned but not yet implemented. Here's how the pieces fit together:

What's available today (Phase 3 — MVP)

• Page dimensions: `doc.page_width(page)` / `doc.page_height(page)` return `f32` in PDF points (1/72 inch).
• DPI-aware rendering: `RenderConfig::new().dpi(150)` renders at a given DPI; internally this calls `.scale(dpi / 72.0)`.
• Coordinate transform FFI: `FPDF_DeviceToPage` and `FPDF_PageToDevice` are already declared in our FFI layer. These convert between device coordinates (pixels at a given DPI) and PDF page coordinates (points, origin bottom-left). They are not yet exposed in the safe high-level API, but the plumbing is there.

What's needed

1. Coordinate conversion (safe wrappers — small addition)

We need to expose `FPDF_DeviceToPage` / `FPDF_PageToDevice` through `Document`:

```rust
impl Document {
/// Convert device (pixel) coordinates to PDF page coordinates.
pub fn device_to_page(
&self, page: PageRef,
render_config: &RenderConfig,
device_x: i32, device_y: i32,
) -> Result<(f64, f64), Error>;

/// Convert PDF page coordinates to device (pixel) coordinates.
pub fn page_to_device(
    &self, page: PageRef,
    render_config: &RenderConfig,
    page_x: f64, page_y: f64,
) -> Result<(i32, i32), Error>;

}
```

The `RenderConfig` carries the DPI/scale/rotation, which determines the device coordinate space. So yes — the coordinates are always associated with a specific DPI through the render config.

2. Text extraction — Phase 4

From the spec, Phase 4 adds:

```rust
impl Document {
pub fn page_text(&self, page: PageRef) -> Result<String, Error>;
pub fn page_chars(&self, page: PageRef) -> Result<Vec, Error>;
pub fn page_text_segments(&self, page: PageRef) -> Result<Vec, Error>;
pub fn search_page(&self, page: PageRef, query: &str, opts: SearchOptions)
-> Result<Vec, Error>;
}

pub struct CharInfo {
pub char: char,
pub unicode: u32,
pub bounds: Rect, // position in PDF page coordinates
pub font_size: f32,
pub font_weight: u32,
}
```

Under the hood this wraps Pdfium's `FPDFText_*` family — specifically `FPDFText_GetBoundedText` for "give me text inside this rectangle."

3. Page object enumeration — Phase 5

Phase 5 adds the ability to enumerate all objects (text runs, images, paths, shadings) on a page:

```rust
impl Document {
pub fn page_objects(&self, page: PageRef) -> Result<Vec, Error>;
pub fn object_type(&self, obj: ObjectRef) -> Result<PageObjectType, Error>;
pub fn object_bounds(&self, obj: ObjectRef) -> Result<Rect, Error>;
// ... plus type-specific accessors (image bitmap, text content, path data)
}

pub enum PageObjectType { Text, Path, Image, Shading, XObjectForm, Unsupported }
```

This wraps `FPDFPage_CountObjects`, `FPDFPage_GetObject`, `FPDFPageObj_GetBounds`, etc.

Putting it together — the "rectangle selection" workflow

Once Phases 4 and 5 land, the workflow for your use case would be:

```rust
let config = RenderConfig::new().dpi(150);
let page_ref = doc.page(page_index)?;

// 1. Convert the user's selection rectangle from device (pixel) coords to PDF page coords
let (left, top) = doc.device_to_page(page_ref, &config, sel_x1, sel_y1)?;
let (right, bottom) = doc.device_to_page(page_ref, &config, sel_x2, sel_y2)?;
let selection = Rect { left, top, right, bottom };

// 2. Get all page objects, filter to those inside the selection
let objects = doc.page_objects(page_ref)?;
let hits: Vec<_> = objects.iter().filter(|obj| {
let bounds = doc.object_bounds(*obj).unwrap();
selection.contains(&bounds) // or intersects, depending on your needs
}).collect();

// 3. Build your result with relative coordinates
for obj in &hits {
let obj_bounds = doc.object_bounds(*obj)?;
let relative_bounds = Rect {
left: obj_bounds.left - selection.left,
top: obj_bounds.top - selection.top,
right: obj_bounds.right - selection.left,
bottom: obj_bounds.bottom - selection.top,
};
let kind = doc.object_type(*obj)?;
// ... collect into your data structure
}
```

On DPI and coordinates

PDF coordinates are in points (1/72 inch) and are DPI-independent. DPI only matters at the rendering/display boundary. The coordinate transforms (`device_to_page` / `page_to_device`) bridge the two spaces, and the `RenderConfig` carries the DPI setting that parameterizes the conversion. So you'd:

1. Render at a chosen DPI → get pixel image
2. User selects a rectangle in pixel space
3. Convert pixel rect → PDF page rect via `device_to_page`
4. Query text/objects using the page-coordinate rect
5. Compute relative positions by subtracting the selection origin

Timeline

Per the roadmap:

• Phase 4 (text extraction) and Phase 5 (page objects) are the next two phases after the current MVP
• The coordinate conversion wrappers can be added as a small incremental improvement before those phases

If you have a specific use case in mind, feel free to open a feature request issue — it would help us prioritize.