terrainr: Landscape Visualization in R and Unity

License: MIT CRAN status Lifecycle: maturing codecov Project Status: Active – The project has reached a stable, usable state and is being actively developed. R build status rOpenSci Review Status


terrainr makes it easy to retrieve elevation and base map image tiles for areas of interest within the United States from the National Map family of APIs, and then process that data into larger, joined images or crop it into tiles that can be imported into the Unity 3D rendering engine.

There are three main utilities provided by terrainr. First, users are able to download data from the National Map via the get_tiles function, downloading data tiles for the area represented by an sf or Raster object:


# Optional way to display a progress bar while your tiles download:

simulated_data <- data.frame(id = seq(1, 100, 1),
                             lat = runif(100, 44.04905, 44.17609), 
                             lng = runif(100, -74.01188, -73.83493))

simulated_data <- st_as_sf(simulated_data, coords = c("lng", "lat"))
simulated_data <- st_set_crs(simulated_data, 4326)

with_progress( # Only needed if you're using progressr
  output_tiles <- get_tiles(simulated_data,
                            services = c("elevation", "ortho"),
                            resolution = 90 # pixel side length in meters

Once downloaded, these images are in standard GeoTIFF or PNG formats and can be used as expected with other utilities:


raster::plotRGB(raster::brick(output_tiles[["ortho"]][[1]]), scale = 1)

Secondly, terrainr provides functions for manipulating these files, editing downloaded images to create new base map tiles:

vector_overlay <- vector_to_overlay(

vector_overlay <- combine_overlays(


Finally, terrainr helps you visualize this data, both natively in R via the new geom_spatial_rgb geom:

ggplot() + 
  geom_spatial_rgb(data = output_tiles[["ortho"]],
                   aes(x = x, y = y, r = red, g = green, b = blue)) + 
  geom_sf(data = simulated_data)

As well as with the Unity 3D rendering engine, allowing you to fly or walk through your downloaded data sets in 3D and VR:

with_progress( # When not specifying resolution, default is 1m pixels
  output_tiles <- get_tiles(simulated_data,
                            services = c("elevation", "ortho"))

merged_dem <- merge_rasters(output_tiles[["elevation"]], 
                            tempfile(fileext = ".tif"))
merged_ortho <- merge_rasters(output_tiles[["ortho"]], 
                              tempfile(fileext = ".tif"))

mapply(function(x, y) raster_to_raw_tiles(input_file = x, 
                                          output_prefix = tempfile(), 
                                          side_length = 4097, 
                                          raw = y),
       c(merged_dem, merged_ortho),
       c(TRUE, FALSE))

# We can then import these tiles to Unity to create:

The more time intensive processing steps can all be monitored via the progressr package, so you’ll be more confident that your computer is still churning along and not just stalled out. For more information, check out the introductory vignette and the guide to importing your data into Unity!

Available Datasets

The following datasets can currently be downloaded using get_tiles or hit_national_map_api:

(All descriptions above taken from the National Map API descriptions.)


You can install the development version of terrainr from GitHub with:

# install.packages("devtools")

Code of Conduct

Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.