Overview

This document is a reference to the file format used in pbrt-v4, the version of the system corresponding to the forthcoming fourth edition of Physically Based Rendering; it serves as a comprehensive reference. The pbrt-v4 User's Guide documents how to use pbrt with more focus on how to achieve various tasks.

The scene description files used by pbrt are plain text files. The file format was designed so that it would be both easy to parse and easy for applications to generate from their own internal representations of scenes.

A pbrt scene file consists of a series of statements; different statements specify the geometry and light sources in the scene and set overall rendering parameters (such as which light transport algorithm to use or the image resolution). Each statement in these files corresponds directly to a pbrt API method defined in the ParserTarget class in pbrt-v4. (See also Appendix C in the fourth edition of the Physically Based Rendering book.) For example, when the WorldBegin statement appears in the input, an implementation of the ParserTarget::WorldBegin() method is called.

Differences from pbrt-v3

We have tried to minimize changes to the file format in order to make it as easy as possible to use existing scene description files with pbrt-v4. However, a number of changes were necessary for new functionality or changes in the system's implementation.

To make it easier to bring pbrt-v3 scenes to pbrt-v4, pbrt now provides an --upgrade command-line option:

$ pbrt --upgrade scene.pbrt > scene-v4.pbrt
In some cases, it may not be possible to upgrade pbrt-v3 scenes automatically; pbrt will then issue an error indicating which part of the scene description requires manual attention.

Major changes to the scene description include:

  • Environment maps used for image-based lighting should now use Clarberg's equal-area mapping. pbrt's imgtool utility provides a makeequiarea operation that converts equirectangular environment maps (as used in pbrt-v3) to this parameterization.
  • The WorldEnd directive has been removed. WorldBegin is still used to separate rendering options from the scene specification but rendering then begins when the end of the input files is reached. This change means that multiple images can no longer be rendered from a single invocation of pbrt, though that feature was both rarely used and buggy.
  • The TransformBegin and TransformEnd directives have also been removed. AttributeBegin and AttributeEnd should be used instead. (In pbrt, they have nearly the same semantics.)
  • The parser has become more strict about types in parameter lists. For example, "point P" will now give an error; "point3 P" must be used instead. (Previously, both were allowed.)
  • The set of materials provided by pbrt is nearly all new and better reflects modes of physical scattering at surfaces. (Thus, for example, materials like "mirror" and "plastic" are no longer available, having been replaced with "conductor" and "coateddiffuse", which provide functionality that is a superset of those.)
  • Various parameter names have been changed to improve clarity or consistency. (For example, the xwidth parameter to various pixel reconstruction filters is now named xradius.) Refer to the the pbrt-v4 File Format documentation for further details.
  • The "image" Film is gone; use "rgb" instead.
  • The "fourier" material is no longer supported and has been replaced with "measured", which is based on a parameterization that better matches measured BRDF data.

Example of a pbrt file

Here is a short example of a pbrt input file: Between the start of the file and the WorldBegin statement, overall options for rendering the scene are specified, including the camera type and position, the sampler definition, and information about the image to be generated. After WorldBegin, the lights, geometry, and scattering volumes (if any) in the scene are defined.

cpLookAt 3 4 1.5  # eye
       .5 .5 0  # look at point
       0 0 1    # up vector
Camera "perspective" "float fov" 45

Sampler "halton" "integer pixelsamples" 128
Integrator "volpath"
Film "rgb" "string filename" "simple.png"
     "integer xresolution" [400] "integer yresolution" [400]

WorldBegin

# uniform blue-ish illumination from all directions
LightSource "infinite" "rgb L" [ .4 .45 .5 ]

# approximate the sun
LightSource "distant"  "point3 from" [ -30 40  100 ]
   "blackbody L" 3000 "float scale" 1.5

AttributeBegin
  Material "dielectric"
  Shape "sphere" "float radius" 1
AttributeEnd

AttributeBegin
  Texture "checks" "spectrum" "checkerboard"
          "float uscale" [16] "float vscale" [16]
          "rgb tex1" [.1 .1 .1] "rgb tex2" [.8 .8 .8]
  Material "diffuse" "texture reflectance" "checks"
  Translate 0 0 -1
  Shape "bilinearmesh"
      "point3 P" [ -20 -20 0   20 -20 0   -20 20 0   20 20 0 ]
      "point2 uv" [ 0 0   1 0    1 1   0 1 ]
AttributeEnd

When this input file is rendered with pbrt-v4, this image is generated:

textured
  disk

General structure of a pbrt input file

A scene description file starts with a series of directives that describe the camera, film, and sampling and light transport algorithms to use in rendering the scene. These are followed by the WorldBegin directive; after WorldBegin, the world definition block starts, and it is no longer legal to specify different definitions of any of the objects defined in the initial section of the file. However, lights, materials, textures, and shapes, can be defined inside the world block (and can only be defined inside the world block). Participating media can be specified before or after WorldBegin, as it can be associated with cameras, lights, and shapes.

The following section, Scene-wide rendering options, documents the directives that are valid outside of the world definition block. The subsequent section, Describing the scene, documents the directives for defining the shapes, materials, lights, etc., that define the scene.

When there is nothing left to parse, rendering begins. At this point, the Integrator defined takes control and performs the required rendering computation.

The hash character # denotes that the rest of the line is a comment and should be ignored by the parser.

Some of the statements in the input file, such as WorldBegin, AttributeEnd, and so on, have no additional arguments. Others, such as those related to specifying transformations, such as Rotate and LookAt, take a predetermined number of arguments of predetermined type. (For example, Translate is followed by three floating-point values that give the x, y, and z components of the translation vector.) The remainder of the statements take a variable number of arguments and are of the form:

identifier "type" parameter-list

For example, the Shape identifier describes a shape to be added to the scene, where the type of shape to create is given by a string (e.g. "sphere") and is followed a list of shape-specific parameters that define the shape. For example,

Shape "sphere" "float radius" [5]

defines a sphere of radius 5. (See Shapes for documentation of the parameters taken by the various shapes implemented in pbrt.)

For these statements, the "type" string gives the name of the particular shape, light., etc., and parameter-list gives the parameters to pass to the implementation. With this design, pbrt's parser doesn't need to know anything about the semantics of the parameters; it just needs to know how to parse parameter lists and store the parameter names and values that it finds in a structure for later processing.

Parameter Lists

Variable-length lists of named parameters and their values are the key meeting ground between the parsing system and the objects that are created to represent the scene. Each of these lists holds an arbitrary number of name/value pairs, with the name in quotation marks and the value or values in square brackets (if there is only a single value, the brackets are optional):

"type name" [ value or values ]

For example,

"float fov" [30]

specifies a parameter "fov" that is a single floating-point value, with value 30.

Alternatively,

"float cropwindow" [0 .5 0 .25]

specifies that "cropwindow" is a floating-point array with the given four values.

The type of each parameter must always be given along with its name; pbrt has no built-in knowledge of any parameter names. This simplifies the parsing system, although it does create a small burden for the creator of the input file.

pbrt supports eleven parameter types: integer, float, point2, vector2, point3, vector3, normal3, spectrum, rgb, blackbody, bool, and string.

The point2 and vector2 types take two floating-point values to specify each value (and similarly for their 3D equivalents). string parameters must be inside quotation marks, and bool parameters are set with the values true and false, quotation marks included.

"string filename" "foo.exr"
"point origin" [ 0 1 2 ]
"normal N" [ 0 1 0  0 0 1 ] # array of 2 normal values
"bool renderquickly" true

pbrt provides three different ways of specifying spectral values in scene description files. RGB values are commonly used, though see the discussion in Section 5.2.2 on page 325 of the third edition of "Physically Based Rendering" for discussion of the shortcomings of this representation. RGB color values can be specified with the rgb type. (They are interpreted as being with respect to the current RGB color space, which can be specified using the ColorSpace directive, which is described below):

"rgb reflectance" [ .2 .5 .3 ]

specifies the RGB color with red equal to 0.2 and so forth.

Alternatively, a normalized blackbody spectral distribution with maximum value of 1 can be specified using blackbody.

"blackbody emission" 6500

General spectral distributions can be specified with a series of (wavelength, value) pairs, where wavelengths are specified in nm:

"spectrum reflectance" [ 300 .3  400 .6   410 .65  415 .8  500 .2  600 .1 ]

specifies a piecewise-linear SPD with a value of 0.3 at 300nm, 0.6 and 400nm, and so forth. Since complex sampled SPDs may have many values, they can also be provided using a file on disk:

"spectrum reflectance" "filename"

Where the filename specifies the path to a plain text file with pairs of floating-point (wavelength, value) as above. The parser for these files allows uses # to denote a comment that goes to the end of the current line.

A number of useful spectral distributions are built in to pbrt; if the following names are provided as string values to spectrum parameters, the corresponding spectral distribution is used:

String Description
"glass-BK7" Index of refraction for BK7 glass
"glass-BAF10" Index of refraction for BAF10 glass
"glass-FK51A" Index of refraction for FK51A glass
"glass-LASF9" Index of refraction for LASF9 glass
"glass-F5" Index of refraction for F5 glass
"glass-F10" Index of refraction for F5 glass
"glass-F11" Index of refraction for F11 glass
"metal-Ag-eta" / "metal-Ag-k" Index of refraction and extinction coefficient for silver.
"metal-Al-eta" / "metal-Al-k" Index of refraction and extinction coefficient for aluminium.
"metal-Au-eta" / "metal-Au-k" Index of refraction and extinction coefficient for gold.
"metal-Cu-eta" / "metal-Cu-k" Index of refraction and extinction coefficient for copper.
"metal-CuZn-eta" / "metal-CuZn-k" Index of refraction and extinction coefficient for copper zinc alloy.
"metal-MgO-eta" / "metal-MgO-k" Index of refraction and extinction coefficient for magnesium oxide.
"metal-TiO2-eta" / "metal-TI02-k" Index of refraction and extinction coefficient for titanium dioxide.
"stdillum-A" CIE standard illuminant A.
"stdillum-D50" CIE standard illuminant D50.
"stdillum-D65" CIE standard illuminant D65.
"stdillum-F1" – "stdillum-F12" CIE standard illuminants F1 through F12.
"illum-acesD60" D60 illuminant from ACES.

Transformations

A series of directives modify the current transformation matrix (CTM). When the scene's camera is specified with a Camera directive, the CTM defines the world to camera transformation; when a light or shape is created, the CTM specifies the transformation from object space to world space.

When parsing begins, the CTM is the identity transformation; furthermore, it is is reset to the identity when the WorldBegin directive is encountered. The following directives modify the CTM:

Input File Syntax
Identity
Translate x y z
Scale x y z
Rotate angle x y z
LookAt eye_x eye_y eye_z look_x look_y look_z up_x up_y up_z
CoordinateSystem "name"
CoordSysTransform "name"
Transform m00 ... m33
ConcatTransform m00 .. m33

For example, Translate takes three floating-point values, x, y, and z, and cause the CTM to be set it to its product of with the matrix representing the given translation. An arbitrary transformation to multiply the CTM with can be specified using ConcatTransform; alternatively, Transform resets the CTM to the specified matrix.

A name can be associated with the CTM using the CoordinateSystem directive. In turn, the CTM can later be reset to the recorded transformation using CoordSysTransform. pbrt automatically records the camera transformation matrix in the "camera" named coordinate system; this can be useful for placing light sources with respect to the camera, for example.

pbrt supports animated transformations by allowing two transformation matrices to be specified at different times. The TransformTimes directive, which must be outside of the world definition block, defines these two times with floating-point values:

TransformTimes start end

Then, the ActiveTransform directive indicates whether subsequent directives that modify the CTM should apply to the transformation at the starting time, the transformation at the ending time, or both. The default is that both matrices should be updated:

Translate 1 0 0  # applies to both, by default
ActiveTransform StartTime
Rotate 90 1 0 0
ActiveTransform EndTime
Rotate 120 0 1 0
ActiveTransform All

Including Files

Two statements make it possible to specify other files to be parsed. The first of them is Include, which behaves similarly to the #include directive in C++, in that parsing of the current file is suspended; the specified file is parsed in its entirety; and only then does parsing of the current file resume. Its effect is equivalent to direct text substitution of the included file.

Include "geometry/car.pbrt"

The Import directive can also be used to specify a file to be parsed. It is similar to Include in that it takes a single filename argument, but its semantics are that the definitions of any named objects—object instances, named textures, named materials, or named participating media—are not made available in the initial file after the Import statement. Thus, Import does not correspond to direct text substitution. In return for this restriction, it is possible to parse imported files in parallel; judicious use of Import can thus significantly improve pbrt's startup time when rendering complex scenes.

Import "geometry/complex-car.pbrt"

If the filename given to a Include or Import statement is not an absolute path, its path is interpreted as being relative to the directory of the initial file being parsed as specified with pbrt's command-line arguments.

Scene-wide rendering options

This section describes rendering options that must be specified before the WorldBegin statement.

General Options

A number of general options that control rendering can be specified using the Option directive. Many of these can also be specified via command-line arguments.

Option "bool" "pixelstats" true

Cameras

The Camera directive specifies the camera used for viewing the scene.

The default camera is a PerspectiveCamera with a 90 degree field of view:

Camera "perspective" "float fov" [90]

When the Camera directive is encountered in an input file, the current transformation matrix is used to initialize the world-to-camera transformation.

pbrt provides four camera implementations:

Option Default Value Description
bool disablepixeljitter false Forces all pixel samples to be through the center of the pixel area. Enabling this can be useful when computing reference images and then computing error with respect to them in that it eliminates differences due to geometric sampling that may not be of interest.
bool disabletexturefiltering false Forces point sampling at the finest MIP level for all texture lookups. (Rarely useful.)
bool disablewavelengthjitter false Forces all samples within each pixel to sample the same wavelengths. RGB will generally have objectionable color error but this can also be useful when computing error with respect to reference images when error due to random wavelength sampling shouldn't be included.
float displacementedgescale 1 Global scale factor applied to triangle edge lengths before evaluating the edge length test for refinement when applying displacement mapping. Increasing this value will generally reduce memory use and startup time when rendering scenes with displacement mapping.
string msereferenceimage (none) Specifies the filename of an image to use when computing mean squared error versus the number of pixel samples taken (see "msereferenceout" below).
string msereferenceout (none) Filename for per-sample mean squared error results. When both this and "msereferenceimage" are specified, the mean squared error of the current image and the reference image is comptued after each sample is taken and the results are stored in text format in this file.
string rendercoordsys (camera, cameraworld, world) "cameraworld" Specifies the coordinate system to use for rendering computation. The default, "cameraworld" translates the scene so that the camera is at the origin. "camera" uses camera space (performance may suffer due to the scene being rotated) and "world" uses world space (accuracy may suffer due to floating-point precision).
integer seed 0 Seed to use for pseudo-random number generation during rendering. Rendering a scene with different seed values will give independent results, which can be useful for statistical analysis.
bool forcediffuse
bool pixelstats
bool wavefront
Name Implementation Class
"orthographic" OrthographicCamera
"perspective" PerspectiveCamera
"realistic" RealisticCamera
"spherical" SphericalCamera

Two parameters that set the camera's shutter open times are common to all cameras in pbrt.

Type Name Default Value Description
float shutteropen 0 The time at which the virtual camera shutter opens.
float shutterclose 1 The time at which the virtual camera shutter closes.

The PerspectiveCamera and OrthographicCamera share two additional parameters that describe the imaging area:

Type Name Default Value Description
float frameaspectratio (see description) The aspect ratio of the film. By default, this is computed from the x and y resolutions of the film, but it can be overridden if desired.
float screenwindow (see description) The bounds of the film plane in screen space. By default, this is [-1,1] along the shorter image axis and is set proportionally along the longer axis.

PerspectiveCamera and OrthographicCamera also support images that include depth of field. They both use the following two parameters to set parameters related to lens focus.

Type Name Default Value Description
float lensradius 0 The radius of the lens. Used to render scenes with depth of field and focus effects. The default value yields a pinhole camera.
float focaldistance 10^30 The focal distance of the lens. If "lensradius" is zero, this has no effect. Otherwise, it specifies the distance from the camera origin to the focal plane.

The perspective camera has a parameter for setting the camera's field of view.

Type Name Default Value Description
float fov 90 Specifies the field of view for the perspective camera. This is the spread angle of the viewing frustum along the narrower of the image's width and height.

The SphericalCamera captures light arriving at the camera from all directions. It takes a parameter that describes the mapping to use from directions to 2D points on the image.

Type Name Default Value Description
string mapping "equalarea" By default, an area-preserving mapping based on an octahedral encoding of the unit sphere is used. Alternatively, an equirectangular mapping can be specified using "equirectangular".

The RealisticCamera simulates imaging from light rays passing through complex lens systems. It takes a number of additional parameters.

Type Name Default Value Description
string lensfile "" Specifies the name of a lens description file that gives the collection of lens elements in the lens system. A number of such lenses are available in the lenses directory in the pbrt-v3 scenes distribution.
float aperturediameter 1.0 Diameter of the lens system's aperture, specified in mm. The smaller the aperture, the less light reaches the film plane, but the greater the range of distances that are in focus.
float focusdistance 10.0 Distance in meters at which the lens system is focused.
string aperture (unspecified) Allows specifying the shape of the camera aperture, which is circular by default. The values of "gaussian", "square", "pentagon", and "star" are associated with built-in aperture shapes; other values are interpreted as filenames specifying an image to be used to specify the shape.

Samplers

The Sampler generates samples for the image, time, lens, and Monte Carlo integration. A number of implementations are provided; the default "zsobol"—is an instance of the ZSobolSampler that takes 16 samples per pixel.

Name Implementation Class
"halton" HaltonSampler
"independent" IndependentSampler
"paddedsobol" PaddedSobolSampler
"sobol" SobolSampler
"stratified" StratifiedSampler
"zsobol" ZSobolSampler

Note that the IndependentSampler is the least effective of the samplers and is mostly included only for comparison with more sophisticated approaches.

For samplers that use pseudorandom values (either directly when jittering sample positions or for scrambling), a seed for the pseudorandom number generator can be specified. Specifying different seeds makes it possible to do intependent runs of pbrt, which can be useful for analysis of convergence or error of various sampling algorithms.

Type Name Default Value Description
integer seed (See description) A seed to use for the pseudorandom number generator. The default seed value is zero, though the --seed command-line argument can be used to specify a different seed. If a seed is specified in the scene description file, it overrides a value specified on the command-line.

All of the samplers other than the StratifiedSampler take a "pixelsamples" parameter that sets the number of samples to take in each pixel area. For PaddedSobolSampler, SobolSampler, and ZSobolSampler, this value must be a power of two. For those, if a non-power-of-two value is provided, it is rounded up to the next power of two.

Type Name Default Value Description
integer pixelsamples 16 The number of samples to take in each pixel.

The four Samplers that are based on low-discrepancy sample points (HaltonSampler, PaddedSobolSampler, SobolSampler, and ZSobolSampler) provide an option that chooses among alorithms that randomize the sample points while still preserving their low-discrepancy properties.

Type Name Default Value Description
string randomization "fastowen" ("permutedigits" for the HaltonSampler). Specifies a randomization algorithm to use. "none" disables randomization; "permutedigits" applies a random permutation to the digits of the sample; "owen" applies Owen scrambling; "fastowen" (not available with the the HaltonSampler) applies an efficient approximation to Owen scrambling.

The StratifiedSampler takes separate specifications of the number of pixel samples in each of the two dimensions and also provides control of whether samples are jittered.

Type Name Default Value Description
bool jitter true Whether or not the generated samples should be jittered inside each stratum; this is generally only worth setting to "false" for comparisons between jittered and uniform sampling—uniform sampling will almost always give a worse result.
integer xsamples 4 The number of samples per pixel to take in the x direction.
integer ysamples 2 4he number of samples per pixel to take in the y direction. In general, "xsamples" and "ysamples" should be set to the same value for best results.

Color Spaces

RGB colors specified in the scene description are interpreted with respect to the current color space when the RGB value is encountered. (For images used as texture maps, the current color space is not used; RGB images are interpreted as being sRGB unless they are stored in an image format like OpenEXR that allows encoding the color space and another color space is specified in the image's metadata.)

The ColorSpace directive specifies the current color space.

ColorSpace "rec2020"

Four color spaces are currently available.

Name Description
aces2065-1 The standard color space defined in the Academy Color Encoding System.
rec2020 The ITU-R Recommendation BT.2020 color space.
dci-p3 The DCI-P3 color space, widely used in current displays.
srgb The venerable sRGB color space; it has the smallest gamut of pbrt-v4's color spaces, but is still widely used.

Film

The Film directive specifies the characteristics of the image being generated by the renderer. Three Film implementations are available:

  • "rgb", corresponding to RGBFilm: the default film if none is specified; stores RGB images using the current color space when the Film directive is encountered.
  • "gbuffer", corresponding to GBufferFilm: in addition to RGB, stores multiple additional channels that encode information about the visible geometry in each pixel. Images must be written in OpenEXR format with this film.
  • "spectral", corresponding toSpectralFilm: stores a discretized spectral distribution at each pixel, in addition to RGB (for convenience when viewing images.) Images must be written in OpenEXR format with this film.

The only Film implementation currently available in pbrt is ImageFilm which is specified as "image" in input files. For example:

Film "image" "string filename" ["out.exr"]
             "float cropwindow" [ .2 .5 .3 .8 ]

The "image" film takes a handful of parameters:

Type Name Default Value Description
integer xresolution 640 The number of pixels in the x direction.
integer yresolution 480 The number of pixels in the y direction.
float[4] cropwindow [ 0 1 0 1 ] The subregion of the image to render. The four values specified should be fractions in the range [0,1], and they represent x_min, x_max, y_min, and y_max, respectively. These values are in normalized device coordinates, with (0,0) in the upper-left corner of the image.
float scale 1 Scale factor to apply to film pixel values before saving the image.
float maxsampleluminance infinite Image sample values with luminance greater than this value are clamped to have this luminance. (This is a hack, but can be useful for eliminating large variance spikes in scenes with difficult light transport.)
float diagonal 35 Diagonal length of the film, in mm. (This value is only used when the RealisticCamera is used.)
string filename "pbrt.exr" The output filename.

The ImageFilm uses the suffix of the given output filename to determine the image file format to use. pbrt supports PFM and EXR for storing images with pixel values stored directly as floating-point values; TGA and PNG can also be used, though these only provide 8 bits per color channel of precision.

Filters

The implementation of ImageFilm uses an instance of the abstract Filter class to filter sample values to compute final pixel values. The filter is specified with the PixelFilter directive. pbrt provides a number of filter implementations, listed below. The default is "box".

Name Implementation Class
"box" BoxFilter
"gaussian" GaussianFilter
"mitchell" MitchellFilter
"sinc" LanczosSincFilter
"triangle" TriangleFilter

All filter implementations take two parameters that set the filter width in each direction. Typically, these two parameters will have the same value.

Type Name Default Value Description
float xwidth 2 (0.5 for box, 4 for sinc) The width of the filter in the x direction.
float ywidth 2 (0.5 for box, 4 for sinc) The width of the filter in the y direction.

The "gaussian" filter takes an additional parameter that adjusts the rate of Gaussian falloff; see page 478 for more information.

Type Name Default Value Description
float alpha 2 alpha controls the falloff rate of the Gaussian filter. Smaller values give a blurrier image.

Two parameters set the shape of the "mitchell" filter; see the equation on the top of page 481.

Type Name Default Value Description
float B 1/3  
float C 1/3 These parameters control the shape of the Mitchell filter. The best results are generally obtained when B+2C=1.

Finally the sinc filter takes a value tau that sets the number of cycles of the sinc function.

Type Name Default Value Description
float tau 3 tau controls how many cycles the sinc function passes through before it is clamped to zero by the windowing function.

Integrators

The integrator implements the light transport algorithm that computes radiance arriving at the film plane from surfaces and participating media in the scene. The default integrator is the PathIntegrator:

Integrator "path" "integer maxdepth" [5]

The PathIntegrator takes a handful of parameters:

Type Name Default Value Description
integer maxdepth 5 Maximum length of a light-carrying path sampled by the integrator.
integer[4] pixelbounds (Entire image) Subset of image to sample during rendering; in order, values given specify the starting and ending x coordinates and then starting and ending y coordinates. (This functionality is primarily useful for narrowing down to a few pixels for debugging.)
float rrthreshold 1 Determines when Russian roulette is applied to paths: when the maximum spectral component of the path contribution falls beneath this value, Russian roulette starts to be used.
string lightsamplestrategy "spatial" Technique used for sampling light sources. Options include "uniform", which samples all light sources uniformly, "power", which samples light sources according to their emitted power, and "spatial", which computes light contributions in regions of the scene and samples from a related distribution.

A number of other surface integrators are available in the system.

Name Implementation Class
"bdpt" BDPTIntegrator
"directlighting" DirectLightingIntegrator
"mlt" MLTIntegrator
"path" PathIntegrator
"sppm" SPPMIntegrator
"volpath" VolPathIntegrator
"whitted" WhittedIntegrator

The DirectLightingIntegrator takes an additional parameter that controls the light source sampling strategy.

Type Name Default Value Description
string strategy "all" The strategy to use for sampling direct lighting. Valid options are "all", which samples all the lights uniformly and averages their contributions, and "one", which chooses a single light uniformly at random.
integer maxdepth 5 Maximum length of a light-carrying path sampled by the integrator.
integer[4] pixelbounds (Entire image) Subset of image to sample during rendering; in order, values given specify the starting and ending x coordinates and then starting and ending y coordinates. (This functionality is primarily useful for narrowing down to a few pixels for debugging.)

These are the parameters that the BDPTIntegrator takes:

Type Name Default Value Description
integer maxdepth 5 Maximum length of a light-carrying path sampled by the integrator.
integer[4] pixelbounds (Entire image) Subset of image to sample during rendering; in order, values given specify the starting and ending x coordinates and then starting and ending y coordinates. (This functionality is primarily useful for narrowing down to a few pixels for debugging.)
string lightsamplestrategy "power" Technique used for sampling light sources. Options include "uniform", which samples all light sources uniformly, "power", which samples light sources according to their emitted power, and "spatial", which computes light contributions in regions of the scene and samples from a related distribution.
bool visualizestrategies false If true, an image is saved for each (s,t) bidirectional path generation strategy used by the integrator. These images can be helpful for understanding which sampling strategies are effective for sampling various types of light transport paths.
bool visualizeweights false If true, an image is saved with the multiple importance sampling weights for each (s,t) bidirectional path generation strategy. These images can be helpful for understanding which sampling strategies are effective for sampling various types of light transport paths.

The MLTIntegrator, which implements the multiplexed Metropolis light transport algorithm described in Section 16.5, takes a number of parameters.

Type Name Default Value Description
integer maxdepth 5 Maximum length of a light-carrying path sampled by the integrator.
integer bootstrapsamples 100000 Number of samples to take during the "bootstrap" phase; some of these samples are used for initial light-carrying paths for the Metropolis algorithm.
integer chains 1000 Number of unique Markov chains chains to follow with the Metropolis algorithm. (Each chain starts with a new path from the bootstrap phase.)
integer mutationsperpixel 100 Number of path mutations to apply per pixel in the image. (Note that each pixel will generally receive more or fewer path contributions, depending on how bright the pixel is. For the most part, this is the most effective parameter to increase to improve image quality.
float largestepprobability 0.3 Probability of discarding the current path and generating a new random path (versus applying a small mutation to the current path). For scenes with very difficult-to-sample light transport paths, reducing this probability may be worthwhile.
float sigma 0.01 Standard deviation of the perturbation applied to random samples in [0,1] used for small path mutations.

Finally, the SPPMIntegrator integrator takes a number of parameters to control the stochastic progressive photon mapping algorithm.

Type Name Default Value Description
integer maxdepth 5 Maximum length of a light-carrying path sampled by the integrator.
integer iterations 64 Total number of iterations of photon shooting from light sources. (After each iteration, photon statistics are updated.)
integer photonsperiteration -1 Number of photons to shoot from light sources in each iteration. With the default value, -1, the number is automatically set to be equal to the number of pixels in the image.
integer imagewritefrequency 2^31 Frequency at which to write out the current image, in photon shooting iterations. (The default value means that the image will effectively only be written once when rendering has finished.)
float radius 1 Initial photon search radius. (This value will be reduced as photons are accumulated at each pixel.)

Accelerators

The type of aggregate to use for efficiently finding ray-shape intersections is defined with the Accelerator directive:

Accelerator "kdtree" "float emptybonus" [0.1]

The default accelerator, "bvh", is generally a good choice; it is rarely worthwhile to specify a different accelerator or to need to change the accelerator's parameters to improve performance.

Two accelerator implementations are available in pbrt:

Name Implementation Class
"bvh" BVHAccel
"kdtree" KdTreeAccel

The "bvh" accelerator, the default, takes just two parameters. This accelerator is efficiently constructed when the scene description is processed, while still providing highly efficient ray-shape intersection tests.

Type Name Default Value Description
integer maxnodeprims 4 Maximum number of primitives to allow in a node in the tree. Once the primitives have been split to groups of this size or smaller, a leaf node is created.
string splitmethod "sah" Method to use to partition the primitives when building the tree. The default, "sah", denotes the surface area heuristic; the default should almost certainly be used. The other options—"middle", which splits each node at its midpoint along the split axis, "equal", which splits the current group of primitives into two equal-sized sets, and "hlbvh", which selects the HLBVH algorithm, which parallelizes well—are slightly more efficient to evaluate at tree construction time, but lead to substantially lower-quality hierarchies.

The "kdtree" accelerator takes a number of parameters that control its construction. This accelerator takes substantially longer to create than "bvh" at scene definition time, but it can be marginally faster at finding ray-shape intersections. It tends to require less memory than "bvh".

See page 291 of the third edition of the book for the details of the cost function used for building kd-trees (and thus the use of some of the the various parameters below.)

Type Name Default Value Description
integer intersectcost 80 The value of the cost function that estimates the expected cost of performing a ray-object intersection, for use in building the kd-tree.
integer traversalcost 1 Estimated cost for traversing a ray through a kd-tree node.
float emptybonus 0.2 "Bonus" factor for kd-tree nodes that represent empty space.
integer maxprims 1 Maximum number of primitives to store in kd-tree node. (Not a hard limit; more may be stored if the kd-tree can't find splitting planes that reduce the number of primitives when refining a node.)
integer maxdepth -1 Maximum depth of the kd-tree. If negative, the kd-tree chooses a maximum depth based on the number of primitives to be stored in it.

Participating media

The MakeNamedMedium and MediumInterface directives are allowed both in the initial options before WorldBegin as well as after WorldBegin. See the documentation of participating media in "Describing the scene" for more information. When media specified in the scene-wide options, the "outside" medium is used for the medium that camera rays start out in.

Describing the scene

After the camera, film, and rendering options have been set, the WorldBegin directive marks the start of the scene definition (the "world block"). In the world block, the lights, materials, and geometric shapes that make up the scene are defined. After WorldBegin, nearly all of the directives described in the Scene-wide rendering options section are illegal; an error message will be printed if one is encountered. Similarly, nearly all of the directives documented in this section are illegal outside of the world block. (The two exceptions are the MakeNamedMedium and MediumInterface directives, which are legal in both places.) The end of the world block is denoted by the WorldEnd directive; when it is encountered, the chosen Integrator takes over and does the requested rendering computation.

Attributes

A number of directives modify the current graphics state—examples include the transformation directives (Transformations), and the directive that sets the current material. The current graphics state (including the current transformation matrix) can be saved and restored using the AttributeBegin and AttributeEnd directives:

Material "matte"
AttributeBegin
   Material "plastic"
   Shape "sphere"
AttributeEnd   # back to the "matte" material
Shape "cone"

The transformation matrix can be saved and restored independently of the graphics state using TransformBegin and TransformEnd.

Scale 2 2 2
TransformBegin
    Translate 1 0 1
    Shape "sphere"
TransformEnd   # Translate no longer applies here

In addition to the current transformation matrix and material, the reverse-orientation setting, specified by the ReverseOrientation directive, is part of the graphics state. This directive, when active, flips the surface normal of the shapes that follow it; it can be useful when specifying area light sources, which only emit light from the side their surface normal points from, and when specifying transparent materials, where the surface normal is used to determine whether rays are entering or exiting the refractive medium.

Shapes

Shapes are specified with the Shape directive; it takes the name of a shape implementation and a parameter list used to define the shape's properties:

Shape "name" parameter-list

For example,

Shape "sphere" "float radius" [0.25]

When a Shape directive is encountered, the current transformation matrix is used to set the object to world transformation for the shape.

A number of shapes are provided by pbrt; this list shows the mapping from shape names to implementation class in the system.

Name Implementation Class
"cone" Cone
"curve" Curve
"cylinder" Cylinder
"disk" Disk
"hyperboloid" Hyperboloid
"paraboloid" Paraboloid
"sphere" Sphere
"trianglemesh" Triangle

A few additional shapes are available for convenience; these immediately convert themselves to instances of the Triangle shape when the scene description is loaded.

Name
"heightfield"
"loopsubdiv"
"nurbs"
"plymesh"

The extent of the "cone" shape is defined by three parameters; note that the cone is oriented along the z axis in object space; the current transformation matrix can be used to orient it differently in the scene's world space.

Type Name Default Value Description
float radius 1 The cone's radius.
float height 1 The height of the cone along the z axis.
float phimax 360 The maximum extent of the cone in phi (in spherical coordinates).

The "curve" shape, described in Section 3.7 of the book, is useful for modeling thin objects like hair, fur, and grass. It has a few variants, including a ribbon that's always oriented toward the incident ray, a flat ribbon with orientation given by a pair of surface normals, and an (apparent) thin cylinder, where shading normals give the illusion of a curved surface.

After the book's publication, support for degree 2 curves was added, as was support for curves spcified in the b-spline basis.

Type Name Default Value Description
point[4] P (none) Control points for the cubic Bezier spline that goes along the center of the curve shape.
string basis "bezier" Curve spline basis. "bspline" is the only other option currently supported.
int degree 3 Degree of the curve's spline. The only other valid option is 2.
string type "flat" Which curve variant is used. The other options are "ribbon" and "cylinder". (Figure 3.18 on page 170 shows the differences between them.)
normal[2] N (none) For "ribbon" curves, these normals are respectively used at the start and end of the curve. Intermediate normals are interpolated using spherical linear interpolation.
float width 1 Width of the curve.
float width0/width1 1 Width of the curve at the start and end points. If specified, these override the "width" parameter.
integer splitdepth 3 Number of times the curve is split in half into sub-curves at startup time. Splitting curves increases memory use but can improve ray intersection performance, as the sub-curves generally have tighter bounding boxes than the entire curve extent.

Similarly, "cylinder" is oriented along the z axis as well. It takes four parameters.

Type Name Default Value Description
float radius 1 The cylinder's radius.
float zmin -1 The height of the cylinder's bottom along the z axis.
float zmax 1 The height of the cylinder's top along the z axis.
float phimax 360 The maximum extent of the cylinder in phi (in spherical coordinates).

The "disk" is perpendicular to the z axis, with its center at x=0 and y=0.

Type Name Default Value Description
float height 0 The location of the disk along the z axis.
float radius 1 The outer radius of the disk.
float innerradius 0 The inner radius of the disk (if nonzero, the disk is an annulus).
float phimax 360 The maximum extent of the disk in phi (in spherical coordinates).

The "heightfield" shape isn't described in the pbrt book text; it's essentially a compact way to describe a regular triangulated mesh. The user provides resolutions in the u and v directions and then a series of height values. The height values give the z values for a series of vertices over [0,1]^2 in (x,y).

Type Name Default Value Description
int nu, nv none Number of sample values in each direction. The total number of triangles in the mesh is 2 * (nu-1) * (nv-1).
float[nu*nv] Pz none Array of height values to specify the heightfield.

"hyperboloid" takes two points to define the line of revolution that sweeps out its surface.

Type Name Default Value Description
point p1 0 0 0 The first end point of the hyperboloid's line of revolution.
point p2 1 1 1 The second end point of the hyperboloid's line of revolution.
float phimax 360 The maximum extent of the hyperboloid in phi (in spherical coordinates).

"loopsubdiv" corresponds to a subdivision surface evaluated with Loop's subdivision rules.

Type Name Default Value Description
integer levels 3 The number of levels of refinement to compute in the subdivision algorithm.
integer[n] indices required—no default Indices for the base mesh. Indexing is the same as for the triangle mesh primitive. (See "trianglemesh" below).
point[n] P required—no default Vertex positions for the base mesh. This is the same as for the triangle mesh primitive. (See "trianglemesh" below).

"nurbs" can be used to define a NURBS surface. The implementation in pbrt does a fixed-rate tessellation, with tessellation rate provided directly by the user.

Type Name Default Value Description
integer nu, nv none—must be specified Number of control points for NURBS patch in the u and v parametric directions.
integer uorder, vorder see description Order of NURBS surface in u and v directions. (Order is equal to one plus the surface's degree.)
float[nu+uorder] uknots none—must be specified Knot vector for NURBS in the u direction.
float[nv+vorder] vknots none—must be specified Knot vector for NURBS in the v direction.
float u0, v0 none—must be specified Starting u and v parametric coordinates at which to evaluate NURBS.
float u1, v1 none—must be specified Ending u and v parametric coordinates at which to evaluate NURBS.
point[nu*nv] P none Either the P or Pw parameter must be specified to give the surface's control points. P gives regular control points.
float[4*nu*nv] Pw none Specifies rational control points, with an additional per-vertex weight value.

Here are the parameters for "paraboloid".

Type Name Default Value Description
float radius 1 The paraboloid's radius.
float zmin 0 The height of the lower clipping plane along the z axis.
float zmax 1 The height of the upper clipping plane along the z axis.
float phimax 360 The maximum extent of the paraboloid along phi (in spherical coordinates).

And these are the "sphere" parameters.

Type Name Default Value Description
float radius 1 The sphere's radius.
float zmin -radius The height of the lower clipping plane along the z axis.
float zmax radius The height of the upper clipping plane along the z axis.
float phimax 360 The maximum extent of the sphere in phi (in spherical coordinates).

An arbitrary triangle mesh is defined by the "trianglemesh" shape. The mesh's topology is defined by the indices parameter, which is an array of integer indices into the vertex arrays. Each successive triplet of indices defines the offsets to the three vertices of one triangle; thus, the length of the indices array must be a multiple of three.

Here is an example of a small triangle mesh:

Shape "trianglemesh"  "integer indices" [0 2 1 0 3 2 ]
    "point P" [550 0 0    0 0 0    0 0 560    550 0 560 ]

Here, we have an array of four vertices in the P parameter. The indices array defines two triangles that use these vertices—the first one has vertex positions (550,0,0), (0,0,560), and (0,0,0). Note that both triangles use vertices 0 and 2. Because the triangle mesh is specified in a way that makes this vertex reuse explicit, the in-memory representation of the triangle mesh can be more compact than if each triangle had to explicitly and privately store all of its per-vertex data.

Type Name Default Value Description
integer[n] indices required—no default The array of integer offsets into the per-vertex data arrays (P, and any of N, S, or uv that are present.)
point[n] P required—no default The vertex positions of the triangle mesh.
normal[n] N none—optional Per-vertex normals. If present, shading normals will be computed from these values.
vector[n] S none—optional Per-vertex tangents.
float[2*n] uv none—optional Per-vertex texture coordinates.
float texture alpha none Optional "alpha" texture. (See the Textures section for more information about textures in pbrt.) When provided, at any point on the triangle where the alpha texture evaluates to have the value zero, the triangle is cut away and any ray intersection is ignored.
float texture shadowalpha none Optional "shadowalpha" texture. (See the Textures section for more information about textures in pbrt.) When provided, intersections at any points on the triangle where the alpha texture evaluates to zero are ignored.

pbrt can also directly read triangle meshes specified in the PLY mesh file format, via the "plymesh" shape. The following parameters are supported:

Type Name Default Value Description
string filename required—no default File from which the PLY-format mesh is loaded.
float texture alpha none Optional "alpha" texture. (See the Textures section for more information about textures in pbrt.) When provided, at any point on the triangle where the alpha texture evaluates to have the value zero, the triangle is cut away and any ray intersection is ignored.
float texture shadowalpha none Optional "shadowalpha" texture. (See the Textures section for more information about textures in pbrt.) When provided, intersections at any points on the triangle where the alpha texture evaluates to zero are ignored.

Object Instancing

If a complex object is used repeatedly in a scene, object instancing may be desirable; this lets the system store a single instance of the object in memory and just record multiple transformations to place it in the scene. Object instances are created via named objects.

To create a named object, its definition should be placed within an ObjectBegin/ObjectEnd pair:

ObjectBegin "name"
  Shape ...
  Shape ...
ObjectEnd

When a named object is defined, the current transformation matrix defines the transformation from object space to the instance's coordinate space.

After a named object has been defined, it can be instantiated with the ObjectInstance directive. The current transformation matrix then defines the instance space to world space transformation; thus, the final transformation for a shape in an object instance definition is the composition of the CTM when the instance was defined and the CTM when the instance was instantiated.

Thus, two instances of an object named "foo" are instantiated in the following:

ObjectInstance "foo"
Translate 1 0 0
ObjectInstance "foo"

Lights

Light sources cast illumination in the scene. pbrt provides two types of lights: lights that exist in the scene without any geometry associated with them, and lights that describe emission from one or more shapes in the scene (area lights).

The first type of light is defined with the LightSource directive. There are 6 light sources of this type that are currently available in pbrt.

Name Implementation Class
"distant" DistantLight
"goniometric" GonioPhotometricLight
"infinite" InfiniteAreaLight
"point" PointLight
"projection" ProjectionLight
"spot" SpotLight

For example, the following defines a point light source with RGB intensity of (0.5, 0.5, 0.5):

LightSource "point" "rgb I" [ .5 .5 .5 ]

When a light source definition is encountered, the current transformation matrix is used to define the light-to-world transformation. Many of the light sources also take parameters to place it in the scene; using either a transformation matrix or an explicit position or direction to place a light can be useful.

All lights support a spectrum "scale" parameter that scales the amount of light that the light emits.

Type Name Default Value Description
spectrum scale rgb (1 1 1) Scale factor that modulates the amount of light that the light source emits into the scene.

Distant

The "distant" light source represents a directional light source "at infinity"; in other words, it illuminates the scene with light arriving from a single direction. It takes these parameters:

Type Name Default Value Description
spectrum L rgb (1 1 1) The radiance emitted from the light source.
point from (0,0,0) "from" and "to" define the direction vector along which illumination from the light arrives at the scene. The defaults give a light that shines along the z axis.
point to (0,0,1)  

Goniometric

The "goniometric" light represents a point light source with directionally-varying emission, where the emission distribution is represented by a texture map. This representation can be useful for modeling many real-world light sources, where measurements of this distribution may be available.

Given a normalized outgoing direction w from the goniometric light source to a point in the scene, the image coordinates in the goniometric diagram file are found using a (theta, phi) parameterization in spherical coordinates. Here, the theta angle is measured with respect to the y axis, and x and z define phi. (Elsewhere in pbrt, the z axis is generally used to measure theta.) The light-to-world transformation matrix can be used to position and orient the light.

Type Name Default Value Description
spectrum I rgb (1 1 1) A radiant intensity scale-factor; the radiant intensity in a particular direction is computed as the product of this value and the appropriate value from the goniometric diagram table.
string mapname required—no default The filename of the image file that stores a goniometric diagram to use for the lighting distribution.

Infinite

The "infinite" light represents an infinitely far away light source that potentially casts illumination from all directions. It is useful for modeling incident light in complex real environments ("HDR lighting"). It takes an environment map with a "latitude-longitude" parameterization, where given a direction vector w, the spherical (theta, phi) coordinates are found, and then the u coordinate of the environment map is indexed by the phi value and v is indexed by theta. (If needed, the environment map can be reoriented with the light to world transformation.)

Type Name Default Value Description
spectrum L rgb (1 1 1) A radiance scale factor for the light; final emitted radiance values for a particular direction are computed as the product of this value and the radiance value found from the environment map.
integer samples 1 Suggested number of shadow samples to take when computing illumination from the light. Depending on the number of pixel samples being taken, this value may need to be increased to reduce noise in the illumination computation for the light. (Note that this value is used only when the DirectLightingIntegrator is used.)
string mapname none The environment map to use for the infinite area light. If this is not provided, the light will be a constant color.

Point

"point" defines a simple point light that casts the same amount of illumination in all directions. It takes two parameters:

Type Name Default Value Description
spectrum I rgb (1 1 1) The light's emitted radiant intensity.
point from 0 0 0 The location of the light.

Projection

The "projection" light acts like a slide projector; the given image is used to define a 2D emission distribution that is projected with a center of projection at the light's position. Directions outside the frustum of light projection receive no emitted illumination. It is positioned using the light-to-world transformation matrix.

Type Name Default Value Description
spectrum I rgb (1 1 1) Radiant intensity scale factor; the intensity in a given direction is the product of this value and the value from the image map for the corresponding direction.
float fov 45 The spread angle of the projected light, along the shorter image axis.
string mapname required—no default The image to project into the scene.

Spotlight

A spotlight is defined by the "spot" light source. The spotlight is defined by a lighting direction and then two angles that specify a cone of directions in which light is emitted.

Type Name Default Value Description
spectrum I rgb (1 1 1) Maximum radiant intensity of the light; this is the emitted radiant intensity in the center of the illumination cone. It falls off to zero outside of the cone.
point from, to see description Two points defining the lighting vector. The defaults are (0,0,0) and (0,0,1), respectively. This gives a light that is pointing down the z axis.
float coneangle 30 The angle that the spotlight's cone makes with its primary axis. For directions up to this angle from the main axis, the full radiant intensity given by "I" is emitted. After this angle and up to "coneangle" + "conedeltaangle", illumination falls off until it is zero.
float conedeltaangle 5 The angle at which the spotlight intensity begins to fall off at the edges.

Area Lights

Area lights have geometry associated with them; the shape and size of the emitting shapes have a substantial effect on the resulting emitted radiance distribution. After an AreaLightSource directive, all subsequent shapes emit light from their surfaces according to the distribution defined by the given area light implementation. Note that area lights can currently only be used with triangle, sphere, cylinder, and disk shapes; a runtime error is issued if an area light is bound to any other type of shape.

The current area light is saved and restored inside attribute blocks; typically area light definitions are inside an AttributeBegin/AttributeEnd pair in order to control the shapes that they are applied to.

AttributeBegin
  AreaLightSource "diffuse" "rgb L" [ .5 .5 .5 ]
  Translate 0 10 0
  Shape "sphere" "float radius" [.25]
AttributeEnd
# area light is out of scope, subsequent shapes aren't emitters

pbrt currently only includes a single area light implementation, "diffuse".

Name Implementation Class
"diffuse" DiffuseAreaLight

The "diffuse" area light defines an emitter that emits radiance uniformly over all directions in the hemisphere around the surface normal at each point on the surface. Thus, the orientation of the surface normal is meaningful; by default, an emitting sphere emits in the directions outside the sphere and there's no illumination inside of it. If this is not the desired behavior, the ReverseOrientation directive can be used to flip the orientation of the surface normal of subsequent shapes, or the "twosided" option, described in the list of options below, can be enabled.

AttributeBegin
  AreaLightSource "diffuse"
  ReverseOrientation  # illuminate inside the sphere
  Shape "sphere"
AttributeEnd

The "diffuse" area light takes these parameters.

Type Name Default Value Description
spectrum L rgb (1 1 1) The amount of emitted radiance at each point and emitted direction..
bool twosided false Determines whether the light source emits light from just the side of the surface where the surface normal points or both sides.
integer samples 1 Suggested number of shadow samples to take when computing illumination from the light. (As with the InfintieAreaLight, this value is used only when the DirectLightingIntegrator is used.)

Materials

Materials specify the light scattering properties of surfaces in the scene. The Material directive specifies the current material, which then applies for all subsequent shape definitions (until the end of the current attribute scope or until a new material is defined:

Material "matte" "rgb Kd" [ .7 .2 .2 ]

Parameters to materials are distinctive in that textures can be used to specify spatially-varying values for the parameters. For example, the above material definition defines diffuse surface with the same reddish color at all points. Alternatively, we might want to use an image map to define the color as a function of (u,v) on the surface. This is done by defining a texture with a user-defined name (below, "lines-tex"), and then binding that to the desired parameter of the material.

For example, the following sets the "Kd" parameter of the "matte" material to be computed via lookups to the "lines.exr" image map.

Texture "lines-tex" "spectrum" "imagemap" "string filename" "textures/lines.exr"
Material "matte" "texture Kd" "lines-tex"

Note that for each parameter (for example, "Kd" in the above), a value for the parameter can either be bound with a constant value, in which case the given type of the parameter should be "float", "rgb", "spectrum", etc., as appropriate, or a texture value, in which case the given type of the parameter should be "texture" and the parameter value bound is the name of a texture. (The next section of this document, Textures, describes the textures available in pbrt as well as their parameters.)

Parameters to materials can be overridden by the shapes that they are applied to. For example, the sphere in the following would be green, not red.

Material "matte" "rgb Kd" [ 1 0 0 ]
Shape "sphere" "float radius" [ .5 ] "rgb Kd" [ 0 1 0 ]  

Finally, it is sometimes useful to name a material. A named material is a material and a set of parameter bindings (to constant values or to textures). It is defined with the MakeNamedMaterial directive. A named material can be set to be the current material with the NamedMaterial directive.

MakeNamedMaterial "myplastic" "string type" "plastic" "float roughness" [0.1]
Material "matte"  # current material is "matte"
NamedMaterial "myplastic"  # current material is "plastic" as above

This table lists the materials available in pbrt and the corresponding class in the source code distribution that implements each of them.

Name Implementation Class
disney DisneyMaterial
fourier FourierMaterial
glass GlassMaterial
hair HairMaterial
kdsubsurface KdSubsurfaceMaterial
matte MatteMaterial
metal MetalMaterial
mirror MirrorMaterial
mix MixMaterial
none A special material that signifies that the surface it is associated with should be ignored for ray intersections. (This is useful for specifying regions of space associated with participating media.)
plastic PlasticMaterial
substrate SubstrateMaterial
subsurface SubsurfaceMaterial
translucent TranslucentMaterial
uber UberMaterial

All of the above materials take a texture that can be used to specify a bump map.

Type Name Default Value Description
float texture bumpmap None The floating-point texture to be used as a bump map.

Disney

The "disney" material was after the book's publication. It implements the "Disney BSDF with subsurface scattering", as described in Extending the Disney BRDF to a BSDF with Integrated Subsurface Scattering. (It builds on the model described in Physically Based Shading at Disney. See those documents for more details about the parameters.

Type Name Default Value Description
spectrum texture color 0.5 Base color of the material.
float texture anisotropic 0 Controls degree of anisotropy in the specular highlight. Default, 0, is none. Range: [0,1].
float texture clearcoat 0 Contribution of the clearcoat, which gives isotropic specular highlight that takes on the light's color. Range: [0,1].
float texture clearcoatgloss 1 Glossiness of the clearcoat. Larger values give tighter highglights. Range: [0,1].
float texture eta 1.5 Object's index of refraction.
float texture metallic 0 Controls how "metal" the object appears. Higher values reduce diffuse scattering and shift the highlight color towards the material's color. Range: [0,1].
float texture roughness 0.5 Material's roughness. Affects specular reflection and transmission. Range: [0,1].
spectrum texture scatterdistance 0 Distance that light travels in the object before scattering. If greater than zero, subsurface scattering is used in place of diffuse reflection.
float texture sheen 0 Contribution of the "sheen" term, which adds retro-reflection at object edges. Mostly useful for cloth. Range: [0,1].
float texture sheentint 0.5 Controls how much the sheen term's color is tinted by the base color. Range: [0,1].
float texture spectrans 0 Controls contribution of glossy specular transmission. Range: [0,1].
float texture speculartint 0 Controls how much the specular highlight's color is tinted by the base color. Range: [0,1]..

The Disney BSDF also has a mode for thin surfaces that aren't closed geometric models (e.g. a sheet of paper). The "thin" parameter to the material can be used to enable it.

Type Name Default Value Description
boolean thin false Controls whether the thin is enabled surface model.
spectrum texture difftrans 1 Controls how much of the diffuse scattering is reflected versus transmitted. Zero causes only diffuse reflection and no diffuse transmission, 1 gives an even split between both, and 2 gives only diffuse transmission. Range: [0,2].
spectrum texture flatness 0 Base color of the material.

Fourier

The "fourier" material is used for the Fourier Basis BSDFs described in Section 8.6 of Physically Based Rendering, starting on page 552. This representation is useful both for measured BSDF data as well as for BSDFs computed through simulation of scattering in layered surfaces. (A number of such BSDFs are available in the bsdfs directory in the pbrt scenes distribution.)

Type Name Default Value Description
string bsdffile none File that stores the Fourier BSDF description.

Glass

The "glass" material has parameters that specify the reflectivity and transmissivity. These values are both modulated by the Fresnel equations for dielectric materials, which also ensure energy conservation (as long as neither "Kr" nor "Kt" is ever greater than one.)

Type Name Default Value Description
spectrum texture Kr 1 The reflectivity of the surface.
spectrum texture Kt 1 The transmissivity of the surface.
float texture eta 1.5 The index of refraction of the inside of the object. (pbrt implicitly assumes that the exterior of objects is a vacuum, with IOR of 1.)
float texture uroughness 0 Microfacet roughness in the u direction. If zero, perfect specular reflection is modeled.
float texture vroughness 0 Microfacet roughness in the v direction. If zero, perfect specular reflection is modeled.
bool remaproughness true If true, roughness values are expected to be in the range [0,1], and are remapped to microfacet distribution function parameter values that range from near-perfect-specular at 0 to very rough at 1. Otherwise the roughness parameters are used directly for the alpha parameters of the microfacet distribution function.

Hair

The "hair" material models reflection and transmission from cylindrical fibers like hair and fur. It's generally only useful with the "curve" shape. Its implementation is described in the supplementary Implementation of a Hair Scattering Model document.

The color of the hair material can be specified in one of a number of different ways.

Type Name Description
spectrum texture sigma_a Absorption coefficient of the medium inside the hair. This absorption coefficient is normalized such that the value provided should be with respect to the diameter of the hair.
spectrum texture color If specified, a value of the absorption coefficient is computed using an approximation that leads to the hair having roughly this color, after multiple scattering in the hair during rendering.
float texture eumelanin Concentration of the eumelanin pigment in the hair. Blonde hair has concentrations around 0.3, brown around 1.3, and black around 8.
float texture pheomelanin Concentration of the pheomelanin pigment in the hair. Pheomelanin makes red hair red.

If "sigma_a" is specified, then all other parameters related to hair color are ignored, if present. Otherwise, if "color" is specified, the eumelanin and pheomelanin parameters are ignored, if present. If no hair color parameters are specified, a eumelanin concentration of 1.3 is used, giving brown hair.

A number of additional parameters are available to control the hair's appearance.

Type Name Default Value Description
float texture eta 1.55 Index of refraction of the hair medium.
float texture beta_m 0.3 Longitudinal roughness of the hair. Should be between 0 and 1. This roughness controls the size and shape of the hair highlight.
float texture beta_n 0.3 Azimuthal roughness of the hair. Should be between 0 and 1.
float texture alpha 2 Angle of scales on the hair surface, in degrees.

KdSubsurface

The "kdsubsurface" material provides a convenient way to specify the scattering materials of a material that exhibits subsurface scattering. (The parameters to the "subsurface" material, below, are often difficult to set to achieve a desired visual result.) Here, the user can specify a diffuse reflection color, "Kd", and the mean free path—the average distance that light travels in the medium before scattering. (The smaller the mean free path, the thicker the medium is.) These two values are then used to derive scattering coefficients for the medium.)

Type Name Default Value Description
spectrum texture Kd 0.5 Diffuse scattering coefficient used to derive scattering properties.
float texture mfp 1 The mean free path--the average distance light travels in the medium before scattering.
float texture eta 1.3 The index of refraction inside the object.
spectrum texture Kr 1 Reflection term; this coefficient is modulated with the dielectric Fresnel equation to give the amount of reflection.
spectrum texture Kt 1 Transmission term; this coefficient is modulated with the dielectric Fresnel equation to give the amount of transmission.
float texture uroughness 0 Microfacet roughness in the u direction. If zero, perfect specular reflection is modeled.
float texture vroughness 0 Microfacet roughness in the v direction. If zero, perfect specular reflection is modeled.
bool remaproughness true If true, roughness values are expected to be in the range [0,1], and are remapped to microfacet distribution function parameter values that range from near-perfect-specular at 0 to very rough at 1. Otherwise the roughness parameters are used directly for the alpha parameters of the microfacet distribution function.

Matte

The "matte" material defines an object with simple Lambertian scattering. It takes two parameters.

Type Name Default Value Description
spectrum texture Kd 0.5 The diffuse reflectivity of the surface.
float texture sigma 0 The sigma parameter for the Oren-Nayar model, in degrees. If this is zero, the surface exhibits pure Lambertian reflection.

Metal

The "metal" material describes scattering from metals, where the index of refraction (eta) and the absorption coefficient (k) describe metals' reflectance spectra. These and a roughness parameter, which adjusts the microfacet distributions roughness, describe the overall material. See the scenes/spds/metals directory in the pbrt distribution for spectra of the IOR and absorption coefficients of a variety of metals.

Type Name Default Value Description
spectrum texture eta (copper) Index of refraction to use in computing the material's reflectance.
spectrum texture k (copper) Absorption coefficient to use in computing the material's reflectance.
float texture roughness 0.01 Roughness of the material's microfacet distribution. Smaller values become increasingly close to perfect specular reflection. This value should be between zero and one.
float texture uroughness n/a Microfacet roughness in the u direction. If unspecified, the "roughness" parameter is used.
float texture vroughness n/a Microfacet roughness in the v direction. If unspecified, the "roughness" parameter is used.
bool remaproughness true If true, roughness values are expected to be in the range [0,1], and are remapped to microfacet distribution function parameter values that range from near-perfect-specular at 0 to very rough at 1. Otherwise the roughness parameters are used directly for the alpha parameters of the microfacet distribution function.

Mirror

The "mirror" material is a simple specular reflector. The amount of reflection isn't modified by the Fresnel equations.

Type Name Default Value Description
spectrum texture Kr 0.9 The reflectivity of the mirror. This value can be used to make colored or dim reflections.

Mixture

The "mix" material interpolates between two previously-named materials using a texture. This allows spatially-varying variation between two materials.

Type Name Default Value Description
spectrum texture amount 0.5 Weighting factor for the blend between materials. A value of one corresponds to just "namedmaterial1", a value of zero corresponds to just "namedmaterial2", and values in between interpolate linearly.
string namedmaterial1 (none) Name of first material to be interpolated between.
string namedmaterial2 (none) Name of second material to be interpolated between.

Plastic

"plastic" defines a simple plastic material, described by diffuse and specular reflection coefficients as well as a roughness value that describes how much variation there is in the microfacet distribution that models glossy specular reflection.

Type Name Default Value Description
spectrum texture Kd 0.25 The diffuse reflectivity of the surface.
spectrum texture Ks 0.25 The specular reflectivity of the surface.
float texture roughness 0.1 The roughness of the surface, from 0 to 1. Larger values result in larger, more blurry highlights.
bool remaproughness true If true, roughness values are expected to be in the range [0,1], and are remapped to microfacet distribution function parameter values that range from near-perfect-specular at 0 to very rough at 1. Otherwise the roughness parameters are used directly for the alpha parameters of the microfacet distribution function.

Substrate

The "substrate" material mixes between diffuse and glossy reflection based on the viewing angle—this models many realistic materials, which become increasingly specular as the viewing angle approaches grazing. It also supports anisotropic microfacet models, with two roughness parameters.

Type Name Default Value Description
spectrum texture Kd 0.5 The coefficient of diffuse reflection.
spectrum texture Ks 0.5 The coefficient of specular reflection.
float texture uroughness 0.1 The roughness of the surface in the u direction.
float texture vroughness 0.1 The roughness of the surface in the v direction.
bool remaproughness true If true, roughness values are expected to be in the range [0,1], and are remapped to microfacet distribution function parameter values that range from near-perfect-specular at 0 to very rough at 1. Otherwise the roughness parameters are used directly for the alpha parameters of the microfacet distribution function.

Subsurface

The "subsurface" material is another material that describes subsurface scattering. It allows directly setting the absorption coefficient and reduced scattering coefficient. (These values are generally difficult to set manually to achieve a desired look; the "kdsubsurface" material is usually better for that. However, if measured data is available, this material is the appropriate one.) This material also supports setting the scattering properties using values that have been measured by various researchers.

Type Name Default Value Description
string name none Name of measured subsurface scattering coefficients. See the file src/core/media.cpp in the pbrt distribution for all of the measurements that are available.
spectrum texture sigma_a (.0011, .0024, .014) Absorption coefficient of the volume, measured in mm^-1.
spectrum texture sigma_prime_s (2.55, 3.12, 3.77) Reduced scattering coefficient of the volume, measured in mm^-1.
float scale 1 Scale factor that is applied to sigma_a and sigma_prime_s. This is particularly useful when the scene is not measured in mm and the coefficients need to be scaled accordingly. For example, if the scene is modeled in meters, then a scale factor of 0.001 would be appropriate.
float texture eta 1.33 Index of refraction of the scattering volume.
spectrum texture Kr 1 Specular reflection term; this coefficient is modulated with the dielectric Fresnel equation to give the amount of specular reflection.
spectrum texture Kt 1 Specular reflection term; this coefficient is modulated with the dielectric Fresnel equation to give the amount of specular reflection.
float texture uroughness 0 Microfacet roughness in the u direction. If zero, perfect specular reflection is modeled.
float texture vroughness 0 Microfacet roughness in the v direction. If zero, perfect specular reflection is modeled.
bool remaproughness true If true, roughness values are expected to be in the range [0,1], and are remapped to microfacet distribution function parameter values that range from near-perfect-specular at 0 to very rough at 1. Otherwise the roughness parameters are used directly for the alpha parameters of the microfacet distribution function.

Translucent

The "translucent" material models transmission through thin objects (like leaves).

Type Name Default Value Description
spectrum texture Kd 0.25 The coefficient of diffuse reflection and transmission.
spectrum texture Ks 0.25 The coefficient of specular reflection and transmission.
spectrum texture reflect 0.5 Fraction of light reflected.
spectrum texture transmit 0.5 Fraction of light transmitted.
float texture roughness 0.1 The roughness of the surface. (This value should be between 0 and 1).
bool remaproughness true If true, roughness values are expected to be in the range [0,1], and are remapped to microfacet distribution function parameter values that range from near-perfect-specular at 0 to very rough at 1. Otherwise the roughness parameters are used directly for the alpha parameters of the microfacet distribution function.

Uber

Finally, the "uber" material is a "kitchen sink" material that supports diffuse, glossy specular, and specular reflection.

Type Name Default Value Description
spectrum texture Kd 0.25 The coefficient of diffuse reflection.
spectrum texture Ks 0.25 The coefficient of glossy reflection.
spectrum texture Kr 0 The coefficient of specular reflection.
spectrum texture Kt 0 The coefficient of specular transmission.
float texture roughness 0.1 The roughness of the surface.
float texture uroughness 0 Microfacet roughness in the u direction. If zero, perfect specular reflection is modeled.
float texture vroughness 0 Microfacet roughness in the v direction. If zero, perfect specular reflection is modeled.
float texture eta 1.5 Index of refraction of the surface. This value is used in both the microfacet model for specular reflection as well as for computing a Fresnel reflection term for perfect specular reflection.
spectrum texture opacity 1 The opacity of the surface. Note that when less than one, the uber material transmits light without refracting it.
bool remaproughness true If true, roughness values are expected to be in the range [0,1], and are remapped to microfacet distribution function parameter values that range from near-perfect-specular at 0 to very rough at 1. Otherwise the roughness parameters are used directly for the alpha parameters of the microfacet distribution function.

Textures

The Texture statement creates a named texture of a particular type. Currently, the only types that are supported are spectrum (color can be used a synonym) and float.

Texture "name" "type" "class" [ parameter-list ]

For example,

Texture "mydiffuse" "spectrum" "imagemap" "string filename" "image.tga"
Material "matte" "texture Kd" "mydiffuse"

pbrt provides the following texture implementations:

Name Implementation Class
"bilerp" BilerpTexture
"checkerboard" Checkerboard2DTexture
"checkerboard" Checkerboard3DTexture
"constant" ConstantTexture
"dots" DotsTexture
"fbm" FBmTexture
"imagemap" ImageTexture
"marble" MarbleTexture
"mix" MixTexture
"scale" ScaleTexture
"uv" UVTexture
"windy" WindyTexture
"wrinkled" WrinkledTexture

In the below, note that a number of textures (e.g. "mix") themselves take textures as parameters; thus, one can build up small "trees" of computation to compose a series of texture functions.

Textures can be separated into three categories: any-D, 2D, and 3D. Any-D textures are ConstantTexture, ScaleTexture, and MixTexture. These kinds of textures do not have a specific dimensionality and have no common arguments.

2D textures use the (u,v) parametric coordinates on a surface for evaluation. They are BilerpTexture, ImageTexture, UVTexture, CheckerboardTexture, and DotsTexture. 2D textures have the following common parameters:

Type Name Default Value Description
string mapping "uv" A string specifying the kind of texture coordinate mapping to use. Legal values are: "uv", "spherical", "cylindrical", or "planar".
float uscale, vscale 1 Scaling factors to be applied to the u and v texture coordinates, respectively. These parameters are only meaningful if the texture coordinate mapping type has been set to "uv".
float udelta, vdelta 0 An offset to be applied to the u and v texture coordinates, respectively. These parameters are only meaningful if the texture coordinate mapping type has been set to "uv" or "planar".
vector v1, v2 see description v1 and v2 are two vectors that define a planar mapping. The defaults are (1,0,0) and (0,1,0), respectively. These parameters are only meaningful if the texture coordinate mapping type has been set to "planar".

3D textures use a texture space point location to evaluate themselves. The current transformation matrix at the time they are created gives the transformation from object space. They are CheckerboardTexture, FBmTexture, WrinkledTexture, MarbleTexture, and WindyTexture. Note that CheckerboardTexture is the only texture that can be either a 2D or 3D texture (see its plug-in specific parameter settings in the following). 3D textures have no common parameters.

Most of the provided textures can generate either Spectrum or float values, which is why many of the following descriptions have the spectrum/float type.

Constant

The "constant" texture is just a convenience that always returns a given constant value.

Type Name Default Value Description
spectrum/float texture value 1 The constant value of this texture.

Scale

"scale" takes two textures as parameters, evaluates each of them, and returns their product. It is often convenient to scale a texture used as a bump map by a constant float value to modulate the perceived height of the bumps, for example.

Type Name Default Value Description
spectrum/float texture tex1, tex2 1 These two textures will be multiplied together by the ScaleTexture.

Mix

"mix" takes two textures and linearly interpolates between their values according to the "amount" parameter (which may itself be a texture).

Type Name Default Value Description
spectrum/float texture tex1 0 One of the two textures to be mixed.
spectrum/float texture tex2 1 The other texture to be mixed. These two textures must be of the same type.
float texture amount 0.5 The amount to use when linearly interpolating between the two mix textures.

Bilinear Interpolation

"bilerp" bilinearly interpolates between the four textures using the (u,v) parametric coordinate. The v00 parameter represents the texture to use at (0,0), and so forth.

Type Name Default Value Description
spectrum/float texture v00, v01, v10, v11 see description The four values to be bilinearly interpolated between. They default to 0, 1, 0, and 1, respectively.

Image Map

Image maps can be provided with the "imagemap" texture.

Type Name Default Value Description
string filename required—no default The filename of the image to load. Currently pbrt supports TGA, PFM, and EXR format images.
string wrap "repeat" What to do with texture coordinates that fall outside the legal [0,1] range. Legal values are "repeat", which simply tiles the texture; "black", which returns black when outside the legal range; and "clamp", which always returns the nearest border texel.
float maxanisotropy 8 The maximum elliptical eccentricity for the EWA algorithm.
bool trilinear false If true, perform trilinear interpolation when looking up pixel values. Otherwise, pbrt uses the EWA algorithm for texture filtering. EWA gives much better results, but is slower.
float scale 1 Scale factor to apply to value looked up in texture.
bool gamma (depends) Indicates whether texel values should be converted from sRGB gamma space to linear space. This parameter is "true" by default for textures stored in 8-bit formats like TGA and PNG, and "false" for floating-point formats like EXR and PFM.

Checkerboard

The "checkerboard" texture is a simple texture that alternates between two other textures.

Type Name Default Value Description
integer dimension 2 Sets the dimension of the checkerboard texture. Legal values are 2 and 3.
spectrum/float texture tex1 1 The texture to use for even checks.
spectrum/float texture tex2 0 The texture to use for odd checks.
string aamode "closedform" Set the antialiasing mode for the checkerboard texture. Legal values are "closedform" or "none". This parameter is only legal for 2D checkerboards.

Dots

The "dots" texture generates a random collection of polka dots.

Type Name Default Value Description
spectrum/float texture inside, outside see description The textures to use for coloring the dots and the background. The defaults are 1 and 0, respectively.

Fbm and Wrinkled

"fbm" and "wrinkled" are two textures based on the Perlin noise function. They are 3D textures, so the scale of the features of the texture can be adjusted by setting accordingly the CTM when the texture is defined.

Type Name Default Value Description
integer octaves 8 The maximum number of octaves of noise to use in spectral synthesis.
float roughness 0.5 The "bumpiness" of the resulting texture.

Marble

Finally, "marble" is a simple approximation to a layered marble texture, based on using Perlin noise to create stochastic variation in the result.

Type Name Default Value Description
integer octaves 8 The maximum number of octaves of noise to use in spectral synthesis.
float roughness 0.5 The "bumpiness" of the resulting texture.
float scale 1 A scaling factor to apply to the noise function inputs.
float variation 0.2 A scaling factor to apply to the noise function output.

Participating media

Participating media can be associated with regions of space in the scene using the MakedNamedMedium and MediumInterface directives. First, MakedNamedMedium associates a user-specified name with medium scattering characteristics.

MakeNamedMedium "mymedium" "string type" "homogeneous" "rgb sigma_s" [100 100 100]

There are two representations of participating media available in pbrt. One represents spatially-uniform media, and the other represents media with varying density specified by a 3D grid of floating-point values.

Name Implementation Class
"homogeneous" HomogeneousMedium
"heterogeneous" GridDensityMedium

Both take a few common parameters. (And for the "homogeneous" medium, these are the only parameters available.)

Type Name Default Value Description
spectrum sigma_a rgb (0.0011, 0.0024, 0.014) The absorption cross section.
spectrum sigma_s rgb (2.55, 3.21, 3.77) The scattering cross section.
string preset none If specified, a named measured scattering medium; see the file src/core/media.cpp in the pbrt distribution for all of the measurements that are available.
float g 0 The phase function asymmetry parameter.
float scale 1 Scale factor applied to the absorption and scattering cross sections.

The "heterogeneous" allows specification of a sampled volume density on a regular grid. Final scattering properties at points inside the volume are computed by trilinearly interpolating the adjacent sample values and then scaling the sigma_a and sigma_s parameter values by the result.

Type Name Default Value Description
point p0, p1 (0,0,0), (1,1,1) The two corners of the bounding box that gives the maximum extent of the medium. (It may be smaller depending on the shape or shapes that the medium is enclosed in.)
integer nx,ny,nz 1 The number of voxels in the x, y, and z directions, respectively.
float[nx*ny*nz] density 0 The array of density values.

Given named media, the MediumInterface directive can be used to specify the current "interior" and "exterior" media. A vacuum—no participating media—is represented by empty string "".

MakeNamedMedium "mymedium" "homogeneous" "rgb sigma_s" [100 100 100]
MediumInterface "" "mymedium"

Before the world block, the interior medium is ignored, but the exterior medium specifies the medium that camera rays start out in.

Inside the world block, the current medium interface is maintained like other attributes; it's saved and restored inside AttributeBegin/AttributeEnd blocks, and so forth. When a light source is created, the current exterior medium is used for rays leaving the light when bidirectional light transport algorithms are used. (The user is responsible for specifying media in a way such that rays reaching lights are in the same medium as rays leaving those lights.)

Shapes can be used to determine the spatial extent of participating media in the scene. When a shape is created, the current interior medium is assumed to be the medium inside the shape (where "inside" is on the side opposite the one the surface normal is pointing), and the current exterior medium is assumed to be the medium outside the shape. As with lights, the user is responsible for defining these consistently. (For example, media's spatial extents should always be enclosed by closed shapes.)

Depending on the application, it can be useful to use a shape purely to determine the spatial extent of media, but to not want the shape to appear in the scene. In this case, if "none" is specified for the shape's material, it will be ignored in ray intersection calculations (except for allowing the current medium to be updated.)