pbrt-v4 User's Guide (2024)

Example scenes

See the resources page for links to avariety of sources of interesting scenes to render with pbrt-v4.

Choosing an integrator

pbrt-v4 provides approximately ten choices for the "integrator" that isused to compute solutions to the rendering equation. In most cases,the default "volpath" integrator is the most effective choice; it handlescomplex direct and indirect lighting and offers state-of-the-artalgorithms for rendering participating media. (When rendering on theGPU or using the "wavefront" integrator on the CPU, there is no choice ofintegrator and the integrator used has equivalent functionality to the"volpath" integrator).

In scenes with focused indirect light due to specular reflection(caustics) or with other forms of difficult-to-sample indirect lighting,the "bdpt" integrator, which uses bidirectional path tracing, may be abetter choice. However, its sampling algorithms for volumetric media(and especially chromatic volumetric media) are not as good as those ofthe "volpath" integrator. Further, it has the disadvantage that itsperformance doesn't scale well as the maximum depth parameter isincreased since the number of shadow rays traced to connect the cameraand light paths grows quadratically with path length.

For scenes with especially challenging indirect lighting or caustics,the "mlt" integrator may be more effective than the "bdpt" integrator.It applies Metropolis sampling algorithms, which allows the reuse oflight carrying paths; this can improve results when it is challenging tosample light carrying paths. However, this benefit comes at the cost ofincreased correlation between paths which can manifest itself aslow-frequency noise in images. Further, the "mlt" integrator is built ontop of the "bdpt" integrator and so inherits its shortcomings withrespect to chromatic media.

The "sppm" integrator is an alternative to the "bdpt" integrator forscenes with tricky indirect lighting and caustics; it is based on thestochastic progressive photon mapping algorithm. When it is used, errorin images is manifested with low-frequency noise at low sampling rates.This integrator does not support volumetric scattering.

The remaining integrators are primarily useful for pedagogical purposesor as baselines for evaluating other integration algorithms.

Choosing a sampler

pbrt-v4 also provides a variety of samplers that are used byintegrators to generate sample points for Monte Carlo integration. Whenrendering complex scenes, most of them give similar results, especiallyat higher sampling rates.

The default "zsobol" sampler is especially effective at low samplingrates; it decorrelates sample values at nearby pixels which tends tocause error in the image to have a "blue noise" (i.e., high frequency)distribution. This tends to be more visually pleasing to humanobservers than lower-frequency noise and is generally more friendly inputto provide to denoising algorithms.

If higher sampling rates are to be used, the "halton" or"sobol" sampler is likely to give slightly better results. Note that the"independent" and "stratified" samplers should not generally be usedexcept as a baseline for comparing the performance of more sophisticatedsamplers.

GPU rendering

If your system has a supported GPU and if pbrt was compiled with GPUsupport, the GPU rendering path can be selected usingthe --gpu command-line option. When used, anyintegrator specified in the scene description file is ignored, and anintegrator that matches the functionality ofthe VolPathIntegrator on the CPU is used:unidirectional path tracing with state-of-the-art support for volumetricscattering.

The GPU rendering path can also execute on the CPU: specifythe --wavefront command-line option to use it.This capability can be especially useful for debugging. We note,however, that execution on the CPU and GPU will not give precisely thesame results, largely due to ray-triangle intersections being computedusing different algorithms, leading to minor floating-point differences.

Interactive rendering

pbrt-v4 provides an interactive rendering mode that is enabled usingthe --interactive command-line option.When it is used, pbrt opens a window and displays the image as it isrendered. Rendering restarts from the first sample after the cameramoves and pbrt exits as usual, writing out the final image once thespecified number of pixel samples have been taken. (Thus, you may wantto specify a very large number of pixel samples if you do not want pbrtto exit.)

The following keyboard controls are provided:

• w, a, s, d: move the camera forward and back, left and right.
• q, e: move the camera down and up, respectively.
• Arrow keys: adjust the camera orientation.
• B, b: respectively increase and decrease the exposure("brightness").
• c: print the transformation matrix for the current cameraposition.
• -, =: respectively decrease and increase the rate of cameramovement.

Note that using many CPU cores, using pbrt's GPU rendering path, orrendering low resolution images will be necessary for interactiveperformance in practice.

Working with images

pbrt is able to write images in a variety of formats, including OpenEXR,PNG, and PFM. We recommend the use of OpenEXR if possible, as it is ableto represent high dynamic range images and has the flexibility to encodeimages with additional geometric information at each pixel as well asspectral images (see below).

While many image viewers can display RGB OpenEXR images, it isworthwhile to use a capable viewer that allows close inspection of pixelvalues, makes it easy to determine the coordinates of a pixel, andsupports display of additional image channels. We have foundThomas Müller'stev image viewer to be anexcellent tool for working with images rendered by pbrt; it runs onWindows, Linux, and OSX.

The pbrt distribution also includes a command-line program for workingwith images, imgtool. It provides a range ofuseful functionality, including conversion between image formats andvarious ways of computing compute the error of images with respect to areference. Run imgtool to see a list of thecommands it offers. Further documentation about a particular command canbe found by running, e.g., imgtool help convert.

"Deep" images with auxiliary information

When the "gbuffer" film is used, pbrt will write out EXR images thatinclude the following image channels. The auxiliary information theyinclude is especially useful for denoising rendered images and for theuse of rendered images for ML training:

• {R,G,B}:Pixel color (as is also output by the regular "rgb" film).
• Albedo.{R,G,B}: red, green, and blue albedo of the first visiblesurface
• P{x,y,z}: x, y, and z components of the position.
• u, v: u and v coordinates of the surface parameterization.
• dzd{x,y}: partial derivatives of camera-space depth z withrespect to raster-space x and y.
• N{x,y,z}: x, y, and z components of thegeometric surface normal.
• Ns{x,y,z}: x, y, and z components of the shadingnormal, including the effect of interpolated per-vertex normals andbump/or normal mapping, if present.
• Variance.{R,G,B}: sample variance of the red, green, and blue pixel color.
• RelativeVariance.{R,G,B}: relative sample variance of red, green, andblue.

The geometric quantities—position, normal, and screen-space z derivatives—arein camera space by default. Alternatively, the "gbuffer" film's "coordinatesystem"parameter can be used to specify world space output; see the file formatdocumentation for details. Note also that pbrt records thecamera-from-world and NDC-from-world transformation matrices in themetadata of the EXR files that it generates; these can be helpful whenworking with those geometric values.

Spectral output

The "spectral" film records images where a specified range ofwavelengths is discretized into buckets the radiance in each wavelengthrange is recorded separately. The images are then stored using OpenEXRbased on an encoding proposedby Fichet et al. (Italso stores "R", "G", and "B" color channels so that the images itgenerates can be viewed in non-spectral-aware image viewers.)

Converting scenes to pbrt’s format

For scenes in a format that can be readby assimp, we have foundthat converting them to pbrt's format using assimp's pbrt-v4 exporterusually works well. It is the preferred approach for formats like FBX.See also the scene exporterssection in the resources page forinformation about exporters from specific modeling and animationsystems.

However, a scene exported using assimp or one of the other exporters isunlikely to immediately render beautifully at first export. Here are somesuggestions for how to take an initial export and turn it into somethingthat looks great.

First, you may find it useful to run

$ pbrt --toply scene.pbrt > newscene.pbrt

This will convert triangle meshes into more compact binary PLY files,giving you a much smaller pbrt scene file to edit and a scene that will befaster to parse, leading to shorter start-up times.

The Camera

Next, if the exporter doesn’t include camera information, the nextthing to do is to find a good view. If your computer has sufficientperformance, the --interactive option to pbrtallows you to interactively position the camera and then print thetransformation matrix that positions the camera(see above).

Lacking interactive rendering, the “spherical” camera (which renders animage in all directions) can be useful for orienting yourself and forfinding a good initial position for the camera. (Setting the “stringmapping” parameter to “equirectangular” gives a spherical image that iseasier to reason about than the default equal-area mapping.) Keeprendering images and adjusting the camera position to taste. (Forefficiency, you may want to use as few pixel samples as you can tolerateand learn to squint and interpret noisy renderings!) Then, you can use thecamera position you’ve chosen as the basis for specifyinga LookAt transformation for a more conventionalcamera model.

Lighting

If the lighting hasn't been set up, it can be helpful to have a pointlight source at the camera’s position while you're placing thecamera. Adding a light source like the following to your scene file doesthis in a way that ensures that the light moves appropriately to whereverthe camera has been placed. (You may need to scale the intensity up or downfor good results–remember the radius-squared falloff!

AttributeBeginCoordSysTransform "camera"LightSource "point" "color I" [10 10 10]AttributeEnd

Once the camera is placed, we have found that it’s next useful to set upapproximate light sources. For outdoor scenes, a good HDR environment mapis often all that is needed for lighting. (You may want to consider usingimgtool makesky to make a realistic HDR skyenvironment map, orsee polyhaven, which has a widevariety of high-quality and freely-available HDR environment maps.)

For indoor scenes, you may want a combination of an environment map forthe outside and point and/or area light sources for interior lights. Youmay find it useful to examine the scene in the modeling system that it camefrom to determine which geometry corresponds to area light sources and totry adding AreaLightSource properties tothose. (Note that in pbrt, area light sources only emit lights on the sidethat the surface normal points; you may needa ReverseOrientation directive to make the lightcome out in the right direction.)

Materials

Given good lighting, the next step is to tune the materials (or set themfrom scratch). It can be helpful to pick a material and set it to anextreme value (such as a “diffuse” material that is pure red) and renderthe scene; this quickly shows which geometric models have that materialassociated with it.

To find out which material is visible in a given pixel,the --pixelmaterial command-line option can beuseful: for all intersections along a ray through the center of the pixel,it prints geometric information about each intersection for all of thematerials from front to back. For a material specifiedusing Material in the scene description file, theoutput will be of the form:

Intersection depth 1World-space p: [ 386.153, 381.153, 560 ]World-space n: [ 0, 0, 1 ]World-space ns: [ 0, 0, 1 ]Distance from camera: 1070.9781[ DiffuseMaterial displacement: (nullptr) normapMap: (nullptr)reflectance: [ SpectrumImageTexture filename: ../textures/grid.exr[...further output elided...]

In this case we can see that the “diffuse” material was used with no bumpor normal map, and ../textures/grid.exr as atexture map for the reflectance.

If a material has been defined usingpbrt's MakeNamedMaterial directive, the outputwill along the lines of:

Intersection depth 1World-space p: [ 0.95191336, 1.1569455, 0.50672007 ]World-space n: [ 0.032488506, -0.851931, -0.5226453 ]World-space ns: [ 0.02753538, -0.8475513, -0.5299988 ]Distance from camera: 6.3228507Named material: MeshBlack_phong_SG

As you figure out which material names correspond to what geometry,watch for objects that are missing texture maps andadd Texture specifications for them and use themin their materials. (The good news is that such objects generally do havecorrect texture coordinates with them, so this usually goes smoothly. Insome cases it may be necessary to specify a custom UV mapping like"planar", "spherical", or "cylindrical".)