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, hillshading algorithms, and overlays to generate stunning 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. Scenes can also be rendered using a high-quality pathtracer, rayrender. 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, and can be exported to an OBJ file.

Installation

# To install the latest version from Github:
# install.packages("devtools")
devtools::install_github("tylermorganwall/rayshader")

On Ubuntu, the following libraries are required:

libpng-dev libjpeg-dev libfreetype6-dev libglu1-mesa-dev libgl1-mesa-dev pandoc zlib1g-dev libicu-dev libgdal-dev gdal-bin libgeos-dev libproj-dev

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”.
• 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.
• texture_shade() calculates a shadow for each point on the surface using the method described by Leland Brown in “Texture Shading: A New Technique for Depicting Terrain Relief.”
• height_shade() calculates a color for each point on the surface using a direct elevation-to-color mapping.
• 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.
• 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.

Rayshader also has functions to add water and generate overlays:

• 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.
• generate_altitude_overlay() uses a hillshade and the height map to generate a semi-transparent hillshade whose transparency varies with altitude.
• generate_compass_overlay() generates an overlay with a compass.
• generate_contour_overlay() calculates and returns an overlay of contour lines.
• generate_label_overlay() this uses the maptools::placeLabel() function to generate labels for the given scene. Either use an sf object or manually specify the x/y coordinates and label.
• generate_line_overlay() generates an overlay of lines, using an sf object with LINESTRING geometry.
• generate_point_overlay() generates an overlay of points, using an sf object with POINT geometry.
• generate_polygon_overlay() generates an overlay of points, using an sf object with POLYGON geometry.
• generate_scalebar_overlay() this function creates an overlay with a scale bar of a user-specified length. It uses the coordinates of the map (specified by passing an extent) and then creates a scale bar at a specified x/y proportion across the map. If the map is not projected (i.e. is in lat/long coordinates) this function will use the geosphere package to create a scale bar of the proper length.
• generate_waterline_overlay() generates a semi-transparent waterline overlay to layer onto an existing map using a height map or a boolean matrix.

Also included are functions to add additional effects and information to your 3D visualizations:

• render_highquality() renders in the scene with a built-in pathtracer, powered by the rayrender package. Use this for high-quality maps with realistic light transport.
• 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.
• 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.
• render_compass() places a compass on the map in 3D.
• render_path() adds a 3D path to the current scene, using latitude/longitude or coordinates in the reference system defined by the extent object. If no altitude is provided, the path will be elevated a constant offset above the heightmap.
• render_points() Adds 3D points to the current scene, using latitude/longitude or coordinates in the reference system defined by the extent object. If no altitude is provided, the points will be elevated a constant offset above the heightmap.
• render_polygons() Adds 3D polygons to the current scene, using latitude/longitude or coordinates in the reference system defined by the extent object.
• render_scalebar() places a scalebar on the map in 3D.

And several helper functions for converting rasters to matrices:

• raster_to_matrix() converts a raster objects into a matrix.
• resize_matrix() resizes a matrix (preserving contents) by specifying the desired output dimensions or a scaling factor.

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_camera() Changes the camera orientation.
• 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/gif 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().

Usage

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

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 = "d