Automatically create 2D and 3D maps using USGS and ESRI map data

This function takes a latitude/longitude coordinate pair alongside a desired distance to map and retrieves USGS (and optionally ESRI) map data, converts said data into matrices, and runs the data through rayshader using sensible defaults in order to return a 2D shaded map relief. It requires a functioning internet connection in order to retrieve data.

automap(
  lat = NULL,
  lng = NULL,
  distance = 10,
  method = c("2d", "3d"),
  img.width = 600,
  img.height = 600,
  overlay = NULL,
  z = 9,
  overlay.alpha = 0.75,
  colorscale = "imhof4",
  color.intensity = 1,
  max.darken = 0.5,
  sun.angle = 315,
  sun.altitude = 45,
  water.cutoff = 0.999,
  water.min.area = length(heightmap)/400,
  water.max.height = NULL,
  solid = TRUE,
  shadow = TRUE,
  water = FALSE,
  waterdepth = 0,
  theta = 45,
  phi = 45,
  fov = 0,
  zoom = 1,
  save.file = c(FALSE, "tif", "png", TRUE),
  from.file = c(FALSE, "tif", "png", TRUE),
  tif.filename = NULL,
  png.filename = NULL,
  dist.unit = c("km", "miles", "m", "ft"),
  coord.unit = c("degrees", "radians"),
  sr_bbox = 4326,
  sr_image = 4326,
  print.map = TRUE
)

Arguments

lat	The latitude for the map's centroid, in decimal degrees or radians.
lng	The longitude for the map's centroid, in decimal degrees or radians.
distance	The distance between the centroid and any corner of the (square) output map to include.
method	Should a 2d or 3d plot be produced?
img.width	Image width, in pixels
img.height	Image height, in pixels
overlay	ESRI overlay map to include, if any -- see get_image_overlay for list of options. If specifying a local file with from.file, any non NULL value will add your local file as an overlay.
z	zscale, passed to various rayshader functions. Defined as the ratio between the x and y spacing (which are assumed to be equal) and the z axis. For contiguous United States, USGS data is generally available at a ~9 meter spacing, with elevation provided in meter increments, resulting in a z value of 9 returning roughly representative maps; decrease this value to exaggerate elevation features.
overlay.alpha	Alpha value for the optional overlay layer.
colorscale	Color scale for land and water elements. If a vector of length 1, the same color scale will be applied for both land and water. If greater than length 1, values named "water" or "watercolor" will be used for water coloring, while "land" or "landcolor" will be used for land.
color.intensity	Intensity of color mapping -- higher values result in more intense colors.
max.darken	Passed to add_shadow. The lower limit for how much the image will be darkened. 0 is completely black, 1 means the shadow map will have no effect.
sun.angle	Angle around the matrix from which lights originate. Values line up with compass directions -- so 0 is directly North, while the default 315 places the sun in the Northwest.
sun.altitude	Angle in degrees from horizon from which light originates. Bounded [0, 90].
water.cutoff	Passed to detect_water. Defined therein as the lower limit of the z-component of the unit normal vector to be classified as water.
water.min.area	Passed to detect_water. The minimum possible area to consider a body of water.
water.max.height	Passed to detect_water. If provided, the maximum height a point can be classified water.
solid	Logical -- should the output be rendered as a solid (TRUE) or just a surface (FALSE)?
shadow	Logical -- should shadows be rendered?
water	Logical -- should water be rendered?
waterdepth	Water level.
theta	Rotation around z axis.
phi	Azimuth angle.
fov	Field of view angle.
zoom	Zoom factor.
save.file	Should the heightmap (= "tif"), overlay (= "png"), or both (= TRUE) be saved? Default FALSE saves neither.
from.file	Should the map be built from local .tif and .png files, rather than downloaded data? Accepts logical FALSE (no local files used) and TRUE (local files used for both height maps and textures, if requested), as well as strings tif (only use height map, redownload PNG) and png (only use texture, redownload tif). Overrides save arguments if local files are used.
tif.filename	If save.tif is TRUE, filename to save the .tif height map to. If from.file is TRUE, filename to load the height map from.
png.filename	If save.png is TRUE, filename to save the .png texture to. If from.file is TRUE, filename to load the texture from.
dist.unit	Units for the distance argument. All units are converted to kilometers, with some errors in the transition due to floating point arithmetic -- so if high accuracy is needed, convert units to kilometers beforehand.
coord.unit	Units for latitude and longitude, in either decimal degrees or radians.
sr_bbox	Spatial reference code (ISO 19111) for bounding box
sr_image	Spatial reference code (ISO 19111) for image
print.map	Logical -- should the output map be printed?

Value

A rayshader map object, by default printed and returned invisibly.

References

Archuleta, C.M., Constance, E.W., Arundel, S.T., Lowe, A.J., Mantey, K.S., and Phillips, L.A., 2017, The National Map seamless digital elevation model specifications: U.S. Geological Survey Techniques and Methods, book 11, chap. B9, 39 p., https://doi.org/10.3133/tm11B9

Examples

if (FALSE) {
automap(44.121268, -73.903734)
automap(44.121268, -73.903734, overlay = "World_Imagery")
automap(44.121268, -73.903734, overlay = "World_Imagery", method = "3d")
}