vignettes/cairohacks.Rmd

   1 ---
   2 title: "CairoHacks: Bookmarks and Rasters"
   3 author: "Don Armstrong"
   4 output:
   5     html_document:
   6         toc: TRUE
   7 vignette: >
   8   %\VignetteIndexEntry{CairoHacks}
   9   %\VignetteEngine{knitr::knitr}
  10   \usepackage[utf8]{inputenc}
  11 ---
  12
  13 ```{r setup, include=FALSE}
  14 knitr::opts_chunk$set(echo=TRUE)
  15 ```
  16
  17 # Bookmarks
  18
  19 CairoHacks allows you to create bookmarks in PDF documents. This
  20 requires the use of pdftk to actually create the bookmarks at the end
  21 of the pdf creation.
  22
  23 Here is a simple example:
  24
  25 ```{r, eval=FALSE}
  26      Cairo::CairoPDF(file="example.pdf",onefile=TRUE)
  27      plot(y~x,data.frame(x=1:5,y=1:5))
  28      bookmarks <- make.pdf.bookmark("First plot")
  29      plot(y~x,data.frame(x=1:5,y=1:5))
  30      bookmarks <- bookmarks + make.pdf.bookmark("Second plot")
  31      dev.off()
  32      write.pdf.bookmarks(file="example.pdf",bookmarks)
  33 ```
  34
  35 This will create two bookmarks in the file `example.pdf` named "First
  36 plot" and "Second plot" which point to the first and second pages,
  37 respectively.
  38
  39 Bookmarks requires the use of the CairoPDF device so that the current
  40 page number can be obtained using the onSave Cairo Hook. In the
  41 future, if other devices allow reporting the current page number, they
  42 will be supported.
  43
  44 # Raster Images
  45
  46 CairoHacks also allows you to create raster images (bitmaps) which can
  47 then be embedded into a PDF. This is very useful, because sometimes
  48 you have a huge number (millions) of points which you would like to
  49 plot on a single plot without making the resultant PDF megabytes in
  50 size. For example:
  51
  52 ```{r echo=TRUE,fig.keep="last"}
  53 library("CairoHacks")
  54 start_rasterplot(width=1024)
  55 plot(y~x,
  56      data=data.frame(y=rnorm(1E5),x=rnorm(1E5)))
  57 raster.image <- stop_rasterplot(plot=FALSE)
  58 grid::grid.raster(raster.image)
  59 ```
  60
  61 produces a plot with 10 million points, but is only 1024 pixels wide
  62 by 1024 pixels tall. (The width is 1024 by default, and the height is
  63 automatically scaled on the basis of the underlying graphics device.)