A fast, helpful, and open-source document parser
//! Typed, borrowed access to a page's content objects: pdfium's page-object API
//! (`FPDFPage_GetObject`, `FPDFPageObj_*`, `FPDFFormObj_*`, `FPDFPath_*`,
//! `FPDFImageObj_*`) as thin accessors over one handle.
//!
//! [`Page::path_objects`] and [`Page::image_objects`] walk objects with this crate's
//! own rules (form recursion depth, size filters, viewport transforms). A caller
//! that has to reproduce *another* extractor's walk — which forms to descend, how
//! matrices compose, what an object's bounds mean — needs the objects themselves.
//! Every method here is one pdfium call with no policy on top: geometry is left in
//! the space pdfium reports it in, failures are `None`, and nothing is filtered.
//!
//! [`Page::path_objects`]: crate::Page::path_objects
//! [`Page::image_objects`]: crate::Page::image_objects
use std::marker::PhantomData;
use crate::bitmap::Bitmap;
use crate::ffi;
use crate::library::Library;
use crate::page::{Page, SegmentKind, image_object_data, read_color};
use crate::types::{Color, Matrix, RectF};
/// What a page object draws (`FPDFPageObj_GetType`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PageObjectKind {
Text,
Path,
Image,
Shading,
/// A Form XObject: a container whose children are reached through
/// [`PageObject::form_object`].
Form,
Unknown,
}
/// `FPDFPath_GetDrawMode`: whether a path is painted at all. A path that is
/// neither filled nor stroked is a clipping path.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PathDrawMode {
/// Fill mode is not `FPDF_FILLMODE_NONE`.
pub filled: bool,
pub stroked: bool,
}
/// One path segment exactly as pdfium reports it: the point is in the object's own
/// coordinate space (apply [`PageObject::matrix`] to reach the page), `kind` is
/// `None` for `FPDF_SEGMENT_UNKNOWN`, `point` is `None` when
/// `FPDFPathSegment_GetPoint` fails.
#[derive(Debug, Clone, Copy)]
pub struct RawPathSegment {
pub kind: Option<SegmentKind>,
pub point: Option<(f32, f32)>,
/// Whether this segment closes the current subpath.
pub close: bool,
}
/// `FPDF_IMAGEOBJ_METADATA`: facts about an image object's pixels. The DPI values
/// are the image's effective resolution as placed on its page.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ImageMetadata {
pub width: u32,
pub height: u32,
pub horizontal_dpi: f32,
pub vertical_dpi: f32,
pub bits_per_pixel: u32,
/// An `FPDF_COLORSPACE_*` value.
pub colorspace: i32,
/// `-1` when the image is not in marked content.
pub marked_content_id: i32,
}
/// One content object of a page, borrowed for `'page`.
///
/// Objects inside a Form XObject are reached through [`PageObject::form_object`]
/// and carry the same borrow: pdfium owns every object for as long as the page is
/// loaded, so none can outlive it.
pub struct PageObject<'page, 'lib> {
handle: pdfium_sys::FPDF_PAGEOBJECT,
page: pdfium_sys::FPDF_PAGE,
_page: PhantomData<&'page ()>,
_lib: PhantomData<&'lib Library>,
}
impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {
/// Number of top-level content objects (`FPDFPage_CountObjects`), 0 on error.
pub fn object_count(&self) -> usize {
let count = unsafe { ffi!(FPDFPage_CountObjects(self.handle)) };
usize::try_from(count).unwrap_or(0)
}
/// The top-level content object at `index`, in content-stream order.
pub fn object(&self, index: usize) -> Option<PageObject<'_, 'lib>> {
let index = std::os::raw::c_int::try_from(index).ok()?;
let handle = unsafe { ffi!(FPDFPage_GetObject(self.handle, index)) };
(!handle.is_null()).then_some(PageObject {
handle,
page: self.handle,
_page: PhantomData,
_lib: PhantomData,
})
}
}
impl<'page, 'lib> PageObject<'page, 'lib> {
/// An identity for this object that is stable while the page is loaded, so a
/// caller can tell "the same form" apart from "a different form" across two
/// visits without holding the object.
pub fn id(&self) -> usize {
self.handle as usize
}
pub fn kind(&self) -> PageObjectKind {
match unsafe { ffi!(FPDFPageObj_GetType(self.handle)) } as u32 {
pdfium_sys::FPDF_PAGEOBJ_TEXT => PageObjectKind::Text,
pdfium_sys::FPDF_PAGEOBJ_PATH => PageObjectKind::Path,
pdfium_sys::FPDF_PAGEOBJ_IMAGE => PageObjectKind::Image,
pdfium_sys::FPDF_PAGEOBJ_SHADING => PageObjectKind::Shading,
pdfium_sys::FPDF_PAGEOBJ_FORM => PageObjectKind::Form,
_ => PageObjectKind::Unknown,
}
}
/// Clip paths in the containing form's coordinates (page coordinates at the
/// top level). The object's own matrix is already applied to clip points.
/// No clip is an empty list; unavailable APIs, failed reads, or more than
/// 1024 segments return `None`. Text-based clipping is not exposed by PDFium.
pub fn clip_paths(&self) -> Option<Vec<Vec<RawPathSegment>>> {
#[cfg(not(target_arch = "wasm32"))]
let (get_clip, count_paths, count_segments, get_segment) = {
let api = pdfium_sys::dynamic::pdfium();
(
api.FPDFPageObj_GetClipPath?,
api.FPDFClipPath_CountPaths?,
api.FPDFClipPath_CountPathSegments?,
api.FPDFClipPath_GetPathSegment?,
)
};
#[cfg(target_arch = "wasm32")]
let (get_clip, count_paths, count_segments, get_segment) = (
pdfium_sys::FPDFPageObj_GetClipPath,
pdfium_sys::FPDFClipPath_CountPaths,
pdfium_sys::FPDFClipPath_CountPathSegments,
pdfium_sys::FPDFClipPath_GetPathSegment,
);
let clip = unsafe { get_clip(self.handle) };
if clip.is_null() {
return None;
}
let count = unsafe { count_paths(clip) };
// PDFium returns -1 for an object with no clip-path reference.
if count == -1 {
return Some(Vec::new());
}
if !(0..=1024).contains(&count) {
return None;
}
let mut paths = Vec::new();
let mut budget = 1024;
for path in 0..count {
let count = unsafe { count_segments(clip, path) };
if count < 0 || count > budget {
return None;
}
budget -= count;
let mut segments = Vec::new();
for index in 0..count {
let segment = unsafe { get_segment(clip, path, index) };
if segment.is_null() {
return None;
}
let kind = match unsafe { ffi!(FPDFPathSegment_GetType(segment)) } {
t if t == pdfium_sys::FPDF_SEGMENT_MOVETO as i32 => Some(SegmentKind::MoveTo),
t if t == pdfium_sys::FPDF_SEGMENT_LINETO as i32 => Some(SegmentKind::LineTo),
t if t == pdfium_sys::FPDF_SEGMENT_BEZIERTO as i32 => {
Some(SegmentKind::BezierTo)
}
_ => None,
};
let mut x = 0.0;
let mut y = 0.0;
if unsafe { ffi!(FPDFPathSegment_GetPoint(segment, &mut x, &mut y)) } == 0 {
return None;
}
segments.push(RawPathSegment {
kind,
point: Some((x, y)),
close: unsafe { ffi!(FPDFPathSegment_GetClose(segment)) } != 0,
});
}
paths.push(segments);
}
Some(paths)
}
/// The object's transformation matrix (`FPDFPageObj_GetMatrix`). For an object
/// inside a form this is relative to the form, not the page. `None` when pdfium
/// reports none — normal for a shading object without a clip path.
pub fn matrix(&self) -> Option<Matrix> {
let mut m = pdfium_sys::FS_MATRIX {
a: 1.0,
b: 0.0,
c: 0.0,
d: 1.0,
e: 0.0,
f: 0.0,
};
let ok = unsafe { ffi!(FPDFPageObj_GetMatrix(self.handle, &mut m)) };
(ok != 0).then_some(Matrix {
a: m.a,
b: m.b,
c: m.c,
d: m.d,
e: m.e,
f: m.f,
})
}
/// The object's bounding box (`FPDFPageObj_GetBounds`) in the space pdfium
/// reports it in — its own matrix applied, ancestor form matrices not — as a
/// y-up rect (`top > bottom`).
pub fn bounds(&self) -> Option<RectF> {
let mut left = 0.0f32;
let mut bottom = 0.0f32;
let mut right = 0.0f32;
let mut top = 0.0f32;
let ok = unsafe {
ffi!(FPDFPageObj_GetBounds(
self.handle,
&mut left,
&mut bottom,
&mut right,
&mut top
))
};
(ok != 0).then_some(RectF {
left,
top,
right,
bottom,
})
}
/// Number of objects inside a Form XObject (`FPDFFormObj_CountObjects`); `None`
/// when this is not a form or pdfium reports an error.
pub fn form_object_count(&self) -> Option<usize> {
let count = unsafe { ffi!(FPDFFormObj_CountObjects(self.handle)) };
usize::try_from(count).ok()
}
/// The child at `index` of a Form XObject, in content-stream order.
pub fn form_object(&self, index: usize) -> Option<PageObject<'page, 'lib>> {
let index = std::os::raw::c_ulong::try_from(index).ok()?;
let handle = unsafe { ffi!(FPDFFormObj_GetObject(self.handle, index)) };
(!handle.is_null()).then_some(PageObject {
handle,
page: self.page,
_page: PhantomData,
_lib: PhantomData,
})
}
/// A path's fill/stroke mode (`FPDFPath_GetDrawMode`); `None` for non-paths.
pub fn path_draw_mode(&self) -> Option<PathDrawMode> {
let mut fill_mode = 0i32;
let mut stroke = 0i32;
let ok = unsafe {
ffi!(FPDFPath_GetDrawMode(
self.handle,
&mut fill_mode,
&mut stroke
))
};
(ok != 0).then_some(PathDrawMode {
filled: fill_mode != pdfium_sys::FPDF_FILLMODE_NONE as i32,
stroked: stroke != 0,
})
}
/// Line width in the object's own space (`FPDFPageObj_GetStrokeWidth`).
pub fn stroke_width(&self) -> Option<f32> {
let mut width = 0.0f32;
let ok = unsafe { ffi!(FPDFPageObj_GetStrokeWidth(self.handle, &mut width)) };
(ok != 0).then_some(width)
}
/// `FPDFPageObj_GetStrokeColor`; `None` when the object has no RGB stroke colour
/// (a pattern, or pdfium could not resolve the colour space).
pub fn stroke_color(&self) -> Option<Color> {
read_color(|r, g, b, a| unsafe {
ffi!(FPDFPageObj_GetStrokeColor(self.handle, r, g, b, a))
})
}
/// `FPDFPageObj_GetFillColor`; `None` on the same terms as [`Self::stroke_color`].
pub fn fill_color(&self) -> Option<Color> {
read_color(|r, g, b, a| unsafe { ffi!(FPDFPageObj_GetFillColor(self.handle, r, g, b, a)) })
}
/// Number of segments in a path (`FPDFPath_CountSegments`); `None` for non-paths.
pub fn path_segment_count(&self) -> Option<usize> {
let count = unsafe { ffi!(FPDFPath_CountSegments(self.handle)) };
usize::try_from(count).ok()
}
/// The segment at `index`, or `None` when pdfium has no segment there.
pub fn path_segment(&self, index: usize) -> Option<RawPathSegment> {
let index = std::os::raw::c_int::try_from(index).ok()?;
let segment = unsafe { ffi!(FPDFPath_GetPathSegment(self.handle, index)) };
if segment.is_null() {
return None;
}
let kind = match unsafe { ffi!(FPDFPathSegment_GetType(segment)) } {
t if t == pdfium_sys::FPDF_SEGMENT_MOVETO as i32 => Some(SegmentKind::MoveTo),
t if t == pdfium_sys::FPDF_SEGMENT_LINETO as i32 => Some(SegmentKind::LineTo),
t if t == pdfium_sys::FPDF_SEGMENT_BEZIERTO as i32 => Some(SegmentKind::BezierTo),
_ => None,
};
let mut x = 0.0f32;
let mut y = 0.0f32;
let ok = unsafe { ffi!(FPDFPathSegment_GetPoint(segment, &mut x, &mut y)) };
let close = unsafe { ffi!(FPDFPathSegment_GetClose(segment)) } != 0;
Some(RawPathSegment {
kind,
point: (ok != 0).then_some((x, y)),
close,
})
}
/// An image's pixel facts (`FPDFImageObj_GetImageMetadata`, which needs the page
/// to work out the effective DPI); `None` for non-images or on failure.
pub fn image_metadata(&self) -> Option<ImageMetadata> {
let mut metadata = pdfium_sys::FPDF_IMAGEOBJ_METADATA::default();
let ok = unsafe {
ffi!(FPDFImageObj_GetImageMetadata(
self.handle,
self.page,
&mut metadata
))
};
(ok != 0).then_some(ImageMetadata {
width: metadata.width,
height: metadata.height,
horizontal_dpi: metadata.horizontal_dpi,
vertical_dpi: metadata.vertical_dpi,
bits_per_pixel: metadata.bits_per_pixel,
colorspace: metadata.colorspace,
marked_content_id: metadata.marked_content_id,
})
}
/// Number of filters on an image's stream (`FPDFImageObj_GetImageFilterCount`);
/// `None` for non-images or on error.
pub fn image_filter_count(&self) -> Option<usize> {
let count = unsafe { ffi!(FPDFImageObj_GetImageFilterCount(self.handle)) };
usize::try_from(count).ok()
}
/// The filter name at `index` (`DCTDecode`, `FlateDecode`, …), however long;
/// `None` when pdfium reports nothing for that index.
pub fn image_filter(&self, index: usize) -> Option<String> {
let index = std::os::raw::c_int::try_from(index).ok()?;
let size = unsafe {
ffi!(FPDFImageObj_GetImageFilter(
self.handle,
index,
std::ptr::null_mut(),
0
))
};
if size == 0 {
return None;
}
let mut bytes = vec![0u8; size as usize];
let written = unsafe {
ffi!(FPDFImageObj_GetImageFilter(
self.handle,
index,
bytes.as_mut_ptr().cast(),
size
))
};
if written == 0 {
return None;
}
let end = bytes.iter().position(|b| *b == 0).unwrap_or(bytes.len());
Some(String::from_utf8_lossy(&bytes[..end]).into_owned())
}
/// The image stream's bytes as stored, every filter still applied
/// (`FPDFImageObj_GetImageDataRaw`).
pub fn image_data_raw(&self) -> Option<Vec<u8>> {
image_object_data(self.handle, false)
}
/// The image stream after pdfium undoes its lossless filters
/// (`FPDFImageObj_GetImageDataDecoded`): for a `DCTDecode` image this is the
/// JPEG file itself.
pub fn image_data_decoded(&self) -> Option<Vec<u8>> {
image_object_data(self.handle, true)
}
/// The image's own pixels at their stored size (`FPDFImageObj_GetBitmap`) — not
/// rendered through the object's matrix, unlike `FPDFImageObj_GetRenderedBitmap`.
/// The format is whatever pdfium decoded to; read [`Bitmap::format`] before the
/// buffer.
pub fn image_bitmap(&self) -> Option<Bitmap<'lib>> {
let handle = unsafe { ffi!(FPDFImageObj_GetBitmap(self.handle)) };
if handle.is_null() {
return None;
}
// SAFETY: a freshly created bitmap we own; `'lib` is the page's lock lifetime.
Some(unsafe { Bitmap::from_handle(handle) })
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::Library;
use crate::bitmap::BitmapFormat;
/// A one-page PDF with, in content order: a filled rectangle under a translation,
/// a Form XObject holding one stroked rectangle, and a 2×2 8-bit grey image.
fn objects_pdf() -> Vec<u8> {
fn stream(dict: &str, data: &[u8]) -> Vec<u8> {
let mut out = format!("<< {dict} /Length {} >>\nstream\n", data.len()).into_bytes();
out.extend_from_slice(data);
out.extend_from_slice(b"\nendstream");
out
}
let content =
b"q 1 0 0 1 10 20 cm 0 0 50 30 re f Q q /Fx1 Do Q q 40 0 0 20 100 50 cm /Im1 Do Q";
let objects: Vec<Vec<u8>> = vec![
b"<< /Type /Catalog /Pages 2 0 R >>".to_vec(),
b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>".to_vec(),
b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 100] /Contents 4 0 R /Resources << /XObject << /Im1 5 0 R /Fx1 6 0 R >> >> >>".to_vec(),
stream("", content),
stream(
"/Type /XObject /Subtype /Image /Width 2 /Height 2 /ColorSpace /DeviceGray /BitsPerComponent 8",
&[0x00, 0xff, 0xff, 0x00],
),
stream(
"/Type /XObject /Subtype /Form /BBox [0 0 100 100] /Matrix [2 0 0 2 5 5]",
b"0 0 10 10 re S",
),
];
let mut pdf = b"%PDF-1.7\n".to_vec();
let mut offsets = Vec::with_capacity(objects.len());
for (index, object) in objects.iter().enumerate() {
offsets.push(pdf.len());
pdf.extend_from_slice(format!("{} 0 obj\n", index + 1).as_bytes());
pdf.extend_from_slice(object);
pdf.extend_from_slice(b"\nendobj\n");
}
let xref = pdf.len();
pdf.extend_from_slice(format!("xref\n0 {}\n", objects.len() + 1).as_bytes());
pdf.extend_from_slice(b"0000000000 65535 f \n");
for offset in offsets {
pdf.extend_from_slice(format!("{offset:010} 00000 n \n").as_bytes());
}
pdf.extend_from_slice(
format!(
"trailer\n<< /Size {} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n",
objects.len() + 1
)
.as_bytes(),
);
pdf
}
#[test]
fn walks_path_form_and_image_objects_with_raw_accessors() {
let bytes = objects_pdf();
let library = Library::init();
let document = library.load_document_from_bytes(&bytes, None).unwrap();
let page = document.page(0).unwrap();
assert_eq!(page.object_count(), 3);
assert!(page.object(3).is_none());
let kinds: Vec<PageObjectKind> = (0..3).map(|i| page.object(i).unwrap().kind()).collect();
assert_eq!(
kinds,
[
PageObjectKind::Path,
PageObjectKind::Form,
PageObjectKind::Image
]
);
// The filled rectangle: its matrix carries the `cm`, its points are local.
let path = page.object(0).unwrap();
assert_eq!(
path.path_draw_mode(),
Some(PathDrawMode {
filled: true,
stroked: false
})
);
let m = path.matrix().unwrap();
assert_eq!((m.a, m.d, m.e, m.f), (1.0, 1.0, 10.0, 20.0));
let b = path.bounds().unwrap();
assert_eq!((b.left, b.bottom, b.right, b.top), (10.0, 20.0, 60.0, 50.0));
assert_eq!(path.fill_color().map(|c| (c.r, c.g, c.b)), Some((0, 0, 0)));
let count = path.path_segment_count().unwrap();
assert!(count >= 4);
let segments: Vec<RawPathSegment> =
(0..count).map(|i| path.path_segment(i).unwrap()).collect();
assert_eq!(segments[0].kind, Some(SegmentKind::MoveTo));
assert_eq!(segments[0].point, Some((0.0, 0.0)));
assert!(
segments
.iter()
.skip(1)
.all(|s| s.kind == Some(SegmentKind::LineTo))
);
assert!(segments.iter().any(|s| s.close));
assert!(path.path_segment(count).is_none());
assert!(path.image_metadata().is_none());
// The form: one stroked path inside, reached only through `form_object`.
let form = page.object(1).unwrap();
assert_eq!(form.form_object_count(), Some(1));
let inner = form.form_object(0).unwrap();
assert_eq!(inner.kind(), PageObjectKind::Path);
assert_eq!(
inner.path_draw_mode(),
Some(PathDrawMode {
filled: false,
stroked: true
})
);
assert_eq!(inner.stroke_width(), Some(1.0));
assert!(form.form_object(1).is_none());
assert_ne!(form.id(), inner.id());
assert_eq!(page.object(1).unwrap().id(), form.id());
// The image: metadata, no filters, raw == decoded, and its own grey pixels.
let image = page.object(2).unwrap();
let meta = image.image_metadata().unwrap();
assert_eq!((meta.width, meta.height, meta.bits_per_pixel), (2, 2, 8));
assert_eq!(
meta.colorspace,
pdfium_sys::FPDF_COLORSPACE_DEVICEGRAY as i32
);
assert_eq!(image.image_filter_count(), Some(0));
assert!(image.image_filter(0).is_none());
assert_eq!(image.image_data_raw().unwrap(), [0x00, 0xff, 0xff, 0x00]);
assert_eq!(
image.image_data_decoded().unwrap(),
[0x00, 0xff, 0xff, 0x00]
);
let bitmap = image.image_bitmap().unwrap();
assert_eq!(bitmap.format(), BitmapFormat::Gray);
assert_eq!((bitmap.width(), bitmap.height()), (2, 2));
let stride = bitmap.stride() as usize;
let buffer = bitmap.buffer();
assert_eq!(&buffer[..2], &[0x00, 0xff]);
assert_eq!(&buffer[stride..stride + 2], &[0xff, 0x00]);
assert!(page.object(0).unwrap().image_bitmap().is_none());
}
}