### Initial Scene Rendering with rayshader

Source: https://www.rayshader.com/reference/render_water.html

Basic example demonstrating how to render a heightmap with rayshader, including sphere shading and initial 3D plot setup.

```R
if(run_documentation()) {
montereybay |>
 sphere_shade() |>
 plot_3d(montereybay,zscale=50)
render_snapshot()
}
```

--------------------------------

### Resize rgl window examples

Source: https://www.rayshader.com/reference/render_resize_window.html

Examples demonstrating how to resize the rgl window to different dimensions and capture snapshots.

```R
#Resize the rgl window to various sizes
if(run_documentation()) {
montereybay |>
 sphere_shade() |>
 plot_3d(montereybay,zscale=50,zoom=0.6,theta=-90,phi=30)
render_resize_window(width = 800, height = 800)
render_snapshot()
}


if(run_documentation()) {
render_resize_window(width = 200, height = 200)
render_snapshot()
}

if(run_documentation()) {
render_resize_window(width = 800, height = 400)
render_snapshot()
}
```

--------------------------------

### Render Buildings Example Wrapper

Source: https://www.rayshader.com/reference/render_buildings.html

A conditional wrapper used to execute documentation examples.

```R
if(run_documentation()) {
```

--------------------------------

### Install rayshader from GitHub

Source: https://www.rayshader.com/index.html

Installs the latest version of the rayshader package from GitHub using the devtools package. Ensure devtools is installed first.

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

--------------------------------

### run_documentation()

Source: https://www.rayshader.com/reference/run_documentation.html

Determines if the examples are currently being executed within a pkgdown environment.

```APIDOC
## run_documentation()

### Description
Determines if the examples are being run in pkgdown. It is not meant to be called by the user.

### Usage
run_documentation()

### Value
- **Boolean** - Returns TRUE if running in pkgdown, otherwise FALSE.

### Example
```r
# See if the documentation should be run.
run_documentation()
#> [1] TRUE
```
```

--------------------------------

### Ambient Occlusion Map Examples

Source: https://www.rayshader.com/reference/ambient_shade.html

Examples demonstrating basic usage, parameter tuning for search distance, and integration with other shading functions.

```R
#Here we produce a ambient occlusion map of the `montereybay` elevation map.
if(run_documentation()) {
plot_map(ambient_shade(heightmap = montereybay))
}
```

```R
#We can increase the distance to look for surface intersections `maxsearch`
#and the density of rays sent out around the point `sunbreaks`.
if(run_documentation()) {
plot_map(ambient_shade(montereybay, sunbreaks = 24,maxsearch = 100, multicore=TRUE))
}
```

```R
#Create the Red Relief Image Map (RRIM) technique using a custom texture and ambient_shade(),
#with an addition lambertian layer added with lamb_shade() to improve topographic clarity.
if(run_documentation()) {
bigmb = resize_matrix(montereybay, scale=2, method="cubic")
bigmb |>
 sphere_shade(zscale=3, texture = create_texture("red","red","red","red","white")) |>
 add_shadow(ambient_shade(bigmb, maxsearch = 100, multicore = TRUE,zscale=1),0) |>
 add_shadow(lamb_shade(bigmb),0.5) |>
 plot_map()
}
```

--------------------------------

### Generate polygon overlay examples

Source: https://www.rayshader.com/reference/generate_polygon_overlay.html

Various examples demonstrating how to overlay polygon data on height maps, including handling bathymetry, transparency, and data-driven color mapping.

```R
#Plot the counties around Monterey Bay, CA
if(run_documentation()) {
generate_polygon_overlay(monterey_counties_sf, palette = rainbow,
                        extent = attr(montereybay,"extent"), heightmap = montereybay) |>
 plot_map()
}

if(run_documentation()) {
#These counties include the water, so we'll plot bathymetry data over the polygon
#data to only include parts of the polygon that fall on land.
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)

generate_polygon_overlay(monterey_counties_sf, palette = rainbow,
                        extent = attr(montereybay,"extent"), heightmap = montereybay) |>
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, start_transition = 0)) |>
 plot_map()
}

if(run_documentation()) {
#Add a semi-transparent hillshade and change the palette, and remove the polygon lines
montereybay |>
 sphere_shade(texture = "bw") |>
 add_overlay(generate_polygon_overlay(monterey_counties_sf,
                        palette = terrain.colors, linewidth=NA,
                        extent = attr(montereybay,"extent"), heightmap = montereybay),
                        alphalayer=0.7) |>
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, start_transition = 0)) |>
 add_shadow(ray_shade(montereybay,zscale=50),0) |>
 plot_map()
}

if(run_documentation()) {
#Map one of the variables in the sf object and use an explicitly defined color palette
county_palette = c("087" = "red",    "053" = "blue",   "081" = "green",
                  "069" = "yellow", "085" = "orange", "099" = "purple")
montereybay |>
 sphere_shade(texture = "bw") |>
 add_shadow(ray_shade(montereybay,zscale=50),0) |>
 add_overlay(generate_polygon_overlay(monterey_counties_sf, linecolor="white", linewidth=3,
                        palette = county_palette, data_column_fill = "COUNTYFP",
                        extent = attr(montereybay,"extent"), heightmap = montereybay),
                        alphalayer=0.7) |>
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, start_transition = 0)) |>
 add_shadow(ray_shade(montereybay,zscale=50),0.5) |>
 plot_map()
}
```

--------------------------------

### Flip Up-Down Example

Source: https://www.rayshader.com/reference/flipud.html

A placeholder example for the flipud function.

```R
#Fake example
```

--------------------------------

### Examples of generate_line_overlay usage

Source: https://www.rayshader.com/reference/generate_line_overlay.html

Examples demonstrating how to add road overlays to a dataset, customize line appearance, and manually specify dimensions for quality.

```R
#Add the included `sf` object with roads to the montereybay dataset
if(run_documentation()) {
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
montereybay |>
 height_shade() |>
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  |>
 add_overlay(generate_line_overlay(monterey_roads_sf,
                                   attr(montereybay,"extent"), heightmap = montereybay))  |>
 add_shadow(ray_shade(montereybay,zscale=50),0.3) |>
 plot_map()
}

if(run_documentation()) {
#Change the line width, color, and transparency
montereybay |>
 height_shade() |>
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  |>
 add_overlay(generate_line_overlay(monterey_roads_sf, linewidth=3, color="white",
                                   attr(montereybay,"extent"), heightmap = montereybay),
                                   alphalayer=0.8)  |>
 add_shadow(ray_shade(montereybay,zscale=50),0.3) |>
 plot_map()
}

if(run_documentation()) {
#Manually specify the width and height to improve visual quality of the lines
montereybay |>
 height_shade() |>
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  |>
 add_shadow(ray_shade(montereybay,zscale=50),0.3) |>
 add_overlay(generate_line_overlay(monterey_roads_sf, linewidth=3, color="white",
                                   attr(montereybay,"extent"), width = 1080, height = 1080),
                                   alphalayer=0.8)  |>
 plot_map()
}
```

--------------------------------

### Example: Load Raster from File

Source: https://www.rayshader.com/reference/raster_to_matrix.html

Demonstrates saving a raster to a temporary file and loading it back into a matrix for visualization.

```R
#Save montereybay as a raster and open using the filename.
if(run_documentation()) {
temp_raster_filename = paste0(tempfile(),".tif")
raster::writeRaster(raster::raster(t(montereybay)),temp_raster_filename)
elmat = raster_to_matrix(temp_raster_filename)
elmat |>
 sphere_shade() |>
 plot_map()
}
```

--------------------------------

### Initialize 3D scene

Source: https://www.rayshader.com/reference/render_camera.html

Initial setup for a 3D plot using the montereybay dataset.

```R
if(run_documentation()) {
montereybay |>
 sphere_shade() |>
 plot_3d(montereybay,zscale = 50, water = TRUE, waterlinecolor="white")
render_snapshot()
}
```

--------------------------------

### Check documentation execution environment

Source: https://www.rayshader.com/reference/run_documentation.html

Determines if examples are running in pkgdown. This function is intended for internal use only.

```R
run_documentation()
```

```R
# See if the documentation should be run.
run_documentation()
#> [1] TRUE
```

--------------------------------

### Examples of rendering compass symbols

Source: https://www.rayshader.com/reference/render_compass.html

Various usage examples for adding, clearing, and customizing compass symbols on a 3D map.

```R
#Add a North arrow to the map, by default in the bottom right (SE)
if(run_documentation()) {
montereybay |>
 sphere_shade() |>
 plot_3d(montereybay,theta=-45, water=TRUE)
render_compass()
render_snapshot()
}
```

```R
if(run_documentation()) {
#Remove the existing symbol with `clear_compass = TRUE`
render_compass(clear_compass = TRUE)

#Point the N towards the light, at 315 degrees:
render_compass(angle = 315)
render_snapshot()
}
```

```R
if(run_documentation()) {
render_compass(clear_compass = TRUE)

#We can change the position by specifying a direction (here are three):
render_camera(theta=45,phi=45)
render_compass(position = "NW")
render_compass(position = "E")
render_compass(position = "S")
render_snapshot()
}
```

```R
if(run_documentation()) {
render_compass(clear_compass = TRUE)

#We can also change the distance away from the edge by setting the `scale_distance` argument.
render_compass(position = "NW", scale_distance = 1.4)
render_compass(position = "E", scale_distance = 1.4)
render_compass(position = "S", scale_distance = 1.4)

#Zoom in slightly:
render_camera(theta=45,phi=45,zoom=0.7)
render_snapshot()
}
```

```R
if(run_documentation()) {
render_compass(clear_compass = TRUE)

#We can also specify the radius directly with `compass_radius`:
render_camera(theta=0,phi=45,zoom=1)
render_compass(position = "N", scale_distance = 1.5, compass_radius=200)
render_compass(position = "E", scale_distance = 1.4, compass_radius=50)
render_compass(position = "S", scale_distance = 1.3, compass_radius=25)
render_compass(position = "W", scale_distance = 1.2, compass_radius=10)
render_snapshot()

render_compass(clear_compass = TRUE)
}
```

```R
if(run_documentation()) {
#We can also adjust the position manually, be specifying all x, y and z arguments.
render_camera(theta=-45,phi=45,zoom=0.9)
render_compass(x = 150, y = 50, z = 150)
render_snapshot()
}
```

--------------------------------

### Examples of add_shadow usage

Source: https://www.rayshader.com/reference/add_shadow.html

Demonstrates applying shadows to the montereybay dataset with varying intensity levels using the max_darken argument.

```R
#First we plot the sphere_shade() hillshade of `montereybay` with no shadows

if(run_documentation()) {
montereybay |>
 sphere_shade(colorintensity=0.5) |>
 plot_map()
}


#Raytrace the `montereybay` elevation map and add that shadow to the output of sphere_shade()
if(run_documentation()) {
montereybay |>
 sphere_shade(colorintensity=0.5) |>
 add_shadow(ray_shade(montereybay,sunaltitude=20,zscale=50),max_darken=0.3) |>
 plot_map()
}


#Increase the intensity of the shadow map with the max_darken argument.
if(run_documentation()) {
montereybay |>
 sphere_shade(colorintensity=0.5) |>
 add_shadow(ray_shade(montereybay,sunaltitude=20,zscale=50),max_darken=0.1) |>
 plot_map()
}


#Decrease the intensity of the shadow map.
if(run_documentation()) {
montereybay |>
 sphere_shade(colorintensity=0.5) |>
 add_shadow(ray_shade(montereybay,sunaltitude=20,zscale=50),max_darken=0.7) |>
 plot_map()
}
```

--------------------------------

### Generate and Plot Texture Palettes

Source: https://www.rayshader.com/reference/create_texture.html

Examples demonstrating the creation of specific color palettes and visualizing them using plot_map.

```R
#Here is the `imhof1` palette:
create_texture("#fff673","#55967a","#8fb28a","#55967a","#cfe0a9") |>
 plot_map()


#Here is the `unicorn` palette:
create_texture("red","green","blue","yellow","white") |>
 plot_map()
```

--------------------------------

### Generate texture shading maps

Source: https://www.rayshader.com/reference/texture_shade.html

Examples demonstrating various parameter configurations for texture shading on the montereybay dataset.

```R
if(run_documentation()) {

#Plut using default values
montereybay |>
  texture_shade() |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Increase the level of detail
montereybay |>
  texture_shade(detail=1) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Decrease the level of detail
montereybay |>
  texture_shade(detail=0) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Increase the level of contrast
montereybay |>
  texture_shade(contrast=3) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Increase the brightness for this level of contrast
montereybay |>
  texture_shade(contrast=5, brightness = 2) |>
  plot_map()
}
```

```R
#Add a texture_shade() layer into a map
montbay = montereybay
montbay[montbay < 0] = 0
if(run_documentation()) {
montbay |>
  height_shade() |>
  add_water(detect_water(montbay), color="dodgerblue") |>
  add_shadow(texture_shade(montbay, detail=1/6, contrast = 4,
                           brightness = 3),0.1) |>
  add_shadow(lamb_shade(montbay,zscale=50),0) |>
  plot_map()
}
```

--------------------------------

### Example: Plotting the Washington Monument Area

Source: https://www.rayshader.com/reference/render_multipolygonz.html

This example demonstrates how to fetch elevation data, convert it to a rayshader matrix, and then plot a 3D scene of the National Mall area, including the Washington Monument. It utilizes functions from `sf`, `elevatr`, and `raster` packages before plotting with rayshader.

```R
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)
render_snapshot()
}
#> 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

if(run_examples) {
#Zoom in on the monument
render_camera(theta=150,  phi=35, zoom= 0.55, fov=70)
#Render the national monument
rgl::par3d(ignoreExtent = TRUE)
render_multipolygonz(washington_monument_multipolygonz,
                    extent = raster::extent(cropped_data),
                    zscale = 4, color = "grey80",
                    heightmap = dc_elevation_matrix)
render_snapshot()
}

if(run_examples) {
#This works with `render_highquality()`
render_highquality(min_variance = 0, samples = 16)
}

```

--------------------------------

### Generate and Customize Waterline Overlays

Source: https://www.rayshader.com/reference/generate_waterline_overlay.html

A collection of examples showing how to create a base map and apply various waterline configurations using generate_waterline_overlay.

```R
if(run_documentation()) {
#Create a flat body of water for Monterey Bay
montbay = montereybay
montbay[montbay < 0] = 0

#Generate base map with no lines
basemap = montbay |>
  height_shade() |>
  add_water(detect_water(montbay), color="dodgerblue") |>
  add_shadow(texture_shade(montbay, detail=1/3, brightness = 15, contrast = 5),0) |>
  add_shadow(lamb_shade(montbay,zscale=50),0)

plot_map(basemap)
}
```

```R
if(run_documentation()) {
#Add waterlines
basemap |>
  add_overlay(generate_waterline_overlay(montbay)) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Change minimum line distance:
basemap |>
  add_overlay(generate_waterline_overlay(montbay, min = 0.02)) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Change maximum line distance
basemap |>
  add_overlay(generate_waterline_overlay(montbay, max = 0.4)) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Smooth waterlines
basemap |>
  add_overlay(generate_waterline_overlay(montbay, max = 0.4, smooth=2)) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Increase number of breaks
basemap |>
  add_overlay(generate_waterline_overlay(montbay, breaks = 20, max=0.4)) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Make lines evenly spaced:
basemap |>
  add_overlay(generate_waterline_overlay(montbay, evenly_spaced = TRUE)) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Change variable distance between each line
basemap |>
  add_overlay(generate_waterline_overlay(montbay, falloff=1.5)) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Turn off fading
basemap |>
  add_overlay(generate_waterline_overlay(montbay, fade=FALSE)) |>
  plot_map()
}
```

```R
if(run_documentation()) {
#Fill up the entire body of water with lines and make them all 50% transparent
basemap |>
  add_overlay(generate_waterline_overlay(montbay, fade=FALSE, max=1, alpha = 0.5, color="white",
                                         evenly_spaced = TRUE, breaks=50)) |>
  plot_map()
}
```

--------------------------------

### Resize and plot a matrix

Source: https://www.rayshader.com/reference/reduce_matrix_size.html

Example of resizing a matrix using resize_matrix and then visualizing it with sphere_shade and plot_map. Requires the run_documentation() condition to be true.

```R
if(run_documentation()) {
montbaysmall = resize_matrix(montereybay, scale=0.5)
montbaysmall |>
 sphere_shade() |
 plot_map()
}
```

--------------------------------

### Exporting 3D Models to STL

Source: https://www.rayshader.com/reference/save_3dprint.html

Examples demonstrating how to save a 3D model to an STL file with various dimension and unit configurations.

```R
filename_stl = tempfile()

#Save the STL file into `filename_stl`
if(run_documentation()) {
volcano |>
 sphere_shade() |>
 plot_3d(volcano,zscale=3)
render_snapshot()
save_3dprint(filename_stl)
}
```

```R
if(run_documentation()) {
volcano |>
 sphere_shade() |>
 plot_3d(volcano,zscale=3)
render_snapshot()
save_3dprint(filename_stl, maxwidth = 100)
}
```

```R
if(run_documentation()) {
volcano |>
 sphere_shade() |>
 plot_3d(volcano,zscale=3)
render_snapshot()
save_3dprint(filename_stl, maxwidth = 4, unit = "in")
}
```

```R
if(run_documentation()) {
volcano |>
 sphere_shade() |>
 plot_3d(volcano,zscale=3)
render_snapshot()
save_3dprint(filename_stl, maxwidth = "120mm")
}
```

--------------------------------

### Convert RGL scene example

Source: https://www.rayshader.com/reference/convert_rgl_to_raymesh.html

Demonstrates converting a 3D plot of the volcano dataset into a ray_mesh object.

```R
filename_obj = tempfile(fileext = ".obj")
#Save model of volcano
if(run_documentation()) {
volcano |>
 sphere_shade() |>
 plot_3d(volcano, zscale = 2)

rm_obj = convert_rgl_to_raymesh()
}
```

--------------------------------

### Exporting rayshader models to OBJ

Source: https://www.rayshader.com/reference/save_obj.html

Examples demonstrating how to save 3D models to OBJ files with various configurations like texture toggling and water refraction settings.

```R
if(interactive()) {
filename_obj = tempfile(fileext = ".obj")

#Save model of volcano
if(run_documentation()) {
volcano |>
 sphere_shade() |>
 plot_3d(volcano, zscale = 2)

save_obj(filename_obj)
}

#Save model of volcano without texture
if(run_documentation()) {
save_obj(filename_obj, save_texture = FALSE)
}

#Make water have realistic index of refraction
if(run_documentation()) {
montereybay |>
 sphere_shade() |>
 plot_3d(montereybay, zscale = 50)

save_obj(filename_obj, water_index_refraction = 1.5)
}
}
```

--------------------------------

### Save a map to a PNG file

Source: https://www.rayshader.com/reference/save_png.html

Example demonstrating how to pipe a hillshade object into the save_png function.

```R
filename_map = tempfile()

#Save the map into `filename_map`
montereybay |>
 sphere_shade() |>
 save_png(filename_map)
```

--------------------------------

### Create Bathymetric Hillshade

Source: https://www.rayshader.com/reference/generate_altitude_overlay.html

This example demonstrates creating a bathymetric hillshade using a custom color palette and plotting it. Ensure run_documentation() returns TRUE to execute.

```R
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
plot_map(bathy_hs)
```

--------------------------------

### Calculate and plot raytraced shadows

Source: https://www.rayshader.com/reference/ray_shade.html

Examples demonstrating various configurations for ray tracing the Monterey Bay dataset.

```R
#First we ray trace the Monterey Bay dataset.
#The default angle is from 40-50 degrees azimuth, from the north east.
if(run_documentation()) {
montereybay |>
 ray_shade(zscale=50) |>
 plot_map()
}

#Change the altitude of the sun to 25 degrees
if(run_documentation()) {
montereybay |>
 ray_shade(zscale=50, sunaltitude=25) |>
 plot_map()
}

#Remove the lambertian shading to just calculate shadow intensity.
if(run_documentation()) {
montereybay |>
 ray_shade(zscale=50, sunaltitude=25, lambert=FALSE) |>
 plot_map()
}


#Change the direction of the sun to the South East
if(run_documentation()) {
montereybay |>
 ray_shade(zscale=50, sunaltitude=25, sunangle=225) |>
 plot_map()
}
```

--------------------------------

### Render floating overlays on a 3D map

Source: https://www.rayshader.com/reference/render_floating_overlay.html

Example demonstrating how to generate and render road and point overlays on a 3D plot of Monterey Bay.

```R
if(run_documentation()) {
#Render the road network as a floating overlay layer, along with a label annotation and a floating
#point annotation
if(all(length(find.package("sf", quiet = TRUE)) > 0,
      length(find.package("magick", quiet = TRUE)) > 0)) {
 monterey = c(-121.892933,36.603053)
 monterey_city = sf::st_sfc(sf::st_point(monterey))

 #Generate Overlays
 road_overlay = generate_line_overlay(monterey_roads_sf, attr(montereybay,"extent"),
                                      heightmap = montereybay)
 point_overlay = generate_point_overlay(monterey_city, color="red", size=1,
                                        attr(montereybay,"extent"), heightmap = montereybay)

 #Create 3D plot (water transparency set to 1 because multiple transparency layers can interfere)
 montereybay |>
   height_shade() |>
   add_shadow(ray_shade(montereybay,zscale=50),0.3) |>
   plot_3d(montereybay, water = T, wateralpha = 1, windowsize = 800, watercolor = "lightblue")
 render_camera(theta=-55,phi=45,zoom=0.8)

 #Render label
 render_label(montereybay, lat = monterey[2], long = monterey[1], altitude = 9900,
              extent = attr(montereybay, "extent"),
              zscale = 50, text = "Monterey", textcolor = "black", linecolor="darkred")

 #Render Floating Overlays
 render_floating_overlay(road_overlay, altitude = 10000,zscale = 50)
 render_floating_overlay(point_overlay, altitude = 100,zscale = 50)
 render_snapshot()
}
}
```

--------------------------------

### Required Ubuntu Libraries for rayshader

Source: https://www.rayshader.com/index.html

Lists the necessary system libraries required for installing rayshader on Ubuntu. These include image, font, OpenGL, and geospatial libraries.

```bash
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
```

--------------------------------

### Manually Specify Contour Levels

Source: https://www.rayshader.com/reference/generate_contour_overlay.html

This example demonstrates how to manually specify the contour levels using the `levels` argument in `generate_contour_overlay`.

```R
montereybay |>
 height_shade() |>
 add_overlay(generate_contour_overlay(montereybay, linewidth=2, levels = seq(-2000,0,100))) |>
 add_shadow(ray_shade(montereybay,zscale=50),0.3) |>
 plot_map()
```

--------------------------------

### Get System Information

Source: https://www.rayshader.com/CONTRIBUTING.html

Include your system information when opening a GitHub issue for bug reports. This helps in diagnosing environment-specific problems.

```R
Sys.info()
```

--------------------------------

### Add Points with Offset for Shadow Effect

Source: https://www.rayshader.com/reference/render_points.html

This example shows how to render points with an offset of 0 to create a shadow effect over water. It also adjusts camera parameters for a better view.

```R
if(run_documentation()) {
#We'll set the altitude to zero to give the tracks a "shadow" over the water.
render_points(extent = attr(montereybay,"extent"),
             lat = unlist(bird_track_lat), long = unlist(bird_track_long),
             offset = 0, zscale=50, color="black")
render_camera(theta=30,phi=35,zoom=0.45,fov=70)
render_snapshot()
}
#> Error in transform_into_heightmap_coords(extent, heightmap, lat, long,     altitude, offset, zscale): No altitude data requires heightmap argument be passed
```

--------------------------------

### Fill Ocean in Monterey Bay Dataset

Source: https://www.rayshader.com/reference/add_water.html

This example shows how to fill the ocean in the Monterey Bay dataset by setting negative elevation values to 0 and then using add_water to simulate the ocean.

```R
montbay_water = montereybay
montbay_water[montbay_water < 0] = 0

if(run_documentation()) {
montereybay |
 sphere_shade(texture="imhof4") |
 add_water(detect_water(montbay_water),color="imhof4") |
 plot_map()
}
```

--------------------------------

### Calculate and Use Normal Vectors

Source: https://www.rayshader.com/reference/calculate_normal.html

Example showing how to cache normal vectors for the volcano dataset and use them to accelerate sphere_shade rendering.

```R
#Here we produce a light intensity map of the `volcano` elevation map.

#Cache the normal vectors of the volcano dataset
if(run_documentation()) {
volcanocache = calculate_normal(volcano)
}

#Use the cached vectors to speed up calculation of `sphere_shade()` on a map.
if(run_documentation()) {
sphere_shade(volcano,normalvectors = volcanocache) |>
 plot_map()
}
```

--------------------------------

### Basic Orbit Movie Rendering

Source: https://www.rayshader.com/reference/render_movie.html

Example of rendering a default orbit movie. Ensure the plot is generated before uncommenting and running this code. The output filename will automatically append '.mp4' if not specified.

```R
if(interactive()) {
filename_movie = tempfile()

#By default, the function produces a 12 second orbit at 30 frames per second, at 30 degrees azimuth.
# \ donttest{
montereybay |> 
 sphere_shade(texture="imhof1") |> 
 plot_3d(montereybay, zscale=50, water = TRUE, watercolor="imhof1",
         waterlinecolor="white", waterlinealpha=0.5)
#Un-comment the following to run:
#render_movie(filename = filename_movie)
# }
}
```

--------------------------------

### Add 3D Points with Altitude

Source: https://www.rayshader.com/reference/render_points.html

This example demonstrates adding 3D points with specified altitudes to a rayshader scene. Ensure the 'montereybay' dataset and its extent attribute are available.

```R
if(run_documentation()) {
#Starting at Moss Landing in Monterey Bay, we are going to simulate a flight of a bird going
#out to sea and diving for food.

#First, create simulated lat/long data
set.seed(2009)
moss_landing_coord = c(36.806807, -121.793332)
x_vel_out = -0.001 + rnorm(1000)[1:300]/1000
y_vel_out = rnorm(1000)[1:300]/200
z_out = c(seq(0,2000,length.out = 180), seq(2000,0,length.out=10),
         seq(0,2000,length.out = 100), seq(2000,0,length.out=10))

bird_track_lat = list()
bird_track_long = list()
bird_track_lat[[1]] = moss_landing_coord[1]
bird_track_long[[1]] = moss_landing_coord[2]
for(i in 2:300) {
bird_track_lat[[i]] = bird_track_lat[[i-1]] + y_vel_out[i]
bird_track_long[[i]] = bird_track_long[[i-1]] + x_vel_out[i]
}


#Render the 3D map
montereybay |
 sphere_shade() |
 plot_3d(montereybay,zscale=50,water=TRUE,
         shadowcolor="#40310a", background = "tan",
         theta=210,  phi=22, zoom=0.20, fov=55)

#Pass in the extent of the underlying raster (stored in an attribute for the montereybay
#dataset) and the latitudes, longitudes, and altitudes of the track.
render_points(extent = attr(montereybay,"extent"),
             lat = unlist(bird_track_lat), long = unlist(bird_track_long),
             altitude = z_out, zscale=50,color="white")
render_snapshot()
}
```

--------------------------------

### Add Contours to Monterey Bay Dataset

Source: https://www.rayshader.com/reference/render_contours.html

Example of adding contours to the montereybay dataset with specified zscale and offset. Requires prior setup of the 3D scene.

```R
#Add contours to the montereybay dataset
if(run_documentation()) {
montereybay |> 
 height_shade() |> 
 add_shadow(ray_shade(montereybay,zscale=50),0.3) |> 
 plot_3d(montereybay, theta = -45, zscale=50, zoom=0.9, windowsize=800)
render_contours(montereybay, zscale = 50, offset = 100)
render_snapshot()
}
```

--------------------------------

### Simulate and Detect Water in Volcano Dataset

Source: https://www.rayshader.com/reference/detect_water.html

This example demonstrates how to simulate water by leveling a portion of the volcano dataset and then using `add_water` with `detect_water` to visualize it. Setting a minimum area prevents small flat regions from being classified as water.

```R
#Here we even out a portion of the volcano dataset to simulate water:
island_volcano = volcano
island_volcano[island_volcano < mean(island_volcano)] = mean(island_volcano)

#Setting a minimum area avoids classifying small flat areas as water:
island_volcano |> 
 sphere_shade(texture="imhof3") |
 add_water(detect_water(island_volcano, min_area = 400),color="imhof3") |
 plot_map()
```

--------------------------------

### Example Usage of fix_manifold_geometry

Source: https://www.rayshader.com/reference/fix_manifold_geometry.html

This example demonstrates how to use the fix_manifold_geometry function. It includes a comment indicating a test scenario.

```R
#Test
```

--------------------------------

### monterey_counties_sf Dataset

Source: https://www.rayshader.com/reference/monterey_counties_sf.html

Information and usage examples for the monterey_counties_sf dataset.

```APIDOC
## monterey_counties_sf Dataset

### Description
This dataset is an `sf` object containing polygon data from the U.S. Department of Commerce with selected geographic and cartographic information from the U.S. Census Bureau's Master Address File / Topologically Integrated Geographic Encoding and Referencing (MAF/TIGER) Database (MTDB). This data has been trimmed to only include 26 features in the extent of the `montereybay` dataset.

### Format
An `sf` object with MULTIPOLYGON geometry.

### Source
https://catalog.data.gov/dataset/tiger-line-shapefile-2016-state-california-current-county-subdivision-state-based

### Examples
```R
# This is the full code (commented out) used to generate this dataset from the original data:
# counties = sf::st_read("tl_2016_06_cousub.shp")
# monterey_counties_sf = sf::st_crop(counties, attr(montereybay,"extent"))
```
```

--------------------------------

### GET /models/flag

Source: https://www.rayshader.com/reference/tree_basic_center_obj.html

Retrieves the file location of the flag 3D OBJ model components.

```APIDOC
## GET /models/flag

### Description
Retrieves the file location of the included flag OBJ file (saved with a .txt extension). Use `flag_full_obj()` for the complete pole, or `flag_banner_obj()` and `flag_pole_obj()` for individual components.

### Method
GET

### Response
#### Success Response (200)
- **file_path** (string) - The local file system path to the OBJ model file.
```

--------------------------------

### GET /data/washington_monument_multipolygonz

Source: https://www.rayshader.com/reference/washington_monument_multipolygonz.html

Retrieves the MULTIPOLYGON Z 3D geometry data for the Washington Monument.

```APIDOC
## GET /data/washington_monument_multipolygonz

### Description
Retrieves an `sf` object containing MULTIPOLYGON Z 3D data of the Washington Monument in Washington, DC.

### Method
GET

### Endpoint
/data/washington_monument_multipolygonz

### Response
#### Success Response (200)
- **data** (sf object) - An `sf` object with MULTIPOLYGONZ geometry representing the Washington Monument.

### Source
https://opendata.dc.gov/documents/DCGIS::buildings-in-3d/
```

--------------------------------

### GET /flag_banner_obj

Source: https://www.rayshader.com/reference/flag_banner_obj.html

Retrieves the file location of the 3D OBJ model for a flag banner.

```APIDOC
## GET /flag_banner_obj

### Description
Returns the file path of the included flag OBJ model (saved with a .txt extension) to be used with the render_obj() function.

### Method
GET

### Endpoint
flag_banner_obj()

### Response
#### Success Response (200)
- **path** (string) - The absolute file path to the flag OBJ file.

#### Response Example
"/Users/runner/work/_temp/Library/rayshader/extdata/flag.txt"
```

--------------------------------

### GET /flag_full_obj

Source: https://www.rayshader.com/reference/flag_full_obj.html

Retrieves the file location of the complete 3D flag model (pole and banner).

```APIDOC
## GET /flag_full_obj

### Description
Returns the file path to the complete 3D flag OBJ model, which includes both the pole and the banner. The file is saved with a .txt extension.

### Method
GET

### Endpoint
flag_full_obj()

### Response
#### Success Response (200)
- **path** (string) - The absolute file path to the flag OBJ file.

#### Response Example
"/Users/runner/work/_temp/Library/rayshader/extdata/full_flag.txt"
```

--------------------------------

### Render High Quality with Compass Support

Source: https://www.rayshader.com/reference/render_compass.html

Initializes a high-quality render with compass support enabled. Set `min_variance` to 0 for full detail and adjust `samples` for render quality.

```r
render_highquality(min_variance = 0, samples = 16)
```

--------------------------------

### Add Polygon Overlay and Labels with White Halo

Source: https://www.rayshader.com/reference/generate_label_overlay.html

Similar to the previous example, but adds a white halo to the county labels for better readability. Requires the `sf` object with roads and the `montereybay` dataset.

```R
if(run_documentation()) {
#It's hard to read these values, so we'll add a white halo.
bathy_hs |>
 add_shadow(lamb_shade(montereybay,zscale=50),0.3) |>
 add_overlay(generate_polygon_overlay(monterey_counties_sf, palette = rainbow,
                                      extent = attr(montereybay,"extent"),
                                      heightmap = montereybay)) |>
 add_overlay(generate_label_overlay(labels=monterey_counties_sf,
                                    color="black", point_size = 1, text_size = 1,
                                    data_label_column = "NAME",
                                    extent= attr(montereybay,"extent"), heightmap = montereybay,
                                    halo_color = "white", halo_expand = 3,
                                    seed=1))  |>
 plot_map()
}
```

--------------------------------

### Path Arguments

Source: https://www.rayshader.com/reference/render_path.html

Detailed explanation of arguments for defining and rendering paths.

```APIDOC
## Path Arguments

This section details the various arguments available for defining and rendering paths within the rayshader package.

### Arguments

- **lat** (vector) - Vector of latitudes or other coordinates in the same coordinate reference system as `extent`. Can also be an `sf` or `SpatialLineDataFrame` object.
- **long** (vector, default: `NULL`) - Vector of longitudes. Ignored if `lat` is an `sf` or `SpatialLineDataFrame` object.
- **altitude** (vector, default: `NULL`) - Elevation of each point, in units of the elevation matrix (scaled by `zscale`). If `NULL`, uses the surface elevation offset by `offset`. A single value applies that altitude to all points.
- **groups** (vector, default: `NULL`) - Integer vector specifying the grouping of each lat/long path segment. Used when `lat`/`long` are numeric vectors.
- **extent** (object) - Spatial extent of the 3D scene. Can be an object from `raster`, `terra`, `sf`, `sp` packages, or a length-4 numeric vector `c("xmin", "xmax", "ymin", "ymax")`.
- **zscale** (numeric, default: `1`) - The ratio between the x and y spacing and the z axis in the original heightmap.
- **heightmap** (matrix, default: `NULL`) - A two-dimensional matrix representing elevation. Used if `altitude` is not provided or no `extent` is passed. Assumes evenly spaced points.
- **resample_evenly** (boolean, default: `FALSE`) - If `TRUE`, re-samples the path evenly from beginning to end to improve performance, especially with `software_render = TRUE`. Requires `reorder = TRUE` or an ordered `sf` object.
- **resample_n** (integer, default: `360`) - Number of breaks for even resampling if `resample_evenly = TRUE`.
- **reorder** (boolean, default: `FALSE`) - If `TRUE`, attempts to re-order rows within an `sf` object with multiple paths into a single continuous path. Merges paths based on matching endpoints.
- **reorder_first_index** (integer, default: `1`) - The index of the `sf` object to start the reordering process.
- **reorder_duplicate_tolerance** (numeric, default: `0.1`) - Tolerance for discarding duplicate paths during reordering.
- **reorder_merge_tolerance** (numeric, default: `1`) - Tolerance for merging path endpoints to form a continuous path.
- **simplify_tolerance** (numeric, default: `0`) - Tolerance for simplifying the path after merging. If `sf_use_s2()` is `TRUE` and coordinates are long-lat, tolerance is in meters.
- **linewidth** (numeric, default: `3`) - The width of the line.
- **color** (string, default: `"black"`) - The color of the line.
- **antialias** (boolean, default: `FALSE`) - If `TRUE`, applies anti-aliasing to the line. Note: may cause issues with transparent surfaces.
- **offset** (numeric, default: `5`) - Offset of the track from the surface when `altitude = NULL`.
- **clear_previous** (boolean, default: `FALSE`) - If `TRUE`, clears all existing paths before adding a new one.
- **return_coords** (boolean, default: `FALSE`) - If `TRUE`, returns the internal rayshader coordinates of the path instead of plotting.
- **tag** (string, default: `"path3d"`) - The `rgl` tag used when adding the path to the scene.
```

--------------------------------

### Resize Matrix to Specific Dimensions

Source: https://www.rayshader.com/reference/resize_matrix.html

Example of resizing a matrix to specific width and height dimensions. Requires the montereybay dataset.

```R
montbaysmall = resize_matrix(montereybay, width = 100, height = 100)
montbaysmall |>
 sphere_shade() |> 
plot_map()
```

--------------------------------

### Build From W Function

Source: https://www.rayshader.com/reference/build_from_w.html

Builds data from a specified directory.

```APIDOC
## build_from_w

### Description
Builds data from a specified directory.

### Method
N/A (R function)

### Endpoint
N/A (R function)

### Parameters
#### Path Parameters
- **dir** (character) - Required - The directory path to build from.

### Value
- **mat** (matrix) - The built data matrix.
```

--------------------------------

### Simulate Water on Volcano Dataset

Source: https://www.rayshader.com/reference/add_water.html

This example demonstrates how to simulate water on the volcano dataset by first leveling a portion of the terrain and then applying the add_water function. Setting a minimum area for water detection prevents small flat areas from being classified as water.

```R
island_volcano = volcano
island_volcano[island_volcano < mean(island_volcano)] = mean(island_volcano)

if(run_documentation()) {
island_volcano |> 
 sphere_shade(texture="imhof3") |
 add_water(detect_water(island_volcano, min_area = 400),color="imhof3") |
 plot_map()
}
```

--------------------------------

### Add Snow Peaks Overlay

Source: https://www.rayshader.com/reference/generate_altitude_overlay.html

This example adds a snow overlay to a map by setting `lower = FALSE` and defining a transition region for snow from 500m to 1200m. Ensure run_documentation() returns TRUE to execute.

```R
snow_palette = "white"
snow_hs = height_shade(montereybay, texture = snow_palette)

montereybay |>
 sphere_shade(zscale=10, texture = "desert") |>
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  |>
 add_overlay(generate_altitude_overlay(snow_hs, montereybay, 500, 1200, lower=FALSE))  |>
 add_shadow(ambient_shade(montereybay,zscale=50,maxsearch=100),0) |>
 plot_map()
```