Images and R Code-chunk formatting

View the underlying source code to understand how this page was composed at: https://github.com/ontheline/otl-bookdown/blob/main/9.3.4-images.Rmd

NOTE: These instructions are designed primarily for the HTML web edition. Be sure to research and consider options if your primary objective is PDF print edition, ePUB electronic publication, or other formats.

In general, create high-resolution color images and save in PNG format (preferred over JPG due to image loss) into the images folder of the Bookdown repository on GitHub.

Write file names in lowercase with year-name format using dashes (not spaces or underscores). Begin with the relevant year if possible, and keywords to match bibliographic information in Zotero.

If the original image is larger than 3MB, add -original to file name to avoid confusion, then create a duplicate and use photo editor to reduce size but maintain 300 dpi resolution for use in the publication.

If adding any artwork to images, insert -annotated to file name to avoid confusion with original.

To create screenshots, use high-resolution Retina monitor (144 ppi) with tight cropping.

To combine images for side-by-sides or montages, save each element using the root file name plus a suffix. Save all elements in an images subfolder using a similar year-name format. Use either https://Canva.com or https://Photopea.com to combine images, and save a copy of the latter in Photoshop format (.psd) in the images subfolder.

Since very large PNG images sometimes appear too large in the PDF edition, convert a copy into a smaller PDF image to fit better. In Preview, open the copy and reduce image size by 50% (or more), and double resolution (up to 300 dpi if feasible), and save. Then File > Export, with Option to change file format to PDF, but keep same file name as PNG.

Save all versions of an image into the images folder to keep them together, as long as the overall GitHub repo size remains under 1GB. (Keep extremely large TIFF files elsewhere but use similar file names in order to locate them.) Bookdown will copy only the relevant files into the docs/images subfolder.

As a result, one image may have different versions:

images/1937-sample.png
images/1937-sample.pdf
images/1937-sample-original.png
images/1937-sample-annotated.psd

Include relevant source info in the Zotero library, and include the file name in the Abstract field to manually match up with the manuscript. Since Bookdown does not cleanly process endnotes in image captions, include the Zotero citation at the end of the main-text paragraph that describes the image, typically after a call-out: …as shown in Figure X.

For the image caption, write a brief standalone description, add an action-instruction and supplemental link for any visualizations, and include any relevant image source credits or copyright information.

In writing this book, one of key goals was to create R Markdown syntax to display different versions of images for different Bookdown editions. For each image, we wanted one set of instructions to display an interactive chart/map/video using an embedded iframe in the HTML web edition, but display a static PNG image in the full-length Markdown edition, or to substitute a smaller PDF static image when available in the PDF book edition. Also, we wanted auto-numbering of images by chapter.

Our solution relies on R code-chunk formatting for most images, with some exceptions. This R Markdown/Bookdown syntax is more complex than basic Markdown image formatting, but supports conditional formatting and captions in all of our editions, and auto-numbering in HMTL and LaTeX/PDF editions. Our general R code-chunk image format looks roughly like this, minus some code tics that have been removed for simplicity:

...as shown in Figure \@ref(fig:keyword).

(ref:keyword) Caption, with optional Markdown links and image credits, but no endnotes.

{r keyword, fig.cap="(ref:keyword)"}
if(knitr::is_html_output(excludes="markdown")) knitr::include_url("http://pathname-to-interactive-version-keyword.html")
else knitr::include_graphics("pathname-to-static-version-keyword.png")

The first line generates an auto-numbered and clickable figure cross-reference call-out. Auto-numbering appears in Figure x.x format in HTML, PDF, and Word, but Figure x format in Markdown. (Word auto-number formatting can be changed with a reference.docx file.) This call-out is important because images in PDF output will “float” by design and may appear before or after the desired page.

The second line contains the caption, with optional links in Markdown format. But do not insert endnotes with Zotero citation keys, since those will cause errors in the PDF edition. Insert detailed endnotes about sources for images in the body of the text, and use the caption for only a brief image credits and any copyright notice.

The third block is the R code-chunk. (In practice, the code-chunk is set off from the other two lines using 3 code tic marks, as shown in later demos, which we omitted here for simplicity.) The first portion references keyword in the call-out and also the caption above. The latter portion may simply instruct Bookdown to include a static image (when there is no interactive version), or it may include an if-else statement for conditional formatting when both interactive and static versions exist.

The if statement for HTML output contains (excludes="markdown") because markdown is considered an HTML format, as described in the R Markdown Cookbook. Since the publisher’s platform will accept a full-length Markdown version of the book, which displays static images rather than interactive visualizations, we need to generate the “markdown” file differently than the HTML web edition.

Write R code-chunk labels that use the same year and keywords as the image file name. Avoid duplicate labels across the book. Use only letters, numbers, and hyphens (not underscores):

ref:1901-keywords-with-hyphens

images/1901-keywords-with-hyphens.png

Do not insert spaces inside the ref:chunk-label for the caption. But do add a blank line to separate it from the code-chunk. After the code-chunk, add another blank line to avoid “undefined reference” Bookdown errors.

Inside the R code-chunk ref caption, do NOT use mischievous characters (such as < or > or ") that will throw HTML errors into the Markdown output images. Do not insert footnotes in the R code-chunk ref caption, which will throw PDF errors.

Our Bookdown index.Rmd file includes global R code-chunk settings immediately after the first header. One setting displays each code-chunk image without a code echo, meaning that only the image is displayed, and not the code used to generate that image. The other setting automatically inserts the PDF version of an PNG/JPG image, whenever it exists, in the PDF output, which allows us to manually reduce the size of large images displayed in the PDF book. Read more about these options in this Bookdown chapter: https://bookdown.org/yihui/bookdown/figures.html.

{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)
options(knitr.graphics.auto_pdf = TRUE)

Demo: R code-chunk for static image for all editions: HTML, PDF, DOCX, MD

…as shown in Figure 9.4.

Caption with optional Markdown links but no endnotes. Source: “Hippo and crocodile” by Stig Nygaard, CC-BY.

Figure 9.4: Caption with optional Markdown links but no endnotes. Source: “Hippo and crocodile” by Stig Nygaard, CC-BY.

Demo: R code-chunk to reduce size of static image for all editions

First, create a copy of the original PNG image. Use Preview or any image editor to reduce size by 50 percent or more, and if needed, increase the resolution (from 72 to 144 dpi or higher), and save. Export as PDF image with same filename as PNG file, to produce two image files: keyword.png (original) and keyword.pdf (smaller size). The global setting will auto-substitute the smaller PDF image in place of the original PNG image.

Second, insert an out.width=... in the second line to reduce the PNG display size as needed in the HTML edition. Note that this method keeps the original PNG image intact, which is ideal when working with historical images of a reasonable file size. Images larger than 3MB may be delayed in the HTML web edition for readers with slow internet connections.

…as shown in Figure 9.5.

This version reduces HTML display size using out.width=300 and auto-substitutes a smaller PDF image. Source: “Hippo and crocodile” by Stig Nygaard, CC-BY.

Figure 9.5: This version reduces HTML display size using out.width=300 and auto-substitutes a smaller PDF image. Source: “Hippo and crocodile” by Stig Nygaard, CC-BY.

R code-chunks allow more complex conditional formatting, where an interactive map or animated GIF or streaming video clip appears in the HTML version, and a manually-produced static image with an embedded link appears in the PDF, MS Word, and full-length Markdown outputs. To change the height of the default 400px iframe, add the new height to include_url as shown in the examples. (Note: Changing the width of the default 675px iframe to less than 100 percent requires adding a line in a custom-scripts.html file, and including this in the index.Rmd file).

Demo: R code-chunk for iframe in HTML, static image in PDF, DOCX, MD

…as shown in Figure 9.6.

Figure 9.6: Explore the full-size interactive map, which enables readers of non-HTML editions to view it. View open-source code and historical sources, developed by list-authors-here.

Demo: R code-chunk for locally-stored scrolling PDF in HTML, static screenshot in PDF, DOCX, MD

Be sure to add “screenshot” to the file name of the static PNG to avoid confusing it with the scrolling PDF, in case the static PNG is converted into a static PDF for better image quality in the PDF book output.

Note: Currently in 2021 this displays a scrolling PDF in Firefox, Chrome, but not Safari browser. Insert link to local PDF in the caption to provide workaround for readers with Safari browsers.

…as shown in Figure 9.7.

Figure 9.7: Explore the sample PDF that is locally stored in the GitHub repo, with option to add more Markdown links.

Demo: R code-chunk for animated GIF in HTML, static image in PDF, DOCX, MD

When appropriate, create animated GIF files using the free Giphy Capture or the paid Camtasia application, which allows the option to add fade-to-black to mark the end-point in the looped version.

…as shown in Figure 9.8.

Figure 9.8: View the animated GIF, which enables readers of non-HTML editions to view it.

Note about CTDA Videos

As of 2020, videos uploaded to CTDA have datastreams generated in MP4 video format, but these run in auto-play format in the browser, which CTDA cannot turn off, so are not appropriate to display in the browser in this book. See sample video datastream: https://collections.ctdigitalarchive.org/islandora/object/120002:172/datastream/MP4 and read more https://confluence.uconn.edu/display/CTDA/Datastreams. Therefore, CTDA should be used as a historical preservation video server, but must use either YouTube, Vimeo, or Kaltura examples above to display secondary video clips for display in this book.

Demo: R code-chunk for YouTube video in HTML, static image in PDF, DOCX, MD

Be sure to use the embed link from a YouTube or Vimeo share button.

…as shown in the video 9.9.

Figure 9.9: View the YouTube video, which enables readers of non-HTML editions to view it. YouTube formatting in Bookdown seems cleaner than Vimeo formatting. Add link to full video on a historical preservation server (such as CTDA) to avoid auto-play issue.

Demo: R code-chunk for Kaltura video in HTML edition, static image in PDF, DOCX, MD

  • Work with Trinity Library to upload items to their Kaltura Hartford History channel or your personal channel.
  • Go to Kaltura video entry > share button > embed, extract the long URL, and paste in R code-chunk below.
  • Option: This method allows you to select a video start time, such as 8:00, which will be appended to the embed code URL in seconds like this: [mediaProxy.mediaPlayFrom]=480"
  • This method successfully avoids auto-play in Mac browsers. TODO: test in Windows browsers and other devices.
  • Note: If you paste the long URL directly into a modern browser, the early portion of the link transforms into HTML5-specific code, which you also could use if needed.
  • TODO: Since Kaltura player setup auto-displays captions, which are faulty in the automated video upload process, need to insert corrected captions directly from the transcript. Prioritize videos that need caption revisions.

…as shown in Figure 9.10.

Figure 9.10: Here’s a sample caption for a video on Trinity Kaltura server. Option to add Markdown link to historical preservation version in CTDA.

Demo: R code-chunk for streaming video ONLY in HTML

This option is useful if you wish to display a video only in the HTML edition, with no screenshot in the other editions. Note that this will alter figure auto-numbering between the HTML and other editions. To avoid auto-numbering issues, use conventional iframe formatting without the R code-chunk.

Figure 9.11: Caption only appears in HTML version. View link to YouTube video.

Demo: Markdown image formatting without auto-numbering, for all editions

While we normally use R code-chunk image formatting, there are some exceptions. For example, we use Markdown formatting for tables or grids of images that are relatively small and do not require captions or auto-numbering.

When creating images to appear as the same size in sequence, temporarily add a code-comment with the image width, height, and resolution as a reminder to match up with others, as shown below. Use PNG images (rather than JPG), and if appropriate, add a numerical suffix to the filename (image-200.png) to distinguish this 200px-wide version from the larger original.

<!-- Images below are 200x200 at 300 resolution -->

Co-Authors About Us
About Jack Dougherty
About Ilya Ilyankou
footer