spacey (version 0.1.1)

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

Description

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.

Usage

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

# NOT RUN {
automap(44.121268, -73.903734)
automap(44.121268, -73.903734, overlay = "World_Imagery")
automap(44.121268, -73.903734, overlay = "World_Imagery", method = "3d")
# }
# NOT RUN {
# }