1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
//! Per-page handle exposing chars, words, and text extraction.
use crate::char::Char;
use crate::document::Document;
use crate::error::Result;
use crate::geom::Matrix;
use crate::text::options::TextOptions;
use crate::word::{Word, WordOptions};
use std::sync::OnceLock;
/// A borrowed view into one page of a [`Document`].
pub struct Page<'doc> {
doc: &'doc Document,
index: usize,
chars_cache: OnceLock<Vec<Char>>,
metrics_cache: OnceLock<PageMetrics>,
}
/// Geometric metadata about a page.
///
/// The media box is stored as the file declares it; `/Rotate` is applied on
/// the way out, so [`Self::display_width`] and [`Self::display_height`] are
/// the dimensions a reader would show.
#[derive(Debug, Clone, Copy)]
pub(crate) struct PageMetrics {
/// `/MediaBox` width in points, before `/Rotate`.
pub media_width: f32,
/// `/MediaBox` height in points, before `/Rotate`.
pub media_height: f32,
/// x of the `/MediaBox` lower-left corner. Usually `0`, but not always.
pub origin_x: f32,
/// y of the `/MediaBox` lower-left corner.
pub origin_y: f32,
/// Rotation in degrees, normalized to `0`, `90`, `180`, or `270`.
pub rotation: i16,
}
impl PageMetrics {
/// `true` when `/Rotate` swaps the page's width and height.
fn is_quarter_turn(&self) -> bool {
self.rotation == 90 || self.rotation == 270
}
/// Width as displayed, after `/Rotate`.
pub(crate) fn display_width(&self) -> f32 {
if self.is_quarter_turn() {
self.media_height
} else {
self.media_width
}
}
/// Height as displayed, after `/Rotate`.
pub(crate) fn display_height(&self) -> f32 {
if self.is_quarter_turn() {
self.media_width
} else {
self.media_height
}
}
/// Transform from raw PDF user space into displayed page space, both
/// still bottom-up. Composing this after the CTM is what makes the
/// `/MediaBox` origin and `/Rotate` apply to glyph positions, not just
/// to the page dimensions.
///
/// Two steps. First the lower-left corner of the media box is moved to
/// `(0, 0)` — it is not always there, and ignoring it shifted every
/// glyph by that corner. Then `/Rotate` turns the page clockwise, so for
/// 90° the corner ends up at the top-left of what the reader shows.
pub(crate) fn page_transform(&self) -> Matrix {
let to_origin = Matrix::translation(-self.origin_x, -self.origin_y);
let (w, h) = (self.media_width, self.media_height);
let rotate = match self.rotation {
90 => Matrix::new(0.0, -1.0, 1.0, 0.0, 0.0, w),
180 => Matrix::new(-1.0, 0.0, 0.0, -1.0, w, h),
270 => Matrix::new(0.0, 1.0, -1.0, 0.0, h, 0.0),
_ => Matrix::IDENTITY,
};
to_origin.then(rotate)
}
}
impl<'doc> Page<'doc> {
pub(crate) fn new(doc: &'doc Document, index: usize) -> Self {
Self {
doc,
index,
chars_cache: OnceLock::new(),
metrics_cache: OnceLock::new(),
}
}
/// 0-based page index in document order.
pub fn index(&self) -> usize {
self.index
}
/// Underlying [`Document`] this page belongs to.
pub fn document(&self) -> &'doc Document {
self.doc
}
/// Internal: the `lopdf` object ID of this page.
pub(crate) fn page_id(&self) -> lopdf::ObjectId {
self.doc.page_ids[self.index]
}
pub(crate) fn metrics(&self) -> &PageMetrics {
self.metrics_cache.get_or_init(|| {
crate::parser::lopdf_backend::page_metrics(&self.doc.inner, self.page_id(), self.index)
.unwrap_or(PageMetrics {
media_width: 612.0,
media_height: 792.0,
origin_x: 0.0,
origin_y: 0.0,
rotation: 0,
})
})
}
/// Page width in points, as displayed.
///
/// A page with `/Rotate 90` or `/Rotate 270` reports its media box
/// height here, because that is the edge a reader shows horizontally.
pub fn width(&self) -> f32 {
self.metrics().display_width()
}
/// Page height in points, as displayed. See [`Self::width`].
pub fn height(&self) -> f32 {
self.metrics().display_height()
}
/// Page rotation in degrees, always one of `0`, `90`, `180`, `270`.
///
/// The value is normalized: a negative `/Rotate` wraps into range, and a
/// `/Rotate` that is not a multiple of 90 is reported as `0`.
///
/// Rotation is already applied to [`Self::width`], [`Self::height`] and
/// to every [`Char`] coordinate, so callers do not need to apply it
/// themselves — this is here to describe the source page.
pub fn rotation(&self) -> i16 {
self.metrics().rotation
}
/// Lazily parse and cache the page's positioned glyphs.
///
/// The first call walks the content stream; subsequent calls return the
/// cached slice in O(1).
///
/// # Errors
///
/// - [`Error::Pdf`](crate::Error::Pdf) if the page dictionary or content
/// stream cannot be read.
/// - [`Error::ContentStream`](crate::Error::ContentStream) if the
/// content stream is malformed.
///
/// On error nothing is cached, so a retry will re-attempt the parse.
///
/// # Examples
///
/// ```no_run
/// # use pdfraw::prelude::*;
/// # fn run() -> Result<()> {
/// let doc = Document::open("invoice.pdf")?;
/// for c in doc.page(0)?.chars()? {
/// println!("{} at ({}, {})", c.text, c.x0, c.top);
/// }
/// # Ok(()) }
/// ```
pub fn chars(&self) -> Result<&[Char]> {
if let Some(cached) = self.chars_cache.get() {
return Ok(cached.as_slice());
}
let parsed = crate::parser::lopdf_backend::extract_chars(self)?;
// `set` returns `Err(parsed)` only when another caller already
// populated the cell first. In that case our `parsed` is dropped
// and we read whatever the winner stored — both walks of the same
// content stream produce the same chars, so the result is
// observationally identical.
let _ = self.chars_cache.set(parsed);
// Invariant: after the get-or-set sequence above, the cell is
// always populated. `expect` here documents that post-condition
// rather than masking a runtime failure.
Ok(self
.chars_cache
.get()
.expect("chars_cache populated by either set() above or a concurrent caller")
.as_slice())
}
/// Cluster the page's chars into words using `opts`.
pub fn words(&self, opts: &WordOptions) -> Result<Vec<Word>> {
let chars = self.chars()?;
Ok(crate::text::extractor::extract_words(chars, opts))
}
/// Naive concatenated text: words separated by `' '`, lines by `'\n'`.
pub fn extract_text(&self) -> Result<String> {
let chars = self.chars()?;
Ok(crate::text::extractor::extract_text_simple(chars))
}
/// Layout-preserving text — replicates pdfplumber's `extract_text(layout=True)`.
pub fn extract_text_layout(&self, opts: &TextOptions) -> Result<String> {
let chars = self.chars()?;
Ok(crate::text::extractor::extract_text_layout(chars, opts))
}
/// Return `Ok(true)` when the page emits no text-showing operators but
/// does draw image-like content (any `Do` XObject invocation or an
/// inline `BI` image) — i.e. OCR is probably what you want.
///
/// A page that draws nothing at all returns `false`. See
/// `docs/decisions/0008-widened-scan-detection.md` for why the check
/// does not descend into the XObject to confirm `/Subtype /Image`.
pub fn is_scanned(&self) -> Result<bool> {
crate::parser::scan_detect::is_scanned(self)
}
}