/
example_README.Rmd
360 lines (277 loc) · 16.5 KB
/
example_README.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
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
---
output:
github_document:
fig_width: 7.5
fig_height: 6
html_preview: false
editor_options:
chunk_output_type: console
---
rayshader<img src="man/figures/raylogosmall.png" align="right" />
=========================================================
<img src="man/figures/smallhobart.gif" ></img>
Overview
--------
**rayshader** is an open source package for producing 2D and 3D data visualizations in R. **rayshader** uses elevation data in a base R matrix and a combination of raytracing, spherical texture mapping, overlays, and ambient occlusion to generate beautiful topographic 2D and 3D maps. In addition to maps, **rayshader** also allows the user to translate **ggplot2** objects into beautiful 3D data visualizations.
The models can be rotated and examined interactively or the camera movement can be scripted to create animations. The user can also create a cinematic depth of field post-processing effect to direct the user's focus to important regions in the figure. The 3D models can also be exported to a 3D-printable format with a built-in STL export function.
Installation
------------
``` r
# To install the latest version from Github:
# install.packages("devtools")
devtools::install_github("tylermorganwall/rayshader")
```
Functions
---------
<img src="man/figures/smallfeature.png">
Rayshader has seven functions related to mapping:
- `ray_shade` uses user specified light directions to calculate a global shadow map for an elevation matrix. By default, this also scales the light intensity at each point by the dot product of the mean ray direction and the surface normal (also implemented in function `lamb_shade`, this can be turned off by setting `lambert=FALSE`.
- `sphere_shade` maps an RGB texture to a hillshade by spherical mapping. A texture can be generated with the `create_texture` function, or loaded from an image. `sphere_shade` also includes 7 built-in palettes: "imhof1", "imhof2", "imhof3", imhof4", "desert", "bw", "unicorn".
- `create_texture` programmatically creates texture maps given five colors: a highlight, a shadow, a left fill light, a right fill light, and a center color for flat areas. The user can also optionally specify the colors at the corners, but `create_texture` will interpolate those if they aren't given.
- `ambient_shade` creates an ambient occlusion shadow layer, darkening areas that have less scattered light from the atmosphere. This results in valleys being darker than flat areas and ridges.
- `lamb_shade` uses a single user specified light direction to calculate a local shadow map based on the dot product between the surface normal and the light direction for an elevation matrix.
- `add_shadow` takes two of the shadow maps above and combines them, scaling the second one (or, if the second is an RGB array, the matrix) as specified by the user.
- `add_overlay` takes a 3 or 4-layer RGB/RGBA array and overlays it on the current map. If the map includes transparency, this is taken into account when overlaying the image. Otherwise, the user can specify a single color that will be marked as completely transparent, or set the full overlay as partly transparent.
Rayshader also has three functions to detect and add water to maps:
- `detect_water` uses a flood-fill algorithm to detect bodies of water of a user-specified minimum area.
- `add_water` uses the output of `detect_water` to add a water color to the map. The user can input their own color, or pass the name of one of the pre-defined palettes from `sphere_shade` to get a matching hue.
- `render_water` adds a 3D tranparent water layer to 3D maps, after the rgl device has already been created. This can either add to a map that does not already have a water layer, or replace an existing water layer on the map.
Also included are two functions to add additional effects and information to your 3D visualizations:
- `render_depth` generates a depth of field effect for the 3D map. The user can specify the focal distance, focal length, and f-stop of the camera, as well as aperture shape and bokeh intensity. This either plots the image to the local device, or saves it to a file if given a filename.
- `render_label` adds a text label to the `x` and `y` coordinate of the map at a specified altitude `z` (in units of the matrix). The altitude can either be specified relative to the elevation at that point (the default), or absolutely.
And four functions to display and save your visualizations:
- `plot_map` Plots the current map. Accepts either a matrix or an array.
- `write_png` Writes the current map to disk with a user-specified filename.
- `plot_3d` Creates a 3D map, given a texture and an elevation matrix. You can customize the appearance of the map, as well as add a user-defined water level.
- `render_snapshot` Saves an image of the current 3D view to disk (if given a filename), or plots the 3D view to the current device (useful for including images in R Markdown files).
- `render_movie` Creates and saves a mp4 file of the camera rotating around the 3D scene by either using a built-in orbit or by using one provided by the user.
Finally, rayshader has a single function to generate 3D plots using ggplot2 objects:
- `plot_gg` Takes a ggplot2 object (or a list of two ggplot2 objects) and uses the fill or color aesthetic to transform the plot into a 3D surface. You can pass any of the arguments used to specify the camera and the background/shadow colors in `plot_3d()`, and manipulate the displayed 3D plot using `render_camera()` and `render_depth()`.
All of these functions are designed to be used with the magrittr pipe `%>%`.
Usage
-----
```{r setup, include = FALSE}
library(knitr)
library(rgl)
knit_hooks$set(rgl = hook_rgl)
knitr::opts_chunk$set(
fig.path = "man/figures/",
cache = TRUE
)
set.seed(1001)
```
Rayshader can be used for two purposes: both creating hillshaded maps and 3D data visualizations plots. First, let's look at rayshader's mapping capabilities. For the latter, scroll below.
## Mapping with rayshader
```{r README_basicmapping}
library(rayshader)
#Here, I load a map with the raster package.
loadzip = tempfile()
download.file("https://tylermw.com/data/dem_01.tif.zip", loadzip)
localtif = raster::raster(unzip(loadzip, "dem_01.tif"))
unlink(loadzip)
#And convert it to a matrix:
elmat = raster_to_matrix(localtif)
#We use another one of rayshader's built-in textures:
elmat %>%
sphere_shade(texture = "desert") %>%
plot_map()
#sphere_shade can shift the sun direction:
elmat %>%
sphere_shade(sunangle = 45, texture = "desert") %>%
plot_map()
#detect_water and add_water adds a water layer to the map:
elmat %>%
sphere_shade(texture = "desert") %>%
add_water(detect_water(elmat), color = "desert") %>%
plot_map()
#And we can add a raytraced layer from that sun direction as well:
elmat %>%
sphere_shade(texture = "desert") %>%
add_water(detect_water(elmat), color = "desert") %>%
add_shadow(ray_shade(elmat), 0.5) %>%
plot_map()
#And here we add an ambient occlusion shadow layer, which models
#lighting from atmospheric scattering:
elmat %>%
sphere_shade(texture = "desert") %>%
add_water(detect_water(elmat), color = "desert") %>%
add_shadow(ray_shade(elmat), 0.5) %>%
add_shadow(ambient_shade(elmat), 0) %>%
plot_map()
```
Rayshader also supports 3D mapping by passing a texture map (either external or one produced by rayshader) into the `plot_3d` function.
```{r README_three-d}
elmat %>%
sphere_shade(texture = "desert") %>%
add_water(detect_water(elmat), color = "desert") %>%
add_shadow(ray_shade(elmat, zscale = 3), 0.5) %>%
add_shadow(ambient_shade(elmat), 0) %>%
plot_3d(elmat, zscale = 10, fov = 0, theta = 135, zoom = 0.75, phi = 45, windowsize = c(1000, 800))
Sys.sleep(0.2)
render_snapshot(clear=TRUE)
```
You can also render using the built-in pathtracer, powered by [rayrender](https://www.rayrender.net). Simply replace `render_snapshot()` with `render_highquality()`. When `render_highquality()` is called, there's no need to pre-compute the shadows with any of the `_shade()` functions, so we remove those:
```{r README_three-dhq}
elmat %>%
sphere_shade(texture = "desert") %>%
add_water(detect_water(elmat), color = "desert") %>%
plot_3d(elmat, zscale = 10, fov = 0, theta = 135, zoom = 0.75, phi = 45, windowsize = c(1000, 800))
Sys.sleep(0.2)
render_highquality()
```
```{r include = FALSE}
rgl::rgl.close()
system("rm dem_01.tif")
```
You can also easily add a water layer by setting `water = TRUE` in `plot_3d()` (and setting `waterdepth` if the water level is not 0), or by using the function `render_water()` after the 3D map has been rendered. You can customize the appearance and transparancy of the water layer via function arguments. Here's an example using bathymetric/topographic data of Monterey Bay, CA (included with rayshader):
```{r README_three-d-water}
montshadow = ray_shade(montereybay, zscale = 50, lambert = FALSE)
montamb = ambient_shade(montereybay, zscale = 50)
montereybay %>%
sphere_shade(zscale = 10, texture = "imhof1") %>%
add_shadow(montshadow, 0.5) %>%
add_shadow(montamb, 0) %>%
plot_3d(montereybay, zscale = 50, fov = 0, theta = -45, phi = 45,
windowsize = c(1000, 800), zoom = 0.75,
water = TRUE, waterdepth = 0, wateralpha = 0.5, watercolor = "lightblue",
waterlinecolor = "white", waterlinealpha = 0.5)
Sys.sleep(0.2)
render_snapshot(clear=TRUE)
```
Water is also supported in `render_highquality()`.
```{r}
montereybay %>%
sphere_shade(zscale = 10, texture = "imhof1") %>%
plot_3d(montereybay, zscale = 50, fov = 70, theta = -45, phi = 20,
windowsize = c(1000, 800), zoom = 0.6,
water = TRUE, waterdepth = 0, wateralpha = 0.5, watercolor = "lightblue",
waterlinecolor = "white", waterlinealpha = 0.5)
Sys.sleep(0.2)
render_highquality(lightdirection = 0, lightaltitude = 30, clamp_value = 10,
samples=200, clear=TRUE)
```
Rayshader also has map shapes other than rectangular included `c("hex", "circle")`, and you can customize the map into any shape you want by setting the areas you do not want to display to `NA`.
```{r README_three-d-shapes, fig.width = 15, fig.height = 6}
par(mfrow = c(1, 2))
montereybay %>%
sphere_shade(zscale = 10, texture = "imhof1") %>%
add_shadow(montshadow, 0.5) %>%
add_shadow(montamb, 0) %>%
plot_3d(montereybay, zscale = 50, fov = 0, theta = -45, phi = 45, windowsize = c(1000, 800), zoom = 0.6,
water = TRUE, waterdepth = 0, wateralpha = 0.5, watercolor = "lightblue",
waterlinecolor = "white", waterlinealpha = 0.5, baseshape = "circle")
render_snapshot(clear = TRUE)
montereybay %>%
sphere_shade(zscale = 10, texture = "imhof1") %>%
add_shadow(montshadow, 0.5) %>%
add_shadow(montamb, 0) %>%
plot_3d(montereybay, zscale = 50, fov = 0, theta = -45, phi = 45, windowsize = c(1000, 800), zoom = 0.6,
water = TRUE, waterdepth = 0, wateralpha = 0.5, watercolor = "lightblue",
waterlinecolor = "white", waterlinealpha = 0.5, baseshape = "hex")
render_snapshot(clear = TRUE)
```
Adding text labels is done with the `render_label()` function, which also allows you to customize the line type, color, and size along with the font:
```{r README_three-d-labels}
montereybay %>%
sphere_shade(zscale = 10, texture = "imhof1") %>%
add_shadow(montshadow, 0.5) %>%
add_shadow(montamb,0) %>%
plot_3d(montereybay, zscale = 50, fov = 0, theta = -100, phi = 30, windowsize = c(1000, 800), zoom = 0.6,
water = TRUE, waterdepth = 0, waterlinecolor = "white", waterlinealpha = 0.5,
wateralpha = 0.5, watercolor = "lightblue")
render_label(montereybay, x = 350, y = 240, z = 4000, zscale = 50,
text = "Moss Landing", textsize = 2, linewidth = 5)
render_label(montereybay, x = 220, y = 330, z = 6000, zscale = 50,
text = "Santa Cruz", textcolor = "darkred", linecolor = "darkred",
textsize = 2, linewidth = 5)
render_label(montereybay, x = 300, y = 130, z = 4000, zscale = 50,
text = "Monterey", dashed = TRUE, textsize = 2, linewidth = 5)
render_label(montereybay, x = 50, y = 130, z = 1000, zscale = 50,
text = "Monterey Canyon", relativez = FALSE, textsize = 2, linewidth = 5)
Sys.sleep(0.2)
render_snapshot(clear = TRUE)
```
You can also apply a post-processing effect to the 3D maps to render maps with depth of field with the `render_depth()` function:
```{r README_three-d-depth, fig.width = 10, fig.height = 8}
elmat %>%
sphere_shade(texture = "desert") %>%
add_water(detect_water(elmat), color = "desert") %>%
add_shadow(ray_shade(elmat, zscale = 3), 0.5) %>%
add_shadow(ambient_shade(elmat), 0) %>%
plot_3d(elmat, zscale = 10, fov = 30, theta = -225, phi = 25, windowsize = c(1000, 800), zoom = 0.3)
Sys.sleep(0.2)
render_depth(focus = 0.6, focallength = 200, clear = TRUE)
```
## 3D plotting with rayshader and ggplot2
Rayshader can also be used to make 3D plots out of ggplot2 objects using the `plot_gg()` function. Here, I turn a color density plot into a 3D density plot. `plot_gg()` detects that the user mapped the `fill` aesthetic to color and uses that information to project the figure into 3D.
```{r README_ggplots, fig.width = 10, fig.height = 5}
library(ggplot2)
ggdiamonds = ggplot(diamonds) +
stat_density_2d(aes(x = x, y = depth, fill = stat(nlevel)),
geom = "polygon", n = 100, bins = 10, contour = TRUE) +
facet_wrap(clarity~.) +
scale_fill_viridis_c(option = "A")
par(mfrow = c(1, 2))
plot_gg(ggdiamonds, width = 5, height = 5, raytrace = FALSE, preview = TRUE)
plot_gg(ggdiamonds, width = 5, height = 5, multicore = TRUE, scale = 250,
zoom = 0.7, theta = 10, phi = 30, windowsize = c(800, 800))
Sys.sleep(0.2)
render_snapshot(clear = TRUE)
```
Rayshader will automatically ignore lines and other elements that should not be mapped to 3D. Here's a contour plot of the `volcano` dataset.
```{r README_ggplots_2, fig.width = 10, fig.height = 5}
library(reshape2)
#Contours and other lines will automatically be ignored. Here is the volcano dataset:
ggvolcano = volcano %>%
melt() %>%
ggplot() +
geom_tile(aes(x = Var1, y = Var2, fill = value)) +
geom_contour(aes(x = Var1, y = Var2, z = value), color = "black") +
scale_x_continuous("X", expand = c(0, 0)) +
scale_y_continuous("Y", expand = c(0, 0)) +
scale_fill_gradientn("Z", colours = terrain.colors(10)) +
coord_fixed()
par(mfrow = c(1, 2))
plot_gg(ggvolcano, width = 7, height = 4, raytrace = FALSE, preview = TRUE)
plot_gg(ggvolcano, multicore = TRUE, raytrace = TRUE, width = 7, height = 4,
scale = 300, windowsize = c(1400, 866), zoom = 0.6, phi = 30, theta = 30)
Sys.sleep(0.2)
render_snapshot(clear = TRUE)
```
Rayshader also detects when the user passes the `color` aesthetic, and maps those values to 3D. If both `color` and `fill` are passed, however, rayshader will default to `fill`.
```{r README_ggplots_3, fig.width = 10, fig.height = 5}
mtplot = ggplot(mtcars) +
geom_point(aes(x = mpg, y = disp, color = cyl)) +
scale_color_continuous(limits = c(0, 8))
par(mfrow = c(1, 2))
plot_gg(mtplot, width = 3.5, raytrace = FALSE, preview = TRUE)
plot_gg(mtplot, width = 3.5, multicore = TRUE, windowsize = c(800, 800),
zoom = 0.85, phi = 35, theta = 30, sunangle = 225, soliddepth = -100)
Sys.sleep(0.2)
render_snapshot(clear = TRUE)
```
Utilize combinations of line color and fill to create different effects. Here is a terraced hexbin plot, created by mapping the line colors of the hexagons to black.
```{r README_ggplots_4, fig.width = 10, fig.height = 5}
a = data.frame(x = rnorm(20000, 10, 1.9), y = rnorm(20000, 10, 1.2))
b = data.frame(x = rnorm(20000, 14.5, 1.9), y = rnorm(20000, 14.5, 1.9))
c = data.frame(x = rnorm(20000, 9.5, 1.9), y = rnorm(20000, 15.5, 1.9))
data = rbind(a, b, c)
#Lines
pp = ggplot(data, aes(x = x, y = y)) +
geom_hex(bins = 20, size = 0.5, color = "black") +
scale_fill_viridis_c(option = "C")
par(mfrow = c(1, 2))
plot_gg(pp, width = 5, height = 4, scale = 300, raytrace = FALSE, preview = TRUE)
plot_gg(pp, width = 5, height = 4, scale = 300, multicore = TRUE, windowsize = c(1000, 800))
render_camera(fov = 70, zoom = 0.5, theta = 130, phi = 35)
Sys.sleep(0.2)
render_snapshot(clear = TRUE)
```
You can also use the `render_depth()` function to direct the viewer's focus to a important areas in the figure.
```{r README_ggplots_5, fig.width = 10, fig.height = 8}
par(mfrow = c(1, 1))
plot_gg(pp, width = 5, height = 4, scale = 300, multicore = TRUE, windowsize = c(1200, 960),
fov = 70, zoom = 0.4, theta = 330, phi = 40)
Sys.sleep(0.2)
render_depth(focus = 0.68, focallength = 200)
```