Overview

This document is a reference to the file format used in pbrt-v3, the version of the system corresponding to the third edition of Physically Based Rendering; it serves as a comprehensive reference. The pbrt User's Guide documents how to use pbrt with more focus on how to achieve certain tasks or how to address various issues in the results it renders.

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 function from Appendix B in the Physically Based Rendering book. For example, when the WorldBegin statement appears in the input, the pbrtWorldBegin() function is called. To best understand this document, you should already be familiar with the concepts introduced in Appendix B, though we will try to re-introduce some key concepts from that appendix here.

Differences from pbrt-v2

We 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-v3. A number of changes were necessary for new functionality or changes in the system's implementation. The biggest resulting change to input files is that the Renderer, SurfaceIntegrator, and VolumeIntegrator directives have all been unified under Integrator; only a single integrator now needs to be specified.

Some functionality was removed:
  • Accelerator "grid": use "bvh" or "kdtree" instead.
  • Material "measured": the new "fourier" material should now be used for measured BRDFs. Note that it uses a different representation of BRDFs than "measured" did.
  • Material "shinymetal": use the "uber" material in place of "shinymetal".
  • VolumeRegion: use the new participating media representation: NamedMedium and MediumInterface.
  • SurfaceIntegrator: the "photonmap", "irradiancecache", "igi", "dipolesubsurface", "ambientocclusion", "useprobes", "diffuseprt" and "glossyprt" integrators have been removed.
    • Use "sppm" for the "photonmap".
    • The "path" integrator now handles subsurface scattering directly.
    • The others aren't as good as path tracing anyway. :-)
  • VolumeIntegrator"single" and emission: use the "volpath" path tracing integrator.
  • Sampler "bestcandidate": use any other sampler.
  • Renderer: use Integrator, as described above.
  • Texture "image" "float gamma": image map textures now take a "bool" value to enable or disable conversion from sRGB to linear texture values; it is true by default for 8-bit texture formats like TGA and false by default for floating-point formats like OpenEXR.

The documentation on the pbrt-v2 file format is still available.

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, up until the WorldEnd statement, which causes the image to be rendered.

LookAt 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 "path"
Film "image" "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"  "point from" [ -30 40  100 ]
   "blackbody L" [3000 1.5]

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

AttributeBegin
  Texture "checks" "spectrum" "checkerboard"
          "float uscale" [8] "float vscale" [8]
          "rgb tex1" [.1 .1 .1] "rgb tex2" [.8 .8 .8]
  Material "matte" "texture Kd" "checks"
  Translate 0 0 -1
  Shape "trianglemesh"
      "integer indices" [0 1 2 0 2 3]
      "point P" [ -20 -20 0   20 -20 0   20 20 0   -20 20 0 ]
      "float st" [ 0 0   1 0    1 1   0 1 ]
AttributeEnd

WorldEnd

When rendered with pbrt, 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, shapes, and volumetric scattering regions can be defined inside the world block (and can only be defined inside the world block). The world block ends with the WorldEnd directive; when this is encountered, the Integrator defined takes control and does the required rendering computation.

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

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.

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

Here, the "type" string gives the name of the particular shape, etc., implementation to use, and parameter-list gives the parameters to pass to the implementation. With this design, the parser doesn't need to know anything about the semantics of the parameters; it just needs to know how to parse parameter lists and how to initialize a ParamSet from them (The ParamSet class is described starting on page 1105 of the third edition of the Physically Based Rendering book).

Almost all directives in a pbrt input file have a direct correspondence with a function in the pbrt API, defined in the files core/api.h and core/api.cpp. The only input file directive that does not directly correspond to a function in the API is the Include statement, which allows other input files to be parsed. Include behaves similarly to the #include directive in C++, except that only the directory that the currently-being-processed input file is searched for matching filenames. Of course, a complete pathname or a path relative to the current directory can be specified if appropriate.

Include "geometry/car.pbrt"

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:

"type name" [ value or values ]

For example,

"float fov" [30]

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

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

specifies that "cropwindow" is a floating-point array with the given four values. Notice that values are enclosed in square brackets. Single values (such as the "30" in the "fov" example above) may be provided with or without square brackets enclosing them, though arrays of values always must be enclosed in square brackets.

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 nine basic parameter types: integer, float, point2, vector2, point3, vector3, normal3, spectrum, bool, and string. Alternatively, point, vector, normal, can be used as synonyms for their three-dimensional equivalents.

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 strings "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 a number of 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. (color is also supported as a synonym for this):

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

specifies the RGB color with red equal to 0.2 and so forth. The FromRGB() method of the Spectrum implementation being used is used to convert the given RGB colors to the current spectral representation.

Alternatively, XYZ colors can be used to specify a spectrum:

"xyz Kd" [ .4 .6 .7 ]

General sampled SPDs are specified with a series of (wavelength, value) pairs, where wavelengths are specified in nm. These SPDs are resampled to the current spectral representation with its FromSampled() method. For example,

"spectrum Kd" [ 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 through a separate file:

"spectrum Kd" "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. See the directory scenes/spds in the pbrt scenes distribution for examples.

Finally, SPDs of blackbody emitters can be specified with two floating-point values, one giving the blackbody temperature in Kelvin, and the second giving a scale factor. (Blackbody emitters are discussed in Section 12.1.1 of the book.)

"blackbody L" [ 6500 1 ] # daylight, approximately

Transformations

A series of directives modify the current transformation matrix (CTM). (See Section B.2.2 on page 1111 for more information about how the CTM is maintained during scene description.) 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 change the CTM; they are shown with the corresponding pbrt API call:

Input File Syntax API Call
Identity pbrtIdentity()
Translate x y z pbrtTranslate()
Scale x y z pbrtScale()
Rotate angle x y z pbrtRotate()
LookAt eye_x eye_y eye_z look_x look_y look_z up_x up_y up_z pbrtLookAt()
CoordinateSystem "name" pbrtCoordinateSystem()
CoordSysTransform "name" pbrtCoordSysTransform()
Transform m00 ... m33 pbrtTransform()
ConcatTransform m00 .. m33 pbrtConcatTransform()

For example, Translate takes three floating-point values, x, y, and z, and the corresponding values are passed to the pbrtTranslate() API call, which in turn modifies the CTM by setting it to the product of the CTM with the matrix representing the given translation.

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

Scene-wide rendering options

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

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:

Name Implementation Class
"environment" EnvironmentCamera
"orthographic" OrthographicCamera
"perspective" PerspectiveCamera
"realistic" RealisticCamera

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, OrthographicCamera, and EnvironmentCamera 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 support images rendered with 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 two (semi-redundant) parameters 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.
float halffov n/a For convenience to some programs that export from modeling systems, the camera's field of view can also be specified via the half-angle between the view direction and the edge of the viewing frustum. If this parameter isn't provided, then fov is used to set the field of view instead.

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.
bool simpleweighting true Indicates whether incident radiance at the film plane should just be weighted by the cosine-to-the-4th term, or whether it should also include the additional weighting terms that account for the shutter open time and the projected area of the exit pupil are included so that the image records incident energy on the film plane.

Samplers

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

Name Implementation Class
"02sequence" (or, for backwards compatibility, "lowdiscrepancy") ZeroTwoSequenceSampler
"halton" HaltonSampler
"maxmindist" MaxMinDistSampler
"random" RandomSampler
"sobol" SobolSampler
"stratified" StratifiedSampler

The HaltonSampler and SobolSampler are generally the most effective samplers for Monte Carlo integration. The RandomSampler generates particularly ineffective sampling patterns and is really only useful for comparison against more sophisticated approaches and shouldn't otherwise be used.

The ZeroTwoSequenceSampler, HaltonSampler, MaxMinDistSampler, RandomSampler, and SobolSampler all take a single parameter, "pixelsamples", which sets the number of samples to take in each pixel area. (For ZeroTwoSequenceSampler, MaxMinDistSampler, and SobolSampler, this value must be a power of two. 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, per pixel. Note that the number of samples is taken per pixel on average; depending on the actual sampling algorithm being used, individual pixel areas may have slightly more or slightly fewer.

The StratifiedSampler has three parameters that control its behavior.

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 2 The number of samples per pixel to take in the x direction.
integer ysamples 2 The 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.

Film

The Film directive specifies the characteristics of the image being generated by the renderer.

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