bg3d {rgl}

Set up background

Description

Set up the background of the scene.

Usage

bg3d(color,
    sphere=FALSE, 
    back="lines",
    fogtype="none",
    fogScale = 1, 
    col, ...)

Arguments

color, col

See Details below.

sphere

logical: if TRUE, an environmental sphere geometry is used for the background decoration.

back

Specifies the fill style of the sphere geometry. See material3d for details.

fogtype

fog type:

"none"

no fog

"linear"

linear fog function

"exp"

exponential fog function

"exp2"

squared exponential fog function

Fog only applies to objects with material3d property fog set to TRUE.

fogScale

Scaling for fog. See Details.

...

Additional material properties. See material3d for details.

Details

The background color is taken from color or col if color is missing. The first entry is used for background clearing and as the fog color. The second (if present) is used for background sphere geometry.

If color and col are both missing, the default is found in the r3dDefaults$bg list, or "white" is used if nothing is specified there.

If sphere is set to TRUE, an environmental sphere enclosing the whole scene is drawn.

If not, but the material properties include a bitmap as a texture, the bitmap is drawn in the background of the scene. (The bitmap colors modify the general color setting.)

If neither a sphere nor a bitmap background is drawn, the background is filled with a solid color.

The fogScale parameter should be a positive value to change the density of the fog in the plot. For fogtype = "linear" it multiplies the density of the fog; for the exponential fog types it multiplies the density parameter used in the display.

See the OpenGL 2.1 reference for the formulas used in the fog calculations within R (though the "exp2" formula appears to be wrong, at least on my system). In WebGL displays, the following rules are used. They appear to match the rules used in R on my system.

• For "linear" fog, the near clipping plane is taken as c=0, and the far clipping plane is taken as c=1. The amount of fog is s * c clamped to a 0 to 1 range, where s = fogScale.

• For "exp" and "exp2" fog, the observer location is negative at a distance depending on the field of view. The formula for the distance is

  c = [1-sin(theta)]/[1 + sin(theta)]

  where theta = FOV/2. We calculate

  c' = d(1-c) + c

  so c' runs from 0 at the observer to 1 at the far clipping plane.

• For "exp" fog, the amount of fog is 1 - exp(-s * c').

• For "exp2" fog, the amount of fog is 1 - exp[-(s * c')^2].

See Also

material3d, bgplot3d to add a 2D plot as background.

Examples

  open3d()
  
  # a simple white background
  
  bg3d("white")

  # the holo-globe (inspired by star trek):

  bg3d(sphere = TRUE, color = c("black", "green"), lit = FALSE, back = "lines" )

  # an environmental sphere with a nice texture.

  bg3d(sphere = TRUE, texture = system.file("textures/sunsleep.png", package = "rgl"), 
         back = "filled" )
         
  # The same texture as a fixed background
  
  open3d()
  bg3d(texture = system.file("textures/sunsleep.png", package = "rgl"), col = "white")