Overview

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

The scene description files used by pbrt are plain text files. The file format was designed so that it would be both easy to parse and easy for applications to generate from their own internal representations of scenes. However, pbrt supports a variety of efficient binary encodings for scene data such as PLY files for meshes and various image formats for textures; thus, the size of the text input files is often not too large.

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

Differences from pbrt-v3

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

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

$ pbrt --upgrade scene.pbrt > scene-v4.pbrt

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

Major changes to the scene description include:

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

Example of a pbrt file

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

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 "volpath"
Film "rgb" "string filename" "simple.png"
     "integer xresolution" [400] "integer yresolution" [400]

WorldBegin

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

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

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

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

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

General structure of a pbrt input file

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

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

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

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

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

identifier "type" parameter-list

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

Shape "sphere" "float radius" [5]

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

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

"float fov" 30

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

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

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

"blackbody emission" 6500

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

"spectrum reflectance" "filename"

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

Include "geometry/car.pbrt"

Include "geometry/bigcar.pbrt.gz"

Import "geometry/complex-car.pbrt"

Scene-wide rendering options

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

Camera "perspective" "float fov" [90]

ColorSpace "rec2020"

Integrator "volpath" "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.)

Material "diffuse"
AttributeBegin
   Material "conductor"
   Shape "sphere"
AttributeEnd   # back to the "diffuse" material
Shape "cone"

Attribute "shape" "float radius" 5
Shape "sphere"
Translate 10 0 0
Shape "sphere"
Translate 10 0 0
Shape "sphere" "float radius" 2  # this one has radius 2

Shape "sphere" "float radius" [0.25]

Shape "trianglemesh"  "integer indices" [0 2 1 0 3 2 ]
    "point3 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" "blackbody I" [ 5500 ]

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, bilinear patch, 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" "blackbody L" [ 6500 ] "float power" [ 100 ]
  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 "diffuse" "rgb reflectance" [ .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 a 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 appropriate parameter of the material.

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

Texture "lines-tex" "spectrum" "imagemap" "string filename" "textures/lines.exr"
Material "diffuse" "texture reflectance" "lines-tex"

Note that for each parameter (for example, "reflectance" 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", "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.)

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. The current material can be set to a preexisting named material using the NamedMaterial directive.

MakeNamedMaterial "mydiffuse"
    "string type" "diffuse" "rgb reflectance" [ 0.1 0.5 0.2 ]
Material "conductor"       # current material is "conductor"
NamedMaterial "mydiffuse"  # current material is "mydiffuse" 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 materials except for "interface" and "mix" can either take a texture that specifies a bump map or an image that specifies a normal map.

Specifying Surface Roughness

Many of the following materials are based on models of light scattering from rough surfaces modeled using microfacets; for example, a metal might be polished to be very smooth, or it might be roughened due to wear over time. For all such materials, the following parameters are used to describe the surface roughness.

CoatedConductor and CoatedDiffuse

The "coatedconductor" and "coateddiffuse" materials model scattering due to a dielectric interface layer above, respectively, a conductor base layer or a diffuse base layer. Scattering and absorption in the medium between the interface and the base layer can also be specified. The "coatedconductor" model is useful both for modeling metals with a glazing as well as metals with a tarnish layer. The "coateddiffuse" model is a good match for the surface appearance of materials like plastic and varnished wood.

Both take a number of common parameters that specify the volumetric medium between the two layers, if any, and control some of the parameters of the algorithm used to simulate scattering between the layers.

The "coateddiffuse" material takes a single additional parameter to describe reflection from the diffuse base. The roughness of the dielectric interface and its index of refraction are specified using the parameters described above (i.e., "roughness", "uroughness", "vroughness", and "remaproughness"). Therefore those parameters are not included in the following table.

The "coatedconductor" material takes the common parameters listed above as well as the additional ones listed in the table below. Although it uses the same general scheme for specifying roughness as above, there is the added challenge that both the interface and the conductor layers may have different roughnesses. Therefore, there are two sets of controls, prefaced with "interface" and "conductor". For example, the roughness of the interface layer is set via the "interface.roughness" parameter, while the conductor layer is set via "conductor.roughness".

"coatedconductor" takes a few additional parameters:

Conductor

The "conductor" material describes scattering from metals, where the index of refraction (eta) and the absorption coefficient (k) affect the conductor's appearance. Alternatively, the average reflectance of the conductor can be specified; this can be especially useful if a conductor's appearance has been described with an image texture map.

As described above the spectral distributions for eta and k for a variety of conductors are built in to pbrt. For example, silver can be specified using "metal-Ag-eta" and "metal-Ag-k". The refractiveindex.info website is also a useful resource for such data.

The "conductor" material takes the standard set of parameters for specifying surface roughness that were described above.

Dielectric

The "dielectric" material models a dielectric interface (e.g., glass). The outside of the interface is taken to be the side of the surface where the surface normal is pointing; the interior is then on the other side.

The index of refraction of the interior medium is specified using the "eta" parameter, which may be wavelength-dependent or may be the same over all wavelengths. If it does vary over wavelengths then light at different wavelengths will refract in different directions, giving rise to dispersion.

This material also takes the set of parameters for specifying surface roughness that were described above.

Diffuse

The "diffuse" material models surfaces with ideal Lambertian reflection. In addition to an optional bump or normal map, it takes a single parameter that describes the surface's reflectance:

DiffuseTransmission

"diffusetransmission" models both diffuse reflection and transmission, taking an additional parameter to specify the amount of transmission. (Note also that its default reflectance is different than that of "diffuse".)

Hair

The "hair" material models reflection and transmission from cylindrical fibers like hair and fur. It is generally only useful with the "curve" shape.

The color of the hair can be specified using a number of different parameters.

If "sigma_a" is specified, then all other parameters related to hair color are ignored, if present. Otherwise, if "reflectance" 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.

Measured

The "measured" material can be used with materials that use the representation described in Dupuy and Jakob's paper An Adaptive Parameterization for Efficient Material Acquisition and Rendering. A wide variety of such materials are available in the RGB Material Database.

Mix

The "mix" material can be used to select between two materials using a texture or to blend between them. More than two materials can be blended using "mix" materials that themselves blend between other "mix" materials. It takes the following parameters:

Unlike most other materials, a bump or normal map may not be specified with the "mix" material: bump and normal maps should be applied to the constituent materials that they blend between, however.

Subsurface

The "subsurface" material provides a convenient way to specify the scattering materials of a material that exhibits subsurface scattering, where light may exit at a different place where it enters. The scattering characteristics of these materials can be specified in one of three ways:

• Direct specification of the absorption coefficient "sigma_a" and the scattering coefficient "sigma_s". (If those values are available, then this approach is the best, though it can be unintuitive to tune these value to achieve a desired visual effect.)
• Specification of the surface's reflectance and the mean free path inside the medium. (The smaller the mean free path, the thicker the medium is.) These two values are then used to derive scattering coefficients for the medium.)
• Providing the name of measured scattering properties that are included in pbrt.

The "subsurface" material also takes the standard set of parameters for specifying surface roughness that were described earlier.

Textures

The Texture statement creates a named texture of a particular type. The only types that are supported are spectrum 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. Those that support both "float" and "spectrum"-typed variants are implemented as two separate classes.

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

Texture Mapping and Parameterization

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

2D textures use a (u,v) parameterization for evaluation. They are both float and spectrum variants of BilerpTexture, ImageTexture, the 2D variant of the CheckerboardTexture, and DotsTexture. 2D textures all take a parameter that describes the texture mapping function to use to generate (u,v) coordinates:

If the "uv" mapping is selected, additional parameters can be used to offset and scale the (u,v) values.

The "spherical" mapping is based on spherical coordinates where theta is measured with respect to the z axis in texture space and is then remapped to a v value between 0 and 1. Phi is measured with respect respect to x and y and remapped between 0 and 1 for u. The "cylindrical" mapping directly maps the z axis to v and computes a u value like the "spherical" mapping does.

For both the "spherical" and "cylindrical" mapping, the current transformation matrix when the associated texture is specified gives the rendering space from texture space transformation. It can be set as needed to orient and center the mapping functions.

Finally, the "planar" mapping projects the texture space 3D position of the lookup point to a plane specified by two basis vectors, one for the u coordinate and the other for v. It takes the following parameters:

(Note that "uscale" and "vscale" are redundant for the "planar" mapping and are therefore not provided since their effect can be had by scaling the "v1" and "v2" vectors.)

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 to the texture evaluation 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.

Bilinear Interpolation

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

Checkerboard

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

Constant

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

DirectionMix

"directionmix" takes two textures and linearly interpolates between their values using an interpolant based on the absolute value of dot product of the surface normal at the texture evaluation point with a specified vector.

Dots

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

Fbm, Wrinkled, and Windy

"fbm", "wrinkled", and "windy" are 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.

Image Map

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

Marble

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

Mix

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

Ptex

The "ptex" texture provides support for Disney's Ptex texture format. Note that pbrt has limited support for Ptex textures when rendering on the GPU: only the highest MIP level is used on each face and no filtering is performed across faces.

Scale

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

Participating Media

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

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

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 "interface" is specified for the shape's material, it will be ignored in ray intersection calculations (except for allowing the current medium to be updated.)

There are five different representations of participating media available in pbrt.

The simplest of them, "homogeneous", models uniform scattering properties within its volume of space.

The "uniformgrid" medium generalizes the "homogeneous" medium by allowing the specification of a uniformly-sampled grid of density values that are trilinearly interpolated and then used to scale the provided absorption and scattering coefficients. This medium also allows the specification of spatially-varying emission that either has a fixed spectral distribution and is scaled by the local density or is specified by a grid of blackbody emission temperatures.

The "uniformgrid" medium takes the following parameters:

The "rgbrid" medium is similar to "uniformgrid", but it allows the specification of spatially-varying emission and absorption and scattering coefficients with RGB colors. Its parameters are:

The "cloud" medium is a fully-procedural model that is based on using Perlin noise to synthesize a cloud-like density.

Finally, the "nanovdb" medium allows the use of media stored in the NanoVDB format, which can efficiently represent complex media through an adaptive hierarchy of grids. The density stored in the NanoVDB volume is used to scale the specified absorption and scattering coefficients and if the volume includes a grid of temperature values, those are mapped to temperatures that are used to specify blackbody emission spectra.