-
Notifications
You must be signed in to change notification settings - Fork 7
/
9.3.4-images.Rmd
185 lines (117 loc) · 16.3 KB
/
9.3.4-images.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
## Images and R Code-chunk formatting {- #images}
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](https://bookdown.org/yihui/rmarkdown-cookbook/latex-html.html). 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 \@ref(fig:sample-image).
(ref:sample-image) Caption with optional Markdown links but no endnotes. Source: "Hippo and crocodile" by [Stig Nygaard](https://www.flickr.com/photos/10259776@N00), CC-BY.
```{r sample-image, fig.cap="(ref:sample-image)"}
knitr::include_graphics("images/bookdown/sample-image.png")
```
### 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 \@ref(fig:sample-image2).
(ref:sample-image2) This version reduces HTML display size using `out.width=300` and auto-substitutes a smaller PDF image. Source: "Hippo and crocodile" by [Stig Nygaard](https://www.flickr.com/photos/10259776@N00), CC-BY.
```{r sample-image2, out.width=300, fig.cap="(ref:sample-image2)"}
knitr::include_graphics("images/bookdown/sample-image2.png")
```
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 \@ref(fig:sample-map).
(ref:sample-map) [Explore the full-size interactive map](https://handsondataviz.github.io/leaflet-map-simple/), which enables readers of non-HTML editions to view it. View [open-source code and historical sources](https://github.com/ontheline), developed by list-authors-here.
```{r sample-map, fig.cap="(ref:sample-map)"}
if(knitr::is_html_output(excludes="markdown")) knitr::include_url("https://handsondataviz.github.io/leaflet-map-simple/", height = "375px") else knitr::include_graphics("images/bookdown/sample-map.png")
```
#### 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 \@ref(fig:sample-local-pdf).
(ref:sample-local-pdf) Explore the [sample PDF](images/bookdown/sample-local-pdf.pdf) that is locally stored in the GitHub repo, with option to add more Markdown links.
```{r sample-local-pdf, fig.cap="(ref:sample-local-pdf)"}
if(knitr::is_html_output(excludes="markdown")) knitr::include_url("images/bookdown/sample-local-pdf.pdf") else knitr::include_graphics("images/bookdown/sample-local-pdf-screenshot.png")
```
### 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](https://giphy.com/apps/giphycapture) or the paid [Camtasia](https://www.techsmith.com/video-editor.html) application, which allows the option to add fade-to-black to mark the end-point in the looped version.
...as shown in Figure \@ref(fig:sample-gif).
(ref:sample-gif) View the [animated GIF](https://handsondataviz.org/images/bookdown/sample.gif), which enables readers of non-HTML editions to view it.
```{r sample-gif, fig.cap="(ref:sample-gif)"}
if(knitr::is_html_output(excludes="markdown")) knitr::include_url("images/bookdown/sample-gif.gif", height = "250px") else knitr::include_graphics("images/bookdown/sample-gif.png")
```
### 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 \@ref(fig:sample-video).
(ref:sample-video) View the [YouTube video](https://youtu.be/M3_TWyva5yc), 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.
```{r sample-video, fig.cap="(ref:sample-video)"}
if(knitr::is_html_output(excludes="markdown")) knitr::include_url("https://www.youtube.com/embed/M3_TWyva5yc") else knitr::include_graphics("images/bookdown/sample-video.png")
```
#### 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](https://trincoll.mediaspace.kaltura.com/channel/Hartford%2BHistory/144729181) 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 \@ref(fig:sample-kaltura).
(ref:sample-kaltura) Here's a sample caption for a video on Trinity Kaltura server. Option to add Markdown link to historical preservation version in CTDA.
```{r sample-kaltura, fig.cap="(ref:sample-kaltura)"}
if(knitr::is_html_output(excludes="markdown")) knitr::include_url("https://cdnapisec.kaltura.com/p/2366381/sp/236638100/embedIframeJs/uiconf_id/42684261/partner_id/2366381?iframeembed=true&playerId=kplayer&entry_id=1_66aksvf1&flashvars") else knitr::include_graphics("images/bookdown/sample-kaltura.png")
```
### 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.
(ref:sample-video2) Caption only appears in HTML version. View link to [YouTube video](https://youtu.be/_hmhEr1s7F0).
```{r sample-video2, fig.cap="(ref:sample-video2)"}
if(knitr::is_html_output(excludes="markdown")) knitr::include_url("https://www.youtube.com/embed/_hmhEr1s7F0")
```
### 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](http://jackdougherty.org) |
|  | About [Ilya Ilyankou](https://github.com/ilyankou) |