render_depth: Render Depth of Field

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

Render Depth of Field

Description

Adds depth of field to the current RGL scene by simulating a synthetic aperture.

The size of the circle of confusion is determined by the following formula (z_depth is from the image's depth map).

abs(z_depth-focus)*focal_length^2/(f_stop*z_depth*(focus - focal_length))

Usage

render_depth(
  focus = NULL,
  focallength = 100,
  fstop = 4,
  filename = NULL,
  preview_focus = FALSE,
  bokehshape = "circle",
  bokehintensity = 1,
  bokehlimit = 0.8,
  rotation = 0,
  gamma_correction = TRUE,
  aberration = 0,
  transparent_water = FALSE,
  heightmap = NULL,
  zscale = NULL,
  title_text = NULL,
  title_offset = c(20, 20),
  title_color = "black",
  title_size = 30,
  title_font = "sans",
  title_bar_color = NULL,
  title_bar_alpha = 0.5,
  title_position = "northwest",
  image_overlay = NULL,
  vignette = FALSE,
  vignette_color = "black",
  vignette_radius = 1.3,
  progbar = interactive(),
  software_render = FALSE,
  width = NULL,
  height = NULL,
  camera_location = NULL,
  camera_lookat = c(0, 0, 0),
  background = "white",
  text_angle = NULL,
  text_size = 10,
  text_offset = c(0, 0, 0),
  point_radius = 0.5,
  line_offset = 1e-07,
  cache_scene = FALSE,
  reset_scene_cache = FALSE,
  print_scene_info = FALSE,
  instant_capture = interactive(),
  clear = FALSE,
  bring_to_front = FALSE,
  ...
)

Arguments

focus	Focal point. Defaults to the center of the bounding box. Depth in which to blur, in distance to the camera plane.
focallength	Default '1'. Focal length of the virtual camera.
fstop	Default '1'. F-stop of the virtual camera.
filename	The filename of the image to be saved. If this is not given, the image will be plotted instead.
preview_focus	Default 'FALSE'. If 'TRUE', a red line will be drawn across the image showing where the camera will be focused.
bokehshape	Default 'circle'. Also built-in: 'hex'. The shape of the bokeh.
bokehintensity	Default '3'. Intensity of the bokeh when the pixel intensity is greater than 'bokehlimit'.
bokehlimit	Default '0.8'. Limit after which the bokeh intensity is increased by 'bokehintensity'.
rotation	Default '0'. Number of degrees to rotate the hexagon bokeh shape.
gamma_correction	Default 'TRUE'. Controls gamma correction when adding colors. Default exponent of 2.2.
aberration	Default '0'. Adds chromatic aberration to the image. Maximum of '1'.
transparent_water	Default 'FALSE'. If 'TRUE', depth is determined without water layer. User will have to re-render the water layer with 'render_water()' if they want to recreate the water layer.
heightmap	Default 'NULL'. The height matrix for the scene. Passing this will allow 'render_depth()' to automatically redraw the water layer if 'transparent_water = TRUE'.
zscale	Default 'NULL'. The zscale value for the heightmap. Passing this will allow 'render_depth()' to automatically redraw the water layer if 'transparent_water = TRUE'.
title_text	Default 'NULL'. Text. Adds a title to the image, using magick::image_annotate.
title_offset	Default 'c(20,20)'. Distance from the top-left (default, 'gravity' direction in image_annotate) corner to offset the title.
title_color	Default 'black'. Font color.
title_size	Default '30'. Font size in pixels.
title_font	Default 'sans'. String with font family such as "sans", "mono", "serif", "Times", "Helvetica", "Trebuchet", "Georgia", "Palatino" or "Comic Sans".
title_bar_color	Default 'NULL'. If a color, this will create a colored bar under the title.
title_bar_alpha	Default '0.5'. Transparency of the title bar.
title_position	Default 'northwest'. Position of the title.
image_overlay	Default 'NULL'. Either a string indicating the location of a png image to overlay over the image (transparency included), or a 4-layer RGBA array. This image will be resized to the dimension of the image if it does not match exactly.
vignette	Default 'FALSE'. If 'TRUE' or numeric, a camera vignetting effect will be added to the image. '1' is the darkest vignetting, while '0' is no vignetting. If vignette is a length-2 vector, the second entry will control the blurriness of the vignette effect.
vignette_color	Default '"black"'. Color of the vignette.
vignette_radius	Default '1.3'. Radius of the vignette, as a porportion of the image dimensions.
progbar	Default 'TRUE' if in an interactive session. Displays a progress bar.
software_render	Default 'FALSE'. If 'TRUE', rayshader will use the rayvertex package to render the snapshot, which is not constrained by the screen size or requires OpenGL.
width	Default 'NULL'. Optional argument to pass to 'rgl::snapshot3d()' to specify the width when 'software_render = TRUE'..
height	Default 'NULL'. Optional argument to pass to 'rgl::snapshot3d()' to specify the height when 'software_render = TRUE'.
camera_location	Default 'NULL'. Custom position of the camera. The 'FOV', 'width', and 'height' arguments will still be derived from the rgl window.
camera_lookat	Default 'NULL'. Custom point at which the camera is directed. The 'FOV', 'width', and 'height' arguments will still be derived from the rgl window.
background	Default '"white"'. Background color when 'software_render = TRUE'.
text_angle	Default 'NULL', which forces the text always to face the camera. If a single angle (degrees), will specify the absolute angle all the labels are facing. If three angles, this will specify all three orientations (relative to the x,y, and z axes) of the text labels.
text_size	Default '10'. Height of the text.
text_offset	Default 'c(0,0,0)'. Offset to be applied to all text labels.
point_radius	Default '0.5'. Radius of 3D points (rendered with 'render_points()'.
line_offset	Default '1e-7'. Small number indicating the offset in the scene to apply to lines if using software rendering. Increase this if your lines aren't showing up, or decrease it if lines are appearing through solid objects.
cache_scene	Default 'FALSE'. Whether to cache the current scene to memory so it does not have to be converted to a 'raymesh' object each time 'render_snapshot()' is called. If 'TRUE' and a scene has been cached, it will be used when rendering.
reset_scene_cache	Default 'FALSE'. Resets the scene cache before rendering.
print_scene_info	Default 'FALSE'. If 'TRUE', it will print the position and lookat point of the camera.
instant_capture	Default 'TRUE' if interactive, 'FALSE' otherwise. If 'FALSE', a slight delay is added before taking the snapshot. This can help stop prevent rendering issues when running scripts.
clear	Default 'FALSE'. If 'TRUE', the current 'rgl' device will be cleared.
bring_to_front	Default 'FALSE'. Whether to bring the window to the front when rendering the snapshot.
...	Additional parameters to pass to 'rayvertex::rasterize_scene()'.

Value

4-layer RGBA array.

Examples

if(run_documentation()) {
montereybay %>%
 sphere_shade() %>%
 plot_3d(montereybay,zscale=50, water=TRUE, waterlinecolor="white",
         zoom=0.3,theta=-135,fov=70, phi=20) 
 
#Preview where the focal plane lies
render_depth(preview_focus=TRUE)
}
if(run_documentation()) {
#Render the depth of field effect
render_depth(focallength = 300)
}
if(run_documentation()) {
#Add a chromatic aberration effect
render_depth(focallength = 300, aberration = 0.3)
}
if(run_documentation()) {
#Render the depth of field effect, ignoring water and re-drawing the waterlayer
render_depth(preview_focus=TRUE, 
            heightmap = montereybay, zscale=50, focallength=300, transparent_water=TRUE)
render_depth(heightmap = montereybay, zscale=50, focallength=300, transparent_water=TRUE)
render_camera(theta=45,zoom=0.15,phi=20)
}

if(run_documentation()) {
#Change the bokeh shape and intensity
render_depth(focus=900, bokehshape = "circle",focallength=500,bokehintensity=30,
            title_text = "Circular Bokeh", title_size = 30, title_color = "white", 
            title_bar_color = "black")
render_depth(focus=900, bokehshape = "hex",focallength=500,bokehintensity=30,
            title_text = "Hexagonal Bokeh", title_size = 30, title_color = "white", 
            title_bar_color = "black")
}

if(run_documentation()) {
#Add a title and vignette effect.
render_camera(theta=0,zoom=0.7,phi=30)
render_depth(focallength = 250, title_text = "Monterey Bay, CA", 
            title_size = 20, title_color = "white", title_bar_color = "black", vignette = TRUE)
}

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