rayshader (version 0.37.3)

render_beveled_polygons: 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()
}