generate_scalebar_overlay: Generate Scalebar Overlay

In tylermorganwall/rayshader: Create Maps and Visualize Data in 2D and 3D

Generate Scalebar Overlay

Description

This function creates an overlay with a scale bar of a user-specified length. It uses the coordinates of the map (specified by passing an extent) and then creates a scale bar at a specified x/y proportion across the map. If the map is not projected (i.e. is in lat/long coordinates) this function will use the 'geosphere' package to create a scale bar of the proper length.

Usage

generate_scalebar_overlay(
  extent,
  length,
  x = 0.05,
  y = 0.05,
  latlong = FALSE,
  thickness = NA,
  bearing = 90,
  unit = "m",
  flip_ticks = FALSE,
  labels = NA,
  text_size = 1,
  decimals = 0,
  text_offset = 1,
  adj = 0.5,
  heightmap = NULL,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  color1 = "white",
  color2 = "black",
  text_color = "black",
  font = 1,
  border_color = "black",
  tick_color = "black",
  border_width = 1,
  tick_width = 1,
  halo_color = NA,
  halo_expand = 1,
  halo_alpha = 1,
  halo_offset = c(0, 0),
  halo_blur = 1
)

Arguments

extent	Either an object representing the spatial extent of the scene (either from the 'raster', 'terra', 'sf', or 'sp' packages), a length-4 numeric vector specifying 'c("xmin", "xmax","ymin","ymax")', or the spatial object (from the previously aforementioned packages) which will be automatically converted to an extent object. If this is in lat/long coordinates, be sure to set 'latlong = TRUE'.
length	The length of the scale bar, in 'units'. This should match the units used on the map, unless 'extent' uses lat/long coordinates. In that case, the distance should be in meters.
x	Default '0.05'. The x-coordinate of the bottom-left corner of the scale bar, as a proportion of the full map width.
y	Default '0.05'. The y-coordinate of the bottom-left corner of the scale bar, as a proportion of the full map height.
latlong	Default 'FALSE'. Set to 'TRUE' if the map is in lat/long coordinates to get an accurate scale bar (using distance calculated with the 'geosphere' package).
thickness	Default 'NA', automatically computed as 1/20th the length of the scale bar. Width of the scale bar.
bearing	Default '90', horizontal. Direction (measured from north) of the scale bar.
unit	Default 'm'. Displayed unit on the scale bar.
flip_ticks	Default 'FALSE'. Whether to flip the ticks to the other side of the scale bar.
labels	Default 'NA'. Manually specify the three labels with a length-3 character vector. Use this if you want display units other than meters.
text_size	Default '1'. Text size.
decimals	Default '0'. Number of decimal places for scale bar labels.
text_offset	Default '1'. Amount of offset to apply to the text from the scale bar, as a multiple of 'thickness'.
adj	Default '0.5', centered. Text justification. '0' is left-justified, and '1' is right-justified.
heightmap	Default 'NULL'. The original height map. Pass this in to extract the dimensions of the resulting RGB image array automatically.
width	Default 'NA'. Width of the resulting image array. Default the same dimensions as height map.
height	Default 'NA'. Width of the resulting image array. Default the same dimensions as height map.
resolution_multiply	Default '1'. If passing in 'heightmap' instead of width/height, amount to increase the resolution of the overlay, which should make lines/polygons/text finer. Should be combined with 'add_overlay(rescale_original = TRUE)' to ensure those added details are captured in the final map.
color1	Default 'black'. Primary color of the scale bar.
color2	Default 'white'. Secondary color of the scale bar.
text_color	Default 'black'. Text color.
font	Default '1'. An integer which specifies which font to use for text. If possible, device drivers arrange so that 1 corresponds to plain text (the default), 2 to bold face, 3 to italic and 4 to bold italic.
border_color	Default 'black'. Border color of the scale bar.
tick_color	Default 'black'. Tick color of the scale bar.
border_width	Default '1'. Width of the scale bar border.
tick_width	Default '1'. Width of the tick.
halo_color	Default 'NA', no halo. If a color is specified, the text label will be surrounded by a halo of this color.
halo_expand	Default '1'. Number of pixels to expand the halo.
halo_alpha	Default '1'. Transparency of the halo.
halo_offset	Default 'c(0,0)'. Horizontal and vertical offset to apply to the halo, as a proportion of the full scene.
halo_blur	Default ‘1'. Amount of blur to apply to the halo. Values greater than '30' won’t result in further blurring.

Value

Semi-transparent overlay with a scale bar.

Examples

if(run_documentation()) {
#Create the water palette
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
#Set scalebar font
par(family = "Arial")

#Generate flat water heightmap
mbay = montereybay
mbay[mbay < 0] = 0

base_map = mbay %>%
height_shade() %>%
add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
add_shadow(lamb_shade(montereybay,zscale=50),0.3)

#For convenience, the extent of the montereybay dataset is included as an attribute
mb_extent = attr(montereybay, "extent")

#Add a scalebar
base_map %>%
add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 40000,
                                      heightmap = montereybay, 
                                      latlong=TRUE)) %>%
plot_map()
}
if(run_documentation()) {
#Change the text color
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 40000,
                                       text_color = "white",
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the length
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 30000,
                                       text_color = "white",
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the thickness (default is length/20)
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 30000,
                                       text_color = "white", thickness = 30000/10,
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the text offset (given in multiples of thickness)
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 30000,
                                       text_color = "white", thickness = 30000/10,
                                       text_offset = 0.75,
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the primary and secondary colors, along with the border and tick color
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 30000,
                                       text_color = "white", border_color = "white",
                                       tick_color = "white",
                                       color1 = "darkolivegreen4", color2 = "burlywood3",
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Add a halo
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 40000,
                                       halo_color = "white", halo_expand = 1,
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the orientation, position, text alignment, and flip the ticks to the other side
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 40000, x = 0.07,
                                       bearing=0, adj = 0, flip_ticks = TRUE,
                                       halo_color = "white", halo_expand = 1.5,
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) { 
#64373.8 meters in 40 miles
#Create custom labels, change font and text size, remove the border/ticks, and change the color
#Here, we specify a width and height to double the resolution of the image (for sharper text)
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 64373.8, x = 0.07,
                                       labels = c("0", "20", "40 miles"), thickness=2500,
                                       text_size=3, font = 2, text_offset = 0,
                                       text_color="white", color2="#bf323b", border_color=NA,
                                       tick_color="red", tick_width=0,
                                       bearing=0, adj = 0, flip_ticks = TRUE,
                                       halo_color="black", halo_blur=3, halo_alpha=0.5,
                                       width = ncol(montereybay)*2,
                                       height = nrow(montereybay)*2,
                                       latlong=TRUE), rescale_original=TRUE) %>%
 plot_map()
}

tylermorganwall/rayshader documentation built on Dec. 21, 2024, 4:29 p.m.