Uses a combination of raytracing, spherical texture mapping, lambertian reflectance, and ambient occlusion to produce hillshades of elevation matrices. Includes water detection and layering functions, programmable color palette generation, several built-in textures, 2D and 3D plotting options, and the ability to export 3D maps to a 3D printable format.
rayshader is an open source package for producing hillshaded maps of elevation matrices with raytracing and spherical texture mapping.
Rayshader has five functions related to hillshading:
ray_shadeuses 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
sphere_shademaps an RGB texture to a hillshade by spherical mapping. A texture can be generated with the
create_texturefunction, or loaded from an image.
sphere_shadealso includes 7 built-in palettes: "imhof1","imhof2","imhof3",imhof4","desert","bw","unicorn".
create_textureprogrammatically 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_texturewill interpolate those if they aren't given.
ambient_shadecreates 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_shadeuses 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_shadowtakes 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.
Rayshader also has two functions to detect and add water to maps:
detect_wateruses a flood-fill algorithm to detect bodies of water of a user-specified minimum area.
add_wateruses the output of
detect_waterto 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_shadeto get a matching hue.
And two functions to display and save your maps:
plot_mapPlots the current map. Accepts either a matrix or an array.
save_pngSaves the current map to disk with a user-specified filename.
plot_3dCreates 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.
save_3dprintWrites a stereolithography (STL) file of the current 3D map to create a 3D printable map. The user can specify the physical maximum width of the 3D print when calling the function.
All of these functions are designed to be used with the magrittr pipe
library(rayshader)library(magrittr)#Here, I load a map for the River Derwent in Tasmania with the raster package:localtif = raster::raster("tasmania.tif")#And convert it to a matrix:elmat = matrix(raster::extract(localtif,raster::extent(localtif),buffer=1000),nrow=ncol(localtif),ncol=nrow(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)) %>%plot_map()
elmat %>%sphere_shade( texture = "desert") %>%add_water(detect_water(elmat), color="desert") %>%add_shadow(ray_shade(elmat)) %>%add_shadow(ambient_shade(elmat)) %>%plot_map()
Rayshader also supports 3D mapping by passing a texture map (either external or one produced by rayshader) into the
elmat %>%sphere_shade(texture = "desert") %>%add_water(detect_water(elmat), color="desert") %>%add_shadow(ray_shade(elmat)) %>%add_shadow(ambient_shade(elmat)) %>%plot_3d(elmat)
You can also easily add a water layer by setting
water = TRUE (and setting
waterdepth if the water level is not 0). You can customize the appearance and transparancy of the water layer via arguments to
plot_3d. Here's an example using the built-in example bathymetric/topographic data of Monterey Bay, CA
montereybay (zscale for a 1-to-1 ratio using
montereybay would be 200, but in plot_3d is set to 50 to give a 4x exaggerated height in the z-direction) :
montereybay %>%sphere_shade(texture = "imhof1") %>%add_shadow(ray_shade(montereybay,zscale=200)) %>%add_shadow(ambient_shade(montereybay,zscale=200)) %>%plot_3d(montereybay, water=TRUE, zscale=50, theta=-45,waterdepth = 0, wateralpha = 0.6, watercolor = "#88DDFF",waterlinecolor = "white", waterlinealpha = 0.5)
plot_3d()to specify location of viewport
render_snapshotfunction capture and save images of the current rgl view to either file or the current device.
pkgdownwebsite for the package.
NEWS.mdfile to track changes to the package.
NAentries in the elevation matrix as holes in the 3D model. This can be used to slice the model into any shape.
plot_3dto include the new
baseshapeargument, which has several built-in shapes
c("circle","hex")to overlay onto a matrix. This removes points in the elevation matrix outside the masked region.
plot_3dto allow the user to turn on antialiasing for the lines in the plot.
save_3dprintto improve robustness. User now has to remove those 3D elements themselves when creating .stl file.
add_overlaywhen the input is a matrix
render_label()function to add text labels to 3D plots.
progbararguments to be either
render_depth(), a post-processing effect to add depth of field to 3D maps.
render_water(), which either adds or replaces a water layer on the existing 3D map.
add_overlay(), which adds a transparent or semi-transparent overlay to the current hillshade.
montereybayto mark it as internal data (for better user messages)
save_3dprint()to include the option to remove the shadow and water layers.
plot_map()no longer crashes R when "rotate" is a matrix rather than a single numeric value.
plot_3d()now displays warning if hillshade argument contains any values below 0 or more than 1.
save_3dprint, a function that exports 3D maps to a stereolithography (STL) format for 3D printing.
remove_edgesoption: the x/y dimensions of the outputs and inputs are now always consistent.
akima::bilinear.gridto remove non-GPL software dependency
add_waterto work with matrices
montereybaydataset used and zscale is not passed in by user
plot_3d, a function to take hillshades/textures and visualize them with an elevation matrix in 3D. Includes water visualization and the ability to view the map as a solid object.
ambient_shade- Added option to pass arguments to makeCluster function for parallel execution
sphere_shadefunction to apply spherical texture maps to elevation matrices.
create_texturefunction to allow user to programmatically create texture maps by specifying colors.
ambient_shadefunction to calculate ambient occlusion shadow maps.
add_shadowfunction to add shadow to existing shadow matrices/texture arrays.
calculate_normalfunction to pre-calculate normal vectors of elevation matrix for faster spherical shading.
detect_waterfunction to automatically detect bodies of water (of a specified size) on an elevation matrix.
write_pngfunction to save hillshaded maps to file.
plot_mapfunction to parse and plot resulting hillshaded maps.