rayshader (version 0.25.2)

render_depth: 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,
  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 = 30,
  text_offset = c(0, 0, 0),
  point_radius = 0.5,
  cache_filename = NULL,
  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.

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. Consider settings a `cache_filename` so a new OBJ file doesn't have to be written with every snapshot.

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 `30`. 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()`.

cache_filename

Default `NULL`. Name of temporary filename to store OBJ file, if the user does not want to rewrite the file each time.

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

# NOT RUN {
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)

#Render the depth of field effect
render_depth(focallength = 300)

#Add a chromatic aberration effect
render_depth(focallength = 300, aberration = 0.3)

#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)

#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")

#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)
            
#
rgl::rgl.close()
# }