Skip to main content

rustium_pdf/
lib.rs

1//! # rustium-pdf
2//!
3//! Pure-Rust extraction of PDF page primitives — glyphs with geometry, vector paths, images —
4//! plus page rendering. No C library, no FFI, no global state.
5//!
6//! It is what [rustypaper] reads PDFs with.
7//!
8//! [rustypaper]: https://github.com/pgarrett-scripps/rustypaper
9//!
10//! ```no_run
11//! # fn main() -> rustium_pdf::Result<()> {
12//! let doc = rustium_pdf::Document::open("paper.pdf")?;
13//! let page = doc.page(0)?;
14//!
15//! // Primitives are in user space (y-up); `page_matrix` converts to y-down device space.
16//! for glyph in page.glyphs.iter().filter(|g| g.is_visible()) {
17//!     println!("{:?} at {:?} {}pt bold={}",
18//!         glyph.text, glyph.origin, glyph.font_size, glyph.flags.is_bold());
19//! }
20//!
21//! let png = page.render(&doc, rustium_pdf::RenderOptions::at_dpi(150.0))?.to_png()?;
22//! # Ok(())
23//! # }
24//! ```
25//!
26//! ## Threading
27//!
28//! [`Document`] is `Send + Sync` with no global state, so pages can be extracted and rendered
29//! concurrently from one open document, without a lock around it.
30//!
31//! ## Text semantics
32//!
33//! A word break the page expresses as a positioning gap rather than a space character is emitted
34//! as a glyph flagged [`Glyph::is_generated_space`], so word boundaries survive.
35//! [`Page::text`] drops soft hyphens, which mark optional break points rather than content.
36//! Primitives are in user space (y-up); [`Page::page_matrix`] converts to y-down page space.
37//!
38//! ## Fonts without embedded programs
39//!
40//! A document may name Helvetica or Times and embed nothing. Extraction is unaffected: advances
41//! come from built-in metrics for the standard 14. Rendering substitutes a system face, chosen
42//! by style and preferring the metrically compatible Liberation family. Set `RUSTIUM_FONT_DIR`
43//! to pin the search to fonts you ship. Positions always come from the document, never the
44//! substitute, so a missing font shifts nothing.
45//!
46//! ## Known gaps
47//!
48//! * Type1 `/FontFile` programs yield metrics and text but no outlines; CFF and TrueType do.
49//! * Predefined non-Identity CJK CMaps fall back to the identity mapping.
50//! * `JPXDecode`, `CCITTFaxDecode` and `JBIG2Decode` images are passed through undecoded and
51//!   are skipped when rendering; `DCTDecode` (JPEG) and the byte filters are handled.
52//! * Clipping is tracked as a bounding rectangle, not an arbitrary path.
53
54pub mod content;
55pub mod crypt;
56pub mod document;
57pub mod error;
58pub mod filters;
59pub mod font;
60pub mod geom;
61pub mod lexer;
62pub mod object;
63pub mod page;
64pub mod parser;
65pub mod render;
66
67pub use document::Document;
68pub use error::{Error, Result};
69pub use font::{Font, FontFlags};
70pub use geom::{Matrix, Point, Rect};
71pub use object::{Dict, Object};
72pub use page::{Glyph, ImageData, ImageItem, Page, PathItem};
73pub use render::{RenderOptions, Rendered};