render_beveled_polygons: Render Beveled Polygons

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

Render Beveled Polygons

Description

Adds beveled polygon to the scene using the 'raybevel' package. See the 'raybevel::generate_beveled_polygon()' function for more information.

Usage

render_beveled_polygons(
  polygon,
  extent,
  material = "grey",
  bevel_material = NA,
  angle = 45,
  bevel_width = 5,
  width_raw_units = FALSE,
  bevel = NA,
  zscale = 1,
  bevel_height = 1,
  base_height = 0,
  raw_heights = FALSE,
  raw_offsets = FALSE,
  heights_relative_to_centroid = TRUE,
  set_max_height = FALSE,
  max_height = 10,
  scale_all_max = TRUE,
  data_column_top = NULL,
  data_column_bottom = NULL,
  heightmap = NULL,
  scale_data = 1,
  holes = 0,
  alpha = 1,
  lit = TRUE,
  flat_shading = FALSE,
  light_altitude = c(45, 30),
  light_direction = c(315, 225),
  light_intensity = 1,
  light_relative = FALSE,
  clear_previous = FALSE,
  ...
)

Arguments

polygon	'sf' object, "SpatialPolygon" 'sp' object, or xy coordinates of polygon represented in a way that can be processed by 'xy.coords()'. If xy-coordinate based polygons are open, they will be closed by adding an edge from the last point to the first.
extent	Either an object representing the spatial extent of the 3D 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.
material	Default '"grey80"'. If a color string, this will specify the color of the sides/base of the polygon. Alternatively (for more customization), this can be a r'ayvertex::material_list()' object to specify the full color/appearance/material options for the resulting 'ray_mesh' mesh.
bevel_material	Default 'NA', defaults to the material specified in 'material'. If a color string, this will specify the color of the polygon bevel. Alternatively (for more customization), this can be a 'rayvertex::material_list()' object to specify the full color/appearance/material options for the resulting 'ray_mesh' mesh.
angle	Default '45'. Angle of the bevel.
bevel_width	Default '5'. Width of the bevel.
width_raw_units	Default 'FALSE'. Whether the bevel width should be measured in raw display units, or the actual units of the map.
bevel	Default 'NULL'. A list with 'x'/'y' components that specify a bevel profile. See 'raybevel::generate_bevel()'
zscale	Default '1'. The ratio between the x and y spacing (which are assumed to be equal) and the z axis in the original heightmap.
bevel_height	Default '1'. Height from the base of the polygon to the start of the beveled top.
base_height	Default '0'. Height of the base of the polygon.
raw_heights	Default 'FALSE'. A logical flag indicating whether the 'bevel_heights' are already in raw format and do not need to be multiplied by the maximum time of the skeleton. See the documentation for 'raybevel::generate_beveled_polygon()' for more info.
raw_offsets	Default 'FALSE'. A logical flag indicating whether the 'bevel_offsets' are already in raw format and do not need to be multiplied by the maximum time of the skeleton. See the documentation for 'raybevel::generate_beveled_polygon()' for more info.
heights_relative_to_centroid	Default 'FALSE'. Whether the heights should be measured in absolute terms, or relative to the centroid of the polygon.
set_max_height	Default 'FALSE'. A logical flag that controls whether to set the max height of the roof based on the 'max_height' argument.
max_height	Default '1'. The maximum height of the polygon.
scale_all_max	Default 'FALSE'. If passing in a list of multiple skeletons with polygons, whether to scale each polygon to the overall max height, or whether to scale each max height to the maximum internal distance in the polygon.
data_column_top	Default 'NULL'. A string indicating the column in the 'sf' object to use to specify the top of the beveled polygon.
data_column_bottom	Default 'NULL'. A string indicating the column in the 'sf' object to use to specify the bottom of the beveled polygon.
heightmap	Default 'NULL'. Automatically extracted from the rgl window–only use if auto-extraction of matrix extent isn't working. A two-dimensional matrix, where each entry in the matrix is the elevation at that point. All points are assumed to be evenly spaced.
scale_data	Default '1'. If specifying 'data_column_top' or 'data_column_bottom', how much to scale that value when rendering.
holes	Default '0'. If passing in a polygon directly, this specifies which index represents the holes in the polygon. See the 'earcut' function in the 'decido' package for more information.
alpha	Default '1'. Transparency of the polygons.
lit	Default 'TRUE'. Whether to light the polygons.
flat_shading	Default 'FALSE'. Set to 'TRUE' to have nicer shading on the 3D polygons. This comes with the slight penalty of increasing the memory use of the scene due to vertex duplication. This will not affect software or high quality renders.
light_altitude	Default 'c(45, 30)'. Degree(s) from the horizon from which to light the polygons.
light_direction	Default 'c(315, 225)'. Degree(s) from north from which to light the polygons.
light_intensity	Default '1'. Intensity of the specular highlight on the polygons.
light_relative	Default 'FALSE'. Whether the light direction should be taken relative to the camera, or absolute.
clear_previous	Default 'FALSE'. If 'TRUE', it will clear all existing polygons.
...	Additional arguments to pass to 'rgl::triangles3d()'.

Examples

# This function can also create fake "terrain" from polygons by visualizing the distance 
# to the nearest edge.
if(run_documentation()) {
#Render the county borders as polygons in Monterey Bay as terrain
montereybay %>%
  sphere_shade(texture = "desert") %>%
  add_shadow(ray_shade(montereybay,zscale = 50)) %>%
  plot_3d(montereybay, water = TRUE, windowsize = 800, watercolor = "dodgerblue",
          background = "pink")

#We will apply a negative buffer to create space between adjacent polygons. You may
#have to call `sf::sf_use_s2(FALSE)` before running this code to get it to run.
sf::sf_use_s2(FALSE)
mont_county_buff = sf::st_simplify(sf::st_buffer(monterey_counties_sf,-0.003), dTolerance=0.001)

render_beveled_polygons(mont_county_buff,  flat_shading  = TRUE, angle = 45 , 
                        heightmap = montereybay, bevel_width=2000,
                        material = "red",
                        extent = attr(montereybay,"extent"),  
                        bevel_height = 5000, base_height=0, 
                        zscale=200) 
render_camera(theta = 0,  phi = 90, zoom = 0.65, fov = 0)
render_snapshot()
render_camera(theta=194, phi= 35,   zoom = 0.5, fov= 80)
render_snapshot()
}

# Changing the color of the beveled top:
if(run_documentation()) {
render_beveled_polygons(mont_county_buff,  flat_shading  = TRUE, angle = 45 , 
                        heightmap = montereybay, bevel_width=2000,
                        material = "tan", bevel_material = "darkgreen",
                        extent = attr(montereybay,"extent"), clear_previous=TRUE,
                        bevel_height = 5000, base_height=0, 
                        zscale=200) 
}
# We can create a nice curved surface by passing in a bevel generated with the 
# `raybevel::generate_bevel()` function. 
if(run_documentation()) {
render_beveled_polygons(mont_county_buff, flat_shading  = TRUE, heightmap = montereybay,
                        bevel = raybevel::generate_bevel("exp",bevel_end = 0.4),
                        #max_height = 10, scale_all_max = TRUE, set_max_height = TRUE,
                        material = rayvertex::material_list(diffuse="red", 
                                                            ambient = "darkred", 
                                                            diffuse_intensity = 0.2,
                                                            ambient_intensity = 0.1),
                        light_intensity = 1, light_relative = FALSE,
                        extent = attr(montereybay,"extent"), bevel_height = 5000, 
                        base_height=0, clear_previous = TRUE,
                        zscale=200) 
render_snapshot()
}

# While the bevels all start at the same point in the above example,
# they rise to different levels due to being scaled by the maximum internal distance
# in the polygon. Setting `scale_all_max = TRUE` ensures the bevels are all scaled to the 
# same maximum height (in this case, 3000m above the 5000m bevel start height).
if(run_documentation()) {
render_beveled_polygons(mont_county_buff, flat_shading  = TRUE, heightmap = montereybay,
                 bevel = raybevel::generate_bevel("exp",bevel_end = 0.4),
                 max_height = 3000, scale_all_max = TRUE, set_max_height = TRUE,
                 material = rayvertex::material_list(diffuse="red", 
                                                     ambient = "darkred", 
                                                     diffuse_intensity = 0.2,
                                                     ambient_intensity = 0.1),
                 light_intensity = 1, light_relative = FALSE,
                 extent = attr(montereybay,"extent"), bevel_height = 5000, 
                 base_height=0, clear_previous = TRUE,
                 zscale=200) 
render_snapshot()
}

# Rendering the polygons with `render_highquality()`
if(run_documentation()) {
  render_highquality()
}

# We can scale the size of the polygon to a column in the `sf` object as well:
# raybevel::generate_bevel() function. We can scale this data down using the `scale_data`
# argument. Note that this is applied as well as the `zscale` argument, and that you 
# must think carefully about your scales and values if trying to represent a meaningful
# data visualization with this object.
if(run_documentation()) {
render_beveled_polygons(mont_county_buff,  flat_shading  = TRUE, angle = 45, bevel_width=1000, 
                 data_column_top = "ALAND", scale_data = 1e-5, heightmap = montereybay,
                 #max_height = 1000, scale_all_max = TRUE, set_max_height = TRUE,
                 material = rayvertex::material_list(diffuse="red"),
                 light_intensity = 1, light_relative = FALSE,
                 extent = attr(montereybay,"extent"), clear_previous = TRUE,
                 zscale=200) 
render_snapshot()
}

tylermorganwall/rayshader documentation built on Nov. 21, 2024, 8:11 a.m.