pdfium-impl-page-objects-edit

What this skill covers

A PDF page holds a collection of page objects: text, path, image, shading, and XObject form objects. This skill covers MUTATING that collection: creating objects, adding and removing them, transforming them with a PdfMatrix, and relocating them between pages with PdfPageGroupObject and the copy_to_page / move_to_page methods.

For reading and inspecting existing page objects see pdfium-syntax-page-objects. For copying whole pages between documents see pdfium-impl-multi-page. For PdfPoints and coordinate geometry see pdfium-core-coordinates. Default API surface here is 0.9.x.

Quick reference

Goal	Call
Get a mutable collection	`page.objects_mut()`
Create and add an image in one step	`objects.create_image_object(x, y, &image, w, h)`
Create and add a bezier path	`objects.create_path_object_bezier(...)`
Build a detached image object	`PdfPageImageObject::new(&document, &image)`
Attach a detached object	`objects.add_image_object(obj)` / `add_path_object(obj)`
Remove an object	`objects.remove_object(obj)` / `remove_object_at_index(i)`
Transform an object	`object.apply_matrix(matrix)`
Relocate an object	`object.copy_to_page(&mut page)` / `move_to_page(&mut page)`

ALWAYS call objects_mut() to mutate. objects() returns an immutable &PdfPageObjects; the create_, add_, and remove_ methods all take &mut self and will not compile against it.

Two ways to create an object

pdfium-render offers two distinct construction styles. NEVER mix them for the same object.

Style A : `create_*` (build and add in one call)

The create_* methods on PdfPageObjects build the object AND add it to the page, returning the added PdfPageObject:

use pdfium_render::prelude::*;

let object = page.objects_mut().create_image_object(
    PdfPoints::new(100.0),   // x
    PdfPoints::new(500.0),   // y
    &image,                  // an image::DynamicImage
    Some(PdfPoints::new(200.0)),  // width
    Some(PdfPoints::new(150.0)),  // height
)?;

Path variants: create_path_object_line, create_path_object_bezier, create_path_object_rect, create_path_object_circle, create_path_object_circle_at, create_path_object_ellipse, create_path_object_ellipse_at. Also create_text_object.

Style B : `new` then `add_*` (build detached, then attach)

PdfPageImageObject constructors build a detached object bound to a document. A separate add_image_object call attaches it to a page:

let object = PdfPageImageObject::new_from_jpeg_file(&document, "logo.jpg")?;
let added = page.objects_mut().add_image_object(object)?;

NEVER call both a create_* method and an add_* method for the same object: create_* already added it. A second add_* adds a duplicate or fails.

PdfPageImageObject constructors

Constructor	Use
`new(&document, &image)`	image at its natural size
`new_with_width(&document, &image, width)`	width fixed, height from aspect ratio
`new_with_height(&document, &image, height)`	height fixed, width from aspect ratio
`new_with_size(&document, &image, width, height)`	exact size
`new_from_jpeg_file(&document, path)`	load straight from a JPEG file (0.8.29)
`new_from_jpeg_reader(&document, reader)`	load from any `Read + Seek` (0.8.29)

Every constructor returns Result<PdfPageImageObject, PdfiumError> and takes the PdfDocument the object will belong to. Use set_image() to replace the image, get_raw_image() / get_processed_image() to read it back.

Transforming an object with PdfMatrix

A PdfPageObject carries a transformation matrix. Apply a PdfMatrix with apply_matrix:

use pdfium_render::prelude::*;

let matrix = PdfMatrix::IDENTITY
    .scale(2.0, 2.0)?
    .rotate_clockwise_degrees(45.0)?;
object.apply_matrix(matrix)?;

PdfMatrix factory methods (translate, scale, rotate_clockwise_degrees, rotate_counter_clockwise_degrees, flip_horizontally, flip_vertically) each return Result<PdfMatrix, PdfiumError>, so chain them with ?.

Method on a page object	Effect
`apply_matrix(matrix)`	compose `matrix` onto the object's current transform
`transform(a, b, c, d, e, f)`	apply a raw six-value matrix
`reset_matrix(matrix)`	replace the object's transform
`reset_matrix_to_identity()`	clear the transform
`matrix()`	read the current transform

Version trap: set_matrix() was deprecated in 0.8.15 and removed in 0.9.0. ALWAYS use apply_matrix() (or reset_matrix() to replace rather than compose).

Removing objects

// By value : you must own the PdfPageObject
let removed = page.objects_mut().remove_object(object)?;
// By index
let removed = page.objects_mut().remove_object_at_index(0)?;

Both return the removed PdfPageObject. Version trap: the 0.6.x names delete_object / delete_object_at_index were renamed to remove_object / remove_object_at_index in 0.7.4.

Relocating objects between pages

NEVER hand-roll object moving as remove-from-page-A then add-to-page-B. That pattern fights the borrow checker, because removing requires a mutable borrow of one page's objects while inserting requires a mutable borrow of another (issues #60, #25). ALWAYS use the dedicated relocation methods.

Method	Source	Effect
`object.copy_to_page(&mut page)`	a single `PdfPageObject`	duplicate onto `page`
`object.move_to_page(&mut page)`	a single `PdfPageObject`	move onto `page`
`group.copy_to_page(&mut page)`	a `PdfPageGroupObject`	duplicate the whole group
`group.move_to_page(&mut page)`	a `PdfPageGroupObject`	move the whole group

PdfPageGroupObject collects several objects so one transform or one relocation applies to all of them at once. Build a group with objects.create_group(...) or create_empty_group(), then call apply_matrix, copy_to_page, move_to_page, or move_to_annotation on the group.

Version trap: the PdfPageGroupObject::copy_onto_new_page_* methods were removed in 0.9.0. ALWAYS use copy_to_page().

Common failures (quick triage)

Symptom	Likely cause	Fix
compile error: method takes `&mut self`	called a mutator on `objects()`	use `objects_mut()`
compile error: `set_matrix` not found	removed 0.9.0 name	use `apply_matrix()`
compile error: `copy_onto_new_page` not found	removed 0.9.0 name	use `copy_to_page()`
compile error: `delete_object` not found	renamed in 0.7.4	use `remove_object()`
borrow-checker error moving an object	hand-rolled remove-then-insert	use `move_to_page()`
`CannotMoveObjectAcrossDocuments`	`move_to_page` targeted another document's page	see `pdfium-impl-multi-page`
duplicate object on the page	both `create_` and `add_` called	use exactly one construction style

Reference files

references/methods.md: complete signatures for PdfPageObjects, PdfPageImageObject, PdfMatrix, PdfPageGroupObject, and the object transform methods, with version annotations.
references/examples.md: verified editing code, from stamping an image to moving objects between pages.
references/anti-patterns.md: real editing failures, why each fails, and the fix.

Companion skills

pdfium-syntax-page-objects: reading and inspecting existing page objects.
pdfium-impl-multi-page: copying whole pages between documents.
pdfium-core-coordinates: PdfPoints, PdfRect vs PdfQuadPoints.
pdfium-impl-saving: persisting the edited document.