Render High Quality — render_highquality • rayshader

Renders a raytraced version of the displayed rgl scene, using the rayrender package. User can specify the light direction, intensity, and color, as well as specify the material of the ground and add additional scene elements.

This function can also generate frames for an animation by passing camera animation information from either convert_path_to_animation_coords() or rayrender::generate_camera_motion() functions.

render_highquality(
  filename = NA,
  samples = 128,
  sample_method = "sobol_blue",
  min_variance = 1e-07,
  light = TRUE,
  lat = NA,
  long = NA,
  datetime = NA,
  sky_args = list(),
  lightdirection = 315,
  lightaltitude = 45,
  lightsize = NULL,
  lightintensity = 500,
  lightcolor = "white",
  material = rayrender::diffuse(),
  water_attenuation = 0,
  water_surface_color = TRUE,
  water_ior = 1,
  override_material = FALSE,
  cache_scene = FALSE,
  reset_scene_cache = FALSE,
  width = NULL,
  height = NULL,
  text_angle = NULL,
  text_size = 12,
  text_offset = c(0, text_size/2, 0),
  line_radius = 0.5,
  point_radius = 0.5,
  smooth_line = FALSE,
  use_extruded_paths = FALSE,
  scale_text_angle = NULL,
  scale_text_size = 12,
  scale_text_offset = c(0, scale_text_size/2, 0),
  title_text = NULL,
  title_offset = c(20, 20),
  title_color = "black",
  title_size = 30,
  title_font = "sans",
  title_just = "left",
  title_bar_color = NA,
  title_bar_alpha = 0.5,
  ground_material = rayrender::diffuse(),
  ground_size = 1e+05,
  scene_elements = NULL,
  camera_location = NULL,
  camera_lookat = NULL,
  camera_interpolate = 1,
  clear = FALSE,
  return_scene = FALSE,
  print_scene_info = FALSE,
  clamp_value = NA,
  calculate_consistent_normals = FALSE,
  load_normals = TRUE,
  point_material = rayrender::diffuse,
  point_material_args = list(),
  path_material = rayrender::diffuse,
  path_material_args = list(),
  animation_camera_coords = NULL,
  plot = is.na(filename),
  ...
)

Arguments

filename: Default NA. Filename of saved image. If missing, will display to current device.
samples: Default 128. The maximum number of samples for each pixel. Increase this to increase the quality of the rendering.
sample_method: Default "sobol_blue", unless samples > 256, in which it defaults to "sobol". The type of sampling method used to generate random numbers. The other options are random (worst quality but fastest), sobol_blue (best option for sample counts below 256), and sobol (slowest but best quality, better than sobol_blue for sample counts greater than 256).
min_variance: Default 1e-6. Minimum acceptable variance for a block of pixels for the adaptive sampler. Smaller numbers give higher quality images, at the expense of longer rendering times. If this is set to zero, the adaptive sampler will be turned off and the renderer will use the maximum number of samples everywhere.
light: Default TRUE. Whether there should be a light in the scene. If not, the scene will be lit with a bluish sky.
lat: Default NA. Latitude (degrees) for automatic sky generation. When lat, long, datetime, or sky_args are supplied, render_highquality() uses skymodelr::generate_sky_latlong() to create an EXR environment map, disables the default light, and sets environment_light for the render.
long: Default NA. Longitude (degrees; west < 0) for automatic sky generation.
datetime: Default NA. POSIXct or character date-time used to position the sun.
sky_args: Default empty list(). Additional arguments passed to skymodelr::generate_sky_latlong() (except filename, which is managed internally). The EXR is cached in tempdir() using a filename derived from these inputs.
lightdirection: Default 315. Position of the light angle around the scene. If this is a vector longer than one, multiple lights will be generated (using values from lightaltitude, lightintensity, and lightcolor)
lightaltitude: Default 45. Angle above the horizon that the light is located. If this is a vector longer than one, multiple lights will be generated (using values from lightdirection, lightintensity, and lightcolor)
lightsize: Default NULL. Radius of the light(s). Automatically chosen, but can be set here by the user.
lightintensity: Default 500. Intensity of the light.
lightcolor: Default white. The color of the light.
material: Default rayrender::diffuse(). The material properties of the object file. Only used if override_material = TRUE
water_attenuation: Default 0, no attenuation. Amount that light should be attenuated when traveling through water. This calculates 1-color
water_surface_color: Default TRUE. Whether the water should have a colored surface or not. This is in contrast to setting a non-zero water attenuation, where the color comes from the attenuation of light in the water itself.
water_ior: Default 1. Water index of refraction.
override_material: Default FALSE. Whether to override the default diffuse material with that in argument material.
cache_scene: Default FALSE. Whether to cache the current scene to memory so it does not have to be converted to a raymesh object each time render_snapshot() is called. If TRUE and a scene has been cached, it will be used when rendering.
reset_scene_cache: Default FALSE. Resets the scene cache before rendering.
width: Defaults to the width of the rgl window. Width of the rendering.
height: Defaults to the height of the rgl window. Height of the rendering.
text_angle: Default NULL, which forces the text always to face the camera. If a single angle (degrees), will specify the absolute angle all the labels are facing. If three angles, this will specify all three orientations (relative to the x,y, and z axes) of the text labels.
text_size: Default 6. Height of the text.
text_offset: Default c(0,0,0). Offset to be applied to all text labels.
line_radius: Default 0.5. Radius of line/path segments.
point_radius: Default 1. Radius of 3D points (rendered with render_points()). This scales the existing value of size specified in render_points().
smooth_line: Default FALSE. If TRUE, the line will be rendered with a continuous smooth line, rather than straight segments.
use_extruded_paths: Default TRUE. If FALSE, paths will be generated with the rayrender::path() object, instead of rayrender::extruded_path().
scale_text_angle: Default NULL. Same as text_angle, but for the scale bar.
scale_text_size: Default 6. Height of the scale bar text.
scale_text_offset: Default c(0,0,0). Offset to be applied to all scale bar text labels.
title_text: Default NULL. Text. Adds a title to the image, using magick::image_annotate.
title_offset: Default c(20,20). Distance from the top-left (default, gravity direction in image_annotate) corner to offset the title.
title_color: Default black. Font color.
title_size: Default 30. Font size in pixels.
title_font: Default sans. String with font family such as "sans", "mono", "serif", "Times", "Helvetica", "Trebuchet", "Georgia", "Palatino" or "Comic Sans".
title_just: Default left. Justification of the title.
title_bar_color: Default NA. If a color, this will create a colored bar under the title.
title_bar_alpha: Default 0.5. Transparency of the title bar.
ground_material: Default diffuse(). Material defined by the rayrender material functions.
ground_size: Default 100000. The width of the plane representing the ground.
scene_elements: Default NULL. Extra scene elements to add to the scene, created with rayrender.
camera_location: Default NULL. Custom position of the camera. The FOV, width, and height arguments will still be derived from the rgl window.
camera_lookat: Default NULL. Custom point at which the camera is directed. The FOV, width, and height arguments will still be derived from the rgl window.
camera_interpolate: Default c(0,0). Maximum 1, minimum 0. Sets the camera at a point between the rgl view and the camera_location and camera_lookat vectors.
clear: Default FALSE. If TRUE, the current rgl device will be cleared.
return_scene: Default FALSE. If TRUE, this will return the rayrender scene (instead of rendering the image).
print_scene_info: Default FALSE. If TRUE, it will print the position and lookat point of the camera.
clamp_value: Default NA. If NA, uses 100 when the OIDN denoiser is unavailable and 10000 when it is available (via rayrender::has_denoiser()).
calculate_consistent_normals: Default FALSE. Whether to calculate consistent vertex normals to prevent energy loss at edges.
load_normals: Default TRUE. Whether to load the vertex normals if they exist in the OBJ file.
point_material: Default rayrender::diffuse. The rayrender material function to be applied to point data.
point_material_args: Default empty list(). The function arguments to point_material. The argument color will be automatically extracted from the rgl scene, but all other arguments can be specified here.
path_material: Default rayrender::diffuse. The rayrender material function to be applied to path data.
path_material_args: Default empty list(). The function arguments to path_material. The argument color will be automatically extracted from the rgl scene, but all other arguments can be specified here.
animation_camera_coords: Default NULL. Expects camera animation output from either convert_path_to_animation_coords() or rayrender::generate_camera_motion() functions.
plot: Default is.na(filename). Whether to plot the scene, or just return the RGBA array.
...: Additional parameters to pass to rayrender::render_scene()

Examples

#Render the volcano dataset using pathtracing
if(run_documentation()) {
volcano %>%
 sphere_shade() %>%
 plot_3d(volcano,zscale = 2)
render_highquality(min_variance = 0, sample_method = "sobol_blue")
}


#Change position of light
if(run_documentation()) {
render_highquality(lightdirection = 45, min_variance = 0, sample_method = "sobol_blue")
}


#Change vertical position of light
if(run_documentation()) {
render_highquality(lightdirection = 45, lightaltitude = 10,
                  min_variance = 0, samples = 16)
}


#Change the ground material
if(run_documentation()) {
render_highquality(lightdirection = 45, lightaltitude=60,
                  ground_material = rayrender::diffuse(checkerperiod = 30, checkercolor="grey50"),
                  min_variance = 0, samples = 16)
}


#Add three different color lights and a title
if(run_documentation()) {
render_highquality(lightdirection = c(0,120,240), lightaltitude=45,
                  lightcolor=c("red","green","blue"), title_text = "Red, Green, Blue",
                  title_bar_color="white", title_bar_alpha=0.8,
                  min_variance = 0, samples = 16)
}



#Change the camera:
if(run_documentation()) {
render_camera(theta=-45,phi=60,fov=60,zoom=0.8)
render_highquality(lightdirection = c(0),
                  title_bar_color="white", title_bar_alpha=0.8,
                  min_variance = 0, samples = 16)
}

#Add a shiny metal sphere
if(run_documentation()) {
render_camera(theta=-45,phi=60,fov=60,zoom=0.8)
render_highquality(lightdirection = c(0,120,240), lightaltitude=45,
                  lightcolor=c("red","green","blue"),
                  scene_elements = rayrender::sphere(z=-60,y=0,
                                                     radius=20,material=rayrender::metal()),
                  min_variance = 0)
}


#Add a red light to the volcano and change the ambient light to dusk
if(run_documentation()) {
render_camera(theta=45,phi=45)
render_highquality(lightdirection = c(240), lightaltitude=30,
                  lightcolor=c("#5555ff"),
                  scene_elements = rayrender::sphere(z=0,y=15, x=-18, radius=5,
                                   material=rayrender::light(color="red",intensity=10)),
                  min_variance = 0, samples = 16)
}

#Manually change the camera location and direction
if(run_documentation()) {
render_camera(theta=45,phi=45,fov=90)
render_highquality(lightdirection = c(240), lightaltitude=30, lightcolor=c("#5555ff"),
                  camera_location = c(50,10,10), camera_lookat = c(0,15,0),
                  scene_elements = rayrender::sphere(z=0,y=15, x=-18, radius=5,
                                   material=rayrender::light(color="red",intensity=10)),
                  min_variance = 0, samples = 16)
}

# Render the shadow of the Washington Monument with a realistic sky at that datetime
run_examples = length(find.package("sf", quiet = TRUE)) &&
              length(find.package("elevatr", quiet = TRUE)) &&
              length(find.package("raster", quiet = TRUE)) &&
              run_documentation()
if(run_examples) {
library(sf)
#Set location of washington monument
washington_monument_location =  st_point(c(-77.035249, 38.889462))
wm_point = washington_monument_location |>
 st_point() |>
 st_sfc(crs = 4326) |>
 st_transform(st_crs(washington_monument_multipolygonz))

elevation_data = elevatr::get_elev_raster(locations = wm_point, z = 14)

scene_bbox = st_bbox(st_buffer(wm_point,300))
cropped_data = raster::crop(elevation_data, scene_bbox)

#Use rayshader to convert that raster data to a matrix
dc_elevation_matrix = raster_to_matrix(cropped_data)

#Remove negative elevation data
dc_elevation_matrix[dc_elevation_matrix < 0] = 0

#Plot a 3D map of the national mall
dc_elevation_matrix |>
 height_shade() |>
 add_shadow(lamb_shade(dc_elevation_matrix), 0) |>
 plot_3d(dc_elevation_matrix, zscale=3.7, water = TRUE, waterdepth = 1,
         soliddepth=-50, windowsize = 800)
#Zoom in on the monument
render_camera(theta=150,  phi=35, zoom= 0.55, fov=70)
#Render the national monument at solar noon on the solstice
rgl::par3d(ignoreExtent = TRUE)
render_multipolygonz(washington_monument_multipolygonz,
                    extent = raster::extent(cropped_data),
                    zscale = 4, color = "grey80",
                    heightmap = dc_elevation_matrix)
#Render the (short) shadow the summer solstice
render_highquality(min_variance = 0, samples = 16,
                  long = -77.035249, lat = 38.889462,
                  datetime = as.POSIXct("2025-06-21 12:00:00",tz="EST"))
#Render the shadow the winter solstice (using the higher quality prague model)
render_highquality(min_variance = 0, samples = 16,
                  long = -77.035249, lat = 38.889462,
                  sky_args = list(hosek = FALSE),
                  datetime = as.POSIXct("2025-12-21 12:00:00",tz="EST"))
}
#> Mosaicing & Projecting
#> Note: Elevation units are in meters.
#> Warning: No water rendered--all elevations above or equal to water level. Range of heights: 2.55567121505737-12.3973035812378. Depth specified: 1
#> Error in render_highquality(min_variance = 0, samples = 16, long = -77.035249,     lat = 38.889462, datetime = as.POSIXct("2025-06-21 12:00:00",         tz = "EST")): `skymodelr` package required for automatic sky generation. Install it or provide `environment_light` via `...`.