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.

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

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:

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"

"float fov" [30]

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

"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"

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

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

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

"spectrum Kd" "filename"

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

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.

Camera "perspective" "float fov" [90]

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

Integrator "path" "integer maxdepth" [5]

Accelerator "kdtree" "float emptybonus" [0.1]

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.

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

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

Shape "sphere" "float radius" [0.25]

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

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

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

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

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

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.

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.

All of the above materials take a texture that can be used to specify 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.

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.

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

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

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.

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.

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

Matte

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

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.

Mirror

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

Mixture

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

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.

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.

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.

Translucent

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

Uber

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

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:

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:

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.

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.

Mix

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

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.

Image Map

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

Checkerboard

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

Dots

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

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.

Marble

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

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.

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

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.

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