Modify selected pages on a pdf — pdf

pdf_apply() renders each page of a pdf as a raster image and on selected pages additionally calls bm_fn() to modify those raster images as well as grid_fn overlay custom graphics on top.

Usage

pdf_apply(
  input,
  output = NULL,
  ...,
  pages = "all",
  rasterize = rasterise,
  dpi = getOption("pnpmisc.dpi", 300),
  paper = NULL,
  bg = "white",
  scale = 1,
  bm_fn = identity,
  grid_fn = grid::grid.null,
  rasterise = NULL
)

Arguments

input

Input pdf filename.

output

Output pdf filename. NULL defaults to tempfile(fileext = ".pdf").

...

Ignored.

pages

A positive numeric vector of pages to include, a negative numeric vector of pages to exclude, or a string:

all: Include all the pages.
even: Include just the even pages.
odd: Include just the odd pages.

The functions pdf_pages() and pdf_subset() also support the string:

2-up saddle stitch: The order of the pages to create a saddle-stitch booklet if printing 2-up.
interleave: Interleave the first and second halves of the pages. Requires an even number of pages.
interleave_first: Repeat the first page n - 1 times and interleave with the remaining n - 1 pages.
interleave_last: Repeat the last page n - 1 times and interleave with the first n - 1 pages.

rasterize, rasterise

If TRUE rasterize the original content using pdftools::pdf_render_page(). If FALSE don't rasterize the original content and throw an error if a requested feature can not yet be implemented without rasterization. If NULL only rasterize if a requested feature requires it. Currently requires rasterization in the following cases:

(!is.null(paper) or scale != 1) and ghostscript is unavailable (see pdf_gs())
any(pages != "all") and !identical(grid_fn, grid::grid.null)
!identical(bm_fn, identity)

rasterise is an alias for rasterize.

dpi

Dots per inch. Passed to pdftools::pdf_render_page() when we rasterize the original content. Defaults to getOption("pnpmisc.dpi", 300).

paper

If NULL (default) the output pdf will be the same size as the input pdf. Otherwise the output pdf will be created with this paper size (see pdf_pad_paper() for supported values but most commonly "letter" or "a4").

bg

output pdf background color.

scale

A numeric scalar to scale the content by. Values less than 1 shrink the content within the page; values greater than 1 enlarge it. By default the original content is not rescaled. Note this also adjusts the size of the grid::viewport() the grid_fn will draw in.

bm_fn

A one-argument function called to edit the selected pages rasterized. The input will be a "raster" object and the output must be an object coercible to a "raster" object by grDevices::as.raster()

grid_fn

A zero-argument function called to draw graphics on selected pages. Defaults to grid::grid.null().

Value

output pdf file name invisibly. As a side effect creates a pdf with overlaid graphics.

Details

The original pdf document may be rasterized depending on the value of bm_fn, pages, paper, scale, and/or rasterize as well as whether ghostscript is available (see pdf_gs()).

Examples

f1 <- pdf_create_blank(length = 2L, paper = "letter", bg = "magenta")
if (requireNamespace("bittermelon", quietly = TRUE)) {
  f2 <- pdf_apply(f1, pages = "even", dpi = 75,
                  bm_fn = bittermelon::bm_invert,
                  grid_fn = function() {
                      grid::grid.text("DRAFT", gp = grid::gpar(col = "red",
                                      fontsize = 72, alpha = 0.3))
                  })
  unlink(f2)
}
#> The original pdf contents were rasterized.
#> ℹ `any(pages != "all")` but `qpdf::pdf_overlay_stamp()` does not support a `pages` argument as of v1.4.1.
#> ℹ We needed to edit the contents with a bitmap function.`
#> ℹ Suppress this message with `suppressMessages(expr, classes = "pnpmisc_message_rasterized")`.
unlink(f1)