- scene
Tibble of object locations and properties.
- width
Default `400`. Width of the render, in pixels.
- height
Default `400`. Height of the render, in pixels.
- fov
Default `20`. Field of view, in degrees. If this is `0`, the camera will use an orthographic projection. The size of the plane
used to create the orthographic projection is given in argument `ortho_dimensions`. From `0` to `180`, this uses a perspective
projections. If this value is `360`, a 360 degree environment image will be rendered.
- samples
Default `100`. The maximum number of samples for each pixel. If this is a length-2
vector and the `sample_method` is `stratified`, this will control the number of strata in each dimension.
The total number of samples in this case will be the product of the two numbers.
- camera_description_file
Default `NA`. Filename of a camera description file for rendering with
a realistic camera. Several camera files are built-in: `"50mm"`,`"wide"`,`"fisheye"`, and `"telephoto"`.
- preview
Default `interactive()`. Whether to display a real-time progressive preview of the render. Press ESC to cancel the render.
If `deferred_render = TRUE`, the preview stays interactive until the final render is explicitly started.
- interactive
Default `interactive()`. Whether the scene preview should be interactive. Camera movement orbits around the
lookat point (unless the mode is switched to free flying), with the following control mapping:
W = Forward, S = Backward, A = Left, D = Right, Q = Up, Z = Down,
Shift-W/Shift-S = Pitch Camera Forward/Back, Shift-A/Shift-D = Roll Camera Left/Right,
E = 2x Step Distance (max 128), C = 0.5x Step Distance, Up Key = Zoom In (decrease FOV), Down Key = Zoom Out (increase FOV),
Left Key = Decrease Aperture, Right Key = Increase Aperture, 1 = Decrease Focal Distance, 2 = Increase Focal Distance,
3/4 = Rotate Environment Light,
Right bracket/left bracket = Increase/Decrease Preview Exposure, Shift + right bracket/left bracket = Increase/Decrease shutter speed,
Shift-Enter = Save Preview Snapshot, R = Reset Camera,
Return = Toggle between deferred and final render if `deferred_render = TRUE`, TAB: Toggle Orbit Mode,
Left Mouse Click: Set Look At and Focal Distance, Right Mouse Click: Set Look At.
If the interactive preview window is wide enough, a status bar at the bottom shows the current camera, exposure, environment rotation,
and keyframe state.
K: Save Keyframe (at the conclusion of the render, this will create the `ray_keyframes`
data.frame in the global environment, which can be passed to `generate_camera_motion()` to tween between those saved positions.
L: Reset Camera to Last Keyframe (if set), Shift-L: Toggle keyframe path open/closed,
< and >: Jump to previous/next keyframe, /: Delete current keyframe,
M: Preview/cancel keyframe motion,
F: Toggle Fast Travel Mode,
B: Toggle Camera Motion Blur,
H: Toggle Atmospheric Haze, Y: Toggle Altitude Queries (with `sky_light()`).
Haze requires altitude queries: enabling haze also enables altitude queries,
and disabling altitude queries also disables haze. Each change restarts sampling.
Initial step size is 1/20th of the distance from `lookat` to `lookfrom`.
With integrator_type = "nee", clicks select the first point where accumulated volume opacity
reaches 15%, or the first ordinary surface if reached sooner. Picking integrates extinction
deterministically with a fixed shutter sample and a centered lens sample. Thin or empty regions
allow selection of surfaces behind them; invisible container faces are skipped. Clicking the
background without reaching this opacity turns perspective and panoramic cameras toward that
direction, preserving focal distance and orbit radius. Orthographic background clicks leave the
view unchanged. Selected surface and volume points remain the orbit center when rotating.
Right clicking preserves the focal distance.
Some options aren't available for all cameras. When using a realistic camera,
the aperture and field of view cannot be changed from their initial settings.
- deferred_render
Default `FALSE`. If `TRUE` and interactive preview is enabled, rayrender will keep
updating the progressive preview until Return is pressed. Pressing Return toggles the full render in the
same window; pressing Return again returns to deferred mode.
- denoise
Default `TRUE`. Whether to de-noise the final image and preview images. Note, this requires
the free Intel Open Image Denoise (OIDN) library be installed on your system. Pre-compiled binaries can be installed from
ppenimagedenoise.org, as well as . Linking during rayrender installation is done by defining the environment variable
OIDN_PATH (set it in the .Renviron file by calling `usethis::edit_r_environ()`) to the top-level directory for OIDN (the directory containing the "lib", "bin", and "include"
directories) and re-installing this package from source.
- camera_scale
Default `1`. Amount to scale the camera up or down in size. Use this rather than scaling a
scene.
- iso
Default `100`. Camera exposure.
- auto_exposure
Default `FALSE`. If `TRUE`, automatically adjust the exposure with
`rayimage::render_exposure(auto = TRUE)`. If `preview = TRUE`, the preview window exposure
is calibrated from the 90% luminance quantile of the first rendered frame.
- film_size
Default `22`, in `mm` (scene units in `m`. Size of the film if using a realistic camera, otherwise
ignored.
- min_variance
Default `0`. Minimum acceptable variance for a block of pixels for the
adaptive sampler. Smaller numbers give higher quality images, at the expense of longer rendering times.
If this is set to zero, the adaptive sampler will be turned off and the renderer
will use the maximum number of samples everywhere.
- min_adaptive_size
Default `8`. Width of the minimum block size in the adaptive sampler.
- sample_method
Default `sobol`. The type of sampling method used to generate
random numbers. The other options are `random` (worst quality but fastest),
`stratified` (only implemented for completion), `sobol_blue` (best option for sample counts below 256),
and `sobol` (slowest but best quality, better than `sobol_blue` for sample counts greater than 256). If
`samples > 256` and `sobol_blue` is selected, the method will automatically switch to `sample_method = "sobol"`.
- max_depth
Default `NA`, automatically sets to 50. Maximum number of bounces a ray can make in a scene. Alternatively,
if a debugging option is chosen, this sets the bounce to query the debugging parameter (only for some options).
- roulette_active_depth
Default `100`. Number of ray bounces until a ray can stop bouncing via
Russian roulette.
- ambient_light
Default `FALSE`, unless there are no emitting objects in the scene.
If `TRUE`, the background will be a gradient varying from `backgroundhigh` directly up (+y) to
`backgroundlow` directly down (-y).
- lookfrom
Default `c(0,1,10)`. Location of the camera.
- lookat
Default `c(0,0,0)`. Location where the camera is pointed.
- camera_up
Default `c(0,1,0)`. Vector indicating the "up" position of the camera.
- aperture
Default `0.1`. Aperture of the camera. Smaller numbers will increase depth of field, causing
less blurring in areas not in focus.
- clamp_value
Default `Inf`. If a bright light or a reflective material is in the scene, occasionally
there will be bright spots that will not go away even with a large number of samples. These
can be removed (at the cost of slightly darkening the image) by setting this to a small number greater than 1.
- filename
Default `NULL`. If present, the renderer will write to the filename instead
of the current device. Can write to JPEG/JPG, PNG, and high dynamic range EXR images. In the
interactive preview, press Shift+Enter to save the current preview. A source filename with an
extension produces numbered snapshots with the number inserted before the extension; otherwise
snapshots are saved as `rayrender_snapshot1.png`, `rayrender_snapshot2.png`, and so on in the
current directory.
- backgroundhigh
Default `#80b4ff`. The "high" color in the background gradient. Can be either
a hexadecimal code, or a numeric rgb vector listing three intensities between `0` and `1`.
- backgroundlow
Default `#ffffff`. The "low" color in the background gradient. Can be either
a hexadecimal code, or a numeric rgb vector listing three intensities between `0` and `1`.
- shutteropen
Default `0`. Time at which the shutter is open. Only affects moving objects.
- shutterclose
Default `1`. Time at which the shutter is open. Only affects moving objects.
- camera_motion_blur
Default `FALSE`. Whether to blur camera movement over the shutter interval. Press `B` in interactive preview to toggle.
- shutter_speed
Default `NULL`. Optional render-time override for the
selected camera's frame-relative shutter speed. A value of `1` samples the
full frame-to-frame motion interval, `2` samples one-half, and `4` samples
one-quarter. Higher values produce less motion blur. `Inf` disables temporal
motion blur. This does not affect exposure or brightness.
- focal_distance
Default `NULL`, automatically set to the `lookfrom-lookat` distance unless
otherwise specified.
- ortho_dimensions
Default `c(1,1)`. Width and height of the orthographic camera. Will only be used if `fov = 0`.
- tonemap
Default `raw`, no tonemapping. Choose the tone mapping function,
`reinhard` scales values by their individual color channels `color/(1+color)` and then performs the
gamma adjustment. `uncharted` uses the mapping developed for Uncharted 2 by John Hable. `hbd` uses an
optimized formula by Jim Hejl and Richard Burgess-Dawson.
- bloom
Default `TRUE`. Set to `FALSE` to get the raw, pathtraced image. Otherwise,
this performs a convolution of the HDR image of the scene with a sharp, long-tailed
exponential kernel, which does not visibly affect dimly pixels, but does result in emitters light
slightly bleeding into adjacent pixels. This provides an antialiasing effect for lights, even when
tonemapping the image. Pass in a matrix to specify the convolution kernel manually, or a positive number
to control the intensity of the bloom (higher number = more bloom).
- parallel
Default `TRUE`. If `FALSE`, it will use all available cores to render the image
(or the number specified in `options("cores")` or `options("Ncpus")` if that option is not `NULL`).
- bvh_type
Default `"sah"`, "surface area heuristic". Method of building the bounding volume
hierarchy structure used when rendering. Other option is "equal", which splits tree into groups
of equal size.
- environment_light
Default `NULL`. An image to be used for the background for rays that escape
the scene. Supports EXR, HDR, PNG, and JPEG images. For reusable scene lights and
multiple environments, use infinite_light() and add_infinite_light(). This
argument adds a light to any infinite lights already attached to the scene.
- rotate_env
Default `0`. The number of degrees to rotate all infinite lights around the scene,
in addition to their individual rotations.
- intensity_env
Default `1`. The amount to increase the intensity of the environment lighting. Useful
if using a LDR (JPEG or PNG) image as an environment map. Applies only to the
`environment_light` argument; scene lights have their own intensity.
- transparent_background
Default `FALSE`. If `TRUE`, any initial camera rays that escape the scene
will be marked as transparent in the final image. If for a pixel some rays escape and others hit a surface,
those pixels will be partially transparent.
- debug_channel
Default `none`. If `depth`, function will return a depth map of rays into the scene
instead of an image. If `normals`, function will return an image of scene normals, mapped from 0 to 1.
If `uv`, function will return an image of the uv coords. If `variance`, function will return an image
showing the number of samples needed to take for each block to converge. If `dpdu` or `dpdv`, function will return
an image showing the differential `u` and `u` coordinates. If `color`, function will return the raw albedo
values (with white for `metal` and `dielectric` materials).
- plot_scene
Default `TRUE`. Whether to plot the rendered scene.
- progress
Default `interactive()` if interactive session, `FALSE` otherwise.
- verbose
Default `FALSE`. Prints information and timing information about scene
construction and raytracing progress.
- print_debug_info
Default `FALSE`. This will print out additional information on the compilation environment with
each render.
- new_page
Default `TRUE`. Whether to call `grid::grid.newpage()` when plotting the image (if
no filename specified). Set to `FALSE` for faster plotting (does not affect render time).
- integrator_type
Default `"rtiow"` (the algorithm specified in the book "Raytracing in One Weekend", a basic
form of path guiding). Other options include `"nee"` (Next Event Estimation, with direct light sampling)
and `"basic"` (basic pathtracing, for high sample reference renders and debugging only).
With `nee`, surfaces and participating media use RGB null-scattering transport;
nee is selected automatically for scenes containing sky_light() or attached
media (including clouds and media inside instances), overriding rtiow or basic.
See set_medium().
- screen_text
Default `NULL`. Optional screen-space text overlay created with `screen_text()`,
or a list of `screen_text()` outputs to draw in order.
- screen_line
Default `NULL`. Optional screen-space line overlay created with `screen_line()`,
or a list of `screen_line()` outputs to draw in order.
Labels are anchored to 3D world-space points, projected through the current camera, and drawn after
rendering so text size and justification are independent of scene scale and view distance.
- camera
Default `NULL`. Scene-attached camera name, `"all"`, or a `ray_camera` object created with `camera()`.
- start_frame
Default `1`. First camera frame to render when using an animated camera.
- end_frame
Default `NA`. Last camera frame to render when using an animated camera. If `NA`, renders through the final frame.
- mode
Default `"auto"`. Rendering mode. `"auto"` renders a still image for static cameras and an animation for animated cameras.