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 seven basic parameter types: integer, float, point, vector, normal, spectrum, bool, and string. The point, vector, and normal types all take three floating-point values to specify each value. 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 Section 5.2.2 on page 273 of the second 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-linar 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 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. See the Wikipedia article on blackbody emitters for more information and the formula used to compute the SPD from the blackbody temperature:

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

Transformations

A series of directives modify the current transformation marix (CTM). (See Section B.2.2 on page 1053 for more information about how the CTM is maintined 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:

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 vaues:

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

Cameras

The Camera directive specifies the camera used for viewing the scene. (The camera is used when pbrt is used to render an actual image. However, some of pbrt's Renderer implementations compute other quantities—for example, AggregateTest tests ray tracing acceleration structures and CreateRadianceProbes computes spherical harmonic radiance probes at a grid of locations—neither one of these uses the camera. See the section on Renderers for more discussion.)

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 three camera implementations:

A number of parameters are common to all cameras in pbrt:

The EnvironmentCamera takes no additional parameters beyond these. PerspectiveCamera and OrthoCamera support images rendered with depth of field. They both use the following two parmaeters to set the lens focus, etc.

Finally, the perspective camera has two (semi-redundant) parameters for setting the camera's field of view.

Samplers

The Sampler generates samples for the image, time, lens, and Monte Carlo integration. A number of implementations are provided; the default is "lowdiscrepancy"—the LDSampler. Note that the sampler is only used if SamplerRenderer is the Renderer being used to render the scene; other renderers have their own sample generation mechanisms internally and/or don't need samples in this manner (e.g. AggregateTest).

The HaltonSampler and StratifiedSampler are not as effective as the LDSampler, AdaptiveSampler, or BestCandidateSampler; the sample points they generate aren't as good and thus more samples will generally be required to get a similar result. The RandomSampler generates particularly ineffective sampling patterns. It is really only useful for comparison against more sophisticated approaches and shouldn't otherwise be used.

The AdaptiveSampler takes a minimum number of samples in each pixel and then performs a test to see if, according to some metric, they vary excessively. If so, it takes a higher number of samples. The underlying sample generation algorithms are based on the low-discrepancy patterns used by the LDSampler.

The "bestcandidate", "lowdiscrepancy", "halton", and "random" samplers all take a single parameter, "pixelsamples", which sets the number of samples to take in each pixel area.

The "stratified" sampler has three parameters that control its behavior.

Film

The Film directive specifies the characteristics of the image being generated by the renderer. Note that only the SamplerRenderer and the MetropolisRenderer use the film; the other renderers don't generate an image per se and thus ignore the film definition.

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:

The ImageFilm uses the suffix of the given output filename to determine the image file format to use. All builds of pbrt support PFM and TGA format images; those configured to use the OpenEXR libraries support EXR as well.

Filters

The implementation of ImageFilm uses an instance of the abstract Filter class to filter sample values to compute final pixel values. (Thus, as only the SamplerRenderer and the MetropolisRenderer use ImageFilm, the filter setting is only relevant when one of those renderers is being used.

pbrt provides a number of filter implementations, listed below. The default is "box"; while the box filter has a number of known shortcomings, it is the most effective filter when the low-discrepancy sampler is being used (recall the illustration in Figure 7.37 on page 392 of Physically Based Rendering).

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

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

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

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

Renderers

The renderer, defined with the Renderer directive, selects the rendering algorithm used to render the scene. For example:

Renderer "metropolis" "integer samplesperpixel" [4096]

pbrt sometimes has a somewhat broad uage for "render the scene" in that some of the Renderer implementations don't actually generate images.

The default renderer is "sampler", corresponding to the SamplerRenderer. The following Renderer implementations are currently available in pbrt.

The "aggregatetest" renderer is one that doesn't create an image. Instead, it traces a number of random rays using the current acceleration structure (see Accelerators for information about how the accelerators are selected) and checks the results to the result from an exhaustive intersection of each ray with all of the triangles in the scene. This renderer can thus be used to find bugs in the implementation of accelerators; see Section 4.6 on page 245 for more information.

The "createprobes" renderer computes a series of spherical harmonic radiance probes; see Section 17.3 on page 956 for more information. This renderer uses whichever surface and volume integrators are specified in the input file; see the following sections, Surface Integrators and Volume Integrators for more information.)

The "metropolis" renderer implements the Metropolis light transport algorithm; it is defined in Section 15.7 of the Physically Based Rendering book.

The "sampler" renderer uses the defined Sampler to provide samples that it in turn uses to generate camera rays and then call the SurfaceIntegrator and VolumeIntegrator to compute the radiance along those rays. This is the default renderer in the system. In general, parameters that control its operation are set indirectly via parameters to the Sampler, SurfaceIntegrator, and VolumeIntegrator.

The "surfacepoints" renderer computes a set of sample points on the surfaces of objects in the scene that have BSSRDF materials (i.e. that exhibit subsurface scattering). These sample points are distributed on the surface according to a Poisson sphere criterion so that no two of them are too close together. Because the generation of these points can be computationally complex, it's often worth doing it in a preprocess; the DipoleSubsurfaceIntegrator can then read these files of sample points and use them at rendering time.

Surface Integrators

The surface integrator implements the light transport algorithm that computes reflected radiance from surfaces in the scene. Recall that surface integrators are only used by the SamplerRenderer and CreateRadianceProbes renderer; if another renderer is specified, then the surface integrator is ignored. The default surface integrator is the DirectLightingIntegrator:

SurfaceIntegrator "directlighting" "integer maxdepth" [5]
    "string strategy" "all"

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

A greyscale ambient occlusion image is computed by the "ambientocclusion" integrator; it takes a number of samples over the hemisphere of each visible point and computes the fraction of them that are unoccluded.

The "diffuseprt" integrator implements the diffuse precomputed radiance transfer algorithm implemented in Section 17.4 of Physically Based Rendering. At each point, it projects the transfer function (Equation 17.20) into the SH basis and uses the efficient dual-product integral approach to compute the reflected light due to incident illumination. (Recall that in practice, one would generally want to precompute the projection of the transfer function and store it and then do the reflected light computation in real-time.)

The "dipolesubsurface" integrator implements the subsurface scattering rendering algorithm described in Section 16.5. It is otherwise similar to the direct lighting integrator, in that it follows specularly reflected and transmitted rays and uses standard algorithms to compute direct lighting.

There are two parameters for the "directlighting" integrator.

The "glossyprt" integrator implements the glossy precomputed radiance transfer algorithm described in Section 17.5 of Physically Based Rendering. As with the "diffuseprt" integrator, it both computes the SH representation of scattering at each point and then computes the effect of this scattering with the light in the scene. In general, one would precompute the scattering properties and then compute the scattering in a real-time renderer.

Furthermore, note that this integrator ignores the properties of the materials bound to objects in the scene but instead uses a simple parameterized material model for all scene objects. The reasons for this, and alternative approaches are discussed at the top of page 980.

The "instant global illumination" algorithm is implemented by the "igi" integrator.

The irradiance caching integrator is used when the "irradiancecache" SurfaceIntegrator is specified.

The "path" integrator takes just a single parameter.

Photon mapping is implemented by the "photonmap" integrator.

The "useprobes" integrator uses a set of radiance probes encoded in spherical harmonics, such as those computed by the CreateRadianceProbes renderer. At each point being shaded, it computes the diffuse reflectance and then uses the SH convolution formula to compute the outgoing scattered radiance due to the incident illumination in the scene.

The "whitted" integrator takes a single parameter that sets the maximum ray tree depth. In general, the "directlighting" integrator should be used in preference to the "whitted" integrator, as it uses better sampling algorithms for direct lighting from area light sources. (The "whitted" integrator is simplified in this respect for better clarity of presentation of the basic ray tracing algorithm.)

Volume Integrators

pbrt provides two volume integrators; the default is EmissionIntegrator, which only accounts for volumetric attenuation and emission. The SingleScatteringIntegrator computes the effect of single scattering and can thus render volumetric shadows, though it can be substantially more computationally intensive.

Both volume integrators take a single parameter, which specifies the distance in world space along the ray to go forward at each step. In general, smaller values will cause rendering to take longer, but will better resolve fine-scale details in the volume description.

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.

Three accelerator implementations are available in pbrt:

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.

The "grid" accelerator takes only a single parameter. While this accelerator is extremely efficient to create, it is substantially lower performance than the others at ray-shape intersection time.

Finally, 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 234 of the second 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.)

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.

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.

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

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

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

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

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

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

Here are the parameters for "paraboloid".

And these are the "sphere" parameters.

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 triange had to explicitly and privately store all of its per-vertex data.

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

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.

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:

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

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

Point

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

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.

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.